@wirecat/cli-template 0.15.0 → 0.17.0

package/src/commands/comments.ts

@@ -0,0 +1,167 @@
+import { CliError } from "@wirecat/cli-base"
+import { annotate } from "@wirecat/cli-base/commands"
+import {
+  answerEntity,
+  commandPath,
+  itemOf,
+  outputFor,
+  pagedList,
+  pageOf,
+  queryTerms,
+  REMOTE_READ,
+  REMOTE_WRITE,
+  renderAnswer,
+  termField,
+  terminalAsker,
+  withPaging,
+  withQuery,
+} from "@wirecat/cli-core/cli"
+import { guardedWrite, guardFor, keyedGuard, levelFor, newOperationId } from "@wirecat/cli-core/sends"
+import { Command } from "commander"
+import { permissions } from "../config.js"
+import { contextOf, withService } from "../context.js"
+import { IDENTITY } from "../identity.js"
+import { type Comment, type CommentsService, commentSchema } from "../sample/comments.js"
+import { SERVICE } from "../sample/transport.js"
+
+// SAMPLE: `comments` is the reference command group. Keep its shape; replace the noun and the calls with your
+// service's. Every command path is its own permission key (`comments.create`), from `commandPermissions()`.
+
+const CLI = IDENTITY.command
+
+/** The list's query: one field the service filters itself (WC-CMD-20). Nothing is filtered in memory. */
+const COMMENTS_QUERY = {
+  entity: "comment",
+  backend: "native",
+  fields: [termField("author", "kw", "author:u2")],
+} as const
+
+/** --all walks pages until the service has no more, at most this many, so a huge account cannot hold the run open. */
+const ALL_PAGES = 20
+const ALL_PAGE_SIZE = 100
+
+const listAll = async (service: CommentsService, author: string | undefined) => {
+  const items: Comment[] = []
+  for (let page = 0; page < ALL_PAGES; page++) {
+    const found = await service.list({ limit: ALL_PAGE_SIZE, offset: page * ALL_PAGE_SIZE, author })
+    for (const item of found.items) items.push(item)
+    if (!found.has_more) return { items, has_more: false }
+  }
+  return { items, has_more: true }
+}
+
+const listCommand = () =>
+  withPaging(
+    withQuery(
+      answerEntity(
+        annotate(new Command("list"), {
+          effects: REMOTE_READ,
+          offline: false,
+          examples: [`${CLI} personal comments list`, `${CLI} personal comments list author:u2 --json=id,text`],
+        }),
+        "comment",
+        commentSchema,
+      ),
+      COMMENTS_QUERY,
+    ),
+  )
+    .description(`list the comments in ${SERVICE}, newest first`)
+    .action(async function (this: Command, words: string[]) {
+      const path = commandPath(this)
+      const author = queryTerms(words, COMMENTS_QUERY, path).get("author")
+      const { settings } = contextOf(this)
+      const found = await withService(this, (service) =>
+        settings.all ? listAll(service, author) : service.list({ ...pageOf(settings), author }),
+      )
+      renderAnswer(this, outputFor(this), pagedList(path, settings, found))
+    })
+
+const showCommand = () =>
+  answerEntity(
+    annotate(new Command("show"), {
+      effects: REMOTE_READ,
+      offline: false,
+      examples: [`${CLI} personal comments show c1`, `${CLI} personal comments show c1 --json`],
+    }),
+    "comment",
+    commentSchema,
+  )
+    .description(`show one comment in ${SERVICE}`)
+    .argument("<id>", "the comment's id, as list prints it")
+    .action(async function (this: Command, id: string) {
+      renderAnswer(this, outputFor(this), itemOf(await withService(this, (service) => service.show(id))))
+    })
+
+/**
+ * Every write's one path (WC-PERM-13). The profile's level for the command's key refuses, or asks once; the send
+ * journal records the attempt and its outcome, never its content (WC-PERM-17); the answer carries the `operation_id`
+ * (WC-OUT-10). cli-core's `run` has already answered `--dry-run` and refused under `<PREFIX>_READ_ONLY` before this
+ * runs. Never retried: a write that got no answer is `outcome_unknown`, with the id to look it up by (WC-LIFE-9).
+ */
+const write = async (command: Command, act: (service: CommentsService) => Promise<Comment>) => {
+  const { settings, env, renderer } = contextOf(command)
+  const key = commandPath(command).replaceAll(" ", ".")
+  const operationId = newOperationId()
+  const levelOf = (one: string) => levelFor(settings.permissions, one, permissions.defaults).level
+  const guard = keyedGuard(
+    (ask) =>
+      guardFor(
+        IDENTITY,
+        // SAMPLE: the service limits its own rate, so this guard keeps the levels and the journal, not a send cap.
+        { ...settings, sendsPerHour: Number.MAX_SAFE_INTEGER, permissionDefaults: permissions.defaults },
+        renderer.warn,
+        env,
+        ask,
+      ),
+    terminalAsker(command),
+    levelOf,
+    [],
+  )
+  const request = { chatId: null, kind: "edit" as const, key, operationId }
+  guard.refuse(request)
+  let comment: Comment
+  try {
+    comment = await guardedWrite(guard, request, () => withService(command, act))
+  } catch (error) {
+    if (error instanceof CliError && error.code === "outcome_unknown")
+      throw new CliError("outcome_unknown", error.message, { ...error.details, operation_id: operationId })
+    throw error
+  }
+  renderAnswer(command, outputFor(command), itemOf({ operation_id: operationId, comment }))
+}
+
+const createCommand = () =>
+  annotate(new Command("create"), {
+    effects: REMOTE_WRITE,
+    offline: false,
+    examples: [
+      `${CLI} personal comments create --text "Looks good to me"`,
+      `${CLI} personal comments create --text "Looks good to me" --dry-run`,
+    ],
+  })
+    .description(`post a comment in ${SERVICE}`)
+    .requiredOption("--text <text>", "the comment's text")
+    .action(async function (this: Command, args: { text: string }) {
+      await write(this, (service) => service.create(args.text))
+    })
+
+const updateCommand = () =>
+  annotate(new Command("update"), {
+    effects: REMOTE_WRITE,
+    offline: false,
+    examples: [`${CLI} personal comments update c1 --text "Looks good now"`],
+  })
+    .description(`change the text of your comment in ${SERVICE}`)
+    .argument("<id>", "the comment's id, as list prints it")
+    .requiredOption("--text <text>", "the new text")
+    .action(async function (this: Command, id: string, args: { text: string }) {
+      await write(this, (service) => service.update(id, args.text))
+    })
+
+export const commentsCommand = (): Command =>
+  annotate(new Command("comments"), { effects: REMOTE_READ })
+    .description(`read and write comments in ${SERVICE}, the sample service`)
+    .addCommand(listCommand())
+    .addCommand(showCommand())
+    .addCommand(createCommand())
+    .addCommand(updateCommand())

package/src/commands/session.ts

@@ -0,0 +1,144 @@
+import { CliError } from "@wirecat/cli-base"
+import { annotate } from "@wirecat/cli-base/commands"
+import { readSecret } from "@wirecat/cli-core"
+import {
+  commandWords,
+  environmentOf,
+  FETCH,
+  itemOf,
+  LOCAL_READ,
+  LOCAL_WRITE,
+  listOf,
+  logsInOrOut,
+  outputFor,
+  profileFree,
+  profilesHere,
+  REMOTE_READ,
+  refuseCommandName,
+  refuseUnderReadOnly,
+  rememberAccount,
+  renderAnswer,
+  rootOf,
+  secretInputOf,
+} from "@wirecat/cli-core/cli"
+import { Command } from "commander"
+import { configuration } from "../config.js"
+import { contextOf, refuseOffline, serviceFor, withService } from "../context.js"
+import { IDENTITY } from "../identity.js"
+import { SERVICE } from "../sample/transport.js"
+import { TOKEN_VARIABLE, type TokenStorage, tokenStore } from "../token.js"
+
+// `session start | status | end | list` is every provider CLI's sign-in (WC-ACCT-12). Keep it; replace the token
+// prompt and the `me` check with your service's. A service with OAuth signs in through cli-core's oauth module
+// instead (WC-SECR-22); see gcal-cli's src/commands/session.ts.
+
+const CLI = IDENTITY.command
+
+const answer = (command: Command, item: unknown) => renderAnswer(command, outputFor(command), itemOf(item))
+
+const storageOf = (raw: string): TokenStorage => {
+  if (raw === "keyring" || raw === "file") return raw
+  throw new CliError("validation_error", `--credential-storage takes keyring or file; got ${raw}`)
+}
+
+const startCommand = () =>
+  logsInOrOut(
+    annotate(new Command("start"), {
+      effects: FETCH,
+      lifetime: "interactive",
+      mcp: false,
+      examples: [`${CLI} personal session start`, `${CLI} personal session start --credential-storage file`],
+    }),
+  )
+    .summary(`sign in to ${SERVICE} with an API token`)
+    .description(
+      `sign this profile in: the ${SERVICE} API token is asked hidden or read from stdin, never taken as an ` +
+        "argument, checked against the service, and only then kept in the keyring, or in a private file",
+    )
+    .option(
+      "--credential-storage <storage>",
+      "where the token is kept: keyring, which falls back to a private file by itself, or file",
+      storageOf,
+      "keyring" as TokenStorage,
+    )
+    .action(async function (this: Command, args: { credentialStorage: TokenStorage }) {
+      const { env, flags, profile, tokens, run } = contextOf(this)
+      refuseCommandName(profile, commandWords(rootOf(this)), CLI)
+      refuseOffline(flags)
+      // A secret is never an argument: it would land in shell history and in the run record (WC-SECR-5).
+      const token = (await readSecret(`${SERVICE} API token: `, secretInputOf(this))).trim()
+      if (!token) throw new CliError("validation_error", "no token was given")
+      const user = await run((events) => serviceFor(this, token, events).me())
+      const storedIn = tokens.write(profile, token, args.credentialStorage)
+      rememberAccount(IDENTITY, profile, user.id, env)
+      answer(this, { profile, state: "saved", stored_in: storedIn, verified: true, user })
+    })
+
+const statusCommand = () =>
+  annotate(new Command("status"), {
+    effects: REMOTE_READ,
+    examples: [`${CLI} personal session status`, `${CLI} personal session status --check --json`],
+  })
+    .summary("show where this profile's token comes from; never the token")
+    .description(
+      `show where this profile's token comes from: ${TOKEN_VARIABLE}, the keyring or a file, never the token; ` +
+        `--check asks ${SERVICE} whose token it is`,
+    )
+    .option("--check", `ask ${SERVICE} whether the token still works, and whose it is`)
+    .action(async function (this: Command, args: { check?: boolean }) {
+      const { profile, tokens } = contextOf(this)
+      const saved = tokens.read(profile)
+      const status = { profile, state: saved ? "saved" : "missing", token_from: saved?.source ?? null }
+      if (!args.check || !saved) return answer(this, { ...status, verified: false })
+      answer(this, { ...status, verified: true, user: await withService(this, (service) => service.me()) })
+    })
+
+const endCommand = () =>
+  logsInOrOut(
+    annotate(new Command("end"), {
+      effects: LOCAL_WRITE,
+      mcp: false,
+      examples: [`${CLI} personal session end`],
+    }),
+  )
+    .summary("forget this profile's token on this computer")
+    .description(`forget this profile's token on this computer; the token itself stays valid in ${SERVICE}`)
+    .action(function (this: Command) {
+      refuseUnderReadOnly(this, "session end")
+      const { profile, tokens } = contextOf(this)
+      answer(this, { profile, ended: tokens.remove(profile) })
+    })
+
+const listCommand = () =>
+  profileFree(
+    annotate(new Command("list"), {
+      effects: LOCAL_READ,
+      examples: [`${CLI} session list`, `${CLI} session list --json`],
+    }),
+  )
+    .summary("list the profiles here and whether each is signed in")
+    .description("list the profiles on this computer and whether each has a token; picks none")
+    .action(function (this: Command) {
+      const environment = environmentOf(this)
+      const env = environment.env ?? process.env
+      // biome-ignore lint/plugin/no-own-settings: baseContext needs a profile, and this local read names none
+      const { configuredProfiles } = configuration.resolveSettings({}, { env, needsProfile: false })
+      const tokens = tokenStore(env, environment.keyring, outputFor(this).renderer.warn)
+      const items = profilesHere(IDENTITY, configuredProfiles, env).map((profile) => {
+        const saved = tokens.read(profile)
+        return { profile, signed_in: saved !== undefined, token_from: saved?.source ?? null }
+      })
+      renderAnswer(
+        this,
+        outputFor(this),
+        listOf("session list", { items, limit: Math.max(1, items.length), has_more: false }),
+      )
+    })
+
+export const sessionCommand = (): Command =>
+  annotate(new Command("session"), { effects: LOCAL_READ })
+    .description(`keep this profile's ${SERVICE} token in the OS keyring`)
+    .addCommand(startCommand())
+    .addCommand(statusCommand())
+    .addCommand(endCommand())
+    .addCommand(listCommand())

package/src/comments.test.ts

@@ -0,0 +1,258 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { brokenKeyring, memoryKeyring } from "@wirecat/cli-base"
+import type { RunOptions } from "@wirecat/cli-core/cli"
+import { mcpOverStdio } from "@wirecat/cli-core/testing"
+import { afterEach, expect, it } from "vitest"
+import type { ServiceEnvironment } from "./context.js"
+import { run } from "./program.js"
+import { FAKE_TOKEN, fakeComments } from "./testing/fake-comments.js"
+import { runCli, signedIn } from "./testing/harness.js"
+import { holdsToken } from "./token.js"
+
+const configFile = join(process.env.CLIDEV_CONFIG_DIR ?? "", "config.json")
+const withPermissions = (permissions: Record<string, string>) => {
+  mkdirSync(join(configFile, ".."), { recursive: true })
+  writeFileSync(configFile, JSON.stringify({ profiles: { personal: { permissions } } }))
+}
+afterEach(() => rmSync(configFile, { force: true }))
+
+const filesUnder = (dir: string): string[] =>
+  readdirSync(dir, { recursive: true, encoding: "utf8" })
+    .map((name) => join(dir, name))
+    .filter((path) => statSync(path).isFile())
+
+it("lists comments in the answer's own shape, asking the service only what it documents", async () => {
+  const service = fakeComments()
+  const listed = await runCli(["personal", "comments", "list", "--json"], { service })
+  expect(listed.code).toBe(0)
+  expect(listed.json().items).toEqual([
+    { id: "c1", text: "First!", author: "Test Person u2", created_at: "2026-01-02T03:04:05Z" },
+    { id: "c2", text: "Agreed", author: "Test Person u3", created_at: "2026-01-02T03:04:05Z" },
+  ])
+  expect(service.refusals).toEqual([])
+  expect(service.calls.map((call) => call.url)).toEqual([
+    "https://comments.example.invalid/v1/comments?limit=20&offset=0",
+  ])
+})
+
+it("narrows the list with its query, pages it, and keeps only the --json fields asked for", async () => {
+  const service = fakeComments()
+  const narrowed = await runCli(["personal", "comments", "list", "author:u3", "--json=id,text"], { service })
+  expect(narrowed.json().items).toEqual([{ id: "c2", text: "Agreed" }])
+  const paged = await runCli(["personal", "comments", "list", "--limit", "1", "--page", "2", "--json"], { service })
+  expect(paged.json()).toMatchObject({ items: [{ id: "c2" }] })
+  expect(service.calls.at(-1)?.query).toEqual({ limit: "1", offset: "1" })
+  const all = await runCli(["personal", "comments", "list", "--all", "--json"], { service })
+  expect(all.json()).toMatchObject({ items: [{ id: "c1" }, { id: "c2" }] })
+  expect(service.refusals).toEqual([])
+})
+
+it("refuses a query field the list does not have, before any request", async () => {
+  const service = fakeComments()
+  const { code, json } = await runCli(["personal", "comments", "list", "colour:red", "--json"], { service })
+  expect(code).toBe(2)
+  expect(json()).toMatchObject({ error: { code: "validation_error" } })
+  expect(service.calls).toEqual([])
+})
+
+it("shows one comment, and says not_found for an id the service does not have", async () => {
+  expect((await runCli(["personal", "comments", "show", "c2", "--json"])).json().item).toMatchObject({ id: "c2" })
+  const missing = await runCli(["personal", "comments", "show", "c9", "--json"])
+  expect(missing.json()).toMatchObject({ error: { code: "not_found" } })
+})
+
+it("creates and updates a comment, each answer with its operation_id", async () => {
+  const service = fakeComments()
+  const created = await runCli(["personal", "comments", "create", "--text", "Plan", "--json"], { service })
+  expect(created.code).toBe(0)
+  expect(created.json().item).toMatchObject({ operation_id: expect.any(String), comment: { id: "c3", text: "Plan" } })
+  const updated = await runCli(["personal", "comments", "update", "c3", "--text", "Plans", "--json"], { service })
+  expect(updated.json().item).toMatchObject({ operation_id: expect.any(String), comment: { text: "Plans" } })
+  expect(service.refusals).toEqual([])
+  expect(service.calls.map((call) => call.body)).toEqual([{ body: "Plan" }, { body: "Plans" }])
+})
+
+it("--dry-run names the write's permission and sends nothing", async () => {
+  const service = fakeComments()
+  const preview = await runCli(["personal", "comments", "create", "--text", "Plan", "--dry-run", "--json"], { service })
+  expect(preview.code).toBe(0)
+  expect(preview.json().item).toMatchObject({ permission: { key: "comments.create" } })
+  expect(service.calls).toEqual([])
+})
+
+it("a deny on a read stops it before any request", async () => {
+  withPermissions({ "comments.list": "deny" })
+  const service = fakeComments()
+  const { code, json } = await runCli(["personal", "comments", "list", "--json"], { service })
+  expect(code).toBe(5)
+  expect(json()).toMatchObject({ error: { code: "permission_error" } })
+  expect(service.calls).toEqual([])
+})
+
+it("a deny on a write, or the read-only lock, stops it before any request", async () => {
+  const service = fakeComments()
+  withPermissions({ "comments.create": "deny" })
+  expect((await runCli(["personal", "comments", "create", "--text", "Plan", "--json"], { service })).code).toBe(5)
+  rmSync(configFile)
+  const locked = await runCli(["personal", "comments", "create", "--text", "Plan", "--json"], {
+    service,
+    env: { CLIDEV_READ_ONLY: "1" },
+  })
+  expect(locked.code).toBe(5)
+  expect(service.calls).toEqual([])
+})
+
+it("a write at ask asks once; no sends nothing, yes sends it", async () => {
+  withPermissions({ "comments.create": "ask" })
+  const service = fakeComments()
+  const asked: string[] = []
+  const answering = (reply: string) => (question: string) => {
+    asked.push(question)
+    return reply
+  }
+  const no = await runCli(["personal", "comments", "create", "--text", "Plan"], { service, answer: answering("n") })
+  expect(no.code).not.toBe(0)
+  expect(asked).toHaveLength(1)
+  expect(service.calls).toEqual([])
+  const yes = await runCli(["personal", "comments", "create", "--text", "Plan"], { service, answer: answering("y") })
+  expect(yes.code).toBe(0)
+  expect(asked).toHaveLength(2)
+  expect(service.calls).toHaveLength(1)
+})
+
+it("a write whose answer is lost is outcome_unknown with its operation_id, and is sent once", async () => {
+  const service = fakeComments({ loseNextWriteAnswer: true })
+  const lost = await runCli(["personal", "comments", "create", "--text", "Plan", "--json"], { service })
+  expect(lost.json()).toMatchObject({
+    error: { code: "outcome_unknown", details: { operation_id: expect.any(String) } },
+  })
+  expect(service.calls).toHaveLength(1)
+  expect(service.comments[0]?.body).toBe("Plan")
+})
+
+it("a write still in flight when --timeout ends the run is outcome_unknown, never a plain timeout", async () => {
+  const service = fakeComments({ hangWrites: true })
+  const cut = await runCli(["--timeout", "50ms", "personal", "comments", "create", "--text", "Plan", "--json"], {
+    service,
+  })
+  expect(cut.json()).toMatchObject({
+    error: { code: "outcome_unknown", details: { operation_id: expect.any(String) } },
+  })
+  expect(service.calls).toHaveLength(1)
+})
+
+it("a server failure is outcome_unknown for a write and retryable for a read", async () => {
+  const service = fakeComments({ failWith: 503 })
+  const write = await runCli(["personal", "comments", "create", "--text", "Plan", "--json"], { service })
+  expect(write.json()).toMatchObject({ error: { code: "outcome_unknown" } })
+  const read = await runCli(["personal", "comments", "list", "--json"], { service })
+  expect(read.json()).toMatchObject({ error: { code: "provider_unavailable", retry: { safe: true } } })
+  expect(service.calls).toHaveLength(2)
+})
+
+it("without a sign-in a command says how to sign in and sends nothing", async () => {
+  const service = fakeComments()
+  const { json } = await runCli(["personal", "comments", "list", "--json"], { service, keyring: memoryKeyring() })
+  expect(json()).toMatchObject({ error: { code: "authentication_error" } })
+  expect(JSON.stringify(json())).toContain("session start")
+  expect(service.calls).toEqual([])
+})
+
+it("--offline refuses a command that needs the service", async () => {
+  const service = fakeComments()
+  expect((await runCli(["--offline", "personal", "comments", "list", "--json"], { service })).code).toBe(5)
+  expect(service.calls).toEqual([])
+})
+
+it("a recorded run is named after the command and holds its request", async () => {
+  const listed = await runCli(["--record", "personal", "comments", "list", "--json"])
+  const runId = String((listed.json().meta as Record<string, unknown>).run_id)
+  expect(runId).toContain("comments")
+  expect(runId).not.toContain("-process-")
+  expect((await runCli(["runs", "show", runId, "--json"])).out).toContain("GET /comments")
+})
+
+it("session start reads the token from stdin and checks it before keeping it; status, list and end", async () => {
+  const keyring = memoryKeyring()
+  const service = fakeComments()
+  const started = await runCli(["personal", "session", "start", "--json"], { keyring, service, stdin: FAKE_TOKEN })
+  expect(started.json().item).toMatchObject({ verified: true, user: { id: "u1" } })
+  const status = await runCli(["personal", "session", "status", "--check", "--json"], { keyring, service })
+  expect(status.json().item).toMatchObject({ state: "saved", token_from: "keyring", verified: true })
+  expect((await runCli(["session", "list", "--json"], { keyring })).json().items).toContainEqual(
+    expect.objectContaining({ profile: "personal", signed_in: true }),
+  )
+  expect((await runCli(["personal", "session", "end", "--json"], { keyring })).code).toBe(0)
+  const ended = await runCli(["personal", "session", "status", "--json"], { keyring })
+  expect(ended.json().item).toMatchObject({ state: "missing" })
+})
+
+it("session start --credential-storage file keeps the token in a private file instead of the keyring", async () => {
+  const keyring = memoryKeyring()
+  const started = await runCli(["personal", "session", "start", "--credential-storage", "file", "--json"], {
+    keyring,
+    stdin: FAKE_TOKEN,
+  })
+  expect(started.json().item).toMatchObject({ stored_in: "file" })
+  const status = await runCli(["personal", "session", "status", "--json"], { keyring })
+  expect(status.json().item).toMatchObject({ token_from: "file" })
+  expect((await runCli(["personal", "session", "end", "--json"], { keyring })).json().item).toMatchObject({
+    ended: expect.arrayContaining(["file"]),
+  })
+})
+
+it("session start without a working keyring keeps the token in a private file, and says so on stderr", async () => {
+  const keyring = brokenKeyring()
+  const started = await runCli(["personal", "session", "start", "--json"], { keyring, stdin: FAKE_TOKEN })
+  expect(started.json().item).toMatchObject({ stored_in: "file" })
+  expect(started.err).toContain("keyring")
+  expect(holdsToken(process.env, "personal", keyring)).toBe(true)
+  expect((await runCli(["personal", "session", "end", "--json"], { keyring })).code).toBe(0)
+  expect(holdsToken(process.env, "personal", keyring)).toBe(false)
+})
+
+it("session start refuses a storage it does not know, before asking for the token", async () => {
+  const { code, err } = await runCli(["personal", "session", "start", "--credential-storage", "vault", "--json"])
+  expect(code).toBe(2)
+  expect(err).toContain("--credential-storage takes keyring or file")
+})
+
+it("session start keeps nothing when the service refuses the token", async () => {
+  const keyring = memoryKeyring()
+  const refused = await runCli(["personal", "session", "start", "--json"], { keyring, stdin: "wrong0token" })
+  expect(refused.json()).toMatchObject({ error: { code: "authentication_error" } })
+  const status = await runCli(["personal", "session", "status", "--json"], { keyring })
+  expect(status.json().item).toMatchObject({ state: "missing" })
+})
+
+it("the token reaches no address, output, run record or journal, whatever the outcome", async () => {
+  const service = fakeComments({ loseNextWriteAnswer: true })
+  const runs = [
+    await runCli(["personal", "session", "start", "--json"], { keyring: memoryKeyring(), stdin: FAKE_TOKEN }),
+    await runCli(["--record", "personal", "comments", "list", "--json"], { service }),
+    await runCli(["personal", "comments", "create", "--text", "Plan", "--json"], { service }),
+    await runCli(["personal", "comments", "show", "c9", "--json"], { service }),
+    await runCli(["personal", "comments", "list", "--json"], { service: fakeComments({ failWith: 401 }) }),
+  ]
+  for (const ran of runs) expect(ran.out + ran.err).not.toContain(FAKE_TOKEN)
+  for (const call of service.calls) expect(call.url).not.toContain(FAKE_TOKEN)
+  const folders = [...new Set([process.env.HOME ?? "", tmpdir()])]
+  const written = folders.flatMap(filesUnder).map((path) => readFileSync(path, "utf8"))
+  expect(written.some((text) => text.includes("GET /comments"))).toBe(true)
+  expect(written.some((text) => text.includes("comments.create"))).toBe(true)
+  expect(written.filter((text) => text.includes(FAKE_TOKEN))).toEqual([])
+})
+
+it("mcp serve runs a read for an agent with the run's keyring", async () => {
+  const service = fakeComments()
+  const options: RunOptions & ServiceEnvironment = { tty: false, keyring: signedIn(), fetch: service.fetch }
+  const mcp = await mcpOverStdio((streams) => run(["personal", "mcp", "serve"], { ...options, ...streams }))
+  try {
+    const listed = await mcp.call("clidev_read", { command: "comments list", arguments: { query: "author:u2" } })
+    expect(listed.body).toMatchObject({ items: [{ id: "c1" }] })
+  } finally {
+    expect(await mcp.close()).toBe(0)
+  }
+})

package/src/context.ts

@@ -0,0 +1,78 @@
+import { CliError } from "@wirecat/cli-base"
+import {
+  type BaseEnvironment,
+  baseContext,
+  type EventSink,
+  environmentOf,
+  type GlobalFlags,
+} from "@wirecat/cli-core/cli"
+import { Pacer, pacePathFor } from "@wirecat/cli-core/sends"
+import type { Command } from "commander"
+import { configuration } from "./config.js"
+import { IDENTITY } from "./identity.js"
+import { type CommentsService, commentsService } from "./sample/comments.js"
+import { SERVICE, transport } from "./sample/transport.js"
+import { tokenStore } from "./token.js"
+
+/** What a test hands `run()` beside cli-core's own: the fake service in place of the network (WC-ARCH-10). */
+export interface ServiceEnvironment extends BaseEnvironment {
+  fetch?: typeof fetch
+}
+
+// SAMPLE: your service's documented limit; this one is made up.
+const PACE = { perMinute: 120, burst: 20 }
+
+/**
+ * Settings, keyring and the run come from cli-core's `baseContext` and nowhere else: a command that resolves settings
+ * on its own skips `--timeout`, the run record and the profile's permissions (WC-LIFE-5, WC-LIFE-15).
+ */
+export const contextOf = (command: Command) => {
+  const base = baseContext(command, configuration.resolveSettings)
+  return {
+    ...base,
+    environment: environmentOf<ServiceEnvironment>(command),
+    flags: command.optsWithGlobals<GlobalFlags>(),
+    profile: base.settings.profile,
+    tokens: tokenStore(base.env, base.keyring, base.renderer.warn),
+  }
+}
+
+export const signInWords = (profile: string) => `\`${IDENTITY.command} ${profile} session start\``
+
+export const refuseOffline = (flags: GlobalFlags) => {
+  if (flags.offline)
+    throw new CliError("permission_error", `this needs ${SERVICE}; leave out --offline`, { reason: "offline.refused" })
+}
+
+/** The service for one run, with the token it was given; `events` comes from `run()`, so each request is recorded. */
+export const serviceFor = (command: Command, token: string, events: EventSink) => {
+  const { environment, env, profile } = contextOf(command)
+  return commentsService(
+    transport({
+      token,
+      events,
+      signal: environment.signal,
+      ...(environment.fetch ? { fetch: environment.fetch } : {}),
+      pacer: new Pacer(pacePathFor(IDENTITY, profile, env), PACE),
+    }),
+  )
+}
+
+/** The profile's saved token, or an authentication error that says how to sign in. Read before any request. */
+export const tokenOf = (command: Command): string => {
+  const { flags, profile, tokens } = contextOf(command)
+  refuseOffline(flags)
+  const saved = tokens.read(profile)
+  if (!saved)
+    throw new CliError("authentication_error", `profile ${profile} is not signed in — run ${signInWords(profile)}`)
+  return saved.secret
+}
+
+/**
+ * Every remote call goes through here: inside cli-core's run, so `--timeout` bounds it, a failure or `--record` keeps
+ * a run named after the command, and the transport's requests land in that run (WC-LIFE-5, WC-LIFE-15).
+ */
+export const withService = <T>(command: Command, body: (service: CommentsService) => Promise<T>): Promise<T> => {
+  const token = tokenOf(command)
+  return contextOf(command).run((events) => body(serviceFor(command, token, events)))
+}