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

package/dist/push-client.js

@@ -0,0 +1,160 @@
+/**
+ * Pattern D schema push — plain `fetch()` client used by the CLI.
+ *
+ * Post ADR-058 + audit FIX-1 (Pattern D bridge): `schemas.push` no longer
+ * exists at Central's top-level Convex API. It lives inside the backend
+ * Component and is only reachable via the Pattern D mutation endpoint
+ * `POST <gatewayUrl>/api/m/schemas/push`. This module hides the
+ * endpoint shape behind a single function used by both `storystick push`
+ * / `sync` (cli.ts) and `storystick init` (init.ts) — one wire format,
+ * one place to maintain it.
+ *
+ * We avoid `ConvexHttpClient` on purpose: the Pattern D contract is plain
+ * HTTP so the edge Worker (follow-up PR) can cache+rewrite without
+ * understanding Convex's protocol, and so the SDK has zero runtime
+ * Convex dependency.
+ *
+ * ADR-072 §D3: failures throw `StorystickError` with `code` + `status` so
+ * the CLI's exit-code router (Batch 7) can route HTTP 5xx and network
+ * errors uniformly. Network errors preserve their original cause via
+ * `cause` (lock L4) so `TypeError(cause: ECONNREFUSED)` survives wrapping.
+ */
+import { StorystickError, storystickErrorFromResponse } from './cli-error.js';
+import { contentShapeCapabilityHeaders, } from '@storystick/types';
+import { abortableSleep, fetchWithDeadline } from './transport.js';
+/**
+ * Convert the core serializer output into the exact Pattern D push body.
+ *
+ * Keep this as the only schema → wire-shape mapper used by push/sync/init/link
+ * so new schema sidecars cannot be dropped by one call site.
+ */
+export function schemaToPushBody(schema) {
+    return {
+        formatVersion: schema.formatVersion,
+        version: schema.version,
+        stories: schema.stories,
+        storyCount: schema.storyCount,
+        zoneMappings: schema.zoneMappings,
+        fieldBindings: schema.fieldBindings,
+        diagnostics: schema.diagnostics,
+    };
+}
+// ─────────────────────────────────────────────
+// Request
+// ─────────────────────────────────────────────
+/**
+ * POST `schemas.push` via Pattern D. Throws with a readable message on
+ * failure — caller decides whether to exit / warn.
+ *
+ * @param siteUrl Central's `.convex.site` base URL (no trailing slash).
+ * @param token Short-lived Storystick JWT with `scope: 'write' | 'full'`.
+ * @param body Resolved schema payload.
+ */
+export async function pushSchema(siteUrl, token, body, fence, options = {}) {
+    const endpoint = `${siteUrl.replace(/\/$/, '')}/api/m/schemas/push`;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+        const res = await fetchWithDeadline(endpoint, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+                'X-Storystick-Client': 'cli',
+                'X-Storystick-Idempotency-Key': body.version,
+            },
+            body: JSON.stringify({ ...body, ...fence }),
+        }, options);
+        if (res.ok)
+            return (await res.json());
+        const error = actionablePushError(await storystickErrorFromResponse(res));
+        if (error.retryable !== true || attempt === 3)
+            throw error;
+        await abortableSleep(Math.min(250 * 2 ** (attempt - 1), 1_000), options.signal);
+    }
+    throw new StorystickError('Schema push exhausted its retry budget.');
+}
+export async function fetchSchemaChangePlan(siteUrl, token, body, options = {}) {
+    const response = await fetchWithDeadline(`${siteUrl.replace(/\/$/, '')}/api/m/schemas/plan`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'X-Storystick-Client': 'cli',
+        },
+        body: JSON.stringify(body),
+    }, options);
+    if (!response.ok) {
+        throw actionablePushError(await storystickErrorFromResponse(response));
+    }
+    return (await response.json());
+}
+export function schemaPlanFence(plan) {
+    return {
+        expectedBaseVersion: plan.baseVersion,
+        planDigest: plan.planDigest,
+    };
+}
+export function assertSchemaPlanAllowed(plan) {
+    if (plan.classification !== 'breaking' && plan.classification !== 'unknown') {
+        return;
+    }
+    throw new StorystickError(`Schema change is ${plan.classification}; no schema or generated pointer was published.`, {
+        code: 'SCHEMA_CHANGE_BLOCKED',
+        category: 'validation',
+        recoverable: true,
+        retryable: false,
+        payload: { plan },
+    });
+}
+function actionablePushError(error) {
+    const payload = error.payload &&
+        typeof error.payload === 'object' &&
+        !Array.isArray(error.payload)
+        ? error.payload
+        : undefined;
+    const docShortId = typeof payload?.docShortId === 'string' ? payload.docShortId : undefined;
+    const context = [error.code, error.message].filter(Boolean).join(': ');
+    const message = docShortId
+        ? `${context} (docShortId: ${docShortId})`
+        : context;
+    return new StorystickError(message, {
+        code: error.code,
+        status: error.status,
+        payload: error.payload,
+        category: error.category,
+        recoverable: error.recoverable,
+        retryable: error.retryable,
+        messageKey: error.messageKey,
+        params: error.params,
+        ref: error.ref,
+        docUrl: error.docUrl,
+    });
+}
+// ─────────────────────────────────────────────
+// Token exchange
+// ─────────────────────────────────────────────
+/**
+ * Exchange a long-lived API key for a short-lived Storystick JWT. The CLI
+ * is a server-to-server consumer: `X-Storystick-Client: sdk` signals
+ * that path to Central's CSRF check (see `apps/studio/convex/_csrf.ts`).
+ *
+ * @param siteUrl Central's `.convex.site` base URL (no trailing slash).
+ * @param apiKey Secret (`ss_sk_*`) API key.
+ */
+export async function fetchSchemaPushToken(siteUrl, apiKey, options = {}) {
+    const res = await fetchWithDeadline(`${siteUrl.replace(/\/$/, '')}/api/tokens/issue`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+            'X-Storystick-Client': 'cli',
+            ...contentShapeCapabilityHeaders('cli'),
+        },
+    }, options);
+    if (!res.ok) {
+        throw await storystickErrorFromResponse(res, `Gateway rejected token issuance (HTTP ${res.status}).`);
+    }
+    const body = (await res.json());
+    if (!body.token)
+        throw new StorystickError('Gateway returned no token.');
+    return body.token;
+}

package/dist/release-context.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+declare const contextSchema: z.ZodObject<{
+    projectShortId: z.ZodString;
+    releaseId: z.ZodString;
+    gatewayUrl: z.ZodString;
+}, z.core.$strict>;
+export type ReleaseContext = z.infer<typeof contextSchema>;
+export declare function readReleaseContext(rootDir: string): ReleaseContext | undefined;
+export declare function writeReleaseContext(rootDir: string, context: ReleaseContext | undefined): void;
+/** A sandbox's destination is supplied by its server-held credential. Neither a
+ * local context file nor --release can retarget that credential to Main. */
+export declare function resolveReleaseContext(rootDir: string, gatewayUrl: string, explicit?: string, env?: NodeJS.ProcessEnv): ReleaseContext | undefined;
+export {};

package/dist/release-context.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { readCliEnvValue } from './runtime-config.js';
+const contextSchema = z.object({ projectShortId: z.string().regex(/^[a-z0-9]{8}$/), releaseId: z.string().min(1).max(120), gatewayUrl: z.string().url() }).strict();
+const file = (rootDir) => join(rootDir, '.storystick', 'release-context.json');
+export function readReleaseContext(rootDir) {
+    return existsSync(file(rootDir)) ? contextSchema.parse(JSON.parse(readFileSync(file(rootDir), 'utf8'))) : undefined;
+}
+export function writeReleaseContext(rootDir, context) {
+    if (!context) {
+        rmSync(file(rootDir), { force: true });
+        return;
+    }
+    const path = file(rootDir), temporary = `${path}.${randomUUID()}.tmp`;
+    mkdirSync(join(rootDir, '.storystick'), { recursive: true });
+    writeFileSync(temporary, JSON.stringify(contextSchema.parse(context)) + '\n', { mode: 0o600 });
+    renameSync(temporary, path);
+}
+/** A sandbox's destination is supplied by its server-held credential. Neither a
+ * local context file nor --release can retarget that credential to Main. */
+export function resolveReleaseContext(rootDir, gatewayUrl, explicit, env = process.env) {
+    if (env.STORYSTICK_RELEASE_SESSION) {
+        const scoped = contextSchema.parse({ projectShortId: env.STORYSTICK_PROJECT_ID, releaseId: env.STORYSTICK_RELEASE_ID, gatewayUrl: env.STORYSTICK_RELEASE_GATEWAY });
+        if (explicit && explicit !== scoped.releaseId)
+            throw Error('This workspace can only write its own release.');
+        return scoped;
+    }
+    const stored = readReleaseContext(rootDir);
+    if (stored && new URL(stored.gatewayUrl).origin !== new URL(gatewayUrl).origin)
+        throw Error('Release context belongs to a different gateway. Select the release again.');
+    if (!explicit)
+        return stored;
+    const projectShortId = stored?.projectShortId ?? readCliEnvValue(rootDir, 'STORYSTICK_PROJECT_ID', env);
+    if (!projectShortId)
+        throw Error('Select a project with storystick release use <id> --project <id> first.');
+    return contextSchema.parse({ projectShortId, releaseId: explicit, gatewayUrl });
+}

package/dist/release-schema-client.d.ts

@@ -0,0 +1,16 @@
+import type { SerializedSchema } from '@storystick/types';
+import type { ReleaseContext } from './release-context.js';
+export declare function releaseSchemaRequest<T>(context: ReleaseContext, request: Record<string, unknown>, rootDir: string, signal?: AbortSignal): Promise<T>;
+export declare function localSourceRevision(rootDir: string): string;
+export declare function pushReleaseSchema(args: {
+    context: ReleaseContext;
+    schema: SerializedSchema;
+    rootDir: string;
+    dryRun?: boolean;
+    signal?: AbortSignal;
+}): Promise<{
+    status: "pushed" | "unchanged" | "planned";
+    version: string;
+    releaseId: string;
+    published: false;
+}>;

package/dist/release-schema-client.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { callHubApi } from './hub-client.js';
+import { fetchWithDeadline } from './transport.js';
+import { storystickErrorFromResponse } from './cli-error.js';
+import { captureWorkingSource } from './source-git.js';
+import { sourceRevision } from '@storystick/source/archive';
+import { sourceScope, defaultSourceScope } from '@storystick/source/manifest';
+export async function releaseSchemaRequest(context, request, rootDir, signal) {
+    const path = '/api/cli/release-schema';
+    const body = { projectShortId: context.projectShortId, releaseId: context.releaseId, ...request };
+    const token = process.env.STORYSTICK_RELEASE_SESSION;
+    if (!token)
+        return callHubApi(path, { rootDir, gatewayUrl: context.gatewayUrl, method: 'POST', body, signal, interactiveAuth: false });
+    // Restricted workspace credential, never a user login or project API key.
+    const response = await fetchWithDeadline(`${context.gatewayUrl.replace(/\/$/, '')}${path}`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Storystick-Workspace-Session': token }, body: JSON.stringify(body), signal,
+    }, { timeoutMs: 60_000, signal });
+    if (!response.ok)
+        throw await storystickErrorFromResponse(response);
+    return response.json();
+}
+export function localSourceRevision(rootDir) {
+    const config = resolve(rootDir, '.storystick/source.json');
+    const scope = existsSync(config) ? sourceScope.parse(JSON.parse(readFileSync(config, 'utf8')).scope) : defaultSourceScope;
+    return sourceRevision(captureWorkingSource(rootDir, scope));
+}
+export async function pushReleaseSchema(args) {
+    const current = await releaseSchemaRequest(args.context, { operation: 'read' }, args.rootDir, args.signal);
+    return releaseSchemaRequest(args.context, {
+        operation: 'push', schema: args.schema, sourceRevision: localSourceRevision(args.rootDir), expectedVersion: current.schemaVersion, dryRun: args.dryRun === true,
+    }, args.rootDir, args.signal);
+}

package/dist/release-sync.d.ts

@@ -0,0 +1,36 @@
+import type { GeneratedFile } from '@storystick/core';
+import type { SerializedSchema } from '@storystick/types';
+import type { ReleaseContext } from './release-context.js';
+export declare function syncRelease(args: {
+    context: ReleaseContext;
+    rootDir: string;
+    outputDirectory: string;
+    prepare: () => Promise<{
+        schema: SerializedSchema;
+        generated: readonly GeneratedFile[];
+        storyCount: number;
+    }>;
+    dryRun?: boolean;
+    signal?: AbortSignal;
+}): Promise<{
+    status: "pushed" | "unchanged" | "planned";
+    version: string;
+    releaseId: string;
+    published: false;
+} | {
+    releaseId: string;
+    published: boolean;
+    generatedFiles: readonly string[];
+    resumed: boolean;
+    status?: "pushed" | "unchanged" | undefined;
+    version?: string | undefined;
+    newBindingNotes?: import("./push-client.js").NewBindingNote[] | undefined;
+    recommendBackfill?: import("./push-client.js").BackfillRecommendation;
+    projectionSeq?: number;
+} | {
+    generatedFiles: readonly string[];
+    status: "pushed" | "unchanged" | "planned";
+    version: string;
+    releaseId: string;
+    published: false;
+}>;

package/dist/release-sync.js

@@ -0,0 +1,31 @@
+import { commitPreparedGeneration, prepareGeneratedFiles } from './generated-transaction.js';
+import { pushReleaseSchema } from './release-schema-client.js';
+import { clearSyncOperation, markSyncOperationPushed, readSyncOperation, writePreparedSyncOperation } from './sync-transaction.js';
+export async function syncRelease(args) {
+    const target = `${args.context.gatewayUrl}|${args.context.projectShortId}|${args.context.releaseId}`;
+    const pending = readSyncOperation(args.rootDir);
+    if (pending && (pending.target !== target || pending.outputDirectory !== args.outputDirectory))
+        throw Error('A sync is pending for another destination. Resume it before changing release.');
+    if (pending?.state === 'pushed') {
+        if (args.dryRun)
+            throw Error('Resume the pending sync without --dry-run.');
+        const committed = await commitPreparedGeneration(pending.outputDirectory, pending.generationId);
+        clearSyncOperation(args.rootDir);
+        return { ...pending.pushResult, releaseId: args.context.releaseId, published: false, generatedFiles: committed.files, resumed: true };
+    }
+    const prepared = await args.prepare();
+    const resolved = { ...args, ...prepared };
+    // Plan validates the exact same admission without changing the remote scope.
+    const plan = await pushReleaseSchema({ ...resolved, dryRun: true });
+    if (args.dryRun)
+        return plan;
+    const staged = await prepareGeneratedFiles(args.outputDirectory, prepared.generated);
+    const receipt = writePreparedSyncOperation({ ...resolved, schemaVersion: prepared.schema.version, generationId: staged.generationId, target });
+    const result = await pushReleaseSchema(resolved);
+    if (result.status === 'planned')
+        throw Error('Release sync did not apply its schema.');
+    markSyncOperationPushed(receipt, { status: result.status, version: result.version, newBindingNotes: [] });
+    const committed = await commitPreparedGeneration(args.outputDirectory, staged.generationId);
+    clearSyncOperation(args.rootDir);
+    return { ...result, generatedFiles: committed.files };
+}

package/dist/resolve.d.ts

@@ -0,0 +1,15 @@
+import type { Diagnostic, ResolvedStory } from '@storystick/core';
+export interface ResolveResult {
+    stories: Map<string, ResolvedStory>;
+    diagnostics: Diagnostic[];
+    success: boolean;
+}
+/**
+ * Parse and resolve all .story files. No side effects (no file writes).
+ * Shared by generate, push, sync, and deterministic build tooling.
+ */
+export declare function runResolve(options: {
+    rootDir: string;
+    storyDirs: string[];
+    corePath: string;
+}): Promise<ResolveResult>;

package/dist/resolve.js

@@ -0,0 +1,80 @@
+import { access, readFile, readdir } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { convertToParsedStory, createStoryRegistry, readStoryFile, resolveStories, } from '@storystick/core';
+/**
+ * Parse and resolve all .story files. No side effects (no file writes).
+ * Shared by generate, push, sync, and deterministic build tooling.
+ */
+export async function runResolve(options) {
+    const { rootDir, storyDirs, corePath } = options;
+    const allDiagnostics = [];
+    const nodeFs = {
+        async exists(path) {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        readdir: (path, opts) => readdir(path, opts),
+        resolve,
+        join,
+        dirname,
+    };
+    const registry = await createStoryRegistry({ rootDir, storyDirs, corePath }, nodeFs);
+    const parsed = new Map();
+    for (const id of registry.allIds()) {
+        const filePath = registry.resolve(id);
+        if (!filePath)
+            continue;
+        const content = await readFile(filePath, 'utf-8');
+        const readResult = readStoryFile(content, filePath);
+        allDiagnostics.push(...readResult.diagnostics);
+        if (!readResult.documents)
+            continue;
+        const convertResult = convertToParsedStory(readResult.documents);
+        allDiagnostics.push(...convertResult.diagnostics);
+        if (convertResult.story) {
+            const expectedId = registry.idFromPath(filePath);
+            if (expectedId !== convertResult.story.id) {
+                allDiagnostics.push({
+                    source: 'storystick',
+                    severity: 'error',
+                    code: 'STORY_ID_FILENAME_MISMATCH',
+                    message: `Story identifier '${convertResult.story.id}' does not match filename identity ` +
+                        `'${expectedId ?? '<unknown>'}'. Rename the file or update 'story:' so they match.`,
+                    file: filePath,
+                });
+                continue;
+            }
+            const existing = parsed.get(convertResult.story.id);
+            if (existing) {
+                allDiagnostics.push({
+                    source: 'storystick',
+                    severity: 'error',
+                    code: 'DUPLICATE_STORY_ID',
+                    message: `Story identifier '${convertResult.story.id}' is declared more than once.`,
+                    file: filePath,
+                    related: [
+                        {
+                            file: existing.filePath,
+                            message: 'First declaration is here.',
+                        },
+                    ],
+                });
+                continue;
+            }
+            parsed.set(convertResult.story.id, convertResult.story);
+        }
+    }
+    const resolveResult = resolveStories(parsed, registry);
+    allDiagnostics.push(...resolveResult.diagnostics);
+    const success = !allDiagnostics.some((diagnostic) => diagnostic.severity === 'error');
+    return {
+        stories: resolveResult.stories,
+        diagnostics: allDiagnostics,
+        success,
+    };
+}

package/dist/runtime-config.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_HUB_URL = "https://storystick.app";
+export declare const DEFAULT_GATEWAY_URL = "https://api.storystick.app";
+export interface CliRuntimeConfig {
+    hubUrl: string;
+    gatewayUrl: string;
+}
+export interface CliRuntimeConfigOptions {
+    rootDir?: string;
+    hubUrl?: string;
+    gatewayUrl?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveCliRuntimeConfig(options?: CliRuntimeConfigOptions): CliRuntimeConfig;
+export declare function readCliEnvValue(rootDir: string, name: string, env?: NodeJS.ProcessEnv): string | null;
+/** Credential issuers are origins, never project-controlled URL prefixes. */
+export declare function normalizeCliIssuer(raw: string, name?: string): string;
+/** Check the effective request URL before attaching a human credential. */
+export declare function cliIssuerRequestUrl(issuer: string, requestPath: string): string;

package/dist/runtime-config.js

@@ -0,0 +1,86 @@
+import { STORYSTICK_GATEWAY_ORIGIN, STORYSTICK_STUDIO_ORIGIN } from '@storystick/types/public-endpoints';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { StorystickError } from './cli-error.js';
+export const DEFAULT_HUB_URL = STORYSTICK_STUDIO_ORIGIN;
+export const DEFAULT_GATEWAY_URL = STORYSTICK_GATEWAY_ORIGIN;
+export function resolveCliRuntimeConfig(options = {}) {
+    const rootDir = resolve(options.rootDir ?? '.');
+    const env = options.env ?? process.env;
+    return {
+        hubUrl: normalizeCliIssuer(options.hubUrl ??
+            env.STORYSTICK_HUB_URL ??
+            readCliEnvValue(rootDir, 'STORYSTICK_HUB_URL', env) ??
+            DEFAULT_HUB_URL, 'STORYSTICK_HUB_URL'),
+        gatewayUrl: normalizeCliIssuer(options.gatewayUrl ??
+            env.STORYSTICK_GATEWAY_URL ??
+            readCliEnvValue(rootDir, 'STORYSTICK_GATEWAY_URL', env) ??
+            DEFAULT_GATEWAY_URL, 'STORYSTICK_GATEWAY_URL'),
+    };
+}
+export function readCliEnvValue(rootDir, name, env = process.env) {
+    if (Object.prototype.hasOwnProperty.call(env, name))
+        return env[name] ?? '';
+    for (const filename of ['.env.local', '.env']) {
+        const path = join(rootDir, filename);
+        if (!existsSync(path))
+            continue;
+        const content = readFileSync(path, 'utf8');
+        for (const line of content.split(/\r?\n/)) {
+            const match = line.match(new RegExp(`^${escapeRegExp(name)}\\s*=\\s*(.*)$`));
+            if (!match)
+                continue;
+            return unquote(match[1].trim());
+        }
+    }
+    return null;
+}
+/** Credential issuers are origins, never project-controlled URL prefixes. */
+export function normalizeCliIssuer(raw, name = 'STORYSTICK_GATEWAY_URL') {
+    const value = raw.trim();
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new StorystickError(`${name} must be a valid HTTP(S) URL.`, {
+            code: 'INVALID_RUNTIME_URL',
+            category: 'validation',
+        });
+    }
+    const localHttp = parsed.protocol === 'http:' &&
+        ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+    if ((parsed.protocol !== 'https:' && !localHttp) ||
+        parsed.username || parsed.password || parsed.search || parsed.hash ||
+        parsed.pathname !== '/') {
+        throw new StorystickError(`${name} must be an HTTPS origin (HTTP loopback is allowed for local development).`, {
+            code: 'INVALID_RUNTIME_URL',
+            category: 'validation',
+        });
+    }
+    return parsed.origin;
+}
+/** Check the effective request URL before attaching a human credential. */
+export function cliIssuerRequestUrl(issuer, requestPath) {
+    const origin = normalizeCliIssuer(issuer);
+    const target = new URL(requestPath, `${origin}/`);
+    if (target.origin !== origin || target.username || target.password || target.hash) {
+        throw new StorystickError('The CLI request must stay on its credential issuer.', {
+            code: 'AUTH_ISSUER_MISMATCH', category: 'auth', retryable: false,
+        });
+    }
+    return target.href;
+}
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/schema-export.d.ts

@@ -0,0 +1,10 @@
+export declare function exportSchema(options: {
+    rootDir: string;
+    storyDirs: string[];
+    corePath: string;
+    out: string;
+}): Promise<{
+    path: string;
+    schemaVersion: string;
+    storyCount: number;
+}>;

package/dist/schema-export.js

@@ -0,0 +1,28 @@
+import { mkdir, writeFile, rename, rm } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { sourcePath } from '@storystick/source/manifest';
+import { serializeSchema } from '@storystick/core/serializer';
+import { runResolve } from './resolve.js';
+export async function exportSchema(options) {
+    sourcePath(options.out);
+    const resolved = await runResolve(options);
+    if (!resolved.success)
+        throw Error('Schema validation failed: ' +
+            resolved.diagnostics
+                .filter((d) => d.severity === 'error')
+                .map((d) => d.message)
+                .join('\n'));
+    const schema = serializeSchema(resolved.stories, resolved.diagnostics);
+    const destination = resolve(options.rootDir, options.out);
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    await mkdir(dirname(destination), { recursive: true });
+    try {
+        await writeFile(temporary, JSON.stringify(schema, null, 2) + '\n', { flag: 'wx' });
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return { path: destination, schemaVersion: schema.version, storyCount: schema.storyCount };
+}

package/dist/setup.d.ts

@@ -0,0 +1,65 @@
+/** Inspection is local, read-only and never invokes package scripts. Only names
+ * and identities escape: no environment values, remote credentials or scripts. */
+export declare function inspectSetup(root: string): {
+    root: string;
+    connection: {
+        projectShortId: string;
+    } | null;
+    repository: {
+        root: string;
+        commit: string | null;
+        dirty: boolean;
+        remotes: string[];
+    } | null;
+    application: {
+        manifest: boolean;
+        framework: string | null;
+        scripts: string[];
+        packageManager: any;
+    };
+    source: {
+        configured: boolean;
+        scope: {
+            appRoot: string;
+            include: string[];
+            exclude: string[];
+        };
+        schemaVersion: string;
+        checks: string[];
+        previewPort: number;
+    } | {
+        configured: boolean;
+        scope?: undefined;
+        schemaVersion?: undefined;
+        checks?: undefined;
+        previewPort?: undefined;
+    };
+    hosting: {
+        provider: string;
+        projectId: any;
+        teamId: any;
+        status: string;
+    } | null;
+    issues: {
+        path: string;
+        message: string;
+    }[];
+    next: {
+        reason: string;
+        command: string;
+        args: string[];
+    }[];
+};
+/** A reviewed proposal becomes the local configuration. Never overwrite another
+ * configuration on retry, including one belonging to an active release. */
+export declare function configureSource(root: string, proposalPath: string): {
+    path: string;
+    configured: boolean;
+    changed: boolean;
+};
+/** A deliberately narrow preset. Monorepos keep their explicit dependency scope. */
+export declare function configureNextSource(root: string, schemaFile: string): {
+    path: string;
+    configured: boolean;
+    changed: boolean;
+};