speqs 0.4.0 → 0.5.1

package/dist/commands/study.js

@@ -0,0 +1,170 @@
+/**
+ * speqs study — Manage studies.
+ */
+import { withClient, getWebUrl, terminalLink } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { formatStudyList, formatStudyDetail, formatStudyResults, output } from "../lib/output.js";
+export function registerStudyCommands(program) {
+    const study = program
+        .command("study")
+        .description("Manage studies");
+    study
+        .command("list")
+        .description("List studies for a workspace")
+        .requiredOption("--workspace <id>", "Workspace ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs study list --workspace <id>\n  $ speqs study list --workspace <id> --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/products/${resolveId(opts.workspace)}/studies`);
+            formatStudyList(data, globals.json);
+        });
+    });
+    study
+        .command("create")
+        .description("Create a new study")
+        .requiredOption("--workspace <id>", "Workspace ID")
+        .requiredOption("--name <name>", "Study name")
+        .option("--description <description>", "Study description")
+        .option("--modality <modality>", "Study modality (interactive, video, audio, text, image)")
+        .option("--content-type <type>", "Content type")
+        .option("--assignments <json>", "JSON array of assignments, e.g. '[{\"name\":\"Task\",\"instructions\":\"Do something\"}]'")
+        .option("--questions <json>", "JSON array of interview questions, e.g. '[{\"question\":\"How was it?\",\"type\":\"text\",\"timing\":\"after\"}]'")
+        .addHelpText("after", `
+Examples:
+  # Create with assignments (required for simulations):
+  $ speqs study create --workspace <id> --name "Onboarding UX" --modality interactive \\
+    --assignments '[{"name":"Sign up","instructions":"Complete the signup flow"}]'
+
+  # Create with assignments and interview questions:
+  $ speqs study create --workspace <id> --name "Checkout" --modality interactive \\
+    --assignments '[{"name":"Buy item","instructions":"Add an item to cart and checkout"}]' \\
+    --questions '[{"question":"How easy was checkout?","type":"slider","timing":"after","min":0,"max":10}]'
+
+  # Minimal (note: assignments are needed before running simulations):
+  $ speqs study create --workspace <id> --name "Landing Page" --json`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            let assignments;
+            let interviewQuestions;
+            if (opts.assignments) {
+                try {
+                    assignments = JSON.parse(opts.assignments);
+                }
+                catch {
+                    throw new Error("Invalid --assignments JSON");
+                }
+            }
+            if (opts.questions) {
+                try {
+                    interviewQuestions = JSON.parse(opts.questions);
+                }
+                catch {
+                    throw new Error("Invalid --questions JSON");
+                }
+            }
+            const resolvedWs = resolveId(opts.workspace);
+            const body = {
+                product_id: resolvedWs,
+                name: opts.name,
+                ...(opts.description && { description: opts.description }),
+                ...(opts.modality && { modality: opts.modality }),
+                ...(opts.contentType && { content_type: opts.contentType }),
+                ...(assignments && { assignments }),
+                ...(interviewQuestions && { interview_questions: interviewQuestions }),
+            };
+            const data = await client.post(`/products/${resolvedWs}/studies`, body);
+            formatStudyDetail(data, globals.json);
+            if (!globals.json && data.id) {
+                const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
+                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    study
+        .command("generate")
+        .description("Generate a study from a problem description using AI")
+        .requiredOption("--workspace <id>", "Workspace ID")
+        .requiredOption("--problem <description>", "Problem description (what you want to understand)")
+        .option("--target-url <url>", "URL of the product to test")
+        .addHelpText("after", "\nExamples:\n  $ speqs study generate --workspace <id> --problem \"How do users navigate the onboarding flow?\"\n  $ speqs study generate --workspace <id> --problem \"Test checkout\" --target-url https://example.com --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                problem_description: opts.problem,
+                ...(opts.targetUrl && { target_url: opts.targetUrl }),
+            };
+            const resolvedWs = resolveId(opts.workspace);
+            const data = await client.post(`/products/${resolvedWs}/studies/generate`, body);
+            formatStudyDetail(data, globals.json);
+            if (!globals.json && data.id) {
+                const url = getWebUrl(globals, `/${resolvedWs}/${data.id}/overview`);
+                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    study
+        .command("get")
+        .description("Get study overview (assignments, questions, testers)")
+        .argument("<id>", "Study ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs study get <id>\n  $ speqs study get <id> --json")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            const data = await client.get(`/studies/${rid}`);
+            formatStudyDetail(data, globals.json);
+            if (!globals.json && data.product_id) {
+                const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    study
+        .command("results")
+        .description("View aggregated results (sentiment, interview answers)")
+        .argument("<id>", "Study ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs study results <id>\n  $ speqs study results <id> --json")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            const data = await client.get(`/studies/${rid}`);
+            formatStudyResults(data, globals.json);
+            if (!globals.json && data.product_id) {
+                const url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
+                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    study
+        .command("update")
+        .description("Update a study")
+        .argument("<id>", "Study ID")
+        .option("--name <name>", "Study name")
+        .option("--description <description>", "Study description")
+        .option("--status <status>", "Study status (draft, running, completed)")
+        .option("--modality <modality>", "Study modality")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {};
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.status !== undefined)
+                body.status = opts.status;
+            if (opts.modality !== undefined)
+                body.modality = opts.modality;
+            const data = await client.put(`/studies/${resolveId(id)}`, body);
+            formatStudyDetail(data, globals.json);
+        });
+    });
+    study
+        .command("delete")
+        .description("Delete a study")
+        .argument("<id>", "Study ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/studies/${resolveId(id)}`);
+            output({ message: "Study deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/tester-profile.d.ts

@@ -0,0 +1,5 @@
+/**
+ * speqs tester-profile — Manage tester profiles.
+ */
+import type { Command } from "commander";
+export declare function registerTesterProfileCommands(program: Command): void;

package/dist/commands/tester-profile.js

@@ -0,0 +1,96 @@
+/**
+ * speqs tester-profile — Manage tester profiles.
+ */
+import { withClient, readJsonFileOrStdin } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { formatTesterProfileList, output } from "../lib/output.js";
+export function registerTesterProfileCommands(program) {
+    const profile = program
+        .command("tester-profile")
+        .description("Manage tester profiles");
+    profile
+        .command("list")
+        .description("List tester profiles (defaults to simulatable AI profiles)")
+        .option("--workspace <id>", "Filter by workspace ID")
+        .option("--search <query>", "Search by name or bio")
+        .option("--type <type>", "Profile type: ai, human, all (default: ai)", "ai")
+        .option("--gender <gender>", "Filter by gender")
+        .option("--country <country>", "Filter by country code (e.g. US, GB, SE)")
+        .option("--min-age <n>", "Minimum age")
+        .option("--max-age <n>", "Maximum age")
+        .option("--limit <n>", "Max results (default 50)", "50")
+        .option("--offset <n>", "Offset for pagination", "0")
+        .addHelpText("after", `
+Examples:
+  $ speqs tester-profile list
+  $ speqs tester-profile list --search "engineer" --country US
+  $ speqs tester-profile list --gender female --min-age 25 --max-age 40
+  $ speqs tester-profile list --type all --json`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const params = {
+                limit: opts.limit,
+                offset: opts.offset,
+            };
+            if (opts.workspace)
+                params.product_id = opts.workspace;
+            if (opts.search)
+                params.search = opts.search;
+            if (opts.type !== "all")
+                params.type = opts.type;
+            if (opts.gender)
+                params.gender = opts.gender;
+            if (opts.country)
+                params.country = opts.country;
+            if (opts.minAge)
+                params.min_age = opts.minAge;
+            if (opts.maxAge)
+                params.max_age = opts.maxAge;
+            const data = await client.get("/tester-profiles", params);
+            formatTesterProfileList(data, globals.json, parseInt(opts.limit, 10));
+        });
+    });
+    profile
+        .command("create")
+        .description("Create a tester profile")
+        .requiredOption("--file <path>", "JSON file with profile data")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.post("/tester-profiles", body);
+            output(data, globals.json);
+        });
+    });
+    profile
+        .command("get")
+        .description("Get tester profile details")
+        .argument("<id>", "Tester profile ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/tester-profiles/${resolveId(id)}`);
+            output(data, globals.json);
+        });
+    });
+    profile
+        .command("update")
+        .description("Update a tester profile")
+        .argument("<id>", "Tester profile ID")
+        .requiredOption("--file <path>", "JSON file with update data")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.put(`/tester-profiles/${resolveId(id)}`, body);
+            output(data, globals.json);
+        });
+    });
+    profile
+        .command("delete")
+        .description("Delete a tester profile")
+        .argument("<id>", "Tester profile ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/tester-profiles/${resolveId(id)}`);
+            output({ message: "Tester profile deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/tester.d.ts

@@ -0,0 +1,5 @@
+/**
+ * speqs tester — Manage testers (usually created via `simulation run`).
+ */
+import type { Command } from "commander";
+export declare function registerTesterCommands(program: Command): void;

package/dist/commands/tester.js

@@ -0,0 +1,64 @@
+/**
+ * speqs tester — Manage testers (usually created via `simulation run`).
+ */
+import { withClient, readJsonFileOrStdin } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { formatTesterDetail, output } from "../lib/output.js";
+export function registerTesterCommands(program) {
+    const tester = program
+        .command("tester")
+        .description("Manage testers (usually created via `simulation run`)");
+    tester
+        .command("create")
+        .description("Create a tester (low-level)")
+        .requiredOption("--iteration <id>", "Iteration ID")
+        .requiredOption("--profile <id>", "Tester profile ID")
+        .option("--language <lang>", "Language code (e.g. en, sv)")
+        .option("--platform <platform>", "Platform (browser, android, figma, code)")
+        .option("--tester-type <type>", "Tester type (ai, human)", "ai")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                tester_profile_id: resolveId(opts.profile),
+                tester_type: opts.testerType,
+                ...(opts.language && { language: opts.language }),
+                ...(opts.platform && { platform: opts.platform }),
+            };
+            const data = await client.post(`/iterations/${resolveId(opts.iteration)}/testers`, body);
+            output(data, globals.json);
+        });
+    });
+    tester
+        .command("batch-create")
+        .description("Create multiple testers from a JSON file (low-level)")
+        .requiredOption("--iteration <id>", "Iteration ID")
+        .requiredOption("--file <path>", "JSON file with testers array")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            const data = await client.post(`/iterations/${resolveId(opts.iteration)}/testers/batch`, body);
+            output(data, globals.json);
+        });
+    });
+    tester
+        .command("get")
+        .description("Get tester details and results")
+        .argument("<id>", "Tester ID")
+        .addHelpText("after", "\nExamples:\n  $ speqs tester get <id>\n  $ speqs tester get <id> --json")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/testers/${resolveId(id)}`);
+            formatTesterDetail(data, globals.json);
+        });
+    });
+    tester
+        .command("delete")
+        .description("Delete a tester")
+        .argument("<id>", "Tester ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/testers/${resolveId(id)}`);
+            output({ message: "Tester deleted" }, globals.json);
+        });
+    });
+}

package/dist/commands/workspace.d.ts

@@ -0,0 +1,5 @@
+/**
+ * speqs workspace — Manage workspaces (API: /products).
+ */
+import type { Command } from "commander";
+export declare function registerWorkspaceCommands(program: Command): void;

package/dist/commands/workspace.js

@@ -0,0 +1,88 @@
+/**
+ * speqs workspace — Manage workspaces (API: /products).
+ */
+import { withClient, getWebUrl, terminalLink } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { formatWorkspaceList, formatWorkspaceDetail, output } from "../lib/output.js";
+export function registerWorkspaceCommands(program) {
+    const workspace = program
+        .command("workspace")
+        .description("Manage workspaces");
+    workspace
+        .command("list")
+        .description("List all workspaces")
+        .addHelpText("after", "\nExamples:\n  $ speqs workspace list\n  $ speqs workspace list --json")
+        .action(async (_opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get("/products");
+            formatWorkspaceList(data, globals.json);
+        });
+    });
+    workspace
+        .command("create")
+        .description("Create a new workspace")
+        .requiredOption("--name <name>", "Workspace name")
+        .option("--description <description>", "Workspace description")
+        .option("--base-url <url>", "Default base URL")
+        .addHelpText("after", "\nExamples:\n  $ speqs workspace create --name \"My App\" --base-url https://example.com\n  $ speqs workspace create --name \"My App\" --json")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {
+                name: opts.name,
+                ...(opts.description && { description: opts.description }),
+                ...(opts.baseUrl && { base_url: opts.baseUrl }),
+            };
+            const data = await client.post("/products", body);
+            formatWorkspaceDetail(data, globals.json);
+            if (!globals.json && data.id) {
+                const url = getWebUrl(globals, `/${data.id}`);
+                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    workspace
+        .command("get")
+        .description("Get workspace details")
+        .argument("<id>", "Workspace ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            const data = await client.get(`/products/${rid}`);
+            formatWorkspaceDetail(data, globals.json);
+            if (!globals.json) {
+                const url = getWebUrl(globals, `/${rid}`);
+                console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    workspace
+        .command("update")
+        .description("Update a workspace")
+        .argument("<id>", "Workspace ID")
+        .option("--name <name>", "Workspace name")
+        .option("--description <description>", "Workspace description")
+        .option("--base-url <url>", "Default base URL")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = {};
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.baseUrl !== undefined)
+                body.base_url = opts.baseUrl;
+            const data = await client.put(`/products/${resolveId(id)}`, body);
+            formatWorkspaceDetail(data, globals.json);
+        });
+    });
+    workspace
+        .command("delete")
+        .description("Delete a workspace")
+        .argument("<id>", "Workspace ID")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            await client.del(`/products/${resolveId(id)}`);
+            output({ message: "Workspace deleted" }, globals.json);
+        });
+    });
+}

package/dist/index.js

@@ -4,18 +4,35 @@ import { runTunnel } from "./connect.js";
 import { login, getAppUrl } from "./auth.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { upgrade } from "./upgrade.js";
+import { registerWorkspaceCommands } from "./commands/workspace.js";
+import { registerStudyCommands } from "./commands/study.js";
+import { registerIterationCommands } from "./commands/iteration.js";
+import { registerTesterProfileCommands } from "./commands/tester-profile.js";
+import { registerTesterCommands } from "./commands/tester.js";
+import { registerSimulationCommands } from "./commands/simulation.js";
+import { registerConfigCommands } from "./commands/config.js";
 import pkg from "../package.json" with { type: "json" };
 const { version } = pkg;
 program
     .name("speqs")
-    .description("Speqs CLI tools")
+    .description("Speqs CLI — manage workspaces, studies, simulations, and more")
     .version(version);
+// Global options
+program
+    .option("-t, --token <token>", "Auth token (or set SPEQS_TOKEN env var)")
+    .option("--api-url <url>", "Backend API URL (default: SPEQS_API_URL or https://api.speqs.io)")
+    .addOption(new Option("--dev", "Use local dev API (http://localhost:8000)").hideHelp())
+    .option("--json", "Output as JSON (for programmatic use)")
+    .option("-q, --quiet", "Suppress progress messages on stderr");
+// --- Inline commands (from upstream) ---
 program
     .command("login")
     .description("Authenticate with Speqs via your browser")
-    .action(async () => {
+    .action(async (_opts, cmd) => {
     try {
-        const tokens = await login(getAppUrl());
+        const globals = cmd.optsWithGlobals();
+        const appUrl = globals.dev ? "http://localhost:3000" : getAppUrl();
+        const tokens = await login(appUrl);
         const config = loadConfig();
         config.access_token = tokens.accessToken;
         config.refresh_token = tokens.refreshToken;
@@ -42,18 +59,24 @@ program
     .command("connect")
     .description("Expose your localhost to Speqs via a Cloudflare tunnel")
     .argument("<port>", "Local port to connect (e.g. 3000)")
-    .option("-t, --token <token>", "Auth token (or set SPEQS_TOKEN, or save via interactive prompt)")
-    .option("--api-url <url>", "Backend API URL (default: SPEQS_API_URL or https://api.speqs.io)")
-    .addOption(new Option("--dev", "Use local dev API (http://localhost:8000)").hideHelp())
-    .action(async (port, options) => {
+    .action(async (port, _opts, cmd) => {
     const portNum = parseInt(port, 10);
     if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
         console.error(`Invalid port: ${port}`);
         process.exit(1);
     }
-    const apiUrl = options.dev ? "http://localhost:8000" : options.apiUrl;
-    await runTunnel(portNum, options.token, apiUrl);
+    const globals = cmd.optsWithGlobals();
+    const apiUrl = globals.dev ? "http://localhost:8000" : globals.apiUrl;
+    await runTunnel(portNum, globals.token, apiUrl);
 });
+// --- Modular command groups ---
+registerWorkspaceCommands(program);
+registerStudyCommands(program);
+registerIterationCommands(program);
+registerTesterProfileCommands(program);
+registerTesterCommands(program);
+registerSimulationCommands(program);
+registerConfigCommands(program);
 program
     .command("upgrade")
     .description("Update speqs to the latest version")

package/dist/lib/alias-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Short alias system for entity IDs.
+ *
+ * Maps short aliases like tp1, w2, s3 to full UUIDs.
+ * Aliases are regenerated on every list call and persisted to ~/.speqs/aliases.json.
+ */
+/** Entity type → alias prefix */
+export declare const ALIAS_PREFIX: {
+    readonly workspace: "w";
+    readonly study: "s";
+    readonly iteration: "i";
+    readonly testerProfile: "tp";
+    readonly tester: "t";
+    readonly config: "c";
+    readonly job: "j";
+};
+/**
+ * Save aliases for a list of IDs under the given prefix.
+ * Clears all existing aliases for that prefix before saving.
+ * Numbers start at `startIndex` (default 1) to support pagination.
+ */
+export declare function saveAliases(prefix: string, ids: string[], startIndex?: number): void;
+/**
+ * Build a uuid→alias map for a given prefix (used by formatters to display aliases).
+ */
+export declare function getAliasMap(prefix: string): Map<string, string>;
+/**
+ * Resolve a short alias to a full UUID, or return the input as-is if it's not an alias.
+ */
+export declare function resolveId(input: string): string;

package/dist/lib/alias-store.js

@@ -0,0 +1,90 @@
+/**
+ * Short alias system for entity IDs.
+ *
+ * Maps short aliases like tp1, w2, s3 to full UUIDs.
+ * Aliases are regenerated on every list call and persisted to ~/.speqs/aliases.json.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const ALIASES_FILE = path.join(os.homedir(), ".speqs", "aliases.json");
+/** Entity type → alias prefix */
+export const ALIAS_PREFIX = {
+    workspace: "w",
+    study: "s",
+    iteration: "i",
+    testerProfile: "tp",
+    tester: "t",
+    config: "c",
+    job: "j",
+};
+function loadAliases() {
+    try {
+        if (fs.existsSync(ALIASES_FILE)) {
+            return JSON.parse(fs.readFileSync(ALIASES_FILE, "utf-8"));
+        }
+    }
+    catch {
+        // Corrupted — start fresh
+    }
+    return {};
+}
+function persistAliases(aliases) {
+    const dir = path.dirname(ALIASES_FILE);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = ALIASES_FILE + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(aliases, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, ALIASES_FILE);
+}
+/**
+ * Save aliases for a list of IDs under the given prefix.
+ * Clears all existing aliases for that prefix before saving.
+ * Numbers start at `startIndex` (default 1) to support pagination.
+ */
+export function saveAliases(prefix, ids, startIndex = 1) {
+    const aliases = loadAliases();
+    // Remove existing entries for this prefix
+    const prefixPattern = new RegExp(`^${prefix}\\d+$`);
+    for (const key of Object.keys(aliases)) {
+        if (prefixPattern.test(key)) {
+            delete aliases[key];
+        }
+    }
+    // Save new mappings
+    for (let i = 0; i < ids.length; i++) {
+        aliases[`${prefix}${startIndex + i}`] = ids[i];
+    }
+    persistAliases(aliases);
+}
+/**
+ * Build a uuid→alias map for a given prefix (used by formatters to display aliases).
+ */
+export function getAliasMap(prefix) {
+    const aliases = loadAliases();
+    const map = new Map();
+    const prefixPattern = new RegExp(`^${prefix}\\d+$`);
+    for (const [alias, uuid] of Object.entries(aliases)) {
+        if (prefixPattern.test(alias)) {
+            map.set(uuid, alias);
+        }
+    }
+    return map;
+}
+/**
+ * Resolve a short alias to a full UUID, or return the input as-is if it's not an alias.
+ */
+export function resolveId(input) {
+    // If it looks like a UUID or contains hyphens, pass through
+    if (input.includes("-") || input.length > 20) {
+        return input;
+    }
+    // Check if it matches an alias pattern (letters + digits)
+    if (/^[a-z]+\d+$/.test(input)) {
+        const aliases = loadAliases();
+        const uuid = aliases[input];
+        if (uuid)
+            return uuid;
+        throw new Error(`Unknown alias "${input}". Run a list command first to generate aliases.`);
+    }
+    return input;
+}

package/dist/lib/api-client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared HTTP API client for the Speqs backend.
+ */
+export declare class ApiError extends Error {
+    status: number;
+    statusText: string;
+    body: unknown;
+    error_code: string;
+    retryable: boolean;
+    constructor(status: number, statusText: string, body: unknown);
+}
+export declare class ApiClient {
+    private baseUrl;
+    private token;
+    constructor(opts: {
+        apiUrl: string;
+        token: string;
+    });
+    private headers;
+    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    del(path: string): Promise<void>;
+    private handleResponse;
+}