@hyperdrive.bot/gut 0.1.14-alpha.0 → 0.1.15-alpha.0

package/README.md

@@ -18,7 +18,7 @@ $ npm install -g @hyperdrive.bot/gut
 $ gut COMMAND
 running command...
 $ gut (--version)
-@hyperdrive.bot/gut/0.1.14-alpha.0 linux-x64 node-v22.22.2
+@hyperdrive.bot/gut/0.1.15-alpha.0 linux-x64 node-v22.22.2
 $ gut --help [COMMAND]
 USAGE
   $ gut COMMAND
@@ -72,6 +72,11 @@ USAGE
 * [`gut used-by [ENTITY]`](#gut-used-by-entity)
 * [`gut workspace ACTION`](#gut-workspace-action)
 * [`gut worktree create NAME`](#gut-worktree-create-name)
+* [`gut worktree gc`](#gut-worktree-gc)
+* [`gut worktree list`](#gut-worktree-list)
+* [`gut worktree prune`](#gut-worktree-prune)
+* [`gut worktree remove NAME`](#gut-worktree-remove-name)
+* [`gut worktree status [NAME]`](#gut-worktree-status-name)
 
 ## `gut add [PATH]`
 
@@ -1215,4 +1220,101 @@ EXAMPLES
 
   GUT_WORKTREE_DIR=/tmp/gut-worktrees gut worktree create feature/ci-run
 ```
+
+## `gut worktree gc`
+
+Remove worktrees older than a given duration (garbage collection)
+
+```
+USAGE
+  $ gut worktree gc -o <value> [-n] [-f]
+
+FLAGS
+  -f, --force               Remove even worktrees with uncommitted changes
+  -n, --dry-run             List candidates without removing anything
+  -o, --older-than=<value>  (required) Duration threshold (e.g. '7d', '24h', '30m', '90s')
+
+DESCRIPTION
+  Remove worktrees older than a given duration (garbage collection)
+
+EXAMPLES
+  $ gut worktree gc --older-than 7d
+
+  $ gut worktree gc --older-than 14d --force
+
+  $ gut worktree gc --older-than 7d --dry-run
+```
+
+## `gut worktree list`
+
+List all active worktrees with metadata and staleness detection
+
+```
+USAGE
+  $ gut worktree list
+
+DESCRIPTION
+  List all active worktrees with metadata and staleness detection
+
+EXAMPLES
+  $ gut worktree list
+```
+
+## `gut worktree prune`
+
+Remove worktree records whose paths no longer exist on disk
+
+```
+USAGE
+  $ gut worktree prune
+
+DESCRIPTION
+  Remove worktree records whose paths no longer exist on disk
+
+EXAMPLES
+  $ gut worktree prune
+```
+
+## `gut worktree remove NAME`
+
+Remove a worktree and all entity worktrees
+
+```
+USAGE
+  $ gut worktree remove NAME [-f]
+
+ARGUMENTS
+  NAME  Worktree name to remove
+
+FLAGS
+  -f, --force  Remove even with uncommitted changes
+
+DESCRIPTION
+  Remove a worktree and all entity worktrees
+
+EXAMPLES
+  $ gut worktree remove workflow/batch
+
+  $ gut worktree remove workflow/batch --force
+```
+
+## `gut worktree status [NAME]`
+
+Show per-entity git status for worktrees
+
+```
+USAGE
+  $ gut worktree status [NAME]
+
+ARGUMENTS
+  NAME  Worktree name (shows all if omitted)
+
+DESCRIPTION
+  Show per-entity git status for worktrees
+
+EXAMPLES
+  $ gut worktree status
+
+  $ gut worktree status workflow/deploy-batch
+```
 <!-- commandsstop -->

package/dist/commands/claude/init.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ClaudeInit extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    protected get requiresInit(): boolean;
+    run(): Promise<void>;
+}

package/dist/commands/claude/init.js

@@ -0,0 +1,120 @@
+import { Flags } from '@oclif/core';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { BaseCommand } from '../../base-command.js';
+const GUT_START = '<!-- gut:start -->';
+const GUT_END = '<!-- gut:end -->';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const templateDir = join(__dirname, '..', '..', '..', 'templates', 'claude-init');
+export default class ClaudeInit extends BaseCommand {
+    static description = 'Scaffold Claude Code configuration for gut';
+    static examples = [
+        '<%= config.bin %> claude init',
+        '<%= config.bin %> claude init --dry-run',
+        '<%= config.bin %> claude init --force',
+    ];
+    static flags = {
+        'dry-run': Flags.boolean({ description: 'Preview changes without writing files' }),
+        force: Flags.boolean({ char: 'f', description: 'Overwrite existing gut section and command files' }),
+    };
+    get requiresInit() {
+        return false;
+    }
+    async run() {
+        const { flags } = await this.parse(ClaudeInit);
+        const dryRun = flags['dry-run'];
+        const force = flags.force;
+        // Validate template directory
+        if (!existsSync(templateDir)) {
+            this.error('Template directory not found at: ' + templateDir);
+        }
+        const results = [];
+        // --- CLAUDE.md handler ---
+        const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
+        const templateContent = readFileSync(join(templateDir, 'claude-md-section.md'), 'utf-8');
+        if (!existsSync(claudeMdPath)) {
+            // No CLAUDE.md — create new file
+            if (dryRun) {
+                results.push({ action: 'created', file: 'CLAUDE.md' });
+            }
+            else {
+                writeFileSync(claudeMdPath, templateContent);
+                results.push({ action: 'created', file: 'CLAUDE.md' });
+            }
+        }
+        else {
+            const existing = readFileSync(claudeMdPath, 'utf-8');
+            if (existing.includes(GUT_START)) {
+                if (force) {
+                    // Remove existing gut section and re-append
+                    const cleaned = existing.replace(new RegExp(GUT_START + '[\\s\\S]*?' + GUT_END, 'g'), '').trimEnd();
+                    if (!dryRun) {
+                        writeFileSync(claudeMdPath, cleaned + '\n\n' + templateContent);
+                    }
+                    results.push({ action: 'modified', file: 'CLAUDE.md' });
+                }
+                else {
+                    this.log('gut section already exists (use --force to overwrite)');
+                    results.push({ action: 'skipped', file: 'CLAUDE.md' });
+                }
+            }
+            else {
+                // Append gut section
+                if (!dryRun) {
+                    writeFileSync(claudeMdPath, existing + '\n\n' + templateContent);
+                }
+                results.push({ action: 'modified', file: 'CLAUDE.md' });
+            }
+        }
+        // --- .claude/commands/ handler ---
+        const commandsDir = join(process.cwd(), '.claude', 'commands');
+        const commandFiles = ['gut-status.md', 'gut-affected.md'];
+        if (!existsSync(commandsDir)) {
+            if (dryRun) {
+                this.log('.claude/commands/ → create directory');
+            }
+            else {
+                mkdirSync(commandsDir, { recursive: true });
+            }
+        }
+        for (const filename of commandFiles) {
+            const source = join(templateDir, 'commands', filename);
+            const target = join(commandsDir, filename);
+            if (existsSync(target) && !force) {
+                this.log(`${filename} → already exists (use --force to overwrite)`);
+                results.push({ action: 'skipped', file: `.claude/commands/${filename}` });
+            }
+            else {
+                if (!dryRun) {
+                    // Ensure directory exists (in case only some files existed)
+                    mkdirSync(commandsDir, { recursive: true });
+                    copyFileSync(source, target);
+                }
+                results.push({ action: 'created', file: `.claude/commands/${filename}` });
+            }
+        }
+        // --- Summary ---
+        const heading = dryRun ? 'gut claude init (dry run)' : 'gut claude init';
+        this.log('');
+        this.log(chalk.bold(heading));
+        this.log('');
+        for (const { action, file } of results) {
+            const label = action === 'created'
+                ? chalk.green(action)
+                : action === 'modified'
+                    ? chalk.yellow(action)
+                    : chalk.dim(action);
+            this.log(`  ${file} → ${label}`);
+        }
+        this.log('');
+        if (dryRun) {
+            this.log('No files were modified. Remove --dry-run to apply.');
+        }
+        else {
+            this.log('Run /gut-status in Claude Code to verify');
+        }
+    }
+}

package/oclif.manifest.json

@@ -1418,6 +1418,45 @@
         "status.js"
       ]
     },
+    "claude:init": {
+      "aliases": [],
+      "args": {},
+      "description": "Scaffold Claude Code configuration for gut",
+      "examples": [
+        "<%= config.bin %> claude init",
+        "<%= config.bin %> claude init --dry-run",
+        "<%= config.bin %> claude init --force"
+      ],
+      "flags": {
+        "dry-run": {
+          "description": "Preview changes without writing files",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "force": {
+          "char": "f",
+          "description": "Overwrite existing gut section and command files",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "claude:init",
+      "pluginAlias": "@hyperdrive.bot/gut",
+      "pluginName": "@hyperdrive.bot/gut",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "claude",
+        "init.js"
+      ]
+    },
     "entity:add": {
       "aliases": [],
       "args": {
@@ -2414,5 +2453,5 @@
       ]
     }
   },
-  "version": "0.1.14-alpha.0"
+  "version": "0.1.15-alpha.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/gut",
-  "version": "0.1.14-alpha.0",
+  "version": "0.1.15-alpha.0",
   "description": "Git Unified Tooling - Enhanced git with workspace intelligence for entity-based organization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/claude-init/claude-md-section.md

@@ -0,0 +1,179 @@
+<!-- gut:start -->
+# Gut — Workspace Intelligence
+
+## What is Gut
+
+Gut is an entity-aware workspace manager for multi-repo and monorepo setups. It wraps git with workspace intelligence — focus-driven commands that scope operations to the entities you care about, dependency analysis across repos, and atomic multi-repo worktree isolation. The CLI is `gut` (npm: `@hyperdrive.bot/gut`).
+
+## Mental Model
+
+### Entities
+
+Entities are the building blocks of your workspace. Each entity has a type, name, and path:
+
+| Type | Purpose |
+|------|---------|
+| `client` | Client projects |
+| `company` | Company-level repositories |
+| `delivery` | Delivery/app projects |
+| `initiative` | Internal initiatives |
+| `module` | Packages and libraries |
+| `prospect` | Prospect/sales projects |
+| `service` | Backend services |
+| `system` | System-level infrastructure |
+| `tool` | Developer tools |
+
+Entities are stored in `.gut/config.json` and auto-discovered from directory patterns (`apps/` → delivery, `packages/` → module, `libs/` → module, `services/` → service, `tools/` → tool).
+
+### Focus System
+
+Focus scopes all gut commands to selected entities. When you focus on an entity, commands like `gut status`, `gut commit`, and `gut push` operate only on that entity's repository.
+
+| Mode | Purpose |
+|------|---------|
+| `audit` | Reviewing code quality and compliance |
+| `debug` | Investigating and fixing issues |
+| `delivery` | Building and shipping features |
+| `proposal` | Preparing proposals and estimates |
+| `research` | Exploring and prototyping |
+| `strategy` | Planning and architecture |
+
+Focus state is stored in `.gut/focus.json` with history in `.gut/history.json` (max 10 entries).
+
+### Worktrees
+
+Gut provides atomic multi-repo isolation via `gut worktree create`. This creates a super-repo worktree plus per-entity worktrees on a new branch, allowing isolated pipeline runs without affecting your working tree. Default location: `~/.local/share/gut/worktrees/<slug>`.
+
+## Command Reference
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `gut init` | Initialize a gut workspace |
+| `gut quick-setup` | Quick workspace setup wizard |
+
+### Entity
+
+| Command | Description |
+|---------|-------------|
+| `gut entity add` | Add entity to workspace |
+| `gut entity clone` | Clone entity repository |
+| `gut entity clone-all` | Clone all entities |
+| `gut entity list` | List entities |
+| `gut entity remove` | Remove entity |
+
+### Focus
+
+| Command | Description |
+|---------|-------------|
+| `gut focus` | Set focus on entities |
+| `gut unfocus` | Clear focus |
+| `gut back` | Return to previous focus/branch |
+| `gut context` | Show current focus context |
+| `gut contexts` | List saved focus contexts |
+
+### Git
+
+| Command | Description |
+|---------|-------------|
+| `gut status` | Show git status for focused entities |
+| `gut commit` | Commit changes across focused entities |
+| `gut push` | Push changes to remotes |
+| `gut pull` | Pull changes from remotes |
+| `gut checkout` | Checkout branches across entities |
+| `gut sync` | Sync across entities |
+
+### Worktree
+
+| Command | Description |
+|---------|-------------|
+| `gut worktree create` | Create mirrored worktrees for super-repo + focused entities |
+| `gut worktree list` | List worktrees |
+| `gut worktree remove` | Remove worktree |
+| `gut worktree status` | Show worktree status |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `gut affected` | Detect entities potentially affected by changes |
+| `gut deps` | Analyze dependencies |
+| `gut graph` | Visualize dependency graph |
+| `gut related` | Find related entities |
+| `gut used-by` | Show what uses an entity |
+| `gut stack` | Show dependency stack |
+| `gut patterns` | Analyze patterns across codebase |
+| `gut insights` | Show insights about entities |
+| `gut audit` | Run audits across entities |
+
+### Tickets
+
+| Command | Description |
+|---------|-------------|
+| `gut ticket focus` | Focus on a ticket |
+| `gut ticket get` | Get ticket details |
+| `gut ticket list` | List tickets |
+| `gut ticket sync` | Sync tickets |
+| `gut ticket update` | Update ticket |
+| `gut ticket config` | Configure ticket system |
+
+### Auth
+
+| Command | Description |
+|---------|-------------|
+| `gut auth login` | Authenticate |
+| `gut auth logout` | Logout |
+| `gut auth status` | Show auth status |
+
+### Other
+
+| Command | Description |
+|---------|-------------|
+| `gut repos` | List repositories |
+| `gut recent` | Show recent activity |
+| `gut add` | Add a git submodule or dependency |
+| `gut extract` | Extract code/modules |
+| `gut workspace` | Workspace management |
+
+## Common Workflows
+
+1. **Start a client project:**
+   ```
+   gut init
+   gut entity add my-client client ./path
+   gut focus client my-client --mode delivery
+   gut context
+   ```
+
+2. **Check blast radius before changes:**
+   ```
+   gut affected --verbose
+   ```
+   Review confidence levels (high/medium/low) and dependency reasons before making cross-entity changes.
+
+3. **Create isolated worktree for pipeline run:**
+   ```
+   gut focus client my-client
+   gut worktree create feature-x --install
+   cd ~/.local/share/gut/worktrees/feature-x
+   ```
+
+4. **Explore workspace:**
+   ```
+   gut entity list
+   gut focus <entity>
+   gut context
+   gut status --all --verbose
+   ```
+
+## Rules for Claude
+
+- Prefer `gut` commands over raw `git` when inside a gut workspace (`.gut/` directory exists)
+- Always check current focus with `gut context` before suggesting git operations
+- Use `gut affected --verbose` to understand blast radius before making cross-entity changes
+- Never modify `.gut/` directory contents directly — use gut commands
+- Use `gut status --all --verbose` for full workspace status, not `git status`
+- When a gut command fails, check if the workspace is initialized (`gut init`) and if entities are focused (`gut context`)
+- Use `gut worktree create` for isolated pipeline/workflow runs — never create git worktrees manually in a gut workspace
+<!-- gut:end -->

package/templates/claude-init/commands/gut-affected.md

@@ -0,0 +1,40 @@
+Analyze which entities are potentially affected by recent changes in the current focus.
+
+## Steps
+
+1. Run `gut affected --verbose` to detect entities affected by changes since the last commit
+
+## Fallback — no entities focused
+
+If the command fails or returns no results because no entities are currently focused:
+
+1. Tell the user: "No entities are focused. You need to focus on an entity first."
+2. Suggest: Run `gut focus <entity-name>` to set focus on the entity you're working on
+3. Then retry `/gut-affected`
+
+## Interpreting the output
+
+### Confidence levels
+Results are grouped by how likely an entity is to be affected:
+- **High** — direct dependency or shared code path changed
+- **Medium** — related configuration or schema change detected
+- **Low** — indirect or transitive dependency change
+
+### Change types
+Each affected entity shows what kind of change triggered the detection:
+- **API** — API contract or endpoint changes
+- **Config** — configuration file changes (serverless.yml, package.json, etc.)
+- **Schema** — database schema or type definition changes
+- **Dependency** — shared dependency or package version changes
+
+### Verbose output
+With `--verbose`, each affected entity includes a file-level breakdown showing exactly which changed files triggered the detection.
+
+## Suggested actions
+
+Based on the affected entities list, suggest which entities the user should:
+- **Review** — entities with high-confidence API or schema changes
+- **Test** — entities with config or dependency changes that may break at runtime
+- **Deploy** — entities that depend on the changed code and need redeployment
+
+Prioritize high-confidence results first. For low-confidence results, mention them but note they may not require immediate action.

package/templates/claude-init/commands/gut-status.md

@@ -0,0 +1,33 @@
+Show the current gut context and git status across all entities in the super-repo.
+
+## Steps
+
+1. Run `gut context` to show the current focus context (which entities are focused, their types, and paths)
+2. Run `gut status --all --verbose` to show git status across all entities with file-level detail
+
+## Interpreting the output
+
+### Entity type emojis
+- 🏢 = client
+- 🚀 = initiative
+- 🏗️ = company
+- 📦 = package
+- 🌐 = web-app
+
+### Status indicators
+- ✓ = clean (no uncommitted changes)
+- ● = has changes (staged, unstaged, or untracked files)
+
+### Verbose output
+When `--verbose` is used, each entity with changes shows file-level details:
+- **Staged** — files added to the index, ready to commit
+- **Unstaged** — modified files not yet staged
+- **Untracked** — new files not tracked by git
+
+## Summary
+
+After running both commands, present a concise summary of:
+- Which entities have uncommitted changes
+- What kind of changes each has (staged, unstaged, untracked)
+- How many files are affected per entity
+- Any entities that are currently focused