@rtorcato/repo-tooling 3.41.0 → 3.42.0

package/AGENTS.md

@@ -28,6 +28,7 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `copy <name>` | ✅ | text only | Copy a single preset (`biome`, `tsconfig`) into the current directory. |
 | `loop guard --root <path>` | ✅ | ✅ | Guard an `ai-issue-loop` tick: repair a wrongly-bare main checkout, gate the `node_modules` rebuild (`--removed`), and assert `gh` authenticates as the declared `rules.aiLoop.agentUser`. Exit `0` continue, `1` repair failed, `2` root is not a repairable checkout or the agent identity is wrong — both non-zero halt the tick. |
 | `loop env` | ✅ | ✅ | Resolve an `ai-issue-loop` tick's variables once: `root` (main checkout, correct from inside a worktree), `worktreeRoot`, `ownerRepo`, `agentUser` (empty unless an assignable collaborator), `humanUser` (empty for org repos), `me`. Without `--json`, prints `KEY='value'` lines for `eval`. Exit `1` when the checkout or its GitHub repo cannot be resolved. |
+| `loop worktree add <ai-N-slug>` | ✅ | ✅ | Create an `ai-issue-loop` worktree at `<root>-worktrees/<slug>` on a new branch off `origin/main` (`--base`), symlink every `worktree.symlinkDirectories` entry from `.claude/settings.json`, and add `node_modules` to `.git/info/exclude`. `needsInstall: true` when no list is declared. Exit `1` when the worktree was not created or an entry is left unlinked — do not spawn an implementer. |
 
 ## Recommended workflows
 
@@ -119,6 +120,7 @@ A fixer may also **refuse** — the target file holds something the generator ca
 - `src/cli/commands/fix-targets.ts` — shared check → fix target map (used by both doctor's footer and fix's lookup)
 - `src/cli/commands/loop-guard.ts` — `loop guard`: the `--is-inside-work-tree` / `.git` invariant table and the `node_modules` rebuild gate, drained out of the ai-issue-loop skill's prose (#519)
 - `src/cli/commands/loop-env.ts` — `loop env`: the skill's Pass 0 variables resolved in one call (#615)
+- `src/cli/commands/loop-worktree.ts` — `loop worktree add`: Pass 4 worktree creation, dependency linking and the missing-link assertion (#616)
 - `src/cli/generators/` — one file per concern (linting, testing, build, git, github-actions, security, misc)
 - `tooling/` — every shipped preset, mirrored 1:1 with `package.json` `exports`
 

package/dist/cli/commands/loop-worktree.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { realGitExec } from '../../base/git-identity.js';
+import { defaultWorktreeRoot } from './loop-guard.js';
+/**
+ * `repo-tooling loop worktree add` — the ai-issue-loop skill's Pass 4
+ * worktree creation, moved into code (#616): `git worktree add`, linking every
+ * `worktree.symlinkDirectories` entry, the `.git/info/exclude` line, and the
+ * assertion that nothing was left unlinked.
+ *
+ * The prose version iterated `for d in $DIRS`, which zsh does not word-split,
+ * so it silently linked nothing (#585). An array has no such failure mode.
+ *
+ * Exit `0` means the worktree is ready for an implementer. Exit `1` means do
+ * not spawn one — either the worktree was not created, or an entry that exists
+ * in the main checkout has no link in the worktree. `needsInstall` (exit `0`)
+ * means the repo declares no symlink list, so nothing was linked and a real
+ * install in the worktree is safe.
+ */
+/** `ai-<issue>-<kebab words>` — it becomes a branch name and a path segment. */
+export const SLUG = /^ai-\d+-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Relative and inside the checkout, or dropped: the list comes from a
+ * committed file, and `../x` would otherwise link outside both trees.
+ */
+function safeEntry(entry) {
+    if (typeof entry !== 'string' || entry.trim() === '')
+        return false;
+    const n = path.normalize(entry);
+    return !path.isAbsolute(n) && n !== '..' && !n.startsWith(`..${path.sep}`);
+}
+export async function symlinkDirectories(root) {
+    const settings = await fs.readJson(path.join(root, '.claude', 'settings.json')).catch(() => null);
+    const dirs = settings?.worktree?.symlinkDirectories;
+    return Array.isArray(dirs) ? dirs.filter(safeEntry) : [];
+}
+/**
+ * `node_modules/` with a trailing slash does not match a symlink, so a
+ * `git add -A` would commit every link. No slash matches at any depth. The
+ * exclude file is shared by every worktree and never committed.
+ */
+async function ensureExcluded(root) {
+    const file = path.join(root, '.git', 'info', 'exclude');
+    const current = await fs.readFile(file, 'utf8').catch(() => '');
+    if (current.split('\n').includes('node_modules'))
+        return false;
+    await fs.outputFile(file, `${current}${current && !current.endsWith('\n') ? '\n' : ''}node_modules\n`);
+    return true;
+}
+async function isSymlink(p) {
+    return fs
+        .lstat(p)
+        .then((s) => s.isSymbolicLink())
+        .catch(() => false);
+}
+export async function runLoopWorktreeAdd(slug, options = {}) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const worktreeRoot = options.worktreeRoot
+        ? path.resolve(options.worktreeRoot)
+        : defaultWorktreeRoot(root);
+    const worktree = path.join(worktreeRoot, slug);
+    // A checkout of a real repo takes longer than realGitExec's 5s default.
+    const git = options.git ?? ((args) => realGitExec(args, root, 120_000));
+    const result = {
+        root,
+        worktree,
+        branch: slug,
+        linked: [],
+        missing: [],
+        needsInstall: false,
+        exitCode: 1,
+        messages: [],
+    };
+    if (!SLUG.test(slug)) {
+        result.messages.push(`⚠ '${slug}' is not ai-<issue>-<kebab-slug>`);
+        return result;
+    }
+    const base = options.base ?? 'origin/main';
+    // Goes to git as an argument; a leading dash would be read as an option.
+    if (base.startsWith('-')) {
+        result.messages.push(`⚠ '${base}' is not a ref`);
+        return result;
+    }
+    await fs.ensureDir(worktreeRoot);
+    if ((await git(['worktree', 'add', worktree, '-b', slug, base])) === null) {
+        result.messages.push(`⚠ git worktree add failed — does branch ${slug} or ${worktree} already exist?`);
+        return result;
+    }
+    result.messages.push(`created ${worktree} on ${slug}`);
+    // Before linking, so the links are never momentarily untracked-and-addable.
+    if (await ensureExcluded(root))
+        result.messages.push('added node_modules to .git/info/exclude');
+    const dirs = await symlinkDirectories(root);
+    if (dirs.length === 0) {
+        result.needsInstall = true;
+        result.messages.push('no worktree.symlinkDirectories — run a real install in the worktree (`fix ai` restores the fast path)');
+    }
+    for (const d of dirs) {
+        const source = path.join(root, d);
+        // An entry pointing at nothing links nothing, and is not missing.
+        if (!(await fs.pathExists(source)))
+            continue;
+        const target = path.join(worktree, d);
+        await fs.ensureDir(path.dirname(target));
+        await fs.symlink(source, target).catch(() => { });
+        if (await isSymlink(target))
+            result.linked.push(d);
+        else
+            result.missing.push(d);
+    }
+    if (result.missing.length > 0) {
+        result.messages.push(`⚠ FATAL: no symlink for ${result.missing.join(', ')} — do not spawn an implementer`);
+        return result;
+    }
+    if (result.linked.length > 0)
+        result.messages.push(`linked ${result.linked.join(', ')}`);
+    result.exitCode = 0;
+    return result;
+}
+export async function loopWorktreeAddCommand(slug, options) {
+    const result = await runLoopWorktreeAdd(slug, options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        for (const line of result.messages) {
+            console.log(`  ${line.startsWith('⚠') ? chalk.yellow(line) : chalk.gray(line)}`);
+        }
+    }
+    process.exitCode = result.exitCode;
+}

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { fixCommand } from './commands/fix.js';
 import { loopCleanupCommand } from './commands/loop-cleanup.js';
 import { loopEnvCommand } from './commands/loop-env.js';
 import { loopGuardCommand } from './commands/loop-guard.js';
+import { loopWorktreeAddCommand } from './commands/loop-worktree.js';
 import { setupProject } from './commands/setup.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
 import { getToolVersion } from './utils/version.js';
@@ -389,6 +390,18 @@ loop
     .addHelpText('after', '\nPass `removed` from --json to `loop guard --removed`.\n' +
     'Exits 1 when a worktree removal failed.\n')
     .action(loopCleanupCommand);
+loop
+    .command('worktree')
+    .description('🌳 Loop worktree mechanics')
+    .command('add <slug>')
+    .description('🌱 Create ai-<issue>-<slug> off origin/main, link its deps, assert none are missing')
+    .option('--root <path>', 'Main checkout to branch the worktree from', process.cwd())
+    .option('--worktree-root <path>', 'Where ai-* worktrees live (default: <root>-worktrees)')
+    .option('--base <ref>', 'Ref to branch from', 'origin/main')
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', '\nExit 1 when the worktree was not created or a symlinkDirectories entry is left\n' +
+    'unlinked — do not spawn an implementer. needsInstall means no list was declared.\n')
+    .action(loopWorktreeAddCommand);
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'setup' || name === 'doctor' || name === 'fix') {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.41.0",
+	"version": "3.42.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [