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

package/dist/hub-client.js

@@ -0,0 +1,178 @@
+/**
+ * Hub API client (SPEC-1 Item #3 — session-expired UX).
+ *
+ * Every CLI command that calls a user-scoped Hub endpoint MUST route through
+ * `callHubApi`. Two things it guarantees:
+ *
+ *   1. **Lazy 401 recovery.** If the CLI JWT has expired, the Hub returns
+ *      401. Instead of dumping a stack trace and exiting, we print a single
+ *      friendly line, launch device-auth login inline, and retry the original
+ *      request ONCE. Second 401 on retry propagates — we do not loop.
+ *
+ *   2. **Structured error surface.** The Hub's Pattern D error envelope is
+ *      `{ code, message }`; on non-2xx responses we throw a `StorystickError`
+ *      whose message ends with the Hub's message, tacked with `(code)` when
+ *      present. Command-level code prints these directly without extra
+ *      wrapping.
+ *
+ * Edge cases (per spec §Edge cases):
+ *
+ *   - 403 Forbidden → do NOT retry. Treated as "valid token, insufficient
+ *     rights" (e.g. user removed from project mid-session, endpoint requires
+ *     admin). Surface verbatim.
+ *   - 429 on retry → do NOT retry again. The first call already burned the
+ *     per-IP bucket; a second retry would just slam it harder.
+ *   - User cancels re-auth (Ctrl-C, closes browser, polls expire) →
+ *     `deviceAuthLogin` throws; we repackage as `StorystickError('Login
+ *     cancelled.')` so commands can catch + exit 1 without a stack trace.
+ *
+ * This module deliberately takes NO dependency on commander/cac/pc — it is
+ * pure transport. The CLI command layer owns all user-facing printing.
+ */
+import { deviceAuthLogin, getAuthToken, requiresExplicitAuthLogin, } from './auth-device.js';
+import { StorystickError, storystickErrorFromResponse } from './cli-error.js';
+import { getOutputMode, logWarning, promptDeviceAuth, stopSpinner, } from './output.js';
+import { cliIssuerRequestUrl, DEFAULT_GATEWAY_URL, resolveCliRuntimeConfig } from './runtime-config.js';
+import { fetchWithDeadline } from './transport.js';
+import { contentShapeCapabilityHeaders } from '@storystick/types';
+// `StorystickError` lives in `./cli-error.js` (ADR-072 §D3 / lock A6 —
+// no re-export from this module; consumers import directly).
+// ─────────────────────────────────────────────────────────────
+// Entry point
+// ─────────────────────────────────────────────────────────────
+/**
+ * Call a Hub user-scoped endpoint with automatic retry-on-401.
+ *
+ * Success path: returns the parsed JSON body.
+ * Failure path: throws `StorystickError` with a clean, user-facing message.
+ */
+export async function callHubApi(path, options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const runtime = resolveCliRuntimeConfig({
+        rootDir: options.rootDir,
+        gatewayUrl: options.gatewayUrl ?? options.login?.gatewayUrl,
+        hubUrl: options.login?.hubUrl,
+    });
+    // Step 1 — obtain a token. If nothing is cached (first run of any
+    // user-scoped command after `storystick logout`), trigger device-auth
+    // upfront so the user sees the login prompt before the "it didn't work"
+    // message.
+    let token = getAuthToken(runtime.gatewayUrl);
+    if (!token) {
+        if (!mayStartInteractiveAuth(options, runtime.gatewayUrl))
+            throw authRequiredError(runtime.gatewayUrl);
+        token = await runDeviceAuthLogin(options, runtime);
+    }
+    // Step 2 — first attempt.
+    let res = await doCall(fetchImpl, runtime.gatewayUrl, path, token, options);
+    // Step 3 — on 401, re-auth once and retry.
+    if (res.status === 401) {
+        if (!mayStartInteractiveAuth(options, runtime.gatewayUrl))
+            throw authRequiredError(runtime.gatewayUrl);
+        // Single friendly line — keep it terse; the device-auth prompt prints
+        // next. Spec text: "Your session has expired. Logging you back in..."
+        logWarning('Your session has expired. Logging you back in...');
+        token = await runDeviceAuthLogin(options, runtime);
+        res = await doCall(fetchImpl, runtime.gatewayUrl, path, token, options);
+        // If the second call is ALSO 401, fall through to the generic error
+        // handling below — we do NOT loop.
+    }
+    if (!res.ok) {
+        throw await storystickErrorFromResponse(res, `HTTP ${res.status} ${res.statusText}`.trim());
+    }
+    // Some endpoints legitimately return 204 No Content. Guard the JSON parse.
+    if (res.status === 204)
+        return undefined;
+    if (options.responseType === 'bytes')
+        return new Uint8Array(await res.arrayBuffer());
+    return (await res.json());
+}
+function mayStartInteractiveAuth(options, gatewayUrl) {
+    // Project/env configuration can select a bound session, but cannot start a
+    // new device flow against another issuer behind the standard Hub prompt.
+    if (gatewayUrl !== DEFAULT_GATEWAY_URL || requiresExplicitAuthLogin(gatewayUrl))
+        return false;
+    return (options.interactiveAuth ??
+        (process.stdin.isTTY === true && getOutputMode() !== 'json'));
+}
+function authRequiredError(gatewayUrl) {
+    return new StorystickError(gatewayUrl === DEFAULT_GATEWAY_URL
+        ? 'Authentication required. Run `storystick login` in an interactive terminal.'
+        : `Authentication required for gateway ${gatewayUrl}. Run storystick login --gateway-url with this origin.`, {
+        code: 'AUTH_REQUIRED',
+        status: 401,
+        category: 'auth',
+        recoverable: true,
+        retryable: false,
+    });
+}
+// ─────────────────────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────────────────────
+async function doCall(fetchImpl, gatewayUrl, path, bearer, options) {
+    const url = cliIssuerRequestUrl(gatewayUrl, path);
+    const method = options.method ?? 'GET';
+    const headers = {
+        Authorization: `Bearer ${bearer}`,
+        // Every CLI call identifies itself for CSRF + observability. The Hub's
+        // user-scoped endpoints accept `cli` as a valid client.
+        'X-Storystick-Client': 'cli',
+        // User-scoped token issuance is also a Pattern D content client. Omitting
+        // this descriptor makes a current CLI indistinguishable from a legacy
+        // binary once the project advances to a stricter content-shape epoch.
+        ...contentShapeCapabilityHeaders('cli', options.contentShapeCapability),
+    };
+    if (options.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+    }
+    return await fetchWithDeadline(url, {
+        method,
+        redirect: 'error',
+        headers,
+        body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    }, {
+        fetchImpl,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+    });
+}
+/**
+ * Run device-auth login, printing the verification prompt via the caller's
+ * hook (when provided) and otherwise via the shared `promptDeviceAuth`
+ * primitive. Any thrown error is repackaged as a `StorystickError`.
+ */
+async function runDeviceAuthLogin(options, runtime) {
+    try {
+        return await deviceAuthLogin({
+            ...(options.login ?? {}),
+            hubUrl: options.login?.hubUrl ?? runtime.hubUrl,
+            gatewayUrl: runtime.gatewayUrl,
+            signal: options.signal ?? options.login?.signal,
+            timeoutMs: options.timeoutMs ?? options.login?.timeoutMs,
+            onPrompt: (data) => {
+                if (options.onAuthPrompt) {
+                    options.onAuthPrompt(data);
+                    return;
+                }
+                promptDeviceAuth(data);
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError')
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        // Normalize the cancel/abort path — spec calls this "Login cancelled."
+        if (/cancel/i.test(message)) {
+            throw new StorystickError('Login cancelled.');
+        }
+        throw new StorystickError(message);
+    }
+    finally {
+        // `promptDeviceAuth` started the "Waiting for authorization…" spinner
+        // as a side effect of the onPrompt callback; close that bracket here
+        // so the next prompt / log line doesn't race the spinner frame.
+        // Idempotent — no-op if no spinner is live.
+        stopSpinner();
+    }
+}

package/dist/init-operation.d.ts

@@ -0,0 +1,98 @@
+import type { StarterArtifactIdentity } from './starter-resolver.js';
+import { StorystickError } from './cli-error.js';
+export declare const INIT_OPERATION_RELATIVE_PATH: string;
+export declare const INIT_PHASES: readonly ["P0", "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9", "P10"];
+export type InitPhase = (typeof INIT_PHASES)[number];
+export type InitPhaseStatus = 'pending' | 'complete' | 'failed' | 'skipped';
+export type InitIntent = {
+    kind: 'create';
+    projectName: string;
+    requestedTeamShortId?: string;
+    requestedNewTeamName?: string;
+} | {
+    kind: 'link';
+    requestedShortId: string;
+};
+export interface InitOperationIdentity {
+    targetDir: string;
+    intent: InitIntent;
+    strategy: 'starter' | 'existing-next';
+    starter: {
+        catalogVersion: 2;
+        id: string;
+        release: string;
+        framework: 'next' | 'astro';
+        source: StarterArtifactIdentity['source'];
+        integrity: string;
+        localDirectory?: string;
+    };
+    origins: string[];
+    originMode: 'append' | 'default-if-empty';
+    locale: string;
+    siteUrl?: string;
+    force: boolean;
+}
+export interface InitOperationReceipt extends InitOperationIdentity {
+    version: 1;
+    operationId: string;
+    phase: InitPhase;
+    outcome: 'running' | 'partial' | 'failed' | 'complete';
+    phases: Record<InitPhase, InitPhaseStatus>;
+    projectShortId?: string;
+    projectName?: string;
+    newTeamName?: string;
+    selectedTeam?: {
+        shortId: string;
+        name: string;
+    };
+    endpoint?: string;
+    keyPairVersion?: number;
+    projectionSeq?: number;
+    schemaVersion?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface PreparedBootstrap {
+    receiptPatch: {
+        selectedTeam?: {
+            shortId: string;
+            name: string;
+        };
+        projectShortId: string;
+        keyPairVersion: number;
+    };
+    credentials: {
+        apiKey: string;
+        publishableKey: string;
+    };
+}
+export interface InitOrchestratorDependencies<TPrepared> {
+    planLocal(receipt: InitOperationReceipt): Promise<void>;
+    materializeAndInstall(receipt: InitOperationReceipt): Promise<void>;
+    prepareGeneration(receipt: InitOperationReceipt): Promise<TPrepared>;
+    authorizeAndSelect(receipt: InitOperationReceipt): Promise<Partial<InitOperationReceipt>>;
+    recoverCommittedConnection(receipt: InitOperationReceipt): Promise<boolean>;
+    prepareBootstrap(receipt: InitOperationReceipt): Promise<PreparedBootstrap>;
+    commitConnection(receipt: InitOperationReceipt, prepared: PreparedBootstrap): Promise<void>;
+    pushSchema(receipt: InitOperationReceipt, prepared: TPrepared): Promise<{
+        schemaVersion: string;
+        projectionSeq?: number;
+    }>;
+    commitGeneration(receipt: InitOperationReceipt, prepared: TPrepared): Promise<void>;
+    acknowledge(receipt: InitOperationReceipt): Promise<void>;
+    initializeGit(receipt: InitOperationReceipt): Promise<void>;
+}
+export declare class InitOrchestrationError extends StorystickError {
+    readonly receipt: InitOperationReceipt;
+    readonly resumeCommand: string;
+    constructor(cause: unknown, receipt: InitOperationReceipt);
+}
+export declare function runInitOrchestrator<TPrepared>(args: {
+    identity: InitOperationIdentity;
+    operationId?: string;
+    dependencies: InitOrchestratorDependencies<TPrepared>;
+}): Promise<InitOperationReceipt>;
+export declare function openInitOperation(identity: InitOperationIdentity, operationId?: string): InitOperationReceipt;
+export declare function readInitOperation(targetDir: string): InitOperationReceipt | null;
+export declare function initResumeCommand(receipt: InitOperationReceipt): string;
+export declare function shellQuote(value: string): string;