@labelbox/recursion-cli 0.0.0 → 0.0.42

package/dist/git-host.js

@@ -0,0 +1,190 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import process from 'node:process';
+import { z } from 'zod';
+import { DEFAULT_BASE_URL, supportUrl } from './manifest.js';
+import { envBaseUrl } from './resolve.js';
+const GitRepoClaimSchema = z.object({
+    cloneUrl: z.string(),
+    defaultBranch: z.string(),
+    pushToken: z.string(),
+});
+/** Filename (under `.git/`) the claim's identity is stashed in after
+ *  `scaffold`, so `submit` can re-claim before every push. `submit` MUST
+ *  re-claim rather than reuse a token stashed at scaffold time: the backend
+ *  mints one push token per Aligner under a fixed name and deletes any
+ *  prior token of that name on every claim (`GitHostClient.mintPushToken`),
+ *  since the Forgejo username derives from the Aligner alone, not the
+ *  problem. Without re-claiming, scaffolding a second problem would
+ *  invalidate the first problem's stashed token and its `submit` would
+ *  401/403. */
+const CLAIM_FILE = 'rl-forgejo-claim.json';
+const StashedClaimSchema = z.object({
+    organizationId: z.string(),
+    problemId: z.string(),
+});
+function resolveBaseUrl(program) {
+    const { baseUrl } = program.opts();
+    return baseUrl ?? envBaseUrl() ?? DEFAULT_BASE_URL;
+}
+function resolveAuth(program) {
+    const { apiKey } = program.opts();
+    const { LABELBOX_API_KEY: envApiKey } = process.env;
+    const resolved = apiKey ?? envApiKey;
+    if (!resolved) {
+        throw new Error('missing API key — set LABELBOX_API_KEY or pass --api-key');
+    }
+    return { apiKey: resolved, baseUrl: resolveBaseUrl(program) };
+}
+/** `POST /v1/organizations/:organizationId/git-repo-claims` — mints a per-Aligner
+ *  repo + push token for `problemId`. The claiming Aligner is the
+ *  authenticated caller (the API key), never a client-supplied field. */
+export async function claimGitRepo(args) {
+    const url = supportUrl(args.baseUrl, `/organizations/${encodeURIComponent(args.organizationId)}/git-repo-claims`);
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+            Authorization: `Bearer ${args.apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ problemId: args.problemId }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`could not claim a git repo for problem ${args.problemId} — HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    const parsed = GitRepoClaimSchema.safeParse(await res.json());
+    if (!parsed.success) {
+        throw new Error(`unexpected response shape from ${url}`);
+    }
+    return parsed.data;
+}
+/** Writes a `GIT_ASKPASS` helper that answers "Username" prompts with a
+ *  placeholder and "Password" prompts with `token`, via an env var — never
+ *  the URL or argv, so the token never lands in shell history or `ps`
+ *  listings. Returns the env overrides to pass to the `git` subprocess and
+ *  the script's containing directory, for the caller to clean up.
+ *
+ *  `GIT_ASKPASS` must be a single executable file, not a "command args"
+ *  string — verified live: git silently never invokes a two-word value like
+ *  `"<node> <script>"` (no error, no fallback prompt — it just doesn't run),
+ *  so the script needs a `#!/usr/bin/env node` shebang and the exec bit.
+ *
+ *  The script lives in its own `mkdtempSync` directory (not a fixed,
+ *  guessable path directly under `tmpdir()`) and is written with the `wx`
+ *  flag, which refuses to follow or overwrite an existing path — closing
+ *  the local-attacker-pre-plants-a-symlink hardening gap a fixed name would
+ *  leave open, even though the script itself carries no secret (the token
+ *  rides in `RL_FORGEJO_TOKEN`, not the script body). */
+function gitCredentialEnv(token) {
+    const dir = mkdtempSync(join(tmpdir(), 'rl-forgejo-'));
+    const scriptPath = join(dir, 'askpass.cjs');
+    writeFileSync(scriptPath, '#!/usr/bin/env node\n' +
+        "const p = process.argv[2] || '';\n" +
+        "process.stdout.write(/username/i.test(p) ? 'x-access-token' : (process.env.RL_FORGEJO_TOKEN || ''));\n", { flag: 'wx' });
+    chmodSync(scriptPath, 0o700);
+    return {
+        env: {
+            ...process.env,
+            // biome-ignore lint/style/useNamingConvention: environment variable names, not ours to rename
+            GIT_ASKPASS: scriptPath,
+            // biome-ignore lint/style/useNamingConvention: environment variable names, not ours to rename
+            RL_FORGEJO_TOKEN: token,
+        },
+        cleanupDir: dir,
+    };
+}
+function runGit(args, cwd, token) {
+    const { env, cleanupDir } = gitCredentialEnv(token);
+    try {
+        // `-c credential.helper=` (empty) disables any configured credential
+        // helper (e.g. macOS's osxkeychain, on by default with git-for-mac) for
+        // just this invocation — found live: without it, a helper transparently
+        // caches/replays a *previous* claim's credential for the same host,
+        // silently shadowing GIT_ASKPASS and authenticating as the wrong claim
+        // (or failing on an expired one) instead of using the fresh token below.
+        const result = spawnSync('git', ['-c', 'credential.helper=', ...args], {
+            cwd,
+            env,
+            stdio: 'inherit',
+        });
+        if (result.status !== 0) {
+            throw new Error(`git ${args.join(' ')} failed (exit ${result.status ?? 'unknown'})`);
+        }
+    }
+    finally {
+        rmSync(cleanupDir, { recursive: true, force: true });
+    }
+}
+function claimFilePath(repoDir) {
+    return join(repoDir, '.git', CLAIM_FILE);
+}
+function stashClaim(repoDir, claim) {
+    writeFileSync(claimFilePath(repoDir), JSON.stringify(claim), { mode: 0o600 });
+}
+function readStashedClaim(repoDir) {
+    const path = claimFilePath(repoDir);
+    if (!existsSync(path)) {
+        throw new Error(`no claim found at ${path} — run \`rl scaffold\` in this directory first, or pass --path to point at a scaffolded repo`);
+    }
+    const parsed = StashedClaimSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+    if (!parsed.success) {
+        throw new Error(`stashed claim at ${path} has an unexpected shape`);
+    }
+    return parsed.data;
+}
+/** Register the `scaffold` / `submit` commands on `program`. */
+export function addGitHostCommands(program, helpGroup) {
+    program
+        .command('scaffold <problemId>')
+        .helpGroup(helpGroup)
+        .description('Claim a per-Aligner git repo for a coding-task problem and clone it locally')
+        .requiredOption('--organization-id <id>', 'Organization the problem belongs to')
+        .option('--out <dir>', 'Directory to clone into (default: derived from the repo name)')
+        .action(async (problemId, opts) => {
+        try {
+            const { apiKey, baseUrl } = resolveAuth(program);
+            const claim = await claimGitRepo({
+                apiKey,
+                baseUrl,
+                organizationId: opts.organizationId,
+                problemId,
+            });
+            const dir = opts.out ?? basename(claim.cloneUrl).replace(/\.git$/u, '');
+            mkdirSync(dir, { recursive: true });
+            runGit(['clone', claim.cloneUrl, dir], process.cwd(), claim.pushToken);
+            stashClaim(dir, { organizationId: opts.organizationId, problemId });
+            process.stdout.write(`Cloned into ${dir} (branch ${claim.defaultBranch}). Ready to work.\n`);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+    program
+        .command('submit')
+        .helpGroup(helpGroup)
+        .description('Push local changes in a scaffolded repo back to its claimed remote')
+        .option('--path <dir>', 'Path to the scaffolded repo (default: current directory)')
+        .action(async (opts) => {
+        const dir = opts.path ?? process.cwd();
+        try {
+            // Re-claims rather than reusing a token stashed at `scaffold` time —
+            // see `CLAIM_FILE`'s doc comment: the backend's push token is a
+            // single fixed-name credential per Aligner, so scaffolding any other
+            // problem since would have invalidated a stashed one.
+            const stashed = readStashedClaim(dir);
+            const { apiKey, baseUrl } = resolveAuth(program);
+            const claim = await claimGitRepo({ apiKey, baseUrl, ...stashed });
+            runGit(['push'], dir, claim.pushToken);
+            process.stdout.write('Pushed.\n');
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
+}

package/dist/manifest.d.ts

@@ -0,0 +1,410 @@
+import { z } from 'zod';
+/**
+ * The DEFAULT production base URL: the public API gateway origin. No path
+ * suffix — the API version lives in each operation's path (`/v1/...`), so the
+ * CLI joins this origin with the manifest's paths verbatim.
+ *
+ * Keep in sync with `DEFAULT_BASE_URL` in `packages/sdk-ts/src/index.ts`,
+ * `PUBLIC_API_BASE_URL` in `packages/sdk-ts/openapi-ts.config.ts`, and
+ * `CURL_BASE_URL` in `tools/dx/src/commands/sdk.ts`.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.recursion.labelbox.com";
+/**
+ * Join a hand-written support-endpoint path onto the base URL, under the API
+ * version segment. `path` is version-relative and must start with `/`.
+ */
+export declare function supportUrl(baseUrl: string, path: string): string;
+/**
+ * The manifest format the engine understands. Bumped only on a *breaking* schema
+ * change (a renamed/removed required field, a changed enum) — additive fields are
+ * backward-compatible because the schema strips unknown keys rather than rejecting
+ * them, so a newer server never breaks an older CLI by adding data. A mismatch is
+ * surfaced with an actionable upgrade message at the validation boundary.
+ */
+export declare const MANIFEST_FORMAT_VERSION = 1;
+export interface ShapeNode {
+    name?: string | undefined;
+    type: string;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    enum?: string[] | undefined;
+    itemEnum?: string[] | undefined;
+    default?: string | number | boolean | undefined;
+    format?: string | undefined;
+    example?: string | number | boolean | undefined;
+    nullable?: boolean | undefined;
+    minimum?: number | undefined;
+    maximum?: number | undefined;
+    exclusiveMinimum?: number | undefined;
+    exclusiveMaximum?: number | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    minItems?: number | undefined;
+    maxItems?: number | undefined;
+    pattern?: string | undefined;
+    fields?: ShapeNode[] | undefined;
+    items?: ShapeNode | undefined;
+    variants?: ShapeNode[] | undefined;
+}
+export declare const ShapeNodeSchema: z.ZodType<ShapeNode>;
+/** The metadata / constraint keys a `ShapeNode` carries beyond its structure. */
+export type ShapeMetaKey = Exclude<keyof ShapeNode, 'name' | 'type' | 'required' | 'description' | 'fields' | 'items' | 'variants'>;
+/** A node's present metadata as ordered `[key, value]` pairs (drives the CLI tags). */
+export declare function shapeMetaEntries(node: ShapeNode): Array<readonly [ShapeMetaKey, string | number | boolean | readonly string[]]>;
+/** A request param: a named shape node plus its HTTP location (for generic dispatch). */
+export declare const ManifestParamSchema: z.ZodObject<{
+    type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    format: z.ZodOptional<z.ZodString>;
+    example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+    items: z.ZodOptional<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>;
+    variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+    name: z.ZodString;
+    required: z.ZodBoolean;
+    in: z.ZodEnum<{
+        path: "path";
+        query: "query";
+        body: "body";
+    }>;
+}, z.core.$strip>;
+export type ManifestParam = z.infer<typeof ManifestParamSchema>;
+/**
+ * One operation, carrying everything the CLI needs to build its command and
+ * dispatch generically: the `callPath` (command tree), the `httpMethod` + `path`
+ * template + `params[].in` + `bodyKey` (dispatch), and the recursive request/response
+ * shapes (`--help`). Mirrors the relevant subset of sdk-ts's `SdkReferenceEntry`.
+ */
+export declare const ManifestOperationSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    callPath: z.ZodArray<z.ZodString>;
+    summary: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    httpMethod: z.ZodEnum<{
+        get: "get";
+        post: "post";
+        put: "put";
+        patch: "patch";
+        delete: "delete";
+    }>;
+    path: z.ZodString;
+    bodyKey: z.ZodOptional<z.ZodString>;
+    requiredPermissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    params: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        format: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        nullable: z.ZodOptional<z.ZodBoolean>;
+        minimum: z.ZodOptional<z.ZodNumber>;
+        maximum: z.ZodOptional<z.ZodNumber>;
+        exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+        exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        minItems: z.ZodOptional<z.ZodNumber>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        pattern: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+        items: z.ZodOptional<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>;
+        variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+        name: z.ZodString;
+        required: z.ZodBoolean;
+        in: z.ZodEnum<{
+            path: "path";
+            query: "query";
+            body: "body";
+        }>;
+    }, z.core.$strip>>;
+    response: z.ZodOptional<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>;
+}, z.core.$strip>;
+export type ManifestOperation = z.infer<typeof ManifestOperationSchema>;
+export declare const ManifestResourceSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    parent: z.ZodOptional<z.ZodString>;
+    order: z.ZodNumber;
+    domain: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    object: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        fields: z.ZodArray<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>;
+    }, z.core.$strip>>;
+    operationIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ManifestResource = z.infer<typeof ManifestResourceSchema>;
+export declare const ManifestRelatedSchema: z.ZodObject<{
+    requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"recipe">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"state">;
+        explanation: z.ZodString;
+        predicate: z.ZodOptional<z.ZodString>;
+        via: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                recipe: "recipe";
+                concept: "concept";
+                tutorial: "tutorial";
+                resource: "resource";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
+    variationOf: z.ZodOptional<z.ZodString>;
+    learnMore: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            recipe: "recipe";
+            concept: "concept";
+            tutorial: "tutorial";
+            resource: "resource";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ManifestRelated = z.infer<typeof ManifestRelatedSchema>;
+export declare const ManifestRecipeSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    goal: z.ZodString;
+    category: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        operationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sdk: z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strip>;
+    python: z.ZodOptional<z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strip>>;
+    cli: z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strip>;
+    curl: z.ZodObject<{
+        setup: z.ZodString;
+        main: z.ZodString;
+    }, z.core.$strip>;
+    related: z.ZodOptional<z.ZodObject<{
+        requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"recipe">;
+            id: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"state">;
+            explanation: z.ZodString;
+            predicate: z.ZodOptional<z.ZodString>;
+            via: z.ZodOptional<z.ZodObject<{
+                type: z.ZodEnum<{
+                    recipe: "recipe";
+                    concept: "concept";
+                    tutorial: "tutorial";
+                    resource: "resource";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>>;
+        variationOf: z.ZodOptional<z.ZodString>;
+        learnMore: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                recipe: "recipe";
+                concept: "concept";
+                tutorial: "tutorial";
+                resource: "resource";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ManifestRecipe = z.infer<typeof ManifestRecipeSchema>;
+export declare const ManifestConceptSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    domain: z.ZodString;
+    related: z.ZodArray<z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type ManifestConcept = z.infer<typeof ManifestConceptSchema>;
+export declare const ManifestTutorialSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ManifestTutorial = z.infer<typeof ManifestTutorialSchema>;
+export declare const ManifestDomainSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    order: z.ZodNumber;
+}, z.core.$strip>;
+export type ManifestDomain = z.infer<typeof ManifestDomainSchema>;
+export declare const ManifestSchema: z.ZodObject<{
+    formatVersion: z.ZodNumber;
+    hash: z.ZodString;
+    operations: z.ZodRecord<z.ZodString, z.ZodObject<{
+        operationId: z.ZodString;
+        callPath: z.ZodArray<z.ZodString>;
+        summary: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        httpMethod: z.ZodEnum<{
+            get: "get";
+            post: "post";
+            put: "put";
+            patch: "patch";
+            delete: "delete";
+        }>;
+        path: z.ZodString;
+        bodyKey: z.ZodOptional<z.ZodString>;
+        requiredPermissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        params: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            format: z.ZodOptional<z.ZodString>;
+            example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            nullable: z.ZodOptional<z.ZodBoolean>;
+            minimum: z.ZodOptional<z.ZodNumber>;
+            maximum: z.ZodOptional<z.ZodNumber>;
+            exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+            exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+            minLength: z.ZodOptional<z.ZodNumber>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            minItems: z.ZodOptional<z.ZodNumber>;
+            maxItems: z.ZodOptional<z.ZodNumber>;
+            pattern: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+            items: z.ZodOptional<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>;
+            variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+            name: z.ZodString;
+            required: z.ZodBoolean;
+            in: z.ZodEnum<{
+                path: "path";
+                query: "query";
+                body: "body";
+            }>;
+        }, z.core.$strip>>;
+        response: z.ZodOptional<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>;
+    }, z.core.$strip>>;
+    resources: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        parent: z.ZodOptional<z.ZodString>;
+        order: z.ZodNumber;
+        domain: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        object: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            fields: z.ZodArray<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>;
+        }, z.core.$strip>>;
+        operationIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    recipes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        goal: z.ZodString;
+        category: z.ZodString;
+        steps: z.ZodArray<z.ZodObject<{
+            operationId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sdk: z.ZodObject<{
+            setup: z.ZodString;
+            main: z.ZodString;
+        }, z.core.$strip>;
+        python: z.ZodOptional<z.ZodObject<{
+            setup: z.ZodString;
+            main: z.ZodString;
+        }, z.core.$strip>>;
+        cli: z.ZodObject<{
+            setup: z.ZodString;
+            main: z.ZodString;
+        }, z.core.$strip>;
+        curl: z.ZodObject<{
+            setup: z.ZodString;
+            main: z.ZodString;
+        }, z.core.$strip>;
+        related: z.ZodOptional<z.ZodObject<{
+            requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"recipe">;
+                id: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"state">;
+                explanation: z.ZodString;
+                predicate: z.ZodOptional<z.ZodString>;
+                via: z.ZodOptional<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        recipe: "recipe";
+                        concept: "concept";
+                        tutorial: "tutorial";
+                        resource: "resource";
+                    }>;
+                    id: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>]>>>;
+            variationOf: z.ZodOptional<z.ZodString>;
+            learnMore: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodEnum<{
+                    recipe: "recipe";
+                    concept: "concept";
+                    tutorial: "tutorial";
+                    resource: "resource";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    concepts: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        domain: z.ZodString;
+        related: z.ZodArray<z.ZodString>;
+        body: z.ZodString;
+    }, z.core.$strip>>;
+    tutorials: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        body: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    domains: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        order: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+/**
+ * Validate a fetched/cached manifest at the I/O boundary and check engine↔manifest
+ * format compatibility. A version mismatch is the one case worth an actionable
+ * message: the schema itself stays lenient (so additive server changes are safe),
+ * and only a deliberate format bump trips this.
+ */
+export declare function parseManifest(value: unknown, source: string): Manifest;
+/**
+ * Fetch the command manifest, revalidating the cache on every run:
+ *   - send `If-None-Match` with the cached ETag → `304` means the cache is provably
+ *     current (use it); `200` means the surface changed (validate + replace cache).
+ *   - a network error (incl. a timeout) falls back to the cached copy with a warning;
+ *     with no cache it errors clearly.
+ * The cache therefore can never serve stale data and never needs manual busting — a
+ * backend redeploy is picked up automatically on the next command.
+ */
+export declare function fetchManifest(baseUrl: string, apiKey: string): Promise<Manifest>;