@stigmer/cli 3.13.0 → 3.14.0

package/src/commands/config/backend.test.ts

@@ -0,0 +1,122 @@
+// Command-level contract for the named-backend surface (O3):
+// add/use/list/remove over the real config file (HOME redirected to a
+// throwaway dir), the reserved-name refusals, and the remove-current guard.
+// The model-level semantics (migration, resolution, credentials) are pinned
+// in config.test.ts / resolve.test.ts — this file pins the command layer's
+// own rules.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { load } from "../../config/index.js";
+import { classify, ExitCode } from "../../errors/index.js";
+import { buildProgram } from "../../program.js";
+
+let home: string;
+let originalHome: string | undefined;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  home = mkdtempSync(join(tmpdir(), "stigmer-backend-cmd-"));
+  process.env.HOME = home;
+});
+
+afterEach(() => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  rmSync(home, { recursive: true, force: true });
+});
+
+interface RunOutcome {
+  readonly exitCode: number;
+  readonly message: string;
+}
+
+async function run(...args: string[]): Promise<RunOutcome> {
+  const program = buildProgram();
+  program.exitOverride();
+  const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+  const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+  try {
+    await program.parseAsync(["node", "stigmer", "config", "backend", ...args]);
+    return { exitCode: ExitCode.Success, message: "" };
+  } catch (err) {
+    return {
+      exitCode: classify(err)?.exitCode ?? -1,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+  }
+}
+
+describe("config backend add/use/list/remove", () => {
+  it("add persists a selfhost entry with its endpoint and api key", async () => {
+    const outcome = await run(
+      "add",
+      "staging",
+      "--endpoint",
+      "stigmer.example.com:7234",
+      "--api-key",
+      "stk_x",
+    );
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    const config = load();
+    expect(config.backends?.["staging"]).toEqual({
+      type: "selfhost",
+      endpoint: "stigmer.example.com:7234",
+      api_key: "stk_x",
+    });
+    // Adding never switches — the user opts in with `use`.
+    expect(config.current_backend).toBe("local");
+  });
+
+  it("add updates an existing entry without dropping its credential", async () => {
+    await run("add", "staging", "--endpoint", "old:7234", "--api-key", "stk_x");
+    await run("add", "staging", "--endpoint", "new:7234");
+    const entry = load().backends?.["staging"];
+    expect(entry?.endpoint).toBe("new:7234");
+    expect(entry?.api_key).toBe("stk_x");
+  });
+
+  it("use switches the current backend; unknown names refuse", async () => {
+    await run("add", "staging", "--endpoint", "host:7234");
+    expect((await run("use", "staging")).exitCode).toBe(ExitCode.Success);
+    expect(load().current_backend).toBe("staging");
+
+    const unknown = await run("use", "nope");
+    expect(unknown.exitCode).toBe(ExitCode.Usage);
+    expect(unknown.message).toContain('unknown backend "nope"');
+  });
+
+  it("the local name is reserved: add and remove refuse it", async () => {
+    const add = await run("add", "local", "--endpoint", "host:7234");
+    expect(add.exitCode).toBe(ExitCode.Usage);
+    const remove = await run("remove", "local");
+    expect(remove.exitCode).toBe(ExitCode.Usage);
+  });
+
+  it("remove refuses the current backend and deletes others", async () => {
+    await run("add", "staging", "--endpoint", "host:7234");
+    await run("use", "staging");
+
+    const current = await run("remove", "staging");
+    expect(current.exitCode).toBe(ExitCode.Usage);
+    expect(current.message).toContain("current backend");
+
+    await run("use", "local");
+    expect((await run("remove", "staging")).exitCode).toBe(ExitCode.Success);
+    expect(load().backends?.["staging"]).toBeUndefined();
+  });
+
+  it("set cloud seeds and selects the reserved cloud entry (legacy sugar)", async () => {
+    expect((await run("set", "cloud")).exitCode).toBe(ExitCode.Success);
+    const config = load();
+    expect(config.current_backend).toBe("cloud");
+    expect(config.backends?.["cloud"]?.endpoint).toBe("api.stigmer.ai:443");
+    expect((await run("set", "local")).exitCode).toBe(ExitCode.Success);
+    expect(load().current_backend).toBe("local");
+  });
+});

package/src/commands/config/backend.ts

@@ -1,13 +1,36 @@
-// `stigmer config backend status|set` — inspect and switch the active backend.
+// `stigmer config backend status|set|add|use|list|remove` — the named-backend
+// surface (O3, 20260827.06; the kubectl-context model). `status` and
+// `set <local|cloud>` predate named backends and stay as the simple view:
+// set is sugar for `use` over the two reserved names.
 
 import type { Command } from "commander";
-import { type Config, isCloudMode, load, resolveEndpoint, save } from "../../config/index.js";
+import {
+  CLOUD_BACKEND_NAME,
+  type Config,
+  LOCAL_BACKEND_NAME,
+  type NamedBackendType,
+  activeBackend,
+  activeBackendName,
+  load,
+  resolveEndpoint,
+  save,
+} from "../../config/index.js";
 import { UsageError } from "../../errors/index.js";
-import { CommandResult, type OutputFlags, renderResult } from "../../output/index.js";
+import {
+  CommandResult,
+  type OutputFlags,
+  renderResult,
+} from "../../output/index.js";
 import { addResultFlags, resultFormat } from "../shared.js";
 
 const DEFAULT_CLOUD_ENDPOINT = "api.stigmer.ai:443";
 
+interface AddOptions extends OutputFlags {
+  endpoint?: string;
+  type?: string;
+  apiKey?: string;
+}
+
 export function addBackendCommands(backend: Command): void {
   const status = backend
     .command("status")
@@ -19,40 +42,198 @@ export function addBackendCommands(backend: Command): void {
 
   const set = backend
     .command("set <type>")
-    .description("set the backend type (local or cloud)")
+    .description("switch between the reserved local and cloud backends")
     .action((type: string, options: OutputFlags) => {
       renderResult(applySet(type), resultFormat(options));
     });
   addResultFlags(set);
+
+  const add = backend
+    .command("add <name>")
+    .description("add or update a named backend (self-hosted by default)")
+    .requiredOption(
+      "--endpoint <host:port>",
+      "the server address, e.g. stigmer.example.com:443",
+    )
+    .option("--type <type>", "backend type: selfhost or cloud", "selfhost")
+    .option(
+      "--api-key <key>",
+      "API token for a self-hosted backend (stigmer apikey create)",
+    )
+    .action((name: string, options: AddOptions) => {
+      renderResult(applyAdd(name, options), resultFormat(options));
+    });
+  addResultFlags(add);
+
+  const use = backend
+    .command("use <name>")
+    .description("switch the active backend")
+    .action((name: string, options: OutputFlags) => {
+      renderResult(applyUse(name), resultFormat(options));
+    });
+  addResultFlags(use);
+
+  const list = backend
+    .command("list")
+    .description("list configured backends")
+    .action((options: OutputFlags) => {
+      renderResult(buildList(load()), resultFormat(options));
+    });
+  addResultFlags(list);
+
+  const remove = backend
+    .command("remove <name>")
+    .description("remove a named backend")
+    .action((name: string, options: OutputFlags) => {
+      renderResult(applyRemove(name), resultFormat(options));
+    });
+  addResultFlags(remove);
 }
 
 function buildStatus(config: Config): CommandResult {
+  const { name, entry } = activeBackend(config);
   const result = CommandResult.success("Backend configuration");
-  const section = result.addSection("").field("Type", config.backend.type).field("Endpoint", resolveEndpoint(config));
-  if (isCloudMode(config)) {
-    section.field("Auth", config.backend.cloud?.token ? "Logged in" : "Not logged in");
+  const section = result
+    .addSection("")
+    .field("Backend", name)
+    .field("Type", entry?.type ?? "local")
+    .field("Endpoint", resolveEndpoint(config));
+  if (entry?.type === "cloud") {
+    section.field("Auth", entry.token ? "Logged in" : "Not logged in");
+  }
+  if (entry?.type === "selfhost") {
+    section.field(
+      "Auth",
+      entry.api_key
+        ? "API key stored"
+        : "No credential (unauthenticated server, or STIGMER_API_KEY)",
+    );
   }
   return result;
 }
 
 function applySet(type: string): CommandResult {
   if (type !== "local" && type !== "cloud") {
-    throw new UsageError(`invalid backend type "${type}" (expected: local, cloud)`);
+    throw new UsageError(
+      `invalid backend type "${type}" (expected: local, cloud — named backends switch with 'use')`,
+    );
   }
 
   const config = load();
-  config.backend.type = type;
-
   if (type === "cloud") {
-    if (config.backend.cloud === undefined) {
-      config.backend.cloud = { endpoint: DEFAULT_CLOUD_ENDPOINT };
-    }
+    const backends = (config.backends ??= {});
+    backends[CLOUD_BACKEND_NAME] ??= {
+      type: "cloud",
+      endpoint: DEFAULT_CLOUD_ENDPOINT,
+    };
+    config.current_backend = CLOUD_BACKEND_NAME;
     save(config);
     return CommandResult.success("Backend set to cloud")
       .hint("Please authenticate:")
       .hint("  stigmer auth login");
   }
 
+  config.current_backend = LOCAL_BACKEND_NAME;
+  save(config);
+  return CommandResult.success("Backend set to local").hint(
+    "Make sure the Stigmer server is running.",
+  );
+}
+
+function applyAdd(name: string, options: AddOptions): CommandResult {
+  if (name === LOCAL_BACKEND_NAME) {
+    throw new UsageError(
+      `"${LOCAL_BACKEND_NAME}" is the managed local daemon — it cannot be redefined`,
+    );
+  }
+  const type = options.type ?? "selfhost";
+  if (type !== "selfhost" && type !== "cloud") {
+    throw new UsageError(
+      `invalid backend type "${type}" (expected: selfhost, cloud)`,
+    );
+  }
+  const endpoint = options.endpoint ?? "";
+  if (endpoint === "") {
+    throw new UsageError("--endpoint is required");
+  }
+
+  const config = load();
+  const backends = (config.backends ??= {});
+  const existing = backends[name];
+  backends[name] = {
+    ...existing,
+    type: type as NamedBackendType,
+    endpoint,
+    ...(options.apiKey !== undefined ? { api_key: options.apiKey } : {}),
+  };
+  save(config);
+
+  const result = CommandResult.success(
+    `Backend "${name}" ${existing !== undefined ? "updated" : "added"} (${type}, ${endpoint})`,
+  ).hint(`Switch to it:  stigmer config backend use ${name}`);
+  if (type === "selfhost" && backends[name].api_key === undefined) {
+    result.hint(
+      "No API key stored. For an authenticated server, mint one on that backend:",
+    );
+    result.hint("  stigmer apikey create --name cli");
+  }
+  return result;
+}
+
+function applyUse(name: string): CommandResult {
+  const config = load();
+  if (name !== LOCAL_BACKEND_NAME && config.backends?.[name] === undefined) {
+    throw new UsageError(
+      `unknown backend "${name}" (known: ${knownBackendNames(config).join(", ")})`,
+    );
+  }
+  config.current_backend = name;
+  save(config);
+  return CommandResult.success(`Switched to backend "${name}"`);
+}
+
+function buildList(config: Config): CommandResult {
+  const current = activeBackendName(config);
+  const result = CommandResult.success("Configured backends");
+  for (const name of knownBackendNames(config)) {
+    const entry = config.backends?.[name];
+    const marker = name === current ? " (current)" : "";
+    const section = result.addSection(`${name}${marker}`);
+    section.field("Type", entry?.type ?? "local");
+    section.field(
+      "Endpoint",
+      entry?.endpoint ??
+        (entry?.type === "cloud" ? DEFAULT_CLOUD_ENDPOINT : "localhost:7234"),
+    );
+    if (entry?.type === "cloud") {
+      section.field("Auth", entry.token ? "Logged in" : "Not logged in");
+    } else if (entry?.type === "selfhost") {
+      section.field("Auth", entry.api_key ? "API key stored" : "None");
+    }
+  }
+  return result;
+}
+
+function applyRemove(name: string): CommandResult {
+  if (name === LOCAL_BACKEND_NAME) {
+    throw new UsageError(
+      `"${LOCAL_BACKEND_NAME}" is the managed local daemon — it cannot be removed`,
+    );
+  }
+  const config = load();
+  if (config.backends?.[name] === undefined) {
+    throw new UsageError(`unknown backend "${name}"`);
+  }
+  if (activeBackendName(config) === name) {
+    throw new UsageError(
+      `backend "${name}" is the current backend — switch first: stigmer config backend use ${LOCAL_BACKEND_NAME}`,
+    );
+  }
+  delete config.backends[name];
   save(config);
-  return CommandResult.success("Backend set to local").hint("Make sure the Stigmer server is running.");
+  return CommandResult.success(`Removed backend "${name}"`);
+}
+
+function knownBackendNames(config: Config): string[] {
+  return [LOCAL_BACKEND_NAME, ...Object.keys(config.backends ?? {}).sort()];
 }

package/src/commands/connect.test.ts

@@ -31,7 +31,11 @@ vi.mock("../config/index.js", async (importOriginal) => {
 
 /** An authenticated cloud config with no org selected — the guard's target shape. */
 function cloudConfigWithoutOrg(): Config {
-  return { backend: { type: "cloud", cloud: { token: "test-token" } } };
+  return {
+    backend: { type: "cloud" },
+    backends: { cloud: { type: "cloud", token: "test-token" } },
+    current_backend: "cloud",
+  };
 }
 
 interface RunOutcome {
@@ -43,16 +47,30 @@ interface RunOutcome {
 // suppressed, returning the thrown error's classified exit code and message (or
 // a success sentinel). `--standalone` is a program-global flag, so it must
 // precede the subcommand (commander's enablePositionalOptions).
-async function runConnect(ref: string, ...flags: string[]): Promise<RunOutcome> {
+async function runConnect(
+  ref: string,
+  ...flags: string[]
+): Promise<RunOutcome> {
   const program = buildProgram();
   program.exitOverride();
   const outSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
   const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
   try {
-    await program.parseAsync(["node", "stigmer", "--standalone", "connect", "mcp-server", ref, ...flags]);
+    await program.parseAsync([
+      "node",
+      "stigmer",
+      "--standalone",
+      "connect",
+      "mcp-server",
+      ref,
+      ...flags,
+    ]);
     return { exitCode: ExitCode.Success, message: "" };
   } catch (err) {
-    return { exitCode: classify(err)?.exitCode ?? -1, message: err instanceof Error ? err.message : String(err) };
+    return {
+      exitCode: classify(err)?.exitCode ?? -1,
+      message: err instanceof Error ? err.message : String(err),
+    };
   } finally {
     outSpy.mockRestore();
     errSpy.mockRestore();

package/src/commands/connect.ts

@@ -7,7 +7,12 @@
 // fast (DD-001).
 
 import type { Command } from "commander";
-import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import {
+  activeBackend,
+  ensureAuthenticated,
+  resolveConsoleURL,
+  resolveOrganization,
+} from "../config/index.js";
 import { UsageError } from "../errors/index.js";
 import { shouldColorize } from "../output/style.js";
 import { globalOrg } from "./shared.js";
@@ -21,7 +26,9 @@ interface ConnectFlags {
 const DEFAULT_TIMEOUT_SECONDS = 30;
 
 export function registerConnect(program: Command): void {
-  const connect = program.command("connect").description("connect to external services and discover capabilities");
+  const connect = program
+    .command("connect")
+    .description("connect to external services and discover capabilities");
 
   connect
     .command("mcp-server <slug-or-id>")
@@ -32,17 +39,26 @@ export function registerConnect(program: Command): void {
         "bounds the server-side connect only when set explicitly)",
       String(DEFAULT_TIMEOUT_SECONDS),
     )
-    .option("--dry-run", "discover and display results without pushing to the backend")
+    .option(
+      "--dry-run",
+      "discover and display results without pushing to the backend",
+    )
     .option(
       "--env <KEY=VALUE>",
       "environment variable for the MCP server (repeatable)",
       (value: string, previous: string[]) => [...previous, value],
       [],
     )
-    .action((reference: string, options: ConnectFlags, command: Command) => runConnect(reference, options, command));
+    .action((reference: string, options: ConnectFlags, command: Command) =>
+      runConnect(reference, options, command),
+    );
 }
 
-async function runConnect(reference: string, options: ConnectFlags, command: Command): Promise<void> {
+async function runConnect(
+  reference: string,
+  options: ConnectFlags,
+  command: Command,
+): Promise<void> {
   const timeoutMs = parseTimeout(options.timeout);
   // The 30s default exists for --dry-run's local discovery. A real connect
   // legitimately takes minutes (server-side sandbox boot + discovery + tool
@@ -50,11 +66,12 @@ async function runConnect(reference: string, options: ConnectFlags, command: Com
   // connects — the wait is bounded only when the user set --timeout
   // explicitly (issue #239: the flag used to be silently ignored here).
   const timeoutIsExplicit = command.getOptionValueSource("timeout") === "cli";
-  const [{ connectBackend }, { connectMcpServer }, { renderConnectResult }] = await Promise.all([
-    import("../backend.js"),
-    import("../resources/connect/connect.js"),
-    import("../resources/connect/display.js"),
-  ]);
+  const [{ connectBackend }, { connectMcpServer }, { renderConnectResult }] =
+    await Promise.all([
+      import("../backend.js"),
+      import("../resources/connect/connect.js"),
+      import("../resources/connect/display.js"),
+    ]);
 
   const client = connectBackend();
   ensureAuthenticated(client.config);
@@ -81,12 +98,17 @@ async function runConnect(reference: string, options: ConnectFlags, command: Com
     pushTimeoutMs: timeoutIsExplicit ? timeoutMs : undefined,
     dryRun: options.dryRun === true,
     envOverrides: options.env,
-    backendType: client.config.backend.type,
+    consoleURL: resolveConsoleURL(client.config),
+    probeLocalConsole: activeBackend(client.config).entry === undefined,
     interactive: process.stderr.isTTY === true,
   });
 
   const colorize = shouldColorize(process.stdout);
-  renderConnectResult(result, (line) => process.stdout.write(`${line}\n`), colorize);
+  renderConnectResult(
+    result,
+    (line) => process.stdout.write(`${line}\n`),
+    colorize,
+  );
 }
 
 // Parse --timeout seconds into milliseconds. Mirrors Go's DurationVar default
@@ -95,7 +117,9 @@ function parseTimeout(raw: string | undefined): number {
   if (raw === undefined || raw === "") return DEFAULT_TIMEOUT_SECONDS * 1000;
   const seconds = Number(raw);
   if (!Number.isFinite(seconds) || seconds < 0) {
-    throw new UsageError(`invalid --timeout '${raw}': expected a number of seconds`);
+    throw new UsageError(
+      `invalid --timeout '${raw}': expected a number of seconds`,
+    );
   }
   return Math.round(seconds * 1000);
 }

package/src/commands/share.ts

@@ -8,7 +8,12 @@
 // lazy-imported so `--help` stays fast (DD-001).
 
 import type { Command } from "commander";
-import { ensureAuthenticated, resolveConsoleURL, resolveOrganization } from "../config/index.js";
+import {
+  activeBackend,
+  ensureAuthenticated,
+  resolveConsoleURL,
+  resolveOrganization,
+} from "../config/index.js";
 import { UsageError } from "../errors/index.js";
 import type { OutputFlags } from "../output/index.js";
 import type { ShareAudience } from "../resources/share.js";
@@ -22,11 +27,15 @@ interface ShareAgentFlags extends OutputFlags {
 }
 
 export function registerShare(program: Command): void {
-  const share = program.command("share").description("share resources via a hosted link");
+  const share = program
+    .command("share")
+    .description("share resources via a hosted link");
 
   const agent = share
     .command("agent <ref>")
-    .description("enable sharing for an agent and print its chat link and embed snippet")
+    .description(
+      "enable sharing for an agent and print its chat link and embed snippet",
+    )
     .option("--off", "disable sharing (the link stops working immediately)")
     .option(
       "--audience <audience>",
@@ -37,7 +46,9 @@ export function registerShare(program: Command): void {
       "generate a new share link and kill the current one immediately (public audience)",
     )
     .option("--open", "open the chat link in your browser")
-    .action((ref: string, options: ShareAgentFlags, command: Command) => runShareAgent(ref, options, command));
+    .action((ref: string, options: ShareAgentFlags, command: Command) =>
+      runShareAgent(ref, options, command),
+    );
   addResultFlags(agent);
 }
 
@@ -45,24 +56,30 @@ export function registerShare(program: Command): void {
 function parseAudience(value: string | undefined): ShareAudience | undefined {
   if (value === undefined) return undefined;
   if (value === "public" || value === "org") return value;
-  throw new UsageError(`invalid --audience '${value}'\n\nExpected 'public' or 'org'.`);
+  throw new UsageError(
+    `invalid --audience '${value}'\n\nExpected 'public' or 'org'.`,
+  );
 }
 
-async function runShareAgent(ref: string, options: ShareAgentFlags, command: Command): Promise<void> {
+async function runShareAgent(
+  ref: string,
+  options: ShareAgentFlags,
+  command: Command,
+): Promise<void> {
   const format = resultFormat(options);
 
-  const [{ connectBackend }, { shareAgent }, { renderResult }] = await Promise.all([
-    import("../backend.js"),
-    import("../resources/share.js"),
-    import("../output/command-result.js"),
-  ]);
+  const [{ connectBackend }, { shareAgent }, { renderResult }] =
+    await Promise.all([
+      import("../backend.js"),
+      import("../resources/share.js"),
+      import("../output/command-result.js"),
+    ]);
 
   const client = connectBackend();
   ensureAuthenticated(client.config);
   const org = resolveOrganization(client.config, globalOrg(command));
 
-  const backendType = client.config.backend.type;
-  const appOrigin = resolveConsoleURL(backendType);
+  const appOrigin = resolveConsoleURL(client.config);
   const enabled = options.off !== true;
   const audience = parseAudience(options.audience);
   const resetLink = options.resetLink === true;
@@ -79,20 +96,23 @@ async function runShareAgent(ref: string, options: ShareAgentFlags, command: Com
     ...(audience !== undefined ? { audience } : {}),
     resetLink,
     appOrigin,
-    isLocal: backendType === "local",
+    isLocal: activeBackend(client.config).entry === undefined,
   });
   renderResult(result, format);
 
   if (options.open === true && enabled) {
     // Best-effort: the link is already rendered above, so a launch failure
     // only needs a nudge, never an error exit (mirrors auth login).
-    const url = result.sections.find((s) => s.title.endsWith("chat link"))?.items[0];
+    const url = result.sections.find((s) => s.title.endsWith("chat link"))
+      ?.items[0];
     if (url !== undefined) {
       try {
         const { default: open } = await import("open");
         await open(url);
       } catch {
-        process.stderr.write("Could not open the browser automatically. Please open the link above.\n");
+        process.stderr.write(
+          "Could not open the browser automatically. Please open the link above.\n",
+        );
       }
     }
   }