@stigmer/cli 0.1.3 → 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 (270) hide show
  1. package/auth/browser.d.ts +7 -0
  2. package/auth/browser.d.ts.map +1 -0
  3. package/auth/browser.js +49 -0
  4. package/auth/browser.js.map +1 -0
  5. package/auth/callback-server.d.ts +8 -3
  6. package/auth/callback-server.d.ts.map +1 -1
  7. package/auth/callback-server.js +53 -19
  8. package/auth/callback-server.js.map +1 -1
  9. package/auth/device.d.ts +23 -0
  10. package/auth/device.d.ts.map +1 -0
  11. package/auth/device.js +119 -0
  12. package/auth/device.js.map +1 -0
  13. package/auth/index.d.ts +4 -3
  14. package/auth/index.d.ts.map +1 -1
  15. package/auth/index.js +4 -3
  16. package/auth/index.js.map +1 -1
  17. package/auth/login.d.ts +49 -1
  18. package/auth/login.d.ts.map +1 -1
  19. package/auth/login.js +161 -51
  20. package/auth/login.js.map +1 -1
  21. package/auth/oidc.d.ts +67 -0
  22. package/auth/oidc.d.ts.map +1 -0
  23. package/auth/oidc.js +213 -0
  24. package/auth/oidc.js.map +1 -0
  25. package/auth/token.d.ts +17 -23
  26. package/auth/token.d.ts.map +1 -1
  27. package/auth/token.js +51 -60
  28. package/auth/token.js.map +1 -1
  29. package/client/client.d.ts.map +1 -1
  30. package/client/client.js +4 -1
  31. package/client/client.js.map +1 -1
  32. package/client/current-organization.d.ts +5 -0
  33. package/client/current-organization.d.ts.map +1 -0
  34. package/client/current-organization.js +15 -0
  35. package/client/current-organization.js.map +1 -0
  36. package/commands/apikey/index.d.ts +16 -1
  37. package/commands/apikey/index.d.ts.map +1 -1
  38. package/commands/apikey/index.js +81 -0
  39. package/commands/apikey/index.js.map +1 -1
  40. package/commands/app-handover.d.ts +17 -0
  41. package/commands/app-handover.d.ts.map +1 -0
  42. package/commands/app-handover.js +168 -0
  43. package/commands/app-handover.js.map +1 -0
  44. package/commands/auth/index.d.ts.map +1 -1
  45. package/commands/auth/index.js +15 -9
  46. package/commands/auth/index.js.map +1 -1
  47. package/commands/auth/login.d.ts +7 -2
  48. package/commands/auth/login.d.ts.map +1 -1
  49. package/commands/auth/login.js +26 -23
  50. package/commands/auth/login.js.map +1 -1
  51. package/commands/auth/whoami.d.ts +15 -0
  52. package/commands/auth/whoami.d.ts.map +1 -1
  53. package/commands/auth/whoami.js +72 -2
  54. package/commands/auth/whoami.js.map +1 -1
  55. package/commands/coding-agent.d.ts +5 -0
  56. package/commands/coding-agent.d.ts.map +1 -0
  57. package/commands/coding-agent.js +30 -0
  58. package/commands/coding-agent.js.map +1 -0
  59. package/commands/config/backend.js +20 -6
  60. package/commands/config/backend.js.map +1 -1
  61. package/commands/docs/index.d.ts +9 -0
  62. package/commands/docs/index.d.ts.map +1 -0
  63. package/commands/docs/index.js +64 -0
  64. package/commands/docs/index.js.map +1 -0
  65. package/commands/embedding.d.ts +28 -0
  66. package/commands/embedding.d.ts.map +1 -0
  67. package/commands/embedding.js +170 -0
  68. package/commands/embedding.js.map +1 -0
  69. package/commands/example.d.ts +20 -0
  70. package/commands/example.d.ts.map +1 -0
  71. package/commands/example.js +136 -0
  72. package/commands/example.js.map +1 -0
  73. package/commands/help.d.ts.map +1 -1
  74. package/commands/help.js +19 -3
  75. package/commands/help.js.map +1 -1
  76. package/commands/list.d.ts.map +1 -1
  77. package/commands/list.js +13 -1
  78. package/commands/list.js.map +1 -1
  79. package/commands/load-test/burst.d.ts +64 -0
  80. package/commands/load-test/burst.d.ts.map +1 -0
  81. package/commands/load-test/burst.js +202 -0
  82. package/commands/load-test/burst.js.map +1 -0
  83. package/commands/load-test/index.d.ts +37 -0
  84. package/commands/load-test/index.d.ts.map +1 -0
  85. package/commands/load-test/index.js +154 -0
  86. package/commands/load-test/index.js.map +1 -0
  87. package/commands/load-test/report.d.ts +98 -0
  88. package/commands/load-test/report.d.ts.map +1 -0
  89. package/commands/load-test/report.js +210 -0
  90. package/commands/load-test/report.js.map +1 -0
  91. package/commands/mcp-server.d.ts +3 -3
  92. package/commands/mcp-server.d.ts.map +1 -1
  93. package/commands/mcp-server.js +16 -7
  94. package/commands/mcp-server.js.map +1 -1
  95. package/commands/provider-key/index.d.ts.map +1 -1
  96. package/commands/provider-key/index.js +2 -2
  97. package/commands/provider-key/index.js.map +1 -1
  98. package/commands/setup.d.ts +17 -0
  99. package/commands/setup.d.ts.map +1 -1
  100. package/commands/setup.js +71 -1
  101. package/commands/setup.js.map +1 -1
  102. package/commands/status.d.ts.map +1 -1
  103. package/commands/status.js +4 -3
  104. package/commands/status.js.map +1 -1
  105. package/commands/up.d.ts.map +1 -1
  106. package/commands/up.js +67 -9
  107. package/commands/up.js.map +1 -1
  108. package/commands/usage.d.ts +15 -0
  109. package/commands/usage.d.ts.map +1 -1
  110. package/commands/usage.js +52 -2
  111. package/commands/usage.js.map +1 -1
  112. package/config/config.d.ts +14 -7
  113. package/config/config.d.ts.map +1 -1
  114. package/config/config.js +5 -1
  115. package/config/config.js.map +1 -1
  116. package/config/index.d.ts +2 -2
  117. package/config/index.d.ts.map +1 -1
  118. package/config/index.js +2 -2
  119. package/config/index.js.map +1 -1
  120. package/config/resolve.d.ts +14 -3
  121. package/config/resolve.d.ts.map +1 -1
  122. package/config/resolve.js +30 -6
  123. package/config/resolve.js.map +1 -1
  124. package/errors/classify.d.ts.map +1 -1
  125. package/errors/classify.js +10 -1
  126. package/errors/classify.js.map +1 -1
  127. package/errors/cli-exit-error.d.ts +3 -1
  128. package/errors/cli-exit-error.d.ts.map +1 -1
  129. package/errors/cli-exit-error.js +6 -2
  130. package/errors/cli-exit-error.js.map +1 -1
  131. package/errors/handle.d.ts +32 -5
  132. package/errors/handle.d.ts.map +1 -1
  133. package/errors/handle.js +67 -8
  134. package/errors/handle.js.map +1 -1
  135. package/local/daemon/components.d.ts +28 -1
  136. package/local/daemon/components.d.ts.map +1 -1
  137. package/local/daemon/components.js +64 -2
  138. package/local/daemon/components.js.map +1 -1
  139. package/local/daemon/host.d.ts.map +1 -1
  140. package/local/daemon/host.js +6 -2
  141. package/local/daemon/host.js.map +1 -1
  142. package/local/daemon/launch.d.ts +12 -4
  143. package/local/daemon/launch.d.ts.map +1 -1
  144. package/local/daemon/launch.js +49 -16
  145. package/local/daemon/launch.js.map +1 -1
  146. package/local/daemon/types.d.ts +9 -1
  147. package/local/daemon/types.d.ts.map +1 -1
  148. package/local/key-check.d.ts +20 -0
  149. package/local/key-check.d.ts.map +1 -0
  150. package/local/key-check.js +45 -0
  151. package/local/key-check.js.map +1 -0
  152. package/local/model-key-step.d.ts +63 -0
  153. package/local/model-key-step.d.ts.map +1 -0
  154. package/local/model-key-step.js +133 -0
  155. package/local/model-key-step.js.map +1 -0
  156. package/local/runtime/node.d.ts +12 -4
  157. package/local/runtime/node.d.ts.map +1 -1
  158. package/local/runtime/node.js +73 -27
  159. package/local/runtime/node.js.map +1 -1
  160. package/local/setup/prompt.d.ts.map +1 -1
  161. package/local/setup/prompt.js +22 -18
  162. package/local/setup/prompt.js.map +1 -1
  163. package/local/setup/wizard.d.ts +10 -0
  164. package/local/setup/wizard.d.ts.map +1 -1
  165. package/local/setup/wizard.js +40 -17
  166. package/local/setup/wizard.js.map +1 -1
  167. package/local/state/lock.d.ts.map +1 -1
  168. package/local/state/lock.js +123 -36
  169. package/local/state/lock.js.map +1 -1
  170. package/local/state/pidfile.d.ts +4 -0
  171. package/local/state/pidfile.d.ts.map +1 -1
  172. package/local/state/pidfile.js +12 -3
  173. package/local/state/pidfile.js.map +1 -1
  174. package/local/status.d.ts.map +1 -1
  175. package/local/status.js +62 -4
  176. package/local/status.js.map +1 -1
  177. package/package.json +13 -10
  178. package/program.d.ts.map +1 -1
  179. package/program.js +12 -0
  180. package/program.js.map +1 -1
  181. package/resources/get.js +1 -1
  182. package/resources/get.js.map +1 -1
  183. package/resources/provider-key.d.ts +7 -2
  184. package/resources/provider-key.d.ts.map +1 -1
  185. package/resources/provider-key.js +18 -3
  186. package/resources/provider-key.js.map +1 -1
  187. package/resources/run/stream.d.ts.map +1 -1
  188. package/resources/run/stream.js +2 -1
  189. package/resources/run/stream.js.map +1 -1
  190. package/resources/runs.d.ts +10 -3
  191. package/resources/runs.d.ts.map +1 -1
  192. package/resources/runs.js +22 -4
  193. package/resources/runs.js.map +1 -1
  194. package/resources/stream/render-plaintext.d.ts +3 -0
  195. package/resources/stream/render-plaintext.d.ts.map +1 -1
  196. package/resources/stream/render-plaintext.js +20 -2
  197. package/resources/stream/render-plaintext.js.map +1 -1
  198. package/resources/usage.d.ts +8 -0
  199. package/resources/usage.d.ts.map +1 -1
  200. package/resources/usage.js +37 -0
  201. package/resources/usage.js.map +1 -1
  202. package/resources/views/agent.d.ts.map +1 -1
  203. package/resources/views/agent.js +18 -2
  204. package/resources/views/agent.js.map +1 -1
  205. package/runtime.d.ts +9 -0
  206. package/runtime.d.ts.map +1 -1
  207. package/runtime.js +12 -1
  208. package/runtime.js.map +1 -1
  209. package/src/auth/browser.ts +57 -0
  210. package/src/auth/callback-server.ts +58 -22
  211. package/src/auth/device.ts +151 -0
  212. package/src/auth/index.ts +4 -3
  213. package/src/auth/login.ts +243 -67
  214. package/src/auth/oidc.ts +270 -0
  215. package/src/auth/token.ts +53 -90
  216. package/src/client/client.ts +4 -1
  217. package/src/client/current-organization.ts +27 -0
  218. package/src/commands/apikey/index.ts +85 -0
  219. package/src/commands/app-handover.ts +202 -0
  220. package/src/commands/auth/index.ts +16 -10
  221. package/src/commands/auth/login.ts +30 -23
  222. package/src/commands/auth/whoami.ts +80 -1
  223. package/src/commands/coding-agent.ts +33 -0
  224. package/src/commands/config/backend.ts +20 -6
  225. package/src/commands/docs/index.ts +65 -0
  226. package/src/commands/embedding.ts +209 -0
  227. package/src/commands/example.ts +157 -0
  228. package/src/commands/help.ts +19 -3
  229. package/src/commands/list.ts +14 -1
  230. package/src/commands/load-test/burst.ts +291 -0
  231. package/src/commands/load-test/index.ts +183 -0
  232. package/src/commands/load-test/report.ts +302 -0
  233. package/src/commands/mcp-server.ts +16 -8
  234. package/src/commands/provider-key/index.ts +7 -1
  235. package/src/commands/setup.ts +76 -2
  236. package/src/commands/status.ts +4 -3
  237. package/src/commands/up.ts +76 -10
  238. package/src/commands/usage.ts +55 -2
  239. package/src/config/config.ts +18 -8
  240. package/src/config/index.ts +2 -0
  241. package/src/config/resolve.ts +31 -6
  242. package/src/errors/classify.ts +10 -1
  243. package/src/errors/cli-exit-error.ts +6 -2
  244. package/src/errors/handle.ts +74 -8
  245. package/src/local/daemon/components.ts +66 -2
  246. package/src/local/daemon/host.ts +6 -2
  247. package/src/local/daemon/launch.ts +51 -16
  248. package/src/local/daemon/types.ts +9 -1
  249. package/src/local/key-check.ts +61 -0
  250. package/src/local/model-key-step.ts +164 -0
  251. package/src/local/runtime/node.ts +95 -30
  252. package/src/local/setup/prompt.ts +22 -18
  253. package/src/local/setup/wizard.ts +45 -18
  254. package/src/local/state/lock.ts +116 -35
  255. package/src/local/state/pidfile.ts +14 -3
  256. package/src/local/status.ts +69 -4
  257. package/src/program.ts +12 -0
  258. package/src/resources/get.ts +1 -1
  259. package/src/resources/provider-key.ts +24 -3
  260. package/src/resources/run/stream.ts +2 -1
  261. package/src/resources/runs.ts +36 -4
  262. package/src/resources/stream/render-plaintext.ts +20 -2
  263. package/src/resources/usage.ts +42 -0
  264. package/src/resources/views/agent.ts +19 -2
  265. package/src/runtime.ts +17 -1
  266. package/auth/auth0.d.ts +0 -19
  267. package/auth/auth0.d.ts.map +0 -1
  268. package/auth/auth0.js +0 -39
  269. package/auth/auth0.js.map +0 -1
  270. package/src/auth/auth0.ts +0 -43
@@ -1,12 +1,14 @@
1
- // `stigmer auth login|logout|whoami` — manage Stigmer Cloud authentication.
1
+ // `stigmer auth login|logout|whoami` — sign in to the server the CLI points at.
2
2
  //
3
- // login is interactive (browser PKCE); all three honor the standard
3
+ // login signs in wherever the active backend's server says (its announced
4
+ // native client): through the browser, or with `--device`, a code typed on
5
+ // any device; all three honor the standard
4
6
  // mutating-output flags, login's result printed once the browser returns. login and whoami both end in the SDK's
5
7
  // ensureMyIdentityAccount (login.ts, whoami.ts): the first-sign-in flow the
6
8
  // console runs, so the CLI provisions an account exactly as the console does.
7
9
 
8
10
  import type { Command } from "commander";
9
- import { activeBackend, load, save } from "../../config/index.js";
11
+ import { activeBackend, hasSignIn, load, save } from "../../config/index.js";
10
12
  import {
11
13
  CommandResult,
12
14
  type OutputFlags,
@@ -17,21 +19,23 @@ import { addResultFlags, resultFormat } from "../shared.js";
17
19
  export function registerAuth(program: Command): void {
18
20
  const auth = program
19
21
  .command("auth")
20
- .description("manage authentication with Stigmer Cloud");
22
+ .description("sign in to the server the CLI points at");
21
23
 
22
24
  const login = auth
23
25
  .command("login")
24
- .description("log in to Stigmer Cloud via browser (PKCE OAuth)")
25
- .action(async (options: OutputFlags) => {
26
+ .description("sign in to the active backend's server, in your browser or with a code")
27
+ .option("--device", "sign in with a code typed on any device (where no browser opens here)")
28
+ .option("--trust-provider", "sign in even though the server's sign-in provider is on another site")
29
+ .action(async (options: OutputFlags & { device?: boolean; trustProvider?: boolean }) => {
26
30
  const format = resultFormat(options);
27
31
  const { runLogin } = await import("./login.js");
28
- renderResult(await runLogin(), format);
32
+ renderResult(await runLogin({ device: options.device, trustProvider: options.trustProvider }), format);
29
33
  });
30
34
  addResultFlags(login);
31
35
 
32
36
  const logout = auth
33
37
  .command("logout")
34
- .description("clear the stored authentication token")
38
+ .description("clear the stored sign-in (or, with none, a self-hosted backend's API key)")
35
39
  .action((options: OutputFlags) => {
36
40
  renderResult(runLogout(), resultFormat(options));
37
41
  });
@@ -50,7 +54,7 @@ export function registerAuth(program: Command): void {
50
54
  function runLogout(): CommandResult {
51
55
  const config = load();
52
56
  const { name, entry } = activeBackend(config);
53
- if (entry?.type === "selfhost") {
57
+ if (entry?.type === "selfhost" && !hasSignIn(entry)) {
54
58
  if (entry.api_key === undefined) {
55
59
  return CommandResult.warning("No API key stored for this backend");
56
60
  }
@@ -71,8 +75,10 @@ function runLogout(): CommandResult {
71
75
  entry.token = undefined;
72
76
  entry.refresh_token = undefined;
73
77
  entry.token_expiry = undefined;
78
+ entry.oidc_issuer = undefined;
79
+ entry.oidc_client_id = undefined;
74
80
  save(config);
75
- return CommandResult.success("Logged out from Stigmer Cloud").hint(
81
+ return CommandResult.success(`Logged out from backend "${name}"`).hint(
76
82
  "Run 'stigmer auth login' to authenticate again.",
77
83
  );
78
84
  }
@@ -1,10 +1,11 @@
1
- // `stigmer auth login` — the browser PKCE flow, then the account.
1
+ // `stigmer auth login` — sign in where the server says, then the account.
2
2
  //
3
- // The auth module's login() persists the tokens and switches the backend to
4
- // cloud. This command then runs the SDK's ensureMyIdentityAccount — the
5
- // console's first-sign-in flow — so a person who signs in
6
- // from the CLI alone is provisioned, not left for the server's authorizer
7
- // to lock out as an unknown principal.
3
+ // The auth module's login() signs in through the server's announced native
4
+ // client, persists the tokens into the backend's entry and makes it active.
5
+ // This command then runs the SDK's ensureMyIdentityAccount — the console's
6
+ // first-sign-in flow — so a person who signs in from the CLI alone is
7
+ // provisioned, not left for the server's authorizer to lock out as an unknown
8
+ // principal.
8
9
  //
9
10
  // The order matters for the result: the tokens are already saved when the
10
11
  // account step runs, so its failure is a WARNING that says the login stood
@@ -12,6 +13,8 @@
12
13
  // sends the person back to the browser.
13
14
 
14
15
  import { ensureMyIdentityAccount } from "@stigmer/client";
16
+ import type { LoginOptions, LoginOutcome } from "../../auth/index.js";
17
+ import { DEFAULT_CLOUD_ENDPOINT } from "../../config/resolve.js";
15
18
  import { classify } from "../../errors/index.js";
16
19
  import { CommandResult } from "../../output/index.js";
17
20
 
@@ -20,26 +23,30 @@ export type AccountSetup =
20
23
  | { readonly status: "ensured"; readonly created: boolean }
21
24
  | { readonly status: "failed"; readonly message: string };
22
25
 
23
- const CLOUD_HINTS = [
24
- "Run commands against the cloud backend, e.g.:",
25
- " stigmer list agents",
26
- ];
26
+ /** Where the sign-in landed, as the result names it. */
27
+ export type SignedIn = Pick<LoginOutcome, "backendName" | "type" | "address">;
28
+
29
+ /** "Stigmer Cloud" for Cloud's own address, else the server's host. */
30
+ export function serverLabel(signedIn: SignedIn): string {
31
+ if (signedIn.type === "cloud" && signedIn.address === DEFAULT_CLOUD_ENDPOINT) return "Stigmer Cloud";
32
+ return signedIn.address.replace(/:443$/, "");
33
+ }
27
34
 
28
35
  /** Render the login outcome. Pure: the command layer supplies `setup`. */
29
- export function loginResult(setup: AccountSetup): CommandResult {
36
+ export function loginResult(signedIn: SignedIn, setup: AccountSetup): CommandResult {
37
+ const label = serverLabel(signedIn);
30
38
  switch (setup.status) {
31
- case "ensured": {
32
- const result = CommandResult.success(
39
+ case "ensured":
40
+ return CommandResult.success(
33
41
  setup.created
34
- ? "Authenticated with Stigmer Cloud — your account was created on this first sign-in"
35
- : "Authenticated with Stigmer Cloud",
36
- );
37
- for (const hint of CLOUD_HINTS) result.hint(hint);
38
- return result;
39
- }
42
+ ? `Authenticated with ${label} — your account was created on this first sign-in`
43
+ : `Authenticated with ${label}`,
44
+ )
45
+ .hint(`Run commands against backend "${signedIn.backendName}", e.g.:`)
46
+ .hint(" stigmer list agents");
40
47
  case "failed":
41
48
  return CommandResult.warning(
42
- `Authenticated with Stigmer Cloud, but your account could not be set up: ${setup.message}`,
49
+ `Authenticated with ${label}, but your account could not be set up: ${setup.message}`,
43
50
  ).hint("Run 'stigmer auth whoami' to finish setting up your account.");
44
51
  default: {
45
52
  const _exhaustive: never = setup;
@@ -48,10 +55,10 @@ export function loginResult(setup: AccountSetup): CommandResult {
48
55
  }
49
56
  }
50
57
 
51
- export async function runLogin(): Promise<CommandResult> {
58
+ export async function runLogin(options: LoginOptions = {}): Promise<CommandResult> {
52
59
  const { login } = await import("../../auth/index.js");
53
- await login();
54
- return loginResult(await ensureAccount());
60
+ const outcome = await login(options);
61
+ return loginResult(outcome, await ensureAccount());
55
62
  }
56
63
 
57
64
  // The tokens are on disk by now; connectBackend() reads them fresh.
@@ -6,6 +6,17 @@
6
6
  // who only ever uses the CLI is never left without an account. The result
7
7
  // says when THIS call created it — a first sign-in is visible, never silent.
8
8
  //
9
+ // When the server names a place to ask for help, it says so last ("Stuck?
10
+ // <words>: <address>"), so a person, or a coding agent signing its person
11
+ // in, learns where to ask before anything fails.
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
+ //
9
20
  // It names the context organization by the slug the backend answers now,
10
21
  // not the one `config context set` stored, and stores the current one when
11
22
  // the organization was renamed since.
@@ -15,15 +26,18 @@
15
26
 
16
27
  import type { IdentityAccount } from "@stigmer/apis/ai/stigmer/iam/identityaccount/v1/api_pb";
17
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";
18
30
  import { ensureMyIdentityAccount, type Stigmer } from "@stigmer/client";
19
31
  import {
20
32
  type Config,
21
33
  ensureAuthenticated,
22
34
  load,
23
35
  resolveContextOrganization,
36
+ resolveServerAddress,
24
37
  save,
25
38
  } from "../../config/index.js";
26
39
  import { CommandResult } from "../../output/index.js";
40
+ import { helpLine } from "../../errors/handle.js";
27
41
  import { organizationNamed, type OrganizationNames } from "../../client/organizations.js";
28
42
  import { omitsOrganization } from "../../client/single-org.js";
29
43
 
@@ -37,6 +51,12 @@ export interface WhoamiContext {
37
51
  readonly orgId?: string;
38
52
  /** The server holds one organization and fills it, so the CLI never names one. */
39
53
  readonly singleOrg: boolean;
54
+ /** Where the server says to ask for help; absent when it names none. */
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;
40
60
  }
41
61
 
42
62
  /**
@@ -84,9 +104,51 @@ export function whoamiResult(
84
104
  }
85
105
  }
86
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
+
124
+ if (context.help !== undefined) {
125
+ result.hint(helpLine(context.help));
126
+ }
127
+
87
128
  return result;
88
129
  }
89
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
+
90
152
  export async function runWhoami(): Promise<CommandResult> {
91
153
  const { connectBackend } = await import("../../backend.js");
92
154
  const client = connectBackend();
@@ -97,7 +159,24 @@ export async function runWhoami(): Promise<CommandResult> {
97
159
  });
98
160
  const singleOrg = await omitsOrganization(client.stigmer);
99
161
  const org = singleOrg ? { label: "", id: "" } : await liveContextOrganization(client.stigmer, client.config);
100
- return whoamiResult(account, { created, org: org.label, orgId: org.id, singleOrg });
162
+ // Printing never fails the command: a failed ask shows no help line and no server.
163
+ const info = await Promise.resolve()
164
+ .then(() => client.serverInfo())
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
+ });
101
180
  }
102
181
 
103
182
  /**
@@ -0,0 +1,33 @@
1
+ // `stigmer coding-agent` — the guide a coding agent follows to set Stigmer up
2
+ // for the project it is in.
3
+ //
4
+ // The door for people who work in Claude Code, Codex or Cursor: they paste one
5
+ // prompt that installs this CLI and runs this command, and their coding agent
6
+ // follows what it prints, from signing in to the agent's chat in their own
7
+ // app. The text is the skill of Stigmer's plugin for coding agents
8
+ // (`@stigmer/coding-agent-plugin`), a dependency released with this CLI, so
9
+ // the guide a person's coding agent reads always names the commands and flags
10
+ // of the CLI they installed. The same file is the plugin's skill, installed
11
+ // from its own repository for next time.
12
+
13
+ import type { Command } from "commander";
14
+ import { type OutputFlags, renderValue } from "../output/index.js";
15
+ import { VERSION } from "../version.js";
16
+ import { addValueFlags, resultFormat } from "./shared.js";
17
+
18
+ export function registerCodingAgent(program: Command): void {
19
+ const command = program
20
+ .command("coding-agent")
21
+ .description("print the guide a coding agent follows to set Stigmer up for your project")
22
+ .action(async (options: OutputFlags) => {
23
+ const { GUIDE } = await import("@stigmer/coding-agent-plugin");
24
+ renderValue(codingAgentGuide(GUIDE, VERSION), { version: VERSION, guide: GUIDE }, resultFormat(options));
25
+ });
26
+ addValueFlags(command);
27
+ }
28
+
29
+ /** The printed guide: one line that says what it is, then the guide. Pure. */
30
+ export function codingAgentGuide(guide: string, version: string): string {
31
+ const header = `Stigmer CLI ${version}: the guide for a coding agent. Follow it step by step, asking the person where it says to.`;
32
+ return `${header}\n\n${guide.trimEnd()}\n`;
33
+ }
@@ -104,9 +104,11 @@ function buildStatus(config: Config): CommandResult {
104
104
  if (entry?.type === "selfhost") {
105
105
  section.field(
106
106
  "Auth",
107
- entry.api_key
108
- ? "API key stored"
109
- : "No credential (unauthenticated server, or STIGMER_API_KEY)",
107
+ entry.token
108
+ ? "Logged in"
109
+ : entry.api_key
110
+ ? "API key stored"
111
+ : "No credential (unauthenticated server, or STIGMER_API_KEY)",
110
112
  );
111
113
  }
112
114
  return result;
@@ -160,8 +162,20 @@ function applyAdd(name: string, options: AddOptions): CommandResult {
160
162
  const config = load();
161
163
  const backends = (config.backends ??= {});
162
164
  const existing = backends[name];
165
+ // A sign-in belongs to the server it was made with: re-pointing the entry
166
+ // drops it, so its token is never sent to the new address.
167
+ const moved = existing !== undefined && (existing.endpoint ?? "") !== endpoint;
163
168
  backends[name] = {
164
169
  ...existing,
170
+ ...(moved
171
+ ? {
172
+ token: undefined,
173
+ refresh_token: undefined,
174
+ token_expiry: undefined,
175
+ oidc_issuer: undefined,
176
+ oidc_client_id: undefined,
177
+ }
178
+ : {}),
165
179
  type: type as NamedBackendType,
166
180
  endpoint,
167
181
  ...(options.apiKey !== undefined ? { api_key: options.apiKey } : {}),
@@ -173,9 +187,9 @@ function applyAdd(name: string, options: AddOptions): CommandResult {
173
187
  ).hint(`Switch to it: stigmer config backend use ${name}`);
174
188
  if (type === "selfhost" && backends[name].api_key === undefined) {
175
189
  result.hint(
176
- "No API key stored. For an authenticated server, mint one on that backend:",
190
+ "No credential stored. For a server that signs people in, switch to it and sign in:",
177
191
  );
178
- result.hint(" stigmer apikey create --name cli");
192
+ result.hint(` stigmer config backend use ${name} && stigmer auth login`);
179
193
  }
180
194
  return result;
181
195
  }
@@ -208,7 +222,7 @@ function buildList(config: Config): CommandResult {
208
222
  if (entry?.type === "cloud") {
209
223
  section.field("Auth", entry.token ? "Logged in" : "Not logged in");
210
224
  } else if (entry?.type === "selfhost") {
211
- section.field("Auth", entry.api_key ? "API key stored" : "None");
225
+ section.field("Auth", entry.token ? "Logged in" : entry.api_key ? "API key stored" : "None");
212
226
  }
213
227
  }
214
228
  return result;
@@ -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
+ }
@@ -0,0 +1,209 @@
1
+ // `stigmer embedding [set]` — how people sign in to the organization from your own app.
2
+ //
3
+ // embedding the settings as they stand
4
+ // embedding set [--create-accounts-on-sign-in on|off]
5
+ // [--sign-in-role member|admin|viewer|none]
6
+ //
7
+ // When your app's backend mints a token for one of its users (the token
8
+ // route `stigmer app-handover` writes), the server makes that person's
9
+ // account on their first sign-in only while account creation is on, and
10
+ // gives it the sign-in role. `set` changes those two and keeps everything
11
+ // else as it stands (the allowed origins and the vaults), the rule the
12
+ // console's In your app tab follows, since the server replaces the settings
13
+ // whole (`updateEmbedding`). A role needs account creation on, so turning it
14
+ // off clears the role. Only the organization's admins may change them; the
15
+ // refusal says so.
16
+
17
+ import type { Command } from "commander";
18
+ import type { Organization } from "@stigmer/apis/ai/stigmer/tenancy/organization/v1/api_pb";
19
+ import { IamRole } from "@stigmer/apis/ai/stigmer/iam/v1/enum_pb";
20
+ import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
21
+ import { Code } from "@connectrpc/connect";
22
+ import { CliExitError, ExitCode, UsageError, classify } from "../errors/index.js";
23
+ import { type OutputFlags, CommandResult, renderResult } from "../output/index.js";
24
+ import { addResultFlags, globalOrg, resultFormat } from "./shared.js";
25
+
26
+ interface SetFlags extends OutputFlags {
27
+ createAccountsOnSignIn?: string;
28
+ signInRole?: string;
29
+ }
30
+
31
+ const SET_ORG_WITH = ["stigmer embedding --org <org>", "stigmer config context set --org <org>"];
32
+
33
+ /** The roles `--sign-in-role` takes, by the word a person types. */
34
+ const ROLES: ReadonlyMap<string, IamRole> = new Map([
35
+ ["member", IamRole.member],
36
+ ["admin", IamRole.admin],
37
+ ["viewer", IamRole.viewer],
38
+ ["none", IamRole.iam_role_unspecified],
39
+ ]);
40
+
41
+ /** The two settings `set` changes, as they stand or should stand. */
42
+ export interface SignInSettings {
43
+ readonly createAccountsOnSignIn: boolean;
44
+ readonly signInRole: IamRole;
45
+ }
46
+
47
+ export function registerEmbedding(program: Command): void {
48
+ const group = program
49
+ .command("embedding")
50
+ .description("how people sign in to the organization from your own app: account creation and their role")
51
+ .action(async (options: OutputFlags, command: Command) => {
52
+ const { organization } = await openSession(command);
53
+ renderResult(embeddingResult(organization, "Embedding settings"), resultFormat(options));
54
+ });
55
+ addResultFlags(group);
56
+
57
+ const set = group
58
+ .command("set")
59
+ .description("change account creation on sign-in and the role it gives, keeping origins and vaults (organization admins)")
60
+ .option("--create-accounts-on-sign-in <on|off>", "make a person's account the first time your app signs them in")
61
+ .option("--sign-in-role <role>", "the role those accounts get: member, admin, viewer or none")
62
+ .action(async (options: SetFlags, command: Command) => {
63
+ const format = resultFormat(options);
64
+ const wanted = parseSetFlags(options);
65
+ const { stigmer, organization } = await openSession(command);
66
+ const next = nextSettings(signInSettingsOf(organization), wanted);
67
+ const { create } = await import("@bufbuild/protobuf");
68
+ const { UpdateOrganizationEmbeddingInputSchema } = await import(
69
+ "@stigmer/apis/ai/stigmer/tenancy/organization/v1/io_pb"
70
+ );
71
+ const { OrganizationEmbeddingSchema } = await import("@stigmer/apis/ai/stigmer/tenancy/organization/v1/spec_pb");
72
+ const current = organization.spec?.embedding;
73
+ let updated: Organization;
74
+ try {
75
+ updated = await stigmer.organization.updateEmbedding(
76
+ create(UpdateOrganizationEmbeddingInputSchema, {
77
+ orgId: organization.metadata?.id ?? "",
78
+ embedding: create(OrganizationEmbeddingSchema, {
79
+ allowedOrigins: [...(current?.allowedOrigins ?? [])],
80
+ vaults: [...(current?.vaults ?? [])],
81
+ createAccountsOnSignIn: next.createAccountsOnSignIn,
82
+ signInRole: next.signInRole,
83
+ }),
84
+ }),
85
+ );
86
+ } catch (err) {
87
+ throw refusalOf(err) ?? err;
88
+ }
89
+ renderResult(embeddingResult(updated, "Embedding settings saved"), format);
90
+ });
91
+ addResultFlags(set);
92
+ }
93
+
94
+ /** The flags as settings to apply; an omitted flag is undefined. Throws on a word it does not know. */
95
+ export function parseSetFlags(options: SetFlags): Partial<SignInSettings> {
96
+ const out: { createAccountsOnSignIn?: boolean; signInRole?: IamRole } = {};
97
+ if (options.createAccountsOnSignIn !== undefined) {
98
+ const word = options.createAccountsOnSignIn.trim().toLowerCase();
99
+ if (word !== "on" && word !== "off") {
100
+ throw new UsageError(`--create-accounts-on-sign-in takes on or off, not "${options.createAccountsOnSignIn}"`);
101
+ }
102
+ out.createAccountsOnSignIn = word === "on";
103
+ }
104
+ if (options.signInRole !== undefined) {
105
+ const word = options.signInRole.trim().toLowerCase();
106
+ const role = ROLES.get(word);
107
+ if (role === undefined) {
108
+ throw new UsageError(
109
+ word === "owner"
110
+ ? "the sign-in role cannot be owner\n\nOwnership is given by hand. Use member, admin, viewer or none."
111
+ : `unknown role "${options.signInRole}"\n\nUse member, admin, viewer or none.`,
112
+ );
113
+ }
114
+ out.signInRole = role;
115
+ }
116
+ if (out.createAccountsOnSignIn === undefined && out.signInRole === undefined) {
117
+ throw new UsageError(
118
+ "nothing to change\n\nPass --create-accounts-on-sign-in on|off, --sign-in-role <role>, or both.",
119
+ );
120
+ }
121
+ return out;
122
+ }
123
+
124
+ /**
125
+ * The settings after a change: a role needs account creation on, so a role
126
+ * asked for turns it on when the flag left it unsaid, and turning it off
127
+ * clears the role. Pure.
128
+ */
129
+ export function nextSettings(current: SignInSettings, wanted: Partial<SignInSettings>): SignInSettings {
130
+ const roleAsked = wanted.signInRole !== undefined && wanted.signInRole !== IamRole.iam_role_unspecified;
131
+ const create = wanted.createAccountsOnSignIn ?? (roleAsked ? true : current.createAccountsOnSignIn);
132
+ if (!create && roleAsked) {
133
+ throw new UsageError(
134
+ "a sign-in role needs account creation on\n\nOnly an account the sign-in makes gets the role. Drop --sign-in-role, or use --create-accounts-on-sign-in on.",
135
+ );
136
+ }
137
+ const role = create ? (wanted.signInRole ?? current.signInRole) : IamRole.iam_role_unspecified;
138
+ return { createAccountsOnSignIn: create, signInRole: role };
139
+ }
140
+
141
+ /** The two settings as the organization holds them. */
142
+ export function signInSettingsOf(organization: Organization): SignInSettings {
143
+ const embedding = organization.spec?.embedding;
144
+ return {
145
+ createAccountsOnSignIn: embedding?.createAccountsOnSignIn === true,
146
+ signInRole: embedding?.signInRole ?? IamRole.iam_role_unspecified,
147
+ };
148
+ }
149
+
150
+ /** The settings as a person reads them. Pure. */
151
+ export function embeddingResult(organization: Organization, message: string): CommandResult {
152
+ const embedding = organization.spec?.embedding;
153
+ const settings = signInSettingsOf(organization);
154
+ const origins = embedding?.allowedOrigins ?? [];
155
+ const vaults = embedding?.vaults ?? [];
156
+ const role = roleWord(settings.signInRole);
157
+ const result = CommandResult.success(message).withData({
158
+ org: organization.metadata?.slug ?? "",
159
+ createAccountsOnSignIn: settings.createAccountsOnSignIn,
160
+ signInRole: role,
161
+ allowedOrigins: [...origins],
162
+ vaults: vaults.length,
163
+ });
164
+ result
165
+ .addSection("")
166
+ .field("Organization", organization.metadata?.slug ?? organization.metadata?.id ?? "")
167
+ .field("Accounts on sign-in", settings.createAccountsOnSignIn ? "made on a person's first sign-in" : "off: your app makes them first")
168
+ .field("Their role", settings.createAccountsOnSignIn ? role : "none")
169
+ .field("Allowed origins", origins.length === 0 ? "any (not checked)" : origins.join(", "))
170
+ .field("Vaults", vaults.length === 0 ? "none" : `${vaults.length}`);
171
+ if (!settings.createAccountsOnSignIn) {
172
+ result.hint("Let your app's users in on their first sign-in: stigmer embedding set --create-accounts-on-sign-in on --sign-in-role member");
173
+ }
174
+ return result;
175
+ }
176
+
177
+ function roleWord(role: IamRole): string {
178
+ for (const [word, value] of ROLES) if (value === role) return word;
179
+ // A role `set` does not offer (an organization that holds one from before): its own name.
180
+ return IamRole[role] ?? "none";
181
+ }
182
+
183
+ /** A refusal in plain words, or undefined for any other failure. */
184
+ function refusalOf(err: unknown): CliExitError | undefined {
185
+ if (classify(err)?.code === Code.PermissionDenied) {
186
+ return new CliExitError(
187
+ "only the organization's admins can change how people sign in from your app",
188
+ ExitCode.Auth,
189
+ ["Ask an admin to run: stigmer embedding set ..."],
190
+ { cause: err },
191
+ );
192
+ }
193
+ return undefined;
194
+ }
195
+
196
+ async function openSession(command: Command): Promise<{
197
+ stigmer: import("@stigmer/client").Stigmer;
198
+ organization: Organization;
199
+ }> {
200
+ const [{ connectBackend }, { currentOrganization }] = await Promise.all([
201
+ import("../backend.js"),
202
+ import("../client/current-organization.js"),
203
+ ]);
204
+ const client = connectBackend();
205
+ ensureAuthenticated(client.config);
206
+ const org = resolveOrganization(client.config, globalOrg(command));
207
+ const organization = await currentOrganization(client.stigmer, org, SET_ORG_WITH);
208
+ return { stigmer: client.stigmer, organization };
209
+ }