qwen-code/scripts/installation
易良 010941d202
fix(standalone): pin @lydell/node-pty-linux-arm64 and fail release on missing prebuilds (#12649)
* fix(standalone): pin @lydell/node-pty-linux-arm64 and make missing prebuilds fatal at release

The wrapper publishes a linux-arm64 prebuild at the same 1.2.0-beta.10 pin,
but the root and core manifests never declared it, so the linux-arm64
standalone archive and the linux-arm64 Desktop runtime both degraded to
"PTY not available" while every other target shipped a working web
terminal.

With the pin in place every shipped target resolves a prebuild package, so
the release archive build can stop degrading silently: release.yml now
exports QWEN_STANDALONE_REQUIRE_NODE_PTY_PREBUILD=1 next to the existing
audio-capture gate, turning a missing prebuild into a hard failure instead
of another #11872.

Fixes #11872

* fix(standalone): update pnpm lockfile for the linux-arm64 node-pty pin

The two package.json manifests gained @lydell/node-pty-linux-arm64 but
pnpm-lock.yaml was not regenerated, so every CI job failed at the
frozen-lockfile install with ERR_PNPM_OUTDATED_LOCKFILE.

* docs(standalone): align the linux-arm64 PTY guide and tripwire with the pin

Pinning @lydell/node-pty-linux-arm64 makes linux-arm64 a supported PTY target,
but INSTALLATION_GUIDE.md still told users that archive ships without PTY and
reports "PTY not available". CI could not catch the drift because
install-script.test.js pinned that exact sentence as its tripwire, so the guide
and the assertion have to move together.

List all five shipped targets in the guide, retarget the tripwire at the new
sentence, and refresh the matching stale comment in desktop-shell's
test-release.js degrade fixture - that arm now only fires for a target the map
does not know.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* fix(standalone): complete the node-pty linux-arm64 pin in esbuild externals

`create-standalone-package.js` documents that "esbuild.config.js keeps every
node-pty specifier external" so the bundled CLI resolves the platform prebuild
from `lib/node_modules` at runtime. The external list carried five of the six
pinned platform packages and omitted `@lydell/node-pty-linux-arm64` — the exact
platform this PR pins. Nothing imports that specifier statically today, so the
bundle is unaffected; the gap is that the invariant the archive's PTY support
rests on was one entry short of complete.

Probe (esbuild, `--platform=node --format=esm`, entry importing both
specifiers):

- without the entry: `Could not resolve "@lydell/node-pty-linux-arm64"`
- with the entry: builds clean and emits the import left external, matching
  the other five platforms

Also corrects two comments this PR rewrote in the previous round. Both claimed
the desktop degrade arm "fires only for a target the map does not know (a
future platform)". That trigger is unreachable: `desktopTarget()` throws
`Unsupported desktop target` for anything outside its five-entry allowlist and
`NODE_PTY_PREBUILD_PACKAGE` maps exactly those five, so `prebuildPackage` is
always a real name. Verified by running the script:

    $ QWEN_DESKTOP_SKIP_BUILD=1 QWEN_DESKTOP_TARGET=freebsd-x64 \
        node packages/desktop-shell/scripts/prepare-runtime.js
    Error: Unsupported desktop target: freebsd-x64
        at desktopTarget (prepare-runtime.js:351:11)

The reachable trigger is the one the warn string already names and the one
`test-release.js` reproduces four lines below its own comment: a known target
whose prebuild package is unpinned in the source root manifest.

Comment-only apart from the single external entry. prettier --check and
eslint --max-warnings 0 clean on all three files; node --check passes.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* test(standalone): pin the node-pty release gate and its target map

Closes out three review findings on the node-pty pin. Test- and
comment-only apart from one new export; no production behavior changes.

R1-1 prepare-runtime.js: the nodePtyPackageSpecs() docstring still claimed
its null return "is how an unsupported target degrades". desktopTarget()
throws for anything outside its five-entry allowlist, and
test-release.js:testRuntimeNodePtyTargetMapping() asserts
NODE_PTY_PREBUILD_PACKAGE's keys equal exactly that allowlist, so an
unknown target can never reach it. A null here is a dropped pin. Verified
by re-running that tripwire's extraction against the edited file: both
literals still match and keys == allowlist == the same five targets.

R1-2 create-standalone-package.js: export TARGET_PREBUILD_DIR and assert
every release target maps to a package the manifests actually pin. The
guide sentence this PR adds states that invariant while release.yml:707
makes violating it abort the whole archive step, yet the map had zero test
references. The expectation is derived from readNodePtyPackageSpecs() so
the version list stays single-sourced, and is one-directional because
@lydell/node-pty-win32-arm64 is pinned while no target maps to it.

R1-3 install-script.test.js: the release.yml assertion matched only the
variable name, which also appears in the packager's usage text, so nothing
connected producer to consumer and no test executed the fail() branch at
create-standalone-package.js:578. Tightened to the full wiring line and
added the behavioral twin of the audio-capture pair: gate on with the
addon removed must throw, gate off must still build a PTY-less archive.
packageFakeStandalone() gained an env option for this; spreading
process.env leaves its 15 existing callers unchanged.

Mutation-checked, each mutant applied alone then restored and md5
verified: win-x64 mapped to an unpinned name, gate reader renamed to '2',
gate polarity flipped to !==, and release.yml no longer evaluating to '1'
are each caught by a new or tightened assertion. The polarity flip was
previously undetectable on the PR lane, where the linux-x64 prebuild is
present so the gate is never reached.

Focused: install-script.test.js 130 passed / 11 skipped (141).
prettier --check and eslint --max-warnings 0 clean on all three files.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmufv3et42h

* docs(standalone): state the real node-pty degrade conditions in comments

prepare-runtime.js said the degrade arm fires only "where the repo pins
nothing", but nodePtyPackageSpecs returns null at the first unpinned name of
the pair, so it also fires when the wrapper pin is the one that went missing
while the warning names the prebuild package. Say "either name in the pair"
and note which package the warning names.

create-standalone-package.js justified the non-fatal default with "a developer
archive stays usable on an unmapped future target", which cannot happen:
main() calls copyNativeAddon first and it reads the same TARGET_PREBUILD_DIR
in an unconditional path.join(), so an unmapped target dies with a TypeError
in the audio step before copyNodePtyAddon runs. Replace the rationale with the
case that does reach the warn arm (a target whose prebuild the host install
does not have).

Comment-only; no behaviour change.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmug1iw422v

* test(standalone): make the node-pty gate assertions discriminate

Pin the `Required ` prefix on the fatal-gate regex. copyNodePtyAddon builds
one message and emits it on both paths, so the prefix-less regex was also
satisfied by the degrade warning folded into the child's stderr — the suite
would have reported the gate as covered after the prefix was dropped from
fail(). The sibling clipboard gate assertion already spells the prefix.

Assert QWEN_STANDALONE_REQUIRE_NODE_PTY_PREBUILD structurally on the `Build
Standalone Archives` step env instead of as a whole-file substring, so
commenting the line out or moving it into a neighbouring step's env goes red.
build-standalone-release.js spawns the packager with no env override, so that
step's env is the only route to the gate. The comment defending the substring
pin named a collision with create-standalone-package.js's usage text, which
cannot occur: the searched string is release.yml alone.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmug1iw422v

* test(standalone): cover the node-pty target map and the win-x64 dir name

Two coverage gaps left by the previous round of gate tests:

- The map test looped over TARGET_PREBUILD_DIR itself, so a release target
  with no map entry was never visited, deleting a whole entry merely removed
  an iteration, and an emptied map passed vacuously. Drive the loop from
  TARGETS and assert the lookup before the pin. Still one-directional:
  @lydell/node-pty-win32-arm64 is pinned while no target maps to it.

- Both gate tests reached the packager through packageFakeStandalone, which
  hardcoded --target linux-x64, the one dialect where the prebuild dir name
  equals the target name. Add a win-x64 arm so the 'win-x64' -> 'win32-x64'
  translation in copyNodePtyAddon is covered on every lane rather than only
  on test_windows. Parameterise the staged-modules fixture and the packaging
  helper to make that reachable without a Windows host.

Test-only change; no production code is modified.

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmug5t7mp33

---------

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-09-25 04:38:07 +00:00
..
install-opentui-preview.ps1 feat(release): add gated bun/OpenTUI preview flavor to standalone releases (#10814) 2026-09-02 12:01:56 +00:00
install-opentui-preview.sh feat(release): add gated bun/OpenTUI preview flavor to standalone releases (#10814) 2026-09-02 12:01:56 +00:00
install-qwen-standalone.bat
install-qwen-standalone.ps1
install-qwen-standalone.sh
install-qwen-with-source.bat
install-qwen-with-source.sh
INSTALLATION_GUIDE.md fix(standalone): pin @lydell/node-pty-linux-arm64 and fail release on missing prebuilds (#12649) 2026-09-25 04:38:07 +00:00
uninstall-qwen-standalone.ps1
uninstall-qwen-standalone.sh