@rtorcato/repo-tooling 3.45.0 → 4.0.0

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.