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

package/dist/commands/setup.js

@@ -0,0 +1,58 @@
+import { resolve } from "node:path";
+import { inspectSetup } from "../setup.js";
+import { callHubApi } from "../hub-client.js";
+import { resolveCliRuntimeConfig } from "../runtime-config.js";
+import { shellQuote } from "../init-operation.js";
+import { StorystickError } from "../cli-error.js";
+import { configureOutput, emitJsonResult, exitJsonFailure, exitWithError, getOutputMode, logMessage, withInterrupt, } from "../output.js";
+export async function runSetup(options) {
+    configureOutput({ json: options.json === true });
+    const { signal, dispose } = withInterrupt();
+    try {
+        const root = resolve(options.root ?? ".");
+        const local = inspectSetup(root);
+        const projectShortId = options.project ?? local.connection?.projectShortId;
+        if (options.remote && !projectShortId)
+            throw new StorystickError("Connect a project or pass --project <shortId> to inspect its remote setup.", {
+                code: "PROJECT_NOT_CONNECTED",
+                category: "validation",
+                retryable: false,
+            });
+        const remote = options.remote
+            ? await callHubApi("/api/cli/project-setup", {
+                rootDir: root,
+                gatewayUrl: resolveCliRuntimeConfig({ rootDir: root }).gatewayUrl,
+                method: "POST",
+                body: { projectShortId },
+                signal,
+                interactiveAuth: false,
+            })
+            : null;
+        const data = { ...local, remote };
+        if (getOutputMode() === "json")
+            emitJsonResult({ command: "setup", ok: true, data });
+        else {
+            logMessage(`Project: ${projectShortId ?? "not connected"}`);
+            logMessage(`Website: ${local.application.framework ?? "not detected"}`);
+            logMessage(`Source: ${local.source.configured ? "configured locally" : "not configured"}`);
+            if (local.repository?.dirty)
+                logMessage("Local changes are present. Source transfer uses committed files only.");
+            if (local.hosting)
+                logMessage(`Hosting: Vercel ${local.hosting.projectId} (local link; access not verified)`);
+            for (const issue of local.issues)
+                logMessage(`${issue.path}: ${issue.message}`);
+            for (const step of local.next)
+                logMessage(`${step.reason}\n  ${step.command} ${step.args.map((arg) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : shellQuote(arg))).join(" ")}`);
+            if (remote)
+                logMessage(JSON.stringify(remote, null, 2));
+        }
+    }
+    catch (err) {
+        if (getOutputMode() === "json")
+            exitJsonFailure({ command: "setup", err });
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+}

package/dist/commands/slice-previews.d.ts

@@ -0,0 +1,17 @@
+export type SlicePreviewManifestEntry = {
+    sliceType: string;
+    variationId?: string;
+    file: string;
+};
+export interface SlicePreviewSyncOptions {
+    root?: string;
+    manifest?: string;
+    projectShortId?: string;
+    dryRun?: boolean;
+    json?: boolean;
+    quiet?: boolean;
+    verbose?: boolean;
+    fetchImpl?: typeof fetch;
+}
+export declare function runSlicePreviewsSync(options?: SlicePreviewSyncOptions): Promise<void>;
+export declare function readSlicePreviewManifest(manifestPath: string): Promise<SlicePreviewManifestEntry[]>;

package/dist/commands/slice-previews.js

@@ -0,0 +1,233 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { basename, relative, resolve, sep } from 'node:path';
+import { StorystickError } from '../cli-error.js';
+import { callHubApi } from '../hub-client.js';
+import { configureOutput, emitJsonResult, exitJsonFailure, exitWithError, getOutputMode, logFinishedStep, logMessage, logWarning, withInterrupt, } from '../output.js';
+import { requireProjectConnection } from '../project-connection.js';
+import { fetchWithDeadline } from '../transport.js';
+export async function runSlicePreviewsSync(options = {}) {
+    configureOutput({
+        json: options.json === true,
+        quiet: options.quiet === true,
+        verbose: options.verbose === true,
+    });
+    const { signal, dispose } = withInterrupt();
+    try {
+        const rootDir = resolve(options.root ?? '.');
+        const canonicalRootDir = await realpath(rootDir);
+        const manifestPath = resolve(rootDir, options.manifest ?? 'slice-previews.json');
+        const projectShortId = options.projectShortId?.trim() ||
+            requireProjectConnection(rootDir).shortId;
+        const entries = await readSlicePreviewManifest(manifestPath);
+        const planned = await Promise.all(entries.map(async (entry) => {
+            const requestedFilePath = resolve(rootDir, entry.file);
+            const filePath = await realpath(requestedFilePath);
+            const pathFromRoot = relative(canonicalRootDir, filePath);
+            if (pathFromRoot === '..' ||
+                pathFromRoot.startsWith(`..${sep}`) ||
+                resolve(canonicalRootDir, pathFromRoot) !== filePath) {
+                throw new StorystickError(`Slice capture must stay inside the project root: ${entry.file}`, { code: 'SLICE_PREVIEW_PATH_OUTSIDE_ROOT' });
+            }
+            const bytes = new Uint8Array(await readFile(filePath));
+            return {
+                ...entry,
+                filePath,
+                bytes,
+                mimeType: mimeTypeForPath(filePath),
+                checksum: createHash('sha256').update(bytes).digest('hex'),
+            };
+        }));
+        if (options.dryRun === true) {
+            const data = {
+                status: 'planned',
+                projectShortId,
+                manifest: manifestPath,
+                total: planned.length,
+                items: planned.map(({ bytes: _bytes, filePath, checksum, ...entry }) => ({
+                    ...entry,
+                    file: filePath,
+                    checksum,
+                })),
+            };
+            if (getOutputMode() === 'json') {
+                emitJsonResult({ command: 'slice-previews sync', ok: true, data });
+            }
+            else {
+                logFinishedStep(`Validated ${planned.length} slice capture(s); no upload performed.`);
+            }
+            return;
+        }
+        const results = [];
+        for (const item of planned) {
+            const begun = await callHubApi('/api/cli/slice-previews/begin-upload', {
+                method: 'POST',
+                body: {
+                    projectShortId,
+                    sliceType: item.sliceType,
+                    ...(item.variationId !== undefined
+                        ? { variationId: item.variationId }
+                        : {}),
+                    originalFilename: basename(item.filePath),
+                    declaredMimeType: item.mimeType,
+                    declaredSizeBytes: item.bytes.byteLength,
+                    declaredChecksum: item.checksum,
+                },
+                rootDir,
+                signal,
+                fetchImpl: options.fetchImpl,
+            });
+            if (begun.status === 'unchanged') {
+                results.push({
+                    sliceType: item.sliceType,
+                    ...(item.variationId !== undefined
+                        ? { variationId: item.variationId }
+                        : {}),
+                    status: 'unchanged',
+                });
+                continue;
+            }
+            if (typeof begun.contentShapeCapability !== 'string' ||
+                !begun.contentShapeCapability.trim()) {
+                throw new StorystickError('The upload response is missing its content-shape capability. Restart the sync.', {
+                    code: 'CONTENT_SHAPE_RELOAD_REQUIRED',
+                });
+            }
+            const response = await fetchWithDeadline(begun.uploadUrl, {
+                method: begun.uploadMethod,
+                headers: begun.uploadHeaders,
+                body: item.bytes,
+            }, { fetchImpl: options.fetchImpl, signal });
+            if (!response.ok) {
+                throw new StorystickError(`Slice capture upload returned HTTP ${response.status}.`, { code: 'SLICE_PREVIEW_UPLOAD_FAILED', status: response.status });
+            }
+            const finalized = await callHubApi('/api/cli/slice-previews/finalize-upload', {
+                method: 'POST',
+                body: { projectShortId, uploadSessionId: begun.uploadSessionId },
+                contentShapeCapability: begun.contentShapeCapability,
+                rootDir,
+                signal,
+                fetchImpl: options.fetchImpl,
+            });
+            results.push({
+                sliceType: item.sliceType,
+                ...(item.variationId !== undefined
+                    ? { variationId: item.variationId }
+                    : {}),
+                status: finalized.status === 'finalized' ? 'uploaded' : 'superseded',
+            });
+        }
+        const data = {
+            status: 'synced',
+            projectShortId,
+            manifest: manifestPath,
+            total: results.length,
+            uploaded: results.filter((item) => item.status === 'uploaded').length,
+            unchanged: results.filter((item) => item.status === 'unchanged').length,
+            superseded: results.filter((item) => item.status === 'superseded').length,
+            items: results,
+        };
+        if (getOutputMode() === 'json') {
+            emitJsonResult({ command: 'slice-previews sync', ok: true, data });
+            return;
+        }
+        logFinishedStep(`Synced ${data.total} slice capture(s): ${data.uploaded} uploaded, ${data.unchanged} unchanged.`);
+        if (data.superseded > 0) {
+            logWarning(`${data.superseded} upload(s) were superseded by a newer capture.`);
+        }
+        if (options.verbose)
+            logMessage(`Manifest: ${manifestPath}`);
+    }
+    catch (error) {
+        if (getOutputMode() === 'json') {
+            exitJsonFailure({ command: 'slice-previews sync', err: error });
+        }
+        exitWithError(error);
+    }
+    finally {
+        dispose();
+    }
+}
+export async function readSlicePreviewManifest(manifestPath) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new StorystickError(`Could not read slice preview manifest at ${manifestPath}.`, { code: 'SLICE_PREVIEW_MANIFEST_INVALID', cause: error });
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw manifestError('The manifest root must be an object.');
+    const manifest = raw;
+    const rootKeys = new Set(['version', 'previews']);
+    if (Object.keys(manifest).some((key) => !rootKeys.has(key))) {
+        throw manifestError('The manifest contains an unknown root property.');
+    }
+    if (manifest.version !== 1)
+        throw manifestError('The manifest version must be 1.');
+    if (!Array.isArray(manifest.previews) || manifest.previews.length === 0) {
+        throw manifestError('The manifest must contain at least one preview.');
+    }
+    const entries = [];
+    const subjects = new Set();
+    for (const [index, value] of manifest.previews.entries()) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw manifestError(`Preview at index ${index} must be an object.`);
+        }
+        const record = value;
+        const allowedKeys = new Set(['slice', 'variation', 'file']);
+        if (Object.keys(record).some((key) => !allowedKeys.has(key))) {
+            throw manifestError(`Preview at index ${index} has an unknown property.`);
+        }
+        if (typeof record.slice !== 'string' || !isIdentifier(record.slice)) {
+            throw manifestError(`Preview at index ${index} has an invalid slice ID.`);
+        }
+        if (record.variation !== undefined) {
+            if (typeof record.variation !== 'string' ||
+                !isIdentifier(record.variation) ||
+                record.variation === 'default') {
+                throw manifestError(`Preview at index ${index} has an invalid variation ID.`);
+            }
+        }
+        pushEntry(entries, subjects, {
+            sliceType: record.slice,
+            ...(typeof record.variation === 'string'
+                ? { variationId: record.variation }
+                : {}),
+            file: requireFile(record.file),
+        });
+    }
+    return entries;
+}
+function pushEntry(entries, subjects, entry) {
+    const key = `${entry.sliceType}:${entry.variationId ?? ''}`;
+    if (subjects.has(key))
+        throw manifestError(`Duplicate slice subject “${key}”.`);
+    subjects.add(key);
+    entries.push(entry);
+}
+function requireFile(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw manifestError('Every capture path must be a non-empty string.');
+    }
+    return value;
+}
+function isIdentifier(value) {
+    return /^[A-Za-z][A-Za-z0-9_-]*$/u.test(value);
+}
+function mimeTypeForPath(path) {
+    if (/\.png$/iu.test(path))
+        return 'image/png';
+    if (/\.jpe?g$/iu.test(path))
+        return 'image/jpeg';
+    if (/\.webp$/iu.test(path))
+        return 'image/webp';
+    throw new StorystickError(`Unsupported slice capture format: ${path}`, {
+        code: 'SLICE_PREVIEW_FORMAT_UNSUPPORTED',
+    });
+}
+function manifestError(message) {
+    return new StorystickError(message, {
+        code: 'SLICE_PREVIEW_MANIFEST_INVALID',
+    });
+}

package/dist/commands/source.d.ts

@@ -0,0 +1,82 @@
+type Options = {
+    root?: string;
+    project?: string;
+    config?: string;
+    ref?: string;
+    out?: string;
+    change?: string;
+    expectedRevision?: string;
+    requestId?: string;
+    json?: boolean;
+    dryRun?: boolean;
+    schema?: string;
+    appRoot?: string;
+    connectionRevision?: string;
+    repairCommand?: string;
+    repairCwd?: string;
+};
+export declare function prepareSource(root: string, configPath?: string, ref?: string): {
+    config: {
+        scope: {
+            appRoot: string;
+            include: string[];
+            exclude: string[];
+        };
+        schemaVersion: string;
+        recipe: {
+            schemaCheck: string;
+            install: {
+                argv: string[];
+                cwd?: string | undefined;
+            }[];
+            checks: {
+                argv: string[];
+                name: string;
+                cwd?: string | undefined;
+            }[];
+            preview: {
+                argv: string[];
+                port: number;
+                cwd?: string | undefined;
+                readyPath?: string | undefined;
+            };
+            allowedHosts: string[];
+            schemaOutput?: string | undefined;
+            env?: Record<string, string> | undefined;
+        };
+    };
+    snapshot: {
+        commit: string;
+        scope: {
+            appRoot: string;
+            include: string[];
+            exclude: string[];
+        };
+        files: {
+            path: string;
+            mode: number;
+            content: Buffer<ArrayBuffer>;
+            digest: string;
+        }[];
+        revision: string;
+    };
+    archive: NonSharedBuffer;
+    summary: {
+        commit: string;
+        revision: string;
+        scope: {
+            appRoot: string;
+            include: string[];
+            exclude: string[];
+        };
+        schemaVersion: string;
+        files: string[];
+        fileCount: number;
+        archiveBytes: number;
+        dirty: boolean;
+        note: string;
+    };
+};
+export declare function readSourceChange(directory: string): any;
+export declare function runSource(operation: string, workspaceId: string | undefined, options: Options): Promise<void>;
+export {};

package/dist/commands/source.js

@@ -0,0 +1,192 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync, renameSync, rmSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { sourceChangeIdentity, sourceChange, sourceScope, MAX_ARCHIVE_BYTES } from '@storystick/source/manifest';
+import { encodeSourceArchive, sourceDigest, sourceRevision, validateWorkspaceArchive } from '@storystick/source/archive';
+import { captureCommit, integrateSource } from '../source-git.js';
+import { callHubApi } from '../hub-client.js';
+import { fetchWithDeadline } from '../transport.js';
+import { resolveCliRuntimeConfig } from '../runtime-config.js';
+import { resolveProjectConnection } from '../project-connection.js';
+import { sourceConfiguration } from '@storystick/source/recipe';
+import { configureSource, configureNextSource } from '../setup.js';
+import { inspectRepository } from '../source-git.js';
+import { configureOutput, emitJsonResult, exitJsonFailure, exitWithError, getOutputMode, logMessage, withInterrupt } from '../output.js';
+export function prepareSource(root, configPath = '.storystick/source.json', ref = 'HEAD') {
+    const config = sourceConfiguration.parse(JSON.parse(readFileSync(resolve(root, configPath), 'utf8')));
+    const snapshot = captureCommit(root, ref, config.scope);
+    if (!snapshot.files.length)
+        throw Error('Source scope contains no committed files. Review the scope and commit the intended source first.');
+    const archive = encodeSourceArchive(snapshot.files);
+    return { config, snapshot, archive, summary: {
+            commit: snapshot.commit, revision: snapshot.revision, scope: snapshot.scope,
+            schemaVersion: config.schemaVersion, files: snapshot.files.map(file => file.path),
+            fileCount: snapshot.files.length, archiveBytes: archive.length,
+            dirty: inspectRepository(root)?.dirty ?? false,
+            note: 'Only the selected commit is transferred. Uncommitted changes are not included.',
+        } };
+}
+export function readSourceChange(directory) {
+    const envelope = JSON.parse(readFileSync(join(directory, 'change.json'), 'utf8'));
+    const change = sourceChange.parse(envelope.change);
+    if (sourceDigest(sourceChangeIdentity(change)) !== envelope.changeId)
+        throw Error('Source change identity mismatch.');
+    const load = (part) => {
+        const bytes = readFileSync(join(directory, `${part}.tar.gz`));
+        const files = validateWorkspaceArchive(bytes, change[part].archiveDigest);
+        if (sourceRevision(files) !== change[part].revision)
+            throw Error('Source snapshot identity mismatch.');
+        return files;
+    };
+    return { ...envelope, change, base: load('base'), result: load('result') };
+}
+export async function runSource(operation, workspaceId, options) {
+    configureOutput({ json: options.json === true });
+    const { signal, dispose } = withInterrupt();
+    try {
+        const root = resolve(options.root ?? '.');
+        if (process.env.STORYSTICK_RELEASE_SESSION)
+            throw Error('Source transfer requires a human CLI session outside the sandbox.');
+        let result;
+        if (options.dryRun && operation !== 'prepare')
+            throw Error('--dry-run is supported by source prepare only.');
+        if (operation === 'configure') {
+            if (Boolean(options.config) === Boolean(options.schema))
+                throw Error('Use --schema <compiled-schema.json> for a Next.js preset, or --config <reviewed-proposal.json>.');
+            result = options.config ? configureSource(root, options.config) : configureNextSource(root, options.schema);
+        }
+        else if (operation === 'prepare' && options.dryRun) {
+            result = { ...prepareSource(root, options.config, options.ref).summary, transferred: false };
+        }
+        else if (operation === 'apply') {
+            if (!options.change || !options.out)
+                throw Error('Specify --change <export-directory> and --out <new-checkout>.');
+            const artifact = readSourceChange(resolve(options.change));
+            result = integrateSource(root, options.out, artifact.change, artifact.base, artifact.result, options.ref);
+            if (result.status === 'conflicted')
+                process.exitCode = 1;
+        }
+        else {
+            const projectShortId = options.project ?? resolveProjectConnection(root)?.shortId;
+            if (!projectShortId)
+                throw Error('Specify --project <shortId> or connect this project.');
+            const runtime = resolveCliRuntimeConfig({ rootDir: root });
+            const transport = { rootDir: root, gatewayUrl: runtime.gatewayUrl, method: 'POST', signal, interactiveAuth: false, timeoutMs: 60_000 };
+            const request = (input, bytes = false) => callHubApi('/api/cli/project-workspace', {
+                ...transport, body: { projectShortId, request: input }, ...(bytes ? { responseType: 'bytes' } : {}),
+            });
+            const requestId = options.requestId ?? randomUUID();
+            const selection = () => { if (!workspaceId)
+                throw Error('Specify a workspace ID.'); return workspaceId; };
+            const upload = async (bytes) => {
+                const admission = await request({
+                    operation: 'createUploadUrl', requestId: `source_${requestId}`, bytes: bytes.byteLength, sha256: sourceDigest(bytes),
+                });
+                if (admission.state === 'stored')
+                    return admission.storageId;
+                const response = await fetchWithDeadline(admission.uploadUrl, { method: 'POST', headers: {
+                        'Content-Type': 'application/gzip', 'X-Storystick-Upload': admission.uploadToken,
+                    }, body: new Uint8Array(bytes) }, { signal, timeoutMs: 60_000 });
+                if (!response.ok)
+                    throw Error(`Source upload failed (${response.status}).`);
+                return (await response.json()).storageId;
+            };
+            if (operation === 'release')
+                result = await request({ operation: 'sourceRelease', releaseId: selection(), requestId });
+            else if (operation === 'stop')
+                result = await request({ operation: 'stop', workspaceId: selection(), requestId });
+            else if (operation === 'recover')
+                result = await request({ operation: 'recover', workspaceId: selection(), requestId,
+                    ...(options.repairCommand === undefined ? {} : { command: options.repairCommand }),
+                    ...(options.repairCwd === undefined ? {} : { cwd: options.repairCwd }) });
+            else if (operation === 'github-status')
+                result = await request({ operation: 'githubStatus' });
+            else if (operation === 'github-inspect')
+                result = await request({ operation: 'githubInspect', ...(options.appRoot ? { appRoot: options.appRoot } : {}), ...(options.ref ? { commit: options.ref } : {}), ...(options.config ? { configuration: sourceConfiguration.parse(JSON.parse(readFileSync(resolve(root, options.config), 'utf8'))) } : {}) });
+            else if (operation === 'propose') {
+                if (!options.change)
+                    throw Error('Specify --change <export-directory>. This creates a GitHub branch and draft PR and may trigger configured CI.');
+                const exported = readSourceChange(resolve(options.change));
+                if (exported.change.projectShortId !== projectShortId)
+                    throw Error('Source artifact belongs to another project.');
+                result = await request({ operation: 'githubPropose', workspaceId: exported.change.workspaceId, requestId: exported.requestId, changeId: exported.changeId });
+            }
+            else if (operation === 'github-import') {
+                if (!options.ref || !options.expectedRevision)
+                    throw Error('Specify --ref <immutable-GitHub-commit> and --expected-revision <workspace-revision>.');
+                result = await request({ operation: 'githubImport', workspaceId: selection(), requestId, expectedRevision: options.expectedRevision, commit: options.ref });
+            }
+            else if (operation === 'github-prepare') {
+                if (!options.ref || !options.connectionRevision)
+                    throw Error('Inspect the repository first, then pass --ref <immutable-GitHub-commit> and --connection-revision <inspected-connection-revision>.');
+                const config = sourceConfiguration.parse(JSON.parse(readFileSync(resolve(root, options.config ?? '.storystick/source.json'), 'utf8')));
+                result = await request({ operation: 'githubPrepare', connectionRevision: options.connectionRevision, commit: options.ref, scope: config.scope, schemaVersion: config.schemaVersion, recipe: config.recipe });
+            }
+            else if (operation === 'status')
+                result = await request({ operation: 'sourceStatus', workspaceId: selection() });
+            else if (operation === 'prepare') {
+                const { config, snapshot, archive } = prepareSource(root, options.config, options.ref);
+                const scope = config.scope;
+                const project = await callHubApi(`/api/cli/projects/for-user-by-shortId?shortId=${encodeURIComponent(projectShortId)}`, { ...transport, method: 'GET' });
+                result = await request({ operation: 'prepare', archiveId: await upload(archive), archiveDigest: sourceDigest(archive),
+                    seed: { projectId: project.internalId, commit: snapshot.commit, schemaVersion: config.schemaVersion, scope }, recipe: config.recipe });
+            }
+            else if (operation === 'export') {
+                if (!options.out || !options.expectedRevision)
+                    throw Error('Read source status, then specify --expected-revision <revision> and --out <new-directory>.');
+                const out = resolve(options.out);
+                if (existsSync(out))
+                    throw Error('Export destination already exists; inspect it before retrying.');
+                mkdirSync(dirname(out), { recursive: true });
+                const exported = await request({ operation: 'exportSource', workspaceId: selection(), requestId, expectedRevision: options.expectedRevision });
+                const stage = mkdtempSync(join(dirname(out), '.storystick-export-'));
+                try {
+                    writeFileSync(join(stage, 'change.json'), JSON.stringify(exported, null, 2) + '\n');
+                    for (const part of ['base', 'result']) {
+                        const chunks = [];
+                        for (let offset = 0; offset <= MAX_ARCHIVE_BYTES; offset += 4 * 1024 * 1024) {
+                            const chunk = Buffer.from(await request({ operation: 'downloadSource', workspaceId, requestId, part, offset }, true));
+                            if (chunk.length > 4 * 1024 * 1024 || offset + chunk.length > MAX_ARCHIVE_BYTES)
+                                throw Error('Source download exceeded its bound.');
+                            chunks.push(chunk);
+                            if (chunk.length < 4 * 1024 * 1024)
+                                break;
+                        }
+                        writeFileSync(join(stage, `${part}.tar.gz`), Buffer.concat(chunks));
+                    }
+                    readSourceChange(stage);
+                    renameSync(stage, out);
+                }
+                finally {
+                    if (existsSync(stage))
+                        rmSync(stage, { recursive: true, force: true });
+                }
+                result = { changeId: exported.changeId, requestId, directory: out, exported: true, applied: false };
+            }
+            else if (operation === 'import') {
+                if (!options.expectedRevision)
+                    throw Error('Read source status, then pass --expected-revision <revision>. Stop the workspace before importing.');
+                const status = await request({ operation: 'sourceStatus', workspaceId: selection() });
+                const snapshot = captureCommit(root, options.ref ?? 'HEAD', sourceScope.parse(status.scope)), archive = encodeSourceArchive(snapshot.files);
+                result = await request({ operation: 'importSource', workspaceId, requestId, expectedRevision: options.expectedRevision,
+                    archiveId: await upload(archive), archiveDigest: sourceDigest(archive), commit: snapshot.commit, scope: snapshot.scope });
+            }
+            else
+                throw Error('Use source configure, prepare, release, status, stop, recover, export, apply, import, github-status, github-inspect, github-prepare, github-import or propose.');
+        }
+        if ((operation === 'stop' || operation === 'recover') && result && typeof result === 'object' && 'error' in result)
+            throw Error(typeof result.error === 'string' ? result.error : 'Workspace operation failed.');
+        if (getOutputMode() === 'json')
+            emitJsonResult({ command: 'source', ok: true, data: result });
+        else
+            logMessage(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        if (getOutputMode() === 'json')
+            exitJsonFailure({ command: 'source', err });
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+}

package/dist/content-import.d.ts

@@ -0,0 +1,78 @@
+import { type ImportManifest, type ImportRecord, type ImportStatus } from '@storystick/core/content-import';
+import { type HubApiOptions } from './hub-client.js';
+import { type ImportAssetInput } from './asset-import.js';
+export interface LocalImportAsset {
+    file: string;
+    input: ImportAssetInput;
+}
+export declare function readContentImport(file: string): Promise<{
+    manifest: ImportManifest;
+    batches: ImportRecord[][];
+    assets: LocalImportAsset[];
+}>;
+/** Reserve source identities without uploading. All local inputs have already been checked. */
+export declare function prepareContentImportAssets(transport: ImportTransport, source: Awaited<ReturnType<typeof readContentImport>>): Promise<{
+    manifest: ImportManifest;
+    batches: ImportRecord[][];
+    assets: {
+        plan: import("./asset-import.js").ImportAssetReceipt;
+        file: string;
+        input: ImportAssetInput;
+    }[];
+}>;
+export type ImportTransport = <T>(request: Record<string, unknown>) => Promise<T>;
+export declare function contentImportTransport(projectShortId: string, options: HubApiOptions): ImportTransport;
+export declare function assetImportTransport(projectShortId: string, options: HubApiOptions): ImportTransport;
+export declare function uploadBudgetTransport(projectShortId: string, options: HubApiOptions): ImportTransport;
+/** Receipt identity is written before the first remote call. No content/secrets. */
+export declare function importRunIdentity(input: {
+    root: string;
+    project: string;
+    gateway: string;
+    manifest: ImportManifest;
+    resume?: string;
+    newRun?: boolean;
+}): Promise<string>;
+export declare function prepareContentImport(transport: ImportTransport, input: {
+    runId: string;
+    manifest: ImportManifest;
+    batches: ImportRecord[][];
+}): Promise<{
+    plans: unknown[];
+    runId: string;
+    state: "preparing" | "planned" | "applying" | "complete" | "cancelled" | "expired";
+    staged: number;
+    planned: number;
+    applied: number;
+    batches: number;
+    planDigest?: string;
+    assetCount: number;
+    assetsReady: number;
+}>;
+export declare function applyContentImport(transport: ImportTransport, runId: string, planDigest: string): Promise<ImportStatus>;
+export declare function verifyContentImport(transport: ImportTransport, runId: string): Promise<{
+    verified: boolean;
+    projected: boolean;
+    verification: {
+        documents: Array<{
+            matches: boolean;
+        }>;
+        assets: Array<{
+            matches: boolean;
+        }>;
+        projection: string;
+    }[];
+    assetVerification: {
+        assetId: string;
+        matches: boolean;
+    }[];
+    runId: string;
+    state: "preparing" | "planned" | "applying" | "complete" | "cancelled" | "expired";
+    staged: number;
+    planned: number;
+    applied: number;
+    batches: number;
+    planDigest?: string;
+    assetCount: number;
+    assetsReady: number;
+}>;