Skip to content

Latest commit

 

History

History
46 lines (27 loc) · 10.7 KB

README.md

File metadata and controls

46 lines (27 loc) · 10.7 KB

Node for full a-Shell

This command embeds upstream Node 26.12.1 and its matching npm 11.20.0 in the full a-Shell target. Only the full a-Shell target embeds the framework; mini keeps its existing command dictionary and discovery markers. V8 stays alive for the app process; each invocation gets a fresh Environment, isolate, CLI options and event loop. Scripts return their exit status to the shell. Concurrent Node invocations and worker_threads use separate environments.

Build

Use Apple Silicon, Xcode with the arm64 iPhoneOS and Simulator SDKs, and Python 3.10 to 3.14 on PATH (Node 26's configure rejects 3.9 and 3.15; the script checks this first). Only the sdk and package stages touch ios_system; node and device build Node alone and never read it, so ios_system cannot be the cause of a Node archive build failing.

The Node port needs two changes in the ios_system binary that stock releases lack: caller-owned stream protection (ashell_register_owned_streams) and PATH lookup from the command environment. ios-system-streams.patch and command-path.patch add them to ios_system revision fb7a9057874290bff2765f82b4ba3ba1d76dadb3, the revision they were written and tested against. Set IOS_SYSTEM_SOURCE to that source directory; sdk copies it, never modifies it, applies both patches with zero fuzz and builds only the ios_system target. Any other revision works only if both patches still apply; if your ios_system is modified and they do not, sdk stops with the failing patch and you either merge the two patches into your tree or build from the pinned revision. package refuses an ios_system that lacks the ownership API. IOS_SYSTEM_XCFRAMEWORK must point to the app's own writable framework copy.

export IOS_SYSTEM_SOURCE=/path/to/ios_system
export IOS_SYSTEM_XCFRAMEWORK=/path/to/ios_system.xcframework
./node/build.sh sdk
./node/build.sh node
./node/build.sh device
./node/build.sh package

NODE_IOS_CACHE defaults to $HOME/.cache/a-shell-node/v26.12.1. The Node source revision and archive checksum are pinned in build.sh. Node and device builds share a source directory and must run sequentially; each saves stripped archives. All stages accept --dry-run. Compilation uses four jobs (NODE_IOS_JOBS overrides) and suppresses Release debug symbols. Configure, make and Xcode output goes to logs in the cache; a failing step prints the last 30 lines and the log path, and later stages refuse to run without their archives. The shared Node tree and the ios_system copy carry a stamp of the patch set and input they were patched from. A matching stamp is reported as already patched; a missing or different one (older patches, an interrupted run) discards the tree, including its build output, and extracts and patches it again from the pinned archive. Patches are never skipped. Package writes xcfs/node.xcframework (the native library and its license) and, next to it, the JavaScript the app bundles: Resources/npm (npm with its dependency tree) and Resources/node-fetch (a locked node-fetch 3.3.2 fallback). Both folders are generated and git-ignored; the project copies them to $APPDIR/npm and $APPDIR/node-fetch. They stay out of the framework because the App Store treats every .js and .py file inside a framework as unsigned code and rejects the upload. It does not build, install or sign the app. No binary is checked in; the app project embeds xcfs/node.xcframework directly, so it is not part of xcfs/Package.swift. Prepare a-Shell's usual dependencies and rerun ./node/build.sh sdk before building the app: dependency preparation may replace ios_system with the stock release. The SDK rerun reuses its compiled slices and restores the patched framework.

ios-system-streams.patch protects caller-owned FILE streams until detached command cleanup finishes and waits for thread completion with a condition variable. command-path.patch makes executable lookup use the command environment's PATH. These changes must accompany the ios_system binary; packaging checks the ownership API before linking. The Node patches adapt upstream iOS configuration, macOS cross-build generators, embedding options, environment and diagnostics, libuv child dispatch and npm script/bin handling. The archive stages compile the core and libuv changes with stock GYP definitions; packaging derives the adapter's V8 ABI definitions from the generated build. npm's bundled npmrc defaults its cache to the writable ${HOME}/Library/Caches/npm; normal CLI/user overrides still apply. No local host adapter or separate application is required.

Behavior and limits

Supported CLI options include -e, -p, --import, --require/-r, --input-type=module, --input-type=commonjs, --no-warnings, -- and standalone --version/-v. Other process-wide CLI switches return 9. A bare invocation starts the REPL. The terminal routes Ctrl-C to the active Node session; scripts without a SIGINT listener return 130. Ctrl-D closes REPL input.

Command stdin/stdout/stderr use owned duplicate descriptors without replacing app fd 0/1/2. Raw descriptor APIs still address the app's descriptors. Each Environment clones Node's stock environment map and receives the ios_system command's environment before bootstrap. process.env writes stay in that map; Workers copy it by default. The host's cwd, PID and descriptor table remain shared. Node's non-owning Environment flags prohibit process.chdir, changing the umask and the native process-title setter; other host commands can still change cwd. Commands run on threads in the app. Native addons are disabled. V8 runs jitless with small ICU; WebAssembly and built-in Undici fetch/WebSocket are unavailable. For HTTPS use node --import "$APPDIR/node-fetch/fetch-preload.mjs" script.js; certificate verification stays enabled.

child_process dispatches a-Shell commands through ios_system. It does not fork OS processes. Only one child command runs at a time; another returns EBUSY. Detached children, IPC/fork, arbitrary executables and child signal delivery are unsupported. npm/npx run $APPDIR/npm/bin/npm-cli.js and npx-cli.js, the matching bundled npm tree, so no path setting is needed. NODE_PATH defaults to ~/Library/node_modules, which require() searches after the usual node_modules directories walked up from the script; modules that npm install puts there from ~/Library resolve from any directory. Each command reads NODE_PATH from its own environment, so setenv NODE_PATH ~/Library/node_modules:/some/other/dir adds locations (a colon-separated list, as in stock Node). ES import ignores NODE_PATH, as in stock Node; pure-JavaScript packages and their bins are supported. Native compiler/node-gyp install scripts fail with ENOSYS. This PR does not add another package manager or registry service. The port has physical-iPhone qualification in a-Shell mini, described below; this PR embeds Node only in full a-Shell. Extension execution and App Store acceptance remain unverified. The plain build has no WebAssembly, so Node's WebAssembly-backed TypeScript path is unavailable; DrumBrake is outside this draft.

Verification

Verified on 2026-10-15 in full a-Shell 2.2.2 (585), arm64 iOS 27 Simulator: the CLI acceptance scripts in this directory and ten child-process cases passed with status 0 and empty runner stderr. Five sequential invocations shared one app process. Node 26.12.1, npm 11.20.0, Node-to-Node pipes, Workers, CommonJS/ESM and HTTPS passed. Real terminal UI Ctrl-C stopped a synchronous loop with status 130; the next Node invocation returned 42 with empty stderr. App RSS after the suite was 400,703,488 bytes (382.1 MiB), measured for the whole app.

The matching Release Simulator bundle grew from 522,078,682 to 589,274,878 apparent bytes: +67,196,196 bytes (64.1 MiB), including npm, fetch dependencies, licenses and the SDK changes. The Node framework was 66,422,159 bytes, with a 41,786,352-byte native library. The local full-target build omits unavailable optional frameworks equally in both measurements. These are uncompressed file sizes, not an App Store download estimate. Both arm64 native slices build for iOS 16.

The same Node port was separately tested on a physical iPhone in a-Shell mini 2.2.2 (585). Its corrected npm build passed 26 base, 16 Worker, ten child-process and 25 npm checks, plus overlapping Node commands. Pure-JavaScript package install/require, scripts, npx and uninstall passed. UI interruption returned 130 for synchronous and asynchronous scripts, a SIGINT handler returned 23, and the REPL exited successfully. Each left the next command working. Simple-eval whole-app RSS on that device was 167,936,000 bytes (160.2 MiB). The mini fork has other host changes; these results qualify the Node port, not this PR's full a-Shell device integration. The full app has not been run on a physical device. Extension execution and App Store acceptance remain unverified.

The included acceptance.sh runs through real Dash/ios_system: source it from a disposable Documents directory and require FAILURES: 0, status 0 and empty runner stderr. child-process-test.cjs exercises command dispatch and pipe/status handling. interactive.sh covers interruption and REPL through the app UI; startup-profile execution cannot prove Ctrl-C routing because it does not set the scene's current command.

tests/interrupt.sh <simulator-uuid> <full-a-Shell.app> <output-directory> checks the app's command frameworks on a booted arm64 Simulator. Use the app in its Xcode build-products directory so the ios_system headers are available, and a new output directory for each run. The runner completes a warmup invocation, starts a local HTTP server, waits for its listen callback and calls ios_kill from the terminal session. Each of Node, npm and npx must return 130, or 23 for an explicit JavaScript SIGINT handler, then run another Node command that reuses the server's port. npx runs the offline fixture through a shim generated by the bundled npm; npm runs it as a package script. Require six PASS lines; individual logs remain in the output directory.

Existing package-bin shims retain their old exec command until regenerated. Run npm rebuild --offline --ignore-scripts in the package directory to relink its bins without running lifecycle scripts.

Check terminal input routing with interactive.sh warm-server, npm, npx, handler and repl in a disposable Documents directory. For npm/npx, copy package.json and node_modules from the runner's output beside interactive.sh. Send Ctrl-C through the app's Control button, then require the mode's .status to contain 130 (23 for handler, 0 for repl), .next to contain 42 and .done to contain complete. The npm/npx modes use the same offline server on port 8099. In the REPL, the first Ctrl-C shows the exit hint and the second exits.