@mrciphersmith/keryx 0.2.156 → 0.2.159

package/dist/core.js

@@ -26434,6 +26434,23 @@ init_service();
 init_fs();
 var exports_service10 = {};
 __export(exports_service10, {
+  HELP_DEFAULT_COLUMNS: () => HELP_DEFAULT_COLUMNS,
+  HELP_GROUPS: () => HELP_GROUPS,
+  HELP_GROUP_ORDER: () => HELP_GROUP_ORDER,
+  HIDDEN_FROM_HELP: () => HIDDEN_FROM_HELP,
+  allHelpTokens: () => allHelpTokens,
+  closestHelpTopics: () => closestHelpTopics,
+  entriesInGroup: () => entriesInGroup,
+  findCliEntry: () => findCliEntry,
+  findEntry: () => findEntry,
+  findSlashEntry: () => findSlashEntry,
+  groupBySlug: () => groupBySlug,
+  renderCliGroupHelp: () => renderCliGroupHelp,
+  renderCommandsByTaskMarkdown: () => renderCommandsByTaskMarkdown,
+  renderEntryDetail: () => renderEntryDetail,
+  renderGroupedCliHelp: () => renderGroupedCliHelp,
+  renderGroupedNamedHelp: () => renderGroupedNamedHelp,
+  renderGroupedSlashHelp: () => renderGroupedSlashHelp,
   runCapabilities: () => runCapabilities,
   runDoctor: () => runDoctor,
   runValidate: () => runValidate
@@ -26918,6 +26935,621 @@ function extractCapabilities(manifest) {
   };
 }
 
+// src/standard/help-groups.ts
+var HELP_GROUP_ORDER = [
+  { name: "Start here", slug: "start-here" },
+  { name: "Connect a model provider", slug: "connect" },
+  { name: "Look and feel", slug: "look-and-feel" },
+  { name: "Working in keryx shell", slug: "shell-work" },
+  { name: "Project knowledge", slug: "project-knowledge" },
+  { name: "Managed work", slug: "managed-work" },
+  { name: "Automation", slug: "automation" },
+  { name: "External agents, ACP and MCP", slug: "external-agents" },
+  { name: "Maintenance and diagnostics", slug: "maintenance" }
+];
+var HELP_GROUPS = [
+  { kind: "cli", name: "init", group: "Start here", summary: "Initialize .metaproject in the current project." },
+  { kind: "cli", name: "status", group: "Start here", summary: "Show local Metaproject status." },
+  {
+    kind: "cli",
+    name: "shell",
+    group: "Start here",
+    summary: "Start the interactive TUI agent harness (--no-tui or --chat to opt out)."
+  },
+  {
+    kind: "cli",
+    name: "help",
+    group: "Start here",
+    summary: "Grouped command help by task \u2014 keryx help [group|command]."
+  },
+  { kind: "slash", name: "/help", group: "Start here", summary: "Show available commands, grouped by task." },
+  {
+    kind: "cli",
+    name: "auth",
+    group: "Connect a model provider",
+    summary: "Subscription login (SuperGrok, ChatGPT Plus/Pro, GitHub Copilot) and API-key status."
+  },
+  {
+    kind: "cli",
+    name: "providers",
+    group: "Connect a model provider",
+    summary: "Providers this operator has configured, and cross-family review eligibility."
+  },
+  { kind: "slash", name: "/connect", group: "Connect a model provider", summary: "Switch provider / API key." },
+  {
+    kind: "slash",
+    name: "/search-provider",
+    group: "Connect a model provider",
+    summary: "Configure and test a web search provider."
+  },
+  {
+    kind: "slash",
+    name: "/search-connect",
+    group: "Connect a model provider",
+    summary: "Select a connected web search provider."
+  },
+  {
+    kind: "slash",
+    name: "/provider",
+    group: "Connect a model provider",
+    summary: "Switch provider \u2014 /provider <name>, or no arg to re-select."
+  },
+  {
+    kind: "slash",
+    name: "/theme",
+    group: "Look and feel",
+    summary: "Open the theme picker \u2014 /theme [name] applies immediately."
+  },
+  { kind: "slash", name: "/model", group: "Look and feel", summary: "Switch the model." },
+  {
+    kind: "slash",
+    name: "/models",
+    group: "Look and feel",
+    summary: "Pick a model for the current provider (numbered menu)."
+  },
+  {
+    kind: "slash",
+    name: "/mode",
+    group: "Look and feel",
+    summary: "Show or switch the permission mode \u2014 /mode [ask|trust|auto]."
+  },
+  {
+    kind: "slash",
+    name: "/think",
+    group: "Look and feel",
+    summary: "Expand the last reasoning block \u2014 /think [auto|expand|hide|collapse]."
+  },
+  {
+    kind: "slash",
+    name: "/reasoning",
+    group: "Look and feel",
+    summary: "Show or set reasoning effort \u2014 /reasoning [off|minimal|low|medium|high|xhigh|max]."
+  },
+  { kind: "cli", name: "sessions", group: "Working in keryx shell", summary: "List or export per-project shell sessions." },
+  {
+    kind: "slash",
+    name: "/sessions",
+    group: "Working in keryx shell",
+    summary: "Open the session list and switch to one."
+  },
+  { kind: "slash", name: "/resume", group: "Working in keryx shell", summary: "Resume a prior session in this project." },
+  { kind: "slash", name: "/new", group: "Working in keryx shell", summary: "Start a new session (old kept on disk)." },
+  { kind: "slash", name: "/clear", group: "Working in keryx shell", summary: "New session (alias of /new)." },
+  {
+    kind: "slash",
+    name: "/compact",
+    group: "Working in keryx shell",
+    summary: "Compact model context \u2014 /compact [focus] (archive kept)."
+  },
+  {
+    kind: "slash",
+    name: "/copy",
+    group: "Working in keryx shell",
+    summary: "Copy the newest transcript block to the clipboard."
+  },
+  { kind: "slash", name: "/expand", group: "Working in keryx shell", summary: "Expand the last tool output block." },
+  {
+    kind: "slash",
+    name: "/status",
+    group: "Working in keryx shell",
+    summary: "Show session identity, context window, limits, workspaces, and flows."
+  },
+  {
+    kind: "slash",
+    name: "/queue",
+    group: "Working in keryx shell",
+    summary: "Manage the main queue \u2014 /queue <remove|edit|force> [N] (N = qN position, default 1)."
+  },
+  {
+    kind: "slash",
+    name: "/interrupt",
+    group: "Working in keryx shell",
+    summary: "Interrupt the running main agent turn."
+  },
+  { kind: "slash", name: "/exit", group: "Working in keryx shell", summary: "Leave the shell (/quit works too)." },
+  {
+    kind: "slash",
+    name: "/game",
+    group: "Working in keryx shell",
+    summary: "Games against the model \u2014 /game [seconds] raises the model-turn deadline."
+  },
+  { kind: "cli", name: "gdgraph", group: "Project knowledge", summary: "Build and query the code dependency graph." },
+  { kind: "cli", name: "ctx", group: "Project knowledge", summary: "Run compact context commands and save raw output." },
+  { kind: "cli", name: "wiki", group: "Project knowledge", summary: "Manage the local project knowledge base." },
+  { kind: "cli", name: "memory", group: "Project knowledge", summary: "Store and search long-term project memory." },
+  {
+    kind: "cli",
+    name: "orient",
+    group: "Project knowledge",
+    summary: "Emit a bounded graph + wiki startup block, or install it as a turn-start hook."
+  },
+  { kind: "cli", name: "skills", group: "Project knowledge", summary: "Manage bundled Metaproject working skills." },
+  { kind: "cli", name: "flow", group: "Managed work", summary: "Agent-first flow lifecycle (Task Manager)." },
+  {
+    kind: "cli",
+    name: "job",
+    group: "Managed work",
+    summary: "Agent-first job packages (job-orchestrator state, steps, documents)."
+  },
+  {
+    kind: "cli",
+    name: "review",
+    group: "Managed work",
+    summary: "Managed review packages and lightweight report-only review mode."
+  },
+  { kind: "slash", name: "/flows", group: "Managed work", summary: "Browse project flows and inspect one." },
+  {
+    kind: "slash",
+    name: "/review",
+    group: "Managed work",
+    summary: "Show project-wide items needing review (proposals, blocked sessions)."
+  },
+  { kind: "slash", name: "/plan", group: "Managed work", summary: "Toggle read-only mode \u2014 /plan [on|off]." },
+  {
+    kind: "slash",
+    name: "/goal",
+    group: "Managed work",
+    summary: "Deterministically start a goal \u2014 /goal <text> [--workspace <id>] [--auto [N]]."
+  },
+  {
+    kind: "cli",
+    name: "trigger",
+    group: "Automation",
+    summary: "Fire one declared project trigger (git hook, cron line, CI job) \u2014 one pass, one exit code."
+  },
+  {
+    kind: "cli",
+    name: "schedule",
+    group: "Automation",
+    summary: "Scheduled agent tasks in the background: create (with confirmation), list, pause, resume, remove."
+  },
+  {
+    kind: "cli",
+    name: "governance",
+    group: "Automation",
+    summary: "Read-only report over already-recorded spend, confirmations, signatures and gate outcomes."
+  },
+  {
+    kind: "slash",
+    name: "/triggers",
+    group: "Automation",
+    summary: "Declared triggers: last outcome, spend, reservations \u2014 run one now."
+  },
+  {
+    kind: "slash",
+    name: "/schedule",
+    group: "Automation",
+    summary: "Schedule a background agent task \u2014 shows a confirmation card first (keryx schedule add)."
+  },
+  {
+    kind: "slash",
+    name: "/schedules",
+    group: "Automation",
+    summary: "Scheduled tasks: next run, last outcome, report \u2014 pause, resume, run now, delete."
+  },
+  {
+    kind: "slash",
+    name: "/governance",
+    group: "Automation",
+    summary: "Show the last governance report, or run one in the background."
+  },
+  {
+    kind: "cli",
+    name: "acp",
+    group: "External agents, ACP and MCP",
+    summary: "Speak ACP v1 (newline-delimited JSON-RPC) over stdio, for an ACP client (e.g. an editor)."
+  },
+  {
+    kind: "cli",
+    name: "agents",
+    group: "External agents, ACP and MCP",
+    summary: "Manage optional global agent bootstrap instructions."
+  },
+  {
+    kind: "cli",
+    name: "mcp",
+    group: "External agents, ACP and MCP",
+    summary: "Retired spelling of serve-mcp / integrate; still works, names its replacement."
+  },
+  {
+    kind: "cli",
+    name: "integrate",
+    group: "External agents, ACP and MCP",
+    summary: "Wire this project into an editor or agent as an MCP server."
+  },
+  {
+    kind: "cli",
+    name: "serve-mcp",
+    group: "External agents, ACP and MCP",
+    summary: "Expose Metaproject services over the Model Context Protocol (opt-in)."
+  },
+  {
+    kind: "cli",
+    name: "bus",
+    group: "External agents, ACP and MCP",
+    summary: "Agent bus: list peers and leases, read the log, send a message, prune."
+  },
+  {
+    kind: "cli",
+    name: "workspace",
+    group: "External agents, ACP and MCP",
+    summary: "Shared Agent Context: workspaces, FWK reads, propose/review (module sac)."
+  },
+  {
+    kind: "slash",
+    name: "/delegate",
+    group: "External agents, ACP and MCP",
+    summary: "Hand a task to an external agent CLI \u2014 /delegate <agent> <task>."
+  },
+  {
+    kind: "slash",
+    name: "/demote",
+    group: "External agents, ACP and MCP",
+    summary: "Move a running foreground task to the background \u2014 /demote <task_id>."
+  },
+  {
+    kind: "slash",
+    name: "/mcp",
+    group: "External agents, ACP and MCP",
+    summary: "MCP servers keryx is connected to \u2014 status, connect/disconnect."
+  },
+  {
+    kind: "slash",
+    name: "/integrations",
+    group: "External agents, ACP and MCP",
+    summary: "Wire this project into an editor over MCP (keryx integrate)."
+  },
+  {
+    kind: "slash",
+    name: "/bus",
+    group: "External agents, ACP and MCP",
+    summary: "Message or view peers on the project agent bus \u2014 /bus @<name> <text>."
+  },
+  {
+    kind: "slash",
+    name: "/workspace",
+    group: "External agents, ACP and MCP",
+    summary: "Show this session's SAC workspace and its slates."
+  },
+  {
+    kind: "cli",
+    name: "health",
+    group: "Maintenance and diagnostics",
+    summary: "Aggregate code quality signals and run the quality gate."
+  },
+  {
+    kind: "cli",
+    name: "test",
+    group: "Maintenance and diagnostics",
+    summary: "Analyze testing context and normalize test reports."
+  },
+  {
+    kind: "cli",
+    name: "standard",
+    group: "Maintenance and diagnostics",
+    summary: "Validate the workspace against the Metaproject Standard."
+  },
+  {
+    kind: "cli",
+    name: "update",
+    group: "Maintenance and diagnostics",
+    summary: "Refresh managed service files without touching data artifacts."
+  },
+  {
+    kind: "cli",
+    name: "sync",
+    group: "Maintenance and diagnostics",
+    summary: "Reconcile graph/wiki/memory with the current code, and wire the git hooks."
+  },
+  {
+    kind: "cli",
+    name: "security",
+    group: "Maintenance and diagnostics",
+    summary: "Policy-based scanning, redaction, guardrails and audit reports."
+  },
+  {
+    kind: "cli",
+    name: "dashboard",
+    group: "Maintenance and diagnostics",
+    summary: "Build or open the project admin dashboard."
+  },
+  {
+    kind: "cli",
+    name: "dash",
+    group: "Maintenance and diagnostics",
+    summary: "Rebuild and open .metaproject/keryx-dashboard.html."
+  },
+  {
+    kind: "cli",
+    name: "metrics",
+    group: "Maintenance and diagnostics",
+    summary: "Provenance-aware execution observability: run records, baselines, benchmarks."
+  },
+  {
+    kind: "cli",
+    name: "sandbox",
+    group: "Maintenance and diagnostics",
+    summary: "Report OS sandbox launcher availability and the per-capability containment matrix."
+  },
+  {
+    kind: "cli",
+    name: "modules",
+    group: "Maintenance and diagnostics",
+    summary: "View and toggle Metaproject modules (interactive)."
+  },
+  {
+    kind: "cli",
+    name: "projects",
+    group: "Maintenance and diagnostics",
+    summary: "Inspect the user-global registry of initialized projects."
+  },
+  {
+    kind: "cli",
+    name: "serve",
+    group: "Maintenance and diagnostics",
+    summary: "Loopback-bound authenticated HTTP entry (off by default; read-only routes)."
+  },
+  {
+    kind: "cli",
+    name: "rules",
+    group: "Maintenance and diagnostics",
+    summary: "Sync root AGENTS.md/CLAUDE.md into high-priority project rules."
+  },
+  {
+    kind: "cli",
+    name: "harness",
+    group: "Maintenance and diagnostics",
+    summary: "Run a single provider turn (harness run) and print structured events."
+  },
+  {
+    kind: "cli",
+    name: "version",
+    group: "Maintenance and diagnostics",
+    summary: "Check whether a newer npm release is available."
+  },
+  {
+    kind: "cli",
+    name: "retention",
+    group: "Maintenance and diagnostics",
+    summary: "Bound stores that grow without bound (gdctx raw/artifacts, owner write-conflict sidecars)."
+  },
+  {
+    kind: "cli",
+    name: "forgetting",
+    group: "Maintenance and diagnostics",
+    summary: "Read the deletion trail \u2014 was this removed, or did it never exist?"
+  },
+  {
+    kind: "cli",
+    name: "commands",
+    group: "Maintenance and diagnostics",
+    summary: "Agent-callable command registry (intents, args, output, model usage)."
+  }
+];
+var HIDDEN_FROM_HELP = [
+  {
+    verb: "__sandbox-net-forward",
+    reason: "internal helper keryx starts inside the unattended sandbox to bridge a local port to the allowlist proxy's socket; never typed by an operator (see the file header on src/commands/sandbox-net-forward.ts and its DOCUMENTED_ELSEWHERE entry in cli-reference-coverage.test.ts)"
+  },
+  {
+    verb: "session",
+    reason: "alias of `sessions`; cli.ts's own flat `Commands:` block omits it too (only `sessions` is listed there, with no inline alias mention)"
+  },
+  {
+    verb: "skill-verify-skill",
+    reason: "standalone alias of `skills verify`; cli.ts's own flat `Commands:` block omits it too (only `skills` is listed there), matching command-registry.coverage.test.ts's EXCLUSIONS reason for the same verb (\"standalone alias of skills verify; not part of the agent surface\")"
+  }
+];
+function groupBySlug(token) {
+  const lower = token.trim().toLowerCase();
+  return HELP_GROUP_ORDER.find((g) => g.slug === lower);
+}
+function entriesInGroup(group, kind) {
+  return HELP_GROUPS.filter((e) => e.group === group && (kind === undefined || e.kind === kind));
+}
+function findEntry(kind, name) {
+  return HELP_GROUPS.find((e) => e.kind === kind && e.name === name);
+}
+function findCliEntry(name) {
+  return findEntry("cli", name);
+}
+function findSlashEntry(name) {
+  return findEntry("slash", name);
+}
+var HELP_DEFAULT_COLUMNS = 80;
+var MIN_WRAP_COLUMNS = 10;
+function wrapWords(line, budget) {
+  const out = [];
+  let cur = "";
+  for (const word of line.split(/\s+/).filter(Boolean)) {
+    if (cur.length > 0 && cur.length + 1 + word.length > budget) {
+      out.push(cur);
+      cur = word;
+    } else {
+      cur = cur.length > 0 ? `${cur} ${word}` : word;
+    }
+  }
+  out.push(cur);
+  return out.length > 0 ? out : [""];
+}
+function renderEntryRows(entries, maxColumns) {
+  if (entries.length === 0) {
+    return [];
+  }
+  const width = entries.reduce((w, e) => Math.max(w, e.name.length), 0);
+  const descColumn = width + 4;
+  const wrapBudget = maxColumns === undefined ? undefined : Math.max(MIN_WRAP_COLUMNS, maxColumns - descColumn);
+  const rows = [];
+  for (const entry of entries) {
+    const wrapped = wrapBudget === undefined ? [entry.summary] : wrapWords(entry.summary, wrapBudget);
+    wrapped.forEach((line, i) => {
+      rows.push(i === 0 ? `  ${entry.name.padEnd(width)}  ${line}`.trimEnd() : `${" ".repeat(descColumn)}${line}`.trimEnd());
+    });
+  }
+  return rows;
+}
+function renderGroupedCliHelp(maxColumns = HELP_DEFAULT_COLUMNS) {
+  const lines = [];
+  for (const group of HELP_GROUP_ORDER) {
+    const entries = entriesInGroup(group.name, "cli");
+    if (entries.length === 0) {
+      continue;
+    }
+    lines.push(`${group.name}:`);
+    lines.push(...renderEntryRows(entries, maxColumns));
+    lines.push("");
+  }
+  return lines.join(`
+`).replace(/\n+$/, `
+`);
+}
+function renderCliGroupHelp(group, maxColumns = HELP_DEFAULT_COLUMNS) {
+  const entries = entriesInGroup(group.name, "cli");
+  const lines = [`${group.name}:`, ...renderEntryRows(entries, maxColumns)];
+  return lines.join(`
+`) + `
+`;
+}
+function renderGroupedSlashHelp(allow, maxColumns) {
+  const allowed = new Set(allow);
+  const lines = ["Commands:"];
+  for (const group of HELP_GROUP_ORDER) {
+    const entries = entriesInGroup(group.name, "slash").filter((e) => allowed.has(e.name));
+    if (entries.length === 0) {
+      continue;
+    }
+    lines.push("", `${group.name}:`);
+    lines.push(...renderEntryRows(entries, maxColumns));
+  }
+  return lines.join(`
+`) + `
+`;
+}
+function renderGroupedNamedHelp(options, maxColumns) {
+  const lines = ["Commands:"];
+  for (const group of HELP_GROUP_ORDER) {
+    const rows = options.filter((o) => findEntry("slash", o.name)?.group === group.name).map((o) => ({ kind: "slash", name: o.name, group: group.name, summary: o.description }));
+    if (rows.length === 0) {
+      continue;
+    }
+    lines.push("", `${group.name}:`);
+    lines.push(...renderEntryRows(rows, maxColumns));
+  }
+  return lines.join(`
+`) + `
+`;
+}
+function renderEntryDetail(entry) {
+  const lines = [`${entry.name}`, "", entry.summary, ""];
+  if (entry.kind === "slash") {
+    lines.push("This is a keryx shell command \u2014 type it inside `keryx shell` (readline chat/agent mode, or the", "TUI's `/`-menu). It has no standalone CLI form.");
+  } else {
+    lines.push(`Run \`keryx ${entry.name} --help\` (or \`keryx help ${entry.name}\`) for its full usage.`);
+  }
+  return lines.join(`
+`) + `
+`;
+}
+function mdCell(text) {
+  return text.replace(/\|/g, "\\|");
+}
+function renderCommandsByTaskMarkdown() {
+  const lines = [
+    "# Commands by task",
+    "",
+    "Every `keryx` CLI verb and every `keryx shell` command, grouped by task \u2014 " + "the same grouping `keryx help` and the OpenTUI shell's `/help` modal use " + "(`src/standard/help-groups.ts`, flow 303).",
+    "",
+    "Generated. Do not hand-edit: regenerate with " + "`bun scripts/generate-commands-by-task.ts`, and " + "`src/standard/commands-by-task.test.ts` fails when this page drifts from " + "the table it is generated from.",
+    ""
+  ];
+  for (const group of HELP_GROUP_ORDER) {
+    const cli = entriesInGroup(group.name, "cli");
+    const slash = entriesInGroup(group.name, "slash");
+    if (cli.length === 0 && slash.length === 0) {
+      continue;
+    }
+    lines.push(`## ${group.name}`, "");
+    if (cli.length > 0) {
+      lines.push("| CLI command | Summary |", "|---|---|");
+      for (const entry of cli) {
+        lines.push(`| \`keryx ${mdCell(entry.name)}\` | ${mdCell(entry.summary)} |`);
+      }
+      lines.push("");
+    }
+    if (slash.length > 0) {
+      lines.push("| Shell command | Summary |", "|---|---|");
+      for (const entry of slash) {
+        lines.push(`| \`${mdCell(entry.name)}\` | ${mdCell(entry.summary)} |`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join(`
+`).replace(/\n+$/, `
+`);
+}
+function levenshtein(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const dp = Array.from({ length: rows }, () => new Array(cols).fill(0));
+  for (let i = 0;i < rows; i += 1) {
+    const row = dp[i];
+    if (row !== undefined)
+      row[0] = i;
+  }
+  const first = dp[0];
+  if (first !== undefined) {
+    for (let j = 0;j < cols; j += 1)
+      first[j] = j;
+  }
+  for (let i = 1;i < rows; i += 1) {
+    for (let j = 1;j < cols; j += 1) {
+      const same = a[i - 1] === b[j - 1];
+      const up = dp[i - 1]?.[j] ?? 0;
+      const left = dp[i]?.[j - 1] ?? 0;
+      const diag = dp[i - 1]?.[j - 1] ?? 0;
+      const row = dp[i];
+      if (row !== undefined)
+        row[j] = same ? diag : 1 + Math.min(up, left, diag);
+    }
+  }
+  return dp[rows - 1]?.[cols - 1] ?? Math.max(a.length, b.length);
+}
+function allHelpTokens() {
+  return [
+    ...HELP_GROUP_ORDER.map((g) => g.slug),
+    ...HELP_GROUPS.map((e) => e.name)
+  ];
+}
+function closestHelpTopics(query, limit = 3) {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) {
+    return [];
+  }
+  const threshold = Math.max(2, Math.ceil(needle.length / 2));
+  return [...new Set(allHelpTokens())].map((candidate) => ({ candidate, distance: levenshtein(needle, candidate.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate)).slice(0, limit).map((entry) => entry.candidate);
+}
+
 // src/standard/service.ts
 async function runValidate(cwd) {
   return validateWorkspace2(cwd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.156",
+  "version": "0.2.159",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {