@gjsify/cli 0.14.0 → 0.16.0

package/lib/commands/trust.d.ts

@@ -1,4 +1,6 @@
+import { type NpmrcConfig } from '@gjsify/npm-registry';
 import type { Command } from '../types/index.js';
+import { OtpProvider } from '../utils/npm-otp.js';
 import { type TrustEntry } from '../utils/trust-registry.js';
 interface TrustOptions {
     packages?: string[];
@@ -13,4 +15,23 @@ interface TrustOptions {
     'no-private'?: boolean;
 }
 export declare const trustCommand: Command<unknown, TrustOptions>;
+/** Parsed result of a trust-registry request. */
+export interface TrustRequestResult {
+    status: number;
+    json: unknown;
+    text: string;
+}
+/** A `(method, url, body?) => TrustRequestResult` function bound to a registry auth + OTP context. */
+export type TrustRequester = (method: string, url: string, body?: unknown) => Promise<TrustRequestResult>;
+/**
+ * Build a trust-registry requester bound to an npmrc + a shared
+ * {@link OtpProvider}. Each request runs through `withOtpRetry` so a 2FA
+ * challenge reuses the cached code before prompting — the same instance passed
+ * to `createTrustRequester` and to the publish flow shares ONE OTP across a
+ * whole `gjsify onboard` sweep.
+ */
+export declare function createTrustRequester(ctx: {
+    npmrc: NpmrcConfig;
+    otpProvider: OtpProvider;
+}): TrustRequester;
 export type { TrustEntry };

package/lib/commands/trust.js

@@ -21,7 +21,7 @@ import { join } from 'node:path';
 import { DEFAULT_REGISTRY, buildHeaders, registryFor, whoami } from '@gjsify/npm-registry';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { hasAnyCredential, loadNpmrc } from '../utils/load-npmrc.js';
-import { promptLine } from '../utils/prompt.js';
+import { OtpProvider, withOtpRetry } from '../utils/npm-otp.js';
 import { classifyTrustList, githubTrustBody, normalizeWorkflowFile, parseRepoFromGitRemote, trustUrl, validateRepository, } from '../utils/trust-registry.js';
 export const trustCommand = {
     command: 'trust [packages..]',
@@ -148,63 +148,13 @@ export const trustCommand = {
         if (dryRun)
             console.log('(dry-run — nothing will be written)');
         console.log();
-        // A one-shot OTP supplied via --otp, used on the FIRST challenge then
-        // cleared (a TOTP code is single-use within its ~30s window). After the
-        // first successful OTP the registry opens a ~5-min skip window, so we
-        // do NOT cache + re-send the code — that would re-challenge once it
-        // expires. Instead each request tries WITHOUT an OTP first (the window
-        // covers it) and only prompts when actually challenged. Mirrors npm's
-        // `otplease`.
-        let pendingOtp = args.otp;
-        const request = async (method, url, body) => {
-            const doFetch = async (code) => {
-                const headers = buildHeaders(url, { npmrc });
-                headers['accept'] = 'application/json';
-                if (body !== undefined)
-                    headers['content-type'] = 'application/json';
-                if (code)
-                    headers['npm-otp'] = code;
-                return fetch(url, {
-                    method,
-                    headers,
-                    body: body === undefined ? undefined : JSON.stringify(body),
-                });
-            };
-            // 1) Try without an OTP — succeeds outright (read) or via an active
-            //    2FA-skip window.
-            let res = await doFetch();
-            // 2) On a challenge, use the --otp (once) or prompt, and retry.
-            if (await isOtpChallenge(res)) {
-                let code = pendingOtp;
-                pendingOtp = undefined; // one-shot — never reuse a stale code
-                if (!code) {
-                    code = await promptLine('This operation requires a one-time password.\nEnter OTP: ');
-                }
-                if (!code) {
-                    console.error('gjsify trust: no OTP entered.');
-                    process.exit(1);
-                }
-                res = await doFetch(code);
-                // 3) Still challenged → the code was stale/expired. Prompt fresh once.
-                if (await isOtpChallenge(res)) {
-                    const fresh = await promptLine('OTP rejected (expired?) — enter a fresh code: ');
-                    if (!fresh) {
-                        console.error('gjsify trust: no OTP entered.');
-                        process.exit(1);
-                    }
-                    res = await doFetch(fresh);
-                }
-            }
-            const text = await res.text().catch(() => '');
-            let json = undefined;
-            try {
-                json = text ? JSON.parse(text) : undefined;
-            }
-            catch {
-                /* non-JSON body — leave json undefined */
-            }
-            return { status: res.status, json, text };
-        };
+        // Cache-first OTP across the whole sweep (shared helper). Each request
+        // tries WITHOUT an OTP first (npm's ~5-min 2FA-skip window covers the
+        // packages after the first success) and only sends a code when actually
+        // challenged: the cached `--otp` / last-typed code first, then a fresh
+        // prompt when npm rejects it. See utils/npm-otp.ts.
+        const otpProvider = new OtpProvider(args.otp);
+        const request = createTrustRequester({ npmrc, otpProvider });
         let ok = 0;
         let skipped = 0;
         let unpublished = 0;
@@ -288,18 +238,38 @@ export const trustCommand = {
         }
     },
 };
-/** True when a response is an npm OTP / 2FA challenge. */
-async function isOtpChallenge(res) {
-    if (res.status !== 401)
-        return false;
-    const wwwAuth = (res.headers.get('www-authenticate') ?? '').toLowerCase();
-    if (wwwAuth.includes('otp'))
-        return true;
-    const text = await res
-        .clone()
-        .text()
-        .catch(() => '');
-    return /one-time pass/i.test(text) || /\bEOTP\b/.test(text);
+/**
+ * Build a trust-registry requester bound to an npmrc + a shared
+ * {@link OtpProvider}. Each request runs through `withOtpRetry` so a 2FA
+ * challenge reuses the cached code before prompting — the same instance passed
+ * to `createTrustRequester` and to the publish flow shares ONE OTP across a
+ * whole `gjsify onboard` sweep.
+ */
+export function createTrustRequester(ctx) {
+    return async (method, url, body) => {
+        const doFetch = (code) => {
+            const headers = buildHeaders(url, { npmrc: ctx.npmrc });
+            headers['accept'] = 'application/json';
+            if (body !== undefined)
+                headers['content-type'] = 'application/json';
+            if (code)
+                headers['npm-otp'] = code;
+            const init = { method, headers };
+            if (body !== undefined)
+                init.body = JSON.stringify(body);
+            return fetch(url, init);
+        };
+        const res = await withOtpRetry(doFetch, ctx.otpProvider);
+        const text = await res.text().catch(() => '');
+        let json = undefined;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            /* non-JSON body — leave json undefined */
+        }
+        return { status: res.status, json, text };
+    };
 }
 function firstLine(s) {
     return s.split('\n')[0].slice(0, 200);

package/lib/commands/workspace.d.ts

@@ -7,6 +7,8 @@ interface WorkspaceCmdOptions {
     'continue-on-error'?: boolean;
     'include-dev'?: boolean;
     verbose?: boolean;
+    cached?: boolean;
 }
 export declare const workspaceCommand: Command<unknown, WorkspaceCmdOptions>;
+export declare function detectPackageManager(): 'yarn' | 'npm' | 'gjsify';
 export {};

package/lib/commands/workspace.js

@@ -15,9 +15,11 @@
 // failures on uninbuilt workspace deps are the single biggest local-dev
 // pain point in this monorepo.
 import { spawn } from 'node:child_process';
-import { buildDependencyGraph, discoverWorkspaces, topologicalSort, } from '@gjsify/workspace';
+import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { suggestClosest } from '../utils/suggest.js';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
     description: 'Run a workspace script (`yarn workspace <name> run <script>` equivalent).',
@@ -41,7 +43,7 @@ export const workspaceCommand = {
         // `-t`/`--topological` is the same flag spelled the way
         // `gjsify foreach` already spells it — kept as an alias so
         // muscle memory transfers.
-        description: 'Pre-build the target workspace\'s transitive workspace dependencies in topological order before running the script in the target. Deps that don\'t declare the script are skipped (--if-present behaviour). Replaces manual `gjsify workspace A build && gjsify workspace B build && …` chains.',
+        description: "Pre-build the target workspace's transitive workspace dependencies in topological order before running the script in the target. Deps that don't declare the script are skipped (--if-present behaviour). Replaces manual `gjsify workspace A build && gjsify workspace B build && …` chains.",
         type: 'boolean',
         alias: ['d', 't', 'topological'],
         default: false,
@@ -61,6 +63,10 @@ export const workspaceCommand = {
         type: 'boolean',
         alias: 'v',
         default: false,
+    })
+        .option('cached', {
+        description: 'Content-hash build cache (ADR 0006): skip the script for a workspace whose inputs (src/**, package.json, tsconfig*.json, transitive workspace deps, toolchain versions) are unchanged and restore its stored outputs instead; on miss run it and store the output dirs it modified. Also applies to the deps run via --with-dependencies. Default from GJSIFY_BUILD_CACHE=1.',
+        type: 'boolean',
     }),
     handler: async (args) => {
         // Walk up to the monorepo root — `gjsify workspace` is often
@@ -71,8 +77,21 @@ export const workspaceCommand = {
         const allWorkspaces = discoverWorkspaces(root);
         const target = allWorkspaces.find((w) => w.name === args.name);
         if (!target) {
-            console.error(`gjsify workspace: no workspace named "${args.name}" — discovered ${allWorkspaces.length} workspace(s)`);
-            process.exit(1);
+            // IMPORTANT: `return process.exit(N)`, not a bare `process.exit(N)`.
+            // Under GJS `process.exit` cannot terminate synchronously (a parked
+            // GLib.MainLoop owns the thread) — it SCHEDULES the exit on a
+            // GLib.idle source and returns a forever-pending Promise. A bare
+            // call therefore falls through to the next statements, dereferences
+            // `target.manifest` on `undefined`, and the resulting throw races
+            // the already-scheduled exit into a SECOND `system.exit` →
+            // `m_should_exit assertion failed` → core dump. `return`-ing halts
+            // the handler so exactly one exit is scheduled. (No-op under Node,
+            // where `process.exit` never returns.)
+            const suggestion = suggestClosest(args.name, allWorkspaces.map((w) => w.name));
+            const hint = suggestion ? ` — did you mean "${suggestion}"?` : '';
+            console.error(`gjsify workspace: no workspace named "${args.name}"${hint} ` +
+                `(discovered ${allWorkspaces.length} workspace(s) under ${root})`);
+            return process.exit(1);
         }
         const runner = detectPackageManager();
         const verbose = args.verbose === true;
@@ -80,8 +99,12 @@ export const workspaceCommand = {
         const continueOnError = args['continue-on-error'] === true;
         const targetScripts = target.manifest.scripts ?? {};
         if (typeof targetScripts[args.script] !== 'string') {
-            console.error(`gjsify workspace: workspace "${args.name}" has no script "${args.script}"`);
-            process.exit(1);
+            const scriptHint = suggestClosest(args.script, Object.keys(targetScripts));
+            console.error(`gjsify workspace: workspace "${args.name}" has no script "${args.script}"` +
+                (scriptHint ? ` — did you mean "${scriptHint}"?` : ''));
+            // `return process.exit` — see the not-found branch above for why a
+            // bare `process.exit` is unsafe under GJS.
+            return process.exit(1);
         }
         // Build the run-list: either just the target, or its transitive
         // workspace-dep closure in topological order followed by the
@@ -97,6 +120,20 @@ export const workspaceCommand = {
         else {
             runList = [target];
         }
+        // Content-hash build cache (ADR 0006 phase 1). Explicit --cached /
+        // --no-cached wins; GJSIFY_BUILD_CACHE=1 is the env default so root
+        // script chains opt in without editing every nested invocation. Keys
+        // are computed against ALL discovered workspaces.
+        const cached = args.cached ?? buildCacheEnabledByEnv();
+        const cache = cached
+            ? new BuildCacheRunner({
+                root,
+                workspaces: allWorkspaces,
+                script: args.script,
+                args: args.args ?? [],
+                targets: runList.map((w) => w.name),
+            })
+            : undefined;
         const failures = [];
         for (const ws of runList) {
             const scripts = ws.manifest.scripts ?? {};
@@ -104,31 +141,35 @@ export const workspaceCommand = {
                 // Skip deps that don't declare the script — mirrors
                 // `gjsify foreach`'s --if-present behaviour. The target
                 // itself was validated above; this branch only filters
-                // intermediate deps.
+                // intermediate deps. A skipped package is also never touched
+                // by the build cache (the no-build-package safety rule).
                 if (verbose)
                     console.error(`[${ws.name}] (no "${args.script}" script — skipping)`);
                 continue;
             }
             try {
-                await runOne(ws, args.script, args.args ?? [], runner, verbose);
+                await runOne(ws, args.script, args.args ?? [], runner, verbose, cache);
             }
             catch (err) {
                 const e = err instanceof Error ? err : new Error(String(err));
                 console.error(`[${ws.name}] ${e.message}`);
                 if (!continueOnError) {
-                    process.exit(1);
+                    // `return` — a bare `process.exit` would not halt under GJS
+                    // and the loop would keep running the remaining deps.
+                    return process.exit(1);
                 }
                 failures.push({ workspace: ws.name, error: e });
             }
         }
         if (failures.length > 0) {
             console.error(`gjsify workspace: ${failures.length} workspace(s) failed: ${failures.map((f) => f.workspace).join(', ')}`);
-            process.exit(1);
+            return process.exit(1);
         }
         // ensureMainLoop() (called inside spawn) keeps GJS alive after the
         // child exits — without an explicit process.exit() the success path
-        // would park the loop forever.
-        process.exit(0);
+        // would park the loop forever. `return` for symmetry with the error
+        // paths above (see the not-found branch for the GJS rationale).
+        return process.exit(0);
     },
 };
 /**
@@ -175,7 +216,14 @@ function collectTransitiveClosure(target, allWorkspaces, includeDev) {
     }
     return out;
 }
-async function runOne(ws, script, extraArgs, runner, verbose) {
+async function runOne(ws, script, extraArgs, runner, verbose, cache) {
+    // Build-cache fast path: on a key hit restore the stored outputs and
+    // skip the script; on a miss snapshot the output dirs so only what the
+    // script MODIFIED is stored after success (never a committed no-build
+    // lib/ — see utils/build-cache.ts).
+    if (cache && cache.tryRestore(ws))
+        return;
+    const before = cache?.snapshotOutputs(ws);
     const argv = runner === 'gjsify'
         ? ['run', script, ...extraArgs]
         : ['run', script, ...(extraArgs.length > 0 ? ['--', ...extraArgs] : [])];
@@ -202,8 +250,10 @@ async function runOne(ws, script, extraArgs, runner, verbose) {
         });
         child.on('error', reject);
     });
+    if (cache && before)
+        cache.storeAfterSuccess(ws, before);
 }
-function detectPackageManager() {
+export function detectPackageManager() {
     // Under GJS there is no Node, so neither `npm` nor `yarn` can run scripts —
     // the only option is `gjsify` itself, resolved via the GJS shim on PATH
     // (see `ensureGjsifyShimOnPath`). This is what makes node-free multi-package

package/lib/utils/build-cache.d.ts

@@ -0,0 +1,157 @@
+import { type Workspace } from '@gjsify/workspace';
+/** Bump to invalidate every existing cache entry (schema/semantic changes). */
+export declare const BUILD_CACHE_LAYOUT_VERSION = "v1";
+/** Conventional per-package build output directories, checked in this order. */
+export declare const OUTPUT_DIR_CANDIDATES: readonly ["lib", "dist", "dist-templates"];
+/** Keep at most this many keys per package; evict the least recently stored/used. */
+export declare const MAX_KEYS_PER_PACKAGE = 2;
+/** Toolchain packages whose resolved versions salt every cache key. */
+export declare const TOOLCHAIN_PACKAGES: readonly ["@gjsify/cli", "@gjsify/tsc", "rolldown", "typescript"];
+export interface BuildCacheManifest {
+    version: 1;
+    layout: string;
+    package: string;
+    script: string;
+    key: string;
+    /** Output dirs (relative to the package dir) the build modified. */
+    dirs: string[];
+    /** Content hash of the stored output dirs (mtime-independent). */
+    outputsHash: string;
+    createdAt: string;
+    usedAt: string;
+}
+/** `true` when GJSIFY_BUILD_CACHE is set to a non-empty, non-"0"/"false" value. */
+export declare function buildCacheEnabledByEnv(env?: Record<string, string | undefined>): boolean;
+/** Cache root for a workspace: `<root>/node_modules/.cache/gjsify/build`. */
+export declare function buildCacheRoot(workspaceRoot: string): string;
+/**
+ * Directory-safe package name. Scoped names collapse (`@gjsify/cli` →
+ * `gjsify-cli`); an 8-hex sha256 suffix of the exact name rules out
+ * collisions between e.g. `@a/b-c` and `@a-b/c`.
+ */
+export declare function sanitizePackageDirName(name: string): string;
+/** Streamed sha256 of one file (bounded memory, real contents). */
+export declare function hashFileStream(path: string): string;
+/**
+ * Content hash of a package's build INPUTS: every file under `src/**`, plus
+ * `package.json`, plus root `tsconfig*.json`. Sorted, content-streamed —
+ * mtimes do not participate, so a `git checkout` with identical contents
+ * hashes identically across machines.
+ */
+export declare function hashPackageInputs(location: string): string;
+/**
+ * Mtime-independent content hash of a set of output dirs — used to skip the
+ * restore copy when the on-disk outputs already match the cached entry, and
+ * as an integrity stamp of what was stored.
+ */
+export declare function hashOutputDirs(location: string, dirs: readonly string[]): string;
+/**
+ * Cheap per-dir change signature (existence + file list + sizes + mtimes).
+ * Taken BEFORE running the script and compared AFTER, to detect which output
+ * dirs the build actually modified. Content hashing is deliberately avoided
+ * here — a build that rewrites identical bytes still bumps mtimes, and that
+ * is exactly the "this dir belongs to the build" signal we want.
+ */
+export declare function snapshotOutputDirs(location: string): Record<string, string | null>;
+/** Output dirs whose signature changed (or that newly appeared) since `before`. */
+export declare function modifiedOutputDirs(location: string, before: Record<string, string | null>): string[];
+export interface ComposeCacheKeyInput {
+    script: string;
+    /** Extra args forwarded to the script invocation (affect the outputs). */
+    args?: readonly string[];
+    /** Toolchain package → resolved version (or 'none'). */
+    toolchain: Record<string, string>;
+    /** The package's own input hash. */
+    ownHash: string;
+    /** dep name → input hash for the FULL transitive workspace-dep closure. */
+    depHashes: ReadonlyMap<string, string> | Record<string, string>;
+}
+/** Deterministic cache key (32 hex chars) from all invalidation ingredients. */
+export declare function composeCacheKey(input: ComposeCacheKeyInput): string;
+/**
+ * Resolve the toolchain versions that salt every key from the workspace's
+ * OWN resolution (`<root>/node_modules/<pkg>/package.json`). In the gjsify
+ * monorepo these are symlinks into the workspace itself, so a CLI/tsc bump
+ * invalidates immediately. A package that isn't resolvable maps to 'none'
+ * (deterministic). `@gjsify/cli` additionally falls back to the RUNNING
+ * CLI's own version so globally-installed CLIs still salt correctly.
+ */
+export declare function resolveToolchainVersions(workspaceRoot: string): Record<string, string>;
+/** Directory of one cache entry: `<cacheRoot>/<pkg-sanitized>/<key>`. */
+export declare function buildCacheEntryDir(cacheRoot: string, pkgName: string, key: string): string;
+/** Read + validate a cache entry's manifest; any mismatch is a MISS (null). */
+export declare function readCacheEntry(cacheRoot: string, pkgName: string, key: string): BuildCacheManifest | null;
+/**
+ * Store the given output dirs of a package under `key`. Atomic: builds a
+ * `.tmp-<pid>` sibling then renames into place, so concurrent readers never
+ * observe a partial entry. Best-effort — failures are swallowed (the build
+ * itself already succeeded).
+ */
+export declare function storeCacheEntry(cacheRoot: string, pkg: {
+    name: string;
+    location: string;
+}, key: string, script: string, dirs: readonly string[]): BuildCacheManifest | null;
+/**
+ * Restore a validated entry into the package. Replaces EXACTLY the dirs the
+ * manifest records (delete-then-copy within the package); skips the copy
+ * when the on-disk outputs already content-match the entry. Returns how the
+ * hit was satisfied, or null when restoration failed (treat as MISS).
+ */
+export declare function restoreCacheEntry(cacheRoot: string, pkg: {
+    name: string;
+    location: string;
+}, manifest: BuildCacheManifest): 'restored' | 'up-to-date' | null;
+/** Evict the oldest entries (by last store/use) beyond `keep` per package. */
+export declare function pruneCacheEntries(cacheRoot: string, pkgName: string, keep?: number): void;
+export interface BuildCacheRunnerOptions {
+    /** Workspace (monorepo) root — owns node_modules/.cache. */
+    root: string;
+    /** ALL discovered workspaces (not just the selected set) for dep closure. */
+    workspaces: readonly Workspace[];
+    /** Script name being run (part of every key). */
+    script: string;
+    /** Extra args forwarded to every invocation (part of every key). */
+    args?: readonly string[];
+    /**
+     * Workspace names that will be run. Their input hashes (plus their
+     * closures') are computed EAGERLY at construction so every key reflects
+     * the tree state at RUN START — a build that mutates its own `src/`
+     * (adwaita-web's generated stylesheet module) must not make a sibling's
+     * key depend on scheduling order within the same run.
+     */
+    targets?: readonly string[];
+    /** Log sink (default: stderr, keeping stdout clean for script output). */
+    log?: (line: string) => void;
+}
+export declare function buildCacheOptedOut(ws: Workspace): boolean;
+/**
+ * Per-run orchestrator used by `gjsify workspace` / `gjsify foreach`:
+ * memoizes input hashes + keys across packages, restores on hit, snapshots +
+ * stores on miss. All entry points are fail-soft — any internal error logs a
+ * warning and reports a MISS so the script runs normally.
+ */
+export declare class BuildCacheRunner {
+    private readonly options;
+    private readonly cacheRoot;
+    private readonly graph;
+    private readonly toolchain;
+    private readonly ownHashes;
+    private readonly closures;
+    private readonly keys;
+    private readonly log;
+    constructor(options: BuildCacheRunnerOptions);
+    private ownHashOf;
+    /** BFS transitive workspace-dep closure (cycle-safe), excluding `name` itself. */
+    private closureOf;
+    /** Content-hash cache key for one workspace (memoized per run). */
+    keyFor(ws: Workspace): string;
+    /**
+     * Try to satisfy the script from the cache. Returns `true` on a hit
+     * (outputs restored / already current — the caller SKIPS the script).
+     */
+    tryRestore(ws: Workspace): boolean;
+    /** Snapshot the candidate output dirs BEFORE running the script. */
+    snapshotOutputs(ws: Workspace): Record<string, string | null>;
+    /** After a SUCCESSFUL script run: store the dirs the build modified. */
+    storeAfterSuccess(ws: Workspace, before: Record<string, string | null>): void;
+}