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

package/dist/commands/migrate.js

@@ -0,0 +1,550 @@
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import { isContentShapeBuildId } from '@storystick/types';
+import { querySchemaFingerprintFromStories } from '@storystick/types/query-schema-fingerprint';
+import { canonicalConversationJson } from '@storystick/core/canonical-json';
+import { abortSchemaChange, activateSchemaChange, analyzeSchemaChange, attestSchemaChange, getSchemaChange, getSchemaChangeIssues, getSchemaChangeReceipt, listSchemaChanges, nextSchemaChangeProposalBatch, pairCompatibleBuild, prepareSchemaChange, resumeSchemaChange, submitSchemaChangeProposalBatch, } from '../operations-client.js';
+import { fetchSchemaChangePlan, schemaToPushBody } from '../push-client.js';
+import { callHubApi } from '../hub-client.js';
+import { configureOutput, emitJsonResult, exitJsonFailure, exitWithError, getOutputMode, logFinishedStep, logMessage, logWarning, promptConfirm, promptText, withInterrupt, } from '../output.js';
+import { resolveCliRuntimeConfig } from '../runtime-config.js';
+import { requireProjectConnection, validateProjectTokenReadback, } from '../project-connection.js';
+import { buildExternalMigrationArtifact, executeExternalMigrationBatch, } from '../migration-artifact.js';
+async function session(options, signal) {
+    const rootDir = resolve(options.root ?? '.');
+    const connection = requireProjectConnection(rootDir);
+    const gatewayUrl = resolveCliRuntimeConfig({
+        rootDir,
+        gatewayUrl: options.gatewayUrl,
+    }).gatewayUrl;
+    const issued = await callHubApi('/api/cli/projects/issue-access-token', {
+        method: 'POST',
+        body: {
+            projectShortId: connection.shortId,
+            purpose: 'schema-migration',
+        },
+        gatewayUrl,
+        rootDir,
+        signal,
+        fetchImpl: options.fetchImpl,
+    });
+    const token = issued.token;
+    validateProjectTokenReadback(token, connection);
+    return { gatewayUrl, token, projectId: connection.shortId };
+}
+function configure(options) {
+    configureOutput({
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+}
+function renderRun(command, run) {
+    if (getOutputMode() === 'json') {
+        emitJsonResult({ command, ok: true, data: run });
+        return;
+    }
+    logFinishedStep(`${run.runId} · ${run.phase} · ${run.status}`);
+    const progress = run.progress;
+    logMessage(pc.dim(`${progress.rootsScanned}/${progress.rootsExpected ?? '?'} roots · ` +
+        `${progress.occurrencesChanged}/${progress.occurrencesScanned} occurrences changed · ` +
+        `${progress.issuesTotal} issue(s) · ${progress.dirtyRoots} dirty`));
+    if (run.preparationId)
+        logMessage(pc.dim(`Preparation: ${run.preparationId}`));
+    if (run.availableCommands.length > 0) {
+        logMessage(pc.dim(`Next: ${run.availableCommands.join(', ')}`));
+    }
+    if (run.statusUrl)
+        logMessage(run.statusUrl);
+    if (run.lastError)
+        logWarning(`${run.lastError.code}: ${run.lastError.message}`);
+}
+async function shell(command, options, fn, render) {
+    configure(options);
+    const { signal, dispose } = withInterrupt();
+    try {
+        const active = await session(options, signal);
+        const result = await fn(active, signal);
+        render(result);
+    }
+    catch (error) {
+        if (signal.aborted)
+            process.exit(130);
+        if (getOutputMode() === 'json')
+            exitJsonFailure({ command, err: error });
+        exitWithError(error);
+    }
+    finally {
+        dispose();
+    }
+}
+export function newMigrationRequestId() {
+    return `cli_${crypto.randomUUID()}`;
+}
+export async function runMigrateBuild(migrationPath, options = {}) {
+    configure(options);
+    try {
+        const artifact = await buildExternalMigrationArtifact(resolve(options.root ?? '.'), migrationPath);
+        const data = {
+            entryPath: artifact.entryPath,
+            artifactDigest: artifact.artifactDigest,
+            manifest: artifact.manifest,
+            bytes: artifact.bytes.byteLength,
+        };
+        if (getOutputMode() === 'json') {
+            emitJsonResult({ command: 'migrate build', ok: true, data });
+        }
+        else {
+            logFinishedStep(`${artifact.manifest.id}@${artifact.manifest.version} · ${artifact.artifactDigest}`);
+            logMessage(pc.dim(`${artifact.bytes.byteLength} bytes · ${artifact.entryPath}`));
+        }
+        return artifact;
+    }
+    catch (error) {
+        if (getOutputMode() === 'json') {
+            exitJsonFailure({ command: 'migrate build', err: error });
+        }
+        return exitWithError(error);
+    }
+}
+async function delay(ms, signal) {
+    await new Promise((resolveDelay, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(signal.reason ?? new Error('Migration interrupted.'));
+        };
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolveDelay();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+async function driveExternalProposals(args) {
+    const admitted = await getSchemaChange(args.gatewayUrl, args.token, args.runId, { signal: args.signal, fetchImpl: args.fetchImpl });
+    assertExternalMigrationArtifact(admitted, args.artifact);
+    for (;;) {
+        const batch = await nextSchemaChangeProposalBatch(args.gatewayUrl, args.token, args.runId, { signal: args.signal, fetchImpl: args.fetchImpl });
+        if (batch) {
+            if (batch.programDigest !== admitted.programDigest) {
+                throw new Error('SCHEMA_MIGRATION_ARTIFACT_MISMATCH');
+            }
+            const results = await executeExternalMigrationBatch(args.artifact.rootDir, args.artifact, batch);
+            await submitSchemaChangeProposalBatch(args.gatewayUrl, args.token, {
+                runId: args.runId,
+                batchId: batch.batchId,
+                inputDigest: batch.inputDigest,
+                programDigest: batch.programDigest,
+                results,
+                requestId: newMigrationRequestId(),
+            }, { signal: args.signal, fetchImpl: args.fetchImpl });
+            continue;
+        }
+        const run = await getSchemaChange(args.gatewayUrl, args.token, args.runId, { signal: args.signal, fetchImpl: args.fetchImpl });
+        if (run.status !== 'running') {
+            if ((run.proposalBatches?.open ?? 0) === 0)
+                return run;
+        }
+        if (args.deadline !== undefined && Date.now() >= args.deadline)
+            return run;
+        await delay(250, args.signal);
+    }
+}
+export function assertExternalMigrationArtifact(run, artifact) {
+    if (run.program?.kind !== 'external' ||
+        canonicalConversationJson(run.program.manifest) !==
+            canonicalConversationJson(artifact.manifest)) {
+        throw new Error('SCHEMA_MIGRATION_ARTIFACT_MISMATCH');
+    }
+}
+function assertGuidedProgram(run, target, program) {
+    if (run.targetVersion !== target.version)
+        throw new Error('The selected run targets a different schema. Re-run preview with the intended source files.');
+    if (program.artifact) {
+        assertExternalMigrationArtifact(run, program.artifact);
+    }
+    else if (!program.recipe || canonicalConversationJson(run.recipe) !== canonicalConversationJson(program.recipe)) {
+        throw new Error('The selected run uses a different native recipe.');
+    }
+}
+async function findGuidedRun(args) {
+    const options = { signal: args.signal, fetchImpl: args.fetchImpl };
+    if (args.program.runId) {
+        const run = await getSchemaChange(args.gatewayUrl, args.token, args.program.runId, options);
+        assertGuidedProgram(run, args.target, args.program);
+        return run;
+    }
+    const recent = await listSchemaChanges(args.gatewayUrl, args.token, 100, options);
+    const matches = recent.filter((run) => {
+        try {
+            assertGuidedProgram(run, args.target, args.program);
+            return run.status !== 'aborted';
+        }
+        catch {
+            return false;
+        }
+    });
+    const active = matches.filter((run) => run.status !== 'succeeded');
+    if (active.length > 1) {
+        throw new Error(`Several matching runs exist (${active.map((run) => run.runId).join(', ')}). Select one with --run.`);
+    }
+    return active[0] ?? matches[0] ?? null;
+}
+async function waitForGuidedRun(args) {
+    const deadline = Date.now() + 180_000;
+    for (;;) {
+        const run = args.artifact
+            ? await driveExternalProposals({ ...args, artifact: args.artifact, deadline })
+            : await getSchemaChange(args.gatewayUrl, args.token, args.runId, {
+                signal: args.signal, fetchImpl: args.fetchImpl,
+            });
+        if (run.status !== 'running' || Date.now() >= deadline)
+            return run;
+        await delay(750, args.signal);
+    }
+}
+/** Compose the existing durable analysis and preparation; no second server state machine. */
+export async function runMigratePreview(target, program, options = {}) {
+    const command = 'migrate preview';
+    return shell(command, options, async ({ gatewayUrl, token }, signal) => {
+        const transport = { signal, fetchImpl: options.fetchImpl };
+        let run = await findGuidedRun({ gatewayUrl, token, target, program, ...transport });
+        if (!run) {
+            const plan = await fetchSchemaChangePlan(gatewayUrl, token, schemaToPushBody(target), transport);
+            if (!plan.baseVersion)
+                throw new Error('A migration requires an existing active source schema.');
+            run = await analyzeSchemaChange(gatewayUrl, token, {
+                expectedBaseVersion: plan.baseVersion,
+                targetSchema: target,
+                planDigest: plan.planDigest,
+                ...(program.artifact
+                    ? { program: { kind: 'external', manifest: program.artifact.manifest } }
+                    : { recipe: program.recipe }),
+                requestId: options.requestId ?? newMigrationRequestId(),
+            }, transport);
+        }
+        if (run.status === 'running' || (program.artifact && run.status === 'awaiting_action' && (run.proposalBatches?.open ?? 0) > 0)) {
+            run = await waitForGuidedRun({ gatewayUrl, token, runId: run.runId, artifact: program.artifact, ...transport });
+        }
+        if (run.phase === 'analysis' && run.status === 'awaiting_action' && run.progress.issuesTotal === 0 && run.analysisId) {
+            run = await prepareSchemaChange(gatewayUrl, token, {
+                runId: run.runId, analysisId: run.analysisId,
+                requestId: newMigrationRequestId(),
+            }, transport);
+            if (run.status === 'running')
+                run = await waitForGuidedRun({ gatewayUrl, token, runId: run.runId, artifact: program.artifact, ...transport });
+        }
+        return run;
+    }, (run) => {
+        renderRun(command, run);
+        if (getOutputMode() === 'json')
+            return;
+        if (run.phase === 'verification' && run.status === 'awaiting_action' && run.preparationId) {
+            logMessage('B is verified in isolation. The application candidate and its Preview still require a human check before activation.');
+        }
+        else if (run.progress.issuesTotal > 0 && run.analysisId) {
+            logWarning(`Resolve the issues in A or the module, then resume: storystick migrate issues ${run.runId} ${run.analysisId}`);
+        }
+        else if (run.status === 'running') {
+            logMessage(`The server is still working. Re-run this command or inspect: storystick migrate status ${run.runId}`);
+        }
+    });
+}
+function migrationReadbackEndpoint(appUrl) {
+    const app = new URL(appUrl);
+    if (!['http:', 'https:'].includes(app.protocol) || app.username || app.password || app.search || app.hash) {
+        throw new Error('The application URL must be HTTP(S), without credentials, query or fragment.');
+    }
+    const base = new URL(app.toString().replace(/\/?$/, '/'));
+    return new URL('api/storystick/migration-readback', base).toString();
+}
+export async function readMigrationApplication(args) {
+    const url = migrationReadbackEndpoint(args.appUrl);
+    const response = await (args.fetchImpl ?? fetch)(url, {
+        redirect: 'error',
+        cache: 'no-store',
+        signal: args.signal ? AbortSignal.any([args.signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+    });
+    if (!response.ok)
+        throw new Error(`Application readback failed (${response.status}) at ${url}.`);
+    const body = await response.json();
+    const value = body && typeof body === 'object' && !Array.isArray(body)
+        ? body.migration : undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('The application did not expose a migration readback. Set STORYSTICK_APP_BUILD_ID and STORYSTICK_APP_BUILD_DIGEST in that build.');
+    const readback = value;
+    if (readback.projectId !== args.projectId || !isContentShapeBuildId(readback.artifactId) ||
+        !/^[a-f0-9]{64}$/.test(readback.artifactDigest) ||
+        (readback.schemaVersion !== null && typeof readback.schemaVersion !== 'string') ||
+        typeof readback.querySchemaFingerprint !== 'string') {
+        throw new Error('Application readback has invalid project or build identity.');
+    }
+    const expectedFingerprint = querySchemaFingerprintFromStories(args.target.stories);
+    if (readback.querySchemaFingerprint !== expectedFingerprint) {
+        throw new Error('The deployed application does not contain the target query schema. Deploy the candidate build first.');
+    }
+    return { url, readback };
+}
+export async function runMigratePairBuild(runId, target, input, options = {}) {
+    const command = 'migrate pair-build';
+    return shell(command, options, async ({ gatewayUrl, token, projectId }, signal) => {
+        const run = await getSchemaChange(gatewayUrl, token, runId, { signal, fetchImpl: options.fetchImpl });
+        if (run.status !== 'succeeded')
+            throw new Error('Complete the migration before pairing a compatible build.');
+        const observed = await readMigrationApplication({
+            appUrl: input.appUrl, projectId, target, signal, fetchImpl: options.fetchImpl,
+        });
+        if (input.phase === 'serving' && !input.previewProof?.trim()) {
+            throw new Error('A manual Preview proof reference is required before recording serving evidence.');
+        }
+        if (input.phase === 'serving' && observed.readback.schemaVersion !== target.version) {
+            throw new Error(`The application still reads ${observed.readback.schemaVersion ?? 'no schema'}; expected ${target.version}.`);
+        }
+        const paired = await pairCompatibleBuild(gatewayUrl, token, {
+            runId,
+            phase: input.phase,
+            artifactId: observed.readback.artifactId,
+            artifactDigest: observed.readback.artifactDigest,
+            schemaVersion: target.version,
+            querySchemaFingerprint: observed.readback.querySchemaFingerprint,
+            references: input.phase === 'prepared'
+                ? [observed.url] : [observed.url, input.previewProof.trim()],
+            requestId: input.requestId ?? newMigrationRequestId(),
+        }, { signal, fetchImpl: options.fetchImpl });
+        return { ...paired, artifactId: observed.readback.artifactId };
+    }, (paired) => {
+        if (getOutputMode() === 'json') {
+            emitJsonResult({ command, ok: true, data: paired });
+        }
+        else {
+            logFinishedStep(`${input.phase} · ${paired.artifactId} · ${paired.schemaVersion.slice(0, 8)}`);
+            logMessage(pc.dim(`Evidence: ${paired.evidenceId}`));
+        }
+    });
+}
+export async function runMigrateGuidedActivate(target, program, options = {}) {
+    const command = 'migrate activate';
+    return shell(command, options, async ({ gatewayUrl, token, projectId }, signal) => {
+        const transport = { signal, fetchImpl: options.fetchImpl };
+        let run = await findGuidedRun({ gatewayUrl, token, target, program, ...transport });
+        if (!run)
+            throw new Error('No matching migration run. Run `storystick migrate preview` first, or select an older run with --run.');
+        if (run.status === 'succeeded')
+            return { run, receipt: await getSchemaChangeReceipt(gatewayUrl, token, run.runId, transport), pending: '' };
+        if (run.phase !== 'verification' && run.phase !== 'convergence') {
+            throw new Error(`Run ${run.runId} is ${run.phase}/${run.status}; complete or resume preparation before activation.`);
+        }
+        if (run.phase === 'verification' && (run.status !== 'awaiting_action' || !run.preparationId || run.progress.issuesTotal !== 0 || run.progress.dirtyRoots !== 0)) {
+            throw new Error(`Run ${run.runId} has no current verified preparation.`);
+        }
+        if (run.phase === 'verification' && !program.yes && (getOutputMode() === 'json' || !process.stdin.isTTY)) {
+            throw new Error('Pass --yes to explicitly approve authority transfer in non-interactive mode.');
+        }
+        const servingUrl = program.servingUrl ?? (getOutputMode() !== 'json' && process.stdin.isTTY
+            ? await promptText('Public serving application URL') : undefined);
+        if (!servingUrl)
+            throw new Error('Pass --serving-url <url> for the public application. The candidate URL is not assumed to be public.');
+        migrationReadbackEndpoint(servingUrl);
+        const appUrl = program.appUrl ?? (run.phase === 'verification' && getOutputMode() !== 'json' && process.stdin.isTTY
+            ? await promptText('Candidate application URL') : undefined);
+        if (run.phase === 'verification') {
+            if (!appUrl)
+                throw new Error('Pass --app-url <url> to identify the candidate application.');
+            const observed = await readMigrationApplication({ appUrl, projectId, target, ...transport });
+            const proof = program.previewProof ?? (getOutputMode() !== 'json' && process.stdin.isTTY
+                ? await promptText('Reference to your manual B Preview check') : undefined);
+            if (!proof?.trim())
+                throw new Error('A manual B Preview proof reference is required (--preview-proof).');
+            if (!run.activationEvidenceId) {
+                run = await attestSchemaChange(gatewayUrl, token, {
+                    runId: run.runId, preparationId: run.preparationId, phase: 'prepared',
+                    level: 'manual-attestation', artifactId: observed.readback.artifactId,
+                    artifactDigest: observed.readback.artifactDigest,
+                    schemaVersion: run.targetVersion, generationId: run.targetGenerationId,
+                    surfaces: ['api', 'preview'], references: [observed.url, proof.trim()],
+                    requestId: newMigrationRequestId(),
+                }, transport);
+            }
+            if (!program.yes) {
+                logMessage(`${run.progress.rootsScanned} roots · ${run.progress.occurrencesChanged} changes · ${run.progress.issuesTotal} issues · ${run.progress.dirtyRoots} dirty`);
+                logMessage(`A → B · ${run.baseVersion} → ${run.targetVersion} · ${observed.readback.artifactId}`);
+                if (!await promptConfirm('Transfer editing authority to B? A promoted candidate build may already read B before the final receipt.', { default: false })) {
+                    return { run, receipt: null, pending: 'Activation cancelled; the verified preparation remains available.' };
+                }
+            }
+            run = await activateSchemaChange(gatewayUrl, token, {
+                runId: run.runId, preparationId: run.preparationId,
+                evidenceId: run.activationEvidenceId, requestId: options.requestId ?? newMigrationRequestId(),
+            }, transport);
+        }
+        if (!run.servingEvidenceId) {
+            // The endpoint is a real, no-cache query through the deployed SDK. It
+            // does not attest every CDN instance or the client's Preview session.
+            const serving = await readMigrationApplication({ appUrl: servingUrl, projectId, target, ...transport });
+            if (serving.readback.schemaVersion !== run.targetVersion) {
+                return { run, receipt: null, pending: `B is active for editing, but ${serving.url} still reads ${serving.readback.schemaVersion ?? 'no schema'}; promote the same build and re-run this command.` };
+            }
+            run = await attestSchemaChange(gatewayUrl, token, {
+                runId: run.runId, preparationId: run.preparationId, phase: 'serving',
+                level: 'adapter-readback', artifactId: serving.readback.artifactId,
+                artifactDigest: serving.readback.artifactDigest,
+                schemaVersion: run.targetVersion, generationId: run.targetGenerationId,
+                surfaces: ['api'], references: [serving.url],
+                requestId: newMigrationRequestId(),
+            }, transport);
+        }
+        const deadline = Date.now() + 180_000;
+        while (run.status === 'running' && Date.now() < deadline) {
+            await delay(750, signal);
+            run = await getSchemaChange(gatewayUrl, token, run.runId, transport);
+        }
+        const receipt = await getSchemaChangeReceipt(gatewayUrl, token, run.runId, transport);
+        return { run, receipt, pending: receipt ? '' : 'Serving was observed, but projection ACK and the final server receipt are still pending. Re-run this command later.' };
+    }, ({ run, receipt, pending }) => {
+        if (getOutputMode() === 'json') {
+            emitJsonResult({ command, ok: true, data: { run, receipt, pending: pending || null, complete: receipt !== null } });
+            return;
+        }
+        renderRun(command, run);
+        if (receipt)
+            logFinishedStep(`Server receipt: ${receipt.receiptId} · projection ACK ${receipt.projectionAckedThroughSeq}`);
+        else if (pending)
+            logWarning(pending);
+    });
+}
+export async function runMigrateAnalyze(targetSchema, recipe, options = {}) {
+    const command = 'migrate analyze';
+    return shell(command, options, async ({ gatewayUrl, token }, signal) => {
+        const plan = await fetchSchemaChangePlan(gatewayUrl, token, schemaToPushBody(targetSchema), { signal, fetchImpl: options.fetchImpl });
+        if (!plan.baseVersion) {
+            throw new Error('A migration requires an existing active source schema.');
+        }
+        return analyzeSchemaChange(gatewayUrl, token, {
+            expectedBaseVersion: plan.baseVersion,
+            targetSchema,
+            planDigest: plan.planDigest,
+            recipe,
+            requestId: options.requestId ?? newMigrationRequestId(),
+        }, { signal, fetchImpl: options.fetchImpl });
+    }, (run) => renderRun(command, run));
+}
+export async function runMigrateAnalyzeExternal(targetSchema, artifact, options = {}) {
+    const command = 'migrate analyze';
+    return shell(command, options, async ({ gatewayUrl, token }, signal) => {
+        const plan = await fetchSchemaChangePlan(gatewayUrl, token, schemaToPushBody(targetSchema), { signal, fetchImpl: options.fetchImpl });
+        if (!plan.baseVersion) {
+            throw new Error('A migration requires an existing active source schema.');
+        }
+        const started = await analyzeSchemaChange(gatewayUrl, token, {
+            expectedBaseVersion: plan.baseVersion,
+            targetSchema,
+            planDigest: plan.planDigest,
+            program: { kind: 'external', manifest: artifact.manifest },
+            requestId: options.requestId ?? newMigrationRequestId(),
+        }, { signal, fetchImpl: options.fetchImpl });
+        return driveExternalProposals({
+            gatewayUrl,
+            token,
+            runId: started.runId,
+            artifact,
+            signal,
+            fetchImpl: options.fetchImpl,
+        });
+    }, (run) => renderRun(command, run));
+}
+export async function runMigratePrepare(runId, analysisId, options = {}) {
+    const command = 'migrate prepare';
+    return shell(command, options, async ({ gatewayUrl, token }, signal) => {
+        const started = await prepareSchemaChange(gatewayUrl, token, {
+            runId,
+            analysisId,
+            requestId: options.requestId ?? newMigrationRequestId(),
+        }, { signal, fetchImpl: options.fetchImpl });
+        if (!options.artifact)
+            return started;
+        return driveExternalProposals({
+            gatewayUrl,
+            token,
+            runId: started.runId,
+            artifact: options.artifact,
+            signal,
+            fetchImpl: options.fetchImpl,
+        });
+    }, (run) => renderRun(command, run));
+}
+export async function runMigrateRunCommand(action, runId, options = {}) {
+    const command = `migrate ${action}`;
+    return shell(command, options, ({ gatewayUrl, token }, signal) => (action === 'resume' ? resumeSchemaChange : abortSchemaChange)(gatewayUrl, token, { runId, requestId: options.requestId ?? newMigrationRequestId() }, { signal, fetchImpl: options.fetchImpl }), (run) => renderRun(command, run));
+}
+export async function runMigrateAttest(body, options = {}) {
+    const command = 'migrate attest';
+    return shell(command, options, ({ gatewayUrl, token }, signal) => attestSchemaChange(gatewayUrl, token, { ...body, requestId: options.requestId ?? newMigrationRequestId() }, { signal, fetchImpl: options.fetchImpl }), (run) => renderRun(command, run));
+}
+export async function runMigrateActivate(runId, preparationId, evidenceId, options = {}) {
+    const command = 'migrate activate';
+    return shell(command, options, ({ gatewayUrl, token }, signal) => activateSchemaChange(gatewayUrl, token, {
+        runId,
+        preparationId,
+        evidenceId,
+        requestId: options.requestId ?? newMigrationRequestId(),
+    }, { signal, fetchImpl: options.fetchImpl }), (run) => renderRun(command, run));
+}
+export async function runMigrateStatus(runId, options = {}) {
+    const command = 'migrate status';
+    return shell(command, options, ({ gatewayUrl, token }, signal) => runId
+        ? getSchemaChange(gatewayUrl, token, runId, {
+            signal,
+            fetchImpl: options.fetchImpl,
+        })
+        : listSchemaChanges(gatewayUrl, token, 20, {
+            signal,
+            fetchImpl: options.fetchImpl,
+        }), (result) => {
+        if (Array.isArray(result)) {
+            if (getOutputMode() === 'json') {
+                emitJsonResult({ command, ok: true, data: result });
+                return;
+            }
+            if (result.length === 0)
+                logMessage('No schema-change runs.');
+            for (const run of result)
+                renderRun(command, run);
+        }
+        else {
+            renderRun(command, result);
+        }
+    });
+}
+export async function runMigrateIssues(runId, analysisId, options = {}) {
+    const command = 'migrate issues';
+    return shell(command, options, ({ gatewayUrl, token }, signal) => getSchemaChangeIssues(gatewayUrl, token, { runId, analysisId, cursor: options.cursor, limit: options.limit }, { signal, fetchImpl: options.fetchImpl }), (result) => {
+        if (getOutputMode() === 'json') {
+            emitJsonResult({ command, ok: true, data: result });
+            return;
+        }
+        for (const entry of result.page) {
+            logWarning(`${entry.code} · ${entry.corpus}/${entry.rootKey}: ${entry.message}`);
+        }
+        logMessage(pc.dim(`${result.page.length}/${result.total} issue(s) shown`));
+        if (result.continueCursor)
+            logMessage(pc.dim(`Cursor: ${result.continueCursor}`));
+    });
+}
+export async function runMigrateReceipt(runId, options = {}) {
+    const command = 'migrate receipt';
+    return shell(command, options, ({ gatewayUrl, token }, signal) => getSchemaChangeReceipt(gatewayUrl, token, runId, {
+        signal,
+        fetchImpl: options.fetchImpl,
+    }), (receipt) => {
+        if (getOutputMode() === 'json') {
+            emitJsonResult({ command, ok: true, data: receipt });
+            return;
+        }
+        if (!receipt) {
+            logMessage('No terminal server receipt is available yet.');
+            return;
+        }
+        logFinishedStep(`${receipt.receiptId} · run ${receipt.runId}`);
+        logMessage(pc.dim(`Projection ACK: ${receipt.projectionAckedThroughSeq}`));
+    });
+}

package/dist/commands/release.d.ts

@@ -0,0 +1,8 @@
+export declare function runRelease(operation: string, value: string | undefined, options: {
+    root?: string;
+    project?: string;
+    name?: string;
+    json?: boolean;
+    approval?: string;
+    requestId?: string;
+}): Promise<void>;

package/dist/commands/release.js

@@ -0,0 +1,60 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { callHubApi } from '../hub-client.js';
+import { resolveCliRuntimeConfig } from '../runtime-config.js';
+import { readReleaseContext, writeReleaseContext } from '../release-context.js';
+import { configureOutput, emitJsonResult, exitJsonFailure, exitWithError, getOutputMode, logMessage, withInterrupt } from '../output.js';
+export async function runRelease(operation, value, options) {
+    configureOutput({ json: options.json === true });
+    const { signal, dispose } = withInterrupt();
+    try {
+        const rootDir = resolve(options.root ?? '.'), runtime = resolveCliRuntimeConfig({ rootDir });
+        const stored = readReleaseContext(rootDir);
+        if (operation === 'use' && value === 'main') {
+            if (process.env.STORYSTICK_RELEASE_SESSION)
+                throw Error('A sandbox cannot select Main.');
+            writeReleaseContext(rootDir, undefined);
+            if (getOutputMode() === 'json')
+                emitJsonResult({ command: 'release', ok: true, data: { releaseId: null } });
+            else
+                logMessage('CLI context: Main');
+            return;
+        }
+        const projectShortId = options.project ?? stored?.projectShortId ?? process.env.STORYSTICK_PROJECT_ID;
+        if (!projectShortId)
+            throw Error('Specify --project <shortId>.');
+        const delivery = ['prepare-publication', 'publication-status', 'publish', 'resume-publication', 'cancel-publication'].includes(operation);
+        if (!delivery && !['list', 'read', 'create', 'use'].includes(operation))
+            throw Error('Use release list, read <id>, create <name> or use <id|main>.');
+        if (operation !== 'list' && !value)
+            throw Error('A release ID or name is required.');
+        if (operation === 'publish' && !options.approval)
+            throw Error('Review release publication-status, then pass --approval <digest> to publish that exact prepared release.');
+        if (delivery && process.env.STORYSTICK_RELEASE_SESSION)
+            throw Error('Publication requires a human CLI session outside the coding sandbox.');
+        const deliveryOperation = { 'prepare-publication': 'prepare', 'publication-status': 'status', publish: 'confirm', 'resume-publication': 'resume', 'cancel-publication': 'cancel' }[operation];
+        const request = delivery ? { operation: deliveryOperation, releaseId: value, ...(deliveryOperation === 'prepare' ? { requestId: options.requestId ?? randomUUID() } : {}), ...(deliveryOperation === 'confirm' ? { approval: options.approval } : {}) } : operation === 'list' ? { operation } : operation === 'create'
+            ? { operation, releaseId: randomUUID(), name: options.name ?? value }
+            : { operation: 'read', releaseId: value };
+        const result = await callHubApi(delivery ? '/api/cli/project-delivery' : '/api/cli/project-release', {
+            rootDir, gatewayUrl: runtime.gatewayUrl, method: 'POST', body: { projectShortId, request }, signal, interactiveAuth: false,
+        });
+        if (operation === 'use') {
+            if (result.status !== 'draft')
+                throw Error('Select an editable draft release.');
+            writeReleaseContext(rootDir, { projectShortId, releaseId: value, gatewayUrl: runtime.gatewayUrl });
+        }
+        if (getOutputMode() === 'json')
+            emitJsonResult({ command: 'release', ok: true, data: result });
+        else
+            logMessage(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        if (getOutputMode() === 'json')
+            exitJsonFailure({ command: 'release', err });
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,6 @@
+export declare function runSetup(options: {
+    root?: string;
+    project?: string;
+    remote?: boolean;
+    json?: boolean;
+}): Promise<void>;