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

package/dist/init-operation.js

@@ -0,0 +1,427 @@
+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';
+import { StorystickError } from './cli-error.js';
+import { redactProjectSecrets } from './project-connection.js';
+import { MATERIALIZED_STARTER_MARKER, PREPARED_STARTER_DIRECTORY, } from './starter-resolver.js';
+export const INIT_OPERATION_RELATIVE_PATH = join('.storystick', 'init-operation.json');
+export const INIT_PHASES = [
+    'P0',
+    'P1',
+    'P2',
+    'P3',
+    'P4',
+    'P5',
+    'P6',
+    'P7',
+    'P8',
+    'P9',
+    'P10',
+];
+export class InitOrchestrationError extends StorystickError {
+    receipt;
+    resumeCommand;
+    constructor(cause, receipt) {
+        const status = receipt.outcome === 'partial' ? 'partial' : 'failed';
+        const resumeCommand = initResumeCommand(receipt);
+        const message = redactProjectSecrets(cause instanceof Error ? cause.message : String(cause));
+        super(`Initialization ${status} at ${receipt.phase}: ${message}\nResume with: ${resumeCommand}`, {
+            code: receipt.outcome === 'partial'
+                ? 'INIT_PARTIAL'
+                : 'INIT_LOCAL_PREPARATION_FAILED',
+            category: 'system',
+            recoverable: true,
+            payload: { outcome: receipt.outcome, receipt, resumeCommand },
+        });
+        this.name = 'InitOrchestrationError';
+        this.receipt = receipt;
+        this.resumeCommand = resumeCommand;
+    }
+}
+export async function runInitOrchestrator(args) {
+    let receipt = openInitOperation(args.identity, args.operationId);
+    let prepared;
+    const run = async (phase, work) => {
+        if (receipt.phases[phase] === 'complete')
+            return;
+        receipt = updateReceipt(receipt, { phase, outcome: 'running' });
+        try {
+            const patch = await work();
+            receipt = updateReceipt(receipt, {
+                ...patch,
+                phase,
+                outcome: 'running',
+                phases: { ...receipt.phases, [phase]: 'complete' },
+            });
+        }
+        catch (error) {
+            const index = INIT_PHASES.indexOf(phase);
+            receipt = updateReceipt(receipt, {
+                phase,
+                outcome: index <= INIT_PHASES.indexOf('P3') ? 'failed' : 'partial',
+                phases: { ...receipt.phases, [phase]: 'failed' },
+            });
+            throw new InitOrchestrationError(error, receipt);
+        }
+    };
+    await run('P1', () => args.dependencies.planLocal(receipt));
+    await run('P2', () => args.dependencies.materializeAndInstall(receipt));
+    // A prepared generation is deliberately ephemeral. Recompute it before
+    // resuming any unfinished P7/P8 work, and always before auth/remote work.
+    if (receipt.phases.P8 !== 'complete') {
+        await run('P3', async () => {
+            prepared = await args.dependencies.prepareGeneration(receipt);
+        });
+        if (prepared === undefined) {
+            try {
+                prepared = await args.dependencies.prepareGeneration(receipt);
+            }
+            catch (error) {
+                receipt = updateReceipt(receipt, {
+                    phase: 'P3',
+                    outcome: 'failed',
+                    phases: { ...receipt.phases, P3: 'failed' },
+                });
+                throw new InitOrchestrationError(error, receipt);
+            }
+        }
+    }
+    await run('P4', async () => args.dependencies.authorizeAndSelect(receipt));
+    if (receipt.phases.P6 !== 'complete') {
+        let recovered = false;
+        if (receipt.projectShortId && receipt.keyPairVersion) {
+            try {
+                recovered = await args.dependencies.recoverCommittedConnection(receipt);
+            }
+            catch (error) {
+                receipt = updateReceipt(receipt, {
+                    phase: 'P6',
+                    outcome: 'partial',
+                    phases: { ...receipt.phases, P6: 'failed' },
+                });
+                throw new InitOrchestrationError(error, receipt);
+            }
+        }
+        if (recovered) {
+            receipt = updateReceipt(receipt, {
+                phase: 'P6',
+                outcome: 'running',
+                phases: { ...receipt.phases, P5: 'complete', P6: 'complete' },
+            });
+        }
+        else {
+            let bootstrap;
+            await run('P5', async () => {
+                bootstrap = await args.dependencies.prepareBootstrap(receipt);
+                return bootstrap.receiptPatch;
+            });
+            // P5 must be replayed on a fresh process when P6 is incomplete because
+            // its one-time cleartext response is intentionally absent from disk.
+            if (!bootstrap) {
+                try {
+                    bootstrap = await args.dependencies.prepareBootstrap(receipt);
+                    receipt = updateReceipt(receipt, bootstrap.receiptPatch);
+                }
+                catch (error) {
+                    receipt = updateReceipt(receipt, {
+                        phase: 'P5',
+                        outcome: 'partial',
+                        phases: { ...receipt.phases, P5: 'failed' },
+                    });
+                    throw new InitOrchestrationError(error, receipt);
+                }
+            }
+            await run('P6', () => args.dependencies.commitConnection(receipt, bootstrap));
+        }
+    }
+    if (receipt.phases.P7 !== 'complete') {
+        if (prepared === undefined) {
+            throw new InitOrchestrationError(new Error('Prepared generation is unavailable.'), receipt);
+        }
+        await run('P7', async () => args.dependencies.pushSchema(receipt, prepared));
+    }
+    if (receipt.phases.P8 !== 'complete') {
+        if (prepared === undefined) {
+            throw new InitOrchestrationError(new Error('Prepared generation is unavailable.'), receipt);
+        }
+        await run('P8', () => args.dependencies.commitGeneration(receipt, prepared));
+    }
+    await run('P9', () => args.dependencies.acknowledge(receipt));
+    if (receipt.phases.P10 !== 'complete' && receipt.phases.P10 !== 'skipped') {
+        try {
+            await args.dependencies.initializeGit(receipt);
+            receipt = updateReceipt(receipt, {
+                phase: 'P10',
+                phases: { ...receipt.phases, P10: 'complete' },
+            });
+        }
+        catch {
+            receipt = updateReceipt(receipt, {
+                phase: 'P10',
+                phases: { ...receipt.phases, P10: 'skipped' },
+            });
+        }
+    }
+    receipt = updateReceipt(receipt, { outcome: 'complete' });
+    removeInitOperation(receipt.targetDir);
+    return receipt;
+}
+export function openInitOperation(identity, operationId = randomUUID()) {
+    const normalized = {
+        ...identity,
+        targetDir: resolve(identity.targetDir),
+    };
+    const path = receiptPath(normalized.targetDir);
+    if (existsSync(path)) {
+        const receipt = parseReceipt(readFileSync(path, 'utf8'));
+        if (stableIdentity(receipt) !== stableIdentity(normalized)) {
+            throw new StorystickError(`An incompatible initialization is already pending in ${normalized.targetDir}.`, {
+                code: 'INIT_INTENT_MISMATCH',
+                category: 'conflict',
+                recoverable: true,
+                payload: { receipt, resumeCommand: initResumeCommand(receipt) },
+            });
+        }
+        return receipt;
+    }
+    const now = Date.now();
+    const phases = Object.fromEntries(INIT_PHASES.map((phase) => [
+        phase,
+        phase === 'P0' ? 'complete' : 'pending',
+    ]));
+    const receipt = {
+        version: 1,
+        operationId,
+        ...normalized,
+        phase: 'P0',
+        outcome: 'running',
+        phases,
+        createdAt: now,
+        updatedAt: now,
+    };
+    writeReceipt(receipt);
+    return receipt;
+}
+export function readInitOperation(targetDir) {
+    const path = receiptPath(targetDir);
+    return existsSync(path) ? parseReceipt(readFileSync(path, 'utf8')) : null;
+}
+export function initResumeCommand(receipt) {
+    const into = shellQuote(receipt.targetDir);
+    const origin = receipt.originMode === 'append' && receipt.origins[0]
+        ? ` --origin ${shellQuote(receipt.origins[0])}`
+        : '';
+    const force = receipt.force ? ' --force' : '';
+    const starter = ` --starter ${shellQuote(receipt.starter.id)}`;
+    const locale = ` --locale ${shellQuote(receipt.locale)}`;
+    const siteUrl = receipt.siteUrl
+        ? ` --site-url ${shellQuote(receipt.siteUrl)}`
+        : '';
+    if (receipt.intent.kind === 'link') {
+        return `storystick init --link ${receipt.intent.requestedShortId} --into ${into}${starter}${locale}${siteUrl}${origin}${force}`;
+    }
+    const team = receipt.intent.requestedTeamShortId
+        ? ` --team ${receipt.intent.requestedTeamShortId}`
+        : receipt.intent.requestedNewTeamName ? ` --new-team ${shellQuote(receipt.intent.requestedNewTeamName)}` : '';
+    return `storystick init ${shellQuote(receipt.intent.projectName)} --into ${into}${team}${starter}${locale}${siteUrl}${origin}${force}`;
+}
+function updateReceipt(receipt, patch) {
+    const next = { ...receipt, ...patch, updatedAt: Date.now() };
+    writeReceipt(next);
+    return next;
+}
+function removeInitOperation(targetDir) {
+    rmSync(receiptPath(targetDir), { force: true });
+    rmSync(join(resolve(targetDir), PREPARED_STARTER_DIRECTORY), {
+        recursive: true,
+        force: true,
+    });
+    rmSync(join(resolve(targetDir), MATERIALIZED_STARTER_MARKER), {
+        force: true,
+    });
+}
+function receiptPath(targetDir) {
+    return join(resolve(targetDir), INIT_OPERATION_RELATIVE_PATH);
+}
+function writeReceipt(receipt) {
+    const path = receiptPath(receipt.targetDir);
+    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 parseReceipt(source) {
+    assertSecretFree(source);
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new StorystickError('The init operation receipt is malformed.', {
+            code: 'INIT_RECEIPT_INVALID',
+            category: 'validation',
+        });
+    }
+    if (!isValidReceipt(value)) {
+        throw new StorystickError('The init operation receipt is unsupported.', {
+            code: 'INIT_RECEIPT_INVALID',
+            category: 'validation',
+        });
+    }
+    return value;
+}
+function isValidReceipt(value) {
+    if (!isRecord(value))
+        return false;
+    const phases = value.phases;
+    const allowedKeys = new Set([
+        'version',
+        'operationId',
+        'targetDir',
+        'intent',
+        'strategy',
+        'starter',
+        'origins',
+        'originMode',
+        'locale',
+        'siteUrl',
+        'force',
+        'phase',
+        'outcome',
+        'phases',
+        'projectShortId',
+        'projectName',
+        'selectedTeam',
+        'newTeamName',
+        'projectionSeq',
+        'endpoint',
+        'keyPairVersion',
+        'schemaVersion',
+        'createdAt',
+        'updatedAt',
+    ]);
+    if (Object.keys(value).some((key) => !allowedKeys.has(key)))
+        return false;
+    if (value.version !== 1 ||
+        typeof value.operationId !== 'string' ||
+        value.operationId.length === 0 ||
+        typeof value.targetDir !== 'string' ||
+        !isIntent(value.intent) ||
+        (value.strategy !== 'starter' && value.strategy !== 'existing-next') ||
+        !isRecord(value.starter) ||
+        value.starter.catalogVersion !== 2 ||
+        typeof value.starter.id !== 'string' ||
+        typeof value.starter.release !== 'string' ||
+        (value.starter.framework !== 'next' && value.starter.framework !== 'astro') ||
+        (value.strategy === 'existing-next' && value.starter.framework !== 'next') ||
+        !isRecord(value.starter.source) ||
+        value.starter.source.provider !== 'archive' ||
+        typeof value.starter.source.url !== 'string' ||
+        typeof value.starter.source.integrity !== 'string' ||
+        typeof value.starter.integrity !== 'string' ||
+        (value.starter.localDirectory !== undefined &&
+            typeof value.starter.localDirectory !== 'string') ||
+        !Array.isArray(value.origins) ||
+        !value.origins.every((origin) => typeof origin === 'string') ||
+        (value.originMode !== 'append' &&
+            value.originMode !== 'default-if-empty') ||
+        typeof value.locale !== 'string' ||
+        (value.siteUrl !== undefined && typeof value.siteUrl !== 'string') ||
+        typeof value.force !== 'boolean' ||
+        !INIT_PHASES.includes(value.phase) ||
+        !['running', 'partial', 'failed', 'complete'].includes(String(value.outcome)) ||
+        !isRecord(phases) ||
+        !INIT_PHASES.every((phase) => ['pending', 'complete', 'failed', 'skipped'].includes(String(isRecord(phases) ? phases[phase] : undefined))) ||
+        typeof value.createdAt !== 'number' ||
+        typeof value.updatedAt !== 'number') {
+        return false;
+    }
+    if ((value.projectShortId !== undefined &&
+        (typeof value.projectShortId !== 'string' ||
+            !/^[0-9a-hjkmnp-tv-z]{8}$/u.test(value.projectShortId))) ||
+        (value.projectName !== undefined &&
+            typeof value.projectName !== 'string') ||
+        (value.endpoint !== undefined && typeof value.endpoint !== 'string') ||
+        (value.keyPairVersion !== undefined &&
+            (typeof value.keyPairVersion !== 'number' ||
+                !Number.isSafeInteger(value.keyPairVersion) ||
+                value.keyPairVersion < 1)) ||
+        (value.schemaVersion !== undefined &&
+            typeof value.schemaVersion !== 'string')) {
+        return false;
+    }
+    if (value.newTeamName !== undefined && typeof value.newTeamName !== 'string')
+        return false;
+    if (value.projectionSeq !== undefined && (!Number.isSafeInteger(value.projectionSeq) || value.projectionSeq < 0))
+        return false;
+    if (value.selectedTeam !== undefined) {
+        if (!isRecord(value.selectedTeam) ||
+            typeof value.selectedTeam.shortId !== 'string' ||
+            typeof value.selectedTeam.name !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}
+function isIntent(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind === 'create') {
+        return (typeof value.projectName === 'string' &&
+            (value.requestedTeamShortId === undefined ||
+                typeof value.requestedTeamShortId === 'string') &&
+            (value.requestedNewTeamName === undefined || typeof value.requestedNewTeamName === 'string'));
+    }
+    return value.kind === 'link' && typeof value.requestedShortId === 'string';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertSecretFree(serialized) {
+    if (/ss_(?:sk|pk)_(?:live|test)_/u.test(serialized) ||
+        /"(?:apiKey|publishableKey)"\s*:/u.test(serialized)) {
+        throw new StorystickError('Refusing to persist secrets in init receipt.', {
+            code: 'INIT_RECEIPT_SECRET',
+            category: 'system',
+        });
+    }
+}
+function stableIdentity(identity) {
+    return JSON.stringify({
+        targetDir: resolve(identity.targetDir),
+        intent: identity.intent,
+        strategy: identity.strategy,
+        starter: identity.starter,
+        origins: identity.origins,
+        originMode: identity.originMode,
+        locale: identity.locale,
+        siteUrl: identity.siteUrl,
+        force: identity.force,
+    });
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/init-readiness.d.ts

@@ -0,0 +1,10 @@
+/** Bounded readback of the receipt's causal checkpoint. Never repeats a remote write. */
+export declare function waitForProjection(args: {
+    endpoint: string;
+    token: string;
+    version: string;
+    seq: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<void>;

package/dist/init-readiness.js

@@ -0,0 +1,50 @@
+import { StorystickError } from './cli-error.js';
+/** Bounded readback of the receipt's causal checkpoint. Never repeats a remote write. */
+export async function waitForProjection(args) {
+    if (!Number.isSafeInteger(args.seq))
+        throw new StorystickError('The schema projection checkpoint is missing. Resume schema synchronization.', { code: 'INIT_CHECKPOINT_MISSING', category: 'system' });
+    const deadline = Date.now() + (args.timeoutMs ?? 60_000);
+    while (Date.now() < deadline) {
+        args.signal?.throwIfAborted();
+        const response = await (args.fetchImpl ?? fetch)(new URL('/api/m/operations/content-plane/readiness', args.endpoint), {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${args.token}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ version: args.version, seq: args.seq }),
+            signal: args.signal
+                ? AbortSignal.any([
+                    args.signal,
+                    AbortSignal.timeout(Math.max(1, Math.min(10_000, deadline - Date.now()))),
+                ])
+                : AbortSignal.timeout(Math.max(1, Math.min(10_000, deadline - Date.now()))),
+        });
+        if (!response.ok)
+            throw new StorystickError(`Projection verification failed (${response.status}). Resume init to retry.`, { code: 'INIT_PROJECTION_UNAVAILABLE', category: 'system' });
+        const { status } = (await response.json());
+        if (status === 'ready')
+            return;
+        if (status === 'superseded')
+            throw new StorystickError('The project schema changed during setup. Synchronize the intended schema before resuming.', { code: 'INIT_SCHEMA_SUPERSEDED', category: 'conflict' });
+        if (status === 'failed')
+            break;
+        await new Promise((resolve, reject) => {
+            const finish = () => {
+                clearTimeout(timer);
+                args.signal?.removeEventListener('abort', abort);
+                resolve();
+            };
+            const abort = () => {
+                clearTimeout(timer);
+                args.signal?.removeEventListener('abort', abort);
+                reject(args.signal?.reason);
+            };
+            const timer = setTimeout(finish, Math.min(1000, Math.max(1, deadline - Date.now())));
+            args.signal?.addEventListener('abort', abort, { once: true });
+            if (args.signal?.aborted)
+                abort();
+        });
+    }
+    throw new StorystickError('The project and connection were created, but its content projection is not ready. Resume init when the Content Plane is available.', { code: 'INIT_PROJECTION_NOT_READY', category: 'system' });
+}

package/dist/init-scaffold.d.ts

@@ -0,0 +1,54 @@
+import type { StarterManifest } from './starter-resolver.js';
+type ScaffoldStatus = 'create' | 'update' | 'overwrite' | 'skip';
+export interface InitScaffoldPlan {
+    readonly rootDir: string;
+    readonly appDir: string;
+    readonly componentsDir: string;
+    readonly actions: readonly InitScaffoldAction[];
+}
+export type InitScaffoldAction = InitScaffoldFileAction | InitScaffoldPackageAction | InitScaffoldGitignoreAction | InitScaffoldDeleteAction;
+export interface InitScaffoldFileAction {
+    readonly kind: 'file';
+    readonly path: string;
+    readonly status: ScaffoldStatus;
+    readonly content: string;
+    readonly reason?: string;
+    readonly critical?: boolean;
+}
+export interface InitScaffoldPackageAction {
+    readonly kind: 'package';
+    readonly path: 'package.json';
+    readonly status: Extract<ScaffoldStatus, 'create' | 'update' | 'skip'>;
+    readonly content: string;
+    readonly reason?: string;
+    readonly critical?: boolean;
+}
+export interface InitScaffoldGitignoreAction {
+    readonly kind: 'gitignore';
+    readonly path: '.gitignore';
+    readonly status: Extract<ScaffoldStatus, 'create' | 'update' | 'skip'>;
+    readonly content: string;
+    readonly reason?: string;
+}
+export interface InitScaffoldDeleteAction {
+    readonly kind: 'delete';
+    readonly path: string;
+    readonly status: 'delete';
+    readonly reason: string;
+}
+export interface PlanInitScaffoldOptions {
+    readonly rootDir: string;
+    readonly starterRoot: string;
+    readonly manifest: StarterManifest;
+    readonly force?: boolean;
+}
+export declare function isNextProject(rootDir: string): boolean;
+export declare function planInitScaffold({ rootDir, starterRoot, manifest, force, }: PlanInitScaffoldOptions): InitScaffoldPlan;
+export declare function assertInitScaffoldReady(plan: InitScaffoldPlan): void;
+export declare function writeInitScaffold(plan: InitScaffoldPlan): void;
+export declare function summarizeInitScaffold(plan: InitScaffoldPlan): {
+    readonly changed: number;
+    readonly skipped: readonly InitScaffoldAction[];
+};
+export declare function renderKernelAsset(asset: string, manifest: StarterManifest): string;
+export {};