@stigmer/cli 3.1.7 → 3.1.8

package/src/commands/share.ts

@@ -0,0 +1,99 @@
+// `stigmer share agent <ref>` — enable (default) or disable (--off) public
+// sharing for an agent, printing the hosted chat link and embed snippet.
+//
+// Thin handler: resolve credentials/org and the console origin, delegate the
+// merge-preserving toggle to resources/share, render the result. `--open` is a
+// best-effort browser launch after render (mirrors auth login: the URL is
+// already on screen, so a failed launch costs nothing). Heavy modules are
+// lazy-imported so `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { 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";
+import { addResultFlags, globalOrg, resultFormat } from "./shared.js";
+
+interface ShareAgentFlags extends OutputFlags {
+  off?: boolean;
+  open?: boolean;
+  audience?: string;
+  resetLink?: boolean;
+}
+
+export function registerShare(program: Command): void {
+  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")
+    .option("--off", "disable sharing (the link stops working immediately)")
+    .option(
+      "--audience <audience>",
+      "who can chat: 'public' (anyone with the link) or 'org' (signed-in organization members only); omit to keep the current audience",
+    )
+    .option(
+      "--reset-link",
+      "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));
+  addResultFlags(agent);
+}
+
+// Validates --audience before any network work; omitted means "preserve".
+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'.`);
+}
+
+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 client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+
+  const backendType = client.config.backend.type;
+  const appOrigin = resolveConsoleURL(backendType);
+  const enabled = options.off !== true;
+  const audience = parseAudience(options.audience);
+  const resetLink = options.resetLink === true;
+  if (resetLink && !enabled) {
+    throw new UsageError(
+      "--reset-link cannot be combined with --off\n\n" +
+        "Disabling sharing already kills the link. Reset is for keeping\n" +
+        "sharing on while invalidating the current URL.",
+    );
+  }
+
+  const result = await shareAgent(client.stigmer, ref, org, {
+    enabled,
+    ...(audience !== undefined ? { audience } : {}),
+    resetLink,
+    appOrigin,
+    isLocal: backendType === "local",
+  });
+  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];
+    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");
+      }
+    }
+  }
+}

package/src/config/index.ts

@@ -12,7 +12,9 @@ export {
   save,
 } from "./config.js";
 export {
+  DEFAULT_CLOUD_CONSOLE_URL,
   ensureAuthenticated,
+  resolveConsoleURL,
   resolveContextOrganization,
   resolveEndpoint,
   resolveOrganization,

package/src/config/resolve.test.ts

@@ -2,7 +2,9 @@ import { afterEach, describe, expect, it } from "vitest";
 import { CliExitError } from "../errors/index.js";
 import type { Config } from "./config.js";
 import {
+  DEFAULT_CLOUD_CONSOLE_URL,
   ensureAuthenticated,
+  resolveConsoleURL,
   resolveContextOrganization,
   resolveEndpoint,
   resolveOrganization,
@@ -77,6 +79,42 @@ describe("resolveOrganization", () => {
   it("falls back to legacy cloud org_id", () => {
     expect(resolveContextOrganization(cloudConfig({ org_id: "legacy" }))).toBe("legacy");
   });
+
+  it("defaults to the seedpack org in local mode when nothing is configured", () => {
+    expect(resolveOrganization({ backend: { type: "local" } })).toBe("stigmer");
+  });
+
+  it("prefers an explicit context org over the local default", () => {
+    const config: Config = { backend: { type: "local" }, context: { organization: "my-local-org" } };
+    expect(resolveOrganization(config)).toBe("my-local-org");
+  });
+
+  it("does not apply the local default in cloud mode (org stays empty)", () => {
+    expect(resolveOrganization({ backend: { type: "cloud" } })).toBe("");
+  });
+
+  it("reports an unset local org as empty via resolveContextOrganization (no implicit default)", () => {
+    // The implicit local default lives only in resolveOrganization (effective
+    // org for operations); the context query must stay faithful so config/context
+    // display can show "(not set)".
+    expect(resolveContextOrganization({ backend: { type: "local" } })).toBe("");
+  });
+});
+
+describe("resolveConsoleURL", () => {
+  it("prefers the STIGMER_CONSOLE_URL override", () => {
+    expect(resolveConsoleURL("cloud", { STIGMER_CONSOLE_URL: "https://console.example" } as NodeJS.ProcessEnv)).toBe(
+      "https://console.example",
+    );
+  });
+
+  it("uses the local web-console port for the local backend", () => {
+    expect(resolveConsoleURL("local", {} as NodeJS.ProcessEnv)).toBe("http://localhost:8234");
+  });
+
+  it("uses the cloud console URL for the cloud backend", () => {
+    expect(resolveConsoleURL("cloud", {} as NodeJS.ProcessEnv)).toBe(DEFAULT_CLOUD_CONSOLE_URL);
+  });
 });
 
 describe("ensureAuthenticated", () => {

package/src/config/resolve.ts

@@ -3,11 +3,22 @@
 // precedence keeps every call site consistent (mirrors the Go CLI's Resolve*).
 
 import { CliExitError, ExitCode } from "../errors/index.js";
-import { type Config, isCloudMode } from "./config.js";
+import { WEB_CONSOLE_PORT } from "../local/constants.js";
+import { type BackendType, type Config, isCloudMode } from "./config.js";
 
 const DEFAULT_CLOUD_ENDPOINT = "api.stigmer.ai:443";
 const DEFAULT_LOCAL_ENDPOINT = "localhost:7234";
 
+/** Well-known URL for the Stigmer Cloud web console. */
+export const DEFAULT_CLOUD_CONSOLE_URL = "https://app.stigmer.ai";
+
+// Local mode is single-tenant: the seedpack bootstraps resources into the
+// "stigmer" org (see client-apps/cli/src/local/seedpack/apply.ts DEFAULT_ORG).
+// Org-scoped getByReference now requires an org, so bare-slug `get`/`run`/`apply`
+// in local mode fall back to this default when nothing else is configured. Cloud
+// mode has no implicit org — the caller must select one (flag/env/context/login).
+const DEFAULT_LOCAL_ORG = "stigmer";
+
 /**
  * Resolve the server endpoint.
  *   STIGMER_SERVER_ADDRESS  (explicit override, either backend)
@@ -52,10 +63,38 @@ export function resolveOrganization(config: Config, flagOrg?: string): string {
   if (env !== undefined && env !== "") {
     return env;
   }
-  return resolveContextOrganization(config);
+  const context = resolveContextOrganization(config);
+  if (context !== "") {
+    return context;
+  }
+  // Nothing configured: local mode falls back to its single-tenant default org
+  // so bare-slug operations resolve without ceremony; cloud stays empty (the
+  // caller must select an org, e.g. apply raises a clear "organization not set").
+  return isCloudMode(config) ? "" : DEFAULT_LOCAL_ORG;
 }
 
-/** The configured organization, with the legacy cloud.org_id fallback. */
+/**
+ * Resolve the web console URL:
+ *   1. `STIGMER_CONSOLE_URL` (explicit override)
+ *   2. local backend → `http://localhost:{WEB_CONSOLE_PORT}`
+ *   3. cloud backend → {@link DEFAULT_CLOUD_CONSOLE_URL}
+ *
+ * The console origin is also the app origin that serves the hosted chat
+ * page (`/chat/<org>/<slug>`) and the embed loader (`/embed.js`), so
+ * share-link builders use this same resolver.
+ */
+export function resolveConsoleURL(backendType: BackendType, env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.STIGMER_CONSOLE_URL;
+  if (override !== undefined && override !== "") return override;
+  if (backendType === "local") return `http://localhost:${WEB_CONSOLE_PORT}`;
+  return DEFAULT_CLOUD_CONSOLE_URL;
+}
+
+/**
+ * The configured organization, with the legacy cloud.org_id fallback. Reports
+ * only what is explicitly set (no implicit local default) so config/context
+ * display can faithfully show "(not set)".
+ */
 export function resolveContextOrganization(config: Config): string {
   if (config.context?.organization !== undefined && config.context.organization !== "") {
     return config.context.organization;

package/src/local/runtime/node.ts

@@ -1,10 +1,10 @@
 // Resolution of the Node.js runtime used to launch the runner subprocess.
 //
 // We reuse the very Node that is running the CLI (process.execPath). The CLI is
-// itself an npm package with `engines: node >= 20`, so a suitable Node is always
-// present by construction — there is deliberately no hermetic Node download
-// (DD-002: keep the base install lean; nothing to acquire that the host already
-// guarantees). This is exactly what the conformance harness does
+// itself an npm package with `engines: node >= 22.13`, so a suitable Node is
+// always present by construction — there is deliberately no hermetic Node
+// download (DD-002: keep the base install lean; nothing to acquire that the host
+// already guarantees). This is exactly what the conformance harness does
 // (`spawn(process.execPath, ...)`). An explicit STIGMER_NODE_BIN override is
 // honored and version-checked for advanced/multi-runtime setups.
 
@@ -12,8 +12,20 @@ import { execFileSync } from "node:child_process";
 import { CliExitError } from "../../errors/cli-exit-error.js";
 import { ExitCode } from "../../errors/exit-codes.js";
 
-/** Minimum Node major version the runner requires. */
-export const MIN_NODE_MAJOR = 20;
+/**
+ * Minimum Node version the runner requires: 22.13. The runner's durable local
+ * checkpointer imports Node's built-in `node:sqlite`, which is only available
+ * WITHOUT the --experimental-sqlite flag from v22.13 (and v23.4) onward. A
+ * major-only gate would let 22.0-22.12 pass and then crash at checkpointer
+ * creation, so the minor is enforced when the major is exactly 22.
+ */
+export const MIN_NODE_MAJOR = 22;
+export const MIN_NODE_MINOR_ON_MAJOR = 13;
+
+interface NodeVersion {
+  major: number;
+  minor: number;
+}
 
 /**
  * Resolve the Node binary to launch the runner with. Honors STIGMER_NODE_BIN
@@ -22,46 +34,52 @@ export const MIN_NODE_MAJOR = 20;
 export function resolveNode(): string {
   const override = process.env.STIGMER_NODE_BIN;
   if (override !== undefined && override !== "") {
-    assertVersion(override, probeNodeMajor(override));
+    assertVersion(override, probeNodeVersion(override));
     return override;
   }
-  // The CLI's own runtime: major is readable directly, no subprocess needed.
-  assertVersion(process.execPath, currentMajor());
+  // The CLI's own runtime: version is readable directly, no subprocess needed.
+  assertVersion(process.execPath, parseVersion(process.versions.node));
   return process.execPath;
 }
 
-function currentMajor(): number | null {
-  return parseMajor(process.versions.node);
-}
-
-function probeNodeMajor(bin: string): number | null {
+function probeNodeVersion(bin: string): NodeVersion | null {
   try {
     const out = execFileSync(bin, ["--version"], { encoding: "utf8" });
-    return parseMajor(out.trim());
+    return parseVersion(out.trim());
   } catch {
     return null;
   }
 }
 
-// Parses "v22.22.2" or "22.22.2" to its major number.
-function parseMajor(version: string): number | null {
-  const match = /^v?(\d+)\./.exec(version.trim());
+// Parses "v22.22.2" or "22.22.2" to its major/minor numbers.
+function parseVersion(version: string): NodeVersion | null {
+  const match = /^v?(\d+)\.(\d+)\./.exec(version.trim());
   if (match === null) return null;
   const major = Number.parseInt(match[1], 10);
-  return Number.isInteger(major) ? major : null;
+  const minor = Number.parseInt(match[2], 10);
+  if (!Number.isInteger(major) || !Number.isInteger(minor)) return null;
+  return { major, minor };
+}
+
+// True when the version is at or above the 22.13 floor.
+function meetsFloor(v: NodeVersion): boolean {
+  if (v.major > MIN_NODE_MAJOR) return true;
+  return v.major === MIN_NODE_MAJOR && v.minor >= MIN_NODE_MINOR_ON_MAJOR;
 }
 
-function assertVersion(bin: string, major: number | null): void {
-  if (major === null) {
+function assertVersion(bin: string, version: NodeVersion | null): void {
+  const floor = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR_ON_MAJOR}`;
+  if (version === null) {
     throw new CliExitError(`could not determine the Node version of ${bin}`, ExitCode.General, [
-      `Ensure ${bin} is a working Node >= ${MIN_NODE_MAJOR} runtime.`,
+      `Ensure ${bin} is a working Node >= ${floor} runtime.`,
     ]);
   }
-  if (major < MIN_NODE_MAJOR) {
+  if (!meetsFloor(version)) {
     throw new CliExitError(
-      `Node >= ${MIN_NODE_MAJOR} is required to run the runner (found major ${major} at ${bin})`,
+      `Node >= ${floor} is required to run the runner ` +
+        `(found ${version.major}.${version.minor} at ${bin})`,
       ExitCode.General,
-      [`Upgrade Node to ${MIN_NODE_MAJOR} or newer, or point STIGMER_NODE_BIN at one.`],
+      [`Upgrade Node to ${floor} or newer, or point STIGMER_NODE_BIN at one.`],
     );
   }
 }

package/src/local/runtime/runtime.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { CliExitError } from "../../errors/cli-exit-error.js";
-import { MIN_NODE_MAJOR, resolveNode } from "./node.js";
+import { MIN_NODE_MAJOR, MIN_NODE_MINOR_ON_MAJOR, resolveNode } from "./node.js";
 import { acquireRunner, resolveRunner } from "./runner.js";
 import { resolveServerBinary } from "./server.js";
 import { which } from "./which.js";
@@ -57,7 +57,7 @@ describe("resolveNode", () => {
   });
 
   it("honors a valid override", () => {
-    process.env.STIGMER_NODE_BIN = process.execPath; // a real Node >= 20
+    process.env.STIGMER_NODE_BIN = process.execPath; // a real Node >= 22.13
     expect(resolveNode()).toBe(process.execPath);
   });
 
@@ -66,8 +66,9 @@ describe("resolveNode", () => {
     expect(() => resolveNode()).toThrow(CliExitError);
   });
 
-  it("requires Node >= 20", () => {
-    expect(MIN_NODE_MAJOR).toBe(20);
+  it("requires Node >= 22.13 (the node:sqlite floor)", () => {
+    expect(MIN_NODE_MAJOR).toBe(22);
+    expect(MIN_NODE_MINOR_ON_MAJOR).toBe(13);
   });
 });
 

package/src/program.test.ts

@@ -43,6 +43,13 @@ describe("buildProgram", () => {
     expect(message?.required).toBe(true);
   });
 
+  it("exposes the share subcommands", () => {
+    const program = buildProgram();
+    const share = program.commands.find((command) => command.name() === "share");
+    const subs = share?.commands.map((command) => command.name());
+    expect(subs).toEqual(["agent"]);
+  });
+
   it("exposes the usage subcommands", () => {
     const program = buildProgram();
     const usage = program.commands.find((command) => command.name() === "usage");

package/src/program.ts

@@ -31,6 +31,7 @@ import { registerRun } from "./commands/run.js";
 import { registerSearch } from "./commands/search.js";
 import { registerSeedpack } from "./commands/seedpack.js";
 import { registerSetup } from "./commands/setup.js";
+import { registerShare } from "./commands/share.js";
 import { registerStatus } from "./commands/status.js";
 import { registerTag } from "./commands/tag.js";
 import { registerUp } from "./commands/up.js";
@@ -76,6 +77,7 @@ export function buildProgram(): Command {
   registerValidate(program);
   registerDelete(program);
   registerTag(program);
+  registerShare(program);
   registerDiff(program);
   registerUsage(program);
   registerPush(program);

package/src/resources/connect/oauth.test.ts

@@ -3,14 +3,7 @@ import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1
 import type { Stigmer } from "@stigmer/sdk";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { UsageError } from "../../errors/index.js";
-import {
-  browserCommand,
-  DEFAULT_CLOUD_CONSOLE_URL,
-  resolveConsoleURL,
-  runOAuthFlow,
-  waitForOAuthGrant,
-  type OAuthFlowDeps,
-} from "./oauth.js";
+import { browserCommand, runOAuthFlow, waitForOAuthGrant, type OAuthFlowDeps } from "./oauth.js";
 
 const server = create(McpServerSchema, {
   metadata: { id: "mcp_1", slug: "github", name: "GitHub" },
@@ -33,22 +26,6 @@ function fakeClient(connectOnCall: number): { client: Stigmer; calls: () => numb
 
 const noopSleep = async (): Promise<void> => {};
 
-describe("resolveConsoleURL", () => {
-  it("prefers the STIGMER_CONSOLE_URL override", () => {
-    expect(resolveConsoleURL("cloud", { STIGMER_CONSOLE_URL: "https://console.example" } as NodeJS.ProcessEnv)).toBe(
-      "https://console.example",
-    );
-  });
-
-  it("uses the local web-console port for the local backend", () => {
-    expect(resolveConsoleURL("local", {} as NodeJS.ProcessEnv)).toBe("http://localhost:8234");
-  });
-
-  it("uses the cloud console URL for the cloud backend", () => {
-    expect(resolveConsoleURL("cloud", {} as NodeJS.ProcessEnv)).toBe(DEFAULT_CLOUD_CONSOLE_URL);
-  });
-});
-
 describe("browserCommand", () => {
   it("maps each supported platform to its opener", () => {
     expect(browserCommand("darwin", "https://x")).toEqual(["open", ["https://x"]]);

package/src/resources/connect/oauth.ts

@@ -16,11 +16,8 @@ import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/
 import { GetOAuthGrantStatusInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import type { Stigmer } from "@stigmer/sdk";
 import type { BackendType } from "../../config/config.js";
+import { resolveConsoleURL } from "../../config/index.js";
 import { UsageError } from "../../errors/index.js";
-import { WEB_CONSOLE_PORT } from "../../local/constants.js";
-
-/** Well-known URL for the Stigmer Cloud web console. */
-export const DEFAULT_CLOUD_CONSOLE_URL = "https://app.stigmer.ai";
 
 const POLL_INTERVAL_MS = 3000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000;
@@ -109,19 +106,6 @@ export async function checkOAuthGrant(client: Stigmer, mcpServerId: string, org:
   return status.connected;
 }
 
-/**
- * Resolve the web console URL:
- *   1. `STIGMER_CONSOLE_URL` (explicit override)
- *   2. local backend → `http://localhost:{WEB_CONSOLE_PORT}`
- *   3. cloud backend → {@link DEFAULT_CLOUD_CONSOLE_URL}
- */
-export function resolveConsoleURL(backendType: BackendType, env: NodeJS.ProcessEnv = process.env): string {
-  const override = env.STIGMER_CONSOLE_URL;
-  if (override !== undefined && override !== "") return override;
-  if (backendType === "local") return `http://localhost:${WEB_CONSOLE_PORT}`;
-  return DEFAULT_CLOUD_CONSOLE_URL;
-}
-
 // Probe the local web console with a short-timeout GET. Any HTTP response (even
 // an error status) means it's serving; a network/timeout failure means it isn't.
 async function probeWebConsole(url: string): Promise<boolean> {

package/src/resources/read-verbs.integration.test.ts

@@ -38,7 +38,7 @@ const knownAgent = create(AgentSchema, {
 const knownOrg = create(OrganizationSchema, {
   apiVersion: "tenancy.stigmer.ai/v1",
   kind: "Organization",
-  metadata: { name: "Acme", slug: "acme", org: "acme", id: "org_1" },
+  metadata: { name: "Acme", slug: "acme", org: "acme", id: "acme" },
 });
 
 const knownApiKey = create(ApiKeySchema, {