@storystick/cli 0.0.0-stage → 0.2.0-rc.0

package/dist/content-import.js

@@ -0,0 +1,210 @@
+/** Node management client. Never imported by customer rendering bundles. */
+import { createReadStream } from 'node:fs';
+import { readFile, writeFile, mkdir, link, unlink, rename, stat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { StorystickError } from './cli-error.js';
+import { CONTENT_IMPORT_LIMITS, importDigest, importObject, importAssetDependencies, parseImportManifest, planImportBatches } from '@storystick/core/content-import';
+import { callHubApi } from './hub-client.js';
+import { readAssetImport, prepareAssetImport } from './asset-import.js';
+export async function readContentImport(file) {
+    const path = resolve(file), directory = await realpath(dirname(path));
+    const input = importObject(JSON.parse(await readFile(path, 'utf8')), 'manifest');
+    const { records: files, assets: assetFiles, ...metadata } = input;
+    if (!Array.isArray(files) || !files.length || files.some(file => typeof file !== 'string'))
+        throw new Error('Manifest records must list local NDJSON files.');
+    const records = [];
+    let totalBytes = 0;
+    for (const file of files) {
+        const resolved = resolve(directory, file), rel = relative(directory, resolved);
+        if (isAbsolute(file) || rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+            throw new Error('NDJSON files must be inside the manifest directory.');
+        const actual = relative(directory, await realpath(resolved));
+        if (actual === '..' || actual.startsWith('../') || isAbsolute(actual))
+            throw new Error('NDJSON files must be inside the manifest directory.');
+        const declaredBytes = (await stat(resolved)).size;
+        const previousBytes = totalBytes;
+        totalBytes += declaredBytes;
+        if (totalBytes > 32 * 1024 * 1024)
+            throw new Error('Import exceeds the 32 MiB input limit.');
+        // NDJSON separates records with LF, not Unicode prose separators. Node's
+        // readline can split U+2028/U+2029 inside otherwise valid JSON strings.
+        const stream = createReadStream(resolved, { encoding: 'utf8' });
+        let pending = '', lineNumber = 0, actualBytes = 0;
+        const parseLine = (line) => {
+            lineNumber++;
+            if (!line.trim())
+                return;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch {
+                throw new Error(`${file}:${lineNumber}: invalid JSON`);
+            }
+            if (records.length > CONTENT_IMPORT_LIMITS.records)
+                throw new Error('Import exceeds the 2000 document limit.');
+        };
+        try {
+            for await (const chunk of stream) {
+                actualBytes += Buffer.byteLength(chunk);
+                if (previousBytes + actualBytes > CONTENT_IMPORT_LIMITS.totalBytes)
+                    throw new Error('Import exceeds the 32 MiB input limit.');
+                pending += chunk;
+                let end;
+                while ((end = pending.indexOf('\n')) >= 0) {
+                    parseLine(pending.slice(0, end));
+                    pending = pending.slice(end + 1);
+                }
+            }
+            if (pending)
+                parseLine(pending);
+            totalBytes = previousBytes + actualBytes;
+        }
+        finally {
+            stream.destroy();
+        }
+    }
+    const batches = planImportBatches(records);
+    const manifest = parseImportManifest({ ...metadata, batchDigests: await Promise.all(batches.map(importDigest)), recordCount: records.length });
+    const assets = [];
+    if (assetFiles !== undefined) {
+        if (!Array.isArray(assetFiles) || assetFiles.length > CONTENT_IMPORT_LIMITS.records || assetFiles.some(f => typeof f !== 'string'))
+            throw new Error('Manifest assets must list local asset manifests.');
+        const keys = new Set();
+        for (const name of assetFiles) {
+            const actual = await realpath(resolve(directory, name)), rel = relative(directory, actual);
+            if (isAbsolute(name) || rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+                throw new Error('Asset manifests must be inside the manifest directory.');
+            const asset = await readAssetImport(actual);
+            if (asset.input.namespace !== manifest.namespace || keys.has(asset.input.key))
+                throw new Error('Asset source keys must be unique and use the corpus namespace.');
+            keys.add(asset.input.key);
+            assets.push(asset);
+        }
+        for (const record of batches.flat())
+            for (const key of importAssetDependencies(record)) {
+                if (!keys.has(key))
+                    throw new Error(`${record.key}: missing asset manifest for ${key}.`);
+            }
+    }
+    return { manifest, batches, assets };
+}
+/** Reserve source identities without uploading. All local inputs have already been checked. */
+export async function prepareContentImportAssets(transport, source) {
+    const plans = [];
+    for (const asset of source.assets) {
+        const plan = await prepareAssetImport(transport, asset.input);
+        if (!plan.assetId || plan.inputDigest !== await importDigest(asset.input))
+            throw new Error('Asset plan does not match its local source.');
+        plans.push({ ...asset, plan });
+    }
+    const manifest = plans.length ? parseImportManifest({ ...source.manifest,
+        assets: plans.map(({ input, plan }) => ({ key: input.key, assetId: plan.assetId, inputDigest: plan.inputDigest })),
+    }) : source.manifest;
+    return { manifest, batches: source.batches, assets: plans };
+}
+export function contentImportTransport(projectShortId, options) {
+    return managementImportTransport('/api/cli/content-import', projectShortId, options);
+}
+export function assetImportTransport(projectShortId, options) {
+    return managementImportTransport('/api/cli/asset-import', projectShortId, options);
+}
+export function uploadBudgetTransport(projectShortId, options) {
+    return managementImportTransport('/api/cli/upload-budget', projectShortId, options);
+}
+function managementImportTransport(endpoint, projectShortId, options) {
+    return async (request) => {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await callHubApi(endpoint, { ...options, method: 'POST', body: { projectShortId, request } });
+            }
+            catch (error) {
+                const transient = error instanceof StorystickError
+                    ? error.retryable === true || [429, 502, 503, 504].includes(error.status ?? 0)
+                    : error instanceof TypeError;
+                const wait = error instanceof StorystickError && error.retryAfterMs !== undefined ? error.retryAfterMs : 500 * 2 ** attempt;
+                if (!transient || attempt >= 4 || wait > 60_000 || options.signal?.aborted)
+                    throw error;
+                // Every request has a server-owned replay receipt. Never mint a new
+                // operation identity because a response was lost or throttled.
+                await delay(wait, undefined, { signal: options.signal });
+            }
+        }
+    };
+}
+/** Receipt identity is written before the first remote call. No content/secrets. */
+export async function importRunIdentity(input) {
+    if (input.resume)
+        return input.resume;
+    const digest = await importDigest({ project: input.project, gateway: input.gateway, manifest: input.manifest });
+    const directory = resolve(input.root, '.storystick', 'imports'), path = resolve(directory, `${digest}.json`);
+    if (!input.newRun)
+        try {
+            const receipt = JSON.parse(await readFile(path, 'utf8'));
+            if (receipt.digest !== digest || typeof receipt.runId !== 'string')
+                throw new Error('Invalid local import receipt.');
+            return receipt.runId;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    await mkdir(directory, { recursive: true });
+    const runId = randomUUID(), temporary = `${path}.${runId}.tmp`;
+    await writeFile(temporary, JSON.stringify({ version: 1, runId, digest, project: input.project }, null, 2) + '\n', { mode: 0o600 });
+    if (input.newRun) {
+        await rename(temporary, path);
+        return runId;
+    }
+    try {
+        // Atomic no-replace installation: simultaneous clients share one run.
+        await link(temporary, path);
+        return runId;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        return importRunIdentity(input);
+    }
+    finally {
+        await unlink(temporary);
+    }
+}
+export async function prepareContentImport(transport, input) {
+    const { runId, manifest, batches } = input;
+    await transport({ operation: 'begin', runId, manifest });
+    for (let index = 0; index < batches.length; index++)
+        await transport({ operation: 'stage', runId, index, records: batches[index] });
+    const plans = [];
+    for (let index = 0; index < batches.length; index++)
+        plans.push(await transport({ operation: 'plan', runId, index }));
+    const status = await transport({ operation: 'seal', runId });
+    return { ...status, plans };
+}
+export async function applyContentImport(transport, runId, planDigest) {
+    const state = await transport({ operation: 'status', runId });
+    if (state.planDigest !== planDigest)
+        throw new Error('The supplied digest does not match the sealed server plan.');
+    if (state.state === 'cancelled' || state.state === 'preparing' || state.state === 'expired')
+        throw new Error(`Import cannot apply while ${state.state}.`);
+    for (let offset = state.assetsReady; offset < state.assetCount; offset += CONTENT_IMPORT_LIMITS.recordsPerBatch) {
+        await transport({ operation: 'ack-assets', runId, index: Math.floor(offset / CONTENT_IMPORT_LIMITS.recordsPerBatch), planDigest });
+    }
+    for (let index = state.applied; index < state.batches; index++)
+        await transport({ operation: 'apply', runId, index, planDigest });
+    return transport({ operation: 'status', runId });
+}
+export async function verifyContentImport(transport, runId) {
+    const state = await transport({ operation: 'status', runId });
+    const assets = [];
+    for (let offset = 0; offset < state.assetsReady; offset += CONTENT_IMPORT_LIMITS.recordsPerBatch) {
+        const proof = await transport({ operation: 'verify-assets', runId, index: Math.floor(offset / CONTENT_IMPORT_LIMITS.recordsPerBatch) });
+        assets.push(...proof.assets);
+    }
+    const batches = [];
+    for (let index = 0; index < state.applied; index++)
+        batches.push(await transport({ operation: 'verify', runId, index }));
+    return { ...state, verified: state.state === 'complete' && state.assetsReady === state.assetCount && assets.every(a => a.matches) && batches.every(b => [...b.documents, ...b.assets].every(d => d.matches)),
+        projected: state.state === 'complete' && batches.every(b => b.projection === 'caught-up'), verification: batches, assetVerification: assets };
+}

package/dist/generated-transaction.d.ts

@@ -0,0 +1,22 @@
+import type { GeneratedFile } from '@storystick/core';
+export type GenerationFaultPoint = 'after-generation-write' | 'before-pointer-commit' | 'after-pointer-commit';
+export interface GeneratedTransactionOptions {
+    readonly check?: boolean;
+    /** Test-only deterministic crash seam. */
+    readonly faultAt?: GenerationFaultPoint;
+    /** Test-only child-process pause seam used to prove hard-crash recovery. */
+    readonly pauseAt?: GenerationFaultPoint;
+    readonly onPause?: (point: GenerationFaultPoint) => void;
+}
+export interface GeneratedTransactionResult {
+    readonly files: readonly string[];
+    readonly generationId: string;
+}
+export interface PreparedGeneratedTransaction extends GeneratedTransactionResult {
+    readonly outputDirectory: string;
+}
+export declare function commitGeneratedFiles(outputDirectory: string, generated: readonly GeneratedFile[], options?: GeneratedTransactionOptions): Promise<GeneratedTransactionResult>;
+/** Write immutable bytes without installing facades or moving the pointer. */
+export declare function prepareGeneratedFiles(outputDirectory: string, generated: readonly GeneratedFile[], options?: Pick<GeneratedTransactionOptions, 'faultAt' | 'pauseAt' | 'onPause'>): Promise<PreparedGeneratedTransaction>;
+/** Commit an already staged immutable generation, including after restart. */
+export declare function commitPreparedGeneration(outputDirectory: string, generationId: string, options?: Pick<GeneratedTransactionOptions, 'faultAt' | 'pauseAt' | 'onPause'>): Promise<GeneratedTransactionResult>;

package/dist/generated-transaction.js

@@ -0,0 +1,330 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, readdir, rename, rm, } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+const GENERATIONS_DIRECTORY = '.storystick-generations';
+const CURRENT_POINTER = '.storystick-current.ts';
+const GENERATION_MANIFEST = '.storystick-generation.json';
+const STABLE_FILES = ['types.ts', 'query.ts', 'preview-provenance.ts'];
+const GENERATED_FILE_MARKER = '// Auto-generated by Storystick. Do not edit.';
+const LEGACY_GENERATED_PREFIXES = [
+    `// ──────────────────────────────────────────\n${GENERATED_FILE_MARKER}\n`,
+    `// -----------------------------------------------------------------------------\n${GENERATED_FILE_MARKER}\n`,
+];
+const FACADE = [
+    GENERATED_FILE_MARKER,
+    '// A single atomic pointer selects the complete immutable generation.',
+    "export * from './.storystick-current'",
+    '',
+].join('\n');
+export async function commitGeneratedFiles(outputDirectory, generated, options = {}) {
+    const files = normalizedFiles(generated);
+    const generationId = generationIdFor(files);
+    const expected = expectedGeneration(outputDirectory, generationId, files);
+    if (options.check) {
+        const drift = await checkGeneration(expected);
+        if (drift.length > 0) {
+            throw new Error(`Generated artifacts are out of date:\n${drift.map((entry) => `- ${entry}`).join('\n')}`);
+        }
+        return { files: STABLE_FILES.map((file) => join(outputDirectory, file)), generationId };
+    }
+    await prepareGeneratedFiles(outputDirectory, files, options);
+    return commitPreparedGeneration(outputDirectory, generationId, options);
+}
+/** Write immutable bytes without installing facades or moving the pointer. */
+export async function prepareGeneratedFiles(outputDirectory, generated, options = {}) {
+    const files = normalizedFiles(generated);
+    const generationId = generationIdFor(files);
+    const expected = expectedGeneration(outputDirectory, generationId, files);
+    await prepareOutputDirectory(outputDirectory);
+    await validateOwnedPaths(outputDirectory);
+    await writeImmutableGeneration(expected);
+    await checkpoint(options, 'after-generation-write');
+    return {
+        outputDirectory,
+        generationId,
+        files: STABLE_FILES.map((file) => join(outputDirectory, file)),
+    };
+}
+/** Commit an already staged immutable generation, including after restart. */
+export async function commitPreparedGeneration(outputDirectory, generationId, options = {}) {
+    if (!/^g-[a-f0-9]{24}$/u.test(generationId)) {
+        throw new Error('Invalid prepared generation id.');
+    }
+    await prepareOutputDirectory(outputDirectory);
+    await validateOwnedPaths(outputDirectory);
+    const files = await readPreparedGeneration(outputDirectory, generationId);
+    const expected = expectedGeneration(outputDirectory, generationId, files);
+    await installStableFacades(outputDirectory);
+    await checkpoint(options, 'before-pointer-commit');
+    await atomicWriteFile(join(outputDirectory, CURRENT_POINTER), expected.pointer);
+    await syncDirectory(outputDirectory);
+    await checkpoint(options, 'after-pointer-commit');
+    await cleanupOwnedOrphans(outputDirectory, generationId);
+    return { files: STABLE_FILES.map((file) => join(outputDirectory, file)), generationId };
+}
+function normalizedFiles(generated) {
+    const byName = new Map();
+    for (const file of generated) {
+        if (!STABLE_FILES.includes(file.filename)) {
+            throw new Error(`Generator does not own ${JSON.stringify(file.filename)}.`);
+        }
+        if (basename(file.filename) !== file.filename || byName.has(file.filename)) {
+            throw new Error(`Invalid generated filename ${JSON.stringify(file.filename)}.`);
+        }
+        byName.set(file.filename, { filename: file.filename, content: file.content });
+    }
+    for (const required of STABLE_FILES) {
+        if (!byName.has(required))
+            throw new Error(`Missing generated file ${required}.`);
+    }
+    return [...byName.values()].sort((left, right) => left.filename.localeCompare(right.filename));
+}
+function generationIdFor(files) {
+    const hash = createHash('sha256');
+    for (const file of files) {
+        hash.update(file.filename);
+        hash.update('\0');
+        hash.update(file.content);
+        hash.update('\0');
+    }
+    return `g-${hash.digest('hex').slice(0, 24)}`;
+}
+function expectedGeneration(outputDirectory, generationId, files) {
+    const relativeRoot = `./${GENERATIONS_DIRECTORY}/${generationId}`;
+    const pointer = [
+        '// Auto-generated by Storystick. Do not edit.',
+        `// Generation: ${generationId}`,
+        ...files.map((file) => `export * from '${relativeRoot}/${file.filename.replace(/\.ts$/u, '')}'`),
+        '',
+    ].join('\n');
+    const manifest = `${JSON.stringify({
+        version: 1,
+        generationId,
+        files: files.map((file) => ({
+            name: file.filename,
+            sha256: createHash('sha256').update(file.content).digest('hex'),
+        })),
+    }, null, 2)}\n`;
+    const generationDirectory = join(outputDirectory, GENERATIONS_DIRECTORY, generationId);
+    return { outputDirectory, generationId, generationDirectory, files, pointer, manifest };
+}
+async function checkGeneration(expected) {
+    const drift = [];
+    for (const stable of STABLE_FILES) {
+        if (await readRegularFile(join(expected.outputDirectory, stable)) !== FACADE)
+            drift.push(stable);
+    }
+    if (await readRegularFile(join(expected.outputDirectory, CURRENT_POINTER)) !== expected.pointer) {
+        drift.push(CURRENT_POINTER);
+    }
+    for (const file of expected.files) {
+        if (await readRegularFile(join(expected.generationDirectory, file.filename)) !== file.content) {
+            drift.push(`${GENERATIONS_DIRECTORY}/${expected.generationId}/${file.filename}`);
+        }
+    }
+    if (await readRegularFile(join(expected.generationDirectory, GENERATION_MANIFEST)) !== expected.manifest) {
+        drift.push(`${GENERATIONS_DIRECTORY}/${expected.generationId}/${GENERATION_MANIFEST}`);
+    }
+    return drift;
+}
+async function prepareOutputDirectory(outputDirectory) {
+    const status = await safeLstat(outputDirectory);
+    if (status?.isSymbolicLink())
+        throw new Error('Generated output directory must not be a symlink.');
+    if (status && !status.isDirectory())
+        throw new Error('Generated output path must be a directory.');
+    await mkdir(outputDirectory, { recursive: true });
+}
+async function validateOwnedPaths(outputDirectory) {
+    for (const name of [...STABLE_FILES, CURRENT_POINTER, GENERATIONS_DIRECTORY]) {
+        const path = join(outputDirectory, name);
+        const status = await safeLstat(path);
+        if (!status)
+            continue;
+        if (status.isSymbolicLink())
+            throw new Error(`Generated owned path ${name} must not be a symlink.`);
+        if (name === GENERATIONS_DIRECTORY) {
+            if (!status.isDirectory())
+                throw new Error(`${name} must be a directory.`);
+            continue;
+        }
+        if (!status.isFile())
+            throw new Error(`Generated owned path ${name} must be a file.`);
+        const content = await readFile(path, 'utf8');
+        if (name === CURRENT_POINTER && !content.startsWith('// Auto-generated by Storystick.')) {
+            throw new Error(`Refusing collision on generated owned file ${name}.`);
+        }
+        if (STABLE_FILES.includes(name) &&
+            !isOwnedGeneratedFile(content)) {
+            throw new Error(`Refusing collision on generated owned file ${name}.`);
+        }
+    }
+}
+function isOwnedGeneratedFile(content) {
+    return content === FACADE ||
+        content.startsWith(GENERATED_FILE_MARKER) ||
+        LEGACY_GENERATED_PREFIXES.some((prefix) => content.startsWith(prefix));
+}
+async function writeImmutableGeneration(expected) {
+    await mkdir(join(expected.outputDirectory, GENERATIONS_DIRECTORY), { recursive: true });
+    const existing = await safeLstat(expected.generationDirectory);
+    if (existing) {
+        if (!existing.isDirectory() || (await checkGenerationFiles(expected)).length > 0) {
+            throw new Error(`Immutable generation collision at ${expected.generationId}.`);
+        }
+        return;
+    }
+    const temporary = `${expected.generationDirectory}.tmp-${randomUUID()}`;
+    await mkdir(temporary);
+    try {
+        for (const file of expected.files)
+            await writeSyncedFile(join(temporary, file.filename), file.content, true);
+        await writeSyncedFile(join(temporary, GENERATION_MANIFEST), expected.manifest, true);
+        await syncDirectory(temporary);
+        await rename(temporary, expected.generationDirectory);
+        await syncDirectory(join(expected.outputDirectory, GENERATIONS_DIRECTORY));
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function checkGenerationFiles(expected) {
+    const drift = [];
+    for (const file of expected.files) {
+        if (await readRegularFile(join(expected.generationDirectory, file.filename)) !== file.content)
+            drift.push(file.filename);
+    }
+    if (await readRegularFile(join(expected.generationDirectory, GENERATION_MANIFEST)) !== expected.manifest) {
+        drift.push(GENERATION_MANIFEST);
+    }
+    return drift;
+}
+async function readPreparedGeneration(outputDirectory, generationId) {
+    const directory = join(outputDirectory, GENERATIONS_DIRECTORY, generationId);
+    const rawManifest = await readRegularFile(join(directory, GENERATION_MANIFEST));
+    if (!rawManifest)
+        throw new Error(`Prepared generation ${generationId} is missing.`);
+    let manifest;
+    try {
+        manifest = JSON.parse(rawManifest);
+    }
+    catch {
+        throw new Error(`Prepared generation ${generationId} manifest is invalid.`);
+    }
+    if (typeof manifest !== 'object' ||
+        manifest === null ||
+        manifest.version !== 1 ||
+        manifest.generationId !== generationId ||
+        !Array.isArray(manifest.files)) {
+        throw new Error(`Prepared generation ${generationId} manifest is invalid.`);
+    }
+    const declared = manifest.files;
+    if (declared.length !== STABLE_FILES.length ||
+        declared.some((file) => typeof file.name !== 'string' ||
+            !STABLE_FILES.includes(file.name) ||
+            typeof file.sha256 !== 'string')) {
+        throw new Error(`Prepared generation ${generationId} manifest is invalid.`);
+    }
+    const files = [];
+    for (const item of declared) {
+        const content = await readRegularFile(join(directory, item.name));
+        if (content === null ||
+            createHash('sha256').update(content).digest('hex') !== item.sha256) {
+            throw new Error(`Prepared generation ${generationId} failed integrity check.`);
+        }
+        files.push({ filename: item.name, content });
+    }
+    const normalized = normalizedFiles(files);
+    if (generationIdFor(normalized) !== generationId) {
+        throw new Error(`Prepared generation ${generationId} identity mismatch.`);
+    }
+    return normalized;
+}
+async function installStableFacades(outputDirectory) {
+    for (const stable of STABLE_FILES) {
+        const path = join(outputDirectory, stable);
+        if (await readRegularFile(path) !== FACADE)
+            await atomicWriteFile(path, FACADE);
+    }
+}
+async function atomicWriteFile(path, content) {
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    await writeSyncedFile(temporary, content, true);
+    try {
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+async function writeSyncedFile(path, content, exclusive) {
+    const handle = await open(path, exclusive ? 'wx' : 'w');
+    try {
+        await handle.writeFile(content, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function cleanupOwnedOrphans(outputDirectory, current) {
+    const root = join(outputDirectory, GENERATIONS_DIRECTORY);
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name === current || !/^g-[a-f0-9]{24}$/u.test(entry.name))
+            continue;
+        const directory = join(root, entry.name);
+        const manifest = await readRegularFile(join(directory, GENERATION_MANIFEST));
+        if (!manifest)
+            continue;
+        try {
+            const parsed = JSON.parse(manifest);
+            if (parsed.version === 1 && parsed.generationId === entry.name) {
+                await rm(directory, { recursive: true });
+            }
+        }
+        catch {
+            // Unknown directories are deliberately preserved.
+        }
+    }
+}
+async function syncDirectory(path) {
+    const handle = await open(path, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readRegularFile(path) {
+    const status = await safeLstat(path);
+    if (!status || !status.isFile() || status.isSymbolicLink())
+        return null;
+    return readFile(path, 'utf8');
+}
+async function safeLstat(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+}
+function isNotFound(error) {
+    return typeof error === 'object' && error !== null &&
+        'code' in error && error.code === 'ENOENT';
+}
+async function checkpoint(options, point) {
+    if (options.faultAt === point)
+        throw new Error(`Injected generation fault at ${point}.`);
+    if (options.pauseAt === point) {
+        options.onPause?.(point);
+        await new Promise(() => {
+            setInterval(() => undefined, 1_000);
+        });
+    }
+}

package/dist/hub-client.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Hub API client (SPEC-1 Item #3 — session-expired UX).
+ *
+ * Every CLI command that calls a user-scoped Hub endpoint MUST route through
+ * `callHubApi`. Two things it guarantees:
+ *
+ *   1. **Lazy 401 recovery.** If the CLI JWT has expired, the Hub returns
+ *      401. Instead of dumping a stack trace and exiting, we print a single
+ *      friendly line, launch device-auth login inline, and retry the original
+ *      request ONCE. Second 401 on retry propagates — we do not loop.
+ *
+ *   2. **Structured error surface.** The Hub's Pattern D error envelope is
+ *      `{ code, message }`; on non-2xx responses we throw a `StorystickError`
+ *      whose message ends with the Hub's message, tacked with `(code)` when
+ *      present. Command-level code prints these directly without extra
+ *      wrapping.
+ *
+ * Edge cases (per spec §Edge cases):
+ *
+ *   - 403 Forbidden → do NOT retry. Treated as "valid token, insufficient
+ *     rights" (e.g. user removed from project mid-session, endpoint requires
+ *     admin). Surface verbatim.
+ *   - 429 on retry → do NOT retry again. The first call already burned the
+ *     per-IP bucket; a second retry would just slam it harder.
+ *   - User cancels re-auth (Ctrl-C, closes browser, polls expire) →
+ *     `deviceAuthLogin` throws; we repackage as `StorystickError('Login
+ *     cancelled.')` so commands can catch + exit 1 without a stack trace.
+ *
+ * This module deliberately takes NO dependency on commander/cac/pc — it is
+ * pure transport. The CLI command layer owns all user-facing printing.
+ */
+import { type LoginOptions } from './auth-device.js';
+export interface HubApiOptions {
+    /** Binary source downloads use the same signed session and error handling. */
+    responseType?: 'json' | 'bytes';
+    /** HTTP method. Defaults to GET. */
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    /** JSON body (will be stringified). Presence flips Content-Type. */
+    body?: unknown;
+    /** Retained authority for a multi-request content operation. */
+    contentShapeCapability?: string;
+    /** Gateway base URL (no trailing slash). Tests pass a mock server. */
+    gatewayUrl?: string;
+    /** Injected `fetch`, for tests. */
+    fetchImpl?: typeof fetch;
+    /** Overrides for the inline device-auth flow when we retry. */
+    login?: LoginOptions;
+    /** Hook called once with the verification URL + userCode when a retry
+     * triggers device-auth login. The CLI uses this to print the "visit this
+     * URL / type this code" banner. */
+    onAuthPrompt?: (data: {
+        issuer: string;
+        verificationUrl: string;
+        userCode: string;
+        expiresIn: number;
+    }) => void;
+    /** Optional AbortSignal wiring (propagates into device-auth polling). */
+    signal?: AbortSignal;
+    /** Deadline applied to each Hub request. */
+    timeoutMs?: number;
+    /** Root used for `.env.local` runtime URL overrides. */
+    rootDir?: string;
+    /** Explicit test/embedding override for whether a device flow may start. */
+    interactiveAuth?: boolean;
+}
+/**
+ * Call a Hub user-scoped endpoint with automatic retry-on-401.
+ *
+ * Success path: returns the parsed JSON body.
+ * Failure path: throws `StorystickError` with a clean, user-facing message.
+ */
+export declare function callHubApi<T>(path: string, options?: HubApiOptions): Promise<T>;