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

package/assets/skills/storystick-development/references/story-and-next.md

@@ -0,0 +1,49 @@
+# Stories and Next.js
+
+Story files are the content grammar, not React components. Read local examples
+before editing. A slice uses `kind: slice`; reusable field fragments and `use`
+keep common content and style definitions shared. Add its ID to the appropriate
+page composition's allowed choices. Preserve existing choices and their options.
+Reference an existing document type for linked case studies or articles rather
+than copying that document's content into another schema.
+
+A typical local slice:
+
+```yaml
+story: numberedProcess
+kind: slice
+label: Numbered process
+use: [sectionStyle]
+---
+fields:
+  content:
+    headline:
+      type: text
+    steps:
+      type: processStep
+      array: true
+      min: 2
+      max: 8
+```
+
+Use the repository's generated types and component registry after generation.
+Do not hand-edit generated bindings or change the public SDK to fit a new slice.
+
+The Next.js starter initializes its existing server facade:
+
+```ts
+import { createSite } from '@storystick/next/server'
+import * as definition from '#storystick/query'
+export const site = createSite({ definition })
+```
+
+Its route calls `site.resolvePage(props)`, handles `redirect` and `document`
+results, and renders the existing `<SliceZone slices={...} components={...} />`.
+Follow the repository's actual composition field name and metadata conventions.
+Other queries should use its existing generated client, for example Coast's
+`client.query('siteSettings').selectAll().fetch()`. Inspect nearby queries and
+the installed version's types before choosing projections or relations.
+
+Preview context is provided by Storystick's integration. Do not add perspective
+parameters to public SDK APIs, mutate the site's DOM, or bypass the existing
+preview session protocol. Values crossing an RSC boundary must be plain data.

package/dist/_backfill-recommendation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pretty-print the optional `recommendBackfill` block surfaced by
+ * `schemas.push` (ADR-062 §D22). Lands two muted lines after the push
+ * success line so the user has the exact CLI invocation ready to copy.
+ * No-op when the recommendation is absent — the steady-state push path
+ * stays silent.
+ *
+ * Extracted from `cli.ts` so the format helper stays unit-testable
+ * without pulling in cac / process.exit / device-auth side effects.
+ */
+import type { BackfillRecommendation } from './push-client.js';
+export declare function printBackfillRecommendation(rec: BackfillRecommendation | undefined): void;

package/dist/_backfill-recommendation.js

@@ -0,0 +1,18 @@
+/**
+ * Pretty-print the optional `recommendBackfill` block surfaced by
+ * `schemas.push` (ADR-062 §D22). Lands two muted lines after the push
+ * success line so the user has the exact CLI invocation ready to copy.
+ * No-op when the recommendation is absent — the steady-state push path
+ * stays silent.
+ *
+ * Extracted from `cli.ts` so the format helper stays unit-testable
+ * without pulling in cac / process.exit / device-auth side effects.
+ */
+import pc from 'picocolors';
+import { logMessage } from './output.js';
+export function printBackfillRecommendation(rec) {
+    if (!rec)
+        return;
+    logMessage(pc.dim(`${rec.reason} Recommended:`));
+    logMessage(pc.dim(`  ${rec.command}`));
+}

package/dist/asset-import.d.ts

@@ -0,0 +1,50 @@
+import type { ImportTransport } from './content-import.js';
+export { assetImportTransport, uploadBudgetTransport } from './content-import.js';
+export interface UploadBudgetInput {
+    sessions: number;
+    bytes: number;
+    reason: string;
+}
+export declare function readUploadBudget(file: string): Promise<{
+    requestId: string;
+    input: UploadBudgetInput;
+}>;
+export interface ImportAssetInput {
+    namespace: string;
+    key: string;
+    assetType: 'image' | 'file' | 'video';
+    displayName: string;
+    originalFilename: string;
+    declaredMimeType: string;
+    declaredSizeBytes: number;
+    declaredChecksum: string;
+    altDefault?: string;
+    altDefaultMode?: 'text' | 'decorative';
+    captionDefault?: string;
+    copyright?: string;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+}
+export interface ImportAssetReceipt {
+    state: 'planned' | 'pending' | 'ready' | 'renewable';
+    planDigest: string;
+    inputDigest: string;
+    sizeBytes?: number;
+    assetId?: string;
+    version?: number;
+    uploadSessionId?: string;
+    expiresAt?: number;
+    reason?: string;
+}
+export declare function readAssetImport(manifestPath: string): Promise<{
+    file: string;
+    input: ImportAssetInput;
+}>;
+export declare function prepareAssetImport(transport: ImportTransport, input: ImportAssetInput): Promise<ImportAssetReceipt>;
+export declare function applyAssetImport(transport: ImportTransport, file: string, input: ImportAssetInput, planDigest: string, options?: {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+    renewSessionId?: string;
+}): Promise<ImportAssetReceipt>;

package/dist/asset-import.js

@@ -0,0 +1,160 @@
+/** Original-file import client. Only delegated PUTs leave the gateway path. */
+import { readFile, realpath, stat, open } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { preflightMediaUpload } from '@storystick/types/asset-upload-policy';
+import { importObject } from '@storystick/core/content-import';
+import { StorystickError } from './cli-error.js';
+export { assetImportTransport, uploadBudgetTransport } from './content-import.js';
+export async function readUploadBudget(file) {
+    const { requestId, ...input } = importObject(JSON.parse(await readFile(file, 'utf8')), 'upload budget');
+    if (typeof requestId !== 'string' || !/^[a-zA-Z0-9_-]{1,80}$/.test(requestId) ||
+        Object.keys(input).some(k => !['sessions', 'bytes', 'reason'].includes(k)) ||
+        typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 512 ||
+        !Number.isSafeInteger(input.sessions) || Number(input.sessions) < 1 || !Number.isSafeInteger(input.bytes) || Number(input.bytes) < 1) {
+        throw new Error('Expected requestId, positive integer sessions and bytes, and an explicit reason.');
+    }
+    return { requestId, input: input };
+}
+async function fingerprint(file, signal) {
+    const hash = createHash('sha256');
+    let size = 0;
+    for await (const bytes of createReadStream(file, { signal })) {
+        hash.update(bytes);
+        size += bytes.length;
+    }
+    return { size, checksum: hash.digest('hex') };
+}
+export async function readAssetImport(manifestPath) {
+    const directory = await realpath(dirname(resolve(manifestPath)));
+    const manifest = importObject(JSON.parse(await readFile(manifestPath, 'utf8')), 'asset manifest');
+    const { file: filename, mimeType, ...metadata } = manifest;
+    const allowed = ['namespace', 'key', 'displayName', 'altDefault', 'altDefaultMode', 'captionDefault', 'copyright', 'focalPoint'];
+    if (Object.keys(metadata).some(k => !allowed.includes(k)))
+        throw new Error('Unknown asset manifest property.');
+    if (typeof filename !== 'string' || isAbsolute(filename))
+        throw new Error('Asset file must be relative to its manifest.');
+    const file = await realpath(resolve(directory, filename)), rel = relative(directory, file);
+    if (rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+        throw new Error('Asset file must be inside its manifest directory.');
+    for (const name of ['namespace', 'key', 'displayName'])
+        if (typeof metadata[name] !== 'string' || !metadata[name].trim())
+            throw new Error(`Asset ${name} is required.`);
+    if (mimeType !== undefined && typeof mimeType !== 'string')
+        throw new Error('mimeType must be a string.');
+    const size = (await stat(file)).size, originalFilename = basename(file);
+    const policy = preflightMediaUpload({ declaredMimeType: mimeType, declaredSizeBytes: size, originalFilename });
+    if (!policy.ok)
+        throw new Error(policy.message);
+    const observed = await fingerprint(file);
+    if (observed.size !== size)
+        throw new Error('Asset file changed while reading.');
+    return { file, input: { ...metadata, assetType: policy.assetType, originalFilename,
+            declaredMimeType: policy.mimeType, declaredSizeBytes: size, declaredChecksum: observed.checksum } };
+}
+export async function prepareAssetImport(transport, input) {
+    return transport({ operation: 'plan', input });
+}
+async function transfer(capability, bytes, single, options) {
+    for (let attempt = 0;; attempt++) {
+        const receipt = await capability();
+        if (receipt.state === 'ready')
+            return receipt;
+        assertNotRenewable(receipt);
+        if (!receipt.uploadUrl || receipt.uploadMethod !== 'PUT')
+            throw new Error('Gateway did not return an upload capability.');
+        try {
+            const response = await (options.fetchImpl ?? fetch)(receipt.uploadUrl, {
+                method: 'PUT', headers: receipt.uploadHeaders, body: bytes,
+                signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(120_000)]) : AbortSignal.timeout(120_000),
+                redirect: 'error',
+            });
+            await response.body?.cancel();
+            // A create-once single PUT may have succeeded before its reply was lost.
+            if (response.ok || (single && response.status === 412))
+                return response;
+            throw new StorystickError('Original-file transfer did not complete.', {
+                status: response.status, retryable: [403, 408, 429, 500, 502, 503, 504].includes(response.status),
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted || attempt >= 4 || !(error instanceof TypeError || (error instanceof Error && error.name === 'TimeoutError') || (error instanceof StorystickError && error.retryable)))
+                throw error;
+            await delay(500 * 2 ** attempt, undefined, { signal: options.signal });
+        }
+    }
+}
+function assertNotRenewable(receipt) {
+    if (receipt.state === 'renewable')
+        throw new StorystickError(`Upload ${receipt.uploadSessionId} requires explicit renewal. Review its failure and apply with --renew ${receipt.uploadSessionId}.`, {
+            code: 'storystick/CONTENT_IMPORT_CONFLICT', status: 409, retryable: false, payload: receipt,
+        });
+}
+export async function applyAssetImport(transport, file, input, planDigest, options = {}) {
+    const observed = await fingerprint(file, options.signal);
+    if (observed.size !== input.declaredSizeBytes || observed.checksum !== input.declaredChecksum)
+        throw new Error('Asset file changed after planning.');
+    const request = { input, planDigest };
+    const begin = () => transport({ operation: options.renewSessionId ? 'renew' : 'begin', ...request,
+        ...(options.renewSessionId ? { expectedUploadSessionId: options.renewSessionId } : {}) });
+    const receipt = await begin();
+    if (receipt.state === 'ready')
+        return receipt;
+    assertNotRenewable(receipt);
+    if (receipt.state !== 'pending')
+        throw new Error('Gateway did not admit the asset upload.');
+    if (receipt.uploadMode === 'multipart') {
+        const partSize = receipt.partSizeBytes, totalParts = receipt.totalParts;
+        if (!Number.isSafeInteger(partSize) || partSize < 1 || partSize > 16 * 1024 * 1024 ||
+            !Number.isSafeInteger(totalParts) || totalParts !== Math.ceil(input.declaredSizeBytes / partSize))
+            throw new Error('Invalid multipart contract.');
+        const handle = await open(file, 'r');
+        try {
+            for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
+                options.signal?.throwIfAborted();
+                const offset = (partNumber - 1) * partSize, sizeBytes = Math.min(partSize, input.declaredSizeBytes - offset);
+                const bytes = Buffer.alloc(sizeBytes);
+                let read = 0;
+                while (read < sizeBytes) {
+                    const next = await handle.read(bytes, read, sizeBytes - read, offset + read);
+                    if (!next.bytesRead)
+                        throw new Error('Asset file changed during transfer.');
+                    read += next.bytesRead;
+                }
+                const checksumMd5 = createHash('md5').update(bytes).digest('base64');
+                if (receipt.parts?.some(p => p.partNumber === partNumber && p.sizeBytes === sizeBytes && p.checksumMd5 === checksumMd5))
+                    continue;
+                const part = { partNumber, checksumMd5 };
+                const response = await transfer(() => transport({ operation: 'prepare-part', ...request, part }), bytes, false, options);
+                if (!(response instanceof Response))
+                    return response;
+                const etag = response.headers.get('etag');
+                if (!etag)
+                    throw new Error('Multipart response has no ETag. The upload remains resumable.');
+                await transport({ operation: 'record-part', ...request, part: { ...part, etag, sizeBytes } });
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    else {
+        const bytes = await readFile(file);
+        if (bytes.length !== input.declaredSizeBytes || createHash('sha256').update(bytes).digest('hex') !== input.declaredChecksum)
+            throw new Error('Asset file changed after planning.');
+        let first = true;
+        const response = await transfer(() => { if (first) {
+            first = false;
+            return Promise.resolve(receipt);
+        } ; return begin(); }, bytes, true, options);
+        if (!(response instanceof Response))
+            return response;
+    }
+    const result = await transport({ operation: 'finalize', ...request });
+    assertNotRenewable(result);
+    if (result.state !== 'ready')
+        throw new Error('Asset import has no verified ready receipt.');
+    return result;
+}

package/dist/assistant-read-client.d.ts

@@ -0,0 +1,3 @@
+import type { HubApiOptions } from './hub-client.js';
+/** Reuses the operator session. No project secret, browser login or token minting. */
+export declare function readProjectCapability(projectShortId: string, request: Record<string, unknown>, options?: Pick<HubApiOptions, 'gatewayUrl' | 'rootDir' | 'fetchImpl' | 'signal'>): Promise<Record<string, unknown>>;

package/dist/assistant-read-client.js

@@ -0,0 +1,8 @@
+import { callHubApi } from './hub-client.js';
+/** Reuses the operator session. No project secret, browser login or token minting. */
+export function readProjectCapability(projectShortId, request, options = {}) {
+    return callHubApi('/api/cli/project-read', {
+        ...options, method: 'POST', body: { projectShortId, request },
+        interactiveAuth: false, timeoutMs: 30_000,
+    });
+}

package/dist/auth-device.d.ts

@@ -0,0 +1,153 @@
+/**
+ * CLI device-auth client (SPEC-1 Item #2).
+ *
+ * Standard device-auth flow from the CLI's perspective:
+ *
+ *   1. POST /api/auth/device/start → receive deviceCode + userCode + URL
+ *   2. Print URL + userCode to the terminal
+ *   3. Poll /api/auth/device/poll every 3 seconds with deviceCode
+ *   4. On status=authorized, persist the returned JWT to
+ *      `~/.config/storystick/auth-<issuer-hash>.json` (chmod 600) and return
+ *   5. On status=expired: fail with a clear message
+ *   6. On user Ctrl-C: fail quietly, no token written
+ *
+ * Token file layout (spec §Token storage path):
+ *
+ *   {
+ *     "issuer":    "https://api.storystick.app",
+ *     "token":     "eyJ...",         ← CLI JWT (typ: "cli"), 30d
+ *     "expiresAt": 1735689600000,    ← epoch-ms, matches JWT `exp`
+ *     "userId":    "user_xyz",       ← for info/whoami without a ping
+ *     "email":     "you@…"           ← cached, not security-sensitive
+ *   }
+ *
+ * File location follows XDG:
+ *   - `$XDG_CONFIG_HOME/storystick/auth-<issuer-hash>.json` if set
+ *   - else `~/.config/storystick/auth-<issuer-hash>.json`
+ *
+ * Permissions:
+ *   - Parent dir: 0o700 (user-only read/write/execute)
+ *   - File:       0o600 (user-only read/write)
+ *
+ * This is the sole CLI user-session store. Project API keys remain separate
+ * credentials and never stand in for user authority.
+ */
+/**
+ * Resolve the token-file directory per XDG. Public so tests can stub
+ * HOME + XDG env vars and assert the resolved path.
+ */
+export declare function authDir(): string;
+export declare function authFilePath(issuer: string): string;
+export interface StoredAuth {
+    /** Canonical gateway that issued this credential. Never inferred from a project. */
+    issuer: string;
+    /** Signed CLI JWT (typ: "cli"). */
+    token: string;
+    /** Epoch-ms expiry copied from the JWT claim. Checked locally to avoid
+     * one bogus network round-trip when the token has obviously aged out. */
+    expiresAt: number;
+    /** Convex user id — cached so `storystick info` can say who's signed in
+     * without a ping. Not security-sensitive. */
+    userId: string;
+    /** Cached email, same rationale as userId. */
+    email?: string;
+}
+/**
+ * Read the cached CLI session. Returns null when:
+ *   - file does not exist
+ *   - file is unreadable (permissions / corruption)
+ *   - JSON is malformed
+ *   - required fields are missing
+ *   - `expiresAt` has passed (local preflight — the Hub is the source of truth)
+ */
+export declare function getAuthToken(issuer: string): string | null;
+/** An unbound/corrupt credential requires a deliberate login, never inference. */
+export declare function requiresExplicitAuthLogin(issuer: string): boolean;
+/**
+ * Lower-level read — returns the whole struct so callers like `whoami`
+ * can display userId/email without re-parsing.
+ */
+export declare function loadAuth(issuer: string): StoredAuth | null;
+/**
+ * Persist this issuer’s session atomically. Separate files keep concurrent
+ * logins to different environments from replacing each other. Old unbound
+ * auth.json files are never loaded; their owners must log in again.
+ */
+export declare function saveAuth(auth: StoredAuth, options?: {
+    faultAt?: 'before-rename';
+}): void;
+/**
+ * Wipe the token file. Missing file is a no-op — `logout` should always
+ * succeed (same intent as `rm -f`).
+ */
+export declare function clearAuthToken(issuer: string): Promise<void>;
+export declare function revokeAuthSession(options?: {
+    gatewayUrl?: string;
+    rootDir?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<'revoked' | 'not-authenticated'>;
+export declare function logoutAuthSession(options?: {
+    localOnly?: boolean;
+    gatewayUrl?: string;
+    rootDir?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<'revoked' | 'not-authenticated' | 'local-only'>;
+/**
+ * Return `{ userId, email }` from the local cache, or null when nothing is
+ * cached (or the cache has expired). Backs `storystick info` / `whoami`.
+ */
+export declare function whoami(options?: {
+    gatewayUrl?: string;
+    rootDir?: string;
+}): Promise<{
+    userId: string;
+    email: string | null;
+} | null>;
+export interface LoginOptions {
+    /** Override Central's HTTP-actions URL (convex.site). Rarely useful in
+     * practice — default works for prod. Tests stub this to point at a mock. */
+    gatewayUrl?: string;
+    /** Override the Hub URL shown to the user. Used in dev where the URL is
+     * `http://storystick.dojo:3000` rather than the prod `storystick.app`. */
+    hubUrl?: string;
+    /** Optional device label shown on the Hub approval page ("MacBook Pro de
+     * Tanguy"). Defaults to the machine's hostname if not provided. */
+    deviceName?: string;
+    /** Hook called exactly once with the user-facing instructions (verification
+     * URL + userCode + expiresIn). The CLI prints them from this callback. */
+    onPrompt?: (data: {
+        issuer: string;
+        verificationUrl: string;
+        userCode: string;
+        expiresIn: number;
+    }) => void;
+    /** Hook called on each poll cycle while the status is `pending`. Lets the
+     * caller update a spinner / refresh a TTY line. */
+    onPoll?: () => void;
+    /** Fetch implementation — tests inject a mock. Default is `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Override the poll cadence (ms). Tests drop this to 1 so they don't wait
+     * 3 seconds per iteration. */
+    pollIntervalMs?: number;
+    /** Abort signal for Ctrl-C / programmatic cancel. */
+    signal?: AbortSignal;
+    /** Deadline for each start/poll HTTP request. */
+    timeoutMs?: number;
+    /** Root used to resolve canonical runtime env overrides. */
+    rootDir?: string;
+}
+/**
+ * Drive the full device-auth flow.
+ *
+ * On success: writes `auth.json`, returns the token.
+ * On failure: throws a human-readable `Error`; nothing written.
+ *
+ * The function does NOT print anything directly — printing is the CLI
+ * command's responsibility. This keeps `deviceAuthLogin` testable without
+ * piping stdout around.
+ */
+export declare function deviceAuthLogin(options?: LoginOptions): Promise<string>;