xtrm-tools 2.1.2 → 2.1.4

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

@@ -40942,6 +40942,78 @@ Installing ${skills.length} project skills:
     await installProjectSkill(skill, projectRoot);
   }
 }
+function buildProjectInitGuide() {
+  const lines = [
+    kleur_default.bold("\nProject Init \u2014 Recommended baseline\n"),
+    `${kleur_default.cyan("1) Install a quality gate skill (or equivalent checks):")}`,
+    kleur_default.dim("   - TypeScript projects: xtrm install project ts-quality-gate"),
+    kleur_default.dim("   - Python projects:     xtrm install project py-quality-gate"),
+    kleur_default.dim("   - TDD workflow:        xtrm install project tdd-guard"),
+    "",
+    `${kleur_default.cyan("2) Ensure your checks are actually configured in this repo:")}`,
+    kleur_default.dim("   - Testing: commands should run and fail when behavior regresses"),
+    kleur_default.dim("   - Linting/formatting: ESLint+Prettier (TS) or ruff (Python)"),
+    kleur_default.dim("   - Type checks: tsc (TS) or mypy/pyright (Python)"),
+    kleur_default.dim("   - Hooks only enforce what your project config defines"),
+    "",
+    `${kleur_default.cyan("3) Optional: Service Skills Set (service-skills-set)")}`,
+    kleur_default.dim("   - For multi-service/Docker repos with repeated operational workflows"),
+    kleur_default.dim("   - Adds project hooks + skills that route Claude to service-specific context"),
+    kleur_default.dim("   - Helps keep architecture knowledge persistent across sessions"),
+    "",
+    kleur_default.bold("Quick start commands:"),
+    kleur_default.dim("   xtrm install project list"),
+    kleur_default.dim("   xtrm install project ts-quality-gate   # or py-quality-gate / tdd-guard"),
+    ""
+  ];
+  return lines.join("\n");
+}
+async function printProjectInitGuide() {
+  console.log(buildProjectInitGuide());
+  await runBdInitForProject();
+}
+async function installProjectByName(toolName) {
+  if (toolName === "all" || toolName === "*") {
+    await installAllProjectSkills();
+    return;
+  }
+  await installProjectSkill(toolName);
+}
+async function runBdInitForProject() {
+  let projectRoot;
+  try {
+    projectRoot = getProjectRoot();
+  } catch (err) {
+    console.log(kleur_default.yellow(`
+  \u26A0 Skipping bd init: ${err.message}
+`));
+    return;
+  }
+  console.log(kleur_default.bold("Running beads initialization (bd init)..."));
+  const result = (0, import_child_process2.spawnSync)("bd", ["init"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    timeout: 15e3
+  });
+  if (result.error) {
+    console.log(kleur_default.yellow(`  \u26A0 Could not run bd init (${result.error.message})`));
+    return;
+  }
+  if (result.status !== 0) {
+    const text = `${result.stdout || ""}
+${result.stderr || ""}`.toLowerCase();
+    if (text.includes("already initialized")) {
+      console.log(kleur_default.dim("  \u2713 beads workspace already initialized"));
+      return;
+    }
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    console.log(kleur_default.yellow(`  \u26A0 bd init exited with code ${result.status}`));
+    return;
+  }
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+}
 async function listProjectSkills() {
   const entries = await getAvailableProjectSkills();
   if (entries.length === 0) {
@@ -40994,11 +41066,7 @@ function createInstallProjectCommand() {
   const installProjectCmd = new Command("project").description("Install a project-specific skill package");
   installProjectCmd.argument("<tool-name>", "Name of the project skill to install").action(async (toolName) => {
     try {
-      if (toolName === "all" || toolName === "*") {
-        await installAllProjectSkills();
-        return;
-      }
-      await installProjectSkill(toolName);
+      await installProjectByName(toolName);
     } catch (err) {
       console.error(kleur_default.red(`
 \u2717 ${err.message}
@@ -41009,9 +41077,33 @@ function createInstallProjectCommand() {
   const listCmd = new Command("list").description("List available project skills").action(async () => {
     await listProjectSkills();
   });
+  const initCmd = new Command("init").description("Show project onboarding guidance (quality gates + service skills)").action(async () => {
+    await printProjectInitGuide();
+  });
   installProjectCmd.addCommand(listCmd);
+  installProjectCmd.addCommand(initCmd);
   return installProjectCmd;
 }
+function createProjectCommand() {
+  const projectCmd = new Command("project").description("Project skill onboarding and installation helpers");
+  projectCmd.command("init").description("Show project onboarding guidance (quality gates + service skills)").action(async () => {
+    await printProjectInitGuide();
+  });
+  projectCmd.command("list").description("List available project skills").action(async () => {
+    await listProjectSkills();
+  });
+  projectCmd.command("install").argument("<tool-name>", "Name of the project skill to install").description("Alias for xtrm install project <tool-name>").action(async (toolName) => {
+    try {
+      await installProjectByName(toolName);
+    } catch (err) {
+      console.error(kleur_default.red(`
+\u2717 ${err.message}
+`));
+      process.exit(1);
+    }
+  });
+  return projectCmd;
+}
 
 // src/commands/install.ts
 var import_child_process3 = require("child_process");
@@ -55703,6 +55795,7 @@ program2.exitOverride((err) => {
   process.exit(1);
 });
 program2.addCommand(createInstallCommand());
+program2.addCommand(createProjectCommand());
 program2.addCommand(createStatusCommand());
 program2.addCommand(createResetCommand());
 program2.addCommand(createHelpCommand());