@ghostpaw/affinity 0.3.0 → 0.4.1

package/dist/cli.js

@@ -1,18 +1,32 @@
 #!/usr/bin/env node
-import { mkdirSync } from 'node:fs';
+import { readFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
+import { Writable } from 'node:stream';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/version.ts
+var affinityVersion;
+var init_version = __esm({
+  "src/version.ts"() {
+    affinityVersion = "0.4.1";
+  }
+});
+
 // src/lib/errors/affinity_error.ts
 var AffinityError;
 var init_affinity_error = __esm({
@@ -2478,21 +2492,6 @@ var init_unset_attribute = __esm({
   }
 });
 
-// src/tools/tool_summary.ts
-function summarizeCount(count, singular) {
-  if (count === 0) {
-    return `No ${singular}s found.`;
-  }
-  if (count === 1) {
-    return `Found 1 ${singular}.`;
-  }
-  return `Found ${count} ${singular}s.`;
-}
-var init_tool_summary = __esm({
-  "src/tools/tool_summary.ts"() {
-  }
-});
-
 // src/tools/tool_mutation.ts
 function mutationToolResult(action, receipt, entitySummary) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
@@ -2506,7 +2505,7 @@ function mutationToolResult(action, receipt, entitySummary) {
     affectedLinks: receipt.affectedLinks,
     derivedEffects: receipt.derivedEffects
   };
-  const summary = changedCount === 0 ? `No ${entitySummary} changes were needed.` : summarizeCount(changedCount, `${entitySummary} change`);
+  const summary = changedCount === 0 ? `No ${entitySummary} changes were needed.` : describeChanges(receipt);
   if (changedCount === 0) {
     return toolNoOp(summary, data, {
       entities: toReceiptEntityRefs(receipt)
@@ -2516,11 +2515,28 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+function describeChanges(receipt) {
+  const parts = [];
+  for (const verb of ["created", "updated", "archived", "removed"]) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const ref of receipt[verb]) {
+      counts.set(ref.kind, (counts.get(ref.kind) ?? 0) + 1);
+    }
+    if (counts.size === 0) continue;
+    const items = [...counts].map(
+      ([kind, n]) => `${n} ${n === 1 ? kind : PLURALS[kind] ?? `${kind}s`}`
+    );
+    parts.push(`${verb} ${items.join(", ")}`);
+  }
+  const text = parts.join("; ");
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}.`;
+}
+var PLURALS;
 var init_tool_mutation = __esm({
   "src/tools/tool_mutation.ts"() {
     init_tool_ref();
-    init_tool_summary();
     init_tool_types();
+    PLURALS = { identity: "identities" };
   }
 });
 
@@ -4282,13 +4298,20 @@ function createContact(db, input) {
     if (!KINDS.has(input.kind)) {
       throw new AffinityValidationError("invalid contact kind");
     }
+    if (input.isOwner !== void 0) {
+      throw new AffinityValidationError(
+        "isOwner is read-only; pass bootstrapOwner: true to create the owner contact"
+      );
+    }
     const now = resolveNow(input.now);
     if (input.bootstrapOwner) {
       const existing = db.prepare(
-        "SELECT id FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "SELECT id, name FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
       ).get();
       if (existing !== void 0) {
-        throw new AffinityConflictError("owner already exists");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -7391,6 +7414,21 @@ var init_list_dismissed_duplicates = __esm({
   }
 });
 
+// src/tools/tool_summary.ts
+function summarizeCount(count, singular) {
+  if (count === 0) {
+    return `No ${singular}s found.`;
+  }
+  if (count === 1) {
+    return `Found 1 ${singular}.`;
+  }
+  return `Found ${count} ${singular}s.`;
+}
+var init_tool_summary = __esm({
+  "src/tools/tool_summary.ts"() {
+  }
+});
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {
@@ -8177,7 +8215,7 @@ var init_tool_registry = __esm({
 });
 
 // src/surface/affinity_surface_tools.ts
-var affinitySurfaceTools;
+var affinitySurfaceTools, mapping, affinityCliSurfaceTools;
 var init_affinity_surface_tools = __esm({
   "src/surface/affinity_surface_tools.ts"() {
     init_tool_registry();
@@ -8191,83 +8229,67 @@ var init_affinity_surface_tools = __esm({
       inputSchema: { ...tool.inputSchema, type: "object" },
       handler: tool.handler
     }));
-  }
-});
-
-// src/surfaces/surface_types.ts
-function isErrorResult(result) {
-  return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
-}
-var init_surface_types = __esm({
-  "src/surfaces/surface_types.ts"() {
-  }
-});
-
-// src/surfaces/validate_input.ts
-function validateInput(schema, input, path = "$") {
-  const errors = [];
-  const matchesType = (type) => {
-    switch (type) {
-      case "object":
-        return typeof input === "object" && input !== null && !Array.isArray(input);
-      case "array":
-        return Array.isArray(input);
-      case "integer":
-        return typeof input === "number" && Number.isInteger(input);
-      case "number":
-        return typeof input === "number" && Number.isFinite(input);
-      case "null":
-        return input === null;
-      default:
-        return typeof input === type;
-    }
-  };
-  if (schema.type && !(Array.isArray(schema.type) ? schema.type : [schema.type]).some(
-    matchesType
-  )) {
-    return [`${path}: expected ${String(schema.type)}`];
-  }
-  if (schema.enum && !schema.enum.some(
-    (value) => JSON.stringify(value) === JSON.stringify(input)
-  ))
-    errors.push(`${path}: expected one of ${JSON.stringify(schema.enum)}`);
-  if (schema.oneOf && !schema.oneOf.some(
-    (branch) => validateInput(branch, input, path).length === 0
-  ))
-    errors.push(`${path}: must match at least one schema branch`);
-  if (typeof input === "object" && input !== null && !Array.isArray(input)) {
-    const record = input;
-    for (const name of schema.required ?? [])
-      if (!Object.hasOwn(record, name))
-        errors.push(`${path}.${name}: required`);
-    for (const [name, property] of Object.entries(schema.properties ?? {}))
-      if (Object.hasOwn(record, name))
-        errors.push(
-          ...validateInput(property, record[name], `${path}.${name}`)
-        );
-  }
-  if (Array.isArray(input) && schema.items)
-    input.forEach((value, index) => {
-      errors.push(
-        ...validateInput(
-          schema.items,
-          value,
-          `${path}[${index}]`
-        )
-      );
-    });
-  return errors;
-}
-var init_validate_input = __esm({
-  "src/surfaces/validate_input.ts"() {
-  }
-});
-
-// src/version.ts
-var affinityVersion;
-var init_version = __esm({
-  "src/version.ts"() {
-    affinityVersion = "0.3.0";
+    mapping = {
+      search_affinity: { verb: "search", positionals: ["query"] },
+      review_affinity: { verb: "review", positionals: ["view"] },
+      inspect_affinity_item: { verb: "show", positionals: ["kind"] },
+      manage_contact: {
+        noun: "contact",
+        verb: "manage",
+        action: {
+          property: "action",
+          verbs: { set_lifecycle: "lifecycle" },
+          positionals: {
+            create: ["input"],
+            revise: ["contact"],
+            set_lifecycle: ["contact", "lifecycleState"]
+          }
+        }
+      },
+      merge_contacts: { noun: "contact", verb: "merge" },
+      manage_duplicate_dismissal: { noun: "duplicate", verb: "manage" },
+      manage_identity: {
+        noun: "identity",
+        verb: "manage",
+        action: {
+          property: "action",
+          positionals: {
+            revise: ["identityId"],
+            verify: ["identityId"],
+            remove: ["identityId"]
+          }
+        }
+      },
+      manage_relationship: {
+        noun: "relationship",
+        verb: "manage",
+        action: {
+          property: "action",
+          verbs: {
+            seed_social_link: "add",
+            revise_bond: "bond",
+            override_state: "state",
+            set_structural_tie: "tie",
+            remove_structural_tie: "untie"
+          }
+        }
+      },
+      record_event: { noun: "event", verb: "record" },
+      manage_commitment: { noun: "commitment", verb: "manage" },
+      manage_date_anchor: {
+        noun: "date",
+        verb: "manage",
+        action: {
+          property: "action",
+          positionals: { revise: ["anchorEventId"], remove: ["anchorEventId"] }
+        }
+      },
+      manage_attribute: { noun: "attribute", verb: "manage" }
+    };
+    affinityCliSurfaceTools = /* @__PURE__ */ affinitySurfaceTools.map((tool) => ({
+      ...tool,
+      ...mapping[tool.name] ? { cli: mapping[tool.name] } : {}
+    }));
   }
 });
 
@@ -8812,6 +8834,75 @@ var init_resolve_affinity_db_path = __esm({
   }
 });
 
+// src/surfaces/surface_types.ts
+function isErrorResult(result) {
+  return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
+}
+var init_surface_types = __esm({
+  "src/surfaces/surface_types.ts"() {
+  }
+});
+
+// src/surfaces/validate_input.ts
+function validateInput(schema, input, path = "$") {
+  const errors = [];
+  const matchesType = (type) => {
+    switch (type) {
+      case "object":
+        return typeof input === "object" && input !== null && !Array.isArray(input);
+      case "array":
+        return Array.isArray(input);
+      case "integer":
+        return typeof input === "number" && Number.isInteger(input);
+      case "number":
+        return typeof input === "number" && Number.isFinite(input);
+      case "null":
+        return input === null;
+      default:
+        return typeof input === type;
+    }
+  };
+  if (schema.type && !(Array.isArray(schema.type) ? schema.type : [schema.type]).some(
+    matchesType
+  )) {
+    return [`${path}: expected ${String(schema.type)}`];
+  }
+  if (schema.enum && !schema.enum.some(
+    (value) => JSON.stringify(value) === JSON.stringify(input)
+  ))
+    errors.push(`${path}: expected one of ${JSON.stringify(schema.enum)}`);
+  if (schema.oneOf && !schema.oneOf.some(
+    (branch) => validateInput(branch, input, path).length === 0
+  ))
+    errors.push(`${path}: must match at least one schema branch`);
+  if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+    const record = input;
+    for (const name of schema.required ?? [])
+      if (!Object.hasOwn(record, name))
+        errors.push(`${path}.${name}: required`);
+    for (const [name, property] of Object.entries(schema.properties ?? {}))
+      if (Object.hasOwn(record, name))
+        errors.push(
+          ...validateInput(property, record[name], `${path}.${name}`)
+        );
+  }
+  if (Array.isArray(input) && schema.items)
+    input.forEach((value, index) => {
+      errors.push(
+        ...validateInput(
+          schema.items,
+          value,
+          `${path}[${index}]`
+        )
+      );
+    });
+  return errors;
+}
+var init_validate_input = __esm({
+  "src/surfaces/validate_input.ts"() {
+  }
+});
+
 // src/surfaces/mcp_server.ts
 function createMcpServer(options) {
   let initialized = false;
@@ -9026,7 +9117,7 @@ function affinityMcpOptions(context) {
     annotations: (tool) => ({
       readOnlyHint: tool.readOnly ?? false,
       destructiveHint: tool.name === "merge_contacts" || /remove|unset|undismiss/.test(
-        JSON.stringify(tool.inputSchema.properties?.action?.enum ?? [])
+        String(tool.inputSchema.properties?.action?.enum ?? [])
       ),
       idempotentHint: tool.readOnly ?? false,
       openWorldHint: false
@@ -9929,29 +10020,434 @@ var init_affinity_skill_spec = __esm({
       packageName: "@ghostpaw/affinity",
       server: "ghostpaw-affinity",
       about: affinityMcpInstructions,
-      tools: affinitySurfaceTools,
+      tools: affinityCliSurfaceTools,
       workflows: affinitySkills,
       principles: affinitySoulTraits.map((trait) => trait.principle)
     };
   }
 });
 
-// src/cli.ts
+// src/surface/affinity_cli_options.ts
+init_version();
 init_affinity_surface_tools();
+var affinityCliOptions = {
+  bin: "ghostpaw-affinity",
+  version: affinityVersion,
+  description: "Local relationship model and social CRM",
+  tools: affinityCliSurfaceTools,
+  openContext: async (options) => {
+    const { openAffinityDb: openAffinityDb2 } = await Promise.resolve().then(() => (init_open_affinity_db(), open_affinity_db_exports));
+    const { resolveAffinityDbPath: resolveAffinityDbPath2 } = await Promise.resolve().then(() => (init_resolve_affinity_db_path(), resolve_affinity_db_path_exports));
+    return openAffinityDb2(
+      resolveAffinityDbPath2(
+        options.db === void 0 ? {} : { flag: options.db }
+      )
+    );
+  },
+  closeContext: (db) => db.close(),
+  commands: {
+    mcp: async (options) => {
+      const { serveAffinityMcp: serveAffinityMcp2 } = await Promise.resolve().then(() => (init_serve_affinity_mcp(), serve_affinity_mcp_exports));
+      await serveAffinityMcp2(
+        options.db === void 0 ? {} : { dbPath: options.db }
+      );
+    },
+    skill: async () => {
+      const { renderSkillMarkdown: renderSkillMarkdown2 } = await Promise.resolve().then(() => (init_skill_markdown(), skill_markdown_exports));
+      const { affinitySkillSpec: affinitySkillSpec2 } = await Promise.resolve().then(() => (init_affinity_skill_spec(), affinity_skill_spec_exports));
+      return renderSkillMarkdown2(affinitySkillSpec2);
+    }
+  }
+};
+var CliUsageError = class extends Error {
+  exitCode = 2;
+};
+var keyOf = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+function parseCliArgs(argv, spec) {
+  const values = {};
+  const positions = [];
+  const flags = spec.flags ?? [];
+  const convert = (raw, arg) => {
+    let value = raw;
+    if (raw.startsWith("@")) {
+      try {
+        value = readFileSync(raw.slice(1), "utf8");
+      } catch {
+        throw new CliUsageError(`Cannot read value file: ${raw.slice(1)}`);
+      }
+    }
+    let result = value;
+    if (arg.type === "number" || arg.type === "integer") {
+      result = Number(value);
+      if (!value.trim() || !Number.isFinite(result) || arg.type === "integer" && !Number.isInteger(result))
+        throw new CliUsageError(
+          `Expected ${arg.type} for ${arg.name}: ${value}`
+        );
+    } else if (arg.type === "boolean") {
+      if (!["true", "false"].includes(value))
+        throw new CliUsageError(`Expected boolean for ${arg.name}`);
+      result = value === "true";
+    } else if (arg.type === "json") {
+      try {
+        result = JSON.parse(value);
+      } catch {
+        throw new CliUsageError(`Invalid JSON for ${arg.name}`);
+      }
+    }
+    if (arg.enum && !arg.enum.includes(result))
+      throw new CliUsageError(
+        `${arg.name} must be one of: ${arg.enum.join(", ")}`
+      );
+    return result;
+  };
+  let ended = false;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!ended && token === "--") {
+      ended = true;
+      continue;
+    }
+    if (ended || token === "-" || !token.startsWith("-")) {
+      positions.push(token);
+      continue;
+    }
+    const [flag, inline] = token.split(/=(.*)/s);
+    const negative = flag?.startsWith("--no-");
+    const name = flag?.replace(/^--?/, "").replace(/^no-/, "");
+    const arg = flags.find(
+      (entry) => entry.name === name || keyOf(entry.name) === name || entry.short === name
+    );
+    if (!arg) {
+      const prefix = (name ?? "").slice(0, 3);
+      const suggestion = prefix ? flags.find((entry) => entry.name.startsWith(prefix)) : void 0;
+      throw new CliUsageError(
+        `Unknown flag: ${flag}${suggestion ? `; did you mean --${suggestion.name}?` : ""}`
+      );
+    }
+    if (negative && arg.type !== "boolean")
+      throw new CliUsageError(`--no-${arg.name} requires a boolean flag`);
+    let raw = inline;
+    if (arg.type === "boolean" && raw === void 0)
+      raw = negative ? "false" : "true";
+    if (raw === void 0) {
+      const next = argv[i + 1];
+      if (next === void 0 || /^--[a-z]/i.test(next))
+        throw new CliUsageError(`Missing value: --${arg.name}`);
+      raw = next;
+      i++;
+    }
+    const key = keyOf(arg.name);
+    if (arg.type === "array") {
+      const item = convert(raw, { ...arg, type: arg.itemType ?? "string" });
+      values[key] = [...values[key] ?? [], item];
+    } else values[key] = convert(raw, arg);
+  }
+  let index = 0;
+  for (const arg of spec.positionals ?? []) {
+    if (index >= positions.length) continue;
+    values[keyOf(arg.name)] = arg.variadic ? positions.slice(index).map(
+      (value) => convert(value, { ...arg, type: arg.itemType ?? arg.type })
+    ) : convert(positions[index], arg);
+    index = arg.variadic ? positions.length : index + 1;
+  }
+  if (index < positions.length)
+    throw new CliUsageError(`Unexpected positional: ${positions[index]}`);
+  for (const arg of [...flags, ...spec.positionals ?? []]) {
+    if (arg.required && values[keyOf(arg.name)] === void 0)
+      throw new CliUsageError(`Missing required argument: ${arg.name}`);
+  }
+  return values;
+}
+function renderCliHelp(spec) {
+  const describe = (arg) => `${arg.type}${arg.enum ? ` (${arg.enum.join("|")})` : ""}${arg.required ? " required" : ""}  ${arg.description ?? ""}`;
+  return `Usage: ${spec.command} ${(spec.positionals ?? []).map((arg) => `<${arg.name}${arg.variadic ? "..." : ""}>`).join(" ")} [flags]
+${spec.description ?? ""}
+
+Positionals:
+${(spec.positionals ?? []).map((arg) => `  ${arg.name}  ${describe(arg)}`).join("\n")}
+Flags:
+${(spec.flags ?? []).map((arg) => `  --${arg.name}${arg.short ? `, -${arg.short}` : ""}  ${describe(arg)}`).join("\n")}
+`;
+}
+
+// src/surfaces/cli_commands.ts
+init_validate_input();
+function cliCommands(tools) {
+  return tools.flatMap((tool) => {
+    const split = tool.name.indexOf("_");
+    const cli = tool.cli ?? {
+      noun: tool.name.slice(split + 1),
+      verb: tool.name.slice(0, split)
+    };
+    const action = cli.action ?? (tool.inputSchema.properties?.action?.enum ? { property: "action" } : void 0);
+    const actions = action ? tool.inputSchema.properties?.[action.property]?.enum ?? [] : [void 0];
+    return actions.map((value) => {
+      const verb = value === void 0 ? cli.verb : action?.verbs?.[String(value)] ?? String(value);
+      return {
+        tool,
+        path: [cli.noun, verb].filter(Boolean).join(" "),
+        fixed: action && value !== void 0 ? { [action.property]: value } : {},
+        positionals: action?.positionals?.[String(value)] ?? cli.positionals ?? []
+      };
+    });
+  });
+}
+async function runCliCommand(argv, options) {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const stdin = options.stdin ?? process.stdin;
+  const args = [...argv];
+  const tree = cliCommands(options.tools);
+  let json = argv.includes("--json");
+  let quiet = argv.includes("--quiet");
+  let compact = false;
+  let help = false;
+  let db;
+  const fail = (message, code) => {
+    stderr.write(`${message}
+`);
+    if (json && !quiet)
+      stdout.write(
+        `${JSON.stringify({ ok: false, error: { code: code === 2 ? "usage_error" : "internal_error", message } })}
+`
+      );
+    return code;
+  };
+  const legacy = ["tools", "describe", "call", "mcp", "skill"];
+  let first;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--db") {
+      i++;
+      continue;
+    }
+    if (token.startsWith("-")) continue;
+    first = token;
+    break;
+  }
+  if (legacy.includes(first ?? "") || options.tools.some(
+    (tool) => tool.name.replace(/[-_]/g, "") === first?.replace(/[-_]/g, "")
+  ))
+    return void 0;
+  try {
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--") break;
+      if (flag === "--db" || flag?.startsWith("--db=")) {
+        db = flag === "--db" ? args.splice(i + 1, 1)[0] : flag.slice(5);
+        if (!db || db.startsWith("--"))
+          throw new CliUsageError("--db requires a path");
+      } else if (flag === "--json") json = true;
+      else if (flag === "--quiet") quiet = true;
+      else if (flag === "--compact") compact = true;
+      else if (flag === "--help" || flag === "-h") help = true;
+      else if (["--version", "-V", "-v"].includes(flag ?? "")) {
+        if (!quiet) stdout.write(`${options.version}
+`);
+        return 0;
+      } else if (flag !== "--no-color") continue;
+      args.splice(i--, 1);
+    }
+    if (args[0] === "version") {
+      if (!quiet) stdout.write(`${options.version}
+`);
+      return 0;
+    }
+    if (args[0] === "help") {
+      help = true;
+      args.shift();
+    }
+    if (!args.length) help = true;
+    const entry = tree.find(
+      (command) => command.path.split(" ").every((part, i) => args[i] === part)
+    );
+    const specFor = (command) => {
+      const argument = (name, schema) => ({
+        name,
+        type: schema.type === "object" || !schema.type ? "json" : schema.type,
+        description: schema.description,
+        enum: schema.enum,
+        ...schema.items?.type ? { itemType: schema.items.type } : {}
+      });
+      const properties = command.tool.inputSchema.properties ?? {};
+      return {
+        command: `${options.bin} ${command.path}`,
+        description: command.tool.description,
+        positionals: command.positionals.map((name) => ({
+          ...argument(name, properties[name] ?? {}),
+          ...properties[name]?.type === "array" ? {
+            type: properties[name]?.items?.type ?? "string",
+            variadic: true
+          } : {}
+        })),
+        flags: Object.entries(properties).filter(([name]) => !(name in command.fixed)).map(([name, schema]) => ({
+          ...argument(
+            name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`),
+            schema
+          ),
+          required: false,
+          description: `${schema.description ?? ""}${command.tool.inputSchema.required?.includes(name) ? " (required)" : ""}`
+        }))
+      };
+    };
+    if (help) {
+      const matches = tree.filter(
+        (command) => command.path.startsWith(args.join(" "))
+      );
+      if (!matches.length)
+        throw new CliUsageError(`Unknown command: ${args.join(" ")}`);
+      if (!quiet)
+        stdout.write(
+          entry ? renderCliHelp(specFor(entry)) : `${options.bin} ${options.version}
+${options.description}
+
+Commands:
+${matches.map((command) => `  ${command.path}`).join("\n")}
+  mcp, skill, tools [--json], describe <tool>, call <tool> [JSON|-], completions <bash|zsh|fish>, version
+Global flags: --db <path>, --json, --quiet, --compact, --help/-h, --version/-V/-v, --no-color
+`
+        );
+      return 0;
+    }
+    if (args[0] === "completions") {
+      const shell = args[1];
+      if (!["bash", "zsh", "fish"].includes(shell ?? ""))
+        throw new CliUsageError("Expected completion shell: bash, zsh or fish");
+      if (quiet) return 0;
+      const words = [
+        ...new Set(tree.flatMap((command) => command.path.split(" ")))
+      ].concat([
+        "mcp",
+        "skill",
+        "tools",
+        "describe",
+        "call",
+        "completions",
+        "version"
+      ]);
+      if (shell === "bash")
+        stdout.write(`complete -W '${words.join(" ")}' ${options.bin}
+`);
+      else if (shell === "zsh")
+        stdout.write(
+          `#compdef ${options.bin}
+_arguments '*:command:(${words.join(" ")})'
+`
+        );
+      else if (shell === "fish")
+        stdout.write(`complete -c ${options.bin} -f -a '${words.join(" ")}'
+`);
+      else
+        throw new CliUsageError("Expected completion shell: bash, zsh or fish");
+      return 0;
+    }
+    if (!entry) throw new CliUsageError(`Unknown command: ${args.join(" ")}`);
+    const rest = args.slice(entry.path.split(" ").length);
+    let base = {};
+    const spec = specFor(entry);
+    const positionalIndexes = [];
+    let ended = false;
+    for (let i = 0; i < rest.length; i++) {
+      const token = rest[i];
+      if (!ended && token === "--") {
+        ended = true;
+        continue;
+      }
+      if (!ended && token.startsWith("--")) {
+        const flag = spec.flags?.find((arg) => `--${arg.name}` === token);
+        if (!token.includes("=") && flag && flag.type !== "boolean") i++;
+      } else positionalIndexes.push(i);
+    }
+    const stdinIndex = positionalIndexes.length === 1 && rest[positionalIndexes[0]] === "-" ? positionalIndexes[0] : void 0;
+    if (stdinIndex !== void 0 || !rest.length && !stdin.isTTY) {
+      if (stdinIndex !== void 0) rest.splice(stdinIndex, 1);
+      let raw = "";
+      for await (const chunk of stdin) raw += String(chunk);
+      try {
+        base = raw.trim() ? JSON.parse(raw) : {};
+      } catch {
+        throw new CliUsageError("Invalid stdin JSON");
+      }
+      if (!base || typeof base !== "object" || Array.isArray(base))
+        throw new CliUsageError("Expected stdin JSON object");
+    }
+    const input = {
+      ...base,
+      ...parseCliArgs(rest, spec),
+      ...entry.fixed
+    };
+    const errors = validateInput(entry.tool.inputSchema, input);
+    if (errors.length) throw new CliUsageError(errors.join("\n"));
+    const context = await options.openContext(db === void 0 ? {} : { db });
+    try {
+      const result = await entry.tool.handler(context, input);
+      const record = result;
+      const code = record.outcome === "needs_clarification" || record.error?.code === "not_found" ? 3 : ["conflict", "version_mismatch"].includes(record.error?.code ?? "") ? 4 : record.ok === false ? 1 : 0;
+      if (code)
+        stderr.write(
+          `${record.error?.message ?? record.summary ?? "Tool failed"}
+`
+        );
+      if (!quiet)
+        stdout.write(
+          json || !stdout.isTTY ? `${JSON.stringify(result, null, compact ? void 0 : 2)}
+` : `${record.summary ?? ""}
+${JSON.stringify(record.data ?? {}, null, 2)}
+`
+        );
+      return code;
+    } finally {
+      await options.closeContext?.(context);
+    }
+  } catch (error) {
+    return fail(
+      error instanceof Error ? error.message : String(error),
+      error instanceof CliUsageError ? 2 : 70
+    );
+  }
+}
 
 // src/surfaces/cli.ts
 init_surface_types();
 init_validate_input();
-async function runToolCli(argv, options) {
+async function runToolCli(argv, providedOptions) {
+  let options = providedOptions;
+  const end = argv.indexOf("--");
+  if (argv.slice(0, end < 0 ? argv.length : end).some((arg) => ["--version", "-V", "-v"].includes(arg))) {
+    if (!argv.includes("--quiet"))
+      (options.stdout ?? process.stdout).write(`${options.version}
+`);
+    return 0;
+  }
+  const modern = await runCliCommand(argv, options);
+  if (modern !== void 0) return modern;
+  const quiet = argv.includes("--quiet");
+  const explicitJson = argv.includes("--json") && !argv.includes("tools");
+  if (quiet)
+    options = {
+      ...options,
+      stdout: new Writable({
+        write(_chunk, _encoding, cb) {
+          cb();
+        }
+      })
+    };
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
   const stdin = options.stdin ?? process.stdin;
-  const args = [...argv];
+  const args = argv.filter(
+    (arg) => arg !== "--quiet" && arg !== "--no-color" && !(explicitJson && arg === "--json")
+  );
   let db;
   let compact = false;
   const fail = (message, code = 2) => {
     stderr.write(`${message}
 `);
+    if (explicitJson)
+      stdout.write(
+        `${JSON.stringify({ ok: false, error: { code: "cli_error", message } })}
+`
+      );
     return code;
   };
   for (let i = 0; i < args.length; i++) {
@@ -9984,7 +10480,7 @@ ${options.tools.map((tool2) => `${tool2.name}  ${tool2.description}`).join("\n")
     );
     return 0;
   }
-  if (["--version", "-v"].includes(command)) {
+  if (["--version", "-V", "-v", "version"].includes(command)) {
     stdout.write(`${options.version}
 `);
     return 0;
@@ -9992,7 +10488,9 @@ ${options.tools.map((tool2) => `${tool2.name}  ${tool2.description}`).join("\n")
   if (command === "tools") {
     stdout.write(
       args.includes("--json") ? `${JSON.stringify(
-        options.tools.map(({ handler: _handler, ...tool2 }) => tool2),
+        options.tools.map(
+          ({ handler: _handler, cli: _cli, ...tool2 }) => tool2
+        ),
         null,
         2
       )}
@@ -10127,33 +10625,4 @@ ${JSON.stringify(tool.inputSchema, null, 2)}
 }
 
 // src/cli.ts
-init_version();
-process.exitCode = await runToolCli(process.argv.slice(2), {
-  bin: "ghostpaw-affinity",
-  version: affinityVersion,
-  description: "Local relationship model and social CRM",
-  tools: affinitySurfaceTools,
-  openContext: async (options) => {
-    const { openAffinityDb: openAffinityDb2 } = await Promise.resolve().then(() => (init_open_affinity_db(), open_affinity_db_exports));
-    const { resolveAffinityDbPath: resolveAffinityDbPath2 } = await Promise.resolve().then(() => (init_resolve_affinity_db_path(), resolve_affinity_db_path_exports));
-    return openAffinityDb2(
-      resolveAffinityDbPath2(
-        options.db === void 0 ? {} : { flag: options.db }
-      )
-    );
-  },
-  closeContext: (db) => db.close(),
-  commands: {
-    mcp: async (options) => {
-      const { serveAffinityMcp: serveAffinityMcp2 } = await Promise.resolve().then(() => (init_serve_affinity_mcp(), serve_affinity_mcp_exports));
-      await serveAffinityMcp2(
-        options.db === void 0 ? {} : { dbPath: options.db }
-      );
-    },
-    skill: async () => {
-      const { renderSkillMarkdown: renderSkillMarkdown2 } = await Promise.resolve().then(() => (init_skill_markdown(), skill_markdown_exports));
-      const { affinitySkillSpec: affinitySkillSpec2 } = await Promise.resolve().then(() => (init_affinity_skill_spec(), affinity_skill_spec_exports));
-      return renderSkillMarkdown2(affinitySkillSpec2);
-    }
-  }
-});
+process.exitCode = await runToolCli(process.argv.slice(2), affinityCliOptions);