@stigmer/cli 3.13.0 → 3.14.0

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

package/src/config/keys.ts

@@ -3,7 +3,12 @@
 // managed by their own (later) commands and preserved opaquely on save.
 
 import { UsageError } from "../errors/usage-error.js";
-import type { BackendType, Config } from "./config.js";
+import {
+  CLOUD_BACKEND_NAME,
+  type Config,
+  LOCAL_BACKEND_NAME,
+  activeBackendName,
+} from "./config.js";
 
 interface ConfigKey {
   /** Stored (non-resolved) value, "" when unset. */
@@ -12,26 +17,54 @@ interface ConfigKey {
   set(config: Config, value: string): void;
 }
 
+// The backend.cloud.* keys predate named backends and remain the documented
+// kv surface for the reserved "cloud" entry; `current_backend` is the named
+// model's own key. `backend.type` stays the simple local/cloud switch
+// (named backends switch through `config backend use`).
 const KEYS: Record<string, ConfigKey> = {
   "backend.type": {
-    get: (config) => config.backend.type,
+    get: (config) =>
+      activeBackendName(config) === LOCAL_BACKEND_NAME ? "local" : "cloud",
     set: (config, value) => {
       if (value !== "local" && value !== "cloud") {
-        throw new UsageError(`invalid backend.type "${value}" (expected: local, cloud)`);
+        throw new UsageError(
+          `invalid backend.type "${value}" (expected: local, cloud)`,
+        );
       }
-      config.backend.type = value as BackendType;
+      if (value === "cloud") {
+        (config.backends ??= {})[CLOUD_BACKEND_NAME] ??= { type: "cloud" };
+        config.current_backend = CLOUD_BACKEND_NAME;
+      } else {
+        config.current_backend = LOCAL_BACKEND_NAME;
+      }
+    },
+  },
+  current_backend: {
+    get: (config) => activeBackendName(config),
+    set: (config, value) => {
+      if (
+        value !== LOCAL_BACKEND_NAME &&
+        config.backends?.[value] === undefined
+      ) {
+        throw new UsageError(
+          `unknown backend "${value}" (add it first: stigmer config backend add)`,
+        );
+      }
+      config.current_backend = value;
     },
   },
   "backend.cloud.endpoint": {
-    get: (config) => config.backend.cloud?.endpoint ?? "",
+    get: (config) => config.backends?.[CLOUD_BACKEND_NAME]?.endpoint ?? "",
     set: (config, value) => {
-      (config.backend.cloud ??= {}).endpoint = value;
+      const backends = (config.backends ??= {});
+      (backends[CLOUD_BACKEND_NAME] ??= { type: "cloud" }).endpoint = value;
     },
   },
   "backend.cloud.org_id": {
-    get: (config) => config.backend.cloud?.org_id ?? "",
+    get: (config) => config.backends?.[CLOUD_BACKEND_NAME]?.org_id ?? "",
     set: (config, value) => {
-      (config.backend.cloud ??= {}).org_id = value;
+      const backends = (config.backends ??= {});
+      (backends[CLOUD_BACKEND_NAME] ??= { type: "cloud" }).org_id = value;
     },
   },
   "context.organization": {
@@ -53,7 +86,11 @@ export function getConfigValue(config: Config, key: string): string {
   return entry.get(config);
 }
 
-export function setConfigValue(config: Config, key: string, value: string): void {
+export function setConfigValue(
+  config: Config,
+  key: string,
+  value: string,
+): void {
   const entry = KEYS[key];
   if (entry === undefined) throw new UsageError(unknownKeyMessage(key));
   entry.set(config, value);