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

package/dist/starter-resolver.js

@@ -0,0 +1,495 @@
+import { validateWorkspaceArchive } from '@storystick/source/archive';
+import { createHash, randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join, posix, relative, resolve, sep } from 'node:path';
+import { StorystickError, storystickErrorFromResponse } from './cli-error.js';
+import { fetchWithDeadline } from './transport.js';
+export const DEFAULT_STARTER_ID = 'minimal-next';
+export const DEFAULT_STARTER_CATALOG_URL = 'https://starters.storystick.app/catalog.json';
+export const STARTER_CATALOG_ENV = 'STORYSTICK_STARTER_CATALOG_URL';
+export const PREPARED_STARTER_DIRECTORY = join('.storystick', 'prepared-starter-v2');
+export const MATERIALIZED_STARTER_MARKER = join('.storystick', 'materialized-starter-v2');
+const STARTER_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const RELEASE_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+const INTEGRITY_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const MAX_CATALOG_BYTES = 1_000_000;
+const MAX_STARTER_FILES = 2_000;
+const MAX_STARTER_BYTES = 50_000_000;
+export async function loadStarterCatalog(options = {}) {
+    const startDir = options.startDir ?? process.cwd();
+    const explicitCatalogUrl = options.catalogUrl ?? process.env[STARTER_CATALOG_ENV];
+    if (!explicitCatalogUrl) {
+        const local = findLocalStarterCatalog(startDir);
+        if (local)
+            return readStarterCatalog(local);
+    }
+    const catalogUrl = normalizeCatalogUrl(explicitCatalogUrl ?? DEFAULT_STARTER_CATALOG_URL);
+    const source = (await fetchStarterBytes(catalogUrl, MAX_CATALOG_BYTES, options)).toString('utf8');
+    return parseStarterCatalog(source, catalogUrl);
+}
+export function readStarterCatalog(path) {
+    const source = readFileSync(path, 'utf8');
+    if (Buffer.byteLength(source) > MAX_CATALOG_BYTES) {
+        throw invalidCatalog('Starter catalog exceeds the supported size limit.');
+    }
+    return parseStarterCatalog(source, path);
+}
+export function selectStarter(catalog, requestedId) {
+    const id = requestedId?.trim() || catalog.default;
+    const entry = catalog.starters.find((candidate) => candidate.id === id);
+    if (!entry) {
+        throw new StorystickError(`Unknown starter "${id}". Available starters: ${catalog.starters
+            .map((candidate) => candidate.id)
+            .join(', ')}.`, { code: 'STARTER_NOT_FOUND', category: 'validation' });
+    }
+    return entry;
+}
+/** A required archive digest pins the bytes independently of the hosting URL. */
+export function resolveStarterSource(entry) {
+    validateArtifactIdentity(entry);
+    return normalizeCatalogUrl(entry.source.url);
+}
+export function findMonorepoRoot(startDir = process.cwd()) {
+    let directory = resolve(startDir);
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (existsSync(join(directory, 'pnpm-workspace.yaml')))
+            return directory;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+    return null;
+}
+export function findLocalStarterCatalog(startDir = process.cwd()) {
+    const root = findMonorepoRoot(startDir);
+    if (!root)
+        return null;
+    const candidate = join(root, 'starters', 'catalog.json');
+    return existsSync(candidate) && statSync(candidate).isFile()
+        ? candidate
+        : null;
+}
+export function findLocalStarter(entry, startDir = process.cwd()) {
+    validateArtifactIdentity(entry);
+    const root = findMonorepoRoot(startDir);
+    if (!root)
+        return null;
+    const candidate = join(root, 'starters', entry.localDirectory ?? entry.id);
+    return existsSync(candidate) && statSync(candidate).isDirectory()
+        ? candidate
+        : null;
+}
+/** Fetch, validate, and hash a starter before publishing any of its bytes. */
+export async function prepareStarter(options) {
+    const source = resolveStarterSource(options.entry);
+    const local = findLocalStarter(options.entry, options.startDir);
+    let verifiedLocal = null;
+    if (local) {
+        try {
+            validatePreparedStarter(local, options.entry);
+            verifiedLocal = local;
+        }
+        catch {
+            // A receipt may pin an older artifact after the monorepo starter moves.
+            // The immutable remote source remains authoritative in that case.
+        }
+    }
+    const targetDir = resolve(options.targetDir);
+    const prepared = join(targetDir, PREPARED_STARTER_DIRECTORY);
+    if (existsSync(prepared)) {
+        const manifest = validatePreparedStarter(prepared, options.entry);
+        options.onManifest?.(manifest);
+        return manifest;
+    }
+    const internal = join(targetDir, '.storystick');
+    mkdirSync(internal, { recursive: true, mode: 0o700 });
+    const temporary = join(internal, `.prepared-starter-v2-${randomUUID()}`);
+    try {
+        if (verifiedLocal) {
+            copyDirRecursive(verifiedLocal, temporary);
+        }
+        else {
+            const bytes = await fetchStarterBytes(source, MAX_STARTER_BYTES, options);
+            const files = validateWorkspaceArchive(bytes, options.entry.source.integrity.slice('sha256:'.length));
+            if (files.length > MAX_STARTER_FILES || files.reduce((sum, file) => sum + file.content.length, 0) > MAX_STARTER_BYTES)
+                throw starterTooLarge();
+            mkdirSync(temporary, { recursive: true });
+            for (const file of files) {
+                const destination = join(temporary, ...file.path.split('/'));
+                mkdirSync(dirname(destination), { recursive: true });
+                writeFileSync(destination, file.content, { flag: 'wx', mode: file.mode });
+            }
+        }
+        const manifest = validatePreparedStarter(temporary, options.entry);
+        renameSync(temporary, prepared);
+        options.onManifest?.(manifest);
+        return manifest;
+    }
+    catch (error) {
+        rmSync(temporary, { recursive: true, force: true });
+        if (existsSync(prepared)) {
+            return validatePreparedStarter(prepared, options.entry);
+        }
+        throw error;
+    }
+}
+/** Publish only previously validated bytes into a blank application tree. */
+export function ensurePreparedStarterMaterialized(targetDir, entry) {
+    const root = resolve(targetDir);
+    const prepared = join(root, PREPARED_STARTER_DIRECTORY);
+    const marker = join(root, MATERIALIZED_STARTER_MARKER);
+    const manifest = validatePreparedStarter(prepared, entry);
+    if (existsSync(marker))
+        return manifest;
+    copyDirRecursive(prepared, root);
+    const temporary = `${marker}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, 'complete\n', { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, marker);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        if (!existsSync(marker))
+            throw error;
+    }
+    return manifest;
+}
+export function readStarterManifest(starterRoot) {
+    const path = join(starterRoot, 'storystick.starter.json');
+    if (!existsSync(path)) {
+        throw new StorystickError('Starter manifest is missing.', {
+            code: 'STARTER_MANIFEST_MISSING',
+            category: 'validation',
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw invalidManifest('Starter manifest is malformed.');
+    }
+    if (!isRecord(parsed))
+        throw invalidManifest();
+    const integration = parsed.integration;
+    if (!isRecord(integration) || !isRecord(integration.fields)) {
+        throw invalidManifest();
+    }
+    const existingNext = integration.existingNext;
+    const validOverlay = parsed.framework === 'astro'
+        ? existingNext === undefined
+        : Array.isArray(existingNext) && existingNext.length > 0 && existingNext.every(isOverlayPath) &&
+            new Set(existingNext.map(mapping => mapping.from)).size === existingNext.length &&
+            new Set(existingNext.map(mapping => mapping.to)).size === existingNext.length;
+    if (parsed.version !== 2 ||
+        typeof parsed.id !== 'string' ||
+        !STARTER_ID_PATTERN.test(parsed.id) ||
+        typeof parsed.release !== 'string' ||
+        !RELEASE_PATTERN.test(parsed.release) ||
+        !((parsed.framework === 'next' && integration.contract === 'next-app-router') || (parsed.framework === 'astro' && integration.contract === 'astro-native')) ||
+        integration.version !== 1 ||
+        !Array.isArray(integration.routeStoryTypes) ||
+        integration.routeStoryTypes.length === 0 ||
+        !integration.routeStoryTypes.every(isStoryIdentifier) ||
+        typeof integration.fields.title !== 'string' ||
+        !isStoryIdentifier(integration.fields.title) ||
+        typeof integration.fields.description !== 'string' ||
+        !isStoryIdentifier(integration.fields.description) ||
+        typeof integration.fields.slices !== 'string' ||
+        !isStoryIdentifier(integration.fields.slices) ||
+        typeof integration.fields.siteSettings !== 'string' ||
+        !isStoryIdentifier(integration.fields.siteSettings) ||
+        typeof integration.fields.siteName !== 'string' ||
+        !isStoryIdentifier(integration.fields.siteName) ||
+        typeof integration.fields.siteDescription !== 'string' ||
+        !isStoryIdentifier(integration.fields.siteDescription) ||
+        !validOverlay ||
+        new Set(integration.routeStoryTypes).size !==
+            integration.routeStoryTypes.length) {
+        throw invalidManifest();
+    }
+    return parsed;
+}
+export function computeStarterIntegrity(starterRoot) {
+    const hash = createHash('sha256');
+    const files = listStarterFiles(starterRoot);
+    if (files.length > MAX_STARTER_FILES)
+        throw starterTooLarge();
+    let totalBytes = 0;
+    for (const path of files) {
+        totalBytes += lstatSync(join(starterRoot, ...path.split('/'))).size;
+        if (totalBytes > MAX_STARTER_BYTES)
+            throw starterTooLarge();
+        hash.update(path);
+        hash.update('\0');
+        hash.update(readFileSync(join(starterRoot, ...path.split('/'))));
+        hash.update('\0');
+    }
+    return `sha256:${hash.digest('hex')}`;
+}
+export function preparedStarterRoot(targetDir) {
+    return join(resolve(targetDir), PREPARED_STARTER_DIRECTORY);
+}
+function validatePreparedStarter(root, entry) {
+    const manifest = readStarterManifest(root);
+    if (manifest.id !== entry.id ||
+        manifest.release !== entry.release ||
+        manifest.framework !== entry.framework) {
+        throw new StorystickError(`Starter manifest identity does not match catalog entry "${entry.id}@${entry.release}".`, { code: 'STARTER_IDENTITY_MISMATCH', category: 'validation' });
+    }
+    const actual = computeStarterIntegrity(root);
+    if (actual !== entry.integrity) {
+        throw new StorystickError(`Starter integrity mismatch for "${entry.id}@${entry.release}".`, {
+            code: 'STARTER_INTEGRITY_MISMATCH',
+            category: 'validation',
+            payload: { expected: entry.integrity, actual },
+        });
+    }
+    return manifest;
+}
+function parseStarterCatalog(source, origin) {
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw invalidCatalog(`Starter catalog is malformed: ${origin}`);
+    }
+    if (!isRecord(parsed) ||
+        parsed.version !== 2 ||
+        typeof parsed.default !== 'string' ||
+        !Array.isArray(parsed.starters) ||
+        parsed.starters.length === 0) {
+        throw invalidCatalog();
+    }
+    const starters = parsed.starters.map(validateCatalogEntry);
+    const ids = new Set(starters.map((entry) => entry.id));
+    if (ids.size !== starters.length || !ids.has(parsed.default)) {
+        throw invalidCatalog('Starter catalog IDs must be unique and include its default.');
+    }
+    return { version: 2, default: parsed.default, starters };
+}
+function validateCatalogEntry(value) {
+    if (!isRecord(value) || !isRecord(value.source))
+        throw invalidCatalog();
+    const source = value.source;
+    if (typeof value.id !== 'string' ||
+        !STARTER_ID_PATTERN.test(value.id) ||
+        typeof value.release !== 'string' ||
+        !RELEASE_PATTERN.test(value.release) ||
+        typeof value.label !== 'string' ||
+        value.label.trim().length === 0 ||
+        typeof value.description !== 'string' ||
+        value.description.trim().length === 0 ||
+        (value.framework !== 'next' && value.framework !== 'astro') ||
+        !Array.isArray(value.capabilities) ||
+        !value.capabilities.every((capability) => typeof capability === 'string' && STARTER_ID_PATTERN.test(capability)) ||
+        source.provider !== 'archive' ||
+        typeof source.url !== 'string' ||
+        !validDistributionUrl(source.url) ||
+        typeof source.integrity !== 'string' ||
+        !INTEGRITY_PATTERN.test(source.integrity) ||
+        typeof value.integrity !== 'string' ||
+        !INTEGRITY_PATTERN.test(value.integrity) ||
+        (value.localDirectory !== undefined &&
+            (typeof value.localDirectory !== 'string' ||
+                !isSafeRelativePath(value.localDirectory)))) {
+        throw invalidCatalog();
+    }
+    return value;
+}
+function validateArtifactIdentity(entry) {
+    const source = entry?.source;
+    if (!isRecord(entry) ||
+        !isRecord(source) ||
+        !STARTER_ID_PATTERN.test(entry.id) ||
+        !RELEASE_PATTERN.test(entry.release) ||
+        (entry.framework !== 'next' && entry.framework !== 'astro') ||
+        source.provider !== 'archive' ||
+        !validDistributionUrl(source.url) ||
+        !INTEGRITY_PATTERN.test(source.integrity) ||
+        !INTEGRITY_PATTERN.test(entry.integrity) ||
+        (entry.localDirectory !== undefined &&
+            !isSafeRelativePath(entry.localDirectory))) {
+        throw new StorystickError(`Starter artifact identity is invalid for "${entry?.id ?? 'unknown'}".`, { code: 'STARTER_IDENTITY_INVALID', category: 'validation' });
+    }
+    return entry;
+}
+function normalizeCatalogUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw invalidCatalog(`${STARTER_CATALOG_ENV} must be an HTTPS URL.`);
+    }
+    if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))) || url.username || url.password || url.search || url.hash) {
+        throw invalidCatalog(`${STARTER_CATALOG_ENV} must be an HTTPS URL.`);
+    }
+    return url.href;
+}
+function validDistributionUrl(value) {
+    try {
+        normalizeCatalogUrl(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Bound headers, streamed bytes and elapsed time before parsing or writing. */
+async function fetchStarterBytes(url, maxBytes, options) {
+    const signal = AbortSignal.any([AbortSignal.timeout(15_000), ...(options.signal ? [options.signal] : [])]);
+    const response = await fetchWithDeadline(url, { redirect: 'error' }, { fetchImpl: options.fetchImpl, signal });
+    if (!response.ok)
+        throw await storystickErrorFromResponse(response);
+    if (response.url && normalizeCatalogUrl(response.url) !== normalizeCatalogUrl(url)) {
+        await response.body?.cancel();
+        throw invalidCatalog('Starter distribution must not redirect.');
+    }
+    if (Number(response.headers.get('content-length')) > maxBytes || !response.body) {
+        await response.body?.cancel();
+        throw starterTooLarge();
+    }
+    const reader = response.body.getReader();
+    const cancel = () => { void reader.cancel().catch(() => { }); };
+    signal.addEventListener('abort', cancel, { once: true });
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const chunk = await reader.read();
+            signal.throwIfAborted();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > maxBytes)
+                throw starterTooLarge();
+            chunks.push(chunk.value);
+        }
+        return Buffer.concat(chunks, size);
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        await reader.cancel();
+    }
+}
+function invalidManifest(message = 'Starter manifest must use a supported Next or Astro integration contract V2.') {
+    return new StorystickError(message, {
+        code: 'STARTER_MANIFEST_INVALID',
+        category: 'validation',
+    });
+}
+function invalidCatalog(message = 'Starter catalog does not match the supported V1 contract.') {
+    return new StorystickError(message, {
+        code: 'STARTER_CATALOG_INVALID',
+        category: 'validation',
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStoryIdentifier(value) {
+    return typeof value === 'string' && /^[A-Za-z][A-Za-z0-9]*$/u.test(value);
+}
+function isOverlayPath(value) {
+    return (isRecord(value) &&
+        typeof value.from === 'string' &&
+        value.from !== '.' &&
+        isSafeRelativePath(value.from) &&
+        typeof value.to === 'string' &&
+        isSafeRelativePath(value.to) &&
+        (value.to === 'stories' || value.to.startsWith('components/')));
+}
+function isSafeRelativePath(value) {
+    if (!value || value.includes('\\'))
+        return false;
+    const normalized = posix.normalize(value);
+    return (normalized === value &&
+        !normalized.startsWith('../') &&
+        normalized !== '..' &&
+        !normalized.startsWith('/') &&
+        !normalized.includes('/../'));
+}
+export function listStarterFiles(root) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory).sort()) {
+            if (ignoredStarterEntry(entry))
+                continue;
+            const absolute = join(directory, entry);
+            const status = lstatSync(absolute);
+            if (status.isSymbolicLink())
+                throw unsafeStarterArtifact(absolute);
+            if (status.isDirectory())
+                visit(absolute);
+            else if (status.isFile()) {
+                files.push(relative(root, absolute).split(sep).join('/'));
+            }
+        }
+    };
+    visit(resolve(root));
+    return files.sort();
+}
+export function copyDirRecursive(source, destination) {
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(source)) {
+        if (ignoredStarterEntry(entry))
+            continue;
+        const from = join(source, entry);
+        const to = join(destination, entry);
+        const status = lstatSync(from);
+        if (status.isSymbolicLink())
+            throw unsafeStarterArtifact(from);
+        if (status.isDirectory()) {
+            if (existsSync(to)) {
+                const destinationStatus = lstatSync(to);
+                if (destinationStatus.isSymbolicLink() ||
+                    !destinationStatus.isDirectory()) {
+                    throw starterCollision(to);
+                }
+            }
+            copyDirRecursive(from, to);
+            continue;
+        }
+        if (!status.isFile())
+            continue;
+        if (existsSync(to)) {
+            const destinationStatus = lstatSync(to);
+            if (destinationStatus.isSymbolicLink() ||
+                !destinationStatus.isFile()) {
+                throw starterCollision(to);
+            }
+            if (readFileSync(to).equals(readFileSync(from)))
+                continue;
+            throw starterCollision(to);
+        }
+        copyFileSync(from, to);
+    }
+}
+function ignoredStarterEntry(entry) {
+    return [
+        'node_modules',
+        '.next',
+        '_generated',
+        '.env.local',
+        'generated',
+        'convex',
+        '.git',
+        '.storystick',
+    ].includes(entry);
+}
+function starterCollision(path) {
+    return new StorystickError(`Starter refuses to overwrite existing path: ${path}`, { code: 'STARTER_TARGET_COLLISION', category: 'conflict' });
+}
+function unsafeStarterArtifact(path) {
+    return new StorystickError(`Starter contains an unsupported link: ${path}`, {
+        code: 'STARTER_ARTIFACT_UNSAFE',
+        category: 'validation',
+    });
+}
+function starterTooLarge() {
+    return new StorystickError(`Starter exceeds ${MAX_STARTER_FILES} files or ${MAX_STARTER_BYTES} bytes.`, { code: 'STARTER_ARTIFACT_TOO_LARGE', category: 'validation' });
+}

package/dist/sync-transaction.d.ts

@@ -0,0 +1,29 @@
+import type { SchemaPushResult } from './push-client.js';
+type SyncPushResult = Omit<SchemaPushResult, 'projectionSeq'> & {
+    projectionSeq?: number;
+};
+export interface SyncOperationReceipt {
+    version: 1;
+    target?: string;
+    state: 'prepared' | 'pushed';
+    rootDir: string;
+    outputDirectory: string;
+    schemaVersion: string;
+    generationId: string;
+    storyCount: number;
+    pushResult?: SyncPushResult;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare function readSyncOperation(rootDir: string): SyncOperationReceipt | null;
+export declare function writePreparedSyncOperation(args: {
+    rootDir: string;
+    outputDirectory: string;
+    schemaVersion: string;
+    generationId: string;
+    storyCount: number;
+    target?: string;
+}): SyncOperationReceipt;
+export declare function markSyncOperationPushed(receipt: SyncOperationReceipt, pushResult: SyncPushResult): SyncOperationReceipt;
+export declare function clearSyncOperation(rootDir: string): void;
+export {};

package/dist/sync-transaction.js

@@ -0,0 +1,159 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const SYNC_RECEIPT_PATH = join('.storystick', 'sync-operation.json');
+export function readSyncOperation(rootDir) {
+    const path = receiptPath(rootDir);
+    if (!existsSync(path))
+        return null;
+    const source = readFileSync(path, 'utf8');
+    assertSecretFree(source);
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new Error('Sync operation receipt is invalid.');
+    }
+    if (!isReceipt(parsed) ||
+        resolve(parsed.rootDir) !== resolve(rootDir) ||
+        (parsed.state === 'pushed' &&
+            parsed.pushResult?.version !== parsed.schemaVersion)) {
+        throw new Error('Sync operation receipt is invalid.');
+    }
+    return parsed;
+}
+export function writePreparedSyncOperation(args) {
+    const existing = readSyncOperation(args.rootDir);
+    if (existing?.state === 'pushed') {
+        throw new Error('A pushed schema is waiting for its local generation commit. Resume sync first.');
+    }
+    const now = Date.now();
+    const receipt = {
+        version: 1,
+        state: 'prepared',
+        ...(args.target ? { target: args.target } : {}),
+        rootDir: resolve(args.rootDir),
+        outputDirectory: resolve(args.outputDirectory),
+        schemaVersion: args.schemaVersion,
+        generationId: args.generationId,
+        storyCount: args.storyCount,
+        createdAt: existing?.schemaVersion === args.schemaVersion &&
+            existing.generationId === args.generationId
+            ? existing.createdAt
+            : now,
+        updatedAt: now,
+    };
+    writeReceipt(receipt);
+    return receipt;
+}
+export function markSyncOperationPushed(receipt, pushResult) {
+    if (pushResult.version !== receipt.schemaVersion) {
+        throw new Error('Schema push result does not match the prepared sync.');
+    }
+    const next = {
+        ...receipt,
+        state: 'pushed',
+        pushResult,
+        updatedAt: Date.now(),
+    };
+    writeReceipt(next);
+    return next;
+}
+export function clearSyncOperation(rootDir) {
+    rmSync(receiptPath(rootDir), { force: true });
+}
+function receiptPath(rootDir) {
+    return join(resolve(rootDir), SYNC_RECEIPT_PATH);
+}
+function writeReceipt(receipt) {
+    const path = receiptPath(receipt.rootDir);
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const serialized = `${JSON.stringify(receipt, null, 2)}\n`;
+    assertSecretFree(serialized);
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    let handle;
+    try {
+        handle = openSync(temporary, 'wx', 0o600);
+        writeFileSync(handle, serialized, 'utf8');
+        fsyncSync(handle);
+        closeSync(handle);
+        handle = undefined;
+        renameSync(temporary, path);
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        if (handle !== undefined)
+            closeSync(handle);
+        try {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+        catch {
+            // Preserve the original write failure.
+        }
+        throw error;
+    }
+}
+function isReceipt(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const receipt = value;
+    const allowedKeys = new Set([
+        'target',
+        'version',
+        'state',
+        'rootDir',
+        'outputDirectory',
+        'schemaVersion',
+        'generationId',
+        'storyCount',
+        'pushResult',
+        'createdAt',
+        'updatedAt',
+    ]);
+    return (Object.keys(receipt).every((key) => allowedKeys.has(key)) &&
+        receipt.version === 1 &&
+        (receipt.target === undefined || typeof receipt.target === 'string') &&
+        (receipt.state === 'prepared' || receipt.state === 'pushed') &&
+        typeof receipt.rootDir === 'string' &&
+        typeof receipt.outputDirectory === 'string' &&
+        typeof receipt.schemaVersion === 'string' &&
+        /^g-[a-f0-9]{24}$/u.test(String(receipt.generationId)) &&
+        typeof receipt.storyCount === 'number' &&
+        Number.isSafeInteger(receipt.storyCount) &&
+        typeof receipt.createdAt === 'number' &&
+        typeof receipt.updatedAt === 'number' &&
+        (receipt.state !== 'pushed' || isPushResult(receipt.pushResult)));
+}
+function isPushResult(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const result = value;
+    if ((result.status !== 'pushed' && result.status !== 'unchanged') ||
+        typeof result.version !== 'string' ||
+        !Array.isArray(result.newBindingNotes)) {
+        return false;
+    }
+    if (!result.newBindingNotes.every((note) => typeof note === 'object' &&
+        note !== null &&
+        !Array.isArray(note) &&
+        ['docType', 'sliceType', 'sliceField', 'sourcePath', 'message'].every((key) => typeof note[key] === 'string'))) {
+        return false;
+    }
+    const recommendation = result.recommendBackfill;
+    return recommendation === undefined || (typeof recommendation === 'object' &&
+        recommendation !== null &&
+        !Array.isArray(recommendation) &&
+        typeof recommendation.command === 'string' &&
+        typeof recommendation.reason === 'string');
+}
+function assertSecretFree(serialized) {
+    if (/ss_(?:sk|pk)_(?:live|test)_/u.test(serialized) ||
+        /"(?:apiKey|publishableKey|token)"\s*:/u.test(serialized)) {
+        throw new Error('Refusing to persist secrets in sync receipt.');
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+export interface FetchWithDeadlineOptions {
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export declare function fetchWithDeadline(input: string | URL | Request, init?: RequestInit, options?: FetchWithDeadlineOptions): Promise<Response>;
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;