@wirecat/cli-template 0.1.4 → 0.1.6

package/docs/commands.md

@@ -5,7 +5,7 @@
 Every command, option and exit code, generated from the program itself. For the same list as JSON, run
 `clidev commands --json`.
 
-**The first word is the profile**, a name you choose: `clidev personal doctor`. `CLIDEV_PROFILE`
+**The first word is the profile**, a name you choose: `clidev personal config show`. `CLIDEV_PROFILE`
 does the same for a whole shell session. No profile is assumed: a command that uses an account stops without one and
 lists the profiles on this computer.
 
@@ -62,7 +62,7 @@ clidev doctor
 
 **Returns:** check this installation: version, paths, config, profiles; no keyring or network
 
-**Example:** `clidev personal doctor`, `clidev personal doctor --json`
+**Example:** `clidev doctor`, `clidev doctor --json`
 
 ## `clidev skill`
 
@@ -166,7 +166,7 @@ clidev config set <setting> <value> [options]
 
 | Argument | | What it is |
 |---|---|---|
-| `setting` | required | one of: limit, timeout_ms, color, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, read_other_bots, update_check, skill_hint, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories.<name>, task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups.<name>. |
+| `setting` | required | one of: limit, timeout_ms, color, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, models, read_other_bots, update_check, skill_hint, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories.<name>, task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups.<name>. |
 | `value` | required | a number, true or false; for a group tg:work,max:Alice,email:me@x. |
 
 | Option | What it does |
@@ -191,7 +191,7 @@ clidev config unset <setting> [options]
 
 | Argument | | What it is |
 |---|---|---|
-| `setting` | required | one of: limit, timeout_ms, color, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, read_other_bots, update_check, skill_hint, default_profile, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories.<name>, task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups.<name>. |
+| `setting` | required | one of: limit, timeout_ms, color, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, models, read_other_bots, update_check, skill_hint, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories.<name>, task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups.<name>. |
 
 | Option | What it does |
 |---|---|
@@ -224,7 +224,7 @@ clidev runs list [query] [options]
 | `--limit <n>` | how many to show. Default: `20`. |
 | `--page <n>` | which page, starting at 1. Default: `1`. |
 
-**Returns:** run — run_id, command, profile, started_at, status, cli_version, completed_at, requests, and 15 more; every field: clidev commands info runs list
+**Returns:** run — run_id, command, started_at, status, cli_version, profile, completed_at, requests, and 20 more; every field: clidev commands info runs list
 
 **Example:** `clidev personal runs list --limit 10`
 
@@ -244,7 +244,7 @@ clidev runs show <run-id> [options]
 |---|---|
 | `--problems` | only failed responses, warnings and crashes. |
 
-**Returns:** run details — run_id, command, profile, started_at, status, cli_version, directory, event_count, and 14 more; every field: clidev commands info runs show
+**Returns:** run details — run_id, command, started_at, status, cli_version, directory, event_count, events, and 19 more; every field: clidev commands info runs show
 
 **Example:** `clidev personal runs show run-101`
 

package/docs/configuration.md

@@ -1,6 +1,6 @@
 # Settings
 
-Settings live in one file, `config.json`, in the folder `clidev personal doctor` shows. Each profile has its own part,
+Settings live in one file, `config.json`, in the folder `clidev doctor` shows. Each profile has its own part,
 and `defaults` apply to every profile. This page lists how to see and change them.
 
 ```sh

package/docs/dev/TESTING.md

@@ -12,5 +12,7 @@ How the tests run, and what they never touch. The rules are the handbook's
   `scripts/test-matrix-untested.ts`.
 - `pnpm contracts:check` runs the built CLI against `contracts/plan.json`: help, discovery, errors and the MCP tool
   list. `cli-contract contracts/plan.json --update` rewrites the snapshots; review the diff.
+- `pnpm contracts:upgrade` does not exist yet: the skeleton has no store of its own, and `.github/workflows/ci.yml`
+  skips the step. Add it with the first store, and remove the skip.
 - `pnpm smoke` installs the packed package into a temporary folder and runs it offline.
 - `pnpm audit:commands` audits the command tree beside the latest published WireCat CLIs.

package/docs/dev/reference-clis.md

@@ -15,5 +15,9 @@ A messenger CLI sets `messenger: true` in `src/identity.ts`, and `new --category
 category keeps the template's `messenger: false`, so the shared help, `commands` and `config` do not speak of chats,
 messages and senders.
 
-Until cli-core has a provider registry, a CLI made from this template is not listed as a provider of its own, and
-`search` finds its records as messages.
+cli-core keeps a provider registry (WC-ARCH-21). A CLI whose provider is not built into cli-core calls
+`registerProvider(store, { name, kind, aliases, command })` from `@wirecat/cli-core/store` on every run that opens
+the shared store. `kind` is one of `messages`, `mail`, `notes`, `documents`, `meetings` or `events`. Until the CLI
+has run once on a computer, `search` there leaves its accounts out and lists them under `skipped`. The reference CLIs
+do not show this call: their providers are built into cli-core. The skeleton opens no store and has no provider, so
+it registers nothing; the call comes with the CLI's first store code.

package/docs/dev/skills/release/SKILL.md

@@ -24,4 +24,4 @@ and runs `bin/release`.
    `package.json`, run `pnpm version:sync`, date the section as `## <version> — DD.MM.YYYY`, run
    `pnpm release:check` again, and open the pull request `chore(release): <version>`.
 7. **The owner** merges it and runs `bin/release` on a clean `main`. `bin/release --local` publishes from this
-   computer when GitHub Actions cannot, with the owner's own npm login or `NPM_TOKEN`.
+   computer when GitHub Actions cannot, with `NPM_TOKEN`, the npm token in the keyring, or the owner's own npm login.

package/docs/index.md

@@ -1,7 +1,7 @@
 # clidev
 
-`clidev` brings a service to the terminal, to scripts and to AI agents. This page is where a reader starts: say what
-the tool does, who it is for, and the first command to run. It will say that once the tool connects to its service.
+`clidev` is a WireCat command-line tool for the terminal, for scripts and for AI agents. It does not connect to a
+service yet.
 
-Today it has the commands every WireCat CLI shares: `doctor`, `commands`, `config`, `skill`, `mcp` and `upgrade`.
+It has the commands every WireCat CLI shares: `doctor`, `commands`, `config`, `skill`, `mcp`, `runs` and `upgrade`.
 Start with [installation](installation.md), then [usage](usage.md).

package/docs/installation.md

@@ -10,7 +10,7 @@ clidev --version
 Check the installation, then pick a profile name for your account, such as `personal`:
 
 ```sh
-clidev personal doctor
+clidev doctor
 ```
 
 `doctor` needs no network and opens no keyring. It shows the version, where settings live and the profiles that

package/docs/security.md

@@ -3,6 +3,6 @@
 What WireCat CLIs share — the keyring, permissions, MCP and what never reaches a log — is on the
 [shared security page](https://wirecat.dev/en/docs/security). This page keeps only what is particular to `clidev`.
 
-`clidev` keeps its settings in `config.json` and its state in the folders `clidev personal doctor` shows. It sends nothing
+`clidev` keeps its settings in `config.json` and its state in the folders `clidev doctor` shows. It sends nothing
 to any service yet. Report a vulnerability as [SECURITY.md](https://github.com/WireCatLabs/clidev-cli/blob/main/SECURITY.md)
 says.

package/docs/troubleshooting.md

@@ -5,10 +5,10 @@ support request.
 
 | Symptom | What to do |
 | --- | --- |
-| Not sure what is set up | Run `clidev personal doctor`. It reads no keyring and uses no network. |
+| Not sure what is set up | Run `clidev doctor`. It reads no keyring and uses no network. |
 | `clidev` is not found | Open a new terminal, and check that npm's global folder is on `PATH`. |
 | "name a profile" | Put the profile first, as in `clidev personal config show`, or set `CLIDEV_PROFILE`. |
-| The settings file does not read | `doctor` names the file and the error. Fix it, or move it away and set the values again. |
+| The settings file does not read | `doctor` lists every problem in the file under `config.issues`. Run the `config unset` each one gives, or fix the file by hand. |
 | A write is refused | The profile's permissions or `CLIDEV_READ_ONLY` stop it; see [settings](configuration.md#permissions). |
 
 Never paste a token, a password or private content into a support request.

package/docs/usage.md

@@ -15,7 +15,7 @@ command without one stops with exit code 2 and lists the profiles on this comput
 
 ## Output for scripts
 
-Every command takes `--json`, and prints one JSON value on stdout. Errors are JSON on stderr, with a code to branch
+Every command except `mcp` takes `--json`, and prints one JSON value on stdout. Errors are JSON on stderr, with a code to branch
 on. The [command reference](commands.md) lists the codes.
 
 ## Agents

package/kit/dist/main.js

@@ -65,6 +65,6 @@ const io = {
 main(process.argv.slice(2), io).then((text) => {
     process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
 }, (error) => {
-    process.stderr.write(`cli-template: ${error.message}\n`);
+    process.stderr.write(`cli-template: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1;
 });

package/kit/dist/manifest.js

@@ -19,7 +19,11 @@ const fail = (file, problem) => {
     throw new Error(`${file}: ${problem}`);
 };
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0);
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isPlaceholder = (key) => key in DEFAULT_PLACEHOLDERS;
+const isNames = (value) => isRecord(value) && ["name", "command", "package", "owner"].every((key) => typeof value[key] === "string");
+const isHashes = (value) => isRecord(value) && Object.values(value).every((hash) => typeof hash === "string");
+const isPending = (value) => isRecord(value) && typeof value.version === "string" && isHashes(value.files) && isStringList(value.conflicts);
 const checkEntries = (file, key, entries) => {
     for (const entry of entries) {
         if (entry.startsWith("/") || entry.split("/").includes(".."))
@@ -35,20 +39,18 @@ export const parseTemplateManifest = (file, raw) => {
         return fail(file, `"seeds" must be a list of paths`);
     checkEntries(file, "files", raw.files);
     checkEntries(file, "seeds", raw.seeds);
-    const placeholders = raw.placeholders ?? {};
-    if (!isRecord(placeholders))
+    const given = raw.placeholders ?? {};
+    if (!isRecord(given))
         return fail(file, `"placeholders" must be an object`);
-    for (const [key, value] of Object.entries(placeholders)) {
-        if (!(key in DEFAULT_PLACEHOLDERS))
-            fail(file, `unknown placeholder "${key}"`);
+    const placeholders = { ...DEFAULT_PLACEHOLDERS };
+    for (const [key, value] of Object.entries(given)) {
+        if (!isPlaceholder(key))
+            return fail(file, `unknown placeholder "${key}"`);
         if (typeof value !== "string" || value.length === 0)
-            fail(file, `placeholder "${key}" must be a string`);
+            return fail(file, `placeholder "${key}" must be a string`);
+        placeholders[key] = value;
     }
-    return {
-        files: raw.files,
-        seeds: raw.seeds,
-        placeholders: { ...DEFAULT_PLACEHOLDERS, ...placeholders },
-    };
+    return { files: raw.files, seeds: raw.seeds, placeholders };
 };
 export const parseCliManifest = (file, raw) => {
     if (!isRecord(raw))
@@ -58,29 +60,15 @@ export const parseCliManifest = (file, raw) => {
         return fail(file, `"template" must be the template's package name`);
     if (typeof version !== "string")
         return fail(file, `"version" must be the template version this CLI is on`);
-    if (!isRecord(names) || !["name", "command", "package", "owner"].every((key) => typeof names[key] === "string")) {
+    if (!isNames(names))
         return fail(file, `"names" must hold name, command, package and owner`);
-    }
-    if (!isRecord(files) || !Object.values(files).every((hash) => typeof hash === "string")) {
+    if (!isHashes(files))
         return fail(file, `"files" must map each template-owned path to its sha256`);
-    }
     if (!isStringList(seeds))
         return fail(file, `"seeds" must be a list of paths`);
-    if (pending !== undefined &&
-        (!isRecord(pending) ||
-            typeof pending.version !== "string" ||
-            !isRecord(pending.files) ||
-            !isStringList(pending.conflicts))) {
+    if (pending !== undefined && !isPending(pending))
         return fail(file, `"pending" must hold version, files and conflicts`);
-    }
-    return {
-        template,
-        version,
-        names: names,
-        files: files,
-        seeds,
-        ...(pending ? { pending: pending } : {}),
-    };
+    return { template, version, names, files, seeds, ...(pending ? { pending } : {}) };
 };
 export const readJson = async (path) => {
     const text = await readFile(path, "utf8").catch(() => fail(path, "not found"));

package/kit/dist/new.js

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 import { ask, choiceList, INTERVIEW, labelOf, NAME_QUESTIONS, parseAnswer } from "./interview.js";
-import { MANIFEST, sha256 } from "./manifest.js";
+import { isRecord, MANIFEST, sha256 } from "./manifest.js";
 import { PACKED_AS, renderTemplate } from "./source.js";
 const run = promisify(execFile);
 const REFERENCES = {
@@ -133,6 +133,8 @@ const removeKit = (command) => command
     .join(" && ");
 export const cliPackageJson = (text, names) => {
     const pkg = JSON.parse(text);
+    if (!isRecord(pkg))
+        throw new Error("package.json must be a JSON object");
     const isKit = (value) => typeof value === "string" && /^(\.\/)?kit(\/|$)/.test(value);
     const repoUrl = `git+https://github.com/${names.owner}/${names.name}.git`;
     const next = { ...pkg, name: names.package, version: "0.0.0" };
@@ -143,9 +145,9 @@ export const cliPackageJson = (text, names) => {
     };
     if (Array.isArray(pkg.files))
         next.files = pkg.files.filter((entry) => !isKit(entry) && !Object.values(PACKED_AS).includes(entry));
-    if (typeof pkg.scripts === "object" && pkg.scripts) {
+    if (isRecord(pkg.scripts)) {
         next.scripts = Object.fromEntries(Object.entries(pkg.scripts)
-            .filter(([key]) => !key.startsWith("kit:"))
+            .filter((entry) => typeof entry[1] === "string" && !entry[0].startsWith("kit:"))
             .map(([key, value]) => [key, removeKit(value)])
             .filter(([, value]) => value.length > 0));
     }
@@ -181,10 +183,10 @@ export const cliReadme = (names) => [
     "```sh",
     "pnpm install",
     "pnpm build",
-    `node dist/bin/${names.command}.js personal doctor`,
+    `node dist/bin/${names.command}.js doctor`,
     "```",
     "",
-    "`personal` is the profile: a name you choose for one account. Every command that uses an account starts with it.",
+    `\`doctor\` needs no profile. Every command that uses an account starts with one, a name you choose: \`${names.command} personal config show\`.`,
     "",
 ].join("\n");
 export const cliChangelog = (names, source) => [
@@ -214,7 +216,7 @@ export const markExecutable = async (cwd, paths) => {
 export const manualSteps = (names) => [
     `1. Create the repository ${names.owner}/${names.name} and its main ruleset (cli-base docs/standards/new-cli.md).`,
     `2. Set npm trusted publishing for ${names.package}, naming release.yml (WC-REL-11), and add any secrets.`,
-    "3. Pick a monthly cron day no other repository uses: .github/workflows/monthly.yml holds a placeholder CI rejects.",
+    "3. Give .github/workflows/monthly.yml a cron minute between 02:17 and 03:20 UTC that no other repository uses.",
     "4. WireCat CLIs only: a pull request to cli-base's PARITY_GROUPS, a line in cli-core's WIRECAT_TOOLS and in cli-docs' tools.json.",
 ];
 export const runNew = async (cwd, source, args, io) => {
@@ -264,7 +266,7 @@ export const runNew = async (cwd, source, args, io) => {
         "  pnpm ci:quick",
         "  git add -A",
         '  git commit -m "chore: start from @wirecat/cli-template"',
-        `  then give the agent docs/dev/DESIGN.md; every example passes a profile, e.g. ${names.command} personal doctor`,
+        `  then give the agent docs/dev/DESIGN.md; every account command passes a profile, e.g. ${names.command} personal config show`,
         "",
         "Four steps need a person:",
         ...manualSteps(names).map((step) => `  ${step}`),

package/kit/dist/rename.js

@@ -29,6 +29,7 @@ export const stripKit = (path, content) => {
         return content;
     const text = content.toString("utf8");
     const stripped = text
+        .replace(/^[ \t]*\/\/[^\n]*\n(?=[ \t]*"!?(\.\/)?kit\/)/gm, "")
         .replace(/\[\s*"!?(\.\/)?kit\/[^"]*"\s*\]/g, "[]")
         .replace(/,\s*"!?(\.\/)?kit\/[^"]*"/g, "")
         .replace(/"!?(\.\/)?kit\/[^"]*",\s*/g, "");

package/kit/dist/source.js

@@ -5,13 +5,13 @@ import { tmpdir } from "node:os";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { classify, MANIFEST, parseTemplateManifest, readJson, } from "./manifest.js";
+import { classify, isRecord, MANIFEST, parseTemplateManifest, readJson, } from "./manifest.js";
 import { renameContent, renamer, stripKit } from "./rename.js";
 const run = promisify(execFile);
 export const ownRoot = () => fileURLToPath(new URL("../../", import.meta.url));
 export const loadSource = async (root) => {
-    const pkg = (await readJson(join(root, "package.json")));
-    if (typeof pkg.name !== "string" || typeof pkg.version !== "string") {
+    const pkg = await readJson(join(root, "package.json"));
+    if (!isRecord(pkg) || typeof pkg.name !== "string" || typeof pkg.version !== "string") {
         throw new Error(`${join(root, "package.json")}: needs a name and a version`);
     }
     const manifestPath = join(root, MANIFEST);
@@ -82,7 +82,10 @@ export const npmCommand = (args) => {
 export const fetchPacked = async (spec) => {
     const dir = await mkdtemp(join(tmpdir(), "cli-template-"));
     const { stdout } = await run(...npmCommand(["pack", spec, "--silent", "--pack-destination", dir])).catch((error) => {
-        throw new Error(`could not download ${spec} from npm, which upgrade needs as the merge base: ${error.message}`);
+        const why = error instanceof Error ? error.message : String(error);
+        throw new Error(`could not download ${spec} from npm, which upgrade needs as the merge base: ${why}`, {
+            cause: error,
+        });
     });
     const tarball = stdout.trim().split("\n").pop() ?? "";
     const dispose = () => rm(dir, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-template",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Start a new WireCat CLI: a working skeleton on cli-base and cli-core, copied by new and kept current by upgrade",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -32,7 +32,7 @@
     "CHANGELOG.md",
     "CLAUDE.md",
     "LICENSE",
-    "README.md",
+    "/README.md",
     "SECURITY.md",
     ".gitattributes",
     ".gitleaks.toml",
@@ -43,9 +43,9 @@
     "lefthook.yml",
     "pnpm-workspace.yaml",
     "template.json",
-    "tsconfig.json",
+    "/tsconfig.json",
     "tsconfig.scripts.json",
-    "tsconfig.test.json",
+    "/tsconfig.test.json",
     "vitest.config.ts",
     "gitignore"
   ],
@@ -63,7 +63,7 @@
     "smoke": "node --experimental-strip-types scripts/smoke.ts",
     "smoke:bun": "bun scripts/smoke.ts",
     "package:check": "pnpm smoke",
-    "docs:check": "cli-dev docs-check --pages && cspell --no-progress --no-summary README.md 'docs/*.md' && rumdl check --config config/wirecat/rumdl.toml README.md CLAUDE.md AGENTS.md docs/*.md docs/dev/*.md && pnpm docs:lint",
+    "docs:check": "cli-dev docs-check --rules scripts/docs-rules.ts --pages && pnpm docs:spell && rumdl check --config config/wirecat/rumdl.toml README.md SECURITY.md CLAUDE.md AGENTS.md docs/*.md docs/dev/*.md && pnpm docs:lint",
     "docs:lint": "markdownlint-cli2",
     "contracts:check": "cli-contract contracts/plan.json",
     "security:no-leak": "cli-testing security no-leak . contracts/no-leak.json",
@@ -76,7 +76,7 @@
     "release:check": "pnpm standards:check && pnpm lint && pnpm typecheck && pnpm test:coverage && pnpm lint:commands && pnpm audit:commands && pnpm contracts:check && pnpm test:matrix:check && pnpm docs:check && pnpm generate:check && pnpm version:check",
     "prepare": "lefthook install || true",
     "prepack": "pnpm build",
-    "docs:spell": "cspell lint --config cspell.json --no-progress README.md",
+    "docs:spell": "cspell lint --config cspell.json --no-progress --no-summary README.md SECURITY.md 'docs/*.md'",
     "kit:build": "tsc -p kit && node -e \"require('node:fs').copyFileSync('.gitignore', 'gitignore')\"",
     "kit:typecheck": "tsc -p kit/tsconfig.test.json",
     "kit:e2e": "bash kit/e2e.sh"
@@ -84,7 +84,7 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.3.0",
     "@wirecat/cli-base": "0.53.0",
-    "@wirecat/cli-core": "0.422.0",
+    "@wirecat/cli-core": "0.426.0",
     "commander": "15.0.0"
   },
   "devDependencies": {

package/scripts/commands.ts

@@ -19,7 +19,7 @@ const page = commandsPage({
     intro: `Every command, option and exit code, generated from the program itself. For the same list as JSON, run
 \`${IDENTITY.command} commands --json\`.
 
-**The first word is the profile**, a name you choose: \`${IDENTITY.command} personal doctor\`. \`${IDENTITY.envPrefix}_PROFILE\`
+**The first word is the profile**, a name you choose: \`${IDENTITY.command} personal config show\`. \`${IDENTITY.envPrefix}_PROFILE\`
 does the same for a whole shell session. No profile is assumed: a command that uses an account stops without one and
 lists the profiles on this computer.`,
     globalHeading: "Options for every command",

package/scripts/docs-rules.ts

@@ -0,0 +1,15 @@
+import { type DocsRules, JOURNAL_IDS, markdownFiles } from "@wirecat/cli-base/release"
+
+export const CHANGELOG = {
+  headings: ["Added", "Changed — may break callers", "Fixed", "Security", "Removed"],
+  unreleased: "Unreleased",
+  ids: JOURNAL_IDS,
+}
+
+const USER_PAGES = /^(README|SECURITY)\.md$|^docs\/[^/]+\.md$/
+
+export const docsRules = (root: string): DocsRules => ({
+  files: markdownFiles(root, new Set(["node_modules", "dist", "coverage", ".git"])),
+  ids: JOURNAL_IDS,
+  userPage: (name) => USER_PAGES.test(name.replaceAll("\\", "/")),
+})

package/scripts/smoke.ts

@@ -1,11 +1,29 @@
 import assert from "node:assert/strict"
 import { execFileSync } from "node:child_process"
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join, resolve } from "node:path"
+import { packContents } from "@wirecat/cli-base/release"
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const isPackage = (value: unknown): value is { name: string; version: string; files: string[] } =>
+  isRecord(value) &&
+  typeof value.name === "string" &&
+  typeof value.version === "string" &&
+  Array.isArray(value.files) &&
+  value.files.every((entry) => typeof entry === "string")
 
 const root = resolve(import.meta.dirname, "..")
-const { name, version } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
+const pkg: unknown = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
+assert.ok(isPackage(pkg), "package.json needs a name, a version and a files list")
+const { name, version, files } = pkg
+// npm reads `files` like .gitignore: a name with no leading slash also matches the same name in any folder.
+const shipped = files
+  .map((entry) => entry.replace(/^\//, ""))
+  .map((entry) => (statSync(join(root, entry), { throwIfNoEntry: false })?.isDirectory() ? `${entry}/` : entry))
+assert.deepEqual(packContents(root, ["package.json", ...shipped], "package.json and the paths in its files list")(), [])
 const temp = mkdtempSync(join(tmpdir(), "clidev-package-"))
 try {
   const userConfig = join(temp, "npm-user-config")
@@ -42,12 +60,13 @@ try {
     execFileSync(process.execPath, [bin, ...args], { cwd: temp, env, encoding: "utf8", timeout: 20000 })
   assert.equal(run(["--version"]).trim(), version)
   assert.match(run(["--help"]), /Usage: clidev/)
-  const tree = JSON.parse(run(["commands", "--json"])) as { commands: { name: string }[] }
+  const tree: unknown = JSON.parse(run(["commands", "--json"]))
+  const names =
+    isRecord(tree) && Array.isArray(tree.commands)
+      ? tree.commands.map((command) => isRecord(command) && command.name)
+      : []
   for (const root of ["commands", "doctor", "skill", "mcp", "upgrade", "config"])
-    assert.ok(
-      tree.commands.some((command) => command.name === root),
-      `${root} is missing from the installed package`,
-    )
+    assert.ok(names.includes(root), `${root} is missing from the installed package`)
   assert.equal(JSON.parse(run(["doctor", "--json"])).item.version, version)
   assert.match(run(["skill", "show"]), /name: clidev-cli/)
   console.log(`installed ${name}@${version}: help, version, commands, doctor and skill answer offline`)

package/skills/clidev-cli/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: clidev-cli
-description: Use clidev, a WireCat CLI started from cli-template, from an agent — find a command, run it with the owner's profile, read JSON answers. Use when a task needs clidev; replace this description with what the tool does once it connects to its service.
+description: Use clidev, a WireCat CLI started from cli-template, from an agent — find a command, run it with the owner's profile, read JSON answers. Use when a task needs clidev. It does not connect to a service yet.
 ---
 
 # clidev
 
-Every account command starts with the owner's profile: `clidev personal doctor`. Never pick a profile yourself; if none
+Every account command starts with the owner's profile: `clidev personal config show`. Never pick a profile yourself; if none
 is given, run a command without one and read the profiles the error lists.
 
 Find your way with the tool itself, not this file:
 
 - `clidev commands --json` is the full command tree; `clidev commands config --json` one group.
 - `clidev help config set` is one command's help, with what it returns.
-- `clidev personal doctor --json` says what is set up on this computer.
+- `clidev doctor --json` says what is set up on this computer.
 
 ## Rules
 

package/src/commands/doctor.ts

@@ -1,7 +1,15 @@
 import { existsSync } from "node:fs"
 import { CliError, configFilePath, resolvePaths } from "@wirecat/cli-base"
 import { annotate } from "@wirecat/cli-base/commands"
-import { environmentOf, itemOf, LOCAL_READ, outputFor, readOnlyLockOf, renderAnswer } from "@wirecat/cli-core/cli"
+import {
+  environmentOf,
+  itemOf,
+  LOCAL_READ,
+  outputFor,
+  profileFree,
+  readOnlyLockOf,
+  renderAnswer,
+} from "@wirecat/cli-core/cli"
 import { Command } from "commander"
 import { configuration } from "../config.js"
 import { IDENTITY } from "../identity.js"
@@ -11,33 +19,42 @@ const failure = (error: unknown) => {
   throw error
 }
 
-/** It is run when everything else is broken, so an unreadable config is a field in the answer, never a throw. */
+/** It is run when everything else is broken, so a problem in the config file is a field in the answer, never a throw. */
 export const doctorReport = (env: NodeJS.ProcessEnv) => {
   const paths = resolvePaths({ appName: IDENTITY.appName, prefix: IDENTITY.envPrefix, env })
-  const file = configFilePath(paths.config)
-  let config: { path: string; exists: boolean; error?: string }
-  let profiles: string[] | null = null
-  try {
-    profiles = configuration.configuredProfiles({ env, readOnly: true })
-    config = { path: file, exists: existsSync(file) }
-  } catch (error) {
-    config = { path: file, exists: existsSync(file), error: failure(error) }
-  }
-  return {
+  const common = {
     version: IDENTITY.version,
     runtime: { node: process.versions.node, platform: process.platform },
     paths: { config: paths.config, state: paths.state, cache: paths.cache },
-    config,
-    profiles,
-    read_only: readOnlyLockOf(IDENTITY, env) ?? null,
+  }
+  const readOnly = readOnlyLockOf(IDENTITY, env) ?? null
+  try {
+    const settings = configuration.resolveSettings({}, { env, readOnly: true, needsProfile: false, withIssues: true })
+    return {
+      ...common,
+      config: { path: settings.configPath, found: settings.configFound, issues: settings.configIssues ?? [] },
+      profiles: settings.configuredProfiles,
+      read_only: readOnly,
+    }
+  } catch (error) {
+    const file = configFilePath(paths.config)
+    return {
+      ...common,
+      config: { path: file, found: existsSync(file), issues: [] },
+      settings: { error: failure(error) },
+      profiles: null,
+      read_only: readOnly,
+    }
   }
 }
 
 export const doctorCommand = (): Command =>
-  annotate(new Command("doctor"), {
-    effects: LOCAL_READ,
-    examples: [`${IDENTITY.command} doctor`, `${IDENTITY.command} personal doctor --json`],
-  })
+  profileFree(
+    annotate(new Command("doctor"), {
+      effects: LOCAL_READ,
+      examples: [`${IDENTITY.command} doctor`, `${IDENTITY.command} doctor --json`],
+    }),
+  )
     .description("check this installation: version, paths, config, profiles; no keyring or network")
     .action(function (this: Command) {
       const env = environmentOf(this).env ?? process.env

package/src/mcp.test.ts

@@ -78,7 +78,6 @@ it("clidev <profile> mcp starts the server and ends on a signal", async () => {
     tty: false,
     streams: { data: () => {}, diagnostic: () => {} },
   })
-  await new Promise((resolve) => setTimeout(resolve, 200))
   stop.abort()
   expect(await serving).toBe(0)
 })

package/src/mcp.ts

@@ -20,6 +20,9 @@ export interface McpOptions {
 
 const EXCLUDED = [["mcp"]]
 
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
 /** The shared three tools — search, read, write — over every command, writes included; the levels decide. */
 export const createMcpServer = (options: McpOptions): McpServer => {
   const server = new McpServer(
@@ -52,13 +55,13 @@ export const createMcpServer = (options: McpOptions): McpServer => {
         run: async (input) => {
           const answer = await runCommandForAgent(program, tool.path, input, context)
           if ("error" in answer) return mcpErrorResult(answer.error)
-          const value = (answer.result ?? {}) as Record<string, unknown>
+          const value = isObject(answer.result) ? answer.result : { result: answer.result }
           return { content: [{ type: "text" as const, text: JSON.stringify(value) }], structuredContent: value }
         },
       },
     ]),
   )
-  registerCommands(server, IDENTITY.command, commands)
+  registerCommands(server, IDENTITY.command, commands, undefined, undefined, IDENTITY.messenger)
   return server
 }
 
@@ -73,6 +76,8 @@ export const serveMcp = async (options: McpOptions): Promise<void> => {
         void server.close().then(resolve, reject)
       }
       options.signal?.addEventListener("abort", stop, { once: true })
+      // A stop that came while the server module was loading has already fired, and the listener never will.
+      if (options.signal?.aborted) stop()
       void server.connect(options.transport ?? new StdioServerTransport()).catch(reject)
     })
   } finally {