diff --git a/.agents/scripts/lib/git.ts b/.agents/scripts/lib/git.ts index ca09faf..8856aa5 100644 --- a/.agents/scripts/lib/git.ts +++ b/.agents/scripts/lib/git.ts @@ -20,3 +20,36 @@ export function cleanGitEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.Proces for (const name of localGitVars()) delete clean[name] return clean } + +export type GitResult = { ok: boolean; stdout: string; stderr: string } + +export function git(root: string, args: string[], options: { input?: string } = {}): GitResult { + const result = spawnSync('git', args, { + cwd: root, + env: cleanGitEnv(), + input: options.input, + encoding: 'utf8', + maxBuffer: 64 * 1024 * 1024, + }) + return { ok: result.status === 0, stdout: result.stdout ?? '', stderr: result.stderr ?? '' } +} + +/** The ref the current branch is measured against: origin's default branch, else a local one. */ +export function defaultBranchRef(root: string): string | undefined { + const originHead = git(root, ['symbolic-ref', '-q', 'refs/remotes/origin/HEAD']) + const candidates = [ + originHead.ok ? originHead.stdout.trim() : undefined, + 'refs/remotes/origin/main', + 'refs/heads/main', + ] + return candidates.find( + (ref) => ref && git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).ok, + ) +} + +/** Where the current branch left the default branch, or undefined if there is no default branch. */ +export function branchBase(root: string, ref = defaultBranchRef(root)): string | undefined { + if (!ref) return undefined + const base = git(root, ['merge-base', 'HEAD', ref]) + return base.ok ? base.stdout.trim() : undefined +} diff --git a/.agents/scripts/lib/state.ts b/.agents/scripts/lib/state.ts new file mode 100644 index 0000000..503d434 --- /dev/null +++ b/.agents/scripts/lib/state.ts @@ -0,0 +1,31 @@ +// Agent tooling state lives in the checkout's gitignored .tmp/agents/, not in .git/: +// Codex's sandbox cannot write .git/, and each worktree keeps its own state. + +import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { dirname, join } from 'node:path' + +export function stateDir(root: string): string { + return join(root, '.tmp/agents') +} + +export function readJson(path: string): T | undefined { + try { + return JSON.parse(readFileSync(path, 'utf8')) as T + } catch { + return undefined + } +} + +export function writeJson(path: string, value: unknown): void { + mkdirSync(dirname(path), { recursive: true }) + writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`) +} + +export type VerifiedRecord = { fingerprint: string; head: string; at: string } + +const verifiedPath = (root: string) => join(stateDir(root), 'verified.json') + +export const readVerified = (root: string) => readJson(verifiedPath(root)) +export const writeVerified = (root: string, record: VerifiedRecord) => + writeJson(verifiedPath(root), record) +export const clearVerified = (root: string) => rmSync(verifiedPath(root), { force: true }) diff --git a/.agents/scripts/lib/steps.test.ts b/.agents/scripts/lib/steps.test.ts new file mode 100644 index 0000000..254572b --- /dev/null +++ b/.agents/scripts/lib/steps.test.ts @@ -0,0 +1,253 @@ +import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { basename, join } from 'node:path' +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { writeJson } from './state.ts' +import { CI_EQUIVALENTS, preflight, VERIFY_STEPS } from './steps.ts' +import { REPO_ROOT } from './test-repo.ts' +import { CHECKED_WORKFLOWS } from './tree.ts' + +const WORKFLOWS_DIR = join(REPO_ROOT, '.github/workflows') +const readWorkflow = (name: string) => readFileSync(join(WORKFLOWS_DIR, name), 'utf8') + +// A line in a `run: |` script that runs a tool. The lines around them are shell guards (if, echo, +// exit, fi). +const TOOL_LINE = /^(npm|npx|node|gh|tsc|vitest|oxlint|oxfmt)\s/ + +/** + * The commands a workflow runs: each one-line `run:`, and every tool line of a `run: |` script, so a + * check added to a script cannot hide behind the command that was already there. + */ +function workflowCommands(text: string): string[] { + const commands: string[] = [] + const lines = text.split('\n') + lines.forEach((line, index) => { + const match = line.match(/^(\s+)(?:- )?run: (.+)$/) + if (!match) return + const [, indent = '', value = ''] = match + if (!value.startsWith('|')) { + commands.push(value.trim()) + return + } + for (const next of lines.slice(index + 1)) { + if (next.trim() && next.search(/\S/) <= indent.length) break + if (TOOL_LINE.test(next.trim())) commands.push(next.trim()) + } + }) + return commands +} + +/** The `on:` trigger, inline (`on: [push, pull_request]`) or as an indented block. */ +function triggers(text: string): string { + const match = text.match(/^["']?on["']?:(.*)\n((?:(?:[ \t].*)?\n)*)/m) + return match ? `${match[1]}\n${match[2]}` : '' +} + +const runsOnPullRequests = (text: string) => /\bpull_request(_target)?\b/.test(triggers(text)) + +describe('reading workflows', () => { + it.each([ + ['on:\n pull_request:\n', true], + ['on:\n pull_request_target:\n types: [opened]\n', true], + ['on: [push, pull_request]\n', true], + ['on: { pull_request: {} }\n', true], + ['"on": pull_request\n', true], + ['on:\n issues:\n types: [opened]\n', false], + ["on:\n push:\njobs:\n a:\n if: github.event_name == 'pull_request'\n", false], + ])('%j runs on pull requests: %s', (text, expected) => { + expect(runsOnPullRequests(text)).toBe(expected) + }) + + it('takes every tool line of a script, not only its last one', () => { + const text = [ + 'steps:', + ' - run: |', + ' if ! gh skill --help >/dev/null 2>&1; then', + ' echo "skipping"', + ' exit 0', + ' fi', + ' npm run new-check', + ' gh skill publish --dry-run', + ' - run: npm test', + '', + ].join('\n') + expect(workflowCommands(text)).toEqual([ + 'npm run new-check', + 'gh skill publish --dry-run', + 'npm test', + ]) + }) +}) + +describe('verify covers CI', () => { + it('reads every pull-request workflow that runs a command', () => { + const running = readdirSync(WORKFLOWS_DIR) + .filter((name) => /\.ya?ml$/.test(name)) + .filter((name) => { + const text = readWorkflow(name) + return runsOnPullRequests(text) && workflowCommands(text).length > 0 + }) + .map((name) => `.github/workflows/${name}`) + expect(running.toSorted()).toEqual(CHECKED_WORKFLOWS.toSorted()) + }) + + it('has an equivalent for every command in those workflows, and only those', () => { + const commands = new Set( + CHECKED_WORKFLOWS.flatMap((path) => workflowCommands(readWorkflow(basename(path)))), + ) + expect(commands.size).toBeGreaterThan(4) + expect([...commands].toSorted()).toEqual( + CI_EQUIVALENTS.map((entry) => entry.run).toSorted(), + ) + }) + + it('says why a command has no verify step', () => { + for (const entry of CI_EQUIVALENTS) { + if (entry.steps.length === 0) expect(entry.why, entry.run).toBeTruthy() + } + }) + + it('runs the same commands as the package.json scripts CI calls', () => { + const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')) as { + scripts: Record + } + // `npx tsc` and node_modules/.bin/tsc are the same command; `--silent` changes output only. + const normalize = (command: string) => + command.trim().replace(/^npx /, '').replace(' --silent', '') + const stepCommand = (name: string) => { + const step = VERIFY_STEPS.find((candidate) => candidate.name === name) + return normalize([basename(step?.command ?? ''), ...(step?.args ?? [])].join(' ')) + } + const scripted = CI_EQUIVALENTS.filter((entry) => entry.steps.length > 0) + for (const entry of scripted) { + const [, run, test] = entry.run.match(/^npm (?:run (\S+)|(test))$/) ?? [] + const script = run ?? test + expect(script, entry.run).toBeDefined() + // A step may run the whole script, as the build does. + if (entry.steps.map(stepCommand).join() === `npm run ${script}`) continue + const commands = (pkg.scripts[script ?? ''] ?? '').split('&&').map(normalize) + expect({ script, commands }).toEqual({ script, commands: entry.steps.map(stepCommand) }) + } + }) + + it('names only steps that exist', () => { + const names = VERIFY_STEPS.map((step) => step.name) + for (const entry of CI_EQUIVALENTS) { + for (const step of entry.steps) expect(names).toContain(step) + } + for (const step of VERIFY_STEPS) { + if (step.after) expect(names).toContain(step.after) + for (const other of step.waitFor ?? []) expect(names).toContain(other) + } + }) +}) + +describe('preflight', () => { + let root: string + + beforeEach(() => { + root = mkdtempSync(join(tmpdir(), 'agent-preflight-')) + writeJson(join(root, 'package.json'), { + engines: { node: '>=24' }, + dependencies: { zod: '1.0.0' }, + devDependencies: { vitest: '2.0.0' }, + }) + writeJson(join(root, 'package-lock.json'), { + packages: { + '': { dependencies: { zod: '1.0.0' }, devDependencies: { vitest: '2.0.0' } }, + 'node_modules/zod': { version: '1.0.0' }, + 'node_modules/vitest': { version: '2.0.0' }, + }, + }) + writeInstalled({ + 'node_modules/zod': { version: '1.0.0' }, + 'node_modules/vitest': { version: '2.0.0' }, + }) + }) + + // What npm records about the tree it installed. + const writeInstalled = (packages: Record) => + writeJson(join(root, 'node_modules/.package-lock.json'), { packages }) + + afterEach(() => rmSync(root, { recursive: true, force: true })) + + it('passes a current install on a supported Node', () => { + expect(preflight(root, '24.0.0')).toEqual([]) + }) + + it('rejects a Node older than package.json engines', () => { + const [problem] = preflight(root, '22.22.2') + expect(problem).toContain('Node 22.22.2 is older than the >=24') + }) + + it('names a dependency whose installed version differs from the lockfile', () => { + writeInstalled({ + 'node_modules/zod': { version: '0.9.0' }, + 'node_modules/vitest': { version: '2.0.0' }, + }) + expect(preflight(root, '24.0.0')).toEqual([ + 'node_modules does not match package-lock.json: zod 0.9.0 (lockfile: 1.0.0). Run `npm ci`.', + ]) + }) + + it('names a dependency that is not installed', () => { + writeInstalled({ 'node_modules/zod': { version: '1.0.0' } }) + expect(preflight(root, '24.0.0')[0]).toContain('vitest missing (lockfile: 2.0.0)') + }) + + it('names a transitive dependency that changed while every direct one kept its version', () => { + const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8')) as { + packages: Record + } + lock.packages['node_modules/undici'] = { version: '7.1.0' } + writeJson(join(root, 'package-lock.json'), lock) + writeInstalled({ + 'node_modules/zod': { version: '1.0.0' }, + 'node_modules/vitest': { version: '2.0.0' }, + 'node_modules/undici': { version: '7.0.0' }, + }) + expect(preflight(root, '24.0.0')).toEqual([ + 'node_modules does not match package-lock.json: undici 7.0.0 (lockfile: 7.1.0). Run `npm ci`.', + ]) + }) + + it('accepts optional packages for other platforms that were never installed', () => { + const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8')) as { + packages: Record + } + lock.packages['node_modules/@oxlint/darwin-arm64'] = { version: '1.0.0', optional: true } + lock.packages['node_modules/@oxfmt/win32-x64'] = { version: '1.0.0', devOptional: true } + writeJson(join(root, 'package-lock.json'), lock) + expect(preflight(root, '24.0.0')).toEqual([]) + }) + + it('says when node_modules has no record of what npm installed', () => { + rmSync(join(root, 'node_modules/.package-lock.json')) + expect(preflight(root, '24.0.0')).toEqual([ + 'node_modules has no record of what npm installed. Run `npm ci`.', + ]) + }) + + it('names a dependency package.json and the lockfile disagree on', () => { + writeJson(join(root, 'package.json'), { + engines: { node: '>=24' }, + dependencies: { zod: '1.1.0', added: '1.0.0' }, + devDependencies: { vitest: '2.0.0' }, + }) + expect(preflight(root, '24.0.0')).toEqual([ + 'package.json and package-lock.json disagree: zod (package.json: 1.1.0, lockfile: 1.0.0), added (package.json: 1.0.0, lockfile: none). Run `npm install`.', + ]) + }) + + it('says when the lockfile is missing', () => { + rmSync(join(root, 'package-lock.json')) + expect(preflight(root, '24.0.0')).toEqual([ + 'package-lock.json is missing or unreadable. Run `npm install`.', + ]) + }) + + it('says when node_modules is missing', () => { + rmSync(join(root, 'node_modules'), { recursive: true }) + expect(preflight(root, '24.0.0')).toEqual(['node_modules is missing. Run `npm ci`.']) + }) +}) diff --git a/.agents/scripts/lib/steps.ts b/.agents/scripts/lib/steps.ts new file mode 100644 index 0000000..97e0a00 --- /dev/null +++ b/.agents/scripts/lib/steps.ts @@ -0,0 +1,165 @@ +import { existsSync } from 'node:fs' +import { join } from 'node:path' +import { readJson } from './state.ts' +import type { Step } from './verify.ts' + +const bin = (tool: string) => `node_modules/.bin/${tool}` + +// GitHub Actions sets CI=true for every job. cli-core's `isCI()` reads it, and it makes vitest fail +// on `.only`, so checks run with it to match CI. +const CI_ENV = { CI: 'true' } + +/** Every check the pull-request workflows in CHECKED_WORKFLOWS run, with one shared build. */ +export const VERIFY_STEPS: Step[] = [ + { name: 'lint', command: bin('oxlint'), args: ['.'] }, + { name: 'format', command: bin('oxfmt'), args: ['--check'] }, + { name: 'types', command: bin('tsc'), args: ['--noEmit'] }, + { name: 'types:tools', command: bin('tsc'), args: ['--noEmit', '-p', '.agents/scripts'] }, + { name: 'tests', command: bin('vitest'), args: ['run'], env: CI_ENV }, + { name: 'build', command: 'npm', args: ['run', '--silent', 'build'], env: CI_ENV }, + { + name: 'skill-sync', + command: 'node', + args: ['scripts/check-skill-sync.js'], + after: 'build', + env: CI_ENV, + }, +] + +/** + * How each `run:` in the checked workflows maps to verify steps. For an npm script, the steps + * must run the script's commands, in order; steps.test.ts compares them with package.json and the + * workflows, so CI and verify cannot drift apart silently. A step list left empty says why. + */ +export const CI_EQUIVALENTS: { run: string; steps: string[]; why?: string }[] = [ + { run: 'npm ci', steps: [], why: 'the preflight checks node_modules matches the lockfile' }, + { run: 'npm run type-check', steps: ['types', 'types:tools'] }, + { run: 'npm run lint:check', steps: ['lint', 'format'] }, + { run: 'npm run build', steps: ['build'] }, + { run: 'npm test', steps: ['tests'] }, + { run: 'npm run check:skill-sync', steps: ['skill-sync'] }, + { + run: 'gh skill publish --dry-run', + steps: [], + why: "it needs gh's preview `skill` command and a GitHub token; CI skips it without them too", + }, +] + +/** + * Variables that change what the CLI does or prints. CI never sets them, so verify removes them, + * and the checks see what CI sees. A real token or server never reaches the tests either. + */ +export const LOCAL_ONLY_ENV = [ + 'COMMS_API_TOKEN', + 'COMMS_AS_URL', + 'COMMS_BASE_URL', + 'COMMS_INCLUDE_PRIVATE_CHANNELS', + 'TWIST_AUTH_TOKEN', + 'TWIST_BASE_URL', + 'TDC_ACCESSIBLE', + 'TDC_SPINNER', + 'FORCE_COLOR', +] + +type PackageJson = { + engines?: { node?: string } + dependencies?: Record + devDependencies?: Record +} +type Lockfile = { + packages?: Record< + string, + { + version?: string + optional?: boolean + devOptional?: boolean + dependencies?: Record + devDependencies?: Record + } + > +} + +const MAX_LISTED = 10 + +/** Problems that would make the checks fail for reasons unrelated to the change. */ +export function preflight(root: string, nodeVersion = process.versions.node): string[] { + const problems: string[] = [] + const pkg = readJson(join(root, 'package.json')) + const minimum = pkg?.engines?.node?.match(/^>=\s*(\d+)/)?.[1] + const major = Number(nodeVersion.split('.')[0]) + if (minimum && major < Number(minimum)) { + problems.push( + `Node ${nodeVersion} is older than the ${pkg?.engines?.node} this repository needs. ` + + 'Switch versions (see .nvmrc) and run again.', + ) + } + + if (!existsSync(join(root, 'node_modules'))) { + problems.push('node_modules is missing. Run `npm ci`.') + return problems + } + const lock = readJson(join(root, 'package-lock.json')) + if (!lock?.packages) { + problems.push('package-lock.json is missing or unreadable. Run `npm install`.') + return problems + } + // npm ci refuses to install when package.json and the lockfile disagree, so CI would fail + // before any check runs. + const manifest = lock.packages[''] ?? {} + const disagree: string[] = [] + for (const field of ['dependencies', 'devDependencies'] as const) { + const wanted = pkg?.[field] ?? {} + const locked = manifest[field] ?? {} + for (const name of new Set([...Object.keys(wanted), ...Object.keys(locked)])) { + if (wanted[name] !== locked[name]) { + disagree.push( + `${name} (package.json: ${wanted[name] ?? 'none'}, lockfile: ${locked[name] ?? 'none'})`, + ) + } + } + } + if (disagree.length > 0) { + problems.push( + `package.json and package-lock.json disagree: ${disagree.join(', ')}. Run \`npm install\`.`, + ) + return problems + } + + // npm records the tree it installed in node_modules/.package-lock.json. Comparing every + // package with the lockfile catches a transitive dependency that changed while every direct one + // kept its version. Optional packages for other platforms are never installed. + const installed = readJson(join(root, 'node_modules/.package-lock.json'))?.packages + if (!installed) { + problems.push('node_modules has no record of what npm installed. Run `npm ci`.') + return problems + } + const stale: string[] = [] + for (const [path, entry] of Object.entries(lock.packages)) { + if (!path.startsWith('node_modules/')) continue + const name = path.slice('node_modules/'.length) + const version = installed[path]?.version + if (version === undefined) { + if (!entry.optional && !entry.devOptional) { + stale.push(`${name} missing (lockfile: ${entry.version})`) + } + } else if (version !== entry.version) { + stale.push(`${name} ${version} (lockfile: ${entry.version})`) + } + } + if (stale.length > 0) { + const shown = stale.slice(0, MAX_LISTED).join(', ') + const more = stale.length > MAX_LISTED ? ` and ${stale.length - MAX_LISTED} more` : '' + problems.push( + `node_modules does not match package-lock.json: ${shown}${more}. Run \`npm ci\`.`, + ) + } + return problems +} + +/** What verification cannot see, printed after every pass. */ +export const BLIND_SPOTS = [ + 'calls against the real Comms API (run `node dist/index.js ` on a test workspace)', + 'output in a real terminal: colours, spinners, `--accessible` (run the command in a TTY)', + 'the other Node version CI tests on (24 and 26); verify uses only yours', + 'the `gh skill publish --dry-run` spec check of skills/comms-cli/SKILL.md (CI only)', +] diff --git a/.agents/scripts/lib/tree.test.ts b/.agents/scripts/lib/tree.test.ts new file mode 100644 index 0000000..ddde543 --- /dev/null +++ b/.agents/scripts/lib/tree.test.ts @@ -0,0 +1,121 @@ +import { rmSync, utimesSync } from 'node:fs' +import { join } from 'node:path' +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { createTempRepo, type TempRepo } from './test-repo.ts' +import { changedPaths, changedSince, classify, codeFingerprint, snapshot } from './tree.ts' + +let repo: TempRepo + +beforeEach(() => { + repo = createTempRepo() + repo.write('src/a.ts', 'export const a = 1\n') + repo.write('README.md', 'readme\n') + repo.write('.gitignore', 'ignored/\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'initial']) +}) + +afterEach(() => repo.cleanup()) + +const objectCount = () => repo.git(['count-objects', '-v']).stdout + +describe('snapshot', () => { + it('sees an edit that keeps the size and modification time', () => { + const before = codeFingerprint(snapshot(repo.dir)) + const file = join(repo.dir, 'src/a.ts') + repo.write('src/a.ts', 'export const a = 2\n') + utimesSync(file, new Date(2020, 0, 1), new Date(2020, 0, 1)) + const middle = codeFingerprint(snapshot(repo.dir)) + repo.write('src/a.ts', 'export const a = 3\n') + utimesSync(file, new Date(2020, 0, 1), new Date(2020, 0, 1)) + const after = codeFingerprint(snapshot(repo.dir)) + expect(new Set([before, middle, after]).size).toBe(3) + }) + + it('includes untracked files and leaves out ignored ones', () => { + const before = snapshot(repo.dir) + repo.write('src/new.ts', 'new\n') + repo.write('ignored/build.js', 'built\n') + expect(changedPaths(before, snapshot(repo.dir))).toEqual(['src/new.ts']) + }) + + it('sees a deleted tracked file', () => { + const before = snapshot(repo.dir) + rmSync(join(repo.dir, 'src/a.ts')) + expect(changedPaths(before, snapshot(repo.dir))).toEqual(['src/a.ts']) + }) + + it('sees an executable bit change', () => { + const before = codeFingerprint(snapshot(repo.dir)) + repo.run('chmod', ['+x', 'src/a.ts']) + expect(codeFingerprint(snapshot(repo.dir))).not.toBe(before) + }) + + it('writes nothing to the object store', () => { + repo.write('src/new.ts', 'new\n') + const before = objectCount() + snapshot(repo.dir) + expect(objectCount()).toBe(before) + }) +}) + +describe('codeFingerprint', () => { + it('ignores docs and files only CI reads, and nothing else', () => { + const before = codeFingerprint(snapshot(repo.dir)) + repo.write('README.md', 'changed\n') + repo.write('docs/guide.md', 'new\n') + repo.write('renovate.json', '{}\n') + repo.write('.github/CODEOWNERS', '* @example\n') + expect(codeFingerprint(snapshot(repo.dir))).toBe(before) + repo.write('src/prompt.md', 'markdown the server could load\n') + expect(codeFingerprint(snapshot(repo.dir))).not.toBe(before) + }) +}) + +describe('classify', () => { + it.each([ + ['README.md', 'docs'], + ['CHANGELOG.md', 'docs'], + ['docs/SPEC.md', 'docs'], + ['CONTRIBUTING.md', 'docs'], + ['CODEBASE.md', 'docs'], + ['docs/icon.md', 'docs'], + ['.github/PULL_REQUEST_TEMPLATE.md', 'docs'], + ['LICENSE', 'docs'], + ['.github/workflows/lint.yml', 'code'], + ['.github/workflows/test.yml', 'code'], + ['.github/workflows/check-skill-sync.yml', 'code'], + ['.github/workflows/release.yml', 'code'], + ['.github/CODEOWNERS', 'unchecked'], + ['renovate.json', 'unchecked'], + ['skills/comms-cli/SKILL.md', 'code'], + ['src/index.ts', 'code'], + ['src/notes.md', 'code'], + ['icons/comms.png', 'code'], + ['package-lock.json', 'code'], + ['.agents/scripts/verify.ts', 'code'], + ['lefthook.yml', 'code'], + ])('%s is %s', (path, kind) => { + expect(classify(path)).toBe(kind) + }) +}) + +describe('changedSince', () => { + it('lists committed, staged, unstaged and untracked changes', () => { + const base = repo.git(['rev-parse', 'HEAD']).stdout.trim() + repo.git(['switch', '--quiet', '-c', 'feature']) + repo.write('src/committed.ts', '1\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'c']) + repo.write('src/staged.ts', '1\n') + repo.git(['add', 'src/staged.ts']) + repo.write('src/a.ts', 'unstaged\n') + repo.write('src/untracked.ts', '1\n') + expect(changedSince(repo.dir, base)).toEqual([ + 'src/a.ts', + 'src/committed.ts', + 'src/staged.ts', + 'src/untracked.ts', + ]) + }) +}) diff --git a/.agents/scripts/lib/tree.ts b/.agents/scripts/lib/tree.ts new file mode 100644 index 0000000..6e8d165 --- /dev/null +++ b/.agents/scripts/lib/tree.ts @@ -0,0 +1,96 @@ +// Fingerprints of the working tree, by file content. Hashing content (not mtimes) catches edits +// made in the same second, and hashing in-process writes nothing to git's object store. + +import { createHash } from 'node:crypto' +import { lstatSync, readFileSync, readlinkSync } from 'node:fs' +import { join } from 'node:path' +import { git } from './git.ts' + +/** Path → content hash for every tracked and untracked, non-ignored file. */ +export type Snapshot = Record + +export function snapshot(root: string): Snapshot { + const listed = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']) + if (!listed.ok) throw new Error(`git ls-files failed: ${listed.stderr.trim()}`) + const files: Snapshot = {} + for (const path of new Set(listed.stdout.split('\0').filter(Boolean))) { + files[path] = hashPath(join(root, path)) + } + return files +} + +function hashPath(path: string): string { + let stat + try { + stat = lstatSync(path) + } catch { + return 'missing' + } + const hash = createHash('sha256') + if (stat.isSymbolicLink()) hash.update(`link:${readlinkSync(path)}`) + else if (stat.isDirectory()) hash.update('dir') // a nested repository, listed but not entered + else hash.update(`${stat.mode & 0o111 ? 'x' : '-'}:`).update(readFileSync(path)) + return hash.digest('hex') +} + +/** + * The pull-request workflows that run checks. .agents/scripts/lib/steps.test.ts compares verify + * with their commands, and reads every other workflow to check none of them runs a command on pull + * requests, so every workflow counts as code. + */ +export const CHECKED_WORKFLOWS = [ + '.github/workflows/check-skill-sync.yml', + '.github/workflows/lint.yml', + '.github/workflows/test.yml', +] + +/** The kind of file, as far as local checks are concerned. */ +export type FileKind = 'docs' | 'unchecked' | 'code' + +/** + * - docs: prose no check reads. Markdown under src/ is excluded, since it could be loaded at runtime. + * - unchecked: files only CI or GitHub reads (Renovate, other .github/ config). Local verification + * cannot vouch for them. + * - code: everything else, including config, lockfiles, the generated skill and tests. + */ +export function classify(path: string): FileKind { + if (path.startsWith('.github/workflows/')) return 'code' + // `npm run check:skill-sync` compares it with src/lib/skills/content.ts. + if (path.startsWith('skills/')) return 'code' + if (path.startsWith('.github/')) return path.endsWith('.md') ? 'docs' : 'unchecked' + if (path === 'renovate.json') return 'unchecked' + if (path.endsWith('.md') && !path.startsWith('src/')) return 'docs' + if (path === 'LICENSE') return 'docs' + return 'code' +} + +/** + * Hash of every file local checks read, so editing docs, or files only CI reads, after a pass + * keeps it valid. + */ +export function codeFingerprint(files: Snapshot): string { + const hash = createHash('sha256') + for (const path of Object.keys(files).sort()) { + if (classify(path) === 'code') hash.update(`${path}\0${files[path]}\n`) + } + return hash.digest('hex') +} + +/** Changed files local checks read. */ +export function changedCodePaths(before: Snapshot, after: Snapshot): string[] { + return changedPaths(before, after).filter((path) => classify(path) === 'code') +} + +export function changedPaths(before: Snapshot, after: Snapshot): string[] { + const paths = new Set([...Object.keys(before), ...Object.keys(after)]) + return [...paths].filter((path) => before[path] !== after[path]).sort() +} + +/** Files that differ from `base`: committed, staged, unstaged and untracked. */ +export function changedSince(root: string, base: string): string[] { + const diff = git(root, ['diff', '--name-only', '-z', '--no-renames', base]) + if (!diff.ok) throw new Error(`git diff failed: ${diff.stderr.trim()}`) + const untracked = git(root, ['ls-files', '-z', '--others', '--exclude-standard']) + const paths = [...diff.stdout.split('\0'), ...untracked.stdout.split('\0')].filter(Boolean) + return [...new Set(paths)].sort() +} diff --git a/.agents/scripts/lib/verify.test.ts b/.agents/scripts/lib/verify.test.ts new file mode 100644 index 0000000..8336dea --- /dev/null +++ b/.agents/scripts/lib/verify.test.ts @@ -0,0 +1,210 @@ +import { existsSync, readFileSync } from 'node:fs' +import { join } from 'node:path' +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { readVerified, stateDir, writeVerified } from './state.ts' +import { createTempRepo, type TempRepo } from './test-repo.ts' +import { codeFingerprint, snapshot } from './tree.ts' +import { runVerify, type Step } from './verify.ts' + +// runVerify with stand-in steps (shell one-liners) in a throwaway repo. The real steps are +// covered by steps.test.ts and by running `npm run verify` itself. +let repo: TempRepo +let base: string +let lines: string[] + +const pass = (name: string, extra: Partial = {}): Step => ({ + name, + command: 'sh', + args: ['-c', `echo ${name} ok`], + ...extra, +}) +const fail = (name: string): Step => ({ + name, + command: 'sh', + args: ['-c', 'i=1; while [ $i -le 40 ]; do echo "line $i"; i=$((i + 1)); done; exit 3'], +}) + +const verify = (steps: Step[], options: { base?: string | null } = {}) => + runVerify({ + root: repo.dir, + steps, + base: options.base === null ? undefined : (options.base ?? base), + out: (line) => lines.push(line), + }) + +beforeEach(() => { + repo = createTempRepo() + repo.write('.gitignore', '.tmp/\n') + repo.write('src/a.ts', 'export const a = 1\n') + repo.write('README.md', 'readme\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'initial']) + base = repo.git(['rev-parse', 'HEAD']).stdout.trim() + repo.git(['switch', '--quiet', '-c', 'feature']) + lines = [] +}) + +afterEach(() => repo.cleanup()) + +describe('a code change', () => { + beforeEach(() => repo.write('src/a.ts', 'export const a = 2\n')) + + it('records the fingerprint of the exact tree it verified', async () => { + const result = await verify([pass('lint'), pass('tests')]) + expect(result).toEqual({ ok: true, recorded: true }) + expect(readVerified(repo.dir)?.fingerprint).toBe(codeFingerprint(snapshot(repo.dir))) + expect(lines.some((line) => /^✓ lint \(\d+\.\ds\)$/.test(line))).toBe(true) + }) + + it('records nothing when a step fails, and forgets an earlier pass', async () => { + writeVerified(repo.dir, { fingerprint: 'earlier', head: 'x', at: 'then' }) + const result = await verify([pass('lint'), fail('tests')]) + expect(result).toEqual({ ok: false, recorded: false }) + expect(readVerified(repo.dir)).toBeUndefined() + }) + + it('prints one line per step, and on failure the log tail and its path', async () => { + await verify([pass('lint'), fail('tests')]) + const failure = lines.findIndex((line) => line.startsWith('✗ tests (exit 3')) + expect(failure).toBeGreaterThan(-1) + expect(lines.slice(failure + 1, failure + 31)).toEqual( + Array.from({ length: 30 }, (_, i) => ` line ${i + 11}`), + ) + const logPath = join(stateDir(repo.dir), 'logs/tests.log') + expect(lines[failure + 31]).toContain('full log: ') + expect(lines[failure + 31]).toContain('tests.log') + expect(readFileSync(logPath, 'utf8')).toContain('line 1\n') + }) + + it('runs a dependent step only after its dependency passed', async () => { + await verify([fail('build'), pass('schemas', { after: 'build' })]) + expect(lines).toContain('- schemas skipped: build failed') + expect(readVerified(repo.dir)).toBeUndefined() + }) + + it('starts a step that waits for another only once that one has finished', async () => { + // The writer's short wait gives a reader that started too early time to miss the file. + const writer = pass('build', { args: ['-c', 'sleep 0.2; echo built > .tmp/built.txt'] }) + const reader = pass('tests', { args: ['-c', 'cat .tmp/built.txt'], waitFor: ['build'] }) + expect(await verify([reader, writer])).toEqual({ ok: true, recorded: true }) + expect(lines.findIndex((line) => line.startsWith('✓ build'))).toBeLessThan( + lines.findIndex((line) => line.startsWith('✓ tests')), + ) + }) + + it('still runs a step when the one it waits for fails', async () => { + await verify([fail('build'), pass('tests', { waitFor: ['build'] })]) + expect(lines.some((line) => line.startsWith('✓ tests'))).toBe(true) + expect(readVerified(repo.dir)).toBeUndefined() + }) + + it('fails when a command cannot start', async () => { + const result = await verify([{ name: 'lint', command: 'no-such-command-xyz', args: [] }]) + expect(result.ok).toBe(false) + // ENOENT, or EACCES when PATH holds a folder the user cannot search (as on WSL). + expect(lines[0]).toMatch(/^✗ lint \(spawn no-such-command-xyz (ENOENT|EACCES)/) + }) + + it('records nothing when files change during the run', async () => { + const editor = pass('tests', { args: ['-c', 'echo edited > src/b.ts'] }) + const result = await verify([pass('lint'), editor]) + expect(result).toEqual({ ok: false, recorded: false }) + expect(lines.at(-1)).toContain('Files changed during the run: src/b.ts') + expect(readVerified(repo.dir)).toBeUndefined() + }) + + it('keeps an earlier pass when only files CI alone reads changed', async () => { + repo.write('src/a.ts', 'export const a = 2\n') + await verify([pass('lint')]) + const earlier = readVerified(repo.dir) + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'code']) + repo.write('renovate.json', '{}\n') + lines = [] + await runVerify({ + root: repo.dir, + steps: [pass('lint')], + base: repo.git(['rev-parse', 'HEAD']).stdout.trim(), + out: (line) => lines.push(line), + }) + expect(readVerified(repo.dir)).toEqual(earlier) + expect(readVerified(repo.dir)?.fingerprint).toBe(codeFingerprint(snapshot(repo.dir))) + }) + + it('keeps the pass when only a file CI alone reads changes during the run', async () => { + const editor = pass('tests', { + args: ['-c', 'echo x > renovate.json'], + }) + const result = await verify([pass('lint'), editor]) + expect(result).toEqual({ ok: true, recorded: true }) + expect(readVerified(repo.dir)?.fingerprint).toBe(codeFingerprint(snapshot(repo.dir))) + }) + + it('keeps its logs and state out of the fingerprint', async () => { + await verify([pass('lint')]) + expect(existsSync(join(stateDir(repo.dir), 'logs/lint.log'))).toBe(true) + expect(readVerified(repo.dir)?.fingerprint).toBe(codeFingerprint(snapshot(repo.dir))) + }) +}) + +describe('what counts as a change', () => { + it('sees an untracked file as a change', async () => { + repo.write('src/new.ts', 'new\n') + expect(await verify([pass('lint')])).toEqual({ ok: true, recorded: true }) + expect(lines[0]).toMatch(/^✓ lint/) + }) + + it('sees committed changes on the branch', async () => { + repo.write('src/a.ts', 'committed\n') + repo.git(['commit', '--quiet', '-am', 'change']) + expect(await verify([pass('lint')])).toEqual({ ok: true, recorded: true }) + expect(lines[0]).toMatch(/^✓ lint/) + }) + + it('keeps an earlier pass when only docs changed', async () => { + writeVerified(repo.dir, { fingerprint: 'earlier', head: 'x', at: 'then' }) + repo.write('README.md', 'changed\n') + await verify([pass('lint')]) + expect(readVerified(repo.dir)?.fingerprint).toBe('earlier') + }) + + it('runs the checks when any workflow changes, since a local test reads them all', async () => { + repo.write('.github/workflows/release.yml', 'on: push\n') + expect(await verify([pass('lint')])).toEqual({ ok: true, recorded: true }) + }) + + it('has nothing to check for a docs-only change', async () => { + repo.write('README.md', 'changed\n') + const result = await verify([fail('lint')]) + expect(result).toEqual({ ok: true, recorded: false }) + expect(lines).toEqual(['Only docs changed since main: nothing to check. Nothing recorded.']) + }) + + it('records nothing when only files CI alone reads changed', async () => { + repo.write('renovate.json', '{}\n') + repo.write('README.md', 'changed\n') + const result = await verify([pass('lint')]) + expect(result).toEqual({ ok: true, recorded: false }) + expect(lines[0]).toContain('renovate.json') + expect(readVerified(repo.dir)).toBeUndefined() + }) + + it('checks everything when a workflow changes along with code', async () => { + repo.write('.github/workflows/release.yml', 'on: push\n') + repo.write('src/a.ts', 'changed\n') + expect(await verify([pass('lint')])).toEqual({ ok: true, recorded: true }) + }) + + it('checks the whole tree, and says so, without a default branch', async () => { + repo.write('README.md', 'changed\n') + const result = await verify([pass('lint')], { base: null }) + expect(result).toEqual({ ok: true, recorded: true }) + expect(lines[0]).toBe('No main branch found, so checking the whole tree.') + }) + + it('checks the tree when nothing changed', async () => { + const result = await verify([pass('lint')]) + expect(result).toEqual({ ok: true, recorded: true }) + expect(lines[0]).toBe('No changes since main; checking the tree anyway.') + }) +}) diff --git a/.agents/scripts/lib/verify.ts b/.agents/scripts/lib/verify.ts new file mode 100644 index 0000000..c42f197 --- /dev/null +++ b/.agents/scripts/lib/verify.ts @@ -0,0 +1,153 @@ +import { spawn } from 'node:child_process' +import { createWriteStream, mkdirSync, readFileSync } from 'node:fs' +import { join, relative } from 'node:path' +import { cleanGitEnv, git } from './git.ts' +import { clearVerified, stateDir, writeVerified } from './state.ts' +import { changedCodePaths, changedSince, classify, codeFingerprint, snapshot } from './tree.ts' + +export type Step = { + name: string + command: string + args: string[] + /** Runs only after this step has passed. Steps without one start together. */ + after?: string + /** Starts only after these steps have finished, passed or not: they share files on disk. */ + waitFor?: string[] + env?: Record +} + +export type VerifyOptions = { + root: string + steps: Step[] + /** Where the branch left the default branch; undefined when there is no default branch. */ + base: string | undefined + baseName?: string + out?: (line: string) => void +} + +export type VerifyResult = { ok: boolean; recorded: boolean } + +const LOG_TAIL_LINES = 30 + +export async function runVerify(options: VerifyOptions): Promise { + const { root, steps, base, baseName = 'main', out = console.log } = options + + if (base === undefined) { + out(`No ${baseName} branch found, so checking the whole tree.`) + } else { + const changes = changedSince(root, base) + const kinds = new Set(changes.map(classify)) + if (changes.length > 0 && !kinds.has('code')) { + if (kinds.has('unchecked')) { + const unchecked = changes.filter((path) => classify(path) === 'unchecked') + out(`No local check reads what changed since ${baseName}: ${unchecked.join(', ')}.`) + out('CI is the only check for these. Nothing recorded.') + } else { + out(`Only docs changed since ${baseName}: nothing to check. Nothing recorded.`) + } + return { ok: true, recorded: false } + } + if (changes.length === 0) out(`No changes since ${baseName}; checking the tree anyway.`) + } + + // From here the checks run, so a run that does not end in a pass must not leave an earlier + // pass behind. (A docs-only run returns above: docs are outside the fingerprint, so an + // earlier pass is still valid.) + clearVerified(root) + const before = snapshot(root) + + const logDir = join(stateDir(root), 'logs') + mkdirSync(logDir, { recursive: true }) + const passed = await runSteps(root, steps, logDir, out) + if (!passed) return { ok: false, recorded: false } + + const after = snapshot(root) + if (codeFingerprint(after) !== codeFingerprint(before)) { + const changed = changedCodePaths(before, after) + out(`Files changed during the run: ${changed.join(', ')}. Nothing recorded; run it again.`) + return { ok: false, recorded: false } + } + + const head = git(root, ['rev-parse', 'HEAD']) + const fingerprint = codeFingerprint(after) + writeVerified(root, { + fingerprint, + head: head.ok ? head.stdout.trim() : 'none', + at: new Date().toISOString(), + }) + out(`Verified. Recorded fingerprint ${fingerprint.slice(0, 12)}.`) + return { ok: true, recorded: true } +} + +async function runSteps( + root: string, + steps: Step[], + logDir: string, + out: (line: string) => void, +): Promise { + const results = new Map>() + const start = (step: Step): Promise => { + const existing = results.get(step.name) + if (existing) return existing + const find = (name: string) => { + const found = steps.find((s) => s.name === name) + if (!found) throw new Error(`step ${step.name} runs after unknown ${name}`) + return found + } + const dependency = step.after ? find(step.after) : undefined + const waits = (step.waitFor ?? []).map(find) + const result = Promise.all([ + dependency ? start(dependency) : Promise.resolve(true), + ...waits.map(start), + ]).then(([ready]) => { + if (ready) return runStep(root, step, logDir, out) + out(`- ${step.name} skipped: ${step.after} failed`) + return false + }) + results.set(step.name, result) + return result + } + const outcomes = await Promise.all(steps.map(start)) + return outcomes.every(Boolean) +} + +function runStep( + root: string, + step: Step, + logDir: string, + out: (line: string) => void, +): Promise { + const logPath = join(logDir, `${step.name.replace(/[^\w.-]/g, '_')}.log`) + const log = createWriteStream(logPath) + const startedAt = Date.now() + return new Promise((resolve) => { + const child = spawn(step.command, step.args, { + cwd: root, + env: { ...cleanGitEnv(), ...step.env }, + stdio: ['ignore', 'pipe', 'pipe'], + }) + child.stdout.pipe(log, { end: false }) + child.stderr.pipe(log, { end: false }) + let finished = false + const finish = (code: number | null, error?: Error) => { + if (finished) return + finished = true + if (error) log.write(`\n${error.message}\n`) + log.end(() => { + const seconds = ((Date.now() - startedAt) / 1000).toFixed(1) + if (code === 0) { + out(`✓ ${step.name} (${seconds}s)`) + resolve(true) + return + } + const lines = readFileSync(logPath, 'utf8').trimEnd().split('\n') + out(`✗ ${step.name} (${error ? error.message : `exit ${code}`}, ${seconds}s)`) + for (const line of lines.slice(-LOG_TAIL_LINES)) out(` ${line}`) + out(` full log: ${relative(process.cwd(), logPath) || logPath}`) + resolve(false) + }) + } + child.on('error', (error) => finish(null, error)) + child.on('close', (code) => finish(code)) + }) +} diff --git a/.agents/scripts/package-contents.test.ts b/.agents/scripts/package-contents.test.ts index de041c0..4bd71b4 100644 --- a/.agents/scripts/package-contents.test.ts +++ b/.agents/scripts/package-contents.test.ts @@ -8,7 +8,8 @@ import { isolatedEnv, REPO_ROOT } from './lib/test-repo.ts' // lives in `.agents/`, and must never be published. const DEV_ONLY = ['.agents/', '.claude/', '.codex/', '.cursor/', '.tmp/'] -it('keeps agent tooling out of the published package', () => { +// npm pack takes several seconds, more when `npm run verify` runs other checks alongside. +it('keeps agent tooling out of the published package', { timeout: 30_000 }, () => { expect(existsSync(join(REPO_ROOT, '.agents/scripts'))).toBe(true) const result = spawnSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], { diff --git a/.agents/scripts/verify.ts b/.agents/scripts/verify.ts new file mode 100644 index 0000000..92fb519 --- /dev/null +++ b/.agents/scripts/verify.ts @@ -0,0 +1,36 @@ +// `npm run verify`: every check CI runs on a pull request, in about fifteen seconds. +// Records a fingerprint of the tree only when everything passed. + +import { CHECKOUT_ROOT, branchBase, defaultBranchRef } from './lib/git.ts' +import { clearVerified } from './lib/state.ts' +import { BLIND_SPOTS, LOCAL_ONLY_ENV, preflight, VERIFY_STEPS } from './lib/steps.ts' +import { runVerify } from './lib/verify.ts' + +const root = CHECKOUT_ROOT + +const problems = preflight(root) +if (problems.length > 0) { + clearVerified(root) + for (const problem of problems) console.log(`✗ ${problem}`) + process.exit(1) +} + +for (const name of LOCAL_ONLY_ENV) { + if (process.env[name] === undefined) continue + console.log(`Ignoring ${name}: CI does not set it.`) + delete process.env[name] +} + +const ref = defaultBranchRef(root) +const result = await runVerify({ + root, + steps: VERIFY_STEPS, + base: ref ? branchBase(root, ref) : undefined, + baseName: ref?.replace(/^refs\/(remotes|heads)\//, '') ?? 'main', +}) + +if (result.recorded) { + console.log('Not covered by these checks:') + for (const spot of BLIND_SPOTS) console.log(`- ${spot}`) +} +process.exit(result.ok ? 0 : 1) diff --git a/.gitignore b/.gitignore index 7d4ceb4..9cb4448 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ dist/ .claude/scheduled_tasks.lock .review/ +.tmp/ diff --git a/.tmp/agents/verified.json b/.tmp/agents/verified.json index 96cbeba..1ee013a 100644 --- a/.tmp/agents/verified.json +++ b/.tmp/agents/verified.json @@ -1,5 +1,5 @@ { - "fingerprint": "701b6e26796f4a12ddc0b3a491f67c6073014232a355a9bab146dff96ea4a743", - "head": "c45686139f6d7bbd2ac181da202681493f244ec0", - "at": "2026-11-05T11:02:34.685Z" + "fingerprint": "22b68f6e37748075465ac6d2d5838af71407510d54edde729baa3a8543b2f37c", + "head": "ac817c81c8414539e8d3befe94ab94f9018a979f", + "at": "2026-11-05T11:19:06.264Z" } diff --git a/AGENTS.md b/AGENTS.md index b55c771..1ca0080 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,13 @@ This file provides guidance to AI coding agents when working with code in this repository. +## Definition of done + +- **Done means proven:** a test that failed before the change and passes after, or the command's real output (`node dist/index.js `, on a test workspace). For a refactor: tests that pin the behaviour, passing before and after. Reading code or a passing compile is not proof. +- **Run `npm run verify` before calling a change done.** It runs every check CI runs, in about fifteen seconds, and records the pass. It prints what it cannot see, and says when only docs changed and there is nothing to check. +- **Never weaken a check to pass it.** Don't skip, delete or loosen tests, edit lint, type or test config to get green, or use `--no-verify`. If a check looks wrong, say so and stop. +- **Report honestly:** what ran, what it showed, and what you did not verify. + ## Commands ```bash @@ -12,6 +19,7 @@ npm run test:watch # Run tests in watch mode npm run type-check # Type check src + tests (tsconfig.json) and the agent tooling (.agents/scripts) npm run lint # Fix lint issues (oxlint) + format (oxfmt) npm run lint:check # Check lint + formatting (for CI) +npm run verify # Every check CI runs (lint, format, types, tests, build, skill sync) ``` The project uses two tsconfig files: `tsconfig.json` includes test files for type-checking, while `tsconfig.build.json` extends it and excludes colocated `*.test.ts` and `*.spec.ts` files (plus `src/__mocks__`) so test-only code is not compiled into `dist/`. diff --git a/CLAUDE.md b/CLAUDE.md index 43f64ad..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -See [AGENTS.md](./AGENTS.md) for all project guidelines and development instructions. +@AGENTS.md diff --git a/CODEBASE.md b/CODEBASE.md index 51d24d2..81f489f 100644 --- a/CODEBASE.md +++ b/CODEBASE.md @@ -30,12 +30,13 @@ come from `@doist/cli-core`. │ # update-comms-sdk ├─ .agents/ │ ├─ skills/ # Skills for agents working on this repo (add-command) -│ └─ scripts/ # Agent tooling (git hook branch guard) and its tests. -│ # Not published, unlike scripts/ +│ └─ scripts/ # Agent tooling (verify, git hook branch guard) and its +│ # tests. Not published, unlike scripts/ ├─ docs/agents.md # How the agent tooling fits together -├─ AGENTS.md # Prescriptive rules (build cmds, JSON flag, skill-sync, errors) +├─ AGENTS.md # Prescriptive rules (definition of done, build cmds, JSON flag, +│ # skill-sync, errors) ├─ CODEBASE.md # This file — descriptive map -├─ CLAUDE.md # One-liner forward to AGENTS.md +├─ CLAUDE.md # Imports AGENTS.md for Claude Code; nothing else ├─ README.md / CONTRIBUTING.md ├─ tsconfig.json # Includes src + tests (type-check, IDE) ├─ tsconfig.build.json # Excludes *.test.ts/.spec.ts, __mocks__, __fixtures__ @@ -255,6 +256,9 @@ see a per-command `--user`). - **Build:** `tsc -p tsconfig.build.json` → `dist/` (then `chmod +x`). Two-tsconfig setup: `tsconfig.json` includes tests (type-check/IDE); `tsconfig.build.json` excludes `*.test.ts`/`.spec.ts` and `__mocks__`. +- **Verify:** `npm run verify` — every check the pull-request workflows run, + with one shared build, in about fifteen seconds (`.agents/scripts/verify.ts`). + Records a pass in `.tmp/agents/`. - **Type-check:** `npm run type-check` (`src/`, then `.agents/scripts/tsconfig.json` for the agent tooling). **Lint/format:** `npm run lint` (oxlint --fix + oxfmt), `npm run lint:check` (CI). **No ESLint, no Prettier.** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 664f94a..381cf2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,7 @@ After cloning the repository and installing dependencies with `npm install`, sev - `npm test`: Runs all tests - `npm run test:watch`: Runs tests in watch mode - `npm run type-check`: Type checks without emitting +- `npm run verify`: Runs every check CI runs (lint, format, types, tests, build, skill sync) in about fifteen seconds ## Sending a Pull Request @@ -37,7 +38,7 @@ Before submitting a pull request, please take the following into consideration: - Create your branch from `main` (or from `next` if working on a pre-release feature) - Follow the [Commit Message Guidelines](#commit-message-guidelines) below - Add tests for code that should be tested -- Ensure the test suite passes +- Run `npm run verify` and make sure it passes - Do not override built-in validation and formatting checks ## Commit Message Guidelines diff --git a/docs/agents.md b/docs/agents.md index 55af946..4e27c30 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -5,17 +5,22 @@ This repository is set up so coding agents prove their work before they call it ## Layers 1. **Git hooks** run for everyone, people and agents alike, on every commit and push. +2. **`npm run verify`** runs every CI check locally and records a pass. +3. **`AGENTS.md`** tells agents what done means. Claude Code reads it through `CLAUDE.md`; Codex and other agents read it directly. ## Rules and what holds them -| Rule | Held by | Certainty | -| -------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------- | -| No commits on `main` | `pre-commit` and `commit-msg` → `.agents/scripts/branch-guard.sh` | Enforced locally; `--no-verify` skips it | -| No pushes to `main` | `pre-push` → `branch-guard.sh`; the "Protect default branch" ruleset | Enforced on GitHub | -| Committed files are linted and formatted | `pre-commit` (lefthook, staged files only); CI | Enforced in CI | -| Type check passes before a commit | `pre-commit`; CI | Enforced in CI | -| Tests pass before a push | `pre-push`; CI | Enforced in CI | -| Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | +| Rule | Held by | Certainty | +| --------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | +| No commits on `main` | `pre-commit` and `commit-msg` → `.agents/scripts/branch-guard.sh` | Enforced locally; `--no-verify` skips it | +| No pushes to `main` | `pre-push` → `branch-guard.sh`; the "Protect default branch" ruleset | Enforced on GitHub | +| Committed files are linted and formatted | `pre-commit` (lefthook, staged files only); CI | Enforced in CI | +| Type check passes before a commit | `pre-commit`; CI | Enforced in CI | +| Tests pass before a push | `pre-push`; CI | Enforced in CI | +| Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | +| `npm run verify` runs what CI runs | `.agents/scripts/lib/steps.test.ts` compares it with the pull-request workflows | Enforced in CI | +| Run `npm run verify` before calling work done | `AGENTS.md` | Asked | +| Never weaken a check to pass it | `AGENTS.md` | Asked | "Enforced in CI" means a pull request cannot merge without it. A local hook alone is a speed bump: `git commit --no-verify` skips it. @@ -31,10 +36,26 @@ This repository is set up so coding agents prove their work before they call it The release workflow commits and pushes to `main` from GitHub Actions, and `npm ci` runs `prepare` there, which installs the hooks. The release step sets `LEFTHOOK=0`, so semantic-release's commit and push run no hooks, as before: every check already ran on the pull request. The guard also skips itself when `GITHUB_ACTIONS=true`, in case another workflow commits with the hooks on. That is the one exemption. Branch protection on GitHub is the real enforcement; the hooks only catch mistakes early. +## `npm run verify` + +One command, every check the pull-request workflows run (`lint.yml`, `test.yml`, `check-skill-sync.yml`): lint, format, both type checks, all tests, the build and the skill sync check. It takes about fifteen seconds, so it always checks the whole tree. Picking only the affected tests would save a few seconds and add a way to miss something. + +- **Before the checks** it stops if Node is older than `package.json` requires, or if `node_modules` does not match the lockfile, transitive dependencies included (npm's own record of what it installed, `node_modules/.package-lock.json`, against `package-lock.json`). Both make checks fail, or pass, for reasons unrelated to your change. +- **Only docs changed** since the branch left `main`: it says there is nothing to check. The generated `skills/comms-cli/SKILL.md` counts as code, since `npm run check:skill-sync` reads it. +- **Only CI files changed** (Renovate, `.github/` config other than workflows): it says no local check reads them. Every workflow counts as code, since a local test compares verify with the three above and checks no other workflow runs commands on pull requests. +- **Order:** every check starts together, except the skill sync check, which imports from `dist/` and so waits for the build. +- **`CI=true`** is set for the build, the tests and the skill sync check, as GitHub Actions sets it. Variables that change what the CLI does (`COMMS_API_TOKEN`, `COMMS_AS_URL`, `COMMS_BASE_URL`, `COMMS_INCLUDE_PRIVATE_CHANNELS`, `TWIST_AUTH_TOKEN`, `TWIST_BASE_URL`, `TDC_ACCESSIBLE`, `TDC_SPINNER`, `FORCE_COLOR`) are removed, with a note, since CI never sets them. A real token or server never reaches the tests. +- **Output:** one line per step. A failing step prints the last 30 lines of its log and the log's path under `.tmp/agents/logs/`. +- **The record:** after a full pass it writes a content hash of every file local checks read (not docs, not CI-only files) to `.tmp/agents/verified.json`. A run that fails, or sees files change while it runs, deletes it. +- **Platforms:** macOS, Linux and WSL. Like the git hooks, it assumes a POSIX shell and runs npm's POSIX launchers in `node_modules/.bin`; on native Windows, run it in WSL. +- **What it cannot see:** the real Comms API, output in a real terminal, the other Node version CI tests on, and the `gh skill publish --dry-run` spec check. It prints these after every pass. + +If a pull-request workflow gains a step, `.agents/scripts/lib/steps.test.ts` fails until verify gains it too, or says why it can't. + ## Where the tooling lives - `.agents/scripts/` holds scripts and their tests. It is not under `scripts/` because `scripts/` ships in the npm package. -- The tooling runs straight from TypeScript with Node's type stripping, so it only uses erasable syntax (`.agents/scripts/tsconfig.json` enforces this). `npm run type-check` covers it, and `npm run lint:check` lints it. +- The tooling runs straight from TypeScript with Node's type stripping, so it only uses erasable syntax (`.agents/scripts/tsconfig.json` enforces this). `npm run type-check` covers it, and `npm run check` lints it. - Tests run in `npm test` and CI. They copy the tools into throwaway git repositories and never touch your checkout. A test helper clears the variables git exports to hooks, since `npm test` itself runs inside `pre-push`. ## Releases diff --git a/package.json b/package.json index ac7f70d..3d0c4a4 100644 --- a/package.json +++ b/package.json @@ -19,6 +19,7 @@ "sync:skill": "npm run build && node scripts/sync-skill.js", "test": "vitest run", "test:watch": "vitest", + "verify": "node .agents/scripts/verify.ts", "prepublishOnly": "npm run build && npm test", "prepare": "lefthook install --reset-hooks-path" },