@rtorcato/repo-tooling 3.38.3 → 3.40.0

package/AGENTS.md

@@ -27,6 +27,7 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `list --json` | ✅ | ✅ | Enumerate the library's surface area. Each entry has `{ name, description, exports, fixTarget }`. |
 | `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. |
 
 ## Recommended workflows
 
@@ -90,13 +91,20 @@ npx @rtorcato/repo-tooling fix bun --yes --json         # Bun runtime/test confi
 # Installs the ai-issue-loop skill to ~/.claude/skills. Override with --skills-dir,
 # which is required alongside --yes/--json when that directory doesn't exist.
 npx @rtorcato/repo-tooling fix claude-skills --yes --json
+
+# Opt-in only. Points this checkout's Claude sessions at a gh profile signed in as
+# rules.aiLoop.agentUser (~/.config/gh-<agentUser>, or --gh-config-dir) by merging
+# env.GH_CONFIG_DIR into the gitignored .claude/settings.local.json. Every session
+# in the checkout then runs as the agent, hands-on ones included. Writes nothing
+# and prints the `gh auth login` command if the profile isn't that account.
+npx @rtorcato/repo-tooling fix ai-loop-identity --yes --json
 ```
 
 ## Drift policy (important)
 
 `fix` defaults the confirm prompt to **No** for drift cases (existing file that doesn't extend our preset). The `--yes` flag is required to overwrite drift. Safe-merge fixers (`biome`, `engines`, `husky`, `package-json`) never overwrite — they add/merge — and use friendlier prompt wording. `fix --json` implies `--yes` (prompts would corrupt JSON output).
 
-Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `claude-skills`, the one fixer whose blast radius is outside the repo.
+Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `claude-skills` (writes outside the repo), `release-environment` (changes what a merge does), and `ai-loop-identity` (changes which account every session in the checkout acts as).
 
 The same goes for every `optional-missing` finding: a bulk `fix` records it `skipped`, because optional tools are often mutually exclusive (Biome / ESLint / Prettier / Oxlint, semantic-release / Changesets / Release Please) and installing them all is never the intent (#630). Name the one you want — `fix editorconfig --yes`.
 
@@ -110,6 +118,7 @@ A fixer may also **refuse** — the target file holds something the generator ca
 - `src/cli/commands/fix.ts` — `Fixer` interface, fixer registry, `fixCommand`
 - `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/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/base/agent-user.js

@@ -18,7 +18,7 @@ const CHECK = 'AI loop agent';
  * or trailing hyphen. The injection boundary — the login is interpolated into
  * the API path below.
  */
-const LOGIN = /^[a-zA-Z0-9](?:-?[a-zA-Z0-9]){0,38}$/;
+export const LOGIN = /^[a-zA-Z0-9](?:-?[a-zA-Z0-9]){0,38}$/;
 const skip = (reason) => ({
     check: CHECK,
     status: 'ok',

package/dist/base/ai-loop-identity.js

@@ -0,0 +1,80 @@
+/**
+ * `fix ai-loop-identity` (#638): point this checkout's Claude sessions at a gh
+ * profile signed in as `rules.aiLoop.agentUser`, so `loop guard` stops halting
+ * on `identity: mismatch`. `.repo-tooling.json` (committed) says *who* the agent
+ * is; the profile path is machine-specific, so it lands in the gitignored,
+ * per-checkout `.claude/settings.local.json`.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { configuredAgentUser } from '../cli/commands/loop-guard.js';
+import { LOGIN } from './agent-user.js';
+import { FixerAbort } from './fixers.js';
+import { realGhExec } from './github-settings.js';
+export const SETTINGS_LOCAL = '.claude/settings.local.json';
+/** The profile dir the fixer looks in when `--gh-config-dir` is not given. */
+export function defaultGhConfigDir(agentUser, home) {
+    return path.join(home, '.config', `gh-${agentUser}`);
+}
+/**
+ * Returns the files written. Writes nothing — and aborts with the `gh auth
+ * login` command as the hint — unless the profile really is the agent account.
+ */
+export async function setupAgentIdentity(targetDir, opts) {
+    const agentUser = await configuredAgentUser(targetDir);
+    if (!agentUser) {
+        console.error('   nothing to do — no rules.aiLoop.agentUser in .repo-tooling.json');
+        return [];
+    }
+    // The login comes from a committed file and becomes a path segment below.
+    if (!LOGIN.test(agentUser)) {
+        throw new FixerAbort('invalid-agent-user', `rules.aiLoop.agentUser "${agentUser}" is not a valid GitHub login`, 'Fix or remove rules.aiLoop.agentUser in .repo-tooling.json');
+    }
+    const dir = path.resolve(opts.ghConfigDir ?? defaultGhConfigDir(agentUser, opts.home));
+    const gh = opts.gh ?? ((args, env) => realGhExec(args, undefined, targetDir, env));
+    const login = (await fs.pathExists(dir))
+        ? await gh(['api', 'user', '--jq', '.login'], { GH_CONFIG_DIR: dir }).then((r) => r.ok ? r.stdout.trim() : '')
+        : '';
+    // GitHub logins are case-insensitive, so a case difference is one account.
+    if (login.toLowerCase() !== agentUser.toLowerCase()) {
+        throw new FixerAbort('agent-identity-unavailable', `${dir} is ${login ? `signed in as ${login}, not ${agentUser}` : `not signed in to gh as ${agentUser}`} — nothing written`, `Sign in once, in a browser logged in as ${agentUser}, then re-run:\n   GH_CONFIG_DIR=${dir} gh auth login --hostname github.com --web --scopes repo`);
+    }
+    const written = [];
+    const settingsPath = path.join(targetDir, SETTINGS_LOCAL);
+    let settings = {};
+    if (await fs.pathExists(settingsPath)) {
+        try {
+            settings = await fs.readJson(settingsPath);
+        }
+        catch {
+            throw new FixerAbort('settings-local-unparseable', `${SETTINGS_LOCAL} is not valid JSON — not overwriting it`, `Fix the file by hand, or add "env": {"GH_CONFIG_DIR": "${dir}"} to it yourself`);
+        }
+    }
+    const env = (settings.env ?? {});
+    if (env.GH_CONFIG_DIR !== dir) {
+        await fs.outputJson(settingsPath, { ...settings, env: { ...env, GH_CONFIG_DIR: dir } }, { spaces: 2 });
+        written.push(SETTINGS_LOCAL);
+    }
+    if (await ensureIgnored(targetDir))
+        written.push('.gitignore');
+    return written;
+}
+// ponytail: exact-line match on the usual spellings; a glob that happens to
+// cover the file gets a redundant (harmless) line. `git check-ignore` if that bites.
+const IGNORE_LINES = new Set([
+    SETTINGS_LOCAL,
+    `/${SETTINGS_LOCAL}`,
+    '.claude',
+    '.claude/',
+    '/.claude',
+    '/.claude/',
+]);
+async function ensureIgnored(targetDir) {
+    const file = path.join(targetDir, '.gitignore');
+    const existing = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf-8') : '';
+    if (existing.split('\n').some((l) => IGNORE_LINES.has(l.trim())))
+        return false;
+    const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    await fs.writeFile(file, `${existing}${separator}${SETTINGS_LOCAL}\n`);
+    return true;
+}

package/dist/base/fixers.js

@@ -27,6 +27,7 @@ import { classifyCopiedAssets } from '../cli/utils/copied-assets.js';
 import { copyPreset } from '../cli/utils/copy-preset.js';
 import { detectAuditLanguage } from '../cli/utils/detect-language.js';
 import { resolveLanguageModule } from '../languages/registry.js';
+import { SETTINGS_LOCAL, setupAgentIdentity } from './ai-loop-identity.js';
 import { applyGithubSettings, applyReleaseEnvironment, RELEASE_ENV_CHECK, RELEASE_GATE_CHECK, } from './github-settings.js';
 import { applyLoopLabels } from './labels.js';
 import { closeCompletedMilestones } from './milestones.js';
@@ -408,6 +409,22 @@ export const BASE_FIXERS = [
             return { filesWritten };
         },
     },
+    {
+        target: 'ai-loop-identity',
+        description: "Point this checkout's Claude sessions at a gh profile signed in as rules.aiLoop.agentUser (~/.config/gh-<agentUser>, or --gh-config-dir) via .claude/settings.local.json. Every session in the checkout then runs as the agent",
+        appliesTo: ['AI loop identity'],
+        outputs: [SETTINGS_LOCAL, '.gitignore'],
+        // safe-add keeps it out of the `--diff` shadow-run, which would spawn gh;
+        // explicitOnly because it changes who every session here acts as.
+        riskLevel: 'safe-add',
+        explicitOnly: true,
+        canFixDrift: true,
+        async run({ targetDir, ghConfigDir }) {
+            return {
+                filesWritten: await setupAgentIdentity(targetDir, { ghConfigDir, home: os.homedir() }),
+            };
+        },
+    },
     {
         target: 'cursor-rules',
         description: 'Install the repo-tooling rules for Cursor (.cursor/rules/repo-tooling.mdc)',

package/dist/base/github-settings.js

@@ -11,7 +11,7 @@ const GH_TIMEOUT_MS = 10_000;
  * `: GhExec` so the optional cwd stays callable; still assignable where GhExec
  * is expected.
  */
-export const realGhExec = (args, stdin, cwd) => new Promise((resolve) => {
+export const realGhExec = (args, stdin, cwd, env) => new Promise((resolve) => {
     let settled = false;
     const done = (r) => {
         if (settled)
@@ -24,6 +24,7 @@ export const realGhExec = (args, stdin, cwd) => new Promise((resolve) => {
     // shell:false + an args array keeps this injection-safe.
     const child = spawn('gh', args, {
         cwd,
+        env: env && { ...process.env, ...env },
         stdio: [stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
     });
     let stdout = '';

package/dist/cli/commands/fix.js

@@ -275,9 +275,13 @@ function promptMessageFor(fixer, result) {
     }
     return { message: `Apply ${fixer.description}?`, default: true };
 }
-async function confirmApply(fixer, result, assumeYes) {
-    if (assumeYes)
+async function confirmApply(fixer, result, assumeYes, dryRun) {
+    // A dry run writes nothing, so there is nothing to confirm (#637).
+    if (assumeYes || dryRun)
         return true;
+    // No TTY means no one can answer: inquirer would throw ExitPromptError. Treat it as "no".
+    if (!process.stdin.isTTY)
+        return false;
     const { message, default: defaultValue } = promptMessageFor(fixer, result);
     const { confirm } = await inquirer.prompt([
         { type: 'confirm', name: 'confirm', message, default: defaultValue },
@@ -345,14 +349,16 @@ export async function fixCommand(target, options = {}) {
             return;
         }
         if (!assumeYes) {
-            const { confirm } = await inquirer.prompt([
-                {
-                    type: 'confirm',
-                    name: 'confirm',
-                    message: `Re-scaffold ${files.length} file(s) from ${LOCKFILE_NAME}? Generators preserve existing customizations where possible, but README.md will be rewritten.`,
-                    default: false,
-                },
-            ]);
+            const { confirm } = !process.stdin.isTTY
+                ? { confirm: false }
+                : await inquirer.prompt([
+                    {
+                        type: 'confirm',
+                        name: 'confirm',
+                        message: `Re-scaffold ${files.length} file(s) from ${LOCKFILE_NAME}? Generators preserve existing customizations where possible, but README.md will be rewritten.`,
+                        default: false,
+                    },
+                ]);
             if (!confirm) {
                 console.log(chalk.gray('   skipped\n'));
                 return;
@@ -440,7 +446,7 @@ export async function fixCommand(target, options = {}) {
             const previews = await previewFixer(fixer, effectiveResult, targetDir, pkg, lock);
             printPreviews(previews);
         }
-        const ok = await confirmApply(fixer, effectiveResult, assumeYes);
+        const ok = await confirmApply(fixer, effectiveResult, assumeYes, dryRun);
         if (!ok) {
             actions.push(recordFor(fixer.target, result.check, effectiveResult.status, 'skipped', [], conflict));
             if (json)
@@ -454,6 +460,7 @@ export async function fixCommand(target, options = {}) {
         const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent, {
             skillsDir: options.skillsDir,
             forceSkills: options.forceSkills,
+            ghConfigDir: options.ghConfigDir,
             assumeYes,
         }).catch((err) => {
             if (!(err instanceof FixerAbort))
@@ -518,7 +525,7 @@ export async function fixCommand(target, options = {}) {
             const previews = await previewFixer(fixer, result, targetDir, pkg, lock);
             printPreviews(previews);
         }
-        const ok = await confirmApply(fixer, result, assumeYes);
+        const ok = await confirmApply(fixer, result, assumeYes, dryRun);
         if (!ok) {
             actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', [], conflict));
             if (!silent)
@@ -536,6 +543,7 @@ export async function fixCommand(target, options = {}) {
             outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, {
                 skillsDir: options.skillsDir,
                 forceSkills: options.forceSkills,
+                ghConfigDir: options.ghConfigDir,
                 assumeYes,
             });
         }

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

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import { LOGIN } from '../../base/agent-user.js';
+import { realGitExec } from '../../base/git-identity.js';
+import { realGhExec } from '../../base/github-settings.js';
+import { configuredAgentUser, defaultWorktreeRoot } from './loop-guard.js';
+async function ghOut(gh, args) {
+    const r = await gh(args);
+    return r.ok ? r.stdout.trim() : '';
+}
+export async function resolveLoopEnv(options = {}) {
+    const dir = path.resolve(options.dir ?? process.cwd());
+    const git = options.git ?? ((args) => realGitExec(args, dir));
+    const gh = options.gh ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const env = options.env ?? process.env;
+    const warnings = [];
+    // Absolute, so the common dir is `<main checkout>/.git` from anywhere.
+    const common = (await git(['rev-parse', '--path-format=absolute', '--git-common-dir']))?.trim();
+    const root = common ? path.resolve(common, '..') : '';
+    if (!root)
+        warnings.push('not a git repository');
+    const worktreeRoot = root ? defaultWorktreeRoot(root) : '';
+    const ownerRepo = await ghOut(gh, [
+        'repo',
+        'view',
+        '--json',
+        'nameWithOwner',
+        '--jq',
+        '.nameWithOwner',
+    ]);
+    if (!ownerRepo)
+        warnings.push('could not resolve the GitHub repo from the working directory');
+    let agentUser = env.AI_LOOP_AGENT?.trim() || (root ? await configuredAgentUser(root) : '') || '';
+    // LOGIN is the injection boundary — the login goes into an API path.
+    if (agentUser &&
+        (!ownerRepo ||
+            !LOGIN.test(agentUser) ||
+            !(await gh(['api', `repos/${ownerRepo}/assignees/${agentUser}`, '--silent'])).ok)) {
+        warnings.push(`agentUser '${agentUser}' is not an assignable collaborator — assigning nothing`);
+        agentUser = '';
+    }
+    const humanUser = ownerRepo
+        ? await ghOut(gh, [
+            'api',
+            `repos/${ownerRepo}`,
+            '--jq',
+            'if .owner.type == "User" then .owner.login else "" end',
+        ])
+        : '';
+    const me = await ghOut(gh, ['api', 'user', '--jq', '.login']);
+    return { root, worktreeRoot, ownerRepo, agentUser, humanUser, me, warnings };
+}
+const VARS = [
+    ['ROOT', 'root'],
+    ['WT_ROOT', 'worktreeRoot'],
+    ['OWNER_REPO', 'ownerRepo'],
+    ['AGENT_USER', 'agentUser'],
+    ['HUMAN_USER', 'humanUser'],
+    ['ME', 'me'],
+];
+/** `KEY='value'` lines, single-quoted so `eval "$(… loop env)"` is safe. */
+export function toShell(env) {
+    return VARS.map(([name, key]) => `${name}='${env[key].replaceAll("'", `'\\''`)}'`).join('\n');
+}
+export async function loopEnvCommand(options) {
+    const env = await resolveLoopEnv(options);
+    if (options.json) {
+        console.log(JSON.stringify(env, null, 2));
+    }
+    else {
+        for (const w of env.warnings)
+            console.error(`⚠ ${w}`);
+        console.log(toShell(env));
+    }
+    // Nothing downstream works without both — the skill bails on either.
+    process.exitCode = env.root && env.ownerRepo ? 0 : 1;
+}

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

@@ -71,7 +71,7 @@ export async function checkAgentIdentity(configured, gh) {
     }
     return {
         verdict: 'mismatch',
-        message: `⚠ agentUser is ${configured} but gh authenticates as ${effective || '(gh could not say — unauthenticated or missing)'} — the tick would commit, push and review as the wrong account`,
+        message: `⚠ agentUser is ${configured} but gh authenticates as ${effective || '(gh could not say — unauthenticated or missing)'} — the tick would commit, push and review as the wrong account. Run \`npx @rtorcato/repo-tooling fix ai-loop-identity\` in this checkout, then relaunch the Claude session`,
     };
 }
 /**

package/dist/cli/generators/git.js

@@ -74,9 +74,9 @@ async function ensureHookRuns(hookPath, runs, fresh, line = fresh) {
     }
     else {
         const existing = await fs.readFile(hookPath, 'utf-8');
-        if (hookHasUncommented(existing, runs))
-            return;
-        await fs.writeFile(hookPath, `${existing.replace(/\n*$/, '\n')}${line}`);
+        if (!hookHasUncommented(existing, runs)) {
+            await fs.writeFile(hookPath, `${existing.replace(/\n*$/, '\n')}${line}`);
+        }
     }
     await fs.chmod(hookPath, 0o755);
 }

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { Command } from 'commander';
 import fs from 'fs-extra';
 import { doctorCommand } from './commands/doctor.js';
 import { fixCommand } from './commands/fix.js';
+import { loopEnvCommand } from './commands/loop-env.js';
 import { loopGuardCommand } from './commands/loop-guard.js';
 import { setupProject } from './commands/setup.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
@@ -341,6 +342,7 @@ program
     // Deliberately not folded into --yes: unattended runs pass --yes, and this is
     // the one overwrite that destroys work living outside the repo (#480).
     .option('--force-skills', 'Let `fix claude-skills` overwrite a locally modified skill instead of refusing')
+    .option('--gh-config-dir <path>', 'gh profile signed in as rules.aiLoop.agentUser, for `fix ai-loop-identity` (default: ~/.config/gh-<agentUser>)')
     .action((target, options) => fixCommand(target, {
     directory: options.directory,
     yes: options.yes,
@@ -351,6 +353,7 @@ program
     diff: options.diff,
     skillsDir: options.skillsDir,
     forceSkills: options.forceSkills,
+    ghConfigDir: options.ghConfigDir,
 }));
 // Mechanics the ai-issue-loop skill used to describe in prose-with-shell (#519).
 // Deliberately outside the isSelfRepo hook below: the loop runs against this
@@ -368,6 +371,14 @@ loop
     '  1  repair was attempted and failed; the root is still bare — halt the tick\n' +
     '  2  root is not a repairable main checkout (bare clone, linked worktree, or not a repo) — halt the tick\n')
     .action(loopGuardCommand);
+loop
+    .command('env')
+    .description('🧭 Resolve ROOT, WT_ROOT, OWNER_REPO, AGENT_USER, HUMAN_USER and ME once')
+    .option('-d, --dir <path>', 'Directory to resolve from — main checkout or any worktree', process.cwd())
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', "\nWithout --json, prints KEY='value' lines for eval. Empty means none.\n" +
+    'Exits 1 when the checkout or its GitHub repo cannot be resolved.\n')
+    .action(loopEnvCommand);
 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.38.3",
+	"version": "3.40.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [