@gjsify/cli 0.36.0 → 0.38.0

package/lib/utils/npm-otp.js

@@ -1,30 +1,22 @@
 // Shared npm 2FA / OTP handling for the auth-aware CLI commands
 // (`gjsify publish`, `gjsify trust`, `gjsify onboard`).
 //
-// npm signals "OTP required" via HTTP 401 + a `www-authenticate` header
-// containing `otp` (or, for malformed responses, a body mentioning
-// "one-time pass" / `EOTP`) — see
-// refs/npm-cli/node_modules/npm-registry-fetch/lib/check-response.js.
+// npm signals "OTP required" via HTTP 401 + a `www-authenticate` header containing
+// `otp` (or, for malformed responses, a body mentioning "one-time pass" / `EOTP`) —
+// see refs/npm-cli/node_modules/npm-registry-fetch/lib/check-response.js.
 //
-// Two pieces were previously duplicated in `publish.ts` and `trust.ts`:
-//   1. detecting the challenge (`isOtpChallenge`);
-//   2. prompting for a code, then retrying the request with it.
-//
-// They are centralised here so a single `OtpProvider` can be injected across
-// MANY operations in one run. `gjsify onboard` sweeps ~110 packages and would
-// otherwise prompt once per package; with one shared provider the user types
-// an OTP once — the cached code is tried first on every subsequent challenge,
-// and a fresh prompt only happens when npm actually rejects/expires it.
-//
-// Standalone `publish`/`trust` keep their existing single-command UX: each
-// still constructs its own provider and prompts on demand.
+// Detection and prompt-then-retry live here so ONE `OtpProvider` can be injected
+// across many operations in a single run: `gjsify onboard` sweeps every publishable
+// package and would otherwise prompt per package, whereas a shared provider tries the cached
+// code first on every subsequent challenge and only re-prompts when npm actually
+// rejects or expires it. Standalone `publish`/`trust` each construct their own
+// provider and prompt on demand.
 import { promptLine } from './prompt.js';
 import { clearCachedOtp, readCachedOtp, writeCachedOtp } from './npm-otp-cache.js';
 const DEFAULT_QUESTION = 'This operation requires a one-time password.\nEnter OTP: ';
 /**
  * True when a response is an npm OTP / 2FA challenge (401 + a `www-authenticate`
  * header naming `otp`, or a body mentioning a one-time password / `EOTP`).
- * Unifies the detection logic previously inlined in both publish.ts and trust.ts.
  */
 export async function isOtpChallenge(res) {
     if (res.status !== 401)
@@ -42,12 +34,11 @@ export async function isOtpChallenge(res) {
  * Holds ONE OTP code across a run and knows how to prompt for a fresh one.
  *
  * `current()` returns the cached code (seeded from `--otp`, the cross-invocation
- * file cache, or the last one the user typed). `refresh()` prompts for a new
- * code and caches it (in-process AND — when a `registry` is set — in the
- * short-lived file cache). A single provider instance shared across many
- * publish + trust operations is what makes `gjsify onboard` need only one OTP
- * entry for the whole sweep; the file cache extends that reuse across SEPARATE
- * `gjsify` invocations (`login → onboard → publish → trust`).
+ * file cache, or the last one typed); `refresh()` prompts for a new one and caches
+ * it in-process AND — when a `registry` is set — in the short-lived file cache. One
+ * shared instance is what makes `gjsify onboard` need a single OTP entry for a whole
+ * sweep; the file cache extends that reuse across SEPARATE invocations
+ * (`login → onboard → publish → trust`).
  */
 export class OtpProvider {
     cached;
@@ -81,9 +72,8 @@ export class OtpProvider {
         return this.cached;
     }
     /**
-     * Prompt for a fresh code, cache it (in-process + file cache), and return
-     * it (the trimmed input, or `''` when nothing was entered — the caller
-     * treats empty as "give up").
+     * Prompt for a fresh code, cache it (in-process + file cache), and return the
+     * trimmed input — `''` when nothing was entered, which callers read as "give up".
      */
     async refresh(question = DEFAULT_QUESTION) {
         const code = (await this.promptFn(question)).trim();
@@ -95,9 +85,9 @@ export class OtpProvider {
         return code;
     }
     /**
-     * Drop the cached code (in-process AND the cross-invocation file entry)
-     * after npm rejects it as invalid/consumed — so the NEXT command re-prompts
-     * instead of replaying a single-use code that the registry already burned.
+     * Drop the cached code (in-process AND the cross-invocation file entry) after npm
+     * rejects it, so the NEXT command re-prompts instead of replaying a single-use
+     * code the registry already burned.
      */
     invalidate() {
         this.cached = undefined;
@@ -106,21 +96,14 @@ export class OtpProvider {
     }
 }
 /**
- * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}.
- *
- * Flow:
- *   1. First attempt — without an OTP (or WITH the cached code when
- *      `seedFirstAttempt` is set).
- *   2. On a 2FA challenge, retry with the currently-cached code (unless step 1
- *      already sent it).
- *   3. If still challenged (cache empty/rejected/expired), prompt for a fresh
- *      code — caching it on the provider so the NEXT operation tries it first —
- *      and retry, up to `maxPrompts` times.
- *   4. Return the last response (a challenge the caller must handle) when the
- *      user declines to enter a code.
+ * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}:
+ * attempt without an OTP (or with the cached code under `seedFirstAttempt`), retry
+ * with the cached code on a challenge, then prompt for fresh codes up to
+ * `maxPrompts` times. A declined prompt returns the last challenge response for the
+ * caller to handle.
  *
- * The caller owns the actual fetch + all response interpretation; this only
- * owns the OTP dance.
+ * The caller owns the fetch and all response interpretation; this owns only the OTP
+ * dance.
  */
 export async function withOtpRetry(doFetch, provider, opts = {}) {
     const maxPrompts = opts.maxPrompts ?? 2;
@@ -130,20 +113,18 @@ export async function withOtpRetry(doFetch, provider, opts = {}) {
     let res = await doFetch(seededFirst ? cached : undefined);
     if (!(await isOtpChallenge(res)))
         return res;
-    // The seeded (`--otp`/file-cached) code was rejected/consumed — drop it so
-    // it is not replayed and the cross-invocation cache entry is cleared.
+    // The seeded code was rejected/consumed — drop it so it is not replayed and the
+    // cross-invocation cache entry is cleared.
     if (seededFirst)
         provider.invalidate();
-    // Try the cached code if we haven't already sent it.
     if (!seededFirst && provider.current() !== undefined) {
         res = await doFetch(provider.current());
         if (!(await isOtpChallenge(res)))
             return res;
-        // Cached code rejected/consumed (stale seed, or a sibling command
-        // already burned the file-cached single-use code) → invalidate.
+        // Stale seed, or a sibling command already burned the file-cached single-use
+        // code.
         provider.invalidate();
     }
-    // Cache empty, rejected, or expired → prompt for a fresh code and retry.
     for (let i = 0; i < maxPrompts; i++) {
         const fresh = await provider.refresh(question);
         if (!fresh)
@@ -151,8 +132,8 @@ export async function withOtpRetry(doFetch, provider, opts = {}) {
         res = await doFetch(fresh);
         if (!(await isOtpChallenge(res)))
             return res;
-        // The freshly-typed code was also rejected — clear it before re-prompting
-        // so a wedged sequence never leaves a burned code in the file cache.
+        // Clear a rejected fresh code before re-prompting, so a wedged sequence never
+        // leaves a burned code in the file cache.
         provider.invalidate();
     }
     return res;

package/lib/utils/onboard-probe.d.ts

@@ -4,7 +4,6 @@ import type { TrustRequester } from '../commands/trust.js';
 import { type TrustState } from './trust-registry.js';
 /** What a package needs, computed from its published + trust state. */
 export type PkgAction = 'skip' | 'trust' | 'publish-and-trust' | 'blocked';
-/** A per-package plan produced by the probe phase. */
 export interface PkgPlan {
     ws: Workspace;
     registry: string;
@@ -13,7 +12,6 @@ export interface PkgPlan {
     httpStatus: number;
     action: PkgAction;
 }
-/** Everything a probe needs beyond the requester + workspace. */
 export interface ProbeContext {
     registryOverride?: string;
     npmrc: NpmrcConfig;
@@ -29,26 +27,22 @@ export interface ProbeOptions {
     /** Injected delay (tests pass a no-op). Default: real `setTimeout`. */
     sleep?: (ms: number) => Promise<void>;
 }
-/** Small backoff before the one-shot retry of a transient 401 read. */
 export declare const PROBE_RETRY_DELAY_MS = 400;
 /** Default probe concurrency — kept SMALL so a single token never bursts npm. */
 export declare const DEFAULT_PROBE_CONCURRENCY = 4;
 /** Map a classified trust state to the action the onboard sweep should take. */
 export declare function actionForState(state: TrustState): PkgAction;
 /**
- * Read one package's published + trust state via the SHARED trust requester —
- * the exact `trustUrl` + `buildHeaders` auth + `withOtpRetry` path `gjsify
- * trust` uses. On a transient `auth-required` (401 that was not an answerable
- * OTP challenge — e.g. a parallel-burst rejection or a lapsed 2FA-skip window),
- * it retries ONCE after a short backoff.
+ * Read one package's published + trust state through the SHARED trust requester.
+ * A surviving `auth-required` means the 401 was not an answerable OTP challenge —
+ * a parallel-burst rejection or a lapsed 2FA-skip window — and both recover on a
+ * single retry after a short backoff.
  */
 export declare function probeTrustState(request: TrustRequester, ws: Workspace, ctx: ProbeContext, opts?: ProbeOptions): Promise<PkgPlan>;
 /**
- * Probe every selected workspace. The FIRST package is read SERIALLY so a
- * 2FA-gated read triggers the single shared-OTP prompt (typed once) before the
- * concurrent burst — the rest reuse the now-cached code — and so a single token
- * never faces a 127-wide parallel read. The remaining packages are read with a
- * bounded (small) concurrency cap.
+ * Probe every selected workspace. The FIRST is read SERIALLY on purpose: a
+ * 2FA-gated read triggers the shared-OTP prompt once, before the burst, so the rest
+ * reuse the cached code instead of each prompting.
  */
 export declare function probeAllTrustStates(request: TrustRequester, selected: readonly Workspace[], concurrency: number, ctx: ProbeContext, opts?: ProbeOptions): Promise<PkgPlan[]>;
 /** Map with bounded concurrency, preserving input order in the result. */

package/lib/utils/onboard-probe.js

@@ -1,23 +1,15 @@
-// Trusted-Publisher STATE-READ path for `gjsify onboard`, extracted so it can
-// be unit-tested against a mocked requester (no live npm).
+// Trusted-Publisher STATE-READ path for `gjsify onboard`, extracted so it can be
+// unit-tested against a mocked requester (no live npm).
 //
-// The bug this fixes (task #60): `gjsify onboard` read all ~127 packages'
-// trust state with a PLAIN authenticated `fetch` (no OTP handling) run in a
-// wide concurrent burst — every read came back `401 → auth-required →
-// unreadable`, so the sweep planned `0 to publish+trust, 0 to trust, 127
-// unreadable`. Meanwhile a targeted `gjsify trust <pkg> --otp <code>` READ the
-// same state fine with the SAME token, because its read runs through the shared
-// `TrustRequester` (→ `withOtpRetry`): a 401 that is an OTP challenge is
-// answered with the shared code, and non-OTP transient 401s are tolerated.
-//
-// Fix: onboard now reads through the EXACT same `TrustRequester` path as
-// `gjsify trust` (identical `trustUrl` + `buildHeaders` auth + OTP handling),
-// PLUS a one-shot retry on a transient 401, PLUS a first-serial-then-bounded
-// probe order so the ONE shared OTP is prompted at most once and npm is never
-// hit with a 127-wide parallel burst from a single token.
+// Onboard MUST read through the same `TrustRequester` as `gjsify trust`, never a
+// plain authenticated `fetch`. It once used the latter, in a wide concurrent burst:
+// every one of ~127 reads came back `401 → auth-required → unreadable` and the
+// sweep planned `0 to publish+trust, 0 to trust, 127 unreadable`, while a targeted
+// `gjsify trust <pkg> --otp <code>` read the same state fine on the SAME token —
+// because the shared requester goes through `withOtpRetry`, which answers a 401
+// that is an OTP challenge and tolerates transient non-OTP ones.
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { classifyTrustList, trustUrl } from './trust-registry.js';
-/** Small backoff before the one-shot retry of a transient 401 read. */
 export const PROBE_RETRY_DELAY_MS = 400;
 /** Default probe concurrency — kept SMALL so a single token never bursts npm. */
 export const DEFAULT_PROBE_CONCURRENCY = 4;
@@ -39,11 +31,10 @@ function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Read one package's published + trust state via the SHARED trust requester —
- * the exact `trustUrl` + `buildHeaders` auth + `withOtpRetry` path `gjsify
- * trust` uses. On a transient `auth-required` (401 that was not an answerable
- * OTP challenge — e.g. a parallel-burst rejection or a lapsed 2FA-skip window),
- * it retries ONCE after a short backoff.
+ * Read one package's published + trust state through the SHARED trust requester.
+ * A surviving `auth-required` means the 401 was not an answerable OTP challenge —
+ * a parallel-burst rejection or a lapsed 2FA-skip window — and both recover on a
+ * single retry after a short backoff.
  */
 export async function probeTrustState(request, ws, ctx, opts = {}) {
     const registry = ctx.registryOverride ?? registryFor(ws.name, ctx.npmrc) ?? DEFAULT_REGISTRY;
@@ -60,11 +51,9 @@ export async function probeTrustState(request, ws, ctx, opts = {}) {
     return { ws, registry, url, state, httpStatus: res.status, action: actionForState(state) };
 }
 /**
- * Probe every selected workspace. The FIRST package is read SERIALLY so a
- * 2FA-gated read triggers the single shared-OTP prompt (typed once) before the
- * concurrent burst — the rest reuse the now-cached code — and so a single token
- * never faces a 127-wide parallel read. The remaining packages are read with a
- * bounded (small) concurrency cap.
+ * Probe every selected workspace. The FIRST is read SERIALLY on purpose: a
+ * 2FA-gated read triggers the shared-OTP prompt once, before the burst, so the rest
+ * reuse the cached code instead of each prompting.
  */
 export async function probeAllTrustStates(request, selected, concurrency, ctx, opts = {}) {
     if (selected.length === 0)

package/lib/utils/parse-spec.d.ts

@@ -13,8 +13,8 @@ export type ParsedSpec = {
  * Local: starts with `./`, `../`, `/`, or is an existing directory path.
  * Registry: `<name>` | `<name>@<version>` | `@scope/<name>` | `@scope/<name>@<version>`
  *
- * The full spec string is preserved on the registry case so it can be passed
- * verbatim to `npm install` (which already understands dist-tags, ranges,
- * git URIs, tarball URLs, etc. — we don't re-parse those).
+ * `spec` keeps the input verbatim so the registry case can be handed straight to
+ * `npm install`, which already understands dist-tags, ranges, git URIs and tarball
+ * URLs — none of those are re-parsed here.
  */
 export declare function parseSpec(input: string): ParsedSpec;

package/lib/utils/parse-spec.js

@@ -8,9 +8,9 @@ const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
  * Local: starts with `./`, `../`, `/`, or is an existing directory path.
  * Registry: `<name>` | `<name>@<version>` | `@scope/<name>` | `@scope/<name>@<version>`
  *
- * The full spec string is preserved on the registry case so it can be passed
- * verbatim to `npm install` (which already understands dist-tags, ranges,
- * git URIs, tarball URLs, etc. — we don't re-parse those).
+ * `spec` keeps the input verbatim so the registry case can be handed straight to
+ * `npm install`, which already understands dist-tags, ranges, git URIs and tarball
+ * URLs — none of those are re-parsed here.
  */
 export function parseSpec(input) {
     if (!input)
@@ -21,8 +21,7 @@ export function parseSpec(input) {
     if (existsSync(input)) {
         return { kind: 'local', path: resolve(input) };
     }
-    // Registry spec: split off the version after the LAST `@` that isn't the
-    // leading scope separator.
+    // Split the version off the LAST `@` — `lastAt > 0` skips a leading scope `@`.
     let name = input;
     let version;
     const lastAt = input.lastIndexOf('@');

package/lib/utils/pkg-json-edit.d.ts

@@ -29,21 +29,16 @@ export declare function parseSpec(spec: string): {
     range?: string;
 };
 /**
- * Collect existing dependencies + devDependencies + optionalDependencies
- * from a project package.json into installable specs of the form
- * `name@range`. Used by `gjsify install` (no args) to seed the resolver
- * with the project's existing dependency manifest — equivalent to
- * `npm install` reading `package.json`.
+ * Existing dependencies + devDependencies + optionalDependencies as `name@range`
+ * specs — what seeds the resolver for a bare `gjsify install`, the way `npm install`
+ * reads `package.json`.
  */
 export declare function projectSpecsFromPackageJson(pkg: PackageJson): string[];
 /**
- * Add or update a dependency entry in `pkg`. If the spec didn't include
- * a range, callers fill in the installed version after resolution and
- * call this again with `installedVersion` set.
+ * Add or update a dependency entry in `pkg`. When the spec carried no range, the
+ * caller calls this a second time after resolution, with `range` derived from the
+ * installed version via {@link defaultRangeFromVersion}.
  */
 export declare function addDependencyEntry(pkg: PackageJson, name: string, range: string, kind: DependencyKind): void;
-/**
- * Default version range when the user didn't pin one: `^x.y.z` from the
- * installed version. Mirrors npm's `save-prefix` default (`^`).
- */
+/** Range used when the user pinned none — npm's `save-prefix` default (`^`). */
 export declare function defaultRangeFromVersion(version: string): string;

package/lib/utils/pkg-json-edit.js

@@ -1,14 +1,7 @@
-// Helpers for editing `package.json` during `gjsify install <pkg>`.
-//
-// Mirrors npm's `--save-{prod,dev,peer,optional}` semantics:
-//   - default → dependencies (production)
-//   - --save-dev → devDependencies
-//   - --save-peer → peerDependencies
-//   - --save-optional → optionalDependencies
-//
-// Version specifier resolution mirrors npm's default (`^x.y.z` from the
-// installed version), unless the user passed an explicit range in the spec
-// (`react@^18` → keep `^18`).
+// Helpers for editing `package.json` during `gjsify install <pkg>`, mirroring npm:
+// `--save-{dev,peer,optional}` pick the matching block and no flag means
+// `dependencies`; the saved range is `^x.y.z` off the installed version unless the
+// spec carried an explicit one (`react@^18` stays `^18`).
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 export function readPackageJson(pkgPath) {
     if (!existsSync(pkgPath))
@@ -48,11 +41,9 @@ export function parseSpec(spec) {
     return { name: spec.slice(0, at), range: spec.slice(at + 1) };
 }
 /**
- * Collect existing dependencies + devDependencies + optionalDependencies
- * from a project package.json into installable specs of the form
- * `name@range`. Used by `gjsify install` (no args) to seed the resolver
- * with the project's existing dependency manifest — equivalent to
- * `npm install` reading `package.json`.
+ * Existing dependencies + devDependencies + optionalDependencies as `name@range`
+ * specs — what seeds the resolver for a bare `gjsify install`, the way `npm install`
+ * reads `package.json`.
  */
 export function projectSpecsFromPackageJson(pkg) {
     const out = [];
@@ -61,9 +52,8 @@ export function projectSpecsFromPackageJson(pkg) {
         if (!block)
             continue;
         for (const [name, range] of Object.entries(block)) {
-            // Skip workspace: / link: / file: / portal: specifiers — those
-            // are workspace-local references handled by Phase D.3, not by
-            // the project-local install path.
+            // `workspace:`/`link:`/`file:`/`portal:` are workspace-local references
+            // resolved by the workspace install path, not this project-local one.
             if (typeof range !== 'string')
                 continue;
             if (/^(workspace|link|file|portal|git\+|https?):/.test(range))
@@ -74,9 +64,9 @@ export function projectSpecsFromPackageJson(pkg) {
     return out;
 }
 /**
- * Add or update a dependency entry in `pkg`. If the spec didn't include
- * a range, callers fill in the installed version after resolution and
- * call this again with `installedVersion` set.
+ * Add or update a dependency entry in `pkg`. When the spec carried no range, the
+ * caller calls this a second time after resolution, with `range` derived from the
+ * installed version via {@link defaultRangeFromVersion}.
  */
 export function addDependencyEntry(pkg, name, range, kind) {
     if (pkg[kind] === undefined) {
@@ -84,10 +74,7 @@ export function addDependencyEntry(pkg, name, range, kind) {
     }
     pkg[kind][name] = range;
 }
-/**
- * Default version range when the user didn't pin one: `^x.y.z` from the
- * installed version. Mirrors npm's `save-prefix` default (`^`).
- */
+/** Range used when the user pinned none — npm's `save-prefix` default (`^`). */
 export function defaultRangeFromVersion(version) {
     return `^${version}`;
 }

package/lib/utils/pkg-json.d.ts

@@ -1,30 +1,23 @@
 import type { PackageJson } from './pkg-json-edit.js';
 /**
- * Drop a leading UTF-8 BOM (`U+FEFF`, the decoded form of `EF BB BF`).
+ * Drop a leading UTF-8 BOM (`U+FEFF`).
  *
- * `JSON.parse` rejects a BOM — it is not whitespace — so a manifest carrying
- * one is "invalid JSON" to every reader here. That is not a hypothetical file
- * shape on Windows: Windows PowerShell 5.1 writes a BOM for `-Encoding utf8`,
- * which is its DEFAULT for `Out-File`/`Set-Content`, so any script that edits a
- * manifest produces one. Notepad offers "UTF-8 with BOM" too.
+ * `JSON.parse` rejects a BOM — it is not whitespace — yet Windows PowerShell 5.1
+ * writes one for `-Encoding utf8`, its DEFAULT for `Out-File`/`Set-Content`, and
+ * npm reads such a manifest without complaint. The file is valid to the
+ * ecosystem, so gjsify must not be the strict one.
  *
- * npm reads such a file without complaint (`npm pkg get name` on a BOM'd
- * manifest returns the name), so the file is valid as far as the ecosystem is
- * concerned and gjsify was the strict one. Stripping matches npm, VS Code and
- * `parse-json`'s own guidance; nothing downstream wants the character.
- *
- * Only a LEADING BOM: `U+FEFF` elsewhere is a zero-width no-break space inside
- * a string value, and removing it would corrupt the data.
+ * Only a LEADING BOM: `U+FEFF` elsewhere is a zero-width no-break space inside a
+ * string value, and stripping it would corrupt the data.
  */
 export declare function stripBom(text: string): string;
 /**
  * Read + parse a `package.json` at `pkgPath`. Permissive: any error (missing
  * file, unreadable, invalid JSON) yields `null`.
  *
- * The BOM strip matters MORE here than in a throwing reader: this one reports
- * an unparseable manifest as `null`, which every caller reads as "no
- * package.json". On Windows a BOM therefore did not produce an error — it made
- * a package look like it had no manifest at all, so `gjsify check` found no
- * `check` script, discovery skipped the package, and nothing said why.
+ * The BOM strip matters more here than in a throwing reader, because callers
+ * read `null` as "no package.json": on Windows a BOM produced no error at all,
+ * it made the package look manifest-less, so `gjsify check` found no `check`
+ * script, discovery skipped the package, and nothing said why.
  */
 export declare function readPackageJson(pkgPath: string): PackageJson | null;

package/lib/utils/pkg-json.js

@@ -1,31 +1,23 @@
-// Single permissive reader for `package.json` files, shared by the CLI's
-// workspace- and dependency-discovery paths (`gjsify run`/`workspace`/`foreach`/
-// `check`, native-prebuild scanning). Returns `null` when the file is missing
-// OR unparseable — discovery must degrade gracefully on a stray or corrupt
-// manifest rather than crash the whole command.
+// Permissive `package.json` reader for the CLI's workspace- and
+// dependency-discovery paths: `null` when the file is missing OR unparseable, so
+// discovery degrades gracefully on a stray or corrupt manifest instead of
+// crashing the whole command.
 //
-// The install-save path keeps its own STRICTER reader in `pkg-json-edit.ts`
-// (`readPackageJson` there): it returns `null` only when the file is absent but
-// THROWS on invalid JSON, so a corrupt manifest is never silently overwritten
-// during `gjsify install <pkg>`. That contract is intentional and load-bearing
-// — do not fold it into this one.
+// The install-save path deliberately keeps a STRICTER reader in
+// `pkg-json-edit.ts` — `null` only when absent, THROWS on invalid JSON — so
+// `gjsify install <pkg>` never silently overwrites a corrupt manifest. Do not
+// fold the two together.
 import { readFileSync } from 'node:fs';
 /**
- * Drop a leading UTF-8 BOM (`U+FEFF`, the decoded form of `EF BB BF`).
+ * Drop a leading UTF-8 BOM (`U+FEFF`).
  *
- * `JSON.parse` rejects a BOM — it is not whitespace — so a manifest carrying
- * one is "invalid JSON" to every reader here. That is not a hypothetical file
- * shape on Windows: Windows PowerShell 5.1 writes a BOM for `-Encoding utf8`,
- * which is its DEFAULT for `Out-File`/`Set-Content`, so any script that edits a
- * manifest produces one. Notepad offers "UTF-8 with BOM" too.
+ * `JSON.parse` rejects a BOM — it is not whitespace — yet Windows PowerShell 5.1
+ * writes one for `-Encoding utf8`, its DEFAULT for `Out-File`/`Set-Content`, and
+ * npm reads such a manifest without complaint. The file is valid to the
+ * ecosystem, so gjsify must not be the strict one.
  *
- * npm reads such a file without complaint (`npm pkg get name` on a BOM'd
- * manifest returns the name), so the file is valid as far as the ecosystem is
- * concerned and gjsify was the strict one. Stripping matches npm, VS Code and
- * `parse-json`'s own guidance; nothing downstream wants the character.
- *
- * Only a LEADING BOM: `U+FEFF` elsewhere is a zero-width no-break space inside
- * a string value, and removing it would corrupt the data.
+ * Only a LEADING BOM: `U+FEFF` elsewhere is a zero-width no-break space inside a
+ * string value, and stripping it would corrupt the data.
  */
 export function stripBom(text) {
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
@@ -34,11 +26,10 @@ export function stripBom(text) {
  * Read + parse a `package.json` at `pkgPath`. Permissive: any error (missing
  * file, unreadable, invalid JSON) yields `null`.
  *
- * The BOM strip matters MORE here than in a throwing reader: this one reports
- * an unparseable manifest as `null`, which every caller reads as "no
- * package.json". On Windows a BOM therefore did not produce an error — it made
- * a package look like it had no manifest at all, so `gjsify check` found no
- * `check` script, discovery skipped the package, and nothing said why.
+ * The BOM strip matters more here than in a throwing reader, because callers
+ * read `null` as "no package.json": on Windows a BOM produced no error at all,
+ * it made the package look manifest-less, so `gjsify check` found no `check`
+ * script, discovery skipped the package, and nothing said why.
  */
 export function readPackageJson(pkgPath) {
     try {

package/lib/utils/prefixed-output.d.ts

@@ -1,7 +1,6 @@
 /**
- * Prefix every line of `src` with `prefix` and route it to `sink`. When
- * `buffered` is false (tty), lines are written live. When true (non-tty /
- * CI pipe), they are accumulated and emitted only by the returned `flush()`
- * — call it once the child has closed.
+ * Prefix every line of `src` with `prefix` and route it to `sink`. `buffered`
+ * withholds everything until the returned `flush()` runs — call that only once
+ * the child has closed.
  */
 export declare function prefixLines(src: NodeJS.ReadableStream, sink: NodeJS.WritableStream, prefix: string, buffered: boolean): () => void;

package/lib/utils/prefixed-output.js

@@ -1,25 +1,19 @@
 // Shared line-prefixed child-output forwarding for the parallel runners
-// (`gjsify foreach`, `gjsify check`).
+// (`gjsify foreach`, `gjsify check`) — one home for it, because the second,
+// unbuffered copy kept the hang below alive after the first was fixed.
 //
-// Under GJS, `process.stdout.write` is a BLOCKING `Gio.write_all`. Writing
-// each prefixed line LIVE during a PARALLEL run into a backpressuring pipe
-// (a CI log collector that drains slowly) stalls the single GLib main loop
-// on a full pipe → every parallel child's pipe backs up → their reads stall
-// → the whole run HANGS. (A tty or file sink never backpressures, which is
-// why this only ever bites in CI.) On a NON-tty sink we therefore BUFFER
-// each child's prefixed output and flush it as ONE write when that child
-// closes: the child is already done by then, so its own read can't stall,
-// and concurrent flushes serialize into brief loop stalls instead of a
-// deadlock. On a tty (interactive) lines are written live for responsive
-// output.
-//
-// This helper is the single home for that logic — `foreach` shipped the fix
-// first; `check` had an unbuffered copy that kept the hang class alive.
+// Under GJS `process.stdout.write` is a BLOCKING `Gio.write_all`. Writing lines
+// live during a PARALLEL run into a backpressuring sink (a slow-draining CI log
+// collector) stalls the single GLib main loop on a full pipe → every child's pipe
+// backs up → their reads stall → the run HANGS. A tty or file sink never
+// backpressures, which is why this only bites in CI. So on a NON-tty sink each
+// child's output is buffered and flushed as ONE write after it closes: the child
+// can no longer stall, and concurrent flushes serialize into brief loop stalls
+// instead of a deadlock. A tty gets live lines, for responsiveness.
 /**
- * Prefix every line of `src` with `prefix` and route it to `sink`. When
- * `buffered` is false (tty), lines are written live. When true (non-tty /
- * CI pipe), they are accumulated and emitted only by the returned `flush()`
- * — call it once the child has closed.
+ * Prefix every line of `src` with `prefix` and route it to `sink`. `buffered`
+ * withholds everything until the returned `flush()` runs — call that only once
+ * the child has closed.
  */
 export function prefixLines(src, sink, prefix, buffered) {
     let buf = '';

package/lib/utils/prompt.d.ts

@@ -15,10 +15,9 @@ export interface KeyOutcome {
     interrupt: boolean;
 }
 /**
- * Pure key handler for the raw-mode line editor — the single source of truth
- * for how a keystroke updates the buffer + echo. Kept pure (no I/O) so it is
- * unit-testable: this is what makes Enter (`\r` OR `\n`) reliably submit, masks
- * passwords, and treats Ctrl-C as an interrupt rather than text.
+ * Pure key handler for the raw-mode line editor — the single source of truth for how a keystroke
+ * updates the buffer + echo. Pure (no I/O) so the rules are unit-testable: Enter is `\r` OR `\n`,
+ * passwords mask, and Ctrl-C is an interrupt rather than text.
  */
 export declare function applyKey(buf: string, ch: string, mask: boolean): KeyOutcome;
 /** Print a question and read one visible line. */