@ghostpaw/affinity 0.3.0 → 0.4.0

package/README.md

@@ -1,11 +1,14 @@
+<a href="https://affinity.ghostpaw.dev/"><img src="https://raw.githubusercontent.com/GhostPawJS/affinity/main/.github/social-preview.png" alt="GhostPaw affinity: Who have you been meaning to call?" width="100%"></a>
+
 # @ghostpaw/affinity
 
-[![npm](https://img.shields.io/npm/v/@ghostpaw/affinity)](https://www.npmjs.com/package/@ghostpaw/affinity)
-[![node](https://img.shields.io/node/v/@ghostpaw/affinity)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/@ghostpaw/affinity)](LICENSE)
-[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Faffinity-06d6a0)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Faffinity/versions/latest)
+[![npm](https://img.shields.io/npm/v/@ghostpaw/affinity?style=flat-square&labelColor=0a1119&color=62e6f2&label=npm)](https://www.npmjs.com/package/@ghostpaw/affinity) [![CI](https://img.shields.io/github/actions/workflow/status/GhostPawJS/affinity/ci.yml?branch=main&style=flat-square&labelColor=0a1119&label=CI)](https://github.com/GhostPawJS/affinity/actions/workflows/ci.yml) [![site](https://img.shields.io/badge/site-affinity.ghostpaw.dev-62e6f2?style=flat-square&labelColor=0a1119)](https://affinity.ghostpaw.dev/) [![runtime deps](https://img.shields.io/badge/runtime_deps-0-7af0b4?style=flat-square&labelColor=0a1119)](package.json) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Faffinity-b39dff?style=flat-square&labelColor=0a1119)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Faffinity/versions/latest) [![node](https://img.shields.io/badge/node-%E2%89%A524-93a5b9?style=flat-square&labelColor=0a1119)](https://nodejs.org) [![license](https://img.shields.io/npm/l/@ghostpaw/affinity?style=flat-square&labelColor=0a1119&color=93a5b9)](LICENSE)
+
+**Agent contacts: people, promises and yearly dates, with a radar for who is drifting.**
+
+```bash
+npm install @ghostpaw/affinity
+```
 
 A standalone social CRM core for Node.js, built on SQLite.
 
@@ -88,11 +91,139 @@ npx -y @ghostpaw/affinity skill > SKILL.md
 
 ## Install
 
-```bash
-npm install @ghostpaw/affinity
+
+The [npm package](https://www.npmjs.com/package/@ghostpaw/affinity) requires Node 24+:
+
+```sh
+npm install -g @ghostpaw/affinity
+npx -y @ghostpaw/affinity --help
+```
+
+Standalone binaries are available from [GitHub Releases](https://github.com/GhostPawJS/affinity/releases)
+for linux-x64, linux-arm64, darwin-arm64, darwin-x64 and windows-x64.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.sh | sh
+```
+
+```powershell
+irm https://raw.githubusercontent.com/GhostPawJS/affinity/main/install.ps1 | iex
+```
+
+Other release installers:
+
+```sh
+mise use -g github:GhostPawJS/affinity
+ubi --project GhostPawJS/affinity --exe ghostpaw-affinity --in ~/.local/bin
+eget GhostPawJS/affinity
+```
+
+For [aqua](https://aquaproj.github.io/docs/reference/registry-config/), define a
+`github_release` package in `aqua.yaml`:
+
+```yaml
+registries:
+  - name: affinity
+    type: local
+    path: affinity-registry.yaml
+packages:
+  - name: GhostPawJS/affinity@v<VERSION>
+    registry: affinity
+```
+
+`affinity-registry.yaml`:
+
+```yaml
+packages:
+  - type: github_release
+    repo_owner: GhostPawJS
+    repo_name: affinity
+    asset: ghostpaw-affinity-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz
+    format: tar.gz
+    replacements: { amd64: x64 }
+    overrides:
+      - goos: windows
+        asset: ghostpaw-affinity-{{trimV .Version}}-windows-{{.Arch}}.zip
+        format: zip
+    files:
+      - name: ghostpaw-affinity
+```
+
+Install scripts verify SHA256SUMS. To verify a downloaded archive's
+[build attestation](https://cli.github.com/manual/gh_attestation_verify):
+
+```sh
+gh attestation verify <archive> -R GhostPawJS/affinity
+```
+
+Set `GHOSTPAW_VERIFY=attestation` for attestation verification in `install.sh`.
+Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser
+download on macOS, remove quarantine with
+`xattr -d com.apple.quarantine /path/to/ghostpaw-affinity`.
+Linux binaries require glibc 2.28+; use npx on Alpine.
+See the [binary build workflow](.github/workflows/release-binaries.yml).
+
+<!-- sizes -->
+
+The install check runs on ubuntu-24.04, macos-15 and windows-2025.
+
+## CLI
+
+```text
+ghostpaw-affinity search <query>
+ghostpaw-affinity review <view>
+ghostpaw-affinity show <owner_profile|contact_profile|link> [--contact JSON --link JSON]
+ghostpaw-affinity contact create <input-json>
+ghostpaw-affinity contact revise <contact-json> --patch JSON
+ghostpaw-affinity contact lifecycle <contact-json> <lifecycleState>
+ghostpaw-affinity contact merge [flags]
+ghostpaw-affinity identity add|revise|verify|remove [flags]
+ghostpaw-affinity relationship add|bond|state|tie|untie [flags]
+ghostpaw-affinity commitment record|resolve [flags]
+ghostpaw-affinity attribute set|unset|replace [flags]
+ghostpaw-affinity date add|revise|remove [flags]
+ghostpaw-affinity event record [flags]
+ghostpaw-affinity duplicate dismiss|undismiss [flags]
+ghostpaw-affinity mcp|skill|tools|describe|call|completions|version|help
 ```
 
-Requires **Node.js 24+** (uses the built-in `node:sqlite` module).
+There are 27 domain commands. `review` accepts the existing view names,
+including `contacts.list`, `contacts.duplicates` and `dates.upcoming`.
+`show` selects an inspection kind; contact and link locators are JSON objects.
+Use `help contact` or `contact create --help` for schema-derived help.
+Nested payloads use JSON or `@path` to read a file.
+
+Global flags: `--db <path>`, `--json`, `--quiet`, `--compact`,
+`--help`/`-h`, `--version`/`-V`/`-v`, `--no-color`.
+`NO_COLOR` is accepted; output uses no terminal colors.
+Noun-verb commands print the full tool result as JSON with `--json` or piped
+stdout. Terminal output shows the summary and payload. `--quiet` suppresses
+stdout. `--compact` removes JSON indentation.
+Array flags repeat; kebab-case flags map to schema properties.
+`--` ends flags. A positional `-`, or piped stdin with no input flags, reads a
+JSON object. Explicit flags override stdin fields.
+Database selection uses `--db`, `GHOSTPAW_AFFINITY_DB`, then
+`~/.ghostpaw/affinity.db`. These commands work offline.
+
+| Exit | Noun-verb result |
+|---|---|
+| 0 | Success, including no_op |
+| 1 | Tool error |
+| 2 | Usage or schema error |
+| 3 | Clarification needed or not found |
+| 4 | Conflict or version mismatch |
+| 70 | Internal error |
+
+Errors go to stderr. With `--json`, errors also print to stdout.
+Legacy `tools [--json]`, `describe <tool>`, `call <tool> [JSON|-]` and
+`<tool_name> --parameter value` retain their output and exit codes.
+`completions bash|zsh|fish` prints shell scripts.
+
+```sh
+ghostpaw-affinity contact create '{"name":"Sam","kind":"human"}' --db /tmp/affinity-example.db --json
+ghostpaw-affinity search Sam --db /tmp/affinity-example.db --json
+ghostpaw-affinity review contacts.list --db /tmp/affinity-example.db --json
+```
 
 ## Quick Start
 
@@ -135,6 +266,16 @@ const profile = read.getContactProfile(db, ada.id);
 const radar = read.listRadar(db);
 ```
 
+## Docs
+
+The live demo runs the library in your browser against an in-memory SQLite database. Each view below opens a different part of it:
+
+- [Dashboard](https://affinity.ghostpaw.dev/docs/): overview and session
+- [Contacts](https://affinity.ghostpaw.dev/docs/#/contacts): people, companies, groups and pets you track
+- [Relationships](https://affinity.ghostpaw.dev/docs/#/relationships): links, rank and bonds
+- [Timeline](https://affinity.ghostpaw.dev/docs/#/timeline): events, commitments and date anchors
+- [Insights](https://affinity.ghostpaw.dev/docs/#/insights): radar and analytics
+
 ## The Model
 
 Eight concepts, strict separation of concerns:

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.0";
+  }
+});
+
 // src/lib/errors/affinity_error.ts
 var AffinityError;
 var init_affinity_error = __esm({
@@ -8177,7 +8191,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 +8205,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 +8810,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 +9093,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 +9996,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 || next.startsWith("--"))
+        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 +10456,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 +10464,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 +10601,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);

package/dist/mcp-server.js

@@ -5,8 +5,13 @@ import { homedir } from 'node:os';
 
 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)
@@ -280,7 +285,7 @@ var init_mcp_stdio = __esm({
 var affinityVersion;
 var init_version = __esm({
   "src/version.ts"() {
-    affinityVersion = "0.3.0";
+    affinityVersion = "0.4.0";
   }
 });
 
@@ -8485,7 +8490,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

package/dist/mcp.cjs

@@ -5,7 +5,7 @@ var node_path = require('node:path');
 var node_os = require('node:os');
 
 // src/version.ts
-var affinityVersion = "0.3.0";
+var affinityVersion = "0.4.0";
 
 // src/surface/affinity_mcp_instructions.ts
 var affinityMcpInstructions = "Affinity is a local relationship model and social CRM. Search before creating contacts. Inspect before revising or merging. Record direct evidence honestly, keep identities and structural ties distinct from social links, and ask for clarification when a target is ambiguous. Review commitments and recurring dates regularly. Derived scores guide attention and do not prove relationship quality.";
@@ -7199,7 +7199,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

package/dist/mcp.d.cts

@@ -19,6 +19,16 @@ interface JsonSchema {
 }
 interface SurfaceTool<TCtx> {
     name: string;
+    cli?: {
+        noun?: string;
+        verb: string;
+        positionals?: string[];
+        action?: {
+            property: string;
+            verbs?: Record<string, string>;
+            positionals?: Record<string, string[]>;
+        };
+    };
     title?: string;
     description: string;
     inputSchema: JsonSchema & {

package/dist/mcp.d.ts

@@ -19,6 +19,16 @@ interface JsonSchema {
 }
 interface SurfaceTool<TCtx> {
     name: string;
+    cli?: {
+        noun?: string;
+        verb: string;
+        positionals?: string[];
+        action?: {
+            property: string;
+            verbs?: Record<string, string>;
+            positionals?: Record<string, string[]>;
+        };
+    };
     title?: string;
     description: string;
     inputSchema: JsonSchema & {

package/dist/mcp.js

@@ -3,7 +3,7 @@ import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
 // src/version.ts
-var affinityVersion = "0.3.0";
+var affinityVersion = "0.4.0";
 
 // src/surface/affinity_mcp_instructions.ts
 var affinityMcpInstructions = "Affinity is a local relationship model and social CRM. Search before creating contacts. Inspect before revising or merging. Record direct evidence honestly, keep identities and structural ties distinct from social links, and ask for clarification when a target is ambiguous. Review commitments and recurring dates regularly. Derived scores guide attention and do not prove relationship quality.";
@@ -7197,7 +7197,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostpaw/affinity",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Relationship intelligence and social CRM model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
   "license": "MIT",
   "author": {
@@ -15,7 +15,7 @@
   "bugs": {
     "url": "https://github.com/GhostPawJS/affinity/issues"
   },
-  "homepage": "https://github.com/GhostPawJS/affinity",
+  "homepage": "https://affinity.ghostpaw.dev/",
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/Anonyfox"
@@ -50,7 +50,12 @@
     "mcp-server",
     "model-context-protocol",
     "agent-skills",
-    "cli"
+    "cli",
+    "ghostpaw",
+    "ai-agents",
+    "llm-tools",
+    "node-sqlite",
+    "local-first"
   ],
   "files": ["dist", "skills", "SKILL.md"],
   "main": "./dist/index.cjs",
@@ -109,13 +114,16 @@
     "check:api": "node scripts/guard/api.mjs",
     "check:consumer": "node scripts/guard/consumer.mjs",
     "check:startup": "node scripts/guard/startup.mjs",
-    "mcpb": "node scripts/mcpb/build.mjs"
+    "mcpb": "node scripts/mcpb/build.mjs",
+    "sea": "node scripts/sea/build.mjs",
+    "sea:smoke": "node scripts/sea/smoke.mjs",
+    "sea:bench": "node scripts/sea/bench.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/node": "^24.12.0",
     "@types/sql.js": "^1.4.10",
-    "esbuild": "^0.27.4",
+    "esbuild": "^0.28.1",
     "fflate": "0.8.3",
     "preact": "^10.29.0",
     "sql.js": "^1.14.1",
@@ -125,5 +133,8 @@
   "bin": {
     "ghostpaw-affinity": "./dist/cli.js"
   },
-  "mcpName": "io.github.GhostPawJS/affinity"
+  "mcpName": "io.github.GhostPawJS/affinity",
+  "overrides": {
+    "esbuild": "$esbuild"
+  }
 }