From 5dd9af79ebe049934be7973385c96402f386ebb6 Mon Sep 17 00:00:00 2001 From: neng Date: Wed, 19 Aug 2026 16:20:12 +0800 Subject: [PATCH 1/2] chore: keep npm package documentation minimal --- .gitignore | 1 + .npmignore | 1 + README.md | 16 +++--- docs/dsh-rc6-gaps.md | 41 ------------- docs/implementation-status.md | 47 --------------- docs/manual-platform-validation.md | 80 -------------------------- docs/release-access.md | 49 ---------------- docs/release.md | 92 ------------------------------ package.json | 1 - 9 files changed, 9 insertions(+), 319 deletions(-) delete mode 100644 docs/dsh-rc6-gaps.md delete mode 100644 docs/implementation-status.md delete mode 100644 docs/manual-platform-validation.md delete mode 100644 docs/release-access.md delete mode 100644 docs/release.md diff --git a/.gitignore b/.gitignore index 0d3f43d..04cc8cc 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ lib/ coverage/ dist/ *.tgz +/docs/ diff --git a/.npmignore b/.npmignore index 4bdec32..612e347 100644 --- a/.npmignore +++ b/.npmignore @@ -3,3 +3,4 @@ scripts/ src/ test/ tsconfig.json +docs/ diff --git a/README.md b/README.md index 43d0464..1b882ec 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ Lexmount cloud browser tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). This package is a lightweight DSH Bundle: it registers native model tools and invokes the Rust `browser-cli`, but it does not contain a native executable, run an MCP server, or depend on the Lexmount Node.js SDK. -> Status: preview releases are published on npm under the `next` tag. Use `next` until Windows and macOS validation is complete. +> Status: preview releases are published on npm under the `next` tag. Windows x64 and macOS Apple Silicon validation is complete; use `next` for preview installations. -> **Current platform support:** Windows x64 and macOS Apple Silicon only. Linux and macOS Intel do not currently have official downloadable `browser-cli` assets and are not supported by this pre-release. +> **Current platform support:** Windows x64 and macOS Apple Silicon only. macOS Intel is not supported by this pre-release. ## Runtime architecture @@ -16,7 +16,7 @@ DSH Web / Headless → Lexmount API / CDP / cloud browser ``` -The Bundle registers tools without accessing the network. On the first tool call it selects the current OS/CPU asset, downloads the pinned `browser-cli` release and `SHA256SUMS` from Lexmount's versioned Tencent COS path, verifies the digest, executable format, static Linux contract, and CLI version, then installs it atomically in a user cache. Later calls and restarts reuse the verified cache, so an already populated cache works offline. +The Bundle registers tools without accessing the network. On the first tool call it selects the current OS/CPU asset, downloads the pinned `browser-cli` release and `SHA256SUMS` from Lexmount's versioned Tencent COS path, verifies the digest, executable format/architecture, and CLI version, then installs it atomically in a user cache. Later calls and restarts reuse the verified cache, so an already populated cache works offline. The npm tarball contains no `browser-cli` or `browser-cli.exe` file. End users do not need Rust, Python, a browser driver, or an npm lifecycle script. @@ -27,9 +27,8 @@ The npm tarball contains no `browser-cli` or `browser-cli.exe` file. End users d | Windows x64 | `x86_64-pc-windows-msvc` | Supported | | macOS Apple Silicon | `aarch64-apple-darwin` | Supported | | macOS Intel | `x86_64-apple-darwin` | Not currently supported; asset missing | -| Linux x64 | `x86_64-unknown-linux-musl` | Not currently supported; asset missing | -`native-source.json` pins `browser-cli` v1.1.13 at commit `3af544780365309feae97d51b631070e7ca73762`. The Windows asset in this release statically links the C runtime. This pre-release intentionally uses the two assets published by that immutable release. Adding Linux or macOS Intel requires a new browser-cli version and a new npm package version with fresh validation; it will not mutate this release in place. +`native-source.json` pins `browser-cli` v1.1.13 at commit `3af544780365309fe97d51b631070e7ca73762`. The Windows asset in this release statically links the C runtime. This pre-release intentionally uses the two assets published by that immutable release. Adding macOS Intel requires a new browser-cli version and a new npm package version with fresh validation; it will not mutate this release in place. ## Install @@ -124,7 +123,6 @@ Default cache locations are: | --- | --- | | Windows | `%LOCALAPPDATA%\Lexmount\dsh-browser` | | macOS | `~/Library/Caches/Lexmount/dsh-browser` | -| Linux | `${XDG_CACHE_HOME:-~/.cache}/lexmount/dsh-browser` | Set `LEXMOUNT_BROWSER_CLI_CACHE_DIR` to choose another cache root. `LEXMOUNT_BROWSER_CLI_PATH` is an explicit administrator/developer override for a preinstalled CLI; that path is still checked for format and version, but its trust is controlled by whoever sets the environment variable. @@ -150,9 +148,9 @@ Screenshot results are persisted through the DSH image attachment service. PDF a - Model input is passed as a child-process argument array with `shell: false`; it is never concatenated into a shell command. - API keys, Authorization fields, `ws`, and Chrome DevTools WebSocket URLs are removed from returned data and diagnostics. - Tool guidance tells the model to obtain user confirmation before purchases, publication, destructive remote actions, and account/security changes. -- JavaScript evaluation and raw CDP remain model-visible to match the existing WorkBuddy plugin. +- JavaScript evaluation and raw CDP remain model-visible for advanced browser automation. -DSH RC.6 does not expose MCP-style side-effect annotations on native tools. UI presentation categories are not permission enforcement. See [DSH RC.6 integration gaps](docs/dsh-rc6-gaps.md). +DSH RC.6 does not expose MCP-style side-effect annotations on native tools. UI presentation categories are not permission enforcement. ## Known browser-cli limitations @@ -188,4 +186,4 @@ npm run native:assets npm run test:native ``` -The `browser-cli-rs` repository owns native builds, macOS signing/notarization, checksums, and COS publication. This repository verifies those immutable inputs and publishes only the lightweight npm wrapper. See [release procedure](docs/release.md), [manual platform validation](docs/manual-platform-validation.md), [release access readiness](docs/release-access.md), and [implementation status](docs/implementation-status.md). +The `browser-cli-rs` repository owns native builds, macOS signing/notarization, checksums, and COS publication. This repository verifies those immutable inputs and publishes only the lightweight npm wrapper. diff --git a/docs/dsh-rc6-gaps.md b/docs/dsh-rc6-gaps.md deleted file mode 100644 index 4833a1e..0000000 --- a/docs/dsh-rc6-gaps.md +++ /dev/null @@ -1,41 +0,0 @@ -# DSH 0.1.0-rc.6 integration gaps - -This document records host limitations discovered against the installed `@deepseek-ai/dsh@0.1.0-rc.6` implementation. They are not silently described as completed plugin features. - -## 1. Native tools have no side-effect annotation field - -The RC.6 native `ToolSchema` contains only `name`, `description`, and `parameters`. `defineTool` adds execution, output, timeout, concurrency, and presentation callbacks, but no `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, or equivalent permission metadata. - -`presentCall().kind` controls UI presentation only. It does not invoke `ctx.approval` and does not enforce a permission decision. - -Impact: - -- the plugin accurately labels calls in descriptions and UI cards; -- the WorkBuddy-equivalent model safety guidance is registered in the system prompt; -- DSH does not automatically ask for approval solely because a Lexmount tool navigates, clicks, fills, evaluates JavaScript, or sends raw CDP; -- the architecture-review statement that these calls "carry DSH side-effect metadata" is not implementable on RC.6. - -DSH does expose an explicit `ctx.approval.request()` service. Adding an unconditional request to every side-effect tool is not equivalent to metadata: the headless `never` policy rejects every request rather than auto-allowing it, which would make unattended browser use fail. Choosing a plugin-owned approval policy therefore requires a separate product decision instead of being hidden in the adapter. - -## 2. Generic binary tool-result attachments do not exist - -RC.6 `ContentBlockMap` supports text, reasoning, raster image, tool-call, and tool-result blocks. `ctx.attachments` persists raster images only. - -Impact: - -- screenshots are returned as real DSH image attachments; -- PDF and browser download bytes cannot be emitted as a generic attachment block; -- PDF/download tools retain browser-cli's host output path and return it as text/JSON; -- files inside the DSH workspace can still become clickable deliverables when the model references their paths in the final response, but that is a Web UI final-response feature rather than a tool-result attachment. - -The architecture-review requirement to map screenshots, PDFs, and downloads uniformly to DSH attachments is only partially implementable on RC.6. - -## 3. Host result policies can still transform a full snapshot - -The plugin returns the complete browser-cli snapshot without truncation or pagination. The default DSH profile separately mounts spill, result-pruning, and conversation-compaction policies. Those host policies can change what ultimately remains inline for the model or durable log. - -This is host behavior, not Node adapter truncation. Validation must distinguish the raw tool result from the post-policy model-visible result. - -## 4. Version compatibility is pre-release compatibility - -The package is implemented and tested against RC.6 services and declares peer ranges below `0.2.0`. DSH is still a release candidate; a semver-compatible RC update can change native tool or Bundle behavior. Release promotion therefore requires explicit regression against every supported DSH version rather than relying only on the declared range. diff --git a/docs/implementation-status.md b/docs/implementation-status.md deleted file mode 100644 index 9386cc3..0000000 --- a/docs/implementation-status.md +++ /dev/null @@ -1,47 +0,0 @@ -# Implementation status - -Status updated on 2026-08-18 for the `@lexmount/dsh-browser@0.1.0-rc.3` candidate. Earlier npm previews and their matching Git tags are published; stable support remains blocked by real Windows/macOS and Lexmount service validation. - -## Completed and verified - -- DSH Bundle manifest and Cordis patch implemented. -- All 31 frozen browser-cli capabilities registered as DSH native tools, including evaluate and raw CDP. -- Node adapter uses `spawn` argument arrays with `shell: false`, forwards cancellation, terminates owned children, parses the existing JSON envelope, preserves CLI error codes through DSH's `HarnessError` channel, and recursively redacts secrets and CDP control URLs. -- Package loading and tool registration do not access the network or require a native executable. -- First tool use resolves the current platform, checks an administrator-provided `LEXMOUNT_BROWSER_CLI_PATH` or a versioned user cache, then downloads from the pinned COS release when needed. -- Download installation verifies the exact `SHA256SUMS` entry, a 128 MiB size limit, executable format/architecture, static Linux ELF contract, CLI version, and cache metadata before atomically replacing the cached file. -- Concurrent first calls share one resolution; cancellation stops the download when no waiter remains; plugin disposal cancels resolution and terminates active child processes. -- Screenshot output is stored through the DSH image attachment service; temporary screenshot files are removed. RC.6 PDF/download attachment limitations are documented separately. -- `npm run check` passes 21 automated tests covering source/target pins, deferred unsupported-platform errors, checksum parsing, executable rejection paths, explicit-path resolution, protocol parsing, redaction, cancellation, forced cleanup, schema/argv mapping, 31-tool registration, and screenshot cleanup. -- `npm run package:verify` reports a 24-file npm payload and rejects any native executable path. The current unpacked wrapper is about 105 KiB. -- `npm run native:assets` resolves the official v1.1.13 tag to the pinned commit, downloads the Windows x64 and macOS ARM64 assets from COS, and verifies both SHA-256 digests successfully. The Windows PE import table has no dynamic Visual C++ runtime dependency. -- `npm audit --omit=dev` reports zero known vulnerabilities. -- The release workflow uses tag-only assembly, pins Node 24.15.0 and npm 12.0.2, creates one tarball, verifies it contains no executable, and passes the exact artifact through the npm environment approval gate without rebuilding. -- The previous bundled Linux binary and all `vendor/` package entries have been removed from the working tree. -- A newly packed lightweight tarball installs through the real DSH RC.6 `dsh plugin`/pnpm path into clean disposable Web and Headless profiles without peer warnings. Both composed configs contain exactly one `lexmount-browser` entry. -- The clean Web profile boots successfully on an OS-assigned port and returns HTTP 200. This proves unsupported Linux is deferred until tool resolution instead of breaking Bundle registration. The Headless profile reaches its native help path. Neither load path downloads a CLI. -- The public npm registry tarball is byte-for-byte identical to the release working tree tarball: SHA-256 `10edac9849e4ded35c8b15afa125680d9bd0a9ac0a0843d69ef57170cea05fa8`. -- Clean DSH RC.6 Web and Headless profiles install `@lexmount/dsh-browser@next` directly from the public npm registry, each register one Bundle entry, and the Web profile returns HTTP 200. -- GitHub `main` and the annotated `v0.1.0-rc.0` tag are pushed. CI run `32095403677` passes on Node 22.14.0 and 22.22.2. -- Tag-only release run `32095697452` passes with `publish=false`; its downloaded Action artifact is byte-for-byte identical to the public npm tarball. - -## Native source currently pinned - -- repository: `https://github.com/lexmount/browser-cli-rs.git`; -- version: `1.1.13`; -- tag commit: `3af544780365309feae97d51b631070e7ca73762`; -- COS base: `https://cli-bin-1377899528.cos.ap-nanjing.myqcloud.com/releases/browser-cli/v1.1.13`. - -The upstream v1.1.13 Action completed successfully and published macOS ARM64 and Windows x64. Its Windows build statically links the C runtime. Those are the only platforms claimed by this npm pre-release. Linux x64 and macOS Intel are deferred to a new native and npm version. - -## Not yet complete - -- Because the current host is Linux and Linux is not supported by this pre-release, the runtime download/native integration test must be completed on Windows x64 and macOS Apple Silicon. -- Real Lexmount authentication, Session, Context, browser action, screenshot, PDF/download, cancellation, cleanup, and Headless service E2E remain pending. -- Windows x64 and macOS Apple Silicon remain manual-platform work. No claim is made that they passed from this Linux host. -- npm Trusted Publisher and the GitHub `npm` environment/reviewers are not configured yet. The next unused version must prove the OIDC path. -- Repository visibility and MIT license approval remain owner decisions. -- npm accepted this package as published without a dual-use declaration. Because the frozen tool surface includes arbitrary page JavaScript and raw CDP, the owner should confirm that it remains classified as ordinary authorized browser automation; declaring it dual-use would require staged publishing and 2FA promotion instead of direct OIDC publishing. -- DSH RC.6 cannot enforce generic per-tool side-effect metadata or generic PDF/download attachments. See [DSH RC.6 integration gaps](dsh-rc6-gaps.md). - -The npm preview is structurally published and registry-installable for its stated two-platform scope. Legal approval, Trusted Publishing setup, DSH regression, and real Windows/macOS validation still block stable promotion. diff --git a/docs/manual-platform-validation.md b/docs/manual-platform-validation.md deleted file mode 100644 index 38f22e3..0000000 --- a/docs/manual-platform-validation.md +++ /dev/null @@ -1,80 +0,0 @@ -# Manual platform validation - -Run this checklist against the exact npm tarball that will be published. The current pre-release supports Windows x64 and macOS Apple Silicon only. Record OS version, CPU architecture, Node version, DSH version, npm package version, browser-cli version, npm tarball SHA-256, downloaded asset name, and downloaded asset SHA-256. - -## Package and installation - -1. Verify the tarball against the workflow `SHA256SUMS`. -2. List the tarball and confirm it contains `lib/`, `native-source.json`, Bundle metadata, docs, and license, but no `vendor/`, `browser-cli`, or `browser-cli.exe`. -3. Start from a clean disposable DSH profile and a clean `LEXMOUNT_BROWSER_CLI_CACHE_DIR`. -4. Install the tarball with `dsh plugin --profile add `. -5. Confirm installation and tool registration do not download a native asset. -6. Start the Web profile and confirm all 31 `lexmount_*` tools register without warnings. -7. Remove the Bundle and confirm its patch layer and tools disappear. - -## First download and cache - -1. Reinstall, run `lexmount_doctor`, and confirm the first tool call downloads exactly the current platform asset from the pinned v1.1.13 COS path. -2. Compare the cached executable hash with its `SHA256SUMS` entry. -3. Confirm cache metadata records v1.1.13, commit `3af544780365309feae97d51b631070e7ca73762`, platform target, asset name, and digest. -4. Disconnect outbound network access, restart DSH, and confirm the verified cache still runs. -5. Corrupt a disposable copy of the cache, restore network access, and confirm the next call refuses the corrupt file and replaces it from the pinned release. -6. Cancel a first-use download and confirm no temporary executable is selected or left as the active cache entry. - -## Authentication - -1. Run auth status and doctor while logged out. -2. Start login from the Web profile and complete the system-browser PKCE flow. -3. Confirm doctor reports ready without exposing the API key. -4. Restart DSH and confirm credentials remain usable. -5. Log out and confirm only the credential file is removed. - -## Browser lifecycle - -1. Create a temporary Session and confirm returned CDP WebSocket fields are redacted. -2. Open a public page, snapshot it, wait for a selector and text, click, and fill a non-sensitive form. -3. Run evaluate and a harmless raw CDP command. -4. Capture viewport and full-page screenshots and confirm the image renders in DSH. -5. Print a PDF to a workspace path and confirm the file is valid. -6. Enable downloads, download a harmless fixture, retrieve it, archive downloads, then delete downloads. -7. Close the Session and confirm it becomes inactive. - -## Persistent Context - -1. Create a Context with description and metadata. -2. Create a read-write Session using it, set harmless browser state, then close normally. -3. Reopen the Context and confirm state is retained. -4. Fork it and verify the new Context is independent. -5. Delete the test Contexts. -6. Exercise force-release only with a deliberately abandoned test Session. - -## Cancellation and cleanup - -1. Cancel a long wait and confirm the local browser-cli process exits. -2. Stop DSH during an active tool call and confirm no browser-cli child remains. -3. Confirm temporary screenshot directories are removed after success, failure, and cancellation. - -## Platform-specific checks - -### Windows x64 - -- Asset: `browser-cli-v1.1.13-x86_64-pc-windows-msvc.exe`. -- The PE import table contains no `VCRUNTIME` or `api-ms-win-crt` dependency. -- SmartScreen/antivirus behavior is documented for the unsigned binary. -- Cache paths containing spaces and non-ASCII characters work. -- The CLI reports v1.1.13 and cancellation leaves no `browser-cli.exe` process. - -### macOS Apple Silicon - -- Asset: `browser-cli-v1.1.13-aarch64-apple-darwin`. -- `codesign --verify --strict` succeeds. -- Gatekeeper accepts the notarized executable on a clean machine. -- The process is native arm64 and reports browser-cli v1.1.13. - -macOS Intel and Linux are not part of this pre-release validation because the pinned native release has no assets for them. - -## Headless profile - -1. Authenticate beforehand. -2. Run a non-interactive open/snapshot/screenshot/close workflow. -3. Confirm a missing credential produces an actionable interactive-login requirement instead of a false success. diff --git a/docs/release-access.md b/docs/release-access.md deleted file mode 100644 index 15e2578..0000000 --- a/docs/release-access.md +++ /dev/null @@ -1,49 +0,0 @@ -# Release access status - -Observed on 2026-08-18. These are external publication and account facts, not browser-runtime validation claims. - -## Confirmed available - -- `browser-cli` v1.1.13 is an official public tag at commit `3af544780365309feae97d51b631070e7ca73762`. -- Its GitHub release and COS path publicly expose the two assets claimed by this npm pre-release: Windows x64 and macOS ARM64. -- `npm run native:assets` downloads both files and verifies their pinned SHA-256 digests. -- npm account `lexmount` has read-write access to `@lexmount/dsh-browser`. -- `@lexmount/dsh-browser@0.1.0-rc.0` was published interactively with npm web authentication and is public. -- npm publish-time scanning completed, and the public registry tarball is byte-for-byte identical to the local release tarball. Its SHA-256 is `10edac9849e4ded35c8b15afa125680d9bd0a9ac0a0843d69ef57170cea05fa8`. -- Clean DSH RC.6 Web and Headless profiles installed `@lexmount/dsh-browser@next` from the public registry. Each composed config contains exactly one `lexmount-browser` entry, and the clean Web profile returned HTTP 200. -- `https://github.com/lexmount/dsh-browser` now contains `main` and the annotated `v0.1.0-rc.0` tag. The tag points to the exact source state used for the published tarball. -- GitHub Actions CI run `32095403677` passed on Node 22.14.0 and Node 22.22.2. -- Tag-only Action run `32095697452` passed with `publish=false`. Its downloaded `npm-package` artifact, checksum file, and native source pin are valid; the Action tarball is byte-for-byte identical to the public npm tarball. - -## Current npm tags - -The first publication was requested with `--tag next`. After npm publish-time scanning, the registry exposed both `next` and `latest` at `0.1.0-rc.0`. An authenticated attempt to remove `latest` returned HTTP 400, so both tags remain. Preview documentation explicitly installs `@next`; no stable-support claim is inferred from the registry's `latest` tag. - -## Remaining production gates - -1. Run the manual download/cache/native integration checklist on Windows x64 and macOS Apple Silicon. -2. Complete real Lexmount authentication, Session, Context, browser action, screenshot, PDF/download, cancellation, cleanup, and Headless service E2E. -3. Create the GitHub `npm` environment and configure its approval policy. -4. Configure npm Trusted Publishing only after the final workflow commit is visible on `main` and CI is green. -5. Decide whether the private GitHub repository should become public. Private repositories can publish through Trusted Publishing but do not receive public npm provenance. -6. Confirm the MIT license and `Copyright (c) 2026 Lexmount` with the owner or legal reviewer. - -## npm versions and scanning - -- The verified interactive publication used Node v22.22.2 and npm 12.0.2. -- The release workflow pins Node 24.15.0 and npm 12.0.2. npm Trusted Publishing requires npm 11.5.1 or later. -- npm now scans a publish before it becomes available for install. The release workflow waits up to 25 minutes, downloads the public registry tarball, and compares its SHA-256 with the assembled artifact before creating a GitHub Release. - -## Dual-use policy checkpoint - -The package is intended for authorized browser automation, not penetration testing or security research. It nevertheless exposes arbitrary page JavaScript and raw CDP to match the existing WorkBuddy integration. No npm dual-use declaration was added to `0.1.0-rc.0`, and npm's publication scan accepted the package. - -Before changing that classification, review npm's [Dual-Use Content Policy](https://docs.npmjs.com/policies/dual-use/). A dual-use declaration is persistent and would change the release architecture: direct Trusted Publishing is not permitted for declared dual-use packages; OIDC may only stage them, followed by a 2FA-enforced promotion. - -## Owner actions - -1. Review the final pushed workflow and confirm the ordinary browser-automation classification, MIT license, and repository visibility. -2. Create the GitHub `npm` environment with any required reviewers. -3. Configure npm Trusted Publishing for organization/user `lexmount`, repository `dsh-browser`, workflow filename `release.yml`, and environment `npm`. -4. Complete Windows x64 and macOS Apple Silicon validation against the exact public npm version. -5. Publish the next unused npm version through the tag-only Action and verify OIDC, the npm scanning wait, and the matching GitHub Release. diff --git a/docs/release.md b/docs/release.md deleted file mode 100644 index 9552b6b..0000000 --- a/docs/release.md +++ /dev/null @@ -1,92 +0,0 @@ -# Release procedure - -The npm package is a wrapper only. Native executables are released first by `lexmount/browser-cli-rs`; this repository never builds or embeds them. - -## Required release order - -1. Publish the pinned `browser-cli` version from `lexmount/browser-cli-rs`. -2. Confirm its version tag resolves to the commit in `native-source.json`. -3. Confirm the COS `SHA256SUMS` and both currently supported assets are public: - - `aarch64-apple-darwin`; - - `x86_64-pc-windows-msvc.exe`. -4. Run `npm run release:check`. It verifies the lightweight package, the GitHub tag/commit, and downloads both remote assets to verify their published SHA-256 digests. -5. Only then create and push the matching `@lexmount/dsh-browser` version tag; the tag push starts its release automatically. - -The current npm pre-release supports Windows x64 and macOS Apple Silicon only. Linux x64 and macOS Intel require a later browser-cli release and a new npm package version. - -## GitHub Action: assemble and publish the npm wrapper - -`.github/workflows/release.yml` runs automatically when an exact `v*` version tag is pushed. Merging a pull request or pushing `main` runs CI but does not publish a release: - -1. `assemble` checks that the pushed ref is exactly `v`. -2. It uses Node 24.15.0 and pins npm 12.0.2. npm Trusted Publishing requires npm 11.5.1 or later. -3. `npm ci` installs locked development dependencies. -4. `npm run release:check` runs Node tests, verifies that the npm file list contains no executable, and fully downloads both supported remote assets to compare them with the pinned checksum manifest. -5. `npm pack` produces one lightweight tarball. The workflow rejects any `package/vendor/`, `browser-cli`, or `browser-cli.exe` entry. -6. The tarball, `SHA256SUMS`, and `native-source.json` become one immutable `npm-package` artifact. -7. The workflow maps versions containing a prerelease suffix to the npm `next` tag and versions without a prerelease suffix to `latest`. -8. The `npm` environment releases that exact artifact through OIDC; no rebuild occurs. If environment reviewers are configured, this job waits for their approval. -9. npm publish-time scanning makes new versions temporarily unavailable. The workflow waits up to 25 minutes, downloads the exact public version, and compares its SHA-256 with the assembled artifact. -10. Only after the public registry comparison succeeds does a separate job attach the same tarball, checksum, and source pin to the matching GitHub Release. - -The workflow never needs Rust, Apple signing secrets, COS credentials, or native build runners. Those belong to the upstream browser-cli release. - -## Bootstrap npm publication record - -The first version could not use Trusted Publishing because npm required the package to exist before its Publisher could be configured. It was therefore published interactively on 2026-08-18 with npm web authentication: - -```bash -npm publish --access public --tag next -``` - -Recorded result: - -- package: `@lexmount/dsh-browser@0.1.0-rc.0`; -- npm SHA-1: `a76b0fc017ef56c21e2eb080b63423f2a48012a2`; -- tarball SHA-256: `10edac9849e4ded35c8b15afa125680d9bd0a9ac0a0843d69ef57170cea05fa8`; -- npm integrity: `sha512-4EsVaX2qwMXiCkGOLXobuFF948jACFZ0WYmg/yzce9Ryb/kD6p5KTE3MyNpvSNuton5Z9LqvJaA+j6i4YuXabA==`; -- npm publish-time scanning passed and a fresh public-registry download matched the local tarball byte-for-byte; -- clean DSH RC.6 Web and Headless profiles installed `@lexmount/dsh-browser@next`, and Web returned HTTP 200; -- annotated Git tag `v0.1.0-rc.0` points to commit `ef93ac2ad309447a05608c496aa4ce2e96575816`, the exact release source state. - -The publication was requested with `next`, but npm exposed both `next` and `latest` for this first package version. An authenticated removal of `latest` returned HTTP 400. Preview installation instructions therefore continue to name `@next` explicitly. - -## Configure npm Trusted Publishing - -After the package exists, configure its Trusted Publisher on npmjs.com with: - -| Field | Value | -| --- | --- | -| Provider | GitHub Actions | -| Organization | `lexmount` | -| Repository | `dsh-browser` | -| Workflow filename | `release.yml` | -| Environment | `npm` | -| Allowed action | `npm publish` | - -Create the GitHub `npm` environment with required reviewers. The publish job has `contents: read` and `id-token: write`; it uses a GitHub-hosted runner and no long-lived npm token. - -Once OIDC publishing is proven, set npm publishing access to require 2FA and disallow traditional tokens. Trusted publishing from a public source repository automatically produces npm provenance; a private repository can publish through OIDC but does not receive public provenance. - -The package is currently treated as ordinary authorized browser automation. If the owner instead classifies its arbitrary JavaScript/raw CDP capabilities as dual-use under npm policy, do not use the direct OIDC publish step above: add the persistent `contentPolicy` metadata and `DISCLOSURE`, stage through OIDC, and require a 2FA promotion. See npm's [Dual-Use Content Policy](https://docs.npmjs.com/policies/dual-use/). - -## Later pre-releases - -1. Update `package.json` and `package-lock.json` to a new unused pre-release version. -2. Update `native-source.json` and the matching constants/tests only when moving to a different reviewed browser-cli release. -3. Merge the version change through a pull request and wait for `main` CI to pass. -4. Create and push the exact `v` tag on that merged commit. -5. The tag push starts `assemble-release` automatically and selects npm `next` for the prerelease version. -6. If the `npm` environment requires review, approve the publish job after the assembly checks pass. The same bytes are published and attached to the GitHub Release. - -An npm name/version pair can never be reused, even after unpublishing. Do not rebuild or republish an existing version. - -## Stable promotion - -Create a version without a prerelease suffix only after Windows x64, macOS Apple Silicon, and real Lexmount service validation are complete; its tag-triggered release publishes to npm `latest` automatically. During preview, `next` is the documented channel even though npm also exposed `latest` for the bootstrap version. If stable product policy still requires Linux, do not create a stable version tag until a later cross-platform version is approved. To promote an already published version without rebuilding it, move `latest` explicitly: - -```bash -npm dist-tag add @lexmount/dsh-browser@ latest -``` - -Promotion changes only the dist-tag. It must not rebuild the package or native executable. diff --git a/package.json b/package.json index 3f37ba7..6608638 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,6 @@ "lib/**/*.d.ts", "cordis.patch.yml", "native-source.json", - "docs/*.md", "README.md", "LICENSE" ], From 843a908bf384b350356c93563217d2cfab0abb91 Mon Sep 17 00:00:00 2001 From: neng Date: Wed, 19 Aug 2026 16:24:32 +0800 Subject: [PATCH 2/2] docs: fix pinned browser-cli commit hash --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1b882ec..cc66292 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The npm tarball contains no `browser-cli` or `browser-cli.exe` file. End users d | macOS Apple Silicon | `aarch64-apple-darwin` | Supported | | macOS Intel | `x86_64-apple-darwin` | Not currently supported; asset missing | -`native-source.json` pins `browser-cli` v1.1.13 at commit `3af544780365309fe97d51b631070e7ca73762`. The Windows asset in this release statically links the C runtime. This pre-release intentionally uses the two assets published by that immutable release. Adding macOS Intel requires a new browser-cli version and a new npm package version with fresh validation; it will not mutate this release in place. +`native-source.json` pins `browser-cli` v1.1.13 at commit `3af544780365309feae97d51b631070e7ca73762`. The Windows asset in this release statically links the C runtime. This pre-release intentionally uses the two assets published by that immutable release. Adding macOS Intel requires a new browser-cli version and a new npm package version with fresh validation; it will not mutate this release in place. ## Install