@rtorcato/repo-tooling 3.44.0 → 4.0.0

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

@@ -1,132 +0,0 @@
-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/generators/claude-skills.js

@@ -1,240 +0,0 @@
-/**
- * User-global agent skills (#404). Every other generator writes inside the repo;
- * this one writes to `~/.claude/skills/<name>/SKILL.md`, which is shared by every
- * project on the machine. That difference drives all three rules below — the
- * version stamp, the symlink handling, and the fixer's opt-in `explicitOnly`.
- */
-import { createHash } from 'node:crypto';
-import os from 'node:os';
-import path from 'node:path';
-import fs from 'fs-extra';
-import { realGitExec } from '../../base/git-identity.js';
-import { getPackageRoot } from '../utils/copy-preset.js';
-import { shellQuote } from '../utils/shell.js';
-import { isNewerVersion, resolveShippedVersion } from '../utils/version.js';
-/**
- * Skills this package owns the content of and keeps up to date. The loop first —
- * it is the pipeline; the next three are its drivers (burst, on-ramp, status).
- * `dogfood` stands apart: it tests the consuming repo's own tooling rather than
- * driving the loop, and it is the only one that writes nothing outside a temp dir.
- */
-export const SHIPPED_SKILLS = [
-    'ai-issue-loop',
-    'ai-workflow',
-    'ai-issue',
-    'ai-loop-status',
-    'dogfood',
-];
-/** The primary skill — the default everywhere a single name is accepted. */
-export const SHIPPED_SKILL = 'ai-issue-loop';
-/**
- * Stamped into the installed copy's frontmatter so a second repo pinned to an
- * older release can tell it would be a downgrade and skip. Without it two repos
- * on different versions overwrite each other's skill on every `fix`, and neither
- * is wrong to do so.
- */
-export const VERSION_KEY = 'repo-tooling-version';
-/**
- * The pristine sha256 of the content we wrote, stamped beside the version — the
- * skills half of #448. The version alone cannot tell a stale copy from a
- * deliberate local fork: a fork that is merely older than the package looks
- * exactly like a copy waiting for an update, and gets overwritten (#480).
- * With the hash, "installed content still matches what some release of this
- * package shipped" is a fact rather than an inference.
- *
- * It lives in the file instead of `.repo-tooling.json` because skills are
- * user-global — no one repo owns the record.
- */
-export const HASH_KEY = 'repo-tooling-hash';
-const STAMP_KEYS = [VERSION_KEY, HASH_KEY];
-const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
-/**
- * Where to install. `explicit` is `--skills-dir`; otherwise the user-level
- * `~/.claude/skills` when it already exists. A machine with neither resolves to
- * null rather than creating `~/.claude` uninvited.
- *
- * There is deliberately no separate "symlinked" case: a stow-managed
- * `SKILL.md` symlink lives *inside* that same directory, and writing through it
- * is what `installClaudeSkill` already does. See its note.
- */
-export async function resolveSkillsDir(explicit, home = os.homedir()) {
-    if (explicit)
-        return { dir: path.resolve(explicit), source: 'explicit' };
-    const userDir = path.join(home, '.claude', 'skills');
-    if (await fs.pathExists(userDir))
-        return { dir: userDir, source: 'user' };
-    return { dir: null, source: 'none' };
-}
-function readStamp(content, key) {
-    return content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null;
-}
-/** The version recorded in an installed copy, or null if it predates the stamp. */
-export function readSkillVersion(content) {
-    return readStamp(content, VERSION_KEY);
-}
-/** The pristine hash recorded in an installed copy, or null if it predates it. */
-export function readSkillHash(content) {
-    return readStamp(content, HASH_KEY);
-}
-/**
- * Replace (or add) the stamp lines in the frontmatter. Appending them last is
- * safe even after a multi-line `description: |` block: an unindented key ends
- * the block scalar, which is exactly what these lines are.
- *
- * With no stamps this is the exact inverse of stamping, so a file we wrote
- * strips back to the bytes we were given — which is what makes the hash
- * comparable.
- */
-function setStamps(content, stamps) {
-    const match = content.match(FRONTMATTER);
-    if (!match)
-        return stamps.length === 0 ? content : `---\n${stamps.join('\n')}\n---\n\n${content}`;
-    const kept = (match[1] ?? '')
-        .split('\n')
-        .filter((line) => !STAMP_KEYS.some((key) => line.startsWith(`${key}:`)));
-    return `---\n${[...kept, ...stamps].join('\n')}\n---\n${content.slice(match[0].length)}`;
-}
-/** An installed copy with this package's own bookkeeping lines removed. */
-export function stripSkillStamps(content) {
-    return setStamps(content, []);
-}
-/**
- * The version stamp on its own — the shape releases before #480 wrote, and what
- * `classifySkillContent` sees as `unknown`. Not the write path; `stampSkill` is.
- */
-export function stampSkillVersion(content, version) {
-    return setStamps(content, [`${VERSION_KEY}: ${version}`]);
-}
-/** sha256 of the content this package shipped, ignoring the stamps it adds. */
-export function hashSkillContent(content) {
-    return createHash('sha256').update(stripSkillStamps(content)).digest('hex');
-}
-/** The version + hash stamps, as written to disk. */
-export function stampSkill(content, version) {
-    return setStamps(content, [
-        `${VERSION_KEY}: ${version}`,
-        `${HASH_KEY}: ${hashSkillContent(content)}`,
-    ]);
-}
-export function classifySkillContent(installed, shipped) {
-    if (stripSkillStamps(installed) === stripSkillStamps(shipped))
-        return 'pristine';
-    const recorded = readSkillHash(installed);
-    if (!recorded)
-        return 'unknown';
-    return recorded === hashSkillContent(installed) ? 'pristine' : 'modified';
-}
-/** The skill source and the package version that will be stamped into it. */
-export async function readShippedSkill(name = SHIPPED_SKILL, git = realGitExec) {
-    const root = getPackageRoot();
-    const file = path.join(root, 'skills', name, 'SKILL.md');
-    const content = await fs.readFile(file, 'utf8');
-    const pkg = await fs.readJson(path.join(root, 'package.json'));
-    return { content, version: await resolveShippedVersion(root, String(pkg.version), git), file };
-}
-/**
- * The command a human runs to see what their fork changed, before deciding
- * whether to take the shipped copy. One builder, because `doctor` and `fix`
- * both print it and two independently-built strings drift (#484). Always
- * `realFile`: through a stow symlink the nominal path is the link, and the
- * bytes worth reading are in the dotfiles checkout it points at.
- *
- * Both paths are user-influenced — `--skills-dir` is an argument (#490) and
- * `realFile` is wherever a symlink happens to point — and this line exists to
- * be pasted into a shell, so it is quoted rather than merely interpolated
- * (#493). Quoting beats refusing to emit a command: single quotes make an odd
- * path *more* visible, not less, and keep the hint usable in the odd case
- * instead of only the ordinary one.
- */
-export function skillDiffCommand(paths) {
-    return `diff ${shellQuote(paths.realFile)} ${shellQuote(paths.shippedFile)}`;
-}
-/** Whether `file` is itself a symlink, as opposed to merely resolving through one. */
-async function isSymlink(file) {
-    return await fs
-        .lstat(file)
-        .then((stat) => stat.isSymbolicLink())
-        .catch(() => false);
-}
-/**
- * Install (or refresh) one shipped skill under `skillsDir`.
- *
- * **Writes through a symlink on purpose.** stow symlinks dotfiles at *file*
- * level, so `~/.claude/skills/ai-issue-loop/SKILL.md` is routinely a link into a
- * dotfiles checkout while its parent directories are real. `fs.writeFile`
- * follows the link and updates the dotfiles copy in place, which is the whole
- * point — the skill stays version-controlled with the rest of the Claude config.
- * Never swap this for an atomic-rename helper (`write-file-atomic` and friends):
- * rename *replaces* the symlink with a real file, orphaning the dotfiles copy
- * with no error at all, which is the split-brain this feature exists to end.
- */
-export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL, { force = false } = {}) {
-    const shipped = await readShippedSkill(name);
-    const file = path.join(skillsDir, name, 'SKILL.md');
-    const existing = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : null;
-    const installedVersion = existing ? readSkillVersion(existing) : null;
-    const viaSymlink = await isSymlink(file);
-    const base = {
-        name,
-        contentState: existing === null ? null : classifySkillContent(existing, shipped.content),
-        file,
-        viaSymlink,
-        shippedFile: shipped.file,
-        realFile: viaSymlink ? await fs.realpath(file) : file,
-        installedVersion,
-        shippedVersion: shipped.version,
-    };
-    // `force` overrides this too, not just the fork check below. It already
-    // overrides the *stronger* protection — overwriting content someone
-    // deliberately edited — so refusing on a version comparison while allowing
-    // that was backwards, and left no escape hatch at all when the comparison
-    // was wrong (#522).
-    if (!force && installedVersion && isNewerVersion(installedVersion, shipped.version)) {
-        return { ...base, status: 'declined-downgrade' };
-    }
-    // Only `pristine` content is provably ours to replace. Anything else is a
-    // fork (or unprovable, which for a destructive write is the same thing) and
-    // stays a human decision — the same rule `fix copied-assets` follows (#448).
-    if (!force && base.contentState !== null && base.contentState !== 'pristine') {
-        return { ...base, status: 'declined-fork' };
-    }
-    const next = stampSkill(shipped.content, shipped.version);
-    if (existing === next)
-        return { ...base, status: 'up-to-date' };
-    await fs.ensureDir(path.dirname(file));
-    await fs.writeFile(file, next);
-    return { ...base, status: existing === null ? 'installed' : 'updated' };
-}
-/** Read-only counterpart of `installClaudeSkill`, for doctor. */
-export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
-    const shipped = await readShippedSkill(name);
-    const { dir } = await resolveSkillsDir(explicit);
-    const absent = {
-        realFile: null,
-        shippedFile: shipped.file,
-        installed: false,
-        installedVersion: null,
-        shippedVersion: shipped.version,
-        contentState: null,
-        needsInstall: true,
-    };
-    if (!dir)
-        return { file: null, ...absent };
-    const file = path.join(dir, name, 'SKILL.md');
-    if (!(await fs.pathExists(file)))
-        return { file, ...absent };
-    const content = await fs.readFile(file, 'utf8');
-    const installedVersion = readSkillVersion(content);
-    const contentState = classifySkillContent(content, shipped.content);
-    const behind = installedVersion === null || isNewerVersion(shipped.version, installedVersion);
-    return {
-        file,
-        realFile: (await isSymlink(file)) ? await fs.realpath(file) : file,
-        shippedFile: shipped.file,
-        installed: true,
-        installedVersion,
-        shippedVersion: shipped.version,
-        contentState,
-        needsInstall: behind && contentState === 'pristine',
-    };
-}

package/skills/ai-issue/SKILL.md

@@ -1,74 +0,0 @@
----
-name: ai-issue
-description: |
-  File a GitHub issue labelled `ai-ready` for the ai-issue-loop pipeline to pick
-  up and implement unattended. Use when the user says "file this for the loop",
-  "make this an AI issue", "queue this for an agent", or invokes `/ai-issue`.
-  For an ordinary issue a human will work on, use plain `gh issue create` with
-  no label instead. GitHub only (`gh`) — not GitLab.
----
-
-# ai-issue
-
-File an issue an **agent will execute unattended**, labelled `ai-ready` so
-`ai-issue-loop` picks it up. Arguments: $ARGUMENTS
-
-This is only for work you intend a background agent to do without you. For an
-ordinary issue, use `gh issue create` with no `ai-*` label.
-
-## Preflight
-
-1. `git remote get-url origin` — GitHub only. On GitLab, stop: the loop is
-   `gh`-based and nothing would ever pick the issue up.
-2. `gh label list --search ai-ready` — if the label is missing, this repo hasn't
-   been bootstrapped for the loop. Stop and point at the `ai-issue-loop` skill's
-   label block; creating a bare `ai-ready` label would produce an issue that
-   silently never runs.
-
-## Write it for an agent, not for yourself
-
-The agent that picks this up **cannot ask a follow-up question**, and is
-instructed to treat the body as untrusted data. Both change how it must read:
-
-- **Describe, never instruct.** "The README claims X but Y is true" — not "go
-  update the README". Directive phrasing is exactly what the agent is told to
-  ignore, so an instruction-shaped issue reads as empty.
-- **Name the files** you already know are involved. The two reviewing agents are
-  diff-scoped and won't explore the repo to judge whether the right thing was
-  touched.
-- **State a done-condition a reviewer can check.** Those same agents review the
-  PR against this body; a vague issue produces a vague review on a PR you then
-  merge without having really vetted.
-- **One PR's worth.** Split anything spanning several concerns — the loop runs
-  several issues in parallel, so splitting is free.
-
-## Refuse the ones that aren't ready
-
-Say so, and file it unlabelled instead, when the task:
-
-- needs a judgement call you'd normally make mid-PR,
-- needs eyes on rendered output, a real device, or a running service,
-- depends on context that lives in this conversation rather than the repo, or
-- you couldn't write self-contained without "we can sort that out in review".
-
-An `ai-ready` that stalls costs more than an issue you did yourself: it burns a
-concurrency slot, two review passes, and up to two fix rounds before it lands as
-`ai-blocked`.
-
-## Create
-
-Draft title and body from `$ARGUMENTS` plus the conversation. The body opens
-with a line saying an agent wrote it — everything you post appears under the
-owner's own account:
-
-```bash
-gh issue create --label ai-ready --title "TITLE" --body "$(cat <<'EOF'
-🤖 *Filed by Claude (AI agent) on the owner's behalf.*
-
-BODY
-EOF
-)"
-```
-
-Print the URL. Note that nothing happens until a tick runs — `/ai-issue-loop`
-manually, or a recurring schedule if one is active.