@ahrzb/personal-mcp-cli 0.1.0

package/dist/pmcp.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// cli/pmcp.mts — the executable face of cli/src/main.ts, nothing else lives here.
+// Run through the repo script:  pnpm pmcp <command …>   (flags that collide with
+// pnpm's own go after a `--`:  pnpm pmcp -- apply --yes), or without a clone via
+// the root package's bin:  npx github:ahrzb/personal-mcps <command …>  (needs a
+// Node whose type stripping is on by default, ≥22.18 / ≥23.6 — the shebang runs
+// this .mts file as-is).
+import { main } from "./src/main.mjs";
+
+// `exitCode`, not `exit()`: process.exit() tears the loop down mid-flight, and on Windows
+// Node ≤24.19 that aborts with a libuv assertion (src\win\async.c) once two or more fetch()
+// calls have run — nodejs/node#56645, fixed upstream only in v26.7.0. Letting the loop drain
+// costs ~1ms here; nothing in the CLI holds a handle open past the last await.
+process.exitCode = await main(process.argv.slice(2));

package/dist/src/commands.mjs

@@ -0,0 +1,98 @@
+/**
+ * cli/src/commands.ts — §10's command surface as DATA: every subcommand and what it
+ * fronts. main.ts dispatches through these names; `server/test/worker/contracts.test.ts`
+ * reads the table as the left-hand side of parity direction D (§4, §8).
+ *
+ * It is a module of its own rather than a `const` in main.ts because the parity suite is a
+ * reader of DATA, not of the CLI: main.ts reaches for node:fs and node:os to read the
+ * config file, and the suite that checks the mapping has no business loading that (it runs
+ * inside workerd, where those are a compatibility shim rather than a filesystem). Nothing
+ * here imports anything. main.ts re-exports the table, so a CLI consumer still finds it
+ * where the command surface lives.
+ */
+
+/**
+ * One row of the CLI's command table: an argv spelling and what it fronts.
+ *
+ * `ops` is the §8 admin ops the subcommand actually calls — the left-hand side of parity
+ * direction D. `method` is for the two commands that front the GATEWAY rather than an
+ * admin op: `pmcp tools` and `pmcp call` are the MCP tool surface itself (any agent
+ * holding the same token calls tools/list and tools/call directly), so they are not a CLI
+ * capability that needs a tool of its own — §8's exception list does not mention them
+ * because they are not an exception to it. `exception` names §8's pinned parity
+ * exceptions — the auth/credential family, the upstream-OAuth consent redirect, and
+ * `/audit`'s JSONL export — so a name that fronts no op of its own is always explicitly
+ * accounted for rather than skipped.
+ */
+                          
+               
+                         
+                  
+                                                        
+  
+
+/**
+ * Every subcommand of §10's surface, as data. A table rather than a switch so the mapping
+ * is inspectable from outside the CLI; main.ts dispatches through the same names.
+ */
+export const COMMANDS                        = [
+  { name: "login", ops: [], exception: "auth" },
+  { name: "logout", ops: [], exception: "auth" },
+  { name: "whoami", ops: [], exception: "auth" },
+  { name: "ls", ops: ["service_list"] },
+  { name: "tools", ops: [], method: "tools/list" },
+  { name: "call", ops: [], method: "tools/call" },
+  // §20.6 (added 2026-08-26): gateway sugar of exactly the same kind as the two rows above
+  // — they front an MCP method on the scoped endpoint, not an admin op, so they sit outside
+  // §8's parity list rather than inside it (§10's amendment note).
+  { name: "prompts", ops: [], method: "prompts/list" },
+  { name: "prompt", ops: [], method: "prompts/get" },
+  { name: "resources", ops: [], method: "resources/list" },
+  { name: "read", ops: [], method: "resources/read" },
+  // A tunneled service is unusable without its token, so §6's lifecycle makes this create
+  // two calls rather than one.
+  { name: "service create", ops: ["service_create", "token_issue"] },
+  { name: "service archive", ops: ["service_archive"] },
+  { name: "service unarchive", ops: ["service_unarchive"] },
+  { name: "service delete", ops: ["service_delete"] },
+  { name: "service disconnect", ops: ["service_disconnect"] },
+  { name: "service set-auth", ops: ["service_set_upstream_auth"] },
+  { name: "account list", ops: ["account_list"] },
+  { name: "account create", ops: ["account_create"] },
+  { name: "account delete", ops: ["account_delete"] },
+  { name: "approvals", ops: ["approval_list"] },
+  { name: "approve", ops: ["approval_decide"] },
+  { name: "reject", ops: ["approval_decide"] },
+  { name: "token issue", ops: ["token_issue"] },
+  { name: "token list", ops: ["token_list"] },
+  { name: "token revoke", ops: ["token_revoke"] },
+  { name: "audit", ops: ["audit_query"] },
+  // A serialization of the same query, not a new capability (§8's third pinned exception).
+  { name: "audit --export jsonl", ops: ["audit_query"], exception: "jsonl-export" },
+  // The consent REDIRECT is browser-only (§8); the command itself only checks the slug
+  // and prints the URL.
+  { name: "connect", ops: ["service_get"], exception: "oauth-consent" },
+  // §19/§8: the OAuth clients connected to this namespace (inbound OAuth, distinct from
+  // `connect`'s outbound upstream flow above). No exception here — unlike the consent
+  // SCREEN it manages, this pair is grants-shaped and fronts a real op each.
+  { name: "connections", ops: ["connection_list"] },
+  { name: "connection revoke", ops: ["connection_revoke"] },
+  { name: "diff", ops: ["service_list", "account_list"] },
+  {
+    name: "apply",
+    // The planner's whole vocabulary plus the two reads it plans against — `apply` is the
+    // only front for service_update and grant_set (§9: grants are declarative).
+    ops: [
+      "service_list",
+      "account_list",
+      "service_create",
+      "service_update",
+      "service_delete",
+      "service_archive",
+      "service_unarchive",
+      "account_create",
+      "account_delete",
+      "grant_set",
+    ],
+  },
+];

package/dist/src/config.mjs

@@ -0,0 +1,197 @@
+/**
+ * cli/src/config.ts — §10's profile store: where a hub identity lives between invocations,
+ * and which profile is ACTIVE for a given invocation.
+ *
+ * Parses and emits `~/.config/pmcp/config.toml` via smol-toml (§4 dependency), behind a
+ * wrapper whose contract is pinned by the implementation plan and cli/test/config-store.test.ts:
+ *
+ *   - A parse error never lets smol-toml's own message escape: every line of this file is a
+ *     live credential, and TomlError's message embeds the offending line's text. Only the
+ *     line NUMBER survives, in a message this module composes itself.
+ *   - Unknown keys — top-level or inside a `[profiles.<name>]` table — survive a
+ *     parse→emit round trip; this module never drops a hand-written key it does not
+ *     recognize (`bootstrap_secret` is the standing example, §12).
+ *   - Profiles are `Record<string, string>`. A non-string TOML value (an unquoted number,
+ *     bool, date, array, inline table) is stringified rather than rejected, so a file with
+ *     one odd hand-edited line still loads instead of failing the whole config.
+ *
+ * `configPath`/`readConfig`/`writeConfig`/`activeProfile`/`profileOf`/`applyProfile` are
+ * ports of the functions of the same name in `main.ts` (~lines 150-250) — same behavior,
+ * same precedence, same 0600 write. `resolveActiveProfile` is new: it names WHERE the active
+ * profile came from, for `profile list --json`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse as parseSmolToml, stringify as stringifySmolToml, TomlError } from "smol-toml";
+                                           
+
+/** One hub identity: `url`, `token`, and whatever else the operator wrote beside them. */
+                                                 
+
+/**
+ * The config file as data: the top-level `profile` key (which profile is active when
+ * nothing else selects one), the named profiles, and any other top-level key the file
+ * carried — kept as `unknown` because this module never interprets one.
+ */
+                          
+                   
+                                        
+                         
+  
+
+/** Where profile-list resolved its `name` from, most-specific first. */
+                                                                  
+
+/** The key order emitConfig writes inside a profile; everything else follows, sorted. */
+const PROFILE_KEYS = ["url", "token", "bootstrap_secret"];
+
+/** Where the profiles live between invocations (§10). */
+export function configPath()         {
+  return join(homedir(), ".config", "pmcp", "config.toml");
+}
+
+/**
+ * The file as it was before profiles: one flat `{ url, token }`. Read once as profile
+ * `default` and superseded by the next write (§10) — never rewritten, never deleted, so a
+ * downgrade still finds the session it left behind.
+ */
+export function legacyConfigPath()         {
+  return join(homedir(), ".config", "pmcp", "config.json");
+}
+
+/**
+ * Text → shape, via smol-toml, with the pinned parse-error contract: a `TomlError`'s own
+ * message (which embeds the offending line's text — a live credential) never escapes.
+ */
+export function parseConfig(text        )             {
+  let raw                           ;
+  try {
+    raw = parseSmolToml(text);
+  } catch (err) {
+    if (err instanceof TomlError) throw new Error(`config: line ${err.line} is not valid TOML`);
+    throw err;
+  }
+  const config             = { profiles: {} };
+  for (const [key, value] of Object.entries(raw)) {
+    if (key !== "profiles") config[key] = toStringValue(value);
+  }
+  if (isTable(raw.profiles)) {
+    for (const [name, profile] of Object.entries(raw.profiles)) {
+      if (!isTable(profile)) continue;
+      const entry              = {};
+      for (const [key, value] of Object.entries(profile)) entry[key] = toStringValue(value);
+      config.profiles[name] = entry;
+    }
+  }
+  return config;
+}
+
+/** Shape → text, via smol-toml. Known keys first in their declared order, then the rest sorted. */
+export function emitConfig(config            )         {
+  const table                            = {};
+  for (const key of ordered(Object.keys(config).filter((k) => k !== "profiles" && typeof config[k] === "string"), ["profile"])) {
+    table[key] = config[key]          ;
+  }
+  const profiles                            = {};
+  for (const name of Object.keys(config.profiles).sort()) {
+    const profile = config.profiles[name];
+    const entry                            = {};
+    for (const key of ordered(Object.keys(profile), PROFILE_KEYS)) entry[key] = profile[key];
+    profiles[name] = entry;
+  }
+  table.profiles = profiles;
+  return stringifySmolToml(table);
+}
+
+export function readConfig()             {
+  // A malformed config.toml is NOT swallowed: parseConfig names the line, and the caller
+  // prints it. Silently resolving to "not logged in" would send the user to `pmcp login`
+  // for a typo three lines up. The legacy json is best-effort — it is on its way out.
+  if (existsSync(configPath())) return parseConfig(readFileSync(configPath(), "utf8"));
+  if (!existsSync(legacyConfigPath())) return { profiles: {} };
+  try {
+    const flat = JSON.parse(readFileSync(legacyConfigPath(), "utf8"))                                    ;
+    return {
+      profile: "default",
+      profiles: {
+        default: { ...(flat.url === undefined ? {} : { url: flat.url }), ...(flat.token === undefined ? {} : { token: flat.token }) },
+      },
+    };
+  } catch {
+    return { profiles: {} };
+  }
+}
+
+export function writeConfig(config            )       {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true });
+  // 0600: the file holds a live session bearer — one per profile.
+  writeFileSync(path, emitConfig(config), { mode: 0o600 });
+}
+
+/**
+ * Which profile this invocation acts on: the `--profile` flag, else PMCP_PROFILE, else the
+ * file's own top-level `profile`, else the name `default` — neutral on purpose, since the
+ * CLI's users are not only developers with environments (§10).
+ */
+export function activeProfile(config            , flag         )         {
+  return flag ?? process.env.PMCP_PROFILE ?? config.profile ?? "default";
+}
+
+/** The active profile's stored values — `{}` when the file has no table by that name. */
+export function profileOf(config            , name        )              {
+  return config.profiles[name] ?? {};
+}
+
+/**
+ * The `pnpm users` bridge, called by scripts/users.mts: consumes a leading
+ * `--profile <name>`, fills PMCP_URL and BOOTSTRAP_SECRET from that profile wherever the
+ * environment has not already spoken, and returns the rest of argv. It lives here because
+ * the precedence lives here — scripts/users.ts stays env-only, which is its tested
+ * contract (§12), and gains a config file it never reads.
+ */
+export function applyProfile(argv          )           {
+  const rest = [...argv];
+  const flag = rest[0] === "--profile" ? rest.splice(0, 2)[1] : undefined;
+  const config = readConfig();
+  const profile = profileOf(config, activeProfile(config, flag));
+  for (const [variable, key] of [["PMCP_URL", "url"], ["BOOTSTRAP_SECRET", "bootstrap_secret"]]         ) {
+    // The environment wins where it is already set; an empty value is not set (users.ts
+    // reads it the same way), and `undefined` is never assigned — process.env would spell
+    // it as the string "undefined".
+    if ((process.env[variable] ?? "") === "" && (profile[key] ?? "") !== "") process.env[variable] = profile[key];
+  }
+  return rest;
+}
+
+/**
+ * Which profile a command resolves to, and WHERE that name came from — the same precedence
+ * as `activeProfile`, exposed for `profile list --json` (source ∈ flag/env/config/builtin).
+ */
+export function resolveActiveProfile(flagValue         )                                          {
+  if (flagValue !== undefined) return { name: flagValue, source: "flag" };
+  if (process.env.PMCP_PROFILE !== undefined) return { name: process.env.PMCP_PROFILE, source: "env" };
+  const config = readConfig();
+  if (config.profile !== undefined) return { name: config.profile, source: "config" };
+  return { name: "default", source: "builtin" };
+}
+
+/** Known keys in their declared order, then everything else alphabetically. */
+function ordered(keys          , known          )           {
+  const rank = (key        )         => (known.indexOf(key) === -1 ? known.length : known.indexOf(key));
+  return [...keys].sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : 1));
+}
+
+function isTable(value         )                                     {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+
+/** Non-string TOML values (numbers, booleans, dates, arrays, inline tables) are stringified. */
+function toStringValue(value           )         {
+  if (typeof value === "string") return value;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}

package/dist/src/errors.mjs

@@ -0,0 +1,173 @@
+/**
+ * cli/src/errors.ts — the frozen error contract (§10 "Errors"): one error type, one
+ * renderer, one did-you-mean helper. The code vocabulary below is FROZEN — prose may be
+ * reworded, a code may never be renamed, and the human/JSON grammar `emitError` produces
+ * is what every agent driving this CLI parses (§8: column-0 `error:`/`usage:`/`hint:`
+ * prefixes, never line counts).
+ *
+ * deps: none
+ */
+
+/** §10's stable snake_case code vocabulary. `usage` is the sole exit-2 code; every other
+ * code exits 1 (a well-formed command that fails at runtime or on the wire, never a
+ * malformed one). The vocabulary may grow; these nine may never be renamed. */
+                          
+           
+               
+                       
+                     
+                  
+                       
+                  
+                   
+            
+                                                                                           
+                                                                                           
+                                                                                        
+                                                                               
+                            
+
+/** Extra fields the JSON error document may carry, per code (§10): a not_found/invalid_arguments
+ * suggestion, and the tool's expected-arguments schema rendered from `inputSchema`. */
+                             
+                      
+                              
+                         
+  
+
+                               
+                                                                                          
+                 
+                                                                                           
+                   
+                                                                                         
+                                                                                              
+                    
+                        
+  
+
+/**
+ * The one error type every command throws to report a stable, agent-parseable failure.
+ * `exitCode` is derived from `code` at construction — `usage` is 2, everything else 1
+ * (§10) — so a caller never has to keep the two in sync by hand.
+ */
+export class CliError extends Error {
+  code              ;
+  exitCode       ;
+  usage         ;
+  hints          ;
+  detail          ;
+  extra                ;
+
+  constructor(code              , message        , opts                  = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = code === "usage" ? 2 : 1;
+    this.usage = opts.usage;
+    this.hints = opts.hints ?? [];
+    this.detail = opts.detail ?? [];
+    this.extra = opts.extra;
+  }
+}
+
+/** Any thrown value, normalized to a CliError: a CliError passes through unchanged; an
+ * unexpected Error (a hub failure that never got its own code, a network exception) becomes
+ * a bare `remote_error` carrying its message — never a stack trace, never `undefined`. */
+function toCliError(err         )           {
+  if (err instanceof CliError) return err;
+  if (err instanceof Error) return new CliError("remote_error", err.message);
+  return new CliError("remote_error", String(err));
+}
+
+/** Indents every line of `text` by `spaces` — a detail entry may already be a multi-line
+ * block (an arguments table under a did-you-mean line) whose own relative indentation
+ * must survive being nested one level deeper under the error line. */
+function indentBlock(text        , spaces        )         {
+  const pad = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => pad + line)
+    .join("\n");
+}
+
+                                
+                                                                                              
+                
+                                                                                             
+                                        
+  
+
+/**
+ * Renders `err` to `opts.stream` per §10's grammar and returns the process exit code, so a
+ * caller does one `process.exitCode = emitError(err, { json, stream: process.stderr })`.
+ *
+ * Human form: `error: <code>: <message>`, then each `detail` entry indented 2 spaces
+ * (column-0 is reserved for `error:`/`usage:`/`hint:` — every other line is human detail
+ * attached to the line above it, §8), then one `usage: …` line if present, then one
+ * `hint: …` line per hint, in order.
+ *
+ * JSON form: one `{"error":{code,message,hint?,didYouMean?,expectedArguments?}}` document —
+ * `hint` is the first of `hints` (the JSON reader gets the single actionable next step, not
+ * the human-only elaboration `detail` carries); `didYouMean`/`expectedArguments` ride
+ * straight from `extra` when present.
+ */
+export function emitError(err         , opts                  )        {
+  const cli = toCliError(err);
+  if (opts.json) {
+    const doc                          = { code: cli.code, message: cli.message };
+    if (cli.hints[0] !== undefined) doc.hint = cli.hints[0];
+    if (cli.extra?.didYouMean !== undefined) doc.didYouMean = cli.extra.didYouMean;
+    if (cli.extra?.expectedArguments !== undefined) doc.expectedArguments = cli.extra.expectedArguments;
+    opts.stream.write(`${JSON.stringify({ error: doc })}\n`);
+    return cli.exitCode;
+  }
+  const lines = [`error: ${cli.code}: ${cli.message}`];
+  for (const entry of cli.detail) lines.push(indentBlock(entry, 2));
+  if (cli.usage !== undefined) lines.push(`usage: ${cli.usage}`);
+  for (const hint of cli.hints) lines.push(`hint: ${hint}`);
+  opts.stream.write(`${lines.join("\n")}\n`);
+  return cli.exitCode;
+}
+
+/**
+ * The did-you-mean behind every `not_found` / `invalid_arguments` enrichment (§10). Two
+ * rules, prefix first: a candidate the input is a PREFIX of wins outright (shortest such
+ * candidate), because prefix-shaped exploration is how a human or an agent probes a catalog
+ * — `describe service/mcp-tools/paper` means `paper_fetch`, at edit distance 6, which no
+ * distance rule would ever suggest. Otherwise the closest candidate within edit distance ≤2,
+ * or `undefined`: a distance-3+ guess is worse than no suggestion. The prefix rule needs
+ * three characters, so a two-letter typo like `ur` stays with the distance rule that turns
+ * it into `url` rather than matching some unrelated `ur…`.
+ */
+export function didYouMean(input        , candidates                   )                     {
+  if (input.length >= 3) {
+    const prefixed = candidates.filter((candidate) => candidate !== input && candidate.startsWith(input));
+    if (prefixed.length > 0) return prefixed.reduce((a, b) => (b.length < a.length ? b : a));
+  }
+  let best                    ;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    const distance = levenshtein(input, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+  return bestDistance <= 2 ? best : undefined;
+}
+
+/** Classic single-row space-optimized edit distance — no dependency earns its keep for this. */
+function levenshtein(a        , b        )         {
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = row[j];
+      row[j] = a[i - 1] === b[j - 1] ? diagonal : 1 + Math.min(diagonal, row[j - 1], above);
+      diagonal = above;
+    }
+  }
+  return row[b.length];
+}