@stigmer/cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/commands/app-handover.d.ts.map +1 -1
  2. package/commands/app-handover.js +23 -10
  3. package/commands/app-handover.js.map +1 -1
  4. package/commands/auth/whoami.d.ts +10 -0
  5. package/commands/auth/whoami.d.ts.map +1 -1
  6. package/commands/auth/whoami.js +63 -5
  7. package/commands/auth/whoami.js.map +1 -1
  8. package/commands/docs/index.d.ts +9 -0
  9. package/commands/docs/index.d.ts.map +1 -0
  10. package/commands/docs/index.js +64 -0
  11. package/commands/docs/index.js.map +1 -0
  12. package/commands/example.d.ts +7 -0
  13. package/commands/example.d.ts.map +1 -1
  14. package/commands/example.js +11 -1
  15. package/commands/example.js.map +1 -1
  16. package/commands/help.d.ts.map +1 -1
  17. package/commands/help.js +3 -0
  18. package/commands/help.js.map +1 -1
  19. package/commands/list.d.ts.map +1 -1
  20. package/commands/list.js +13 -1
  21. package/commands/list.js.map +1 -1
  22. package/commands/mcp-server.d.ts.map +1 -1
  23. package/commands/mcp-server.js +12 -3
  24. package/commands/mcp-server.js.map +1 -1
  25. package/commands/provider-key/index.d.ts.map +1 -1
  26. package/commands/provider-key/index.js +2 -2
  27. package/commands/provider-key/index.js.map +1 -1
  28. package/commands/status.d.ts.map +1 -1
  29. package/commands/status.js +4 -3
  30. package/commands/status.js.map +1 -1
  31. package/config/index.d.ts +1 -1
  32. package/config/index.d.ts.map +1 -1
  33. package/config/index.js +1 -1
  34. package/config/index.js.map +1 -1
  35. package/config/resolve.d.ts +13 -2
  36. package/config/resolve.d.ts.map +1 -1
  37. package/config/resolve.js +24 -3
  38. package/config/resolve.js.map +1 -1
  39. package/local/runtime/node.d.ts +12 -4
  40. package/local/runtime/node.d.ts.map +1 -1
  41. package/local/runtime/node.js +73 -27
  42. package/local/runtime/node.js.map +1 -1
  43. package/local/status.d.ts.map +1 -1
  44. package/local/status.js +62 -4
  45. package/local/status.js.map +1 -1
  46. package/package.json +12 -12
  47. package/program.d.ts.map +1 -1
  48. package/program.js +2 -0
  49. package/program.js.map +1 -1
  50. package/resources/provider-key.d.ts +7 -2
  51. package/resources/provider-key.d.ts.map +1 -1
  52. package/resources/provider-key.js +18 -3
  53. package/resources/provider-key.js.map +1 -1
  54. package/resources/runs.d.ts +10 -3
  55. package/resources/runs.d.ts.map +1 -1
  56. package/resources/runs.js +22 -4
  57. package/resources/runs.js.map +1 -1
  58. package/resources/views/agent.d.ts.map +1 -1
  59. package/resources/views/agent.js +18 -2
  60. package/resources/views/agent.js.map +1 -1
  61. package/src/commands/app-handover.ts +26 -12
  62. package/src/commands/auth/whoami.ts +68 -4
  63. package/src/commands/docs/index.ts +65 -0
  64. package/src/commands/example.ts +12 -1
  65. package/src/commands/help.ts +3 -0
  66. package/src/commands/list.ts +14 -1
  67. package/src/commands/mcp-server.ts +11 -3
  68. package/src/commands/provider-key/index.ts +7 -1
  69. package/src/commands/status.ts +4 -3
  70. package/src/config/index.ts +1 -0
  71. package/src/config/resolve.ts +26 -3
  72. package/src/local/runtime/node.ts +95 -30
  73. package/src/local/status.ts +69 -4
  74. package/src/program.ts +2 -0
  75. package/src/resources/provider-key.ts +24 -3
  76. package/src/resources/runs.ts +36 -4
  77. package/src/resources/views/agent.ts +19 -2
@@ -10,6 +10,13 @@
10
10
  // <words>: <address>"), so a person, or a coding agent signing its person
11
11
  // in, learns where to ask before anything fails.
12
12
  //
13
+ // It names the server's version and edition (`Server: 0.2.0 (Cloud)`), from
14
+ // the same server-info answer, so a person, or their coding agent, can tell
15
+ // whether a feature the docs describe has reached the server they talk to.
16
+ // Beside it, `Endpoint` is the address the CLI dialled (the word `stigmer
17
+ // config backend status` uses for it), so the answer also says which server
18
+ // that is: a self-hosted one, Stigmer Cloud, or a local stack (stigmer#3369).
19
+ //
13
20
  // It names the context organization by the slug the backend answers now,
14
21
  // not the one `config context set` stored, and stores the current one when
15
22
  // the organization was renamed since.
@@ -19,12 +26,14 @@
19
26
 
20
27
  import type { IdentityAccount } from "@stigmer/apis/ai/stigmer/iam/identityaccount/v1/api_pb";
21
28
  import { IdentityAccountProvisioningMode } from "@stigmer/apis/ai/stigmer/iam/identityaccount/v1/enum_pb";
29
+ import { ServerEdition } from "@stigmer/apis/ai/stigmer/platform/v1/server_info_pb";
22
30
  import { ensureMyIdentityAccount, type Stigmer } from "@stigmer/client";
23
31
  import {
24
32
  type Config,
25
33
  ensureAuthenticated,
26
34
  load,
27
35
  resolveContextOrganization,
36
+ resolveServerAddress,
28
37
  save,
29
38
  } from "../../config/index.js";
30
39
  import { CommandResult } from "../../output/index.js";
@@ -44,6 +53,10 @@ export interface WhoamiContext {
44
53
  readonly singleOrg: boolean;
45
54
  /** Where the server says to ask for help; absent when it names none. */
46
55
  readonly help?: { readonly url: string; readonly label: string };
56
+ /** The server's version and edition; absent when the server didn't say. */
57
+ readonly server?: { readonly version: string; readonly edition: ServerEdition };
58
+ /** The address the CLI dialled; absent when unknown. */
59
+ readonly endpoint?: string;
47
60
  }
48
61
 
49
62
  /**
@@ -91,6 +104,23 @@ export function whoamiResult(
91
104
  }
92
105
  }
93
106
 
107
+ if (context.server !== undefined) {
108
+ const server = serverLine(context.server.version, context.server.edition);
109
+ if (server !== "") section.field("Server", server);
110
+ }
111
+ const endpoint = context.endpoint ?? "";
112
+ if (endpoint !== "") section.field("Endpoint", endpoint);
113
+ if (context.server !== undefined || endpoint !== "") {
114
+ result.withData({
115
+ server: {
116
+ ...(context.server !== undefined
117
+ ? { version: context.server.version, edition: EDITION_KEYS[context.server.edition] ?? "" }
118
+ : {}),
119
+ ...(endpoint !== "" ? { endpoint } : {}),
120
+ },
121
+ });
122
+ }
123
+
94
124
  if (context.help !== undefined) {
95
125
  result.hint(helpLine(context.help));
96
126
  }
@@ -98,6 +128,27 @@ export function whoamiResult(
98
128
  return result;
99
129
  }
100
130
 
131
+ /** Each edition's name as the docs say it. */
132
+ const EDITION_NAMES: Readonly<Partial<Record<ServerEdition, string>>> = {
133
+ [ServerEdition.oss]: "open source",
134
+ [ServerEdition.cloud]: "Cloud",
135
+ [ServerEdition.enterprise]: "Enterprise",
136
+ };
137
+
138
+ /** Each edition's wire name, for `-o json`. */
139
+ const EDITION_KEYS: Readonly<Partial<Record<ServerEdition, string>>> = {
140
+ [ServerEdition.oss]: "oss",
141
+ [ServerEdition.cloud]: "cloud",
142
+ [ServerEdition.enterprise]: "enterprise",
143
+ };
144
+
145
+ /** `0.2.0 (Cloud)`; either half alone when the other is unknown; "" when both are. Pure. */
146
+ export function serverLine(version: string, edition: ServerEdition): string {
147
+ const name = EDITION_NAMES[edition] ?? "";
148
+ if (version === "") return name === "" ? "" : `version unknown (${name})`;
149
+ return name === "" ? version : `${version} (${name})`;
150
+ }
151
+
101
152
  export async function runWhoami(): Promise<CommandResult> {
102
153
  const { connectBackend } = await import("../../backend.js");
103
154
  const client = connectBackend();
@@ -108,11 +159,24 @@ export async function runWhoami(): Promise<CommandResult> {
108
159
  });
109
160
  const singleOrg = await omitsOrganization(client.stigmer);
110
161
  const org = singleOrg ? { label: "", id: "" } : await liveContextOrganization(client.stigmer, client.config);
111
- // Printing never fails the command: a failed ask shows no help line.
112
- const help = await Promise.resolve()
162
+ // Printing never fails the command: a failed ask shows no help line and no server.
163
+ const info = await Promise.resolve()
113
164
  .then(() => client.serverInfo())
114
- .then((info) => info.help, () => undefined);
115
- return whoamiResult(account, { created, org: org.label, orgId: org.id, singleOrg, ...(help !== undefined ? { help } : {}) });
165
+ .then((answer) => answer, () => undefined);
166
+ const help = info?.help;
167
+ const server = info === undefined ? undefined : { version: info.version, edition: info.edition };
168
+ // The address the client dials, from the resolver it dialled by; it
169
+ // resolved once already when the client was made, so this cannot throw.
170
+ const endpoint = resolveServerAddress(client.config).address;
171
+ return whoamiResult(account, {
172
+ endpoint,
173
+ created,
174
+ org: org.label,
175
+ orgId: org.id,
176
+ singleOrg,
177
+ ...(help !== undefined ? { help } : {}),
178
+ ...(server !== undefined ? { server } : {}),
179
+ });
116
180
  }
117
181
 
118
182
  /**
@@ -0,0 +1,65 @@
1
+ // `stigmer docs search|read` — find and read Stigmer's documentation at
2
+ // stigmer.ai/docs from the terminal, so a person, or the coding agent working
3
+ // with them, answers from what the docs say today and cites the page.
4
+ //
5
+ // No backend and no sign-in: it reads the public site, so it works before
6
+ // `stigmer auth login`, for someone still deciding. The reader is the tool
7
+ // server's (`@stigmer/mcp-server/docs`, the same code its search_docs and
8
+ // read_doc tools run), imported through its own subpath so this command loads
9
+ // a few kilobytes, not the server. `read` prints the page's Markdown export
10
+ // whole, opening with its `Source:` URL; `-o json` prints `{results}` or
11
+ // `{url, markdown}`.
12
+
13
+ import type { Command } from "commander";
14
+ import { ExitCode } from "@stigmer/client/exit-codes";
15
+ import { CliExitError } from "../../errors/cli-exit-error.js";
16
+ import { UsageError } from "../../errors/usage-error.js";
17
+ import { type OutputFlags, renderValue } from "../../output/index.js";
18
+ import { addValueFlags, resultFormat } from "../shared.js";
19
+
20
+ export function registerDocs(program: Command): void {
21
+ const docs = program
22
+ .command("docs")
23
+ .description("search and read Stigmer's documentation at stigmer.ai/docs");
24
+
25
+ const search = docs
26
+ .command("search")
27
+ .description("list the documentation pages that best match some words")
28
+ .argument("<words...>", "what the question is about")
29
+ .action(async (words: string[], options: OutputFlags) => {
30
+ const { formatHits, sharedDocsReader } = await import("@stigmer/mcp-server/docs");
31
+ const query = words.join(" ");
32
+ const results = await asCliError(() => sharedDocsReader().searchDocs(query));
33
+ renderValue(formatHits(query, results), { results }, resultFormat(options));
34
+ });
35
+ addValueFlags(search);
36
+
37
+ const read = docs
38
+ .command("read")
39
+ .description("print one documentation page whole, as Markdown")
40
+ .argument("<page>", "the page's path after /docs/ (concepts/tools) or its full URL")
41
+ .action(async (page: string, options: OutputFlags) => {
42
+ const { sharedDocsReader } = await import("@stigmer/mcp-server/docs");
43
+ const { url, markdown } = await asCliError(() => sharedDocsReader().readDocPage(page));
44
+ renderValue(markdown, { url, markdown }, resultFormat(options));
45
+ });
46
+ addValueFlags(read);
47
+ }
48
+
49
+ /**
50
+ * Run a docs read, saying its failure as the CLI does: a page outside the
51
+ * docs is a usage error, a missing page not-found, an unreachable site a
52
+ * connection failure.
53
+ */
54
+ export async function asCliError<T>(read: () => Promise<T>): Promise<T> {
55
+ try {
56
+ return await read();
57
+ } catch (error) {
58
+ const kind = (error as { kind?: unknown }).kind;
59
+ const message = error instanceof Error ? error.message : String(error);
60
+ if (kind === "refused") throw new UsageError(message);
61
+ if (kind === "not-found") throw new CliExitError(message, ExitCode.NotFound, ["Find the page's path:", " stigmer docs search <words>"]);
62
+ if (kind === "unreachable") throw new CliExitError(message, ExitCode.Connection);
63
+ throw error;
64
+ }
65
+ }
@@ -121,7 +121,18 @@ export function writeSkill(skill: ExampleSkill, dir: string, force: boolean): Co
121
121
  return CommandResult.success(`Wrote the ${skill.name} skill into ${shown}`)
122
122
  .withData({ dir: shown, files: written, skill: skill.id })
123
123
  .hint(`Push it to your organization: stigmer push skill ${shown}`)
124
- .hint(`Then add it to an agent's skill_refs and apply the agent again.`);
124
+ .hint(`Then add these lines under the agent's spec: and apply it again:`)
125
+ .hint(skillRefsLines(skill.id));
126
+ }
127
+
128
+ /**
129
+ * The exact `skill_refs` lines that turn a pushed skill on for an agent, as
130
+ * its manifest carries them under `spec:` (a relative reference, so the
131
+ * manifest works in any organization). Spelled out because a bare
132
+ * "add it to skill_refs" left coding agents guessing the shape (stigmer#3233).
133
+ */
134
+ export function skillRefsLines(slug: string): string {
135
+ return `skill_refs:\n - kind: skill\n slug: ${slug}`;
125
136
  }
126
137
 
127
138
  function writeFiles(dir: string, files: readonly { name: string; text: string }[], force: boolean): string[] {
@@ -69,6 +69,7 @@ export const COMMAND_GROUPS: Readonly<Record<string, HelpGroup>> = {
69
69
  config: "Configuration",
70
70
  completion: "Configuration",
71
71
  version: "Configuration",
72
+ docs: "Configuration",
72
73
  };
73
74
 
74
75
  /** Each runnable command's examples, by path. */
@@ -102,6 +103,8 @@ export const HELP_EXAMPLES: ReadonlyMap<string, readonly HelpExample[]> = new Ma
102
103
  ["stigmer config set", [{ say: "make acme the active organization", run: "stigmer config set context.org acme" }]],
103
104
  ["stigmer connect plugin", [{ say: "list the tools the linear plugin's MCP server offers", run: "stigmer connect plugin linear" }]],
104
105
  ["stigmer delete", [{ say: "delete an agent by slug", run: "stigmer delete agent my-agent" }, { say: "delete an agent by ID", run: "stigmer delete agent agt_abc123" }]],
106
+ ["stigmer docs read", [{ say: "print a page whole, opening with its Source URL", run: "stigmer docs read concepts/runners" }]],
107
+ ["stigmer docs search", [{ say: "find the pages about moving the local server's port", run: "stigmer docs search port stigmer up" }]],
105
108
  ["stigmer down", [{ say: "stop the local stack", run: "stigmer down" }]],
106
109
  ["stigmer down server", [{ say: "stop the whole stack, as stigmer down does", run: "stigmer down server" }]],
107
110
  ["stigmer download", [{ say: "download all outputs from a run", run: "stigmer download run run_01abc123" }, { say: "download to a specific directory", run: "stigmer download run run_01abc123 --output-dir ./results/" }]],
@@ -18,6 +18,7 @@ interface ListFlags extends OutputFlags {
18
18
  verb?: string;
19
19
  label?: string[];
20
20
  session?: string;
21
+ agent?: string;
21
22
  }
22
23
 
23
24
  export function registerList(program: Command): void {
@@ -33,6 +34,7 @@ export function registerList(program: Command): void {
33
34
  [],
34
35
  )
35
36
  .option("--session <id>", "files: list one conversation's Files, what was given to it and what its turns saved (only for 'list files')")
37
+ .option("--agent <agent>", "runs: list one agent's runs, newest first across its conversations (only for 'list runs')")
36
38
  .action((type: string, options: ListFlags, command: Command) => runList(type, options, command));
37
39
  addReadFlags(list);
38
40
  }
@@ -45,6 +47,7 @@ async function runList(type: string, options: ListFlags, command: Command): Prom
45
47
  if (options.session !== undefined) {
46
48
  throw new UsageError("--session names a conversation whose Files to list; 'list types' has none");
47
49
  }
50
+ if (options.agent !== undefined) throw agentFilterRefusal(type);
48
51
  process.stdout.write(renderTypes(options.verb, readFormat(options)));
49
52
  return;
50
53
  }
@@ -69,6 +72,7 @@ async function runList(type: string, options: ListFlags, command: Command): Prom
69
72
  if (info === undefined) {
70
73
  throw new UsageError(`unknown resource type: ${type}`);
71
74
  }
75
+ if (options.agent !== undefined) throw agentFilterRefusal(type);
72
76
  if (!info.supportedVerbs.has(Verb.List)) {
73
77
  throw new UsageError(`${info.displayName} does not support 'list'`);
74
78
  }
@@ -101,6 +105,10 @@ async function runList(type: string, options: ListFlags, command: Command): Prom
101
105
  process.stdout.write(rendered);
102
106
  }
103
107
 
108
+ function agentFilterRefusal(type: string): UsageError {
109
+ return new UsageError(`--agent lists one agent's runs; 'list ${type}' takes no agent (use 'list runs --agent <agent>')`);
110
+ }
111
+
104
112
  function sessionFilterRefusal(type: string): UsageError {
105
113
  return new UsageError(`--session lists one conversation's Files; 'list ${type}' takes no conversation (use 'list files --session <id>')`);
106
114
  }
@@ -108,6 +116,8 @@ function sessionFilterRefusal(type: string): UsageError {
108
116
  // Runs bypass the registry: they're listed by their own controller. Results are
109
117
  // scoped to the resolved org context (--org flag, env, or configured context);
110
118
  // an unset cloud context resolves to "" = permission-bounded across orgs.
119
+ // `--agent` lists one agent's runs instead, newest first across its
120
+ // conversations, the agent named as `agent quality` names it.
111
121
  async function runListRuns(options: ListFlags, command: Command, labels: Record<string, string>): Promise<void> {
112
122
  const [{ connectBackend }, runs] = await Promise.all([
113
123
  import("../backend.js"),
@@ -120,7 +130,10 @@ async function runListRuns(options: ListFlags, command: Command, labels: Record<
120
130
  const limit = parseLimit(options.limit);
121
131
  const format = readFormat(options);
122
132
 
123
- const result = await runs.listAgentRuns(client.stigmer, limit, org, labels);
133
+ const result =
134
+ options.agent === undefined
135
+ ? await runs.listOrgRuns(client.stigmer, limit, org, labels)
136
+ : await runs.listRunsOfAgent(client.stigmer, limit, options.agent, org, labels);
124
137
  process.stdout.write(runs.renderRunList(result, format));
125
138
  }
126
139
 
@@ -22,6 +22,12 @@
22
22
  // backend instead (auth/token.ts, createBackendTokenSource), which refreshes the
23
23
  // sign-in and saves it as every other command does. A given key (flag or
24
24
  // environment) still wins and is never refreshed.
25
+ //
26
+ // This server runs on the person's machine, as their coding agent's child,
27
+ // so it tells the server it shares their disk (`localFiles`): run_agent may
28
+ // then hand a run the project files a call names, inside the folders the
29
+ // coding agent lists as its workspace. The server applies it to the stdio
30
+ // roster alone; its HTTP rosters never read a path.
25
31
 
26
32
  import type { Command } from "commander";
27
33
  import { type Config, activeBackend, hasSignIn } from "../config/config.js";
@@ -81,10 +87,12 @@ async function runMcpServer(flags: McpServerFlags): Promise<void> {
81
87
  // Imported lazily so `stigmer --help`/`version` never pull in the MCP stack.
82
88
  const { run, defaultConfig } = await import("@stigmer/mcp-server");
83
89
  const { createBackendTokenSource } = await import("../auth/token.js");
84
- const options =
85
- signIn === undefined
90
+ const options = {
91
+ localFiles: true,
92
+ ...(signIn === undefined
86
93
  ? {}
87
- : { getAccessToken: createBackendTokenSource(signIn.name, signIn.endpoint).getAccessToken };
94
+ : { getAccessToken: createBackendTokenSource(signIn.name, signIn.endpoint).getAccessToken }),
95
+ };
88
96
 
89
97
  const controller = new AbortController();
90
98
  const onSignal = (): void => controller.abort();
@@ -35,6 +35,7 @@ import { type Command, Option } from "commander";
35
35
  import {
36
36
  contextOrganizationLabel,
37
37
  ensureAuthenticated,
38
+ knownConsoleURL,
38
39
  resolveContextOrganization,
39
40
  resolveOrganization,
40
41
  } from "../../config/index.js";
@@ -114,7 +115,12 @@ export function registerProviderKey(program: Command): void {
114
115
  openSession(command, "writes keys"),
115
116
  import("../../output/command-result.js"),
116
117
  ]);
117
- const apiKey = await resources.readProviderKey(provider, options.keyStdin === true, await keyIo());
118
+ const apiKey = await resources.readProviderKey(
119
+ provider,
120
+ options.keyStdin === true,
121
+ await keyIo(),
122
+ knownConsoleURL(session.client.config),
123
+ );
118
124
  renderResult(
119
125
  await resources.setProviderKey(session.client.stigmer, session.org, provider, apiKey, baseUrl),
120
126
  format,
@@ -1,5 +1,6 @@
1
- // `stigmer status` — show the local stack's health (daemon, Temporal, server,
2
- // runner, web console) plus the effective LLM configuration.
1
+ // `stigmer status` — say which server the CLI uses (backend and address),
2
+ // then show the local stack's health (daemon, Temporal, server, runner, web
3
+ // console) plus the effective LLM configuration.
3
4
  //
4
5
  // Thin handler: build the structured result in the local subsystem and render
5
6
  // it. The local module loads lazily so `--help` stays fast.
@@ -11,7 +12,7 @@ import { addResultFlags, resultFormat } from "./shared.js";
11
12
  export function registerStatus(program: Command): void {
12
13
  const status = program
13
14
  .command("status")
14
- .description("show the status of the local Stigmer stack")
15
+ .description("show which server the CLI uses and the local stack's health")
15
16
  .action(async (options: OutputFlags) => {
16
17
  const { buildStatusResult } = await import("../local/status.js");
17
18
  renderResult(await buildStatusResult(), resultFormat(options));
@@ -20,6 +20,7 @@ export {
20
20
  export {
21
21
  DEFAULT_CLOUD_CONSOLE_URL,
22
22
  ensureAuthenticated,
23
+ knownConsoleURL,
23
24
  resolveConsoleURL,
24
25
  contextOrganizationId,
25
26
  contextOrganizationLabel,
@@ -37,10 +37,11 @@ export function resolveEndpoint(config: Config): string {
37
37
  * The endpoint {@link resolveEndpoint} names, with where it came from: the
38
38
  * override's name, or the active backend's kind. The backend client records
39
39
  * it when made, so a failure names the address tried and the fix that fits
40
- * its source.
40
+ * its source. `env` is the environment the override is read from; `stigmer
41
+ * status` passes the one it was given, so its tests need no process state.
41
42
  */
42
- export function resolveServerAddress(config: Config): ServerAddress {
43
- const override = process.env.STIGMER_SERVER_ADDRESS;
43
+ export function resolveServerAddress(config: Config, env: NodeJS.ProcessEnv = process.env): ServerAddress {
44
+ const override = env.STIGMER_SERVER_ADDRESS;
44
45
  if (override !== undefined && override !== "") {
45
46
  return { address: override, source: "environment" };
46
47
  }
@@ -138,6 +139,28 @@ export function resolveConsoleURL(
138
139
  return DEFAULT_CLOUD_CONSOLE_URL;
139
140
  }
140
141
 
142
+ /**
143
+ * The console's address when the CLI knows it for certain, or `undefined`:
144
+ * the `STIGMER_CONSOLE_URL` override, or Stigmer Cloud's own console for a
145
+ * `cloud` entry that talks to Stigmer Cloud's own API. Where a person is sent
146
+ * to a page, a guess must not stand in for it: a hosted deployment registered
147
+ * by its API address (an address entry, or a `cloud` entry given another
148
+ * endpoint) can serve its console from another origin, so the rule
149
+ * {@link resolveConsoleURL} applies there would name the wrong host.
150
+ */
151
+ export function knownConsoleURL(
152
+ config: Config,
153
+ env: NodeJS.ProcessEnv = process.env,
154
+ ): string | undefined {
155
+ const override = env.STIGMER_CONSOLE_URL;
156
+ if (override !== undefined && override !== "") return override;
157
+ const { entry } = activeBackend(config);
158
+ if (entry?.type !== "cloud") return undefined;
159
+ const serverOverride = env.STIGMER_SERVER_ADDRESS ?? "";
160
+ const endpoint = serverOverride !== "" ? serverOverride : (entry.endpoint ?? "");
161
+ return endpoint === "" || endpoint === DEFAULT_CLOUD_ENDPOINT ? DEFAULT_CLOUD_CONSOLE_URL : undefined;
162
+ }
163
+
141
164
  /**
142
165
  * The configured organization, with the active entry's org_id fallback.
143
166
  * Reports only what is explicitly set (no implicit local default) so
@@ -2,32 +2,38 @@
2
2
  // subprocesses.
3
3
  //
4
4
  // We reuse the very Node that is running the CLI (process.execPath). The CLI is
5
- // itself an npm package with `engines: node >= 22.13`, so a suitable Node is
6
- // always present by construction — there is deliberately no hermetic Node
7
- // download (keep the base install lean: nothing to acquire that the host
8
- // already guarantees). This is exactly what the conformance harness does
9
- // (`spawn(process.execPath, ...)`). An explicit STIGMER_NODE_BIN override is
10
- // honored and capability-checked for advanced/multi-runtime setups.
5
+ // itself an npm package whose `engines` is the server's range (Node 22 from
6
+ // 22.19, or 24 and later), so npm warns at install on a Node that cannot run
7
+ // the server — there is deliberately no hermetic Node download (keep the base
8
+ // install lean: nothing to acquire that the host already provides). This is
9
+ // exactly what the conformance harness does (`spawn(process.execPath, ...)`).
10
+ // An explicit STIGMER_NODE_BIN override is honored and checked the same way
11
+ // for advanced/multi-runtime setups.
11
12
  //
12
- // The gates are CAPABILITY probes, not version checks. Two probes, because the
13
- // two children need different sqlite capabilities:
13
+ // The runner's gate is a CAPABILITY probe; the server's is its declared
14
+ // version range, then a capability probe:
14
15
  //
15
16
  // - The RUNNER's durable local checkpointer imports Node's built-in
16
17
  // `node:sqlite`, available unflagged from 22.13 in the 22.x line and only
17
18
  // from 23.4 in the 23.x line — a gap (23.0–23.3) that a previous
18
19
  // version-table gate here missed, letting those Nodes through to crash at
19
- // runner boot with a raw ERR_UNKNOWN_BUILTIN_MODULE.
20
- // - The SERVER additionally needs `node:sqlite` compiled WITH FTS5 (its
21
- // search index; migration v3 creates an fts5 virtual table at boot). Node
22
- // 23.4 PROVIDES node:sqlite but its sqlite build LACKS FTS5 — the reason
23
- // the module-presence probe alone is insufficient
24
- // for the server. Probing "can this binary create an fts5 table?" directly
25
- // cannot drift; the version floors survive only in the error messages,
26
- // where staleness is harmless.
20
+ // runner boot with a raw ERR_UNKNOWN_BUILTIN_MODULE. Probing the module
21
+ // cannot drift; the runner's floors survive only in its error copy.
22
+ // - The SERVER declares the Nodes it runs on in its own `engines`
23
+ // (`backend/services/stigmer-server/package.json`), above the runner's:
24
+ // its outbound dialer loads undici, whose floor is 22.19, and the server
25
+ // supports 22.x and 24+. undici's need has no capability this resolver
26
+ // could probe without loading undici, so here the gate IS a version check,
27
+ // against `SERVER_NODE_LINES`, which a test holds equal to the server's
28
+ // declared range and to this package's own `engines`, so the two cannot
29
+ // drift apart. The server ALSO needs `node:sqlite` compiled WITH FTS5 (its
30
+ // search index; migration v3 creates an fts5 virtual table at boot), and
31
+ // that stays a capability probe: a Node in range whose sqlite build lacks
32
+ // FTS5 is refused by what it cannot do.
27
33
  //
28
34
  // The runner performs the module-presence probe on its own boot (see
29
35
  // backend/services/runner/src/preflight.ts); the server fails at migration
30
- // time. Both probes here exist to fail at resolve time with CLI-appropriate
36
+ // time. These gates exist to fail at resolve time with CLI-appropriate
31
37
  // guidance instead of a subprocess crash.
32
38
 
33
39
  import { execFileSync } from "node:child_process";
@@ -82,24 +88,83 @@ export function resolveNode(): string {
82
88
  return bin;
83
89
  }
84
90
 
91
+ /**
92
+ * The Node lines the server runs on, lowest accepted version first: each
93
+ * entry accepts its major from `minor`, and the last accepts every later
94
+ * major too. The one source for the server's floor in the CLI: the range
95
+ * string, the sentence and the check all derive from it, and a test holds
96
+ * the range equal to the server's `engines.node` and this package's own.
97
+ */
98
+ const SERVER_NODE_LINES = [
99
+ { major: 22, minor: 19 },
100
+ { major: 24, minor: 0 },
101
+ ] as const;
102
+
103
+ /** Whether the line at `index` is the last, which accepts every later major too. */
104
+ const isLastLine = (index: number): boolean => index === SERVER_NODE_LINES.length - 1;
105
+
106
+ /** The server's supported Node range as npm's `engines` writes it: `>=22.19.0 <23 || >=24`. */
107
+ export const SERVER_NODE_RANGE = SERVER_NODE_LINES.map(({ major, minor }, i) =>
108
+ isLastLine(i)
109
+ ? minor === 0
110
+ ? `>=${major}`
111
+ : `>=${major}.${minor}.0`
112
+ : `>=${major}.${minor}.0 <${major + 1}`,
113
+ ).join(" || ");
114
+
115
+ /** The same range in words: "Node.js 22 (22.19 or newer) or Node.js 24 or newer". */
116
+ export const SERVER_NODE_FLOOR = SERVER_NODE_LINES.map(({ major, minor }, i) =>
117
+ isLastLine(i)
118
+ ? minor === 0
119
+ ? `Node.js ${major} or newer`
120
+ : `Node.js ${major}.${minor} or newer`
121
+ : `Node.js ${major} (${major}.${minor} or newer)`,
122
+ ).join(" or ");
123
+
124
+ /** Whether `version` (`v22.19.0` or `22.19.0`) is on a line the server runs on. */
125
+ export function serverRunsOn(version: string): boolean {
126
+ const [major = Number.NaN, minor = Number.NaN] = version.replace(/^v/, "").split(".").map(Number);
127
+ return SERVER_NODE_LINES.some(
128
+ (line, i) => (major === line.major && minor >= line.minor) || (isLastLine(i) && major > line.major),
129
+ );
130
+ }
131
+
85
132
  /**
86
133
  * Resolve the Node binary to launch the TS server with. Same
87
- * STIGMER_NODE_BIN/execPath resolution as {@link resolveNode}, but probes for
88
- * `node:sqlite` WITH FTS5 — the server's search index needs it and some Node
89
- * builds (e.g. 23.4) ship node:sqlite without it. Runs on server-launch paths
90
- * only (ensureServer).
134
+ * STIGMER_NODE_BIN/execPath resolution as {@link resolveNode}, but checks
135
+ * the binary's version against the server's supported lines first (a Node
136
+ * outside them is refused naming the version to install), then probes for
137
+ * `node:sqlite` WITH FTS5 — the server's search index needs it, and a Node
138
+ * build can ship node:sqlite without it. Runs on server-launch paths only
139
+ * (ensureServer).
91
140
  */
92
141
  export function resolveServerNode(): string {
93
142
  const bin = nodeCandidate();
143
+ const version = probeNodeVersion(bin);
144
+ if (version === null) {
145
+ throw new CliExitError(
146
+ `could not run ${bin} to verify the stigmer server's Node requirements`,
147
+ ExitCode.General,
148
+ [`Ensure ${bin} is a working ${SERVER_NODE_FLOOR} runtime.`],
149
+ );
150
+ }
151
+ if (!serverRunsOn(version)) {
152
+ throw new CliExitError(
153
+ `Node at ${bin} (${version}) cannot run the stigmer server: it needs ${SERVER_NODE_FLOOR}`,
154
+ ExitCode.General,
155
+ [
156
+ "These are the Node lines the server is built and tested for; on 22.x its network client needs 22.19 or newer.",
157
+ `Install ${SERVER_NODE_FLOOR}, or point STIGMER_NODE_BIN at one.`,
158
+ ],
159
+ );
160
+ }
94
161
  assertCapability(bin, NODE_SQLITE_FTS5_PROBE, {
95
162
  subject: "the stigmer server",
96
163
  capability: "the built-in node:sqlite module with FTS5",
97
- floor: "Node 22.13+ in the 22.x line (23.x builds lack FTS5)",
164
+ floor: SERVER_NODE_FLOOR,
98
165
  detail: [
99
- "The server's search index requires node:sqlite compiled with FTS5.",
100
- "The 22.x line from 22.13 is known-good; 23.x builds ship node:sqlite",
101
- "WITHOUT FTS5 and cannot run the server. Newer majors work if their",
102
- "sqlite build includes FTS5 — this probe is the authority.",
166
+ "The server's search index requires node:sqlite compiled with FTS5,",
167
+ "and this Node's sqlite build lacks it.",
103
168
  ],
104
169
  });
105
170
  return bin;
@@ -112,7 +177,7 @@ function nodeCandidate(): string {
112
177
  : process.execPath;
113
178
  }
114
179
 
115
- /** Best-effort `--version` for error messages only; null when the spawn fails. */
180
+ /** The binary's `--version` (`v22.19.0`); null when the spawn fails. */
116
181
  function probeNodeVersion(bin: string): string | null {
117
182
  try {
118
183
  const out = execFileSync(bin, ["--version"], {
@@ -130,9 +195,9 @@ interface CapabilityErrorCopy {
130
195
  subject: string;
131
196
  /** The missing capability, in user terms. */
132
197
  capability: string;
133
- /** The known-good version floor, per probe — the two probes differ (the
134
- * runner accepts 23.4+; the server does not). Error copy only; the probe
135
- * is the authority. */
198
+ /** The known-good version floor, per probe — the two differ (the runner
199
+ * accepts 23.4+; the server does not). Error copy only; the probe is the
200
+ * authority for the capability. */
136
201
  floor: string;
137
202
  /** Guidance lines explaining the requirement. */
138
203
  detail: string[];