@rosthq/cli 0.5.3 → 0.5.4

package/dist/index.js

@@ -42241,7 +42241,7 @@ Agents should explain the job, the required tool category, the minimum permissio
     order: 48,
     title: "CLI and MCP installation guide",
     summary: "Install the public CLI, register remote token-backed MCP clients, and find the full command and tool catalog.",
-    version: "2026-06-18.2",
+    version: "2026-06-18.4",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["company_setup", "staffing"],
@@ -42394,7 +42394,7 @@ export {{envPrefix}}_CLI_ALLOW_FILE_TOKEN_STORE=1
 {{cli}} login --device
 \`\`\`
 
-For CI, do not run an interactive device login on every job (a device code still needs a human approver, which CI does not have). Note that the CLI session is a **short-lived** auth session (it carries an expiry), not a durable credential \u2014 so storing the session file as a long-lived CI secret will stop working once it expires, and re-approving a device code unattended is not possible. For ongoing unattended automation, prefer a **seat-scoped MCP token** (mint it once with \`mcp install --scope seat\`; it stays valid until revoked) used directly by your MCP client, and treat that client config as a secret. Revoke and re-mint if a runner image is rebuilt or shared.
+For CI, do not run an interactive device login on every job (a device code still needs a human approver, which CI does not have). Note that the CLI session is a **short-lived** auth session (it carries an expiry), not a durable credential \u2014 so storing the session file as a long-lived CI secret will stop working once it expires, and re-approving a device code unattended is not possible. For ongoing unattended automation, prefer a **seat-scoped MCP token** used directly by your MCP client, and treat that client config as a secret. Such a token now defaults to a **90-day** expiry, so for automation that must outlive that window, mint it with an explicit \`--expires-in <days>\` (up to 365) or, accepting the long-lived-credential tradeoff, \`--no-expiry\` \u2014 e.g. \`mcp install --scope seat --seat-id <id> --expires-in 365\`. Rotate it before it lapses (\`--rotate <old-token-id>\`), and revoke and re-mint if a runner image is rebuilt or shared.
 
 ## First-run path
 
@@ -42503,7 +42503,22 @@ After registering, confirm the client can actually reach the server with the new
 
 ### Token lifetime and rotation
 
-Tokens minted by \`{{cli}} mcp install\` today carry **no expiry** \u2014 they stay valid until revoked, for both tenant-admin and seat-scoped tokens. (\`mcp install\` does not set an \`expires_at\`; the underlying \`mcp_token.create\` command does accept an optional \`expires_at\`, and default expiry plus one-step rotation are planned \u2014 but do not assume an automatic TTL on a token you minted through \`mcp install\`.) Because such a token is long-lived, rotate it deliberately:
+Every MCP token now carries an expiry. Tokens minted by \`{{cli}} mcp install\` default to a **90-day** TTL (for both tenant-admin and seat-scoped tokens); after that the token stops authenticating and you re-mint. Override the lifetime at mint time:
+
+- \`--expires-in <days>\` \u2014 set an explicit TTL, between **1 and 365** days. Example: \`{{cli}} mcp install --client codex --expires-in 30\`.
+- \`--no-expiry\` \u2014 mint a token with **no practical expiry** (a ~100-year TTL). This is a deliberate loosening for long-lived automation; the CLI prints a warning. Prefer a finite \`--expires-in\` and rotate instead.
+
+\`mcp install\` echoes the chosen expiry, and \`{{cli}} command mcp_token.list\` reports \`expires_in_days\` for every token so you can see what is about to lapse.
+
+**One-step rotation.** Replace a live token in a single command \u2014 it mints the replacement, prints the new registration block, then revokes the old token:
+
+\`\`\`bash
+{{cli}} mcp install --client <client> --rotate <old-token-id>
+\`\`\`
+
+Rotation **preserves the original token's scope and seat**: rotating a seat-scoped token mints a new seat-scoped token for the same seat, and rotating a tenant-admin token mints a tenant-admin token \u2014 you do **not** pass \`--scope\`/\`--seat-id\` (and if you do, they must match the old token, or the command errors without minting). The CLI looks the old token up first, so an unknown \`--rotate\` id fails cleanly with nothing minted. If the mint succeeds but revoking the old token fails (or the id isn't found at revoke time), the CLI says so on stderr and prints the manual \`mcp_token.revoke\` command \u2014 the new token is already live, so revoke the old one by hand. Find the \`<old-token-id>\` with \`{{cli}} command mcp_token.list\`.
+
+You can also rotate the long way (mint then revoke separately):
 
 1. Re-run \`{{cli}} mcp install --client <client>\` (add \`--scope seat --seat-id <seat-id>\` for a seat token) to mint and register a fresh token.
 2. Revoke the old one (below). Rotate on a periodic cadence, and whenever the scope or seat changes.
@@ -42637,7 +42652,7 @@ These ergonomic wrappers (including the \`{{cli}} agent\` group) require **{{cli
 
 | Command | Purpose | Scope | Safe example |
 |---|---|---|---|
-| \`{{cli}} mcp install --client claude-code|codex|cursor\` | Help syntax for supported MCP clients. | Tenant | \`{{cli}} mcp install --client codex\` |
+| \`{{cli}} mcp install --client claude-code|codex|cursor [--scope seat --seat-id <id>] [--expires-in <days>|--no-expiry] [--rotate <token-id>]\` | Help syntax for supported MCP clients. \`--expires-in <days>\` (1..365) or \`--no-expiry\` sets the token TTL (default 90 days); \`--rotate <token-id>\` mints a replacement then revokes the old token. | Tenant | \`{{cli}} mcp install --client codex --expires-in 30\` |
 | \`{{cli}} mcp install --client claude-code\` | Mint a tenant-admin MCP token and print a Claude Code registration command. | Tenant | \`{{cli}} mcp install --client claude-code\` |
 | \`{{cli}} mcp install --client codex\` | Mint a tenant-admin MCP token and print Codex TOML. | Tenant | \`{{cli}} mcp install --client codex\` |
 | \`{{cli}} mcp install --client cursor\` | Mint a tenant-admin MCP token and print Cursor JSON. | Tenant | \`{{cli}} mcp install --client cursor\` |
@@ -42822,7 +42837,7 @@ These rows are quick, at-a-glance triage. For deeper auth, tenant, scope, confir
 - Node present but too old (npx launches but the CLI rejects it): run \`node --version\`; if it is below v22, upgrade Node.
 - Stale npx cache: rerun with \`npx {{cliPackage}}@latest --help\` or clear the npm cache.
 - MCP connection not working after registering: call \`rost_list_commands\` with \`{}\` (any token); with a tenant-admin token read \`rost://tenant/status\`, with a seat-scoped token call \`rost_get_context\` with \`{}\` (a seat token cannot read \`rost://tenant/status\`). A 401 / not-authorized shape means the token did not register \u2014 re-run \`mcp install\`.
-- Revoked or invalid MCP token: run \`{{cli}} mcp install --client <client>\` again to mint and register a fresh one. (Tokens minted by \`mcp install\` carry no expiry \u2014 they stay valid until revoked.)
+- Revoked, **expired**, or invalid MCP token: run \`{{cli}} mcp install --client <client>\` again to mint and register a fresh one (or rotate with \`--rotate <old-token-id>\`). Tokens minted by \`mcp install\` default to a 90-day expiry \u2014 check \`expires_in_days\` in \`{{cli}} command mcp_token.list\`; mint with \`--expires-in <days>\` or \`--no-expiry\` to change it.
 - Confirmation required: a human approves from the \`approveVia\` web link or runs the \`{{cli}} command confirmation.approve --json ...\` command shown in the CLI error output (an agent never approves its own request \u2014 see the confirmations-guide).
 - Command denied by scope or manifest: switch to a tenant-admin token for setup, or ask a human Steward to update the seat Charter and permission manifest.
 - Need command guidance: run \`{{cli}} docs\`, \`{{cli}} reference search "onboarding"\`, or \`{{cli}} reference get agent-reference-map\`.
@@ -43527,7 +43542,7 @@ Templates may draft. Humans approve. A stock agent should not go live until a hu
     order: 77,
     title: "Troubleshooting guide",
     summary: "How users and agents should diagnose common setup, tool, Signal, Friction, and MCP problems.",
-    version: "2026-06-18.1",
+    version: "2026-06-18.2",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["company_setup", "staffing", "operating_rhythm"],
@@ -43571,7 +43586,7 @@ Before calling a command that changes state, discover its exact shape so you do
 - "Wrong tenant": \`{{cli}} tenants\` then \`{{cli}} use <tenant-slug-or-id>\`.
 - "Command denied by scope or manifest": a seat token cannot run tenant-admin setup. Switch to a tenant-admin token, or ask a human Steward to update the seat Charter and permission manifest.
 - "Confirmation required": the command is gated. The CLI prints \`{{cli}} command confirmation.approve --json ...\` or a web link. A human approves; an agent does not approve its own request.
-- Revoked or invalid MCP token: run \`{{cli}} mcp install --client <client>\` again to mint and register a fresh one. Tokens minted by \`mcp install\` carry no expiry \u2014 they stay valid until revoked.
+- Revoked, **expired**, or invalid MCP token: run \`{{cli}} mcp install --client <client>\` again to mint and register a fresh one (or rotate with \`--rotate <old-token-id>\`). Tokens minted by \`mcp install\` default to a 90-day expiry \u2014 check \`expires_in_days\` in \`{{cli}} command mcp_token.list\`.
 
 ## Agent-creation failures
 
@@ -44224,12 +44239,29 @@ function renderReferenceCorpusIndex() {
 }
 
 // src/mcp-install.ts
+var MCP_TOKEN_DEFAULT_EXPIRY_DAYS = 90;
+var MCP_TOKEN_MIN_EXPIRY_DAYS = 1;
+var MCP_TOKEN_MAX_EXPIRY_DAYS = 365;
+var MCP_TOKEN_NO_EXPIRY_SENTINEL_DAYS = 36525;
+var mcpTokenScopeSchema = external_exports.enum(["tenant_admin", "seat"]);
 var mcpTokenOutputSchema = external_exports.object({
   token_id: external_exports.string().min(1),
   token: external_exports.string().min(1),
-  scope: external_exports.enum(["tenant_admin", "seat"]),
+  scope: mcpTokenScopeSchema,
   seat_id: external_exports.string().min(1).nullable()
 }).strict();
+var mcpTokenRevokeOutputSchema = external_exports.object({
+  token_id: external_exports.string().min(1),
+  revoked: external_exports.boolean()
+}).strict();
+var mcpTokenListEntrySchema = external_exports.object({
+  token_id: external_exports.string().min(1),
+  scope: mcpTokenScopeSchema,
+  seat_id: external_exports.string().min(1).nullable()
+}).passthrough();
+var mcpTokenListOutputSchema = external_exports.object({
+  tokens: external_exports.array(mcpTokenListEntrySchema)
+}).passthrough();
 var pendingConfirmationSchema = external_exports.object({
   confirmationId: external_exports.string().min(1),
   commandId: external_exports.string().min(1)
@@ -44245,6 +44277,9 @@ function parseMcpInstallOptions(args) {
   let scope = "tenant_admin";
   let seatId;
   let json2 = false;
+  let expiresInDays;
+  let noExpiry = false;
+  let rotateTokenId;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--client") {
@@ -44257,6 +44292,14 @@ function parseMcpInstallOptions(args) {
       seatId = requireValue(args, index, "--seat-id");
       scope = "seat";
       index += 1;
+    } else if (arg === "--expires-in") {
+      expiresInDays = parseExpiresIn(requireValue(args, index, "--expires-in"));
+      index += 1;
+    } else if (arg === "--no-expiry") {
+      noExpiry = true;
+    } else if (arg === "--rotate") {
+      rotateTokenId = requireValue(args, index, "--rotate");
+      index += 1;
     } else if (arg === "--json") {
       json2 = true;
     } else {
@@ -44269,22 +44312,53 @@ function parseMcpInstallOptions(args) {
   if (scope === "seat" && !seatId) {
     throw new Error("Seat-scoped MCP install requires --seat-id.");
   }
+  if (noExpiry && expiresInDays !== void 0) {
+    throw new Error("Use either --expires-in or --no-expiry, not both.");
+  }
+  const expiry = noExpiry ? { kind: "none" } : expiresInDays === void 0 ? { kind: "default" } : { kind: "days", days: expiresInDays };
   return {
     client,
     scope,
     ...seatId === void 0 ? {} : { seatId },
-    json: json2
+    json: json2,
+    expiry,
+    ...rotateTokenId === void 0 ? {} : { rotateTokenId }
   };
 }
 var MCP_TOKEN_CAUTION = "Security: this minted MCP token is a live credential that lands in the client's plaintext config \u2014 prefer the narrowest scope (--scope seat --seat-id <id>) and revoke it immediately if it leaks.";
+var NO_EXPIRY_WARNING = "Warning: --no-expiry mints a token with no practical expiry (a ~100-year TTL). This is a long-lived credential by choice \u2014 rotate it deliberately and revoke immediately if it leaks.";
 async function renderMcpInstall(input) {
-  const token = await createMcpToken(input.client, {
-    scope: input.options.scope,
-    ...input.options.seatId === void 0 ? {} : { seat_id: input.options.seatId }
-  });
+  const stderrLines = [];
+  const mintScope = input.options.rotateTokenId === void 0 ? { scope: input.options.scope, ...input.options.seatId === void 0 ? {} : { seatId: input.options.seatId } } : await resolveRotationScope(input.client, input.options);
+  const token = await createMcpToken(input.client, mcpTokenCreateBody(mintScope, input.options.expiry));
+  let rotationOldRevoked = null;
+  if (input.options.rotateTokenId !== void 0) {
+    const oldTokenId = input.options.rotateTokenId;
+    try {
+      const output = await executeWithConfirmation(input.client, "mcp_token.revoke", { token_id: oldTokenId });
+      const revoke = mcpTokenRevokeOutputSchema.safeParse(output);
+      rotationOldRevoked = revoke.success && revoke.data.revoked === true;
+      if (!rotationOldRevoked) {
+        const reason = revoke.success ? "the token id was not found for your tenant (it was not revoked \u2014 check the id)" : "the revoke response could not be parsed";
+        stderrLines.push(
+          `Warning: the new token (${token.token_id}) was minted, but the old token (${oldTokenId}) was NOT revoked \u2014 ${reason}. It is still live. Revoke it by hand: ${cliBrand.binName} command mcp_token.revoke --json '{"token_id":"${oldTokenId}"}'`
+        );
+      }
+    } catch (error51) {
+      rotationOldRevoked = false;
+      stderrLines.push(
+        `Warning: the new token (${token.token_id}) was minted, but revoking the old token (${oldTokenId}) failed: ${revokeFailureReason(error51)}. It is still live. Revoke it by hand: ${cliBrand.binName} command mcp_token.revoke --json '{"token_id":"${oldTokenId}"}'`
+      );
+    }
+  }
   const mcpUrl = `${input.appUrl.replace(/\/+$/, "")}/mcp`;
   const registration = registrationFor(input.options.client, mcpUrl, token.token);
+  const expiryLine = expiryEcho(input.options.expiry);
+  if (input.options.expiry.kind === "none") {
+    stderrLines.push(NO_EXPIRY_WARNING);
+  }
   if (input.options.json) {
+    stderrLines.unshift(MCP_TOKEN_CAUTION);
     return {
       stdout: `${JSON.stringify({
         client: input.options.client,
@@ -44292,32 +44366,119 @@ async function renderMcpInstall(input) {
         scope: token.scope,
         seat_id: token.seat_id,
         mcp_url: mcpUrl,
+        expiry: expiryDescriptor(input.options.expiry),
+        ...input.options.rotateTokenId === void 0 ? {} : { rotated_from: input.options.rotateTokenId, rotated_old_revoked: rotationOldRevoked },
         registration
       }, null, 2)}
 `,
-      stderr: `${MCP_TOKEN_CAUTION}
-`
+      stderr: stderrLines.length > 0 ? `${stderrLines.join("\n")}
+` : ""
     };
   }
+  const stdoutLines = [
+    input.options.rotateTokenId === void 0 ? "MCP token minted. It is shown once in the registration block below." : "MCP token rotated. The replacement is shown once in the registration block below.",
+    expiryLine
+  ];
+  if (input.options.rotateTokenId !== void 0 && rotationOldRevoked === true) {
+    stdoutLines.push(`Old token revoked: ${input.options.rotateTokenId}`);
+  }
+  stdoutLines.push(
+    "",
+    registration,
+    "",
+    MCP_TOKEN_CAUTION,
+    `Revoke later with: ${cliBrand.binName} command mcp_token.revoke --json '{"token_id":"${token.token_id}"}'`,
+    ""
+  );
   return {
-    stdout: [
-      "MCP token minted. It is shown once in the registration block below.",
-      "",
-      registration,
-      "",
-      MCP_TOKEN_CAUTION,
-      `Revoke later with: ${cliBrand.binName} command mcp_token.revoke --json '{"token_id":"${token.token_id}"}'`,
-      ""
-    ].join("\n"),
-    stderr: ""
+    stdout: stdoutLines.join("\n"),
+    stderr: stderrLines.length > 0 ? `${stderrLines.join("\n")}
+` : ""
+  };
+}
+function mcpTokenCreateBody(mint, expiry) {
+  const base = {
+    scope: mint.scope,
+    ...mint.seatId === void 0 ? {} : { seat_id: mint.seatId }
   };
+  if (expiry.kind === "days") {
+    return { ...base, expires_in_days: expiry.days };
+  }
+  if (expiry.kind === "none") {
+    const sentinel = new Date(Date.now() + MCP_TOKEN_NO_EXPIRY_SENTINEL_DAYS * 24 * 60 * 60 * 1e3);
+    return { ...base, expires_at: sentinel.toISOString() };
+  }
+  return base;
+}
+async function resolveRotationScope(client, options) {
+  const oldTokenId = options.rotateTokenId;
+  const listOutput = await executeWithConfirmation(client, "mcp_token.list", { include_revoked: true });
+  const parsed = mcpTokenListOutputSchema.safeParse(listOutput);
+  if (!parsed.success) {
+    throw new Error("Could not read the token list to rotate \u2014 mcp_token.list returned an unexpected shape.");
+  }
+  const old = parsed.data.tokens.find((entry) => entry.token_id === oldTokenId);
+  if (!old) {
+    throw new Error(
+      `--rotate token id "${oldTokenId}" was not found in this tenant's tokens (nothing was minted). List ids with: ${cliBrand.binName} command mcp_token.list --json '{"include_revoked":true}'`
+    );
+  }
+  const userSpecifiedScope = options.seatId !== void 0 || options.scope === "seat";
+  if (userSpecifiedScope && options.scope !== old.scope) {
+    throw new Error(
+      `--rotate preserves the old token's scope (${old.scope}); the requested scope (${options.scope}) does not match. Omit --scope/--seat-id to rotate in place, or revoke and mint a new token with the different scope.`
+    );
+  }
+  if (old.scope === "seat" && options.seatId !== void 0 && options.seatId !== old.seat_id) {
+    throw new Error(
+      `--rotate preserves the old token's seat (${old.seat_id ?? "unknown"}); the requested --seat-id (${options.seatId}) does not match.`
+    );
+  }
+  if (old.scope === "seat") {
+    if (old.seat_id === null) {
+      throw new Error(`--rotate token "${oldTokenId}" is seat-scoped but has no seat id; cannot rotate it in place.`);
+    }
+    return { scope: "seat", seatId: old.seat_id };
+  }
+  return { scope: "tenant_admin" };
+}
+function expiryEcho(expiry) {
+  if (expiry.kind === "days") {
+    return `Expiry: ${expiry.days} day${expiry.days === 1 ? "" : "s"} from now.`;
+  }
+  if (expiry.kind === "none") {
+    return "Expiry: none (a ~100-year TTL \u2014 see the warning on stderr).";
+  }
+  return `Expiry: ${MCP_TOKEN_DEFAULT_EXPIRY_DAYS} days from now (default).`;
+}
+function expiryDescriptor(expiry) {
+  if (expiry.kind === "days") {
+    return { mode: "days", days: expiry.days };
+  }
+  if (expiry.kind === "none") {
+    return { mode: "none", days: null };
+  }
+  return { mode: "default", days: MCP_TOKEN_DEFAULT_EXPIRY_DAYS };
+}
+function revokeFailureReason(error51) {
+  if (error51 instanceof CommandClientError) {
+    return error51.message;
+  }
+  if (error51 instanceof Error) {
+    return error51.message;
+  }
+  return "unknown error";
 }
 async function createMcpToken(client, body) {
+  const output = await executeWithConfirmation(client, "mcp_token.create", body);
+  return mcpTokenOutputSchema.parse(output);
+}
+async function executeWithConfirmation(client, commandId, body) {
   try {
-    const result = await client.execute("mcp_token.create", body);
-    return mcpTokenOutputSchema.parse(result.output);
+    const result = await client.execute(commandId, body);
+    return result.output;
   } catch (error51) {
-    const pending = pendingMcpTokenConfirmation(error51);
+    const pending = pendingCommandConfirmation(error51, commandId);
     if (!pending) {
       throw error51;
     }
@@ -44325,10 +44486,10 @@ async function createMcpToken(client, body) {
       confirmation_id: pending.confirmationId
     });
     const approvalOutput = confirmationApprovalOutputSchema.parse(approved.output);
-    return mcpTokenOutputSchema.parse(approvalOutput.output);
+    return approvalOutput.output;
   }
 }
-function pendingMcpTokenConfirmation(error51) {
+function pendingCommandConfirmation(error51, commandId) {
   if (!(error51 instanceof CommandClientError) || error51.status !== 409 || !error51.response || error51.response.ok) {
     return null;
   }
@@ -44336,7 +44497,7 @@ function pendingMcpTokenConfirmation(error51) {
     return null;
   }
   const pending = pendingConfirmationSchema.safeParse(error51.response.error.details);
-  if (!pending.success || pending.data.commandId !== "mcp_token.create") {
+  if (!pending.success || pending.data.commandId !== commandId) {
     return null;
   }
   return pending.data;
@@ -44379,6 +44540,16 @@ function parseScope(value) {
   }
   throw new Error("MCP token scope must be tenant-admin or seat.");
 }
+function parseExpiresIn(value) {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`--expires-in must be a whole number of days (${MCP_TOKEN_MIN_EXPIRY_DAYS}..${MCP_TOKEN_MAX_EXPIRY_DAYS}).`);
+  }
+  const days = Number.parseInt(value, 10);
+  if (days < MCP_TOKEN_MIN_EXPIRY_DAYS || days > MCP_TOKEN_MAX_EXPIRY_DAYS) {
+    throw new Error(`--expires-in must be between ${MCP_TOKEN_MIN_EXPIRY_DAYS} and ${MCP_TOKEN_MAX_EXPIRY_DAYS} days.`);
+  }
+  return days;
+}
 function requireValue(args, index, flag) {
   const value = args[index + 1];
   if (!value) {
@@ -45964,7 +46135,7 @@ async function executeOnboard(io, client, args) {
 }
 async function executeMcp(io, client, appUrl2, args) {
   if (args[0] !== "install") {
-    io.stderr.write(`Usage: ${cliBrand.binName} mcp install --client claude-code|codex|cursor
+    io.stderr.write(`Usage: ${cliBrand.binName} mcp install --client claude-code|codex|cursor [--scope seat --seat-id <id>] [--expires-in <days>|--no-expiry] [--rotate <token-id>]
 `);
     return 1;
   }
@@ -46085,7 +46256,7 @@ function printUsage(io) {
     ...operationUsageLines(cliBrand.binName),
     `${cliBrand.binName} onboard status`,
     `${cliBrand.binName} onboard run`,
-    `${cliBrand.binName} mcp install --client claude-code|codex|cursor`,
+    `${cliBrand.binName} mcp install --client claude-code|codex|cursor [--scope seat --seat-id <id>] [--expires-in <days>|--no-expiry] [--rotate <token-id>]`,
     `${cliBrand.binName} init [--client claude-code|codex|cursor]`,
     `${cliBrand.binName} docs`,
     `${cliBrand.binName} reference <list|search|get> [options]`,