xtrm-tools 2.1.1 → 2.1.3

package/README.md

@@ -198,19 +198,23 @@ Task intake and service routing for Docker service projects.
 
 ### Standalone Hooks
 
-**pip-venv-guard.py**
-- Trigger: PreToolUse (Bash)
-- Purpose: Prevent `pip install` outside virtual environments
+**main-guard.mjs**
+- Trigger: PreToolUse (Write|Edit|MultiEdit)
+- Purpose: Blocks direct edits on protected branches with structured deny output
 
 **type-safety-enforcement.py**
 - Trigger: PreToolUse (Bash|Edit|Write)
 - Purpose: Enforce type safety in Python code
 
-**statusline.js**
-- Trigger: StatusLine
-- Purpose: Display custom status line information
+**agent_context.py**
+- Trigger: Support module used by Python hooks
+- Purpose: Shared hook input/output helper
 
-**NOTE** certain skills are third-party utilities, i believe they can be useful.
+**beads gate hooks** (installed with `xtrm install all`, or included when beads+dolt is available):
+- `beads-edit-gate.mjs` (PreToolUse)
+- `beads-commit-gate.mjs` (PreToolUse)
+- `beads-stop-gate.mjs` (Stop)
+- `beads-close-memory-prompt.mjs` (PostToolUse)
 
 ## Project Skills
 
@@ -301,11 +305,12 @@ npm link          # registers `xtrm` globally
 xtrm <command> [options]
 ```
 
-| Command  | Description                       |
-| -------- | --------------------------------- |
-| `sync`   | Sync tools to target environments |
-| `status` | Show diff without making changes  |
-| `reset`  | Clear saved preferences           |
+| Command   | Description                      |
+| --------- | -------------------------------- |
+| `install` | Install/update tools             |
+| `status`  | Show diff without making changes |
+| `reset`   | Clear saved preferences          |
+| `help`    | Show command/component overview  |
 
 ---
 
@@ -329,7 +334,7 @@ xtrm install --backport     # reverse direction: copy drifted local edits → re
 - **cli-table3 plan table**: Formatted table showing Target / + New / ↑ Update / ! Drift / Total
 - **boxen summary card**: Completion summary with green/yellow border based on drift
 - **Themed output**: Semantic colors (success, error, warning, muted, accent) via `theme.ts`
-- **Interactive consent**: Multiselect for MCP servers (space to toggle, all pre-selected)
+- **beads+dolt prerequisite flow**: `xtrm install` / `xtrm install all` check workflow backend and can install missing deps
 - **Auto-detection**: Scans Claude Code targets automatically (`~/.claude`, `%APPDATA%/Claude` on Windows) plus the `.agents/skills` cache for skills-only sync
 - **Inline sync**: `status` command offers to apply sync immediately after showing changes
 - **Single confirmation**: See full plan across all targets, confirm once
@@ -395,8 +400,8 @@ xtrm reset
 
 1. Clone this repository:
    ```bash
-   git clone https://github.com/Jaggerxtrm/jaggers-agent-tools.git
-   cd jaggers-agent-tools
+   git clone https://github.com/Jaggerxtrm/xtrm-tools.git
+   cd xtrm-tools
    ```
 
 2. Copy skills to Claude Code:
@@ -457,9 +462,9 @@ If you use Gemini CLI or Qwen CLI, you can still use xtrm-tools skills and hooks
 
 ## Configuration
 
-### MCP Servers (v1.7.0 Unified System)
+### MCP Servers (Unified CLI Sync)
 
-MCP servers are configured from canonical sources with automatic format adaptation for each agent.
+MCP servers are configured from canonical sources and synced via official CLI commands.
 
 **Core Servers** (installed by default):
 - **serena**: Code analysis (requires `uvx`, auto project detection)
@@ -484,22 +489,24 @@ MCP servers are configured from canonical sources with automatic format adaptati
 - **Persistence:** Values preserved across syncs; never overwritten
 - Edit `~/.config/xtrm-tools/.env` to add your API keys manually
 
-**Unified MCP CLI Sync (v1.7.0)**:
-- Uses official `mcp add`/`mcp remove`/`mcp list` commands for all agents
+**Unified MCP CLI Sync**:
+- Uses official `claude mcp add` / `claude mcp list` commands
 - **Idempotent:** Re-running is always safe — skips already-installed servers
 - **Deduplication:** Prevents same server from syncing N times when multiple dirs selected
-- **Interactive consent:** Multiselect prompt (space to toggle, all pre-selected)
 - **Prerequisite auto-install:** Runs `npm install -g gitnexus` automatically when selected
 - **Post-install guidance:** Shows required next steps (e.g., `npx gitnexus analyze`)
 - **Timeout protection:** 10s timeout on CLI calls to prevent hangs
 - **Clean errors:** User-friendly messages (no stack traces)
 
-**Supported Agents**:
-- Claude Code (`~/.claude.json` via `mcp add` CLI)
-- Antigravity (`~/.gemini/antigravity/mcp_config.json` via `mcp add` CLI)
+**Scopes**:
+- Global installs (`xtrm install`, `xtrm install all`, `xtrm install basic`) sync MCP into Claude global config
+- Project installs (`xtrm install project <name|all>`) sync core MCP at project scope (`-s project`)
 
-**Deprecated (v1.7.0)**:
-- JSON file sync for Claude/Gemini/Qwen MCP — superseded by official `mcp` CLI method
+**Supported Agent**:
+- Claude Code
+
+**Deprecated**:
+- JSON file MCP sync (superseded by official CLI method)
 - Repo `.env` files — use centralized `~/.config/xtrm-tools/.env`
 
 **Documentation**: See [docs/mcp-servers-config.md](docs/mcp-servers-config.md) for complete setup guide.
@@ -526,7 +533,7 @@ Adjust hook execution timeouts in `settings.json`:
   "hooks": {
     "UserPromptSubmit": [{
       "hooks": [{
-        "timeout": 5000  // Timeout in milliseconds (5000ms = 5 seconds) for both Claude and Gemini
+        "timeout": 5000  // Timeout in milliseconds (5000ms = 5 seconds)
       }]
     }]
   }
@@ -574,7 +581,7 @@ Project-specific operational knowledge system for Docker service projects. Gives
 
 ```bash
 cd ~/projects/my-project
-python3 /path/to/jaggers-agent-tools/project-skills/service-skills-set/install-service-skills.py
+python3 /path/to/xtrm-tools/project-skills/service-skills-set/install-service-skills.py
 ```
 
 - Idempotent — safe to re-run after updates
@@ -657,7 +664,7 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 ## Repository Structure
 
 ```
-jaggers-agent-tools/
+xtrm-tools/
 ├── README.md                    # This file
 ├── CHANGELOG.md                 # Version history
 ├── ROADMAP.md                   # Future plans
@@ -667,7 +674,7 @@ jaggers-agent-tools/
 ├── cli/                         # Config Manager CLI (TypeScript)
 │   ├── src/
 │   │   ├── index.ts             # Entry point (Commander program)
-│   │   ├── commands/            # sync.ts, status.ts, reset.ts
+│   │   ├── commands/            # install.ts, install-project.ts, status.ts, reset.ts, help.ts
 │   │   ├── adapters/            # base, claude, gemini, qwen, registry
 │   │   ├── core/                # context, diff, sync-executor, manifest, rollback
 │   │   ├── utils/               # hash, atomic-config, config-adapter, env-manager, theme…
@@ -708,7 +715,7 @@ jaggers-agent-tools/
 │   ├── type-safety-enforcement.py # Type safety
 │   ├── gitnexus/
 │   │   └── gitnexus-hook.cjs    # PreToolUse knowledge graph enrichment
-│   └── statusline.js            # Status line display
+│   └── main-guard.mjs           # Protected-branch edit guard
 │
 ├── config/                      # Canonical configuration
 │   ├── mcp_servers.json         # Core MCP servers

package/cli/dist/index.cjs

@@ -41031,7 +41031,7 @@ function renderPlanTable(allChanges) {
     const missing = Object.values(changeSet).reduce((s, c) => s + c.missing.length, 0);
     const outdated = Object.values(changeSet).reduce((s, c) => s + c.outdated.length, 0);
     table.push([
-      kleur_default.white(import_path11.default.basename(target)),
+      kleur_default.white(formatTargetLabel(target)),
       missing > 0 ? kleur_default.green(String(missing)) : t.label("\u2014"),
       outdated > 0 ? kleur_default.yellow(String(outdated)) : t.label("\u2014"),
       kleur_default.bold().white(String(totalChanges))
@@ -41060,6 +41060,12 @@ async function renderSummaryCard(allChanges, totalCount, allSkipped, isDryRun) {
   }) + "\n");
 }
 var BEADS_HOOK_PATTERN = /^beads-/;
+function formatTargetLabel(target) {
+  const normalized = target.replace(/\\/g, "/").toLowerCase();
+  if (normalized.endsWith("/.agents/skills") || normalized.includes("/.agents/skills/")) return "~/.agents/skills";
+  if (normalized.endsWith("/.claude") || normalized.includes("/.claude/")) return "~/.claude";
+  return import_path11.default.basename(target);
+}
 function filterBeadsFromChangeSet(changeSet) {
   return {
     ...changeSet,
@@ -41164,7 +41170,7 @@ async function runGlobalInstall(flags, installOpts = {}) {
   }
   const diffTasks = new Listr(
     targets.map((target) => ({
-      title: import_path11.default.basename(target),
+      title: formatTargetLabel(target),
       task: async (listCtx, task) => {
         try {
           let changeSet = await calculateDiff(repoRoot, target, false);
@@ -41179,13 +41185,13 @@ async function runGlobalInstall(flags, installOpts = {}) {
             (sum, c) => sum + c.missing.length + c.outdated.length + c.drifted.length,
             0
           );
-          task.title = `${import_path11.default.basename(target)}${t.muted(` \u2014 ${totalChanges} change${totalChanges !== 1 ? "s" : ""}`)}`;
+          task.title = `${formatTargetLabel(target)}${t.muted(` \u2014 ${totalChanges} change${totalChanges !== 1 ? "s" : ""}`)}`;
           if (totalChanges > 0) {
             listCtx.allChanges.push({ target, changeSet, totalChanges, skippedDrifted: [] });
           }
         } catch (err) {
           if (err instanceof PruneModeReadError) {
-            task.title = `${import_path11.default.basename(target)} ${kleur_default.red("(skipped \u2014 cannot read in prune mode)")}`;
+            task.title = `${formatTargetLabel(target)} ${kleur_default.red("(skipped \u2014 cannot read in prune mode)")}`;
           } else {
             throw err;
           }
@@ -41221,7 +41227,7 @@ async function runGlobalInstall(flags, installOpts = {}) {
   let totalCount = 0;
   for (const { target, changeSet, skippedDrifted } of allChanges) {
     console.log(t.bold(`
-  ${sym.arrow} ${import_path11.default.basename(target)}`));
+  ${sym.arrow} ${formatTargetLabel(target)}`));
     const count = await executeSync(repoRoot, target, changeSet, syncMode, "sync", dryRun, void 0, {
       skipMcp: noMcp,
       force
@@ -41315,7 +41321,7 @@ function createInstallCommand() {
     }
     const diffTasks = new Listr(
       targets.map((target) => ({
-        title: import_path11.default.basename(target),
+        title: formatTargetLabel(target),
         task: async (listCtx, task) => {
           try {
             let changeSet = await calculateDiff(repoRoot, target, prune);
@@ -41332,13 +41338,13 @@ function createInstallCommand() {
               (sum, c) => sum + c.missing.length + c.outdated.length + c.drifted.length,
               0
             );
-            task.title = `${import_path11.default.basename(target)}${t.muted(` \u2014 ${totalChanges} change${totalChanges !== 1 ? "s" : ""}`)}`;
+            task.title = `${formatTargetLabel(target)}${t.muted(` \u2014 ${totalChanges} change${totalChanges !== 1 ? "s" : ""}`)}`;
             if (totalChanges > 0) {
               listCtx.allChanges.push({ target, changeSet, totalChanges, skippedDrifted: [] });
             }
           } catch (err) {
             if (err instanceof PruneModeReadError) {
-              task.title = `${import_path11.default.basename(target)} ${kleur_default.red("(skipped \u2014 cannot read in prune mode)")}`;
+              task.title = `${formatTargetLabel(target)} ${kleur_default.red("(skipped \u2014 cannot read in prune mode)")}`;
             } else {
               throw err;
             }
@@ -41360,7 +41366,7 @@ function createInstallCommand() {
       };
       for (const target of targets) {
         console.log(t.bold(`
-  ${sym.arrow} ${import_path11.default.basename(target)}`));
+  ${sym.arrow} ${formatTargetLabel(target)}`));
         await executeSync(repoRoot, target, emptyChangeSet, syncMode, "sync", false);
       }
     }
@@ -41389,7 +41395,7 @@ function createInstallCommand() {
     let totalCount = 0;
     for (const { target, changeSet, skippedDrifted } of allChanges) {
       console.log(t.bold(`
-  ${sym.arrow} ${import_path11.default.basename(target)}`));
+  ${sym.arrow} ${formatTargetLabel(target)}`));
       const count = await executeSync(repoRoot, target, changeSet, syncMode, syncType, dryRun);
       totalCount += count;
       for (const [category, cat] of Object.entries(changeSet)) {
@@ -55230,6 +55236,12 @@ function getManifestPath(projectDir) {
 // src/commands/status.ts
 var import_fs_extra12 = __toESM(require_lib2(), 1);
 var import_path13 = __toESM(require("path"), 1);
+function formatTargetLabel2(target) {
+  const normalized = target.replace(/\\/g, "/").toLowerCase();
+  if (normalized.endsWith("/.agents/skills") || normalized.includes("/.agents/skills/")) return "~/.agents/skills";
+  if (normalized.endsWith("/.claude") || normalized.includes("/.claude/")) return "~/.claude";
+  return import_path13.default.basename(target);
+}
 function formatRelativeTime(timestamp) {
   const now = Date.now();
   const diff = now - timestamp;
@@ -55270,7 +55282,7 @@ function createStatusCommand() {
         (sum, c) => sum + c.missing.length + c.outdated.length + c.drifted.length,
         0
       );
-      results.push({ path: target, name: import_path13.default.basename(target), lastSync, changes: changeSet, totalChanges });
+      results.push({ path: target, name: formatTargetLabel2(target), lastSync, changes: changeSet, totalChanges });
     }
     if (json2) {
       console.log(JSON.stringify({ targets: results }, null, 2));
@@ -55380,6 +55392,32 @@ async function readSkillsFromDir(dir) {
   }
   return skills;
 }
+async function readProjectSkillsFromDir(dir) {
+  if (!await import_fs_extra13.default.pathExists(dir)) return [];
+  const entries = await import_fs_extra13.default.readdir(dir);
+  const skills = [];
+  for (const name of entries.sort()) {
+    const readme = import_path14.default.join(dir, name, "README.md");
+    if (!await import_fs_extra13.default.pathExists(readme)) continue;
+    const content = await import_fs_extra13.default.readFile(readme, "utf8");
+    const descLine = content.split("\n").find((line) => {
+      const trimmed = line.trim();
+      return Boolean(trimmed) && !trimmed.startsWith("#") && !trimmed.startsWith("[") && !trimmed.startsWith("<");
+    }) || "";
+    skills.push({ name, desc: descLine.replace(/[*_`]/g, "").trim() });
+  }
+  return skills;
+}
+function resolvePkgRootFallback() {
+  const candidates = [
+    import_path14.default.resolve(__dirname, "../.."),
+    import_path14.default.resolve(__dirname, "../../..")
+  ];
+  const match = candidates.find(
+    (candidate) => import_fs_extra13.default.existsSync(import_path14.default.join(candidate, "skills")) || import_fs_extra13.default.existsSync(import_path14.default.join(candidate, "project-skills"))
+  );
+  return match || null;
+}
 function col(s, width) {
   return s.length >= width ? s.slice(0, width - 1) + "\u2026" : s.padEnd(width);
 }
@@ -55391,8 +55429,11 @@ function createHelpCommand() {
     } catch {
       repoRoot = "";
     }
-    const skills = repoRoot ? await readSkillsFromDir(import_path14.default.join(repoRoot, "skills")) : [];
-    const projectSkills = repoRoot ? await readSkillsFromDir(import_path14.default.join(repoRoot, "project-skills")) : [];
+    const pkgRoot = resolvePkgRootFallback();
+    const skillsRoot = repoRoot || pkgRoot || "";
+    const projectSkillsRoot = repoRoot || pkgRoot || "";
+    const skills = skillsRoot ? await readSkillsFromDir(import_path14.default.join(skillsRoot, "skills")) : [];
+    const projectSkills = projectSkillsRoot ? await readProjectSkillsFromDir(import_path14.default.join(projectSkillsRoot, "project-skills")) : [];
     const W = 80;
     const hr = kleur_default.dim("-".repeat(W));
     const section = (title) => `
@@ -55448,11 +55489,12 @@ ${hr}`;
       (s) => `  ${kleur_default.white(col(s.name, 30))}${kleur_default.dim(s.desc)}`
     ).join("\n");
     const psSection = [
-      section("PROJECT SKILLS"),
+      section("PROJECT SKILLS + HOOKS"),
       "",
-      projectSkills.length ? psRows : kleur_default.dim("  (none found)"),
+      projectSkills.length ? psRows : kleur_default.dim("  (none found in package)"),
       "",
-      `  ${kleur_default.dim("Install: xtrm install project <name>  |  xtrm install project list")}`
+      `  ${kleur_default.dim("Install: xtrm install project <name>  |  xtrm install project list")}`,
+      `  ${kleur_default.dim("Each project skill can install .claude/skills plus project hooks/settings.")}`
     ].join("\n");
     const otherSection = [
       section("OTHER COMMANDS"),