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

package/dist/project-access.d.ts

@@ -0,0 +1,18 @@
+export type TeamRole = 'owner' | 'admin' | 'member';
+export type ContentRole = 'editor' | 'viewer';
+export type ProjectAccessSource = 'team' | 'direct' | 'override';
+export interface ProjectCapabilities {
+    readContent: boolean;
+    writeContent: boolean;
+    configureContent: boolean;
+    configureProject: boolean;
+    manageProjectAccess: boolean;
+    manageProjectCredentials: boolean;
+    archiveProject: boolean;
+}
+export interface ProjectAccessSummary {
+    teamRole: TeamRole | null;
+    contentRole: ContentRole;
+    accessSource: ProjectAccessSource;
+    capabilities: ProjectCapabilities;
+}

package/dist/project-access.js

@@ -0,0 +1 @@
+export {};

package/dist/project-connection.d.ts

@@ -0,0 +1,62 @@
+export declare const PROJECT_CONNECTION_ENV_KEYS: readonly ["STORYSTICK_PROJECT_ID", "NEXT_PUBLIC_STORYSTICK_PROJECT_ID", "STORYSTICK_API_KEY", "NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY"];
+export type ProjectConnectionEnvKey = (typeof PROJECT_CONNECTION_ENV_KEYS)[number];
+export interface ProjectConnectionValues {
+    projectId: string;
+    publicProjectId: string;
+    apiKey: string;
+    publishableKey: string;
+}
+/** Validated connection: both ids and both key prefixes already agree. */
+export interface ProjectConnection {
+    shortId: string;
+    apiKey: string;
+    publishableKey: string;
+    keyEnvironment: 'live' | 'test';
+}
+export interface LocatedProjectConnection extends ProjectConnection {
+    source: 'environment' | 'env-file';
+    envFile: string | null;
+}
+export interface ProjectConnectionChange {
+    name: ProjectConnectionEnvKey;
+    action: 'set' | 'replace' | 'unchanged';
+    /** Safe for human and JSON output. Secret values are always redacted. */
+    value: string;
+}
+export interface ProjectConnectionWriteResult {
+    envFile: string;
+    created: boolean;
+    changed: boolean;
+    dryRun: boolean;
+    changes: ProjectConnectionChange[];
+}
+export declare function parseProjectConnection(values: ProjectConnectionValues): ProjectConnection;
+export declare function projectConnectionValues(connection: ProjectConnection): Record<ProjectConnectionEnvKey, string>;
+/**
+ * Resolve one complete authority. If any process-level connection variable is
+ * present, all four must be present and coherent; values are never mixed with
+ * a file. Otherwise the nearest `.env.local` containing any connection field
+ * is parsed as one indivisible unit.
+ */
+export declare function resolveProjectConnection(startDir?: string, env?: NodeJS.ProcessEnv): LocatedProjectConnection | null;
+export declare function requireProjectConnection(startDir?: string, env?: NodeJS.ProcessEnv): LocatedProjectConnection;
+/** Find the nearest `.env.local` containing at least one connection field. */
+export declare function findProjectConnectionEnvFile(startDir?: string): string | null;
+/**
+ * Commit the four values through one temp-file + fsync + rename transaction.
+ * The returned plan is safe to serialize; it never contains either key.
+ */
+export declare function commitProjectConnection(envFile: string, connection: ProjectConnection, options?: {
+    dryRun?: boolean;
+    faultAt?: 'before-rename';
+}): ProjectConnectionWriteResult;
+/** Safe dry-run plan for connect before any credential has been minted. */
+export declare function planProjectConnection(envFile: string, shortId: string): ProjectConnectionWriteResult;
+/** Validate the JWT returned by the secret-key exchange before local commit. */
+export declare function validateProjectTokenReadback(token: string, connection: ProjectConnection): void;
+export declare function redactProjectSecrets(text: string): string;
+export declare function parseProjectShortId(value: string, field?: string): string;
+export declare function parseEnvAssignment(line: string): {
+    key: string;
+    value: string;
+} | null;

package/dist/project-connection.js

@@ -0,0 +1,347 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { StorystickError } from './cli-error.js';
+export const PROJECT_CONNECTION_ENV_KEYS = [
+    'STORYSTICK_PROJECT_ID',
+    'NEXT_PUBLIC_STORYSTICK_PROJECT_ID',
+    'STORYSTICK_API_KEY',
+    'NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY',
+];
+const SHORT_ID_PATTERN = /^[0-9a-hjkmnp-tv-z]{8}$/;
+const API_KEY_PATTERN = /^ss_(sk|pk)_(live|test)_([0-9a-hjkmnp-tv-z]{8})_([A-Za-z0-9]{20,})$/;
+const SECRET_PATTERN = /ss_(?:sk|pk)_(?:live|test)_[0-9a-hjkmnp-tv-z]{8}_[A-Za-z0-9]{20,}/g;
+const REDACTED = '[redacted]';
+export function parseProjectConnection(values) {
+    const projectId = parseProjectShortId(values.projectId, 'STORYSTICK_PROJECT_ID');
+    const publicProjectId = parseProjectShortId(values.publicProjectId, 'NEXT_PUBLIC_STORYSTICK_PROJECT_ID');
+    if (projectId !== publicProjectId) {
+        throw connectionError('STORYSTICK_PROJECT_ID and NEXT_PUBLIC_STORYSTICK_PROJECT_ID must match.', 'PROJECT_CONNECTION_ID_MISMATCH');
+    }
+    const secret = parseApiKey(values.apiKey, 'secret');
+    const publishable = parseApiKey(values.publishableKey, 'publishable');
+    if (secret.shortId !== projectId || publishable.shortId !== projectId) {
+        throw connectionError('Both Storystick keys must belong to the configured project shortId.', 'PROJECT_CONNECTION_KEY_MISMATCH');
+    }
+    if (secret.environment !== publishable.environment) {
+        throw connectionError('The secret and publishable Storystick keys must use the same environment.', 'PROJECT_CONNECTION_ENV_MISMATCH');
+    }
+    return {
+        shortId: projectId,
+        apiKey: values.apiKey,
+        publishableKey: values.publishableKey,
+        keyEnvironment: secret.environment,
+    };
+}
+export function projectConnectionValues(connection) {
+    return {
+        STORYSTICK_PROJECT_ID: connection.shortId,
+        NEXT_PUBLIC_STORYSTICK_PROJECT_ID: connection.shortId,
+        STORYSTICK_API_KEY: connection.apiKey,
+        NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY: connection.publishableKey,
+    };
+}
+/**
+ * Resolve one complete authority. If any process-level connection variable is
+ * present, all four must be present and coherent; values are never mixed with
+ * a file. Otherwise the nearest `.env.local` containing any connection field
+ * is parsed as one indivisible unit.
+ */
+export function resolveProjectConnection(startDir = process.cwd(), env = process.env) {
+    const environment = connectionValuesFromEnvironment(env);
+    if (environment.present) {
+        return {
+            ...parseProjectConnection(environment.values),
+            source: 'environment',
+            envFile: null,
+        };
+    }
+    const envFile = findProjectConnectionEnvFile(startDir);
+    if (!envFile)
+        return null;
+    const parsed = connectionValuesFromText(readFileSync(envFile, 'utf8'), envFile);
+    return {
+        ...parseProjectConnection(parsed),
+        source: 'env-file',
+        envFile,
+    };
+}
+export function requireProjectConnection(startDir = process.cwd(), env = process.env) {
+    const connection = resolveProjectConnection(startDir, env);
+    if (connection)
+        return connection;
+    throw connectionError(`No ProjectConnection found from ${resolve(startDir)}. Run \`storystick connect <shortId> --root ${resolve(startDir)}\`.`, 'PROJECT_CONNECTION_MISSING');
+}
+/** Find the nearest `.env.local` containing at least one connection field. */
+export function findProjectConnectionEnvFile(startDir = process.cwd()) {
+    let directory = resolve(startDir);
+    for (let depth = 0; depth < 64; depth += 1) {
+        const envFile = join(directory, '.env.local');
+        if (existsSync(envFile) &&
+            containsProjectConnectionField(readFileSync(envFile, 'utf8'))) {
+            return envFile;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+    return null;
+}
+/**
+ * Commit the four values through one temp-file + fsync + rename transaction.
+ * The returned plan is safe to serialize; it never contains either key.
+ */
+export function commitProjectConnection(envFile, connection, options = {}) {
+    // Revalidate at the write boundary so callers cannot fabricate the branded
+    // shape with a type assertion and bypass the invariant.
+    const valid = parseProjectConnection({
+        projectId: connection.shortId,
+        publicProjectId: connection.shortId,
+        apiKey: connection.apiKey,
+        publishableKey: connection.publishableKey,
+    });
+    const destination = resolve(envFile);
+    const existed = existsSync(destination);
+    const before = existed ? readFileSync(destination, 'utf8') : '';
+    const desired = projectConnectionValues(valid);
+    const after = replaceProjectConnectionBlock(before, desired);
+    const result = {
+        envFile: destination,
+        created: !existed,
+        changed: before !== after,
+        dryRun: options.dryRun === true,
+        changes: safeChanges(before, desired),
+    };
+    if (options.dryRun === true || before === after)
+        return result;
+    const directory = dirname(destination);
+    const temporary = join(directory, `.${basename(destination)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = openSync(temporary, 'wx', 0o600);
+        writeFileSync(handle, after, 'utf8');
+        fsyncSync(handle);
+        closeSync(handle);
+        handle = undefined;
+        if (options.faultAt === 'before-rename') {
+            throw new Error('PROJECT_CONNECTION_FAULT_BEFORE_RENAME');
+        }
+        renameSync(temporary, destination);
+        chmodSync(destination, 0o600);
+        fsyncDirectoryBestEffort(directory);
+        return result;
+    }
+    catch (error) {
+        if (handle !== undefined)
+            closeSync(handle);
+        try {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+        catch {
+            // Preserve the original transaction failure.
+        }
+        throw error;
+    }
+}
+/** Safe dry-run plan for connect before any credential has been minted. */
+export function planProjectConnection(envFile, shortId) {
+    const normalized = parseProjectShortId(shortId, 'project shortId');
+    const destination = resolve(envFile);
+    const existed = existsSync(destination);
+    const before = existed ? readFileSync(destination, 'utf8') : '';
+    const old = firstConnectionValues(before);
+    return {
+        envFile: destination,
+        created: !existed,
+        changed: true,
+        dryRun: true,
+        changes: PROJECT_CONNECTION_ENV_KEYS.map((name) => ({
+            name,
+            action: old.has(name) ? 'replace' : 'set',
+            value: isSecretKey(name) ? REDACTED : normalized,
+        })),
+    };
+}
+/** Validate the JWT returned by the secret-key exchange before local commit. */
+export function validateProjectTokenReadback(token, connection) {
+    let payload;
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            throw new Error('missing payload');
+        payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw connectionError('Gateway returned an unreadable project token.', 'PROJECT_TOKEN_READBACK_INVALID');
+    }
+    const expectedEnv = connection.keyEnvironment === 'live' ? 'prod' : 'preview';
+    if (payload.projectId !== connection.shortId ||
+        payload.scope !== 'full' ||
+        payload.env !== expectedEnv) {
+        throw connectionError('Gateway token does not match the proposed ProjectConnection.', 'PROJECT_TOKEN_READBACK_MISMATCH');
+    }
+}
+export function redactProjectSecrets(text) {
+    return text.replace(SECRET_PATTERN, REDACTED);
+}
+function parseApiKey(value, expectedType) {
+    const match = API_KEY_PATTERN.exec(value);
+    const expectedCode = expectedType === 'secret' ? 'sk' : 'pk';
+    if (!match || match[1] !== expectedCode) {
+        const variable = expectedType === 'secret'
+            ? 'STORYSTICK_API_KEY'
+            : 'NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY';
+        throw connectionError(`${variable} is not a valid ${expectedType} Storystick key.`, 'PROJECT_CONNECTION_KEY_INVALID');
+    }
+    return {
+        environment: match[2],
+        shortId: match[3],
+    };
+}
+export function parseProjectShortId(value, field = 'project shortId') {
+    const normalized = value.trim().toLowerCase();
+    if (!SHORT_ID_PATTERN.test(normalized)) {
+        throw connectionError(`${field} must be an 8-character Storystick project shortId.`, 'PROJECT_CONNECTION_ID_INVALID');
+    }
+    return normalized;
+}
+function connectionValuesFromEnvironment(env) {
+    const present = PROJECT_CONNECTION_ENV_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(env, key));
+    if (present.length === 0) {
+        return {
+            present: false,
+            values: { projectId: '', publicProjectId: '', apiKey: '', publishableKey: '' },
+        };
+    }
+    if (present.length !== PROJECT_CONNECTION_ENV_KEYS.length) {
+        throw connectionError('Process environment contains a partial ProjectConnection; provide all four variables or none.', 'PROJECT_CONNECTION_PARTIAL');
+    }
+    return {
+        present: true,
+        values: {
+            projectId: env.STORYSTICK_PROJECT_ID ?? '',
+            publicProjectId: env.NEXT_PUBLIC_STORYSTICK_PROJECT_ID ?? '',
+            apiKey: env.STORYSTICK_API_KEY ?? '',
+            publishableKey: env.NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY ?? '',
+        },
+    };
+}
+function connectionValuesFromText(content, source) {
+    const values = new Map();
+    for (const line of content.split(/\r?\n/)) {
+        const parsed = parseEnvAssignment(line);
+        if (!parsed || !isConnectionKey(parsed.key))
+            continue;
+        if (values.has(parsed.key)) {
+            throw connectionError(`${source} contains duplicate ${parsed.key} entries.`, 'PROJECT_CONNECTION_DUPLICATE');
+        }
+        values.set(parsed.key, parsed.value);
+    }
+    const missing = PROJECT_CONNECTION_ENV_KEYS.filter((key) => !values.has(key));
+    if (missing.length > 0) {
+        throw connectionError(`${source} contains a partial ProjectConnection; missing ${missing.join(', ')}.`, 'PROJECT_CONNECTION_PARTIAL');
+    }
+    return {
+        projectId: values.get('STORYSTICK_PROJECT_ID'),
+        publicProjectId: values.get('NEXT_PUBLIC_STORYSTICK_PROJECT_ID'),
+        apiKey: values.get('STORYSTICK_API_KEY'),
+        publishableKey: values.get('NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY'),
+    };
+}
+function replaceProjectConnectionBlock(content, desired) {
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const body = content.replace(/(?:\r?\n)$/, '');
+    const lines = body.length > 0 ? body.split(/\r?\n/) : [];
+    const connectionLines = PROJECT_CONNECTION_ENV_KEYS.map((key) => `${key}=${desired[key]}`);
+    const next = [];
+    let inserted = false;
+    for (const line of lines) {
+        const parsed = parseEnvAssignment(line);
+        if (parsed && isConnectionKey(parsed.key)) {
+            if (!inserted) {
+                next.push(...connectionLines);
+                inserted = true;
+            }
+            continue;
+        }
+        next.push(line);
+    }
+    if (!inserted)
+        next.push(...connectionLines);
+    return next.join(newline) + newline;
+}
+function safeChanges(before, desired) {
+    const old = firstConnectionValues(before);
+    return PROJECT_CONNECTION_ENV_KEYS.map((name) => ({
+        name,
+        action: !old.has(name)
+            ? 'set'
+            : old.get(name) === desired[name]
+                ? 'unchanged'
+                : 'replace',
+        value: isSecretKey(name) ? REDACTED : desired[name],
+    }));
+}
+function firstConnectionValues(content) {
+    const values = new Map();
+    for (const line of content.split(/\r?\n/)) {
+        const parsed = parseEnvAssignment(line);
+        if (parsed && isConnectionKey(parsed.key) && !values.has(parsed.key)) {
+            values.set(parsed.key, parsed.value);
+        }
+    }
+    return values;
+}
+function containsProjectConnectionField(content) {
+    return content.split(/\r?\n/).some((line) => {
+        const parsed = parseEnvAssignment(line);
+        return parsed !== null && isConnectionKey(parsed.key);
+    });
+}
+export function parseEnvAssignment(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#'))
+        return null;
+    const equals = trimmed.indexOf('=');
+    if (equals < 1)
+        return null;
+    const key = trimmed.slice(0, equals).trim();
+    let value = trimmed.slice(equals + 1).trim();
+    if (value.length >= 2 &&
+        ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'")))) {
+        value = value.slice(1, -1);
+    }
+    return { key, value };
+}
+function isConnectionKey(key) {
+    return PROJECT_CONNECTION_ENV_KEYS.includes(key);
+}
+function isSecretKey(key) {
+    return (key === 'STORYSTICK_API_KEY' ||
+        key === 'NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY');
+}
+function connectionError(message, code) {
+    return new StorystickError(message, {
+        code,
+        category: 'validation',
+        recoverable: true,
+        retryable: false,
+    });
+}
+function fsyncDirectoryBestEffort(directory) {
+    let handle;
+    try {
+        handle = openSync(directory, 'r');
+        fsyncSync(handle);
+    }
+    catch {
+        // File data is already fsynced and rename is atomic on supported targets.
+    }
+    finally {
+        if (handle !== undefined)
+            closeSync(handle);
+    }
+}

package/dist/project-execution-client.d.ts

@@ -0,0 +1,2 @@
+import { type HubApiOptions } from './hub-client.js';
+export declare function executeProjectCapability(projectShortId: string, request: Record<string, unknown>, options?: Pick<HubApiOptions, 'gatewayUrl' | 'rootDir' | 'fetchImpl' | 'signal'>): Promise<Record<string, unknown>>;

package/dist/project-execution-client.js

@@ -0,0 +1,33 @@
+import { callHubApi } from './hub-client.js';
+import { resolveCliRuntimeConfig } from './runtime-config.js';
+import { resolveReleaseContext } from './release-context.js';
+import { resolve } from 'node:path';
+export async function executeProjectCapability(projectShortId, request, options = {}) {
+    // Observe the same selection as push/sync. It is client context, never an
+    // implicit replacement for a journal's server-owned editorial scopes.
+    let cliReleaseContext;
+    if (request.operation === 'begin' || request.operation === 'status') {
+        const rootDir = resolve(options.rootDir ?? '.');
+        const { gatewayUrl } = resolveCliRuntimeConfig({ rootDir, gatewayUrl: options.gatewayUrl });
+        try {
+            const selected = resolveReleaseContext(rootDir, gatewayUrl);
+            cliReleaseContext = selected && selected.projectShortId !== projectShortId
+                ? { projectShortId, errorCode: 'CLI_RELEASE_CONTEXT_PROJECT_MISMATCH' }
+                : { projectShortId, releaseId: selected?.releaseId ?? null };
+        }
+        catch {
+            cliReleaseContext = { projectShortId, errorCode: 'CLI_RELEASE_CONTEXT_INVALID' };
+        }
+    }
+    // A cold workspace installation can outlive the ordinary content request deadline.
+    // Host cancellation is still forwarded; the server owns the hard VM lifetime.
+    const input = request.input;
+    const runtimeCall = request.operation === 'call' && request.toolName === 'projectCode' &&
+        (input?.operation === 'check' || input?.operation === 'preview' || input?.operation === 'exec');
+    const result = await callHubApi('/api/cli/project-execution', {
+        ...options, method: 'POST', body: { projectShortId, request }, interactiveAuth: false, timeoutMs: runtimeCall ? 610_000 : 60_000,
+    });
+    return cliReleaseContext && result.context && typeof result.context === 'object'
+        ? { ...result, context: { ...result.context, cliReleaseContext } }
+        : result;
+}

package/dist/push-client.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 { STORY_SCHEMA_FORMAT_VERSION, type SchemaChangePlanV1, type SerializedSchema } from '@storystick/types';
+/**
+ * Body of `POST /api/m/schemas/push`. Mirrors the args of the backend
+ * Component's `schemas.push` mutation. Kept as a structural type (not
+ * imported from the backend) so this module doesn't depend on Convex
+ * code — the CLI must stay buildable in environments without Convex.
+ */
+export interface SchemaPushBody {
+    formatVersion: typeof STORY_SCHEMA_FORMAT_VERSION;
+    version: string;
+    stories: any;
+    storyCount: number;
+    zoneMappings?: any;
+    fieldBindings?: any;
+    diagnostics?: any;
+}
+export interface NewBindingNote {
+    docType: string;
+    sliceType: string;
+    sliceField: string;
+    sourcePath: string;
+    message: string;
+}
+/**
+ * Surfaced by `schemas.push` when the ref-relevant schema view has shifted
+ * since the last successful project-wide backfill (ADR-062 §D22). The CLI
+ * prints `command` after the success line so the user has the exact
+ * invocation ready to copy-paste. Absent on pushes that don't change the
+ * ref-relevant view (which is the steady-state case).
+ */
+export interface BackfillRecommendation {
+    command: string;
+    reason: string;
+}
+export interface SchemaPushResult {
+    projectionSeq: number;
+    status: 'pushed' | 'unchanged';
+    version: string;
+    newBindingNotes: NewBindingNote[];
+    /** Optional recommendation — see `BackfillRecommendation`. */
+    recommendBackfill?: BackfillRecommendation;
+}
+export interface SchemaPushFence {
+    expectedBaseVersion: string | null;
+    planDigest: string;
+}
+export interface ProjectRequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * 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 declare function schemaToPushBody(schema: SerializedSchema): SchemaPushBody;
+/**
+ * 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 declare function pushSchema(siteUrl: string, token: string, body: SchemaPushBody, fence: SchemaPushFence, options?: ProjectRequestOptions): Promise<SchemaPushResult>;
+export declare function fetchSchemaChangePlan(siteUrl: string, token: string, body: SchemaPushBody, options?: ProjectRequestOptions): Promise<SchemaChangePlanV1>;
+export declare function schemaPlanFence(plan: SchemaChangePlanV1): SchemaPushFence;
+export declare function assertSchemaPlanAllowed(plan: SchemaChangePlanV1): void;
+/**
+ * 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 declare function fetchSchemaPushToken(siteUrl: string, apiKey: string, options?: ProjectRequestOptions): Promise<string>;