@apicircle/cli 1.0.0 → 1.0.2

package/dist/index.js

@@ -82,7 +82,6 @@ function installShutdown(handle) {
 }
 
 // src/commands/mcp.ts
-import * as path3 from "path";
 import kleur2 from "kleur";
 import {
   createMcpServer,
@@ -149,10 +148,258 @@ async function ensureWorkspace(dir) {
   return fresh;
 }
 
+// src/util/resolveWorkspace.ts
+import * as os from "os";
+import * as path3 from "path";
+import { promises as fs3 } from "fs";
+import {
+  findWorkspaceEntry,
+  loadRegistry,
+  registerWorkspace,
+  saveRegistry,
+  workspaceDirFor
+} from "@apicircle/core/workspace/registry";
+import { saveToFile as saveToFile2 } from "@apicircle/core/workspace/file-backed";
+import { generateId as generateId3 } from "@apicircle/shared";
+var APP_NAME = "@apicircle";
+var APP_SUBDIR = "desktop";
+var WORKSPACES_DIRNAME = "workspaces";
+function defaultWorkspacesRoot() {
+  const override = process.env.APICIRCLE_WORKSPACES_ROOT;
+  if (override && override.length > 0) return path3.resolve(override);
+  return path3.join(electronUserDataDir(), WORKSPACES_DIRNAME);
+}
+function electronUserDataDir() {
+  const home = os.homedir();
+  switch (process.platform) {
+    case "win32": {
+      const appdata = process.env.APPDATA ?? path3.join(home, "AppData", "Roaming");
+      return path3.join(appdata, APP_NAME, APP_SUBDIR);
+    }
+    case "darwin":
+      return path3.join(home, "Library", "Application Support", APP_NAME, APP_SUBDIR);
+    default:
+      return path3.join(
+        process.env.XDG_CONFIG_HOME ?? path3.join(home, ".config"),
+        APP_NAME,
+        APP_SUBDIR
+      );
+  }
+}
+async function resolveWorkspace(opts = {}) {
+  const root = opts.workspacesRoot ?? defaultWorkspacesRoot();
+  const nameSelector = opts.name?.trim();
+  const pathSelector = opts.path?.trim();
+  const expectExists = opts.expectExists ?? true;
+  if (nameSelector && pathSelector) {
+    throw new WorkspaceResolutionError(
+      "--workspace-name and --workspace-path are mutually exclusive. Pass one or neither.",
+      "both-flags"
+    );
+  }
+  if (pathSelector) {
+    const expanded = expandTilde(pathSelector);
+    const dir = path3.resolve(expanded);
+    if (expectExists && !await dirExists(dir)) {
+      throw new WorkspaceResolutionError(`Workspace directory not found: ${dir}`, "path-missing");
+    }
+    return { dir, id: null, name: null, fromRegistry: false, registryRoot: null };
+  }
+  const registry = await loadRegistry(root);
+  if (nameSelector) {
+    if (!registry) {
+      throw new WorkspaceResolutionError(
+        `No workspaces are registered at ${root}. Open the desktop app once to seed the registry, or pass --workspace-path <dir> to point at a workspace directory directly.`,
+        "no-registry"
+      );
+    }
+    const entry2 = findWorkspaceEntry(registry, nameSelector);
+    if (!entry2) {
+      throw new WorkspaceResolutionError(
+        `No workspace named "${nameSelector}" in the registry at ${root}. Run \`apicircle workspaces list\` to see what's available.`,
+        "not-found"
+      );
+    }
+    return {
+      dir: workspaceDirFor(root, entry2.id),
+      id: entry2.id,
+      name: entry2.name,
+      fromRegistry: true,
+      registryRoot: root
+    };
+  }
+  if (registry && registry.activeWorkspaceId) {
+    const active = registry.workspaces.find((w) => w.id === registry.activeWorkspaceId);
+    if (active) {
+      return {
+        dir: workspaceDirFor(root, active.id),
+        id: active.id,
+        name: active.name,
+        fromRegistry: true,
+        registryRoot: root
+      };
+    }
+  }
+  return {
+    dir: path3.resolve(process.cwd()),
+    id: null,
+    name: null,
+    fromRegistry: false,
+    registryRoot: null
+  };
+}
+async function createWorkspaceOnDisk(args) {
+  const root = args.workspacesRoot ?? defaultWorkspacesRoot();
+  const trimmed = args.name.trim();
+  if (!trimmed) throw new Error("Workspace name is required");
+  const existing = await loadRegistry(root);
+  if (existing && existing.workspaces.some((w) => w.name.toLowerCase() === trimmed.toLowerCase())) {
+    throw new Error(`A workspace named "${trimmed}" already exists`);
+  }
+  const workspaceId = generateId3();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const state = buildEmptyState(workspaceId, now, args.sampleRequest ?? false);
+  const dir = workspaceDirFor(root, workspaceId);
+  await saveToFile2(dir, state);
+  const entry2 = {
+    id: workspaceId,
+    name: trimmed,
+    createdAt: now,
+    lastOpenedAt: now
+  };
+  const registry = await registerWorkspace(root, entry2);
+  return { registry, entry: entry2, state, dir };
+}
+async function listWorkspacesOnDisk(args = {}) {
+  const root = args.workspacesRoot ?? defaultWorkspacesRoot();
+  const registry = await loadRegistry(root) ?? {
+    schemaVersion: 1,
+    activeWorkspaceId: null,
+    workspaces: []
+  };
+  return { registry, root };
+}
+async function saveRegistryToDisk(registry, workspacesRoot) {
+  await saveRegistry(workspacesRoot ?? defaultWorkspacesRoot(), registry);
+}
+var WorkspaceResolutionError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "WorkspaceResolutionError";
+    this.code = code;
+  }
+};
+function expandTilde(value) {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path3.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+async function dirExists(p) {
+  try {
+    const st = await fs3.stat(p);
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+function buildEmptyState(workspaceId, now, withSample) {
+  const sample = withSample ? {
+    id: generateId3(),
+    name: "Sample: GET /anything",
+    folderId: null,
+    method: "GET",
+    url: "https://httpbin.org/anything",
+    headers: [{ key: "Accept", value: "application/json", enabled: true }],
+    query: [],
+    body: { type: "none", content: "" },
+    auth: { type: "inherit" },
+    contextVars: [],
+    extractions: [],
+    assertions: [],
+    createdAt: now,
+    updatedAt: now
+  } : null;
+  const folders = {};
+  const requests = sample ? { [sample.id]: sample } : {};
+  return {
+    synced: {
+      schemaVersion: 1,
+      workspaceId,
+      collections: {
+        tree: {
+          id: generateId3(),
+          type: "root",
+          children: sample ? [{ kind: "request", id: sample.id }] : []
+        },
+        requests,
+        folders
+      },
+      environments: { items: {}, activeName: null, priorityOrder: [] },
+      linkedWorkspaces: {},
+      linkedOverrides: { requests: {}, environmentVars: {} },
+      releases: { self: null, perLink: {} },
+      globalAssets: { schemas: {}, graphql: {} },
+      mockServers: {},
+      meta: { createdAt: now, updatedAt: now, appVersion: "1.0.0" }
+    },
+    local: {
+      schemaVersion: 1,
+      workspaceId,
+      executionPlans: {},
+      history: { requestRuns: [], planRuns: [] },
+      secretIndex: { entries: {} },
+      sessions: { github: { workspace: null, links: {} } },
+      connectedRepo: null,
+      workingBranch: null,
+      seededWorkspaceSha: null,
+      retiredBranch: null,
+      sync: { lastPulledSnapshot: null, lastPulledSha: null, lastPulledAt: null, dirtyKeys: [] },
+      linkedCollections: {},
+      globalContext: {},
+      mockRuntime: { active: {} },
+      ui: {
+        activeRequestId: sample?.id ?? null,
+        sidebarExpandedSections: [],
+        themeId: "studio-dark",
+        fontId: "system-mono",
+        fontSizePercent: 100
+      },
+      settings: { validateOnSend: true, monacoConsumesWheel: false },
+      snapshots: { entries: [], maxBytes: 50 * 1024 * 1024 }
+    }
+  };
+}
+
 // src/commands/mcp.ts
 function registerMcpCommand(program) {
-  program.command("mcp").description("Run the APICircle MCP server (stdio transport)").option("-w, --workspace <dir>", "Workspace directory (defaults to current directory)").action(async (opts) => {
-    const dir = path3.resolve(opts.workspace ?? process.cwd());
+  program.command("mcp").description("Run the API Circle MCP server (stdio transport)").option(
+    "--workspace-name <name-or-id>",
+    "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
+  ).option(
+    "--workspace-path <dir>",
+    "Filesystem directory containing workspace.synced.json (skips the registry)."
+  ).action(async (opts) => {
+    let dir;
+    let label;
+    try {
+      const resolved = await resolveWorkspace({
+        name: opts.workspaceName,
+        path: opts.workspacePath,
+        expectExists: false
+      });
+      dir = resolved.dir;
+      label = resolved.fromRegistry ? `${resolved.name ?? resolved.id} (${dir})` : dir;
+    } catch (err) {
+      if (err instanceof WorkspaceResolutionError) {
+        process.stderr.write(`${kleur2.red("error")}: ${err.message}
+`);
+        process.exit(2);
+      }
+      throw err;
+    }
     try {
       await ensureWorkspace(dir);
     } catch (err) {
@@ -165,27 +412,54 @@ function registerMcpCommand(program) {
     const workspace = new FileBackedWorkspaceProvider(dir);
     const mock = new InProcessMockController();
     const host = createMcpServer({ workspace, mock });
-    process.stderr.write(`${kleur2.green("apicircle-mcp")} ready \xB7 workspace=${dir}
+    process.stderr.write(`${kleur2.green("apicircle-mcp")} ready \xB7 workspace=${label}
 `);
     await host.connect();
   });
 }
 
 // src/commands/import.ts
-import { promises as fs3 } from "fs";
+import { promises as fs4 } from "fs";
 import * as path4 from "path";
 import kleur3 from "kleur";
 import { applyMutation } from "@apicircle/core";
-import { saveToFile as saveToFile2 } from "@apicircle/core/workspace/file-backed";
+import { saveToFile as saveToFile3 } from "@apicircle/core/workspace/file-backed";
 import {
   parseInsomniaToEndpoints,
   parseOpenApiToEndpoints,
   parsePostmanToEndpoints
 } from "@apicircle/mock-server-core";
-import { generateId as generateId3 } from "@apicircle/shared";
+import { generateId as generateId4 } from "@apicircle/shared";
 function registerImportCommand(program) {
-  program.command("import").description("Import a spec into a workspace folder").argument("<type>", "Source type: openapi | postman | insomnia | curl").argument("<input>", "Path to a spec file, or `-` to read from stdin").option("-w, --workspace <dir>", "Workspace directory (defaults to current directory)").option("-f, --format <format>", "OpenAPI format: json | yaml", "json").action(async (type, input, opts) => {
-    const dir = path4.resolve(opts.workspace ?? process.cwd());
+  program.command("import").description("Import a spec into a workspace folder").argument("<type>", "Source type: openapi | postman | insomnia | curl").argument("<input>", "Path to a spec file, or `-` to read from stdin").option(
+    "--workspace-name <name-or-id>",
+    "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
+  ).option(
+    "--workspace-path <dir>",
+    "Filesystem directory containing workspace.synced.json (skips the registry)."
+  ).option("-f, --format <format>", "OpenAPI format: json | yaml", "json").action(async (type, input, opts) => {
+    let dir;
+    try {
+      const resolved = await resolveWorkspace({
+        name: opts.workspaceName,
+        path: opts.workspacePath,
+        expectExists: false
+      });
+      dir = resolved.dir;
+      if (resolved.fromRegistry) {
+        process.stderr.write(
+          `${kleur3.dim("workspace")}: ${kleur3.cyan(resolved.name ?? resolved.id ?? "")} ${kleur3.dim(`(${dir})`)}
+`
+        );
+      }
+    } catch (err) {
+      if (err instanceof WorkspaceResolutionError) {
+        process.stderr.write(`${kleur3.red("error")}: ${err.message}
+`);
+        process.exit(2);
+      }
+      throw err;
+    }
     const raw = await readInput(input);
     const state = await ensureWorkspace(dir);
     let nextSynced = state.synced;
@@ -252,7 +526,7 @@ function registerImportCommand(program) {
 `);
       process.exit(2);
     }
-    await saveToFile2(dir, { synced: nextSynced, local: nextLocal });
+    await saveToFile3(dir, { synced: nextSynced, local: nextLocal });
     process.stdout.write(
       `${kleur3.green("imported")} ${created.length} request${created.length === 1 ? "" : "s"} into ${dir}
 `
@@ -261,22 +535,22 @@ function registerImportCommand(program) {
 }
 async function readInput(p) {
   if (p === "-") {
-    return new Promise((resolve7, reject) => {
+    return new Promise((resolve6, reject) => {
       let data = "";
       process.stdin.setEncoding("utf-8");
       process.stdin.on("data", (chunk) => {
         data += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
       });
-      process.stdin.on("end", () => resolve7(data));
+      process.stdin.on("end", () => resolve6(data));
       process.stdin.on("error", reject);
     });
   }
-  return fs3.readFile(path4.resolve(p), "utf-8");
+  return fs4.readFile(path4.resolve(p), "utf-8");
 }
 function blankRequest(partial) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   return {
-    id: generateId3(),
+    id: generateId4(),
     folderId: null,
     headers: [],
     query: [],
@@ -292,8 +566,7 @@ function blankRequest(partial) {
 }
 
 // src/commands/run.ts
-import * as os from "os";
-import * as path6 from "path";
+import * as os2 from "os";
 import kleur4 from "kleur";
 import {
   ANONYMOUS_ACTOR,
@@ -301,11 +574,11 @@ import {
   resolvePlanRef,
   runPlan
 } from "@apicircle/core";
-import { loadFromFile as loadFromFile2, saveToFile as saveToFile3 } from "@apicircle/core/workspace/file-backed";
+import { loadFromFile as loadFromFile2, saveToFile as saveToFile4 } from "@apicircle/core/workspace/file-backed";
 
 // src/util/secrets.ts
 import * as path5 from "path";
-import { promises as fs4 } from "fs";
+import { promises as fs5 } from "fs";
 var DEFAULT_PREFIX = "APICIRCLE_SECRET_";
 async function buildSecretsFromCli(options = {}) {
   const env = options.env ?? process.env;
@@ -313,7 +586,7 @@ async function buildSecretsFromCli(options = {}) {
   const byId = {};
   if (options.secretsFile) {
     const resolved = path5.resolve(options.secretsFile);
-    const raw = await fs4.readFile(resolved, "utf8");
+    const raw = await fs5.readFile(resolved, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error(
@@ -338,8 +611,34 @@ async function buildSecretsFromCli(options = {}) {
 // src/commands/run.ts
 var REPORTERS = ["text", "json", "junit"];
 function registerRunCommand(program) {
-  program.command("run").description("Run a saved execution plan from a workspace and report the result").argument("<plan>", "Plan name or id to run").option("-w, --workspace <dir>", "Workspace directory (defaults to current directory)").option("--no-assertions", "Run requests without evaluating their assertions").option("-s, --secrets <file>", "JSON file mapping secretKeyId \u2192 plaintext value").option("--no-save", "Do not write the plan run to workspace history").option("--reporter <format>", "Report format: text | json | junit", "text").option("--bail", "Stop the run at the first failed step").option("-e, --env <name>", "Layer a local environment on top of the run").option("--as <actor>", "Override the recorded runner identity").action(async (planRef, opts) => {
-    const dir = path6.resolve(opts.workspace ?? process.cwd());
+  program.command("run").description("Run a saved execution plan from a workspace and report the result").argument("<plan>", "Plan name or id to run").option(
+    "--workspace-name <name-or-id>",
+    "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
+  ).option(
+    "--workspace-path <dir>",
+    "Filesystem directory containing workspace.synced.json (skips the registry)."
+  ).option("--no-assertions", "Run requests without evaluating their assertions").option("-s, --secrets <file>", "JSON file mapping secretKeyId \u2192 plaintext value").option("--no-save", "Do not write the plan run to workspace history").option("--reporter <format>", "Report format: text | json | junit", "text").option("--bail", "Stop the run at the first failed step").option("-e, --env <name>", "Layer a local environment on top of the run").option("--as <actor>", "Override the recorded runner identity").action(async (planRef, opts) => {
+    let dir;
+    try {
+      const resolved = await resolveWorkspace({
+        name: opts.workspaceName,
+        path: opts.workspacePath,
+        expectExists: false
+      });
+      dir = resolved.dir;
+      if (resolved.fromRegistry) {
+        process.stderr.write(
+          `${kleur4.dim("workspace")}: ${kleur4.cyan(resolved.name ?? resolved.id ?? "")} ${kleur4.dim(`(${dir})`)}
+`
+        );
+      }
+    } catch (err) {
+      if (err instanceof WorkspaceResolutionError) {
+        fail(err.message);
+        return;
+      }
+      throw err;
+    }
     const reporter = opts.reporter ?? "text";
     if (!isReporter(reporter)) {
       fail(`unknown --reporter "${reporter}" (expected: ${REPORTERS.join(", ")})`);
@@ -405,7 +704,7 @@ function registerRunCommand(program) {
     process.off("SIGINT", onSigint);
     const aborted = controller.signal.aborted;
     const saved = opts.save !== false;
-    if (saved) await saveToFile3(dir, result.nextState);
+    if (saved) await saveToFile4(dir, result.nextState);
     if (reporter === "json") {
       process.stdout.write(
         JSON.stringify(
@@ -431,7 +730,7 @@ function resolveActor(local, override) {
   const login = local.sessions.github.workspace?.accountLogin;
   if (login) return { kind: "github", name: login };
   try {
-    const username = os.userInfo().username;
+    const username = os2.userInfo().username;
     if (username) return { kind: "os", name: username };
   } catch {
   }
@@ -597,14 +896,126 @@ function fail(message, code = 2, kind = "error") {
   process.exitCode = code;
 }
 
+// src/commands/workspaces.ts
+import kleur5 from "kleur";
+import { findWorkspaceEntry as findWorkspaceEntry2, setActiveWorkspace } from "@apicircle/core/workspace/registry";
+function registerWorkspacesCommand(program) {
+  const ws = program.command("workspaces").description("List, create, or switch the active workspace");
+  ws.command("list").description("List every workspace registered on this machine").option("--json", "Emit JSON instead of a formatted table").action(async (opts) => {
+    const { registry, root } = await listWorkspacesOnDisk();
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ root, registry }, null, 2) + "\n");
+      return;
+    }
+    if (registry.workspaces.length === 0) {
+      process.stdout.write(
+        `${kleur5.dim("No workspaces registered yet at")} ${root}
+${kleur5.dim("Run")} ${kleur5.cyan("apicircle workspaces create <name>")} ${kleur5.dim(
+          "or open the desktop app to seed one."
+        )}
+`
+      );
+      return;
+    }
+    process.stdout.write(`${kleur5.dim("registry")}: ${root}
+
+`);
+    const rows = [...registry.workspaces].sort(
+      (a, b) => b.lastOpenedAt.localeCompare(a.lastOpenedAt)
+    );
+    const nameWidth = Math.max(4, ...rows.map((r) => r.name.length));
+    const idWidth = Math.max(2, ...rows.map((r) => r.id.length));
+    process.stdout.write(
+      kleur5.bold(
+        `  ${"".padEnd(1)} ${"NAME".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  LAST OPENED
+`
+      )
+    );
+    for (const w of rows) {
+      const mark = w.id === registry.activeWorkspaceId ? kleur5.green("\u25CF") : " ";
+      process.stdout.write(
+        `  ${mark} ${w.name.padEnd(nameWidth)}  ${kleur5.dim(
+          w.id.padEnd(idWidth)
+        )}  ${kleur5.dim(w.lastOpenedAt)}
+`
+      );
+    }
+    process.stdout.write(`
+${kleur5.dim("\u25CF = active")}
+`);
+  });
+  ws.command("create").description("Create a new workspace and add it to the registry").argument("<name>", "Human-readable label for the workspace").option("--sample", "Seed the workspace with one sample request", false).action(async (name, opts) => {
+    try {
+      const { entry: entry2, dir, registry } = await createWorkspaceOnDisk({
+        name,
+        sampleRequest: opts.sample ?? false
+      });
+      process.stdout.write(
+        `${kleur5.green("created")} workspace ${kleur5.cyan(entry2.name)} ${kleur5.dim(`(${entry2.id})`)}
+  at ${dir}
+`
+      );
+      if (registry.activeWorkspaceId === entry2.id) {
+        process.stdout.write(`${kleur5.dim("marked as active")}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(
+        `${kleur5.red("error")}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(2);
+    }
+  });
+  ws.command("use").description("Set the active workspace by id or name").argument("<selector>", "Workspace id or name").action(async (selector) => {
+    const { registry, root } = await listWorkspacesOnDisk();
+    const entry2 = findWorkspaceEntry2(registry, selector);
+    if (!entry2) {
+      process.stderr.write(
+        `${kleur5.red("error")}: no workspace named "${selector}" in the registry at ${root}.
+${kleur5.dim("Run")} ${kleur5.cyan("apicircle workspaces list")} ${kleur5.dim("to see what is available.")}
+`
+      );
+      process.exit(2);
+      return;
+    }
+    const next = await setActiveWorkspace(root, entry2.id);
+    void next;
+    process.stdout.write(
+      `${kleur5.green("active")} workspace is now ${kleur5.cyan(entry2.name)} ${kleur5.dim(`(${entry2.id})`)}
+`
+    );
+  });
+  ws.command("path").description("Print the on-disk path for a workspace (or the workspaces root)").argument("[selector]", "Optional workspace id or name; prints the root when omitted").action(async (selector) => {
+    if (!selector) {
+      process.stdout.write(defaultWorkspacesRoot() + "\n");
+      return;
+    }
+    const { registry, root } = await listWorkspacesOnDisk();
+    const entry2 = findWorkspaceEntry2(registry, selector);
+    if (!entry2) {
+      process.stderr.write(
+        `${kleur5.red("error")}: no workspace named "${selector}" in the registry at ${root}.
+`
+      );
+      process.exit(2);
+      return;
+    }
+    void saveRegistryToDisk;
+    const { workspaceDirFor: workspaceDirFor2 } = await import("@apicircle/core/workspace/registry");
+    process.stdout.write(workspaceDirFor2(root, entry2.id) + "\n");
+  });
+}
+
 // src/index.ts
 function buildProgram() {
   const program = new Command();
-  program.name("apicircle").description("Command-line companion to APICircle Studio.").version("1.0.0");
+  program.name("apicircle").description("Command-line companion to API Circle Studio.").version("1.0.0");
   registerMockCommand(program);
   registerMcpCommand(program);
   registerImportCommand(program);
   registerRunCommand(program);
+  registerWorkspacesCommand(program);
   return program;
 }
 async function runCli(argv = process.argv) {