primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/commands/prompts.js

@@ -1,11 +1,27 @@
-import { readFileSync, writeFileSync, statSync } from "fs";
-import { basename } from "path";
-import * as TOML from "@iarna/toml";
-import { lookup as mimeLookup } from "mime-types";
+import { writeFileSync } from "fs";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
 import chalk from "chalk";
-import { success, error, info, warn, keyValue, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, } from "../lib/output.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, progress, progressEnd, } from "../lib/output.js";
+import { pollUntil } from "../lib/watch.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseStatusFilter } from "../lib/object-status-filter.js";
+import { formatAccessRuleForDisplay } from "../lib/access-rule-display.js";
+import { requireTestCaseInputVariables } from "../lib/test-case-variables.js";
+import { resolvePromptSelector } from "../lib/block-selector.js";
+/**
+ * Resolve a prompt reference — its server id, or the author-chosen key its
+ * TOML file is named for.
+ *
+ * Under TOML-only authoring the key is what an operator has: `prompts/<key>.toml`
+ * is the object, and the id is a server detail they never wrote down. Mirrors
+ * `resolveScriptId` in `scripts.ts`. The resolution itself lives in
+ * `block-selector.ts` (#3249) so the `tests` verbs and `configs get` agree on
+ * it — and drain every page of the list, where this used to read one.
+ */
+async function resolvePromptId(client, appId, ref) {
+    return (await resolvePromptSelector(client, appId, ref)).blockId;
+}
 export function registerPromptsCommands(program) {
     const prompts = program
         .command("prompts")
@@ -13,9 +29,19 @@ export function registerPromptsCommands(program) {
         .addHelpText("after", `
 Examples:
   $ primitive prompts list
-  $ primitive prompts create --from-file summarizer.toml
+  $ primitive config create prompt summarizer       # scaffold prompts/summarizer.toml
+  $ primitive config push --only prompt/summarizer  # apply it
   $ primitive prompts execute 01HXY... --vars '{"text":"Hello world"}'
-  $ primitive prompts configs activate 01HXY... 01ABC...
+  $ primitive prompts configs list summarizer       # what the server runs
+`);
+    // Server-side configuration is authored in TOML and applied with `config push`
+    // (issue #2645) — this group no longer carries config-setting flags.
+    prompts.addHelpText("after", `
+Configuration lives in prompts/<key>.toml:
+  $ primitive config fields prompt        # the file's keys, types and defaults
+  $ primitive config create prompt <key>  # scaffold one locally
+  $ primitive config set prompt/<key> <path>=<value>
+  $ primitive config push --only prompt/<key>
 `);
     // List prompts
     prompts
@@ -23,14 +49,22 @@ Examples:
         .description("List prompts")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
-        .option("--status <status>", "Filter by status: draft, active, archived")
+        .option("--status <status>", "Filter by status: active, inactive, archived")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
+            // #2803 — `draft` is gone; refuse it by name rather than returning the
+            // empty list a canonical filter would produce. #2887 added `archived`:
+            // the delete flow writes one now, so asking for the retired rows is a
+            // question with an answer rather than a 400.
             const { items } = await client.listPrompts(resolvedAppId, {
-                status: options.status,
+                status: parseStatusFilter("prompts", options.status, [
+                    "active",
+                    "inactive",
+                    "archived",
+                ]),
             });
             if (options.json) {
                 json(items);
@@ -53,209 +87,154 @@ Examples:
             process.exit(1);
         }
     });
-    // Create prompt
+    // #2645 criterion 9 / #2803 — the operational verbs. They are the only
+    // writers of `status`, which is server-owned and no longer a TOML key.
     prompts
-        .command("create")
-        .description("Create a new prompt")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--key <key>", "Prompt key (unique identifier)")
-        .option("--name <name>", "Display name")
-        .option("--description <desc>", "Description")
-        .option("--provider <provider>", "LLM provider: openrouter, gemini", "openrouter")
-        .option("--model <model>", "Model name")
-        .option("--system-prompt <prompt>", "System prompt")
-        .option("--user-template <template>", "User prompt template")
-        .option("--temperature <temp>", "Temperature (0-1)")
-        .option("--max-tokens <n>", "Max output tokens")
-        .option("--output-format <format>", "Output format: text, json")
-        .option("--input-schema <json>", "Input schema as JSON")
-        .option("--output-schema <json>", "Output schema as JSON")
-        .option("--from-file <path>", "Load prompt from TOML file")
+        .command("disable")
+        .description("Take prompt out of service now. Operational, not configuration: `status` is server-owned and 'config push' can neither set nor clear it.")
+        .argument("<prompt-id>", "Prompt ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
+        .action(async (id, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
-        let payload;
-        if (options.fromFile) {
-            try {
-                const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                const prompt = tomlData.prompt || tomlData;
-                const config = tomlData.configs?.[0] || {};
-                payload = {
-                    promptKey: prompt.key || prompt.promptKey,
-                    displayName: prompt.displayName || prompt.name,
-                    description: prompt.description,
-                    provider: config.provider || prompt.provider || "openrouter",
-                    model: config.model || prompt.model,
-                    systemPrompt: config.systemPrompt || prompt.systemPrompt,
-                    userPromptTemplate: config.userPromptTemplate || prompt.userPromptTemplate,
-                    temperature: config.temperature || prompt.temperature,
-                    maxTokens: config.maxTokens || prompt.maxTokens,
-                    outputFormat: config.outputFormat || prompt.outputFormat,
-                    inputSchema: prompt.inputSchema,
-                    outputSchema: prompt.outputSchema,
-                };
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-        }
-        else {
-            if (!options.key || !options.name || !options.model || !options.userTemplate) {
-                error("Required: --key, --name, --model, --user-template (or use --from-file)");
-                process.exit(1);
-            }
-            payload = {
-                promptKey: options.key,
-                displayName: options.name,
-                description: options.description,
-                provider: options.provider,
-                model: options.model,
-                systemPrompt: options.systemPrompt,
-                userPromptTemplate: options.userTemplate,
-                temperature: options.temperature,
-                maxTokens: options.maxTokens ? parseInt(options.maxTokens) : undefined,
-                outputFormat: options.outputFormat,
-                inputSchema: options.inputSchema,
-                outputSchema: options.outputSchema,
-            };
-        }
         try {
-            const result = await client.createPrompt(resolvedAppId, payload);
+            const result = await client.setPromptAvailability(resolvedAppId, id, "disable");
             if (options.json) {
                 json(result);
                 return;
             }
-            success(`Prompt created: ${result.displayName}`);
-            keyValue("Prompt ID", result.promptId);
-            keyValue("Key", result.promptKey);
+            success(`Prompt disabled: ${result.promptKey || id}`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Get prompt
     prompts
-        .command("get")
-        .description("Get prompt details")
+        .command("enable")
+        .description("Put prompt back in service.")
         .argument("<prompt-id>", "Prompt ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .action(async (id, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.getPrompt(resolvedAppId, promptId);
+            const result = await client.setPromptAvailability(resolvedAppId, id, "enable");
             if (options.json) {
                 json(result);
                 return;
             }
-            keyValue("Prompt ID", result.promptId);
-            keyValue("Key", result.promptKey);
-            keyValue("Name", result.displayName);
-            keyValue("Description", result.description);
-            keyValue("Status", formatStatus(result.status));
-            keyValue("Active Config", result.activeConfigId || "-");
-            if (result.configs && result.configs.length > 0) {
-                divider();
-                info(`Configs (${result.configs.length}):`);
-                console.log(formatTable(result.configs, [
-                    { header: "ID", key: "configId", format: formatId },
-                    { header: "NAME", key: "configName" },
-                    { header: "MODEL", key: "model" },
-                    { header: "STATUS", key: "status", format: formatStatus },
-                ]));
-            }
+            success(`Prompt enabled: ${result.promptKey || id}`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Update prompt
+    // #2907 — the delete flow's CLI spelling. Not a second writer of `status`:
+    // this is the plain `DELETE` #2887 made retire-with-history, which until now
+    // only the admin API and the console could reach. Named `archive`, not
+    // `delete`, because a configuration noun gets no `delete` verb
+    // (docs/cli-design.md) and prune-by-push stays the only CLI hard-delete path.
     prompts
-        .command("update")
-        .description("Update a prompt")
+        .command("archive")
+        .description("Retire a prompt (soft delete). Delete-lifecycle, not `disable`: the row and its configs are kept so executions still resolve, it goes on holding its key, and there is no un-archive.")
         .argument("<prompt-id>", "Prompt ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Display name")
-        .option("--description <desc>", "Description")
-        .option("--status <status>", "Status: draft, active, archived")
-        .option("--input-schema <json>", "Input schema as JSON")
-        .option("--output-schema <json>", "Output schema as JSON")
+        .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .addHelpText("after", `
+What archiving a prompt costs (retire-with-history):
+  The member endpoint refuses it, and so does admin execution — the diagnostic
+  runs an INACTIVE prompt on purpose, but not an archived one.
+  Its configs, executions and analytics keep resolving what they point at.
+  The archived row still holds its promptKey.
+  \`primitive prompts enable\` refuses an archived prompt; there is no
+  un-archive.
+  The per-version \`[[configs]] status\` is a different key and is untouched.
+
+Reclaiming the key means hard-deleting the row:
+  $ rm prompts/<key>.toml
+  $ primitive config push --prune     # confirmed; hard-deletes the row
+  # or hard-delete it in the console, then re-add the file and push.
+`)
+        .action(async (id, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.displayName = options.name;
-        if (options.description)
-            payload.description = options.description;
-        if (options.status)
-            payload.status = options.status;
-        if (options.inputSchema)
-            payload.inputSchema = options.inputSchema;
-        if (options.outputSchema)
-            payload.outputSchema = options.outputSchema;
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified.");
-            process.exit(1);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(`Archive prompt ${id}? It is retired, its configs and executions are ` +
+                    `kept, it goes on holding its key, and there is no un-archive.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
         }
         const client = new ApiClient();
         try {
-            const result = await client.updatePrompt(resolvedAppId, promptId, payload);
+            // The soft delete: no `hard`, so the configs and stored prompt bodies
+            // survive and every execution row keeps resolving.
+            const result = await client.deletePrompt(resolvedAppId, id);
             if (options.json) {
                 json(result);
                 return;
             }
-            success("Prompt updated.");
+            success(`Prompt archived: ${id}`);
+            info("Its configs and executions keep resolving. The row still holds its key — reclaim it by removing its file and running a confirmed `primitive config push --prune`.");
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Delete prompt
     prompts
-        .command("delete")
-        .description("Delete or archive a prompt")
+        .command("get")
+        .description("Get prompt details")
         .argument("<prompt-id>", "Prompt ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--hard", "Permanently delete instead of archive")
-        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
         .action(async (promptId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            const action = options.hard ? "permanently delete" : "archive";
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to ${action} prompt ${promptId}?`,
-                    default: false,
-                },
-            ]);
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
         const client = new ApiClient();
         try {
-            await client.deletePrompt(resolvedAppId, promptId, options.hard);
-            success(`Prompt ${options.hard ? "deleted" : "archived"}.`);
+            const result = await client.getPrompt(resolvedAppId, promptId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            printResult("Prompt ID", result.promptId);
+            printResult("Key", result.promptKey);
+            printResult("Name", result.displayName);
+            printResult("Description", result.description);
+            printResult("Status", formatStatus(result.status));
+            // #2652: no rule means every non-admin execution is denied. Print that
+            // in words — a blank or "-" would read as "unrestricted" and hide a
+            // prompt that was never given a rule.
+            printResult("Access Rule", formatAccessRuleForDisplay(result.accessRule, "prompt"));
+            printResult("Active Config", result.activeConfigId || "-");
+            if (result.configs && result.configs.length > 0) {
+                divider();
+                info(`Configs (${result.configs.length}):`);
+                console.log(formatTable(result.configs, [
+                    { header: "ID", key: "configId", format: formatId },
+                    { header: "NAME", key: "configName" },
+                    { header: "MODEL", key: "model" },
+                    { header: "STATUS", key: "status", format: formatStatus },
+                ]));
+            }
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Execute prompt
     prompts
         .command("execute")
         .description("Execute a prompt with variables")
@@ -397,8 +376,25 @@ Examples:
             process.exit(1);
         }
     });
-    // Configs subcommand
-    const configs = prompts.command("configs").description("Manage prompt configs");
+    // Configs subcommand — reads only. A prompt's configs are `[[configs]]`
+    // entries in its own TOML file (#2645), so the verbs that used to write them
+    // were a second writer for state the file already owns.
+    const configs = prompts
+        .command("configs")
+        .description("Inspect a prompt's configs (authored in prompts/<key>.toml)")
+        .addHelpText("after", `
+A prompt's configs are the \`[[configs]]\` entries of prompts/<key>.toml. Add,
+edit, retire (\`status = "archived"\`) or mark one live (\`active = true\`) in that
+file, then apply it:
+
+  $ primitive config push --only prompt/<key>
+
+That per-config \`status\` says which VERSION is retired and is yours to author.
+The PROMPT's own availability is server-owned and has no TOML key: use
+'primitive prompts disable' / 'enable'.
+
+Duplicating a config is copying its \`[[configs]]\` block and renaming it.
+`);
     // List configs
     configs
         .command("list")
@@ -432,154 +428,51 @@ Examples:
             process.exit(1);
         }
     });
-    // Create config
+    // Get one config. `list` says which configs exist; this says what one of
+    // them actually runs — the body, provider and model the server would use.
+    // With `prompts configs create/update` gone, this is where that content is
+    // read back from.
     configs
-        .command("create")
-        .description("Create a new config for a prompt")
-        .argument("<prompt-id>", "Prompt ID")
+        .command("get")
+        .description("Show one config of a prompt as the server has it")
+        .argument("<prompt>", "Prompt ID or key")
+        .argument("<config>", "Config ID or name")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Config name")
-        .option("--description <desc>", "Description")
-        .option("--provider <provider>", "LLM provider: openrouter, gemini", "openrouter")
-        .option("--model <model>", "Model name")
-        .option("--system-prompt <prompt>", "System prompt")
-        .option("--user-template <template>", "User prompt template")
-        .option("--temperature <temp>", "Temperature (0-1)")
-        .option("--max-tokens <n>", "Max output tokens")
-        .option("--output-format <format>", "Output format: text, json")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .action(async (prompt, config, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.name || !options.model || !options.userTemplate) {
-            error("Required: --name, --model, --user-template");
-            process.exit(1);
-        }
-        const payload = {
-            configName: options.name,
-            description: options.description,
-            provider: options.provider,
-            model: options.model,
-            systemPrompt: options.systemPrompt,
-            userPromptTemplate: options.userTemplate,
-            temperature: options.temperature,
-            maxTokens: options.maxTokens ? parseInt(options.maxTokens) : undefined,
-            outputFormat: options.outputFormat,
-        };
         const client = new ApiClient();
         try {
-            const result = await client.createPromptConfig(resolvedAppId, promptId, payload);
-            if (options.json) {
-                json(result);
-                return;
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
+            const { items } = await client.listPromptConfigs(resolvedAppId, promptId);
+            const summary = (items ?? []).find((c) => c.configId === config || c.configName === config);
+            if (!summary) {
+                error(`Prompt '${prompt}' has no config '${config}'. Run 'primitive prompts configs list ${prompt}' to see them.`);
+                process.exit(1);
             }
-            success(`Config created: ${result.configName}`);
-            keyValue("Config ID", result.configId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Activate config
-    configs
-        .command("activate")
-        .description("Set a config as the active config for a prompt")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<config-id>", "Config ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .action(async (promptId, configId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            await client.activatePromptConfig(resolvedAppId, promptId, configId);
-            success(`Config ${configId} activated.`);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Duplicate config
-    configs
-        .command("duplicate")
-        .description("Duplicate a config")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<config-id>", "Config ID to duplicate")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "New config name")
-        .option("--json", "Output as JSON")
-        .action(async (promptId, configId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.duplicatePromptConfig(resolvedAppId, promptId, configId, {
-                configName: options.name,
-            });
+            const full = (await client.getPromptConfig(resolvedAppId, promptId, summary.configId)) ??
+                summary;
             if (options.json) {
-                json(result);
+                json(full);
                 return;
             }
-            success(`Config duplicated: ${result.configName}`);
-            keyValue("New Config ID", result.configId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Update config
-    configs
-        .command("update")
-        .description("Update a config")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<config-id>", "Config ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Config name")
-        .option("--description <desc>", "Description")
-        .option("--provider <provider>", "LLM provider: openrouter, gemini")
-        .option("--model <model>", "Model name")
-        .option("--system-prompt <prompt>", "System prompt")
-        .option("--user-template <template>", "User prompt template")
-        .option("--temperature <temp>", "Temperature (0-1)")
-        .option("--max-tokens <n>", "Max output tokens")
-        .option("--output-format <format>", "Output format: text, json")
-        .option("--status <status>", "Status: active, archived")
-        .option("--json", "Output as JSON")
-        .action(async (promptId, configId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.configName = options.name;
-        if (options.description)
-            payload.description = options.description;
-        if (options.provider)
-            payload.provider = options.provider;
-        if (options.model)
-            payload.model = options.model;
-        if (options.systemPrompt)
-            payload.systemPrompt = options.systemPrompt;
-        if (options.userTemplate)
-            payload.userPromptTemplate = options.userTemplate;
-        if (options.temperature)
-            payload.temperature = options.temperature;
-        if (options.maxTokens)
-            payload.maxTokens = parseInt(options.maxTokens);
-        if (options.outputFormat)
-            payload.outputFormat = options.outputFormat;
-        if (options.status)
-            payload.status = options.status;
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified.");
-            process.exit(1);
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.updatePromptConfig(resolvedAppId, promptId, configId, payload);
-            if (options.json) {
-                json(result);
-                return;
+            printResult("Config ID", full.configId);
+            printResult("Name", full.configName);
+            printResult("Status", formatStatus(full.status));
+            printResult("Provider", full.provider || "-");
+            printResult("Model", full.model || "-");
+            if (full.description)
+                printResult("Description", full.description);
+            if (full.systemPrompt) {
+                divider();
+                info("System prompt:");
+                console.log(full.systemPrompt);
+            }
+            if (full.userPrompt) {
+                divider();
+                info("User prompt:");
+                console.log(full.userPrompt);
             }
-            success("Config updated.");
         }
         catch (err) {
             error(err.message);
@@ -591,26 +484,37 @@ Examples:
     // ============================================
     const tests = prompts
         .command("tests")
-        .description("Manage and run prompt test cases")
+        .description("Run and inspect prompt test cases")
         .addHelpText("after", `
+Test cases are authored in TOML at prompts/<key>.tests/<name>.toml and applied
+with \`primitive config push\` (issue #2769); \`config fields prompt\` lists the
+fields. Deleting a case is removing its file and running \`config push --prune\`.
+
+Every verb here takes the prompt's KEY or its ID (#3249). An identifier that
+names no prompt in the app fails; "No test cases found." only ever means the
+prompt exists and has no cases.
+
 Examples:
-  $ primitive prompts tests list <prompt-id>
-  $ primitive prompts tests create <prompt-id> --name "Basic test" --vars '{"input":"hello"}'
-  $ primitive prompts tests run <prompt-id> <test-case-id>
-  $ primitive prompts tests run-all <prompt-id>
-  $ primitive prompts tests run-all <prompt-id> --test-cases 01ABC,01DEF,01GHI
+  $ primitive prompts tests list <prompt>
+  $ primitive prompts tests run <prompt> <test-case-id>
+  $ primitive prompts tests run-all <prompt>
+  $ primitive prompts tests run-all <prompt> --test-cases 01ABC,01DEF,01GHI
 `);
     // List test cases
     tests
         .command("list")
         .description("List test cases for a prompt")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .action(async (prompt, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            // #3249 — resolve BEFORE listing: the test-case endpoint answers an
+            // unknown block with an empty page, so an unresolved identifier would
+            // print "No test cases found." and exit 0.
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             const { items } = await client.listTestCases(resolvedAppId, "prompt", promptId);
             if (options.json) {
                 json(items);
@@ -632,100 +536,28 @@ Examples:
             process.exit(1);
         }
     });
-    // Create test case
-    tests
-        .command("create")
-        .description("Create a test case for a prompt")
-        .argument("<prompt-id>", "Prompt ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Test case name (required)")
-        .option("--vars <json>", "Input variables as JSON (required)")
-        .option("--pattern <regex>", "Expected output pattern (regex)")
-        .option("--contains <json>", "Expected strings to contain (JSON array)")
-        .option("--json-subset <json>", "Expected JSON subset to match")
-        .option("--config <config-id>", "Config ID to use for this test")
-        .option("--evaluator-prompt <prompt-id>", "Evaluator prompt ID")
-        .option("--evaluator-config <config-id>", "Evaluator config ID")
-        .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.name || !options.vars) {
-            error("Required: --name and --vars");
-            process.exit(1);
-        }
-        let inputVariables;
-        try {
-            inputVariables = JSON.parse(options.vars);
-        }
-        catch {
-            error("Invalid JSON in --vars");
-            process.exit(1);
-        }
-        let expectedOutputContains;
-        if (options.contains) {
-            try {
-                expectedOutputContains = JSON.parse(options.contains);
-            }
-            catch {
-                error("Invalid JSON in --contains");
-                process.exit(1);
-            }
-        }
-        let expectedJsonSubset;
-        if (options.jsonSubset) {
-            try {
-                expectedJsonSubset = JSON.parse(options.jsonSubset);
-            }
-            catch {
-                error("Invalid JSON in --json-subset");
-                process.exit(1);
-            }
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.createTestCase(resolvedAppId, "prompt", promptId, {
-                name: options.name,
-                inputVariables,
-                expectedOutputPattern: options.pattern,
-                expectedOutputContains,
-                expectedJsonSubset,
-                configId: options.config,
-                evaluatorPromptId: options.evaluatorPrompt,
-                evaluatorConfigId: options.evaluatorConfig,
-            });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Test case created: ${result.name}`);
-            keyValue("Test Case ID", result.testCaseId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // Get test case
     tests
         .command("get")
         .description("Get test case details")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (promptId, testCaseId, options) => {
+        .action(async (prompt, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             const result = await client.getTestCase(resolvedAppId, "prompt", promptId, testCaseId);
             if (options.json) {
                 json(result);
                 return;
             }
-            keyValue("Test Case ID", result.testCaseId);
-            keyValue("Name", result.name);
-            keyValue("Config ID", result.configId || "-");
-            keyValue("Created", formatDate(result.createdAt));
+            printResult("Test Case ID", result.testCaseId);
+            printResult("Name", result.name);
+            printResult("Config ID", result.configId || "-");
+            printResult("Created", formatDate(result.createdAt));
             divider();
             info("Input Variables:");
             try {
@@ -737,7 +569,7 @@ Examples:
             }
             if (result.expectedOutputPattern) {
                 divider();
-                keyValue("Expected Pattern", result.expectedOutputPattern);
+                printResult("Expected Pattern", result.expectedOutputPattern);
             }
             if (result.expectedOutputContains) {
                 divider();
@@ -761,8 +593,8 @@ Examples:
             }
             if (result.evaluatorPromptId) {
                 divider();
-                keyValue("Evaluator Prompt", result.evaluatorPromptId);
-                keyValue("Evaluator Config", result.evaluatorConfigId || "-");
+                printResult("Evaluator Prompt", result.evaluatorPromptId);
+                printResult("Evaluator Config", result.evaluatorConfigId || "-");
             }
         }
         catch (err) {
@@ -770,144 +602,26 @@ Examples:
             process.exit(1);
         }
     });
-    // Update test case
-    tests
-        .command("update")
-        .description("Update a test case")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Test case name")
-        .option("--vars <json>", "Input variables as JSON")
-        .option("--pattern <regex>", "Expected output pattern (regex)")
-        .option("--contains <json>", "Expected strings to contain (JSON array)")
-        .option("--json-subset <json>", "Expected JSON subset to match")
-        .option("--config <config-id>", "Config ID to use for this test")
-        .option("--clear-pattern", "Clear expected pattern")
-        .option("--clear-contains", "Clear expected contains")
-        .option("--clear-json-subset", "Clear expected JSON subset")
-        .option("--json", "Output as JSON")
-        .action(async (promptId, testCaseId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.name = options.name;
-        if (options.vars) {
-            try {
-                payload.inputVariables = JSON.parse(options.vars);
-            }
-            catch {
-                error("Invalid JSON in --vars");
-                process.exit(1);
-            }
-        }
-        if (options.clearPattern) {
-            payload.expectedOutputPattern = null;
-        }
-        else if (options.pattern) {
-            payload.expectedOutputPattern = options.pattern;
-        }
-        if (options.clearContains) {
-            payload.expectedOutputContains = null;
-        }
-        else if (options.contains) {
-            try {
-                payload.expectedOutputContains = JSON.parse(options.contains);
-            }
-            catch {
-                error("Invalid JSON in --contains");
-                process.exit(1);
-            }
-        }
-        if (options.clearJsonSubset) {
-            payload.expectedJsonSubset = null;
-        }
-        else if (options.jsonSubset) {
-            try {
-                payload.expectedJsonSubset = JSON.parse(options.jsonSubset);
-            }
-            catch {
-                error("Invalid JSON in --json-subset");
-                process.exit(1);
-            }
-        }
-        if (options.config)
-            payload.configId = options.config;
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified.");
-            process.exit(1);
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.updateTestCase(resolvedAppId, "prompt", promptId, testCaseId, payload);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success("Test case updated.");
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Delete test case
-    tests
-        .command("delete")
-        .description("Delete a test case")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .action(async (promptId, testCaseId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to delete test case ${testCaseId}?`,
-                    default: false,
-                },
-            ]);
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            await client.deleteTestCase(resolvedAppId, "prompt", promptId, testCaseId);
-            success("Test case deleted.");
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // Run a single test case
     tests
         .command("run")
         .description("Run a single test case")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--config <config-id>", "Override config ID")
         .option("--json", "Output as JSON")
-        .action(async (promptId, testCaseId, options) => {
+        .action(async (prompt, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             // Get test case to retrieve its variables
             const testCase = await client.getTestCase(resolvedAppId, "prompt", promptId, testCaseId);
-            let variables = {};
-            try {
-                variables = JSON.parse(testCase.inputVariables || "{}");
-            }
-            catch {
-                // Use empty object if parsing fails
-            }
+            // #3158 — the case's stored input IS the run's input, and the server
+            // hands it back parsed; `JSON.parse` on that object threw and the run
+            // went ahead with `{}`, disagreeing with `run-all` over the same case.
+            const variables = requireTestCaseInputVariables(testCase.inputVariables, testCaseId);
             const result = await client.executeBlockTest(resolvedAppId, "prompt", promptId, {
                 variables,
                 testCaseId,
@@ -962,15 +676,18 @@ Examples:
     tests
         .command("run-all")
         .description("Run all test cases for a prompt, or a specific subset")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--config <config-id>", "Override config ID for all tests")
         .option("--test-cases <ids>", "Comma-separated list of test case IDs to run (runs only these)")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .action(async (prompt, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            // #3249 — resolve first, so `Total Tests: 0` can only ever mean the
+            // prompt exists and has no cases, never that the identifier was wrong.
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             // Parse test case IDs if provided
             let testCaseIds;
             if (options.testCases) {
@@ -1028,15 +745,16 @@ Examples:
     tests
         .command("runs")
         .description("List recent test runs for a prompt")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--limit <n>", "Maximum number of runs to show", "20")
         .option("--group <group>", "Filter by comparison group")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .action(async (prompt, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             const { items } = await client.listTestRuns(resolvedAppId, "prompt", promptId, {
                 limit: parseInt(options.limit),
                 comparisonGroup: options.group,
@@ -1078,24 +796,25 @@ Examples:
         .description("Run tests in parallel using workflow-based execution")
         .addHelpText("after", `
 Examples:
-  $ primitive prompts tests batch start <prompt-id>
-  $ primitive prompts tests batch start <prompt-id> --test-cases 01ABC,01DEF
-  $ primitive prompts tests batch status <prompt-id> <batch-id>
-  $ primitive prompts tests batch cancel <prompt-id> <batch-id>
+  $ primitive prompts tests batch start <prompt>
+  $ primitive prompts tests batch start <prompt> --test-cases 01ABC,01DEF
+  $ primitive prompts tests batch status <prompt> <batch-id>
+  $ primitive prompts tests batch cancel <prompt> <batch-id>
 `);
     // Start batch tests
     batch
         .command("start")
         .description("Start parallel batch test execution")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--config <config-id>", "Override config ID for all tests")
         .option("--test-cases <ids>", "Comma-separated list of test case IDs to run")
         .option("--json", "Output as JSON")
-        .action(async (promptId, options) => {
+        .action(async (prompt, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             let testCaseIds;
             if (options.testCases) {
                 testCaseIds = options.testCases.split(",").map((id) => id.trim()).filter(Boolean);
@@ -1132,27 +851,37 @@ Examples:
     batch
         .command("status")
         .description("Get status of a batch test execution")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .argument("<batch-id>", "Batch ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--wait", "Wait for completion (polls every 2 seconds)")
         .option("--json", "Output as JSON")
-        .action(async (promptId, batchId, options) => {
+        .action(async (prompt, batchId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             const fetchStatus = async () => {
                 return client.getBatchTestStatus(resolvedAppId, "prompt", promptId, batchId);
             };
             let result = await fetchStatus();
             if (options.wait && result.status === "running") {
                 info("Waiting for batch completion...");
-                while (result.status === "running") {
-                    await new Promise((r) => setTimeout(r, 2000));
-                    result = await fetchStatus();
-                    process.stdout.write(`\r  Completed: ${result.completed}/${result.results?.length || 0}  `);
-                }
-                console.log();
+                // #1969 — shared poll primitive (delay-then-probe every 2s, honoring
+                // an AbortSignal). `onError: "throw"` preserves the prior loop's
+                // fail-fast behavior: a throwing fetchStatus (expired token, deleted
+                // batch → 401/404) propagates to the command-level catch below and
+                // exits non-zero, rather than spinning forever with a frozen progress
+                // line. (The follow/watch tail loops legitimately keep "continue".)
+                const controller = new AbortController();
+                result = await pollUntil(fetchStatus, (r) => r.status !== "running", {
+                    intervalMs: 2000,
+                    signal: controller.signal,
+                    onError: "throw",
+                    // Progress goes to stderr so it can't corrupt JSON on stdout under --json.
+                    onValue: (r) => progress(`  Completed: ${r.completed}/${r.results?.length || 0}  `),
+                });
+                progressEnd();
             }
             if (options.json) {
                 json(result);
@@ -1188,23 +917,22 @@ Examples:
     batch
         .command("cancel")
         .description("Cancel a running batch test execution")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .argument("<batch-id>", "Batch ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
-        .action(async (promptId, batchId, options) => {
+        .action(async (prompt, batchId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to cancel batch ${batchId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Are you sure you want to cancel batch ${batchId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -1212,6 +940,7 @@ Examples:
         }
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             // First get current status to get instance IDs
             const status = await client.getBatchTestStatus(resolvedAppId, "prompt", promptId, batchId);
             // Get instance IDs that are still running
@@ -1244,26 +973,29 @@ Examples:
     // ============================================
     const attachments = tests
         .command("attachments")
-        .description("Manage test case file attachments")
+        .description("Inspect test case file attachments")
         .addHelpText("after", `
+Attachments are authored as files in prompts/<key>.tests/<name>/ and applied
+with \`primitive config push\` (#2769); removing one and running
+\`config push --prune\` deletes it server-side. These verbs read server state.
+
 Examples:
-  $ primitive prompts tests attachments list <prompt-id> <test-case-id>
-  $ primitive prompts tests attachments upload <prompt-id> <test-case-id> ./document.pdf
-  $ primitive prompts tests attachments download <prompt-id> <test-case-id> document.pdf
-  $ primitive prompts tests attachments delete <prompt-id> <test-case-id> document.pdf
+  $ primitive prompts tests attachments list <prompt> <test-case-id>
+  $ primitive prompts tests attachments download <prompt> <test-case-id> document.pdf
 `);
     // List attachments
     attachments
         .command("list")
         .description("List attachments for a test case")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
-        .action(async (promptId, testCaseId, options) => {
+        .action(async (prompt, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             const result = await client.listTestCaseAttachments(resolvedAppId, "prompt", promptId, testCaseId);
             if (options.json) {
                 json(result.attachments);
@@ -1288,62 +1020,20 @@ Examples:
             process.exit(1);
         }
     });
-    // Upload attachment
-    attachments
-        .command("upload")
-        .description("Upload a file attachment to a test case")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .argument("<file-path>", "Path to the file to upload")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Override the filename")
-        .option("--json", "Output as JSON")
-        .action(async (promptId, testCaseId, filePath, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            // Check file exists and get stats
-            const stats = statSync(filePath);
-            if (!stats.isFile()) {
-                error(`Not a file: ${filePath}`);
-                process.exit(1);
-            }
-            // Check file size (10 MB limit)
-            const TEN_MB = 10 * 1024 * 1024;
-            if (stats.size > TEN_MB) {
-                error(`File too large (max 10MB): ${formatFileSize(stats.size)}`);
-                process.exit(1);
-            }
-            const filename = options.name || basename(filePath);
-            const data = readFileSync(filePath);
-            const contentType = mimeLookup(filePath) || "application/octet-stream";
-            const result = await client.uploadTestCaseAttachment(resolvedAppId, "prompt", promptId, testCaseId, filename, data, contentType);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Uploaded: ${filename}`);
-            keyValue("Size", formatFileSize(result.attachment.size));
-            keyValue("Type", result.attachment.contentType);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // Download attachment
     attachments
         .command("download")
         .description("Download a file attachment from a test case")
-        .argument("<prompt-id>", "Prompt ID")
+        .argument("<prompt>", "Prompt key or ID")
         .argument("<test-case-id>", "Test Case ID")
         .argument("<filename>", "Name of the file to download")
         .argument("[output-path]", "Output path (defaults to current directory)")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .action(async (promptId, testCaseId, filename, outputPath, options) => {
+        .action(async (prompt, testCaseId, filename, outputPath, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
+            const promptId = await resolvePromptId(client, resolvedAppId, prompt);
             const result = await client.downloadTestCaseAttachment(resolvedAppId, "prompt", promptId, testCaseId, filename);
             const finalPath = outputPath || filename;
             writeFileSync(finalPath, result.data);
@@ -1356,42 +1046,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Delete attachment
-    attachments
-        .command("delete")
-        .description("Delete a file attachment from a test case")
-        .argument("<prompt-id>", "Prompt ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .argument("<filename>", "Name of the file to delete")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .action(async (promptId, testCaseId, filename, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to delete attachment "${filename}"?`,
-                    default: false,
-                },
-            ]);
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            await client.deleteTestCaseAttachment(resolvedAppId, "prompt", promptId, testCaseId, filename);
-            success(`Deleted: ${filename}`);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
 }
 function formatFileSize(bytes) {
     if (bytes < 1024)