speqs 0.5.0 → 0.6.0

package/dist/commands/config.js

@@ -2,6 +2,7 @@
  * speqs config — Manage simulation configs.
  */
 import { withClient, readJsonFileOrStdin } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatConfigList } from "../lib/output.js";
 export function registerConfigCommands(program) {
     const config = program
@@ -25,7 +26,10 @@ export function registerConfigCommands(program) {
         await withClient(cmd, async (client, globals) => {
             const body = await readJsonFileOrStdin(opts.file);
             const data = await client.post("/dev/simulation-configs", body);
-            output(data, globals.json);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.config, String(result.id));
+            output(result, globals.json);
         });
     });
     config
@@ -34,8 +38,11 @@ export function registerConfigCommands(program) {
         .argument("<id>", "Config ID")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/dev/simulation-configs/${id}`);
-            output(data, globals.json);
+            const data = await client.get(`/dev/simulation-configs/${resolveId(id)}`);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.config, String(result.id));
+            output(result, globals.json);
         });
     });
     config
@@ -55,8 +62,11 @@ export function registerConfigCommands(program) {
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = await readJsonFileOrStdin(opts.file);
-            const data = await client.put(`/dev/simulation-configs/${id}`, body);
-            output(data, globals.json);
+            const data = await client.put(`/dev/simulation-configs/${resolveId(id)}`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.config, String(result.id));
+            output(result, globals.json);
         });
     });
     config
@@ -65,7 +75,7 @@ export function registerConfigCommands(program) {
         .argument("<id>", "Config ID")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            await client.del(`/dev/simulation-configs/${id}`);
+            await client.del(`/dev/simulation-configs/${resolveId(id)}`);
             output({ message: "Config deleted" }, globals.json);
         });
     });

package/dist/commands/iteration.js

@@ -1,7 +1,8 @@
 /**
  * speqs iteration — Manage iterations (usually created via `simulation run`).
  */
-import { withClient } from "../lib/command-helpers.js";
+import { withClient, resolveStudy } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatIterationList } from "../lib/output.js";
 export function registerIterationCommands(program) {
     const iteration = program
@@ -10,40 +11,76 @@ export function registerIterationCommands(program) {
     iteration
         .command("list")
         .description("List iterations for a study")
-        .requiredOption("--study <id>", "Study ID")
+        .option("--study <id>", "Study ID")
         .addHelpText("after", "\nExamples:\n  $ speqs iteration list --study <id>\n  $ speqs iteration list --study <id> --json")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/studies/${opts.study}/iterations`);
+            const data = await client.get(`/studies/${resolveStudy(opts.study)}/iterations`);
             formatIterationList(data, globals.json);
         });
     });
     iteration
         .command("create")
         .description("Create a new iteration (low-level)")
-        .requiredOption("--study <id>", "Study ID")
+        .option("--study <id>", "Study ID")
         .requiredOption("--name <name>", "Iteration name")
         .option("--description <description>", "Iteration description")
         .option("--details-json <json>", "Iteration details as JSON string")
+        .addHelpText("after", `
+Examples:
+  # Interactive:
+  $ speqs iteration create --study S --name "v1" \\
+    --details-json '{"type":"interactive","platform":"browser","url":"https://example.com","screen_format":"desktop"}'
+
+  # Text/email:
+  $ speqs iteration create --study S --name "v1" \\
+    --details-json '{"type":"text","content_text":"Your email content here","title":"Newsletter"}'
+
+  # Video:
+  $ speqs iteration create --study S --name "v1" \\
+    --details-json '{"type":"video","content_url":"https://cdn.example.com/video.mp4","mime_type":"video/mp4"}'
+
+  # Image:
+  $ speqs iteration create --study S --name "v1" \\
+    --details-json '{"type":"image","image_urls":["https://cdn.example.com/a.png","https://cdn.example.com/b.png"]}'
+
+  # Document (PDF):
+  $ speqs iteration create --study S --name "v1" \\
+    --details-json '{"type":"document","content_url":"https://cdn.example.com/report.pdf","mime_type":"application/pdf"}'
+
+  Note: For local file uploads, use \`speqs simulation run\` which automatically
+  uploads files and resolves URLs (e.g. --content-url ./video.mp4).`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = {
                 name: opts.name,
-                ...(opts.description && { description: opts.description }),
-                ...(opts.detailsJson && { details: JSON.parse(opts.detailsJson) }),
+                ...(opts.description !== undefined && { description: opts.description }),
+                ...(opts.detailsJson && { details: (() => { try {
+                        return JSON.parse(opts.detailsJson);
+                    }
+                    catch {
+                        throw new Error("Invalid --details-json: expected valid JSON string");
+                    } })() }),
             };
-            const data = await client.post(`/studies/${opts.study}/iterations`, body);
-            output(data, globals.json);
+            const data = await client.post(`/studies/${resolveStudy(opts.study)}/iterations`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            output(result, globals.json);
         });
     });
     iteration
         .command("get")
         .description("Get iteration details")
         .argument("<id>", "Iteration ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs iteration get <id>\n  $ speqs iteration get <id> --json")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/iterations/${id}`);
-            output(data, globals.json);
+            const data = await client.get(`/iterations/${resolveId(id)}`);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            output(result, globals.json);
         });
     });
     iteration
@@ -54,6 +91,7 @@ export function registerIterationCommands(program) {
         .option("--description <description>", "Iteration description")
         .option("--details-json <json>", "Iteration details as JSON string")
         .option("--label <label>", "Iteration label (uppercase letters)")
+        .addHelpText("after", "\nExamples:\n  $ speqs iteration update <id> --name \"v2\"\n  $ speqs iteration update <id> --label B --json")
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = {};
@@ -61,21 +99,35 @@ export function registerIterationCommands(program) {
                 body.name = opts.name;
             if (opts.description !== undefined)
                 body.description = opts.description;
-            if (opts.detailsJson !== undefined)
-                body.details = JSON.parse(opts.detailsJson);
+            if (opts.detailsJson !== undefined) {
+                try {
+                    body.details = JSON.parse(opts.detailsJson);
+                }
+                catch {
+                    throw new Error("Invalid --details-json: expected valid JSON string");
+                }
+            }
             if (opts.label !== undefined)
                 body.label = opts.label;
-            const data = await client.put(`/iterations/${id}`, body);
-            output(data, globals.json);
+            if (Object.keys(body).length === 0) {
+                console.error("No update flags provided. Run `speqs iteration update --help` for options.");
+                return;
+            }
+            const data = await client.put(`/iterations/${resolveId(id)}`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+            output(result, globals.json);
         });
     });
     iteration
         .command("delete")
         .description("Delete an iteration")
         .argument("<id>", "Iteration ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs iteration delete <id>")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            await client.del(`/iterations/${id}`);
+            await client.del(`/iterations/${resolveId(id)}`);
             output({ message: "Iteration deleted" }, globals.json);
         });
     });

package/dist/commands/simulation.d.ts

@@ -4,7 +4,7 @@
  * Primary command: `speqs simulation run` — orchestrates the full flow:
  *   1. Creates iteration (if not provided)
  *   2. Creates testers from profiles
- *   3. Starts simulations
+ *   3. Starts simulations (interactive or media, based on study modality)
  */
 import type { Command } from "commander";
 export declare function registerSimulationCommands(program: Command): void;