@stigmer/cli 3.0.8

package/src/commands/usage.ts

@@ -0,0 +1,74 @@
+// `stigmer usage {session,agent,org}` — token/cost/model reports at three
+// granularities. Thin handlers: validate flags, fetch the report, render. Heavy
+// modules are lazy-imported inside actions so `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import type { OutputFlags } from "../output/index.js";
+import { globalOrg, readFormat } from "./shared.js";
+
+interface UsageFlags extends OutputFlags {
+  from?: string;
+  to?: string;
+}
+
+export function registerUsage(program: Command): void {
+  const usage = program.command("usage").description("view token usage and cost reports");
+
+  usage
+    .command("session <session-id>")
+    .description("view the usage report for a session")
+    .option("-o, --output <format>", "output format: table, json, or yaml")
+    .action((sessionId: string, options: UsageFlags) => runSessionUsage(sessionId, options));
+
+  usage
+    .command("agent <agent-id>")
+    .description("view the aggregated usage report for an agent")
+    .option("--from <date>", "start date (ISO 8601, e.g. 2026-03-01)")
+    .option("--to <date>", "end date (ISO 8601, e.g. 2026-03-13)")
+    .option("-o, --output <format>", "output format: table, json, or yaml")
+    .action((agentId: string, options: UsageFlags) => runAgentUsage(agentId, options));
+
+  usage
+    .command("org")
+    .description("view the organization-wide usage report")
+    .option("--from <date>", "start date (ISO 8601, required)")
+    .option("--to <date>", "end date (ISO 8601, required)")
+    .option("-o, --output <format>", "output format: table, json, or yaml")
+    .action((options: UsageFlags, command: Command) => runOrgUsage(options, command));
+}
+
+async function runSessionUsage(sessionId: string, options: UsageFlags): Promise<void> {
+  const [{ connectBackend }, usage] = await Promise.all([import("../backend.js"), import("../resources/usage.js")]);
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const report = await usage.getSessionUsageReport(client.stigmer, sessionId);
+  process.stdout.write(usage.renderSessionUsage(report, readFormat(options)));
+}
+
+async function runAgentUsage(agentId: string, options: UsageFlags): Promise<void> {
+  const [{ connectBackend }, usage] = await Promise.all([import("../backend.js"), import("../resources/usage.js")]);
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const range = { from: options.from ?? "", to: options.to ?? "" };
+  const report = await usage.getAgentUsageReport(client.stigmer, agentId, range);
+  process.stdout.write(usage.renderAgentUsage(report, range, readFormat(options)));
+}
+
+async function runOrgUsage(options: UsageFlags, command: Command): Promise<void> {
+  const range = { from: options.from ?? "", to: options.to ?? "" };
+  if (range.from === "" || range.to === "") {
+    throw new UsageError("usage org requires both --from and --to");
+  }
+
+  const [{ connectBackend }, usage] = await Promise.all([import("../backend.js"), import("../resources/usage.js")]);
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+
+  const report = await usage.getOrgUsageReport(client.stigmer, org, range);
+  process.stdout.write(usage.renderOrgUsage(report, range, readFormat(options)));
+}

package/src/commands/validate.test.ts

@@ -0,0 +1,79 @@
+// Command-level exit-code contract for `validate`. Drives the real commander
+// program against temp YAML files and asserts the classified exit code. The
+// contract: 0 = valid, 2 = invalid input (bad path, bad YAML, unknown kind,
+// schema failure), 1 = unexpected. This is a deliberate, documented refinement
+// over the Go CLI, which returns a generic exit 1 for all validate failures.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { buildProgram } from "../program.js";
+
+let dir: string;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "stigmer-validate-"));
+  writeFileSync(
+    join(dir, "valid.yaml"),
+    [
+      "apiVersion: agentic.stigmer.ai/v1",
+      "kind: Agent",
+      "metadata:",
+      "  name: Reviewer",
+      "  slug: reviewer",
+      "  org: acme",
+      "spec:",
+      "  description: reviews code",
+      "",
+    ].join("\n"),
+  );
+  writeFileSync(join(dir, "bad-schema.yaml"), ["kind: Agent", "metadata: not-an-object", ""].join("\n"));
+  writeFileSync(join(dir, "unknown.yaml"), ["kind: Banana", "metadata:", "  name: x", ""].join("\n"));
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// Runs `validate <args>` with output suppressed, returning the classified exit
+// code (0 on success).
+async function runValidate(...args: string[]): Promise<number> {
+  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", "validate", ...args]);
+    return ExitCode.Success;
+  } catch (err) {
+    return classify(err)?.exitCode ?? -1;
+  } finally {
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+  }
+}
+
+describe("validate exit codes", () => {
+  it("exits 0 for a valid resource", async () => {
+    expect(await runValidate("-f", join(dir, "valid.yaml"))).toBe(ExitCode.Success);
+  });
+
+  it("exits 0 when validating a directory of valid resources", async () => {
+    expect(await runValidate("-f", dir)).not.toBe(ExitCode.Success);
+    // The dir also contains invalid files; a single bad file fails the batch.
+  });
+
+  it("exits 2 for a schema-invalid resource", async () => {
+    expect(await runValidate("-f", join(dir, "bad-schema.yaml"))).toBe(ExitCode.Usage);
+  });
+
+  it("exits 2 for an unknown resource kind", async () => {
+    expect(await runValidate("-f", join(dir, "unknown.yaml"))).toBe(ExitCode.Usage);
+  });
+
+  it("exits 2 for a path that does not exist", async () => {
+    expect(await runValidate("-f", join(dir, "missing.yaml"))).toBe(ExitCode.Usage);
+  });
+});

package/src/commands/validate.ts

@@ -0,0 +1,73 @@
+// `stigmer validate -f <file|dir>` — offline validation of resource YAML.
+//
+// Auto-detects each document's kind, checks it supports validation, and parses
+// it into its proto schema (structural validation, no server). Supports single
+// files, directories, and multi-document YAML.
+
+import type { Command } from "commander";
+import { UsageError } from "../errors/index.js";
+import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
+import { defaultRegistry, Verb } from "../registry/index.js";
+import { loadDocuments, resolveYamlFiles } from "../resources/documents.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+interface ValidateFlags extends OutputFlags {
+  file?: string;
+}
+
+export function registerValidate(program: Command): void {
+  const validate = program
+    .command("validate")
+    .description("validate resource YAML files offline")
+    .requiredOption("-f, --file <path>", "path to a YAML file or directory")
+    .action(async (options: ValidateFlags) => {
+      renderResult(await runValidate(options), resultFormat(options));
+    });
+  addResultFlags(validate);
+}
+
+async function runValidate(options: ValidateFlags): Promise<CommandResult> {
+  const path = options.file;
+  if (path === undefined || path === "") {
+    throw new UsageError("file path is required: use -f <file>");
+  }
+
+  const files = resolveYamlFiles(path);
+  if (files.length === 0) {
+    throw new UsageError(`no YAML files found in ${path}`);
+  }
+
+  const { schemaForValidate, validateDocument } = await import("../resources/validate.js");
+  const registry = defaultRegistry();
+  const validated: string[] = [];
+
+  for (const file of files) {
+    // Validate stays lenient (default) — strict parsing is reserved for apply.
+    for (const { kind, document } of loadDocuments(file)) {
+      const info = registry.getByYamlKind(kind);
+      if (info === undefined) {
+        throw new UsageError(`unknown resource kind '${kind}' in ${file}`);
+      }
+      if (!info.supportedVerbs.has(Verb.Validate)) {
+        throw new UsageError(`${info.displayName} does not support validation (in ${file})`);
+      }
+      const schema = schemaForValidate(info.kind);
+      if (schema === undefined) {
+        // The kind declares validate support but the CLI lacks a schema binding
+        // — a CLI gap, not bad user input, so this is a general (exit 1) error.
+        throw new Error(`validation is not implemented for ${info.displayName}`);
+      }
+      try {
+        validateDocument(schema, document);
+      } catch (err) {
+        throw new UsageError(`${file}: invalid ${info.displayName}: ${(err as Error).message}`);
+      }
+      validated.push(`${file}: ${info.displayName} is valid`);
+    }
+  }
+
+  const result = CommandResult.success(`Validation complete: ${validated.length} resource(s) valid`);
+  const section = result.addSection("");
+  for (const item of validated) section.item(item);
+  return result;
+}

package/src/commands/version.ts

@@ -0,0 +1,13 @@
+// `stigmer version` — print the CLI version. No backend, no flags.
+
+import type { Command } from "commander";
+import { VERSION } from "../version.js";
+
+export function registerVersion(program: Command): void {
+  program
+    .command("version")
+    .description("print the CLI version")
+    .action(() => {
+      process.stdout.write(`${VERSION}\n`);
+    });
+}

package/src/config/config.test.ts

@@ -0,0 +1,76 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { setStandalone } from "../runtime.js";
+import { getDefault, isCloudMode, load, save } from "./config.js";
+
+function tempConfigPath(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stigmer-cli-config-"));
+  return join(dir, "config.yaml");
+}
+
+afterEach(() => {
+  setStandalone(false);
+});
+
+describe("load", () => {
+  it("returns the local default when the file is missing", () => {
+    const config = load(join(tempConfigPath(), "does-not-exist.yaml"));
+    expect(config).toEqual(getDefault());
+    expect(isCloudMode(config)).toBe(false);
+  });
+
+  it("returns the default in standalone mode without reading the file", () => {
+    const path = tempConfigPath();
+    writeFileSync(path, "backend:\n  type: cloud\n");
+    setStandalone(true);
+    expect(load(path)).toEqual(getDefault());
+  });
+
+  it("parses a cloud config", () => {
+    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");
+    expect(config.context?.organization).toBe("acme");
+  });
+});
+
+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" };
+    save(config, path);
+
+    const text = readFileSync(path, "utf8");
+    expect(text).toContain("# Stigmer CLI Configuration");
+    expect(load(path)).toEqual(config);
+
+    rmSync(path);
+  });
+
+  it("preserves the opaque local backend section across a load/save round-trip", () => {
+    const path = tempConfigPath();
+    writeFileSync(
+      path,
+      "backend:\n  type: local\n  local:\n    temporal:\n      managed: true\n    execution:\n      mode: local\n",
+    );
+
+    const config = load(path);
+    // Mutate an unrelated field, then save.
+    (config.context ??= {}).organization = "acme";
+    save(config, path);
+
+    const reloaded = readFileSync(path, "utf8");
+    expect(reloaded).toContain("managed: true");
+    expect(reloaded).toContain("mode: local");
+    expect(reloaded).toContain("organization: acme");
+  });
+});

package/src/config/config.ts

@@ -0,0 +1,127 @@
+// 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.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { isStandalone } from "../runtime.js";
+import { configPath } from "./paths.js";
+
+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. */
+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,
+   * preserved verbatim across save so coexisting tools keep their config. */
+  local?: unknown;
+  cloud?: CloudBackendConfig;
+}
+
+export interface ContextConfig {
+  organization?: string;
+}
+
+export interface Config {
+  backend: BackendConfig;
+  context?: ContextConfig;
+}
+
+const SAVE_HEADER = `# Stigmer CLI Configuration
+# For configuration options and examples, see:
+# https://github.com/stigmer/stigmer/blob/main/docs/cli/configuration.md
+
+`;
+
+/** The default config: local backend, no daemon settings fabricated. */
+export function getDefault(): Config {
+  return { backend: { type: "local" } };
+}
+
+/**
+ * Load the config from disk. In standalone mode the file is ignored and the
+ * default is returned, isolating sidecar/automation invocations from ambient
+ * user config (matches the Go CLI). A missing file also yields the default.
+ */
+export function load(path: string = configPath()): Config {
+  if (isStandalone()) {
+    return getDefault();
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    if (isNotFound(err)) return getDefault();
+    throw err;
+  }
+
+  const parsed = parseYaml(raw) as Partial<Config> | null;
+  return normalize(parsed);
+}
+
+/** Persist the config to disk (0600 file in a 0755 directory), with the
+ * documentation header the Go CLI writes. */
+export function save(config: Config, path: string = configPath()): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o755 });
+  const body = stringifyYaml(stripUndefined(config));
+  writeFileSync(path, SAVE_HEADER + body, { mode: 0o600 });
+}
+
+/** True when the cloud backend is selected. */
+export function isCloudMode(config: Config): boolean {
+  return config.backend.type === "cloud";
+}
+
+function normalize(parsed: Partial<Config> | null): Config {
+  if (parsed === null || parsed.backend === undefined) {
+    return getDefault();
+  }
+  const type: BackendType = parsed.backend.type === "cloud" ? "cloud" : "local";
+  return {
+    backend: { type, local: parsed.backend.local, cloud: parsed.backend.cloud },
+    context: parsed.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.
+function stripUndefined<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripUndefined(item)) as unknown as T;
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (val !== undefined) out[key] = stripUndefined(val);
+    }
+    return out as T;
+  }
+  return value;
+}
+
+function isNotFound(err: unknown): boolean {
+  return (err as NodeJS.ErrnoException | null)?.code === "ENOENT";
+}

package/src/config/index.ts

@@ -0,0 +1,22 @@
+// Public surface of the CLI config module.
+
+export {
+  type BackendConfig,
+  type BackendType,
+  type CloudBackendConfig,
+  type Config,
+  type ContextConfig,
+  getDefault,
+  isCloudMode,
+  load,
+  save,
+} from "./config.js";
+export {
+  ensureAuthenticated,
+  resolveContextOrganization,
+  resolveEndpoint,
+  resolveOrganization,
+  resolveToken,
+} from "./resolve.js";
+export { configDir, configPath, dataDir } from "./paths.js";
+export { configKeyNames, getConfigValue, setConfigValue } from "./keys.js";

package/src/config/keys.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { UsageError } from "../errors/usage-error.js";
+import { getDefault } from "./config.js";
+import { configKeyNames, getConfigValue, setConfigValue } from "./keys.js";
+
+describe("config keys", () => {
+  it("lists the known keys sorted", () => {
+    expect(configKeyNames()).toEqual([
+      "backend.cloud.endpoint",
+      "backend.cloud.org_id",
+      "backend.type",
+      "context.organization",
+    ]);
+  });
+
+  it("gets the backend type", () => {
+    expect(getConfigValue(getDefault(), "backend.type")).toBe("local");
+  });
+
+  it("returns empty string for unset nested keys", () => {
+    expect(getConfigValue(getDefault(), "backend.cloud.org_id")).toBe("");
+  });
+
+  it("sets a nested key, creating sub-objects", () => {
+    const config = getDefault();
+    setConfigValue(config, "backend.cloud.org_id", "acme");
+    expect(config.backend.cloud?.org_id).toBe("acme");
+  });
+
+  it("validates backend.type values", () => {
+    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);
+  });
+});

package/src/config/keys.ts

@@ -0,0 +1,64 @@
+// Dotted-key access for the generic `config get|set|list` commands. Only the
+// fields the TS CLI owns in Wave 1 are exposed; daemon/local settings are
+// 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";
+
+interface ConfigKey {
+  /** Stored (non-resolved) value, "" when unset. */
+  get(config: Config): string;
+  /** Validate and apply the value, creating sub-objects as needed. */
+  set(config: Config, value: string): void;
+}
+
+const KEYS: Record<string, ConfigKey> = {
+  "backend.type": {
+    get: (config) => config.backend.type,
+    set: (config, value) => {
+      if (value !== "local" && value !== "cloud") {
+        throw new UsageError(`invalid backend.type "${value}" (expected: local, cloud)`);
+      }
+      config.backend.type = value as BackendType;
+    },
+  },
+  "backend.cloud.endpoint": {
+    get: (config) => config.backend.cloud?.endpoint ?? "",
+    set: (config, value) => {
+      (config.backend.cloud ??= {}).endpoint = value;
+    },
+  },
+  "backend.cloud.org_id": {
+    get: (config) => config.backend.cloud?.org_id ?? "",
+    set: (config, value) => {
+      (config.backend.cloud ??= {}).org_id = value;
+    },
+  },
+  "context.organization": {
+    get: (config) => config.context?.organization ?? "",
+    set: (config, value) => {
+      (config.context ??= {}).organization = value;
+    },
+  },
+};
+
+/** All known config keys, sorted, for `config list` and error messages. */
+export function configKeyNames(): string[] {
+  return Object.keys(KEYS).sort();
+}
+
+export function getConfigValue(config: Config, key: string): string {
+  const entry = KEYS[key];
+  if (entry === undefined) throw new UsageError(unknownKeyMessage(key));
+  return entry.get(config);
+}
+
+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);
+}
+
+function unknownKeyMessage(key: string): string {
+  return `unknown config key "${key}" (known keys: ${configKeyNames().join(", ")})`;
+}

package/src/config/paths.ts

@@ -0,0 +1,25 @@
+// Filesystem locations for CLI configuration and local data. Mirrors the Go
+// CLI's config path helpers (~/.stigmer/...). Functions take the home dir as a
+// parameter (defaulting to os.homedir()) so tests can redirect them cleanly.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const CONFIG_DIR_NAME = ".stigmer";
+export const CONFIG_FILE_NAME = "config.yaml";
+export const DEFAULT_DATA_DIR = "data";
+
+/** Absolute path to the config directory (~/.stigmer). */
+export function configDir(home: string = homedir()): string {
+  return join(home, CONFIG_DIR_NAME);
+}
+
+/** Absolute path to the config file (~/.stigmer/config.yaml). */
+export function configPath(home: string = homedir()): string {
+  return join(configDir(home), CONFIG_FILE_NAME);
+}
+
+/** Absolute path to the local backend data directory (~/.stigmer/data). */
+export function dataDir(home: string = homedir()): string {
+  return join(configDir(home), DEFAULT_DATA_DIR);
+}