@gjsify/cli 0.35.0 → 0.37.0

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. */

package/lib/utils/prompt.js

@@ -1,20 +1,17 @@
 // Interactive prompts for `gjsify login` / `gjsify trust`.
 //
-// On a TTY every prompt runs inside a single RAW-mode session (`runRawSession`)
-// that reads key-by-key with manual echo and a guaranteed cooked-mode restore
-// (try/finally). This deliberately does NOT rely on the terminal's cooked
-// line-discipline nor on the shared `process.stdin` resume/pause cycle:
-//   - The old visible prompt read a cooked line via `process.stdin` 'data'
-//     events. With the line discipline in an unexpected state (e.g. ICRNL off
-//     after a prior raw prompt) Enter arrived as a bare `\r` that never
-//     terminated the cooked line — the prompt hung showing `name^M`. The
-//     resume/pause churn on the shared stdin singleton between two sequential
-//     prompts also intermittently dropped the line or resolved it empty.
-//   - Reading raw + handling `\r`/`\n` ourselves removes both failure modes.
+// On a TTY every prompt runs inside a single RAW-mode session (`runRawSession`) reading
+// key-by-key with manual echo and a guaranteed cooked-mode restore. It deliberately relies on
+// neither the terminal's cooked line-discipline nor the shared `process.stdin` resume/pause
+// cycle: a cooked read with the line discipline in an unexpected state (ICRNL off after a prior
+// raw prompt) saw Enter arrive as a bare `\r` that never terminated the line, hanging the prompt
+// showing `name^M`, and the resume/pause churn on the shared stdin singleton between sequential
+// prompts intermittently dropped the line or resolved it empty. Handling `\r`/`\n` here removes
+// both failure modes.
 //
-// Raw mode (via @gjsify/process → terminal-native) now also clears ISIG, so
-// Ctrl-C is delivered as a `\x03` keystroke we handle (restore + exit) instead
-// of a SIGINT that would kill the process leaving the terminal in raw mode.
+// Raw mode (via @gjsify/process → terminal-native) also clears ISIG, so Ctrl-C arrives as a
+// `\x03` keystroke handled below (restore + exit) rather than a SIGINT that would kill the
+// process leaving the terminal in raw mode.
 //
 // Non-TTY stdin (piped input, CI) keeps a plain line read so
 // `printf 'user\npass\n' | gjsify login` still works.
@@ -26,10 +23,9 @@ function isTtyStdin() {
     return Boolean(stdin.isTTY) && typeof stdin.setRawMode === 'function';
 }
 /**
- * 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 function applyKey(buf, ch, mask) {
     if (ch === '\r' || ch === '\n') {

package/lib/utils/publish-diagnose.d.ts

@@ -3,36 +3,31 @@ export type Diagnose404Reason = 'dead-token' | 'live-token-404' | 'unknown';
 export interface Diagnose404Result {
     /** Discriminant — drives the JSON shape + exit-code path in the caller. */
     reason: Diagnose404Reason;
-    /** Username from `/-/whoami` when reason === 'live-token-404'. */
+    /** Set only when `reason === 'live-token-404'`. */
     username?: string;
-    /** Multi-line, human-friendly hint ready for stderr emission. */
+    /** Multi-line hint, ready for stderr as-is. */
     message: string;
 }
 interface Diagnose404Input {
     /** Full package name including scope, e.g. `@gjsify/abort-controller`. */
     packageName: string;
-    /** Pinned version we tried to publish. */
     version: string;
-    /** Registry URL (with or without trailing slash). */
+    /** Registry URL, with or without trailing slash. */
     registry: string;
-    /** Parsed .npmrc — used to derive Authorization on the whoami probe. */
+    /** Source of the Authorization header on the whoami probe. */
     npmrc: NpmrcConfig | undefined;
 }
 /**
- * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: any thrown
- * error / non-2xx falls through to `reason: 'unknown'` so the caller's
- * generic error path runs untouched.
- *
- * Pure async I/O — no side effects, no process.exit, no console writes.
- * The caller owns presentation (stderr vs stdout, plain vs JSON).
+ * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: a thrown error or
+ * non-2xx yields `reason: 'unknown'`, leaving the caller's generic error path
+ * untouched. No side effects and no writes — the caller owns presentation.
  */
 export declare function diagnose404(input: Diagnose404Input): Promise<Diagnose404Result>;
 /**
- * Heuristic: is the 404 body the "dead-token-or-missing-package" shape?
- * npm's PUT returns plain text `Not Found` (sometimes empty body). We trigger
- * the diagnostic for both, plus for the JSON `{"error":"Not Found"}` shape
- * just in case. Other 404 bodies (e.g. with a structured npm error code)
- * keep the generic error path.
+ * Is the 404 body the "dead-token-or-missing-package" shape? npm's PUT answers
+ * with plain-text `Not Found` or an empty body; the JSON `{"error":"Not Found"}`
+ * form is accepted too. Any other 404 body — notably one carrying a structured npm
+ * error code — keeps the generic error path.
  */
 export declare function is404DiagnosticCandidate(body: string): boolean;
 export {};

package/lib/utils/publish-diagnose.js

@@ -1,31 +1,19 @@
 // Dead-token vs new-package diagnostic for `gjsify publish`.
 //
-// When the publish PUT returns `404 Not Found` (body `"Not Found"` or empty)
-// it is ambiguous between two very different situations:
+// A `404 Not Found` on the publish PUT is npm's shape for two very different
+// causes, and guessing sends the user down the wrong path entirely: the
+// `_authToken` has been revoked/expired (npm answers an unrecognised bearer with
+// 404, not 401), or the scoped package genuinely is not on npm yet and needs the
+// first-publish bootstrap from AGENTS.md.
 //
-//   1. The `_authToken` in ~/.npmrc has been revoked / expired. The npm
-//      registry's 404 is its way of saying "we don't recognize this
-//      bearer". Easy to mistake for a missing-package error and send the
-//      user down the wrong path (Trusted-Publisher-bootstrap setup).
-//   2. The scoped `@gjsify/<pkg>` genuinely doesn't exist on npm yet —
-//      the first-publish bootstrap step from AGENTS.md.
-//
-// `GET /-/whoami` with the SAME Authorization header disambiguates: a live
-// token returns `{"username": "..."}`, a dead token returns `{}` (status 200
-// in both cases — the empty body is npm's signal).
-//
-// `npm publish` from npm-cli handles dead tokens with `401 EOTP` + a clear
-// "one-time-password or refresh the token" hint. The 404 path is npm's
-// PUT-specific shape and `gjsify publish` previously just printed the
-// opaque body. This helper closes the diagnostic gap.
+// `GET /-/whoami` with the SAME Authorization header disambiguates: a live token
+// returns `{"username": "…"}`, a dead one returns `{}` — status 200 for both, so
+// the EMPTY BODY is the signal.
 import { whoami } from '@gjsify/npm-registry';
 /**
- * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: any thrown
- * error / non-2xx falls through to `reason: 'unknown'` so the caller's
- * generic error path runs untouched.
- *
- * Pure async I/O — no side effects, no process.exit, no console writes.
- * The caller owns presentation (stderr vs stdout, plain vs JSON).
+ * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: a thrown error or
+ * non-2xx yields `reason: 'unknown'`, leaving the caller's generic error path
+ * untouched. No side effects and no writes — the caller owns presentation.
  */
 export async function diagnose404(input) {
     const { packageName, version, registry, npmrc } = input;
@@ -85,11 +73,10 @@ function formatUnknown(name, version) {
     return `gjsify publish: ${name}@${version} — 404 Not Found`;
 }
 /**
- * Heuristic: is the 404 body the "dead-token-or-missing-package" shape?
- * npm's PUT returns plain text `Not Found` (sometimes empty body). We trigger
- * the diagnostic for both, plus for the JSON `{"error":"Not Found"}` shape
- * just in case. Other 404 bodies (e.g. with a structured npm error code)
- * keep the generic error path.
+ * Is the 404 body the "dead-token-or-missing-package" shape? npm's PUT answers
+ * with plain-text `Not Found` or an empty body; the JSON `{"error":"Not Found"}`
+ * form is accepted too. Any other 404 body — notably one carrying a structured npm
+ * error code — keeps the generic error path.
  */
 export function is404DiagnosticCandidate(body) {
     const trimmed = body.trim();