@hyperdrive.bot/gut 0.1.12 → 0.1.13

package/README.md

@@ -18,7 +18,7 @@ $ npm install -g @hyperdrive.bot/gut
 $ gut COMMAND
 running command...
 $ gut (--version)
-@hyperdrive.bot/gut/0.1.12 linux-x64 node-v22.22.1
+@hyperdrive.bot/gut/0.1.13 linux-x64 node-v22.22.1
 $ gut --help [COMMAND]
 USAGE
   $ gut COMMAND

package/dist/commands/context.d.ts

@@ -2,5 +2,9 @@ import { BaseCommand } from '../base-command.js';
 export default class Context extends BaseCommand {
     static description: string;
     static examples: string[];
+    static flags: {
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/context.js

@@ -1,3 +1,4 @@
+import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import path from 'node:path';
 import { BaseCommand } from '../base-command.js';
@@ -5,22 +6,106 @@ export default class Context extends BaseCommand {
     static description = 'Show current focus context with entity details';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --json',
+        '<%= config.bin %> <%= command.id %> --json --all',
     ];
+    static flags = {
+        all: Flags.boolean({
+            default: false,
+            description: 'Include all registered entities, not just focused ones (implies --json or adds to text output)',
+        }),
+        json: Flags.boolean({
+            default: false,
+            description: 'Emit structured JSON for programmatic consumption (includes per-entity branch + hasUncommitted)',
+        }),
+    };
     async run() {
-        await this.parse(Context);
+        const { flags } = await this.parse(Context);
+        const workspaceRoot = this.configService.getWorkspaceRoot();
         const focusedEntities = await this.focusService.getFocusedEntities();
-        if (focusedEntities.length === 0) {
+        const focus = await this.focusService.getCurrentFocus();
+        const focusedNames = new Set(focusedEntities.map(e => e.name));
+        // For JSON or --all, resolve the full entity set. For normal text output,
+        // keep the existing behavior (focused only).
+        const includeAll = flags.json || flags.all;
+        const entitiesToReport = includeAll
+            ? this.entityService.getAllEntities()
+            : focusedEntities;
+        // Enrich each entity with branch + uncommitted status. Entities may not
+        // exist on disk (not cloned), so be defensive.
+        const enriched = [];
+        for (const entity of entitiesToReport) {
+            const relativePath = entity.path.replace(/^\.\//, '');
+            const absolutePath = path.isAbsolute(entity.path)
+                ? entity.path
+                : path.join(workspaceRoot, relativePath);
+            let currentBranch = null;
+            let hasUncommitted = false;
+            let pathExists = false;
+            try {
+                const { existsSync } = await import('node:fs');
+                pathExists = existsSync(path.join(absolutePath, '.git')) || existsSync(absolutePath);
+            }
+            catch {
+                pathExists = false;
+            }
+            if (pathExists) {
+                try {
+                    currentBranch = await this.gitService.getCurrentBranch(absolutePath);
+                }
+                catch {
+                    currentBranch = null;
+                }
+                try {
+                    hasUncommitted = await this.gitService.hasChanges(absolutePath);
+                }
+                catch {
+                    hasUncommitted = false;
+                }
+            }
+            enriched.push({
+                currentBranch,
+                focused: focusedNames.has(entity.name),
+                hasUncommitted,
+                name: entity.name,
+                path: relativePath,
+                pathExists,
+                type: entity.type,
+            });
+        }
+        if (flags.json) {
+            const payload = {
+                entities: enriched,
+                focus: {
+                    entities: [...focusedNames],
+                    mode: focus?.mode ?? null,
+                },
+                workspaceRoot,
+            };
+            // Emit compact, machine-readable JSON on stdout. No chalk, no decoration.
+            this.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        if (focusedEntities.length === 0 && !flags.all) {
             this.log(chalk.yellow('No entities are currently focused'));
             this.log(chalk.dim('Use "gut focus <entity>" to set focus'));
             return;
         }
-        const workspaceRoot = this.configService.getWorkspaceRoot();
         this.log(chalk.bold('\n📍 Current Focus Context'));
         this.log(chalk.dim('─'.repeat(50)));
-        for (const entity of focusedEntities) {
-            this.log(`\n${chalk.green('▸')} ${chalk.bold(entity.name)}`);
+        for (const entity of enriched) {
+            if (!flags.all && !entity.focused)
+                continue;
+            const marker = entity.focused ? chalk.green('▸') : chalk.dim('·');
+            this.log(`\n${marker} ${chalk.bold(entity.name)}`);
             this.log(`  ${chalk.dim('Type:')} ${entity.type}`);
-            this.log(`  ${chalk.dim('Path:')} ${path.relative(workspaceRoot, entity.path)}`);
+            this.log(`  ${chalk.dim('Path:')} ${entity.path}`);
+            if (entity.pathExists) {
+                this.log(`  ${chalk.dim('Branch:')} ${entity.currentBranch ?? chalk.red('(unknown)')}${entity.hasUncommitted ? chalk.yellow(' *dirty') : ''}`);
+            }
+            else {
+                this.log(`  ${chalk.dim('Branch:')} ${chalk.dim('(not checked out)')}`);
+            }
         }
         this.log(chalk.dim('\n─'.repeat(50)));
         this.log(`${chalk.dim('Total focused entities:')} ${focusedEntities.length}`);

package/dist/commands/focus.js

@@ -125,6 +125,9 @@ export default class Focus extends BaseCommand {
                     this.log(`  ${this.getTypeEmoji(entity.type)} ${entity.name} (${entity.type})`);
                 }
             }
+            // Machine-readable confirmation line for programmatic callers (e.g.,
+            // bmad-workflow execSync). Always printed, grep-friendly format.
+            this.log(`FOCUSED: ${entities.map(e => e.name).join(',')}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/commands/worktree/create.d.ts

@@ -7,6 +7,7 @@ export default class WorktreeCreate extends BaseCommand {
     static examples: string[];
     static flags: {
         'base-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        entity: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         from: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         install: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/worktree/create.js

@@ -2,8 +2,11 @@ import { Args, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { BaseCommand } from '../../base-command.js';
+import { parseEntitySpecs } from '../../utils/entity-spec.js';
+const xdgDefaultBaseDir = path.join(os.homedir(), '.local', 'share', 'gut', 'worktrees');
 export default class WorktreeCreate extends BaseCommand {
     static args = {
         name: Args.string({ description: 'Branch name for the worktree', required: true }),
@@ -13,9 +16,18 @@ export default class WorktreeCreate extends BaseCommand {
         '<%= config.bin %> worktree create workflow/deploy-batch',
         '<%= config.bin %> worktree create workflow/deploy-batch --from master --install',
         '<%= config.bin %> worktree create feature/story-42 --base-dir /home/user/worktrees',
+        '<%= config.bin %> worktree create seo-lake --entity serverless-api:feature/seo-lake --entity sign',
+        'GUT_WORKTREE_DIR=/tmp/gut-worktrees <%= config.bin %> worktree create feature/ci-run',
     ];
     static flags = {
-        'base-dir': Flags.string({ default: '/tmp/gut-worktrees', description: 'Root directory for worktrees' }),
+        'base-dir': Flags.string({
+            default: async () => process.env.GUT_WORKTREE_DIR ?? xdgDefaultBaseDir,
+            description: 'Root directory for worktrees (default: ~/.local/share/gut/worktrees, override via GUT_WORKTREE_DIR env var; explicit --base-dir wins)',
+        }),
+        entity: Flags.string({
+            description: 'Entity to include, optionally pinned to a branch via "name:branch". Repeatable. Overrides current focus when provided.',
+            multiple: true,
+        }),
         from: Flags.string({ description: 'Base branch to create from (defaults to current branch)' }),
         install: Flags.boolean({ default: false, description: 'Run pnpm install after creation' }),
     };
@@ -24,6 +36,9 @@ export default class WorktreeCreate extends BaseCommand {
         const workspaceRoot = this.configService.getWorkspaceRoot();
         const slug = args.name.replace(/\//g, '-');
         const wtPath = path.join(flags['base-dir'], slug);
+        // Ensure the base directory exists — git worktree add creates the target
+        // dir, but the parent (the base dir itself) must already exist.
+        fs.mkdirSync(flags['base-dir'], { recursive: true });
         const baseBranch = flags.from ?? await this.gitService.getCurrentBranch(workspaceRoot);
         // --- Validation (AC: 7) ---
         const existing = this.worktreeService.get(args.name);
@@ -35,10 +50,35 @@ export default class WorktreeCreate extends BaseCommand {
         if (branchCollision) {
             this.error(`Branch "${args.name}" already has a worktree at ${branchCollision.path}. Remove it first or use a different name.`);
         }
-        // --- Validation (AC: 8) ---
-        const focusedEntities = await this.focusService.getFocusedEntities();
-        if (focusedEntities.length === 0) {
-            this.error('No entities focused. Use "gut focus <entity>" first.');
+        // --- Resolve entity set: --entity flag overrides focus ---
+        let entitySpecs;
+        try {
+            entitySpecs = parseEntitySpecs(flags.entity);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.error(message);
+        }
+        let selectedEntities;
+        const branchOverrides = new Map();
+        if (entitySpecs.length > 0) {
+            selectedEntities = [];
+            for (const spec of entitySpecs) {
+                const entity = this.entityService.findEntity(spec.name);
+                if (!entity) {
+                    this.error(`Entity "${spec.name}" not found in workspace config. Run \`gut entity list\` to see available entities.`);
+                }
+                selectedEntities.push(entity);
+                if (spec.branch) {
+                    branchOverrides.set(entity.name, spec.branch);
+                }
+            }
+        }
+        else {
+            selectedEntities = await this.focusService.getFocusedEntities();
+            if (selectedEntities.length === 0) {
+                this.error('No entities focused and no --entity flag provided. Use "gut focus <entity>" first, or pass --entity <name> (repeatable).');
+            }
         }
         // --- Create worktrees with atomic rollback (AC: 1, 2, 9) ---
         const createdWorktrees = [];
@@ -49,14 +89,18 @@ export default class WorktreeCreate extends BaseCommand {
             createdWorktrees.push({ repoPath: workspaceRoot, wtPath });
             this.log(chalk.green('✓ Super-repo worktree created at ' + wtPath));
             // Per-entity worktrees (AC: 2)
-            for (const entity of focusedEntities) {
+            for (const entity of selectedEntities) {
                 const entityRelativePath = entity.path.replace(/^\.\//, '');
                 const entityWtPath = path.join(wtPath, entityRelativePath);
                 const entityMainPath = path.join(workspaceRoot, entityRelativePath);
-                // Always use the entity's current branch as base — the super-repo branch
-                // may exist but be stale (e.g., api has master but works on develop)
-                const entityBaseBranch = await this.gitService.getCurrentBranch(entityMainPath);
-                if (entityBaseBranch !== baseBranch) {
+                // Branch override from --entity name:branch wins; otherwise use entity's
+                // current branch in the main repo.
+                const override = branchOverrides.get(entity.name);
+                const entityBaseBranch = override ?? await this.gitService.getCurrentBranch(entityMainPath);
+                if (override) {
+                    this.log(chalk.cyan(`  Branch override: ${entity.name} → ${override}`));
+                }
+                else if (entityBaseBranch !== baseBranch) {
                     this.log(chalk.yellow(`⚠ Entity "${entity.name}" is on "${entityBaseBranch}" (super-repo: "${baseBranch}")`));
                 }
                 // Remove submodule stub
@@ -64,7 +108,7 @@ export default class WorktreeCreate extends BaseCommand {
                 // Create entity worktree
                 await this.gitService.worktreeAdd(entityMainPath, entityWtPath, args.name, entityBaseBranch);
                 createdWorktrees.push({ repoPath: entityMainPath, wtPath: entityWtPath });
-                this.log(chalk.green(`✓ Entity worktree: ${entity.name} → ${args.name}`));
+                this.log(chalk.green(`✓ Entity worktree: ${entity.name} → ${args.name} (from ${entityBaseBranch})`));
                 entityRecords.push({
                     branch: args.name,
                     entityName: entity.name,
@@ -79,7 +123,7 @@ export default class WorktreeCreate extends BaseCommand {
                 await this.gitService.worktreeRemove(entry.repoPath, entry.wtPath, true).catch(() => { });
             }
             await this.gitService.worktreePrune(workspaceRoot).catch(() => { });
-            for (const entity of focusedEntities) {
+            for (const entity of selectedEntities) {
                 const entityRelativePath = entity.path.replace(/^\.\//, '');
                 const entityMainPath = path.join(workspaceRoot, entityRelativePath);
                 await this.gitService.worktreePrune(entityMainPath).catch(() => { });

package/dist/utils/entity-spec.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parses `--entity` flag values for `gut worktree create`.
+ *
+ * Each spec is either a bare entity name (`serverless-api`) or a pinned
+ * spec (`serverless-api:feature/seo-lake`). The first `:` separates the
+ * entity name from the branch; the branch itself may contain `/` or `-`.
+ *
+ * Invalid shapes throw with a descriptive message so callers can surface
+ * the error to the user.
+ */
+export interface EntitySpec {
+    branch?: string;
+    name: string;
+}
+export declare function parseEntitySpecs(specs: string[] | undefined): EntitySpec[];

package/dist/utils/entity-spec.js

@@ -0,0 +1,29 @@
+export function parseEntitySpecs(specs) {
+    if (!specs || specs.length === 0)
+        return [];
+    const parsed = [];
+    for (const raw of specs) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) {
+            parsed.push({ name: trimmed });
+            continue;
+        }
+        const name = trimmed.slice(0, colonIdx).trim();
+        const branch = trimmed.slice(colonIdx + 1).trim();
+        if (!name) {
+            throw new Error(`Invalid --entity spec "${raw}": missing entity name before ":"`);
+        }
+        if (branch) {
+            parsed.push({ branch, name });
+        }
+        else {
+            // "name:" is tolerated — same as bare name. Useful if a caller builds
+            // specs programmatically and omits the branch for some entities.
+            parsed.push({ name });
+        }
+    }
+    return parsed;
+}

package/oclif.manifest.json

@@ -301,9 +301,24 @@
       "args": {},
       "description": "Show current focus context with entity details",
       "examples": [
-        "<%= config.bin %> <%= command.id %>"
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --json",
+        "<%= config.bin %> <%= command.id %> --json --all"
       ],
-      "flags": {},
+      "flags": {
+        "all": {
+          "description": "Include all registered entities, not just focused ones (implies --json or adds to text output)",
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Emit structured JSON for programmatic consumption (includes per-entity branch + hasUncommitted)",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
       "id": "context",
@@ -2186,17 +2201,26 @@
       "examples": [
         "<%= config.bin %> worktree create workflow/deploy-batch",
         "<%= config.bin %> worktree create workflow/deploy-batch --from master --install",
-        "<%= config.bin %> worktree create feature/story-42 --base-dir /home/user/worktrees"
+        "<%= config.bin %> worktree create feature/story-42 --base-dir /home/user/worktrees",
+        "<%= config.bin %> worktree create seo-lake --entity serverless-api:feature/seo-lake --entity sign",
+        "GUT_WORKTREE_DIR=/tmp/gut-worktrees <%= config.bin %> worktree create feature/ci-run"
       ],
       "flags": {
         "base-dir": {
-          "description": "Root directory for worktrees",
+          "description": "Root directory for worktrees (default: ~/.local/share/gut/worktrees, override via GUT_WORKTREE_DIR env var; explicit --base-dir wins)",
           "name": "base-dir",
-          "default": "/tmp/gut-worktrees",
+          "default": "/root/.local/share/gut/worktrees",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "entity": {
+          "description": "Entity to include, optionally pinned to a branch via \"name:branch\". Repeatable. Overrides current focus when provided.",
+          "name": "entity",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
         "from": {
           "description": "Base branch to create from (defaults to current branch)",
           "name": "from",
@@ -2227,5 +2251,5 @@
       ]
     }
   },
-  "version": "0.1.12"
+  "version": "0.1.13"
 }

package/package.json

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