@apicircle/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,621 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/mock.ts
+import { promises as fs } from "fs";
+import * as path from "path";
+import kleur from "kleur";
+import {
+  parseSourceToEndpoints,
+  startMockServer
+} from "@apicircle/mock-server-core";
+import { generateId } from "@apicircle/shared";
+function registerMockCommand(program) {
+  program.command("mock").description("Run a mock server from an OpenAPI / Postman / Insomnia file").argument("<spec>", "Path to the spec file").option("-p, --port <number>", "TCP port to bind (defaults to a free port)").option("-h, --host <host>", "Hostname to bind", "127.0.0.1").option("-t, --type <type>", "Source type: openapi | postman | insomnia | auto", "auto").option("-f, --format <format>", "OpenAPI format: json | yaml | auto", "auto").option("--cors", "Enable permissive CORS", true).action(async (spec, opts) => {
+    const absolute = path.resolve(spec);
+    const raw = await fs.readFile(absolute, "utf-8");
+    const type = inferType(absolute, opts.type ?? "auto");
+    const format = type === "openapi" ? inferFormat(absolute, opts.format ?? "auto") : "json";
+    const source = makeSource(type, format, raw);
+    const parsed = await parseSourceToEndpoints(source);
+    const mock = {
+      id: generateId(),
+      name: path.basename(absolute),
+      source,
+      endpoints: parsed.endpoints,
+      defaultPort: opts.port ? Number(opts.port) : null,
+      cors: { enabled: opts.cors !== false, origins: ["*"] },
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const handle = await startMockServer(mock, {
+      port: opts.port ? Number(opts.port) : void 0,
+      host: opts.host
+    });
+    process.stdout.write(
+      `${kleur.green("Mock server")} listening on ${kleur.cyan(`http://${opts.host}:${handle.port}`)} with ${parsed.endpoints.length} endpoints (type=${type}). Press Ctrl-C to stop.
+`
+    );
+    if (parsed.warnings.length) {
+      for (const w of parsed.warnings) {
+        process.stderr.write(`${kleur.yellow("warn")}: ${w}
+`);
+      }
+    }
+    installShutdown(handle);
+  });
+}
+function inferType(filePath, hint) {
+  if (hint && hint !== "auto") return hint;
+  const lower = filePath.toLowerCase();
+  if (lower.includes("postman")) return "postman";
+  if (lower.includes("insomnia")) return "insomnia";
+  return "openapi";
+}
+function inferFormat(filePath, hint) {
+  if (hint && hint !== "auto") return hint;
+  const lower = filePath.toLowerCase();
+  return lower.endsWith(".yaml") || lower.endsWith(".yml") ? "yaml" : "json";
+}
+function makeSource(type, format, raw) {
+  switch (type) {
+    case "openapi":
+      return { kind: "openapi", spec: raw, format };
+    case "postman":
+      return { kind: "postman", collection: raw };
+    case "insomnia":
+      return { kind: "insomnia", export: raw };
+  }
+}
+function installShutdown(handle) {
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    await handle.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+}
+
+// src/commands/mcp.ts
+import * as path3 from "path";
+import kleur2 from "kleur";
+import {
+  createMcpServer,
+  FileBackedWorkspaceProvider,
+  InProcessMockController
+} from "@apicircle/mcp-server";
+
+// src/util/loadWorkspace.ts
+import * as path2 from "path";
+import { promises as fs2 } from "fs";
+import { loadFromFile, saveToFile } from "@apicircle/core/workspace/file-backed";
+import { FONT_SIZE_PERCENT_DEFAULT, generateId as generateId2 } from "@apicircle/shared";
+async function ensureWorkspace(dir) {
+  const resolved = path2.resolve(dir);
+  await fs2.mkdir(resolved, { recursive: true });
+  const existing = await loadFromFile(resolved, { allowMissing: true });
+  if (existing) return existing;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const workspaceId = generateId2();
+  const fresh = {
+    synced: {
+      schemaVersion: 1,
+      workspaceId,
+      collections: {
+        tree: { id: generateId2(), type: "root", children: [] },
+        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: null,
+        sidebarExpandedSections: [],
+        themeId: "studio-dark",
+        fontId: "system-mono",
+        fontSizePercent: FONT_SIZE_PERCENT_DEFAULT
+      },
+      settings: { validateOnSend: true, monacoConsumesWheel: false },
+      snapshots: { entries: [], maxBytes: 50 * 1024 * 1024 }
+    }
+  };
+  await saveToFile(resolved, fresh);
+  return fresh;
+}
+
+// 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());
+    try {
+      await ensureWorkspace(dir);
+    } catch (err) {
+      process.stderr.write(
+        `${kleur2.red("failed to initialise workspace")} at ${dir}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    }
+    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}
+`);
+    await host.connect();
+  });
+}
+
+// src/commands/import.ts
+import { promises as fs3 } 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 {
+  parseInsomniaToEndpoints,
+  parseOpenApiToEndpoints,
+  parsePostmanToEndpoints
+} from "@apicircle/mock-server-core";
+import { generateId as generateId3 } 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());
+    const raw = await readInput(input);
+    const state = await ensureWorkspace(dir);
+    let nextSynced = state.synced;
+    let nextLocal = state.local;
+    const created = [];
+    const append = (req) => {
+      const out = applyMutation(
+        { synced: nextSynced, local: nextLocal },
+        { kind: "request.create", request: req }
+      );
+      nextSynced = out.next.synced;
+      nextLocal = out.next.local;
+      created.push(req.id);
+    };
+    if (type === "curl") {
+      const { parseCurl } = await import("@apicircle/core");
+      const parsed = parseCurl(raw);
+      append(
+        blankRequest({
+          name: `cURL ${parsed.method} ${parsed.url}`.slice(0, 80),
+          method: parsed.method,
+          url: parsed.url,
+          headers: parsed.headers,
+          query: parsed.query,
+          body: parsed.body,
+          auth: parsed.auth
+        })
+      );
+    } else if (type === "openapi") {
+      const parsed = await parseOpenApiToEndpoints(raw, opts.format ?? "json");
+      for (const ep of parsed.endpoints) {
+        append(
+          blankRequest({
+            name: ep.example ?? `${ep.method} ${ep.pathPattern}`,
+            method: ep.method,
+            url: ep.pathPattern
+          })
+        );
+      }
+    } else if (type === "postman") {
+      const parsed = parsePostmanToEndpoints(raw);
+      for (const ep of parsed.endpoints) {
+        append(
+          blankRequest({
+            name: ep.example ?? `${ep.method} ${ep.pathPattern}`,
+            method: ep.method,
+            url: ep.pathPattern
+          })
+        );
+      }
+    } else if (type === "insomnia") {
+      const parsed = parseInsomniaToEndpoints(raw);
+      for (const ep of parsed.endpoints) {
+        append(
+          blankRequest({
+            name: ep.example ?? `${ep.method} ${ep.pathPattern}`,
+            method: ep.method,
+            url: ep.pathPattern
+          })
+        );
+      }
+    } else {
+      process.stderr.write(`${kleur3.red("error")}: unknown type '${String(type)}'
+`);
+      process.exit(2);
+    }
+    await saveToFile2(dir, { synced: nextSynced, local: nextLocal });
+    process.stdout.write(
+      `${kleur3.green("imported")} ${created.length} request${created.length === 1 ? "" : "s"} into ${dir}
+`
+    );
+  });
+}
+async function readInput(p) {
+  if (p === "-") {
+    return new Promise((resolve7, 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("error", reject);
+    });
+  }
+  return fs3.readFile(path4.resolve(p), "utf-8");
+}
+function blankRequest(partial) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    id: generateId3(),
+    folderId: null,
+    headers: [],
+    query: [],
+    body: { type: "none", content: "" },
+    auth: { type: "none" },
+    contextVars: [],
+    extractions: [],
+    assertions: [],
+    createdAt: now,
+    updatedAt: now,
+    ...partial
+  };
+}
+
+// src/commands/run.ts
+import * as os from "os";
+import * as path6 from "path";
+import kleur4 from "kleur";
+import {
+  ANONYMOUS_ACTOR,
+  PlanRunDeniedError,
+  resolvePlanRef,
+  runPlan
+} from "@apicircle/core";
+import { loadFromFile as loadFromFile2, saveToFile as saveToFile3 } from "@apicircle/core/workspace/file-backed";
+
+// src/util/secrets.ts
+import * as path5 from "path";
+import { promises as fs4 } from "fs";
+var DEFAULT_PREFIX = "APICIRCLE_SECRET_";
+async function buildSecretsFromCli(options = {}) {
+  const env = options.env ?? process.env;
+  const prefix = options.envPrefix ?? DEFAULT_PREFIX;
+  const byId = {};
+  if (options.secretsFile) {
+    const resolved = path5.resolve(options.secretsFile);
+    const raw = await fs4.readFile(resolved, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(
+        `--secrets ${options.secretsFile}: expected an object mapping secretKeyId \u2192 value`
+      );
+    }
+    for (const [id, value] of Object.entries(parsed)) {
+      if (typeof value !== "string") {
+        throw new Error(`--secrets ${options.secretsFile}: value for "${id}" must be a string`);
+      }
+      byId[id] = value;
+    }
+  }
+  for (const [name, value] of Object.entries(env)) {
+    if (!name.startsWith(prefix) || typeof value !== "string") continue;
+    const id = name.slice(prefix.length);
+    if (id) byId[id] = value;
+  }
+  return { byId };
+}
+
+// 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());
+    const reporter = opts.reporter ?? "text";
+    if (!isReporter(reporter)) {
+      fail(`unknown --reporter "${reporter}" (expected: ${REPORTERS.join(", ")})`);
+      return;
+    }
+    const state = await loadFromFile2(dir, { allowMissing: true });
+    if (!state) {
+      fail(`no workspace found at ${dir} (expected workspace.synced.json)`);
+      return;
+    }
+    const ref = resolvePlanRef(state.synced, planRef);
+    if (!ref.ok) {
+      fail(ref.error);
+      if (ref.available.length > 0) {
+        process.stderr.write(`Available plans: ${ref.available.join(", ")}
+`);
+      }
+      return;
+    }
+    if (opts.env && !state.synced.environments.items[opts.env]) {
+      const names = Object.keys(state.synced.environments.items);
+      fail(`no environment named "${opts.env}" in this workspace`);
+      if (names.length > 0) {
+        process.stderr.write(`Available environments: ${names.join(", ")}
+`);
+      }
+      return;
+    }
+    let secretsById;
+    try {
+      secretsById = (await buildSecretsFromCli({ secretsFile: opts.secrets })).byId;
+    } catch (err) {
+      fail(err instanceof Error ? err.message : String(err));
+      return;
+    }
+    const actor = resolveActor(state.local, opts.as);
+    const withAssertions = opts.assertions !== false;
+    const text = reporter === "text";
+    const controller = new AbortController();
+    const onSigint = () => controller.abort(new Error("aborted by SIGINT"));
+    process.on("SIGINT", onSigint);
+    if (text) process.stdout.write(formatHeader(ref.plan, actor, withAssertions, opts));
+    let result;
+    try {
+      result = await runPlan(state, ref.id, {
+        withAssertions,
+        bail: opts.bail === true,
+        env: opts.env,
+        secretsById,
+        actor,
+        signal: controller.signal,
+        authorize: checkRunPermission,
+        onStep: text ? (step) => process.stdout.write(formatStepLine(step)) : void 0
+      });
+    } catch (err) {
+      process.off("SIGINT", onSigint);
+      if (err instanceof PlanRunDeniedError) {
+        fail(err.message, 3, "denied");
+        return;
+      }
+      throw err;
+    }
+    process.off("SIGINT", onSigint);
+    const aborted = controller.signal.aborted;
+    const saved = opts.save !== false;
+    if (saved) await saveToFile3(dir, result.nextState);
+    if (reporter === "json") {
+      process.stdout.write(
+        JSON.stringify(
+          buildJsonReport(dir, ref.id, ref.plan, actor, result, saved, aborted),
+          null,
+          2
+        ) + "\n"
+      );
+    } else if (reporter === "junit") {
+      process.stdout.write(buildJunitReport(ref.plan, result));
+    } else {
+      process.stdout.write(formatSummary(result, saved, aborted));
+    }
+    process.exitCode = result.passed && !aborted ? 0 : 1;
+  });
+}
+function isReporter(value) {
+  return REPORTERS.includes(value);
+}
+function resolveActor(local, override) {
+  const explicit = override?.trim();
+  if (explicit) return { kind: "unknown", name: explicit };
+  const login = local.sessions.github.workspace?.accountLogin;
+  if (login) return { kind: "github", name: login };
+  try {
+    const username = os.userInfo().username;
+    if (username) return { kind: "os", name: username };
+  } catch {
+  }
+  return ANONYMOUS_ACTOR;
+}
+function checkRunPermission(_ctx) {
+}
+function formatHeader(plan, actor, withAssertions, opts) {
+  const enabled = plan.steps.filter((s) => s.enabled !== false).length;
+  const flags = [
+    withAssertions ? "assertions on" : "assertions off",
+    opts.bail ? "bail" : null,
+    opts.env ? `env=${opts.env}` : null
+  ].filter((f) => f !== null);
+  return `${kleur4.bold("Plan")} ${plan.name}  ${kleur4.dim(
+    `(${enabled}/${plan.steps.length} steps \xB7 ${flags.join(" \xB7 ")})`
+  )}
+${kleur4.dim("Run by")} ${actor.name} ${kleur4.dim(`(${actor.kind})`)}
+
+`;
+}
+function formatStepLine(step) {
+  const n = `${step.stepIndex + 1}.`.padEnd(3);
+  const method = (step.requestMethod || "\u2014").padEnd(7);
+  if (step.skipped) {
+    return `  ${kleur4.dim("\u2013")} ${kleur4.dim(n)} ${kleur4.dim(method)} ${kleur4.dim(
+      `${step.requestName}  skipped`
+    )}
+`;
+  }
+  const mark = step.passed ? kleur4.green("\u2713") : kleur4.red("\u2717");
+  const status = step.result?.status != null ? String(step.result.status) : "\u2014";
+  const duration = step.result ? `${step.result.durationMs}ms` : "";
+  const name = step.requestName.padEnd(28);
+  let line = `  ${mark} ${n} ${method} ${name} ${status.padEnd(4)} ${kleur4.dim(duration)}`;
+  if (step.assertionResults.length > 0) {
+    const passed = step.assertionResults.filter((a) => a.passed).length;
+    line += `  ${kleur4.dim(`${passed}/${step.assertionResults.length} assertions`)}`;
+  }
+  line += "\n";
+  if (step.error) {
+    line += `      ${kleur4.red(step.error)}
+`;
+  }
+  for (const a of step.assertionResults) {
+    if (!a.passed) line += `      ${kleur4.red("\u2717")} ${a.detail ?? `${a.kind} ${a.op}`}
+`;
+  }
+  if (step.missingVariables.length > 0) {
+    line += `      ${kleur4.yellow("\u26A0")} unresolved: ${step.missingVariables.map((v) => `{{${v}}}`).join(", ")}
+`;
+  }
+  return line;
+}
+function tally(result) {
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  for (const s of result.steps) {
+    if (s.skipped) skipped++;
+    else if (s.passed) passed++;
+    else failed++;
+  }
+  return { passed, failed, skipped };
+}
+function formatSummary(result, saved, aborted) {
+  if (result.steps.length === 0) {
+    return `
+${kleur4.yellow("Plan has no steps.")}
+`;
+  }
+  const { passed, failed, skipped } = tally(result);
+  const parts = [
+    kleur4.green(`${passed} passed`),
+    failed > 0 ? kleur4.red(`${failed} failed`) : kleur4.dim(`${failed} failed`),
+    kleur4.dim(`${skipped} skipped`)
+  ];
+  const verdict = result.passed && !aborted ? kleur4.green("PASS") : kleur4.red("FAIL");
+  let out = `
+${verdict}  ${parts.join(kleur4.dim(" \xB7 "))}  ${kleur4.dim(
+    `\xB7 ${result.planRun.durationMs}ms`
+  )}
+`;
+  if (aborted) out += `${kleur4.yellow("Run aborted before every step finished.")}
+`;
+  out += saved ? kleur4.dim("Plan run saved to workspace history.\n") : kleur4.dim("Plan run not saved (--no-save).\n");
+  return out;
+}
+function buildJsonReport(workspace, planId, plan, actor, result, saved, aborted) {
+  return {
+    workspace,
+    plan: { id: planId, name: plan.name },
+    actor,
+    withAssertions: result.planRun.withAssertions,
+    passed: result.passed && !aborted,
+    aborted,
+    durationMs: result.planRun.durationMs,
+    saved,
+    counts: tally(result),
+    steps: result.steps.map((s) => ({
+      step: s.stepIndex + 1,
+      request: s.requestName,
+      method: s.requestMethod,
+      skipped: s.skipped,
+      status: s.result?.status ?? null,
+      ok: s.result?.ok ?? false,
+      durationMs: s.result?.durationMs ?? 0,
+      passed: s.passed,
+      error: s.error ?? null,
+      missingVariables: s.missingVariables,
+      assertions: s.assertionResults.map((a) => ({
+        kind: a.kind,
+        op: a.op,
+        target: a.target,
+        expected: a.expected,
+        passed: a.passed,
+        detail: a.detail
+      }))
+    }))
+  };
+}
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function buildJunitReport(plan, result) {
+  const { failed, skipped } = tally(result);
+  const total = result.steps.length;
+  const suite = xmlEscape(plan.name);
+  const suiteTime = (result.planRun.durationMs / 1e3).toFixed(3);
+  const cases = result.steps.map((s) => {
+    const name = xmlEscape(`${s.stepIndex + 1}. ${s.requestName}`);
+    const time = ((s.result?.durationMs ?? 0) / 1e3).toFixed(3);
+    const open = `    <testcase name="${name}" classname="${suite}" time="${time}"`;
+    if (s.skipped) return `${open}>
+      <skipped/>
+    </testcase>`;
+    if (s.passed) return `${open}/>`;
+    const reasons = [];
+    if (s.error) reasons.push(s.error);
+    for (const a of s.assertionResults) {
+      if (!a.passed) reasons.push(a.detail ?? `assertion ${a.kind} ${a.op} failed`);
+    }
+    if (s.result && !s.result.ok && s.result.status != null) {
+      reasons.push(`HTTP ${s.result.status}`);
+    }
+    const detail = xmlEscape(reasons.join("\n") || "step failed");
+    const summary = detail.split("\n")[0];
+    return `${open}>
+      <failure message="${summary}">${detail}</failure>
+    </testcase>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="${suite}" tests="${total}" failures="${failed}" skipped="${skipped}" time="${suiteTime}">
+  <testsuite name="${suite}" tests="${total}" failures="${failed}" skipped="${skipped}" time="${suiteTime}">
+${cases.join("\n")}
+  </testsuite>
+</testsuites>
+`;
+}
+function fail(message, code = 2, kind = "error") {
+  process.stderr.write(`${kleur4.red(kind)}: ${message}
+`);
+  process.exitCode = code;
+}
+
+// src/index.ts
+function buildProgram() {
+  const program = new Command();
+  program.name("apicircle").description("Command-line companion to APICircle Studio.").version("1.0.0");
+  registerMockCommand(program);
+  registerMcpCommand(program);
+  registerImportCommand(program);
+  registerRunCommand(program);
+  return program;
+}
+async function runCli(argv = process.argv) {
+  await buildProgram().parseAsync(argv);
+}
+var entry = process.argv[1] ?? "";
+if (entry.endsWith("apicircle") || entry.endsWith("index.cjs") || entry.endsWith("index.ts")) {
+  void runCli();
+}
+export {
+  buildProgram,
+  runCli
+};
+//# sourceMappingURL=index.js.map