@stigmer/cli 0.1.3 → 0.2.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 (230) 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 +155 -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 +5 -0
  52. package/commands/auth/whoami.d.ts.map +1 -1
  53. package/commands/auth/whoami.js +13 -1
  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/embedding.d.ts +28 -0
  62. package/commands/embedding.d.ts.map +1 -0
  63. package/commands/embedding.js +170 -0
  64. package/commands/embedding.js.map +1 -0
  65. package/commands/example.d.ts +13 -0
  66. package/commands/example.d.ts.map +1 -0
  67. package/commands/example.js +126 -0
  68. package/commands/example.js.map +1 -0
  69. package/commands/help.d.ts.map +1 -1
  70. package/commands/help.js +16 -3
  71. package/commands/help.js.map +1 -1
  72. package/commands/load-test/burst.d.ts +64 -0
  73. package/commands/load-test/burst.d.ts.map +1 -0
  74. package/commands/load-test/burst.js +202 -0
  75. package/commands/load-test/burst.js.map +1 -0
  76. package/commands/load-test/index.d.ts +37 -0
  77. package/commands/load-test/index.d.ts.map +1 -0
  78. package/commands/load-test/index.js +154 -0
  79. package/commands/load-test/index.js.map +1 -0
  80. package/commands/load-test/report.d.ts +98 -0
  81. package/commands/load-test/report.d.ts.map +1 -0
  82. package/commands/load-test/report.js +210 -0
  83. package/commands/load-test/report.js.map +1 -0
  84. package/commands/mcp-server.d.ts +3 -3
  85. package/commands/mcp-server.d.ts.map +1 -1
  86. package/commands/mcp-server.js +4 -4
  87. package/commands/mcp-server.js.map +1 -1
  88. package/commands/setup.d.ts +17 -0
  89. package/commands/setup.d.ts.map +1 -1
  90. package/commands/setup.js +71 -1
  91. package/commands/setup.js.map +1 -1
  92. package/commands/up.d.ts.map +1 -1
  93. package/commands/up.js +67 -9
  94. package/commands/up.js.map +1 -1
  95. package/commands/usage.d.ts +15 -0
  96. package/commands/usage.d.ts.map +1 -1
  97. package/commands/usage.js +52 -2
  98. package/commands/usage.js.map +1 -1
  99. package/config/config.d.ts +14 -7
  100. package/config/config.d.ts.map +1 -1
  101. package/config/config.js +5 -1
  102. package/config/config.js.map +1 -1
  103. package/config/index.d.ts +1 -1
  104. package/config/index.d.ts.map +1 -1
  105. package/config/index.js +1 -1
  106. package/config/index.js.map +1 -1
  107. package/config/resolve.d.ts +1 -1
  108. package/config/resolve.d.ts.map +1 -1
  109. package/config/resolve.js +6 -3
  110. package/config/resolve.js.map +1 -1
  111. package/errors/classify.d.ts.map +1 -1
  112. package/errors/classify.js +10 -1
  113. package/errors/classify.js.map +1 -1
  114. package/errors/cli-exit-error.d.ts +3 -1
  115. package/errors/cli-exit-error.d.ts.map +1 -1
  116. package/errors/cli-exit-error.js +6 -2
  117. package/errors/cli-exit-error.js.map +1 -1
  118. package/errors/handle.d.ts +32 -5
  119. package/errors/handle.d.ts.map +1 -1
  120. package/errors/handle.js +67 -8
  121. package/errors/handle.js.map +1 -1
  122. package/local/daemon/components.d.ts +28 -1
  123. package/local/daemon/components.d.ts.map +1 -1
  124. package/local/daemon/components.js +64 -2
  125. package/local/daemon/components.js.map +1 -1
  126. package/local/daemon/host.d.ts.map +1 -1
  127. package/local/daemon/host.js +6 -2
  128. package/local/daemon/host.js.map +1 -1
  129. package/local/daemon/launch.d.ts +12 -4
  130. package/local/daemon/launch.d.ts.map +1 -1
  131. package/local/daemon/launch.js +49 -16
  132. package/local/daemon/launch.js.map +1 -1
  133. package/local/daemon/types.d.ts +9 -1
  134. package/local/daemon/types.d.ts.map +1 -1
  135. package/local/key-check.d.ts +20 -0
  136. package/local/key-check.d.ts.map +1 -0
  137. package/local/key-check.js +45 -0
  138. package/local/key-check.js.map +1 -0
  139. package/local/model-key-step.d.ts +63 -0
  140. package/local/model-key-step.d.ts.map +1 -0
  141. package/local/model-key-step.js +133 -0
  142. package/local/model-key-step.js.map +1 -0
  143. package/local/setup/prompt.d.ts.map +1 -1
  144. package/local/setup/prompt.js +22 -18
  145. package/local/setup/prompt.js.map +1 -1
  146. package/local/setup/wizard.d.ts +10 -0
  147. package/local/setup/wizard.d.ts.map +1 -1
  148. package/local/setup/wizard.js +40 -17
  149. package/local/setup/wizard.js.map +1 -1
  150. package/local/state/lock.d.ts.map +1 -1
  151. package/local/state/lock.js +123 -36
  152. package/local/state/lock.js.map +1 -1
  153. package/local/state/pidfile.d.ts +4 -0
  154. package/local/state/pidfile.d.ts.map +1 -1
  155. package/local/state/pidfile.js +12 -3
  156. package/local/state/pidfile.js.map +1 -1
  157. package/package.json +12 -9
  158. package/program.d.ts.map +1 -1
  159. package/program.js +10 -0
  160. package/program.js.map +1 -1
  161. package/resources/get.js +1 -1
  162. package/resources/get.js.map +1 -1
  163. package/resources/run/stream.d.ts.map +1 -1
  164. package/resources/run/stream.js +2 -1
  165. package/resources/run/stream.js.map +1 -1
  166. package/resources/stream/render-plaintext.d.ts +3 -0
  167. package/resources/stream/render-plaintext.d.ts.map +1 -1
  168. package/resources/stream/render-plaintext.js +20 -2
  169. package/resources/stream/render-plaintext.js.map +1 -1
  170. package/resources/usage.d.ts +8 -0
  171. package/resources/usage.d.ts.map +1 -1
  172. package/resources/usage.js +37 -0
  173. package/resources/usage.js.map +1 -1
  174. package/runtime.d.ts +9 -0
  175. package/runtime.d.ts.map +1 -1
  176. package/runtime.js +12 -1
  177. package/runtime.js.map +1 -1
  178. package/src/auth/browser.ts +57 -0
  179. package/src/auth/callback-server.ts +58 -22
  180. package/src/auth/device.ts +151 -0
  181. package/src/auth/index.ts +4 -3
  182. package/src/auth/login.ts +243 -67
  183. package/src/auth/oidc.ts +270 -0
  184. package/src/auth/token.ts +53 -90
  185. package/src/client/client.ts +4 -1
  186. package/src/client/current-organization.ts +27 -0
  187. package/src/commands/apikey/index.ts +85 -0
  188. package/src/commands/app-handover.ts +188 -0
  189. package/src/commands/auth/index.ts +16 -10
  190. package/src/commands/auth/login.ts +30 -23
  191. package/src/commands/auth/whoami.ts +16 -1
  192. package/src/commands/coding-agent.ts +33 -0
  193. package/src/commands/config/backend.ts +20 -6
  194. package/src/commands/embedding.ts +209 -0
  195. package/src/commands/example.ts +146 -0
  196. package/src/commands/help.ts +16 -3
  197. package/src/commands/load-test/burst.ts +291 -0
  198. package/src/commands/load-test/index.ts +183 -0
  199. package/src/commands/load-test/report.ts +302 -0
  200. package/src/commands/mcp-server.ts +5 -5
  201. package/src/commands/setup.ts +76 -2
  202. package/src/commands/up.ts +76 -10
  203. package/src/commands/usage.ts +55 -2
  204. package/src/config/config.ts +18 -8
  205. package/src/config/index.ts +1 -0
  206. package/src/config/resolve.ts +5 -3
  207. package/src/errors/classify.ts +10 -1
  208. package/src/errors/cli-exit-error.ts +6 -2
  209. package/src/errors/handle.ts +74 -8
  210. package/src/local/daemon/components.ts +66 -2
  211. package/src/local/daemon/host.ts +6 -2
  212. package/src/local/daemon/launch.ts +51 -16
  213. package/src/local/daemon/types.ts +9 -1
  214. package/src/local/key-check.ts +61 -0
  215. package/src/local/model-key-step.ts +164 -0
  216. package/src/local/setup/prompt.ts +22 -18
  217. package/src/local/setup/wizard.ts +45 -18
  218. package/src/local/state/lock.ts +116 -35
  219. package/src/local/state/pidfile.ts +14 -3
  220. package/src/program.ts +10 -0
  221. package/src/resources/get.ts +1 -1
  222. package/src/resources/run/stream.ts +2 -1
  223. package/src/resources/stream/render-plaintext.ts +20 -2
  224. package/src/resources/usage.ts +42 -0
  225. package/src/runtime.ts +17 -1
  226. package/auth/auth0.d.ts +0 -19
  227. package/auth/auth0.d.ts.map +0 -1
  228. package/auth/auth0.js +0 -39
  229. package/auth/auth0.js.map +0 -1
  230. 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,10 @@
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
+ //
9
13
  // It names the context organization by the slug the backend answers now,
10
14
  // not the one `config context set` stored, and stores the current one when
11
15
  // the organization was renamed since.
@@ -24,6 +28,7 @@ import {
24
28
  save,
25
29
  } from "../../config/index.js";
26
30
  import { CommandResult } from "../../output/index.js";
31
+ import { helpLine } from "../../errors/handle.js";
27
32
  import { organizationNamed, type OrganizationNames } from "../../client/organizations.js";
28
33
  import { omitsOrganization } from "../../client/single-org.js";
29
34
 
@@ -37,6 +42,8 @@ export interface WhoamiContext {
37
42
  readonly orgId?: string;
38
43
  /** The server holds one organization and fills it, so the CLI never names one. */
39
44
  readonly singleOrg: boolean;
45
+ /** Where the server says to ask for help; absent when it names none. */
46
+ readonly help?: { readonly url: string; readonly label: string };
40
47
  }
41
48
 
42
49
  /**
@@ -84,6 +91,10 @@ export function whoamiResult(
84
91
  }
85
92
  }
86
93
 
94
+ if (context.help !== undefined) {
95
+ result.hint(helpLine(context.help));
96
+ }
97
+
87
98
  return result;
88
99
  }
89
100
 
@@ -97,7 +108,11 @@ export async function runWhoami(): Promise<CommandResult> {
97
108
  });
98
109
  const singleOrg = await omitsOrganization(client.stigmer);
99
110
  const org = singleOrg ? { label: "", id: "" } : await liveContextOrganization(client.stigmer, client.config);
100
- return whoamiResult(account, { created, org: org.label, orgId: org.id, singleOrg });
111
+ // Printing never fails the command: a failed ask shows no help line.
112
+ const help = await Promise.resolve()
113
+ .then(() => client.serverInfo())
114
+ .then((info) => info.help, () => undefined);
115
+ return whoamiResult(account, { created, org: org.label, orgId: org.id, singleOrg, ...(help !== undefined ? { help } : {}) });
101
116
  }
102
117
 
103
118
  /**
@@ -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,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
+ }
@@ -0,0 +1,146 @@
1
+ // `stigmer example list|get` — Stigmer's example agents, as files in your repository.
2
+ //
3
+ // example list every example: the job, what goes in, what comes back;
4
+ // then the ready-made skills
5
+ // example get <id> [dir] write an example's manifest and samples into dir
6
+ // (default stigmer/<id>), or a skill's SKILL.md
7
+ // (default stigmer/skills/<id>)
8
+ //
9
+ // The list is `@stigmer/examples`, the one the console's first question and
10
+ // its Make it yours tab read, so every door offers the same agents with the
11
+ // same words. `get` writes the manifest people would download and the sample
12
+ // files a first run attaches, then says the two commands that make the agent
13
+ // and run it once on the samples (`stigmer apply -f`, `stigmer run --attach`).
14
+ // An agent made from an example keeps the example's slug, which is how the
15
+ // console's journey knows it.
16
+ //
17
+ // It never overwrites: a file already there is refused unless `--force`, so a
18
+ // manifest a person (or their coding agent) has edited is not lost.
19
+
20
+ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
21
+ import { join, relative, resolve } from "node:path";
22
+ import type { Command } from "commander";
23
+ import type { Example, ExampleSkill } from "@stigmer/examples";
24
+ import { CliExitError, ExitCode } from "../errors/index.js";
25
+ import { type OutputFlags, CommandResult, renderResult } from "../output/index.js";
26
+ import { addResultFlags, resultFormat } from "./shared.js";
27
+
28
+ interface GetFlags extends OutputFlags {
29
+ force?: boolean;
30
+ }
31
+
32
+ /** Where the output of a first run goes, as the guide's step 4 names it. */
33
+ export const RUN_OUTPUT_DIR = "stigmer-output";
34
+
35
+ export function registerExample(program: Command): void {
36
+ const group = program
37
+ .command("example")
38
+ .description("the example agents and skills, written into your repository as files");
39
+
40
+ const list = group
41
+ .command("list")
42
+ .description("list the example agents (the job, what goes in, what comes back) and the ready-made skills")
43
+ .action(async (options: OutputFlags) => {
44
+ const { EXAMPLES, SKILLS } = await import("@stigmer/examples");
45
+ renderResult(exampleListResult(EXAMPLES, SKILLS), resultFormat(options));
46
+ });
47
+ addResultFlags(list);
48
+
49
+ const get = group
50
+ .command("get <id> [dir]")
51
+ .description("write an example's manifest and sample files (or a skill's SKILL.md) into dir")
52
+ .option("-f, --force", "overwrite files that are already there")
53
+ .action(async (id: string, dir: string | undefined, options: GetFlags) => {
54
+ const { exampleById, skillById, EXAMPLES, SKILLS } = await import("@stigmer/examples");
55
+ const example = exampleById(id);
56
+ const skill = example === undefined ? skillById(id) : undefined;
57
+ if (example === undefined && skill === undefined) {
58
+ throw new CliExitError(`no example or skill named "${id}"`, ExitCode.Usage, [
59
+ `Examples: ${EXAMPLES.map((e) => e.id).join(", ")}`,
60
+ `Skills: ${SKILLS.map((s) => s.id).join(", ")}`,
61
+ "See them with: stigmer example list",
62
+ ]);
63
+ }
64
+ const result =
65
+ example !== undefined
66
+ ? writeExample(example, dir ?? join("stigmer", example.id), options.force === true)
67
+ : writeSkill(skill as ExampleSkill, dir ?? join("stigmer", "skills", (skill as ExampleSkill).id), options.force === true);
68
+ renderResult(result, resultFormat(options));
69
+ });
70
+ addResultFlags(get);
71
+ }
72
+
73
+ /** The list a person reads: each example's job, then the skills. Pure. */
74
+ export function exampleListResult(examples: readonly Example[], skills: readonly ExampleSkill[]): CommandResult {
75
+ const result = CommandResult.success(`${examples.length} example agents`).withData({
76
+ examples: examples.map((e) => ({
77
+ id: e.id,
78
+ name: e.name,
79
+ for: e.for,
80
+ gives: e.gives,
81
+ gets: e.gets,
82
+ agent: e.agent.slug,
83
+ })),
84
+ skills: skills.map((s) => ({ id: s.id, name: s.name, description: s.description })),
85
+ });
86
+ for (const example of examples) {
87
+ result
88
+ .addSection(`${example.id} — ${example.name}`)
89
+ .field("For", example.for.replace(/^For /, ""))
90
+ .field("Gives", example.gives)
91
+ .field("Gets", example.gets)
92
+ .field("Agent", example.agent.slug);
93
+ }
94
+ if (skills.length > 0) {
95
+ const section = result.addSection("Skills");
96
+ for (const skill of skills) section.field(skill.id, skill.name);
97
+ }
98
+ return result
99
+ .hint("Write one into this repository: stigmer example get <id>")
100
+ .hint("Or describe your own agent in a manifest and: stigmer apply -f <file>");
101
+ }
102
+
103
+ /** Write an example's manifest and samples into `dir`, refusing to overwrite unless `force`. */
104
+ export function writeExample(example: Example, dir: string, force: boolean): CommandResult {
105
+ const files = [example.manifest, ...example.samples.map((s) => ({ name: s.name, text: s.text }))];
106
+ const written = writeFiles(dir, files, force);
107
+ const shown = displayPath(dir);
108
+ const attach = example.samples.map((s) => `--attach ${join(shown, s.name)}`).join(" ");
109
+ return CommandResult.success(`Wrote ${example.name} into ${shown}`)
110
+ .withData({ dir: shown, files: written, agent: example.agent.slug })
111
+ .hint(`Make the agent: stigmer apply -f ${join(shown, example.manifest.name)}`)
112
+ .hint(
113
+ `Run it once on the ${example.sampleName}: stigmer run ${example.agent.slug} -m ${JSON.stringify(example.message)} ${attach} --download ${RUN_OUTPUT_DIR}/`,
114
+ );
115
+ }
116
+
117
+ /** Write a skill's SKILL.md into `dir`, refusing to overwrite unless `force`. */
118
+ export function writeSkill(skill: ExampleSkill, dir: string, force: boolean): CommandResult {
119
+ const written = writeFiles(dir, [{ name: "SKILL.md", text: skill.text }], force);
120
+ const shown = displayPath(dir);
121
+ return CommandResult.success(`Wrote the ${skill.name} skill into ${shown}`)
122
+ .withData({ dir: shown, files: written, skill: skill.id })
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.`);
125
+ }
126
+
127
+ function writeFiles(dir: string, files: readonly { name: string; text: string }[], force: boolean): string[] {
128
+ const target = resolve(dir);
129
+ const existing = files.map((f) => join(target, f.name)).filter((path) => existsSync(path));
130
+ if (existing.length > 0 && !force) {
131
+ throw new CliExitError(
132
+ `${existing.map(displayPath).join(", ")} ${existing.length === 1 ? "is" : "are"} already there`,
133
+ ExitCode.Usage,
134
+ ["Keep your copy, write somewhere else (stigmer example get <id> <dir>), or overwrite with --force."],
135
+ );
136
+ }
137
+ mkdirSync(target, { recursive: true });
138
+ for (const file of files) writeFileSync(join(target, file.name), file.text);
139
+ return files.map((f) => displayPath(join(target, f.name)));
140
+ }
141
+
142
+ /** A path as the person typed it: relative to where they stand when it is inside. */
143
+ function displayPath(path: string): string {
144
+ const rel = relative(process.cwd(), resolve(path));
145
+ return rel === "" ? "." : rel.startsWith("..") ? resolve(path) : rel;
146
+ }