@stigmer/cli 3.12.9 → 3.14.0-dev.20260910084630

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",
+        );
       }
     }
   }

package/src/commands/up.ts

@@ -6,9 +6,11 @@
 // outcome. The launcher (and the heavy resolvers it pulls in) load lazily so
 // `--help` stays fast (DD-001).
 
+import { homedir } from "node:os";
+import { join } from "node:path";
 import type { Command } from "commander";
 import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
-import { SERVER_PORT } from "../local/constants.js";
+import { HEALTH_STATE_FILE, SERVER_PORT } from "../local/constants.js";
 import { addResultFlags, resultFormat } from "./shared.js";
 
 interface UpFlags extends OutputFlags {
@@ -16,15 +18,17 @@ interface UpFlags extends OutputFlags {
   web?: boolean; // false when --no-web is passed
 }
 
+// The server serves the web console from its unified port (DD-012); the
+// flag suppresses probing/reporting it, not the serving itself (one
+// process, one origin — there is no separate console to not-start).
+const NO_WEB_HELP = "don't report the web console URL";
+
 export function registerUp(program: Command): void {
   const up = program
     .command("up")
     .description("start the local Stigmer stack (server, runner, Temporal)")
     .option("--server-only", "start only the control plane (no runners)")
-    // Accepted for compatibility with the Go CLI; this CLI does not bundle a
-    // local web console, so the stack is headless either way (use the cloud
-    // console at app.stigmer.ai for a UI).
-    .option("--no-web", "no-op: this CLI does not serve a local web console")
+    .option("--no-web", NO_WEB_HELP)
     .action((options: UpFlags) =>
       runUp({ serverOnly: options.serverOnly === true, noWeb: options.web === false }, options),
     );
@@ -33,7 +37,7 @@ export function registerUp(program: Command): void {
   const server = up
     .command("server")
     .description("start only the control plane (no runners)")
-    .option("--no-web", "no-op: this CLI does not serve a local web console")
+    .option("--no-web", NO_WEB_HELP)
     .action((options: UpFlags) => runUp({ serverOnly: true, noWeb: options.web === false }, options));
   addResultFlags(server);
 }
@@ -46,6 +50,20 @@ async function runUp(opts: { serverOnly: boolean; noWeb: boolean }, flags: Outpu
   const result = CommandResult.success(opts.serverOnly ? "Stigmer control plane is up" : "Stigmer local stack is up");
   const section = result.addSection("Endpoints");
   section.field("server", `http://localhost:${SERVER_PORT}`);
+  if (await consoleReported()) {
+    // Same origin as the API: the server serves the console (DD-012). Only
+    // printed when the daemon's probe found a bundled export — a dev-tree
+    // server without one must not advertise a dead URL.
+    section.field("console", `http://localhost:${SERVER_PORT}`);
+  }
   result.hint("Check status with: stigmer status").hint("Stop it with:    stigmer down");
   renderResult(result, resultFormat(flags));
 }
+
+/** Whether the daemon recorded the web console as running (its own probe). */
+async function consoleReported(): Promise<boolean> {
+  const { dataDir } = await import("../local/paths.js");
+  const { loadHealthState } = await import("../local/state/health-state.js");
+  const health = loadHealthState(join(dataDir(homedir()), HEALTH_STATE_FILE));
+  return health?.components["web-console"]?.state === "running";
+}

package/src/config/config.test.ts

@@ -28,16 +28,37 @@ describe("load", () => {
     expect(load(path)).toEqual(getDefault());
   });
 
-  it("parses a cloud config", () => {
+  it("migrates a legacy cloud config into the named model on load", () => {
     const path = tempConfigPath();
     writeFileSync(
       path,
       "backend:\n  type: cloud\n  cloud:\n    endpoint: api.stigmer.ai:443\n    org_id: acme\ncontext:\n  organization: acme\n",
     );
     const config = load(path);
-    expect(config.backend.type).toBe("cloud");
-    expect(config.backend.cloud?.org_id).toBe("acme");
+    // The legacy slot becomes the reserved "cloud" entry; the legacy type
+    // selects it as current. The slot itself is not carried forward.
+    expect(config.current_backend).toBe("cloud");
+    expect(config.backends?.["cloud"]).toEqual({
+      type: "cloud",
+      endpoint: "api.stigmer.ai:443",
+      org_id: "acme",
+    });
+    expect(config.backend.cloud).toBeUndefined();
     expect(config.context?.organization).toBe("acme");
+    expect(isCloudMode(config)).toBe(true);
+  });
+
+  it("parses a named-model config with selfhost entries", () => {
+    const path = tempConfigPath();
+    writeFileSync(
+      path,
+      "backend:\n  type: cloud\nbackends:\n  staging:\n    type: selfhost\n    endpoint: stigmer.example.com:7234\n    api_key: stk_x\ncurrent_backend: staging\n",
+    );
+    const config = load(path);
+    expect(config.current_backend).toBe("staging");
+    expect(config.backends?.["staging"]?.type).toBe("selfhost");
+    expect(config.backends?.["staging"]?.api_key).toBe("stk_x");
+    expect(isCloudMode(config)).toBe(false);
   });
 });
 
@@ -45,17 +66,52 @@ describe("save", () => {
   it("round-trips a config and writes a 0600 file with the doc header", () => {
     const path = tempConfigPath();
     const config = getDefault();
-    config.backend.type = "cloud";
-    config.backend.cloud = { endpoint: "api.stigmer.ai:443", token: "t", org_id: "acme" };
+    (config.backends ??= {})["cloud"] = {
+      type: "cloud",
+      endpoint: "api.stigmer.ai:443",
+      token: "t",
+      org_id: "acme",
+    };
+    config.current_backend = "cloud";
     save(config, path);
 
     const text = readFileSync(path, "utf8");
     expect(text).toContain("# Stigmer CLI Configuration");
-    expect(load(path)).toEqual(config);
+    const reloaded = load(path);
+    expect(reloaded.backends).toEqual(config.backends);
+    expect(reloaded.current_backend).toBe("cloud");
+    // The legacy mirror is written for older readers.
+    expect(reloaded.backend.type).toBe("cloud");
 
     rmSync(path);
   });
 
+  it("writes a legacy-loaded cloud config in the named shape (the one-time migration)", () => {
+    const path = tempConfigPath();
+    writeFileSync(
+      path,
+      "backend:\n  type: cloud\n  cloud:\n    endpoint: api.stigmer.ai:443\n    token: t\n",
+    );
+    save(load(path), path);
+
+    const text = readFileSync(path, "utf8");
+    expect(text).toContain("backends:");
+    expect(text).toContain("current_backend: cloud");
+    // The legacy slot is gone; its content lives in backends.cloud.
+    expect(text).not.toContain("  cloud:\n    endpoint");
+    const reloaded = load(path);
+    expect(reloaded.backends?.["cloud"]?.token).toBe("t");
+  });
+
+  it("keeps a pristine local config byte-stable (no named-model keys appear)", () => {
+    const path = tempConfigPath();
+    save(getDefault(), path);
+    const text = readFileSync(path, "utf8");
+    expect(text).not.toContain("backends:");
+    expect(text).not.toContain("current_backend:");
+    expect(text).toContain("type: local");
+  });
+
   it("preserves the opaque local backend section across a load/save round-trip", () => {
     const path = tempConfigPath();
     writeFileSync(

package/src/config/config.ts

@@ -1,41 +1,81 @@
 // CLI configuration model and persistence (~/.stigmer/config.yaml).
 //
-// Parity + coexistence: the file format matches the Go CLI exactly (snake_case
-// keys, 0600 perms, doc-link header) so a single config works whether invoked
-// through the Go or TS CLI during the migration. Crucially, the local-backend
-// section (daemon/LLM/Temporal settings owned by later waves and the Go CLI) is
-// carried through opaquely on save, so the TS CLI never drops fields it does
-// not yet model.
+// Named backends (O3, 20260827.06 — the parent program's recorded revisit:
+// "a named backend without a credential story is half a feature"): the
+// `backends` map + `current_backend` are the kubectl-context model — each
+// entry carries its own endpoint AND its own credentials, so switching
+// between Stigmer Cloud and a self-hosted server never clobbers either
+// side's login state. Two names are reserved: "local" (the managed daemon,
+// never stored in the map — its endpoint and no-auth posture are fixed)
+// and "cloud" (where `stigmer auth login` lands by default).
+//
+// Legacy shape + migration: pre-O3 files carried one `backend.cloud` slot
+// selected by `backend.type`. Loading migrates that shape in memory
+// (cloud section → `backends.cloud`, type → `current_backend`); the first
+// save writes the new shape — the ruled one-time write migration. The
+// legacy `backend.type` is still WRITTEN (mirroring local vs non-local)
+// so older readers keep a coherent view, and the opaque `backend.local`
+// section (daemon/LLM/Temporal settings owned by other tools) is
+// preserved verbatim, exactly as before.
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { UsageError } from "../errors/index.js";
 import { isStandalone } from "../runtime.js";
 import { configPath } from "./paths.js";
 
+/** The legacy binary switch, still written as a mirror for older readers. */
 export type BackendType = "local" | "cloud";
 
-/** Cloud backend connection. Property names are snake_case to serialize to the
- * exact YAML keys the Go CLI reads/writes. */
+/** The two named-backend families: Stigmer Cloud, or any OSS server. */
+export type NamedBackendType = "cloud" | "selfhost";
+
+/** The reserved name of the managed local daemon backend. */
+export const LOCAL_BACKEND_NAME = "local";
+
+/** The reserved name `stigmer auth login` targets from local mode. */
+export const CLOUD_BACKEND_NAME = "cloud";
+
+/**
+ * One named backend: endpoint + its own credentials. Property names are
+ * snake_case to keep the YAML in the file's established dialect.
+ *
+ * Credential lanes by type:
+ *   - cloud: the OAuth token set (token / refresh_token / token_expiry),
+ *     written by `stigmer auth login` and rotated by the token provider.
+ *   - selfhost: `api_key` — a server-minted `stk_` token
+ *     (`stigmer apikey create`). Browser login against self-hosted
+ *     issuers is deliberately not modeled here; the API token is the
+ *     self-host credential story.
+ */
+export interface NamedBackendConfig {
+  type: NamedBackendType;
+  endpoint?: string;
+  token?: string;
+  org_id?: string;
+  env_id?: string;
+  refresh_token?: string;
+  token_expiry?: string;
+  api_key?: string;
+}
+
+/** Cloud backend connection — the LEGACY single-slot shape (pre-O3 files). */
 export interface CloudBackendConfig {
   endpoint?: string;
   token?: string;
   org_id?: string;
   env_id?: string;
-  // Refresh-token support is new in the TS CLI (the Go CLI persists only the
-  // access token). These ride alongside the access token so the CLI can refresh
-  // silently instead of forcing re-login every hour. Interop note: the Go CLI
-  // models cloud config as a fixed struct and will drop these two fields if it
-  // re-saves the file — acceptable during the migration that retires it.
   refresh_token?: string;
   token_expiry?: string;
 }
 
 export interface BackendConfig {
   type: BackendType;
-  /** Local daemon/LLM/Temporal settings — opaque to the TS CLI in Wave 1,
+  /** Local daemon/LLM/Temporal settings — opaque to this CLI,
    * preserved verbatim across save so coexisting tools keep their config. */
   local?: unknown;
+  /** Legacy cloud slot — read for migration, never written back. */
   cloud?: CloudBackendConfig;
 }
 
@@ -45,6 +85,8 @@ export interface ContextConfig {
 
 export interface Config {
   backend: BackendConfig;
+  backends?: Record<string, NamedBackendConfig>;
+  current_backend?: string;
   context?: ContextConfig;
 }
 
@@ -54,9 +96,13 @@ const SAVE_HEADER = `# Stigmer CLI Configuration
 
 `;
 
-/** The default config: local backend, no daemon settings fabricated. */
+/** The default config: the local backend, no daemon settings fabricated. */
 export function getDefault(): Config {
-  return { backend: { type: "local" } };
+  return {
+    backend: { type: "local" },
+    backends: {},
+    current_backend: LOCAL_BACKEND_NAME,
+  };
 }
 
 /**
@@ -81,30 +127,125 @@ export function load(path: string = configPath()): Config {
   return normalize(parsed);
 }
 
-/** Persist the config to disk (0600 file in a 0755 directory), with the
- * documentation header the Go CLI writes. */
+/**
+ * Persist the config to disk (0600 file in a 0755 directory), with the
+ * documentation header the file has always carried. Writes the NAMED shape
+ * (the one-time migration): the legacy cloud slot is dropped — its content
+ * lives in `backends.cloud` — and `backend.type` is written as the
+ * local-vs-not mirror. A pristine local config (no named backends) writes
+ * exactly the pre-O3 bytes.
+ */
 export function save(config: Config, path: string = configPath()): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o755 });
-  const body = stringifyYaml(stripUndefined(config));
+  const body = stringifyYaml(stripUndefined(serializable(config)));
   writeFileSync(path, SAVE_HEADER + body, { mode: 0o600 });
 }
 
-/** True when the cloud backend is selected. */
+/** The active backend's name (normalize always stamps current_backend). */
+export function activeBackendName(config: Config): string {
+  const name = config.current_backend ?? "";
+  return name === "" ? LOCAL_BACKEND_NAME : name;
+}
+
+/**
+ * The active backend: the reserved local daemon (entry undefined) or a
+ * named entry. A current_backend naming a missing entry is a loud
+ * configuration error, never a silent fallback — the config was edited by
+ * hand or a remove left it dangling.
+ */
+export function activeBackend(config: Config): {
+  name: string;
+  entry: NamedBackendConfig | undefined;
+} {
+  const name = activeBackendName(config);
+  if (name === LOCAL_BACKEND_NAME) {
+    return { name, entry: undefined };
+  }
+  const entry = config.backends?.[name];
+  if (entry === undefined) {
+    throw new UsageError(
+      `current backend "${name}" does not exist — run 'stigmer config backend list' and 'stigmer config backend use <name>'`,
+    );
+  }
+  return { name, entry };
+}
+
+/** True when the active backend is Stigmer Cloud. */
 export function isCloudMode(config: Config): boolean {
-  return config.backend.type === "cloud";
+  return activeBackend(config).entry?.type === "cloud";
 }
 
 function normalize(parsed: Partial<Config> | null): Config {
-  if (parsed === null || parsed.backend === undefined) {
+  if (parsed === null || typeof parsed !== "object") {
     return getDefault();
   }
-  const type: BackendType = parsed.backend.type === "cloud" ? "cloud" : "local";
+
+  const legacy = parsed.backend;
+  const backends = normalizeBackends(parsed.backends);
+
+  // Migration: a pre-O3 cloud slot becomes the reserved "cloud" entry —
+  // unless a named shape already exists (then the named shape wins and the
+  // stale legacy slot is ignored).
+  if (Object.keys(backends).length === 0 && legacy?.cloud !== undefined) {
+    backends[CLOUD_BACKEND_NAME] = { type: "cloud", ...legacy.cloud };
+  }
+
+  let current =
+    typeof parsed.current_backend === "string" ? parsed.current_backend : "";
+  if (current === "") {
+    current =
+      legacy?.type === "cloud" && backends[CLOUD_BACKEND_NAME] !== undefined
+        ? CLOUD_BACKEND_NAME
+        : LOCAL_BACKEND_NAME;
+  }
+
   return {
-    backend: { type, local: parsed.backend.local, cloud: parsed.backend.cloud },
+    backend: {
+      type: legacy?.type === "cloud" ? "cloud" : "local",
+      local: legacy?.local,
+    },
+    backends,
+    current_backend: current,
     context: parsed.context,
   };
 }
 
+function normalizeBackends(
+  parsed: Record<string, NamedBackendConfig> | undefined,
+): Record<string, NamedBackendConfig> {
+  const backends: Record<string, NamedBackendConfig> = {};
+  if (parsed === undefined || typeof parsed !== "object") {
+    return backends;
+  }
+  for (const [name, entry] of Object.entries(parsed)) {
+    if (entry === null || typeof entry !== "object") continue;
+    backends[name] = {
+      ...entry,
+      type: entry.type === "cloud" ? "cloud" : "selfhost",
+    };
+  }
+  return backends;
+}
+
+/** The on-disk shape: named model + legacy mirror, minimal for defaults. */
+function serializable(config: Config): Config {
+  const backends = config.backends ?? {};
+  const current = activeBackendName(config);
+  const pristineLocal =
+    Object.keys(backends).length === 0 && current === LOCAL_BACKEND_NAME;
+  return {
+    backend: {
+      // The legacy mirror: local stays "local"; anything named is "cloud"
+      // to older readers (which cannot represent selfhost anyway).
+      type: current === LOCAL_BACKEND_NAME ? "local" : "cloud",
+      local: config.backend.local,
+      // The legacy cloud slot is never written back — migrated.
+    },
+    ...(pristineLocal ? {} : { backends, current_backend: current }),
+    context: config.context,
+  };
+}
+
 // Recursively drop undefined-valued keys so the serialized YAML omits empty
 // optionals (matching Go's yaml omitempty), while preserving the opaque local
 // section untouched.

package/src/config/index.ts

@@ -6,6 +6,12 @@ export {
   type CloudBackendConfig,
   type Config,
   type ContextConfig,
+  type NamedBackendConfig,
+  type NamedBackendType,
+  CLOUD_BACKEND_NAME,
+  LOCAL_BACKEND_NAME,
+  activeBackend,
+  activeBackendName,
   getDefault,
   isCloudMode,
   load,

package/src/config/keys.test.ts

@@ -10,6 +10,7 @@ describe("config keys", () => {
       "backend.cloud.org_id",
       "backend.type",
       "context.organization",
+      "current_backend",
     ]);
   });
 
@@ -21,18 +22,40 @@ describe("config keys", () => {
     expect(getConfigValue(getDefault(), "backend.cloud.org_id")).toBe("");
   });
 
-  it("sets a nested key, creating sub-objects", () => {
+  it("sets a nested key, creating the reserved cloud entry", () => {
     const config = getDefault();
     setConfigValue(config, "backend.cloud.org_id", "acme");
-    expect(config.backend.cloud?.org_id).toBe("acme");
+    expect(config.backends?.["cloud"]?.org_id).toBe("acme");
+    expect(getConfigValue(config, "backend.cloud.org_id")).toBe("acme");
+  });
+
+  it("backend.type set to cloud selects the reserved cloud entry", () => {
+    const config = getDefault();
+    setConfigValue(config, "backend.type", "cloud");
+    expect(config.current_backend).toBe("cloud");
+    expect(config.backends?.["cloud"]?.type).toBe("cloud");
+    expect(getConfigValue(config, "backend.type")).toBe("cloud");
+  });
+
+  it("current_backend switches only to known names", () => {
+    const config = getDefault();
+    expect(() => setConfigValue(config, "current_backend", "nope")).toThrow(
+      UsageError,
+    );
+    setConfigValue(config, "current_backend", "local");
+    expect(getConfigValue(config, "current_backend")).toBe("local");
   });
 
   it("validates backend.type values", () => {
-    expect(() => setConfigValue(getDefault(), "backend.type", "bogus")).toThrow(UsageError);
+    expect(() => setConfigValue(getDefault(), "backend.type", "bogus")).toThrow(
+      UsageError,
+    );
   });
 
   it("rejects unknown keys", () => {
     expect(() => getConfigValue(getDefault(), "nope.nope")).toThrow(UsageError);
-    expect(() => setConfigValue(getDefault(), "nope.nope", "x")).toThrow(UsageError);
+    expect(() => setConfigValue(getDefault(), "nope.nope", "x")).toThrow(
+      UsageError,
+    );
   });
 });