@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/team-metadata.js

@@ -0,0 +1,513 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadCockpitConfig, readBoundedInput } from './config/load.js';
+import { ENVIRONMENT_CODES, errorCause, hasErrorCode, isMissing, parseJsonText, RefusalError, tryParseJson } from './environment/contract.js';
+import { installedPackageMetadata } from './package-metadata.js';
+import { cockpitCommand } from './fix-catalogue.js';
+import { GUARD_LOCAL_PATHS, parseGuardLocalIdentity } from './guards/local-identity.js';
+import { guardLauncherEvidence } from './guards/protected-locations.js';
+const PACKAGE = installedPackageMetadata.name;
+const VERSION = installedPackageMetadata.version;
+const INSTALLED_PACKAGE_ROOT = dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+const SCRIPTS = Object.freeze({
+    'cockpit:setup': 'cockpit setup --config cockpit.toml',
+    'cockpit:sync': 'cockpit sync --config cockpit.toml',
+    'cockpit:check': 'cockpit check --config cockpit.toml',
+});
+const START = '# cockpit:ignore:start';
+const END = '# cockpit:ignore:end';
+const OTHER_DEPENDENCY_SECTIONS = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+const PACKAGE_JSON_SHAPE = 'an npm package.json object';
+function refuse(code, message, target) {
+    return { kind: 'refusal', code, message, target };
+}
+// The loader already names the failing key and reason; replacing it with a generic refusal left
+// sync reporting "cockpit.toml must be valid" for every malformed configuration.
+function configRefusal(loaded, configPath) {
+    const reason = loaded.diagnostics.find(diagnostic => diagnostic.severity === 'error');
+    if (!reason)
+        return refuse('TEAM_METADATA_UNAVAILABLE', 'cockpit.toml could not be loaded and the loader gave no reason', configPath);
+    return { kind: 'refusal', code: reason.code, message: reason.message, target: reason.target ?? configPath, ...(reason.fix ? { fix: reason.fix } : {}) };
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+async function captureRoot(root) {
+    if (await realpath(root) !== root)
+        throw new RefusalError('cockpit root is not canonical');
+    const chain = [];
+    for (let path = root;; path = dirname(path)) {
+        const status = await lstat(path);
+        if (!status.isDirectory() || status.isSymbolicLink())
+            throw new RefusalError('cockpit root ancestry is redirected');
+        chain.push({ path, dev: status.dev, ino: status.ino });
+        if (dirname(path) === path)
+            break;
+        if (chain.length >= 64)
+            throw new RefusalError('cockpit root ancestry exceeds the verification bound');
+    }
+    return { root, chain };
+}
+async function authenticateRoot(authority) {
+    if (await realpath(authority.root) !== authority.root)
+        throw new RefusalError('cockpit root was redirected');
+    for (const expected of authority.chain) {
+        const status = await lstat(expected.path);
+        if (!status.isDirectory() || status.isSymbolicLink() || status.dev !== expected.dev || status.ino !== expected.ino) {
+            throw new RefusalError('cockpit root ancestry changed');
+        }
+    }
+}
+async function readOptional(authority, path) {
+    if (dirname(path) !== authority.root)
+        throw new RefusalError('team metadata escaped the cockpit root');
+    await authenticateRoot(authority);
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new RefusalError('not a regular file');
+        const read = await readBoundedInput(path);
+        if (read.kind !== 'complete')
+            throw new RefusalError('file exceeds the input limit');
+        await authenticateRoot(authority);
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(read.bytes);
+        }
+        catch {
+            throw new RefusalError(`${basename(path)} is not valid UTF-8`);
+        } // The decoder throws only for invalid UTF-8.
+        return { bytes: text, mode: stat.mode,
+            identity: `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${createHash('sha256').update(read.bytes).digest('hex')}` };
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT')) {
+            await authenticateRoot(authority);
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function replaceAuthenticated(authority, path, before, bytes) {
+    const directory = dirname(path);
+    if (directory !== authority.root)
+        throw new RefusalError('team metadata escaped the cockpit root');
+    const temporary = join(directory, `.${path.slice(path.lastIndexOf('/') + 1)}.cockpit-${randomBytes(8).toString('hex')}`);
+    let created = false;
+    try {
+        await authenticateRoot(authority);
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, before?.mode ?? 0o644);
+        created = true;
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await authenticateRoot(authority);
+        const current = await readOptional(authority, path);
+        if (current?.identity !== before?.identity)
+            throw new RefusalError('file changed before replacement');
+        await authenticateRoot(authority);
+        await rename(temporary, path);
+        created = false;
+        await authenticateRoot(authority);
+        const parent = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            const status = await parent.stat();
+            const expected = authority.chain[0];
+            if (!status.isDirectory() || status.dev !== expected.dev || status.ino !== expected.ino)
+                throw new RefusalError('cockpit root changed before sync');
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+    finally {
+        if (created) {
+            await authenticateRoot(authority);
+            await unlink(temporary);
+        }
+    }
+}
+/**
+ * The package manifest without the entries sync owns in it: the cockpit dependency, under any spec,
+ * and each cockpit script while it is the exact command sync writes. Sections those removals leave
+ * empty are dropped, so a manifest cockpit created and one it edited project the same way.
+ */
+export function productPackageManifest(manifest) {
+    const product = { ...manifest };
+    if (object(manifest.devDependencies)) {
+        const { [PACKAGE]: _pin, ...rest } = manifest.devDependencies;
+        product.devDependencies = rest;
+    }
+    if (object(manifest.scripts))
+        product.scripts = Object.fromEntries(Object.entries(manifest.scripts)
+            .filter(([name, command]) => SCRIPTS[name] !== command));
+    for (const section of ['devDependencies', 'scripts']) {
+        const value = product[section];
+        if (object(value) && Object.keys(value).length === 0)
+            delete product[section];
+    }
+    return product;
+}
+function packageDependencySlots(manifest) {
+    const devDependencies = manifest.devDependencies === undefined ? {} : manifest.devDependencies;
+    if (!object(devDependencies))
+        return undefined;
+    const misplaced = [];
+    for (const section of OTHER_DEPENDENCY_SECTIONS) {
+        const dependencies = manifest[section];
+        if (dependencies !== undefined && !object(dependencies))
+            return undefined;
+        if (object(dependencies) && dependencies[PACKAGE] !== undefined)
+            misplaced.push(section);
+    }
+    return { devDependencies, misplaced };
+}
+function misplacedDependencyMessage(sections) {
+    return `package.json declares ${PACKAGE} in ${sections.join(', ')} outside cockpit-owned devDependencies; cockpit requires one exact development dependency so the team has one version authority. Run npm uninstall ${PACKAGE} && npm install --save-dev --save-exact ${PACKAGE}@${VERSION}, then run npx --no cockpit sync --config <your cockpit.toml> again`;
+}
+function packageCandidate(bytes, verifiedLocalPin) {
+    let parsed = {};
+    if (bytes !== undefined && bytes.trim() !== '') {
+        const decoded = parseJsonText(bytes, 'package.json', PACKAGE_JSON_SHAPE);
+        if ('refusal' in decoded)
+            return { bytes: '', valid: false, cause: decoded.refusal };
+        parsed = decoded.value;
+    }
+    if (!object(parsed))
+        return { bytes: '', valid: false };
+    const slots = packageDependencySlots(parsed);
+    const scripts = parsed.scripts === undefined ? {} : parsed.scripts;
+    if (!slots || !object(scripts))
+        return { bytes: '', valid: false };
+    if (slots.misplaced.length > 0)
+        return { bytes: '', valid: false, misplaced: slots.misplaced };
+    const conflictingDependency = slots.devDependencies[PACKAGE] !== undefined && slots.devDependencies[PACKAGE] !== VERSION
+        && slots.devDependencies[PACKAGE] !== verifiedLocalPin;
+    const conflictingScript = Object.entries(SCRIPTS).some(([name, command]) => scripts[name] !== undefined && scripts[name] !== command);
+    if (conflictingDependency || conflictingScript)
+        return { bytes: '', valid: false };
+    return { valid: true, bytes: `${JSON.stringify({ ...parsed,
+            scripts: { ...scripts, ...SCRIPTS }, devDependencies: { ...slots.devDependencies, [PACKAGE]: verifiedLocalPin ?? VERSION },
+        }, null, 2)}\n` };
+}
+// `npm install -D <archive>` pins a `file:` spec, and before a release that archive is the only
+// source of the package. The pin is accepted as the team's version when the lockfile resolves it
+// to this exact running package; rewriting it to the bare version named a release that may not
+// exist and changed a dependency the user chose without asking. The installed copy is compared by
+// manifest bytes, not by location: the bootstrap route runs init from a temporary install of the
+// same archive, and requiring the running copy to be the root's own install refused that resume.
+async function verifiedLocalPin(authority, packageBytes) {
+    // An unparseable package.json is refused by the caller's own parse of the same bytes.
+    const manifest = packageBytes === undefined ? undefined : tryParseJson(packageBytes);
+    const dependencies = object(manifest) && object(manifest.devDependencies) ? manifest.devDependencies : undefined;
+    const spec = dependencies?.[PACKAGE];
+    if (typeof spec !== 'string' || !spec.startsWith('file:') || spec.length > 4096)
+        return undefined;
+    const installedPath = join(authority.root, 'node_modules', ...PACKAGE.split('/'));
+    let installed;
+    try {
+        installed = await lstat(installedPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    if (!installed.isDirectory() || installed.isSymbolicLink())
+        return undefined;
+    if (await realpath(installedPath) !== await realpath(INSTALLED_PACKAGE_ROOT)) {
+        const installedManifest = await readBoundedInput(join(installedPath, 'package.json'));
+        const runningManifest = await readBoundedInput(join(INSTALLED_PACKAGE_ROOT, 'package.json'));
+        if (installedManifest.kind !== 'complete' || runningManifest.kind !== 'complete'
+            || !Buffer.from(installedManifest.bytes).equals(Buffer.from(runningManifest.bytes)))
+            return undefined;
+    }
+    const lockFile = await readOptional(authority, join(authority.root, 'package-lock.json'));
+    if (!lockFile)
+        return undefined;
+    // An unparseable lockfile verifies no pin; the caller then refuses the file: pin as unresolved.
+    const lock = tryParseJson(lockFile.bytes);
+    const packages = object(lock) && object(lock.packages) ? lock.packages : undefined;
+    const rootEntry = packages?.[''];
+    const rootDependencies = object(rootEntry) && object(rootEntry.devDependencies) ? rootEntry.devDependencies : undefined;
+    const installedEntry = packages?.[`node_modules/${PACKAGE}`];
+    if (!rootDependencies || rootDependencies[PACKAGE] !== spec || !object(installedEntry)
+        || installedEntry.version !== VERSION || installedEntry.resolved !== spec)
+        return undefined;
+    return spec;
+}
+// A checkout is its own Git repository; left visible inside the cockpit root, a `git add` embeds
+// it as a gitlink, or fails on one with no commit yet. Cloned rows are repositories by declaration.
+// `acquire = "none"` rows are local data the cockpit itself may track, except a directory that
+// already holds Git metadata: `sibling add --create` records a new repository as "none" until it
+// has a remote, so for those rows the disk decides.
+async function ignoreBlock(root, config) {
+    const siblingsRoot = config.cockpit.siblings_root;
+    if (/[\0\r\n]/.test(siblingsRoot))
+        return undefined;
+    // Claude Code's machine-local settings, where `cockpit use` grants a served checkout.
+    const patterns = ['/node_modules/', '/.cockpit/local/', '/.claude/settings.local.json', '/env/.secrets/*', '!/env/.secrets/.gitignore'];
+    const inside = (path, kind = 'directory') => {
+        const local = relative(root, path);
+        if (local === '' || local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local))
+            return undefined;
+        return `/${local.split(sep).map((part) => part.replace(/[\\*?\[\] !#]/g, '\\$&')).join('/')}${kind === 'directory' ? '/' : ''}`;
+    };
+    // Generated host paths (browser artifact roots among them) hold run output such as screenshots;
+    // left unignored, `git add` commits them. One may be a file bound into a service, which a
+    // trailing-slash pattern would not match.
+    for (const generated of config.environment.generated_host_paths) {
+        const pattern = inside(resolve(root, generated), 'any');
+        if (pattern && !patterns.includes(pattern))
+            patterns.push(pattern);
+    }
+    const siblings = resolve(root, siblingsRoot);
+    const siblingsPattern = inside(siblings);
+    if (siblingsPattern)
+        patterns.push(siblingsPattern);
+    else
+        for (const sibling of config.sibling) {
+            const path = resolve(siblings, sibling.dir);
+            const pattern = inside(path);
+            if (pattern && !patterns.includes(pattern) && (sibling.acquire !== 'none' || await holdsGitMetadata(path)))
+                patterns.push(pattern);
+        }
+    const body = patterns.join('\n');
+    return `${blockHeader(body)}\n${body}\n${END}`;
+}
+async function holdsGitMetadata(directory) {
+    try {
+        await lstat(join(directory, '.git'));
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+// The start marker carries a digest of the region it opens, which is what separates a region a
+// changed configuration made stale (rewritten) from one a person edited (refused). Without it,
+// adding a sibling under a siblings_root of "." made every later sync refuse the cockpit's own block.
+function blockHeader(body) {
+    return `${START} sha256=${createHash('sha256').update(body).digest('hex').slice(0, 16)}`;
+}
+function writtenByCockpit(region) {
+    const header = region.slice(0, Math.max(0, region.indexOf('\n')));
+    const body = region.slice(header.length + 1, region.length - END.length - 1);
+    return header !== '' && region.endsWith(`\n${END}`) && header === blockHeader(body);
+}
+function ignoreCandidate(original, block) {
+    const start = original.indexOf(START);
+    const end = original.indexOf(END);
+    if ((start < 0) !== (end < 0) || start >= 0 && (original.indexOf(START, start + 1) >= 0 || original.indexOf(END, end + 1) >= 0 || end < start))
+        return undefined;
+    if (start < 0)
+        return `${original}${original.length > 0 && !original.endsWith('\n') ? '\n' : ''}${block}\n`;
+    const region = original.slice(start, end + END.length);
+    if (region === block)
+        return original;
+    return writtenByCockpit(region) ? `${original.slice(0, start)}${block}${original.slice(end + END.length)}` : undefined;
+}
+const issuedMetadata = new WeakMap();
+export async function prepareTeamMetadata(configPath) {
+    const root = dirname(resolve(configPath));
+    try {
+        const authority = await captureRoot(root);
+        const loaded = await loadCockpitConfig(configPath);
+        await authenticateRoot(authority);
+        if (loaded.kind !== 'complete')
+            return configRefusal(loaded, configPath);
+        const block = await ignoreBlock(root, loaded.result.config);
+        if (block === undefined) {
+            return refuse('TEAM_METADATA_UNAVAILABLE', `cockpit.siblings_root must be a single-line path without NUL because .gitignore cannot represent it literally; fix cockpit.toml and run ${cockpitCommand('sync', { config: configPath })}`, 'cockpit.siblings_root');
+        }
+        const packagePath = join(root, 'package.json');
+        const packageBefore = await readOptional(authority, packagePath);
+        const candidate = packageCandidate(packageBefore?.bytes, await verifiedLocalPin(authority, packageBefore?.bytes));
+        if (candidate.misplaced)
+            return refuse('TEAM_METADATA_UNAVAILABLE', misplacedDependencyMessage(candidate.misplaced), packagePath);
+        if (candidate.cause)
+            return refuse('TEAM_METADATA_UNAVAILABLE', `${candidate.cause}; repair it, then run ${cockpitCommand('sync', { config: configPath })}`, packagePath);
+        if (!candidate.valid)
+            return refuse('TEAM_METADATA_UNAVAILABLE', `package.json conflicts with cockpit's exact ${PACKAGE} pin or cockpit:* scripts; resolve the conflict and run ${cockpitCommand('sync', { config: configPath })}`, packagePath);
+        const ignorePath = join(root, '.gitignore');
+        const ignoreBefore = await readOptional(authority, ignorePath);
+        const nextIgnore = ignoreCandidate(ignoreBefore?.bytes ?? '', block);
+        if (nextIgnore === undefined)
+            return refuse('TEAM_METADATA_UNAVAILABLE', `the cockpit-owned .gitignore block was edited or malformed; restore it exactly, or remove the whole ${START} through ${END} region and run ${cockpitCommand('sync', { config: configPath })}`, ignorePath);
+        const files = [
+            { path: packagePath, before: packageBefore, bytes: candidate.bytes },
+            { path: ignorePath, before: ignoreBefore, bytes: nextIgnore },
+        ];
+        const changes = files.filter(file => file.before?.bytes !== file.bytes)
+            .map(file => ({ operation: 'write', path: relative(root, file.path) }));
+        const prepared = { changes };
+        issuedMetadata.set(prepared, { authority, configPath: loaded.result.source.path,
+            sourceSha256: loaded.result.source.sha256, files });
+        return { kind: 'complete', authority: prepared };
+    }
+    catch (error) {
+        return refuse('TEAM_METADATA_UNAVAILABLE', `team metadata could not be updated (${errorCause(error)})`, root);
+    }
+}
+export async function applyTeamMetadata(prepared) {
+    const record = issuedMetadata.get(prepared);
+    if (!record)
+        return refuse('TEAM_METADATA_UNAVAILABLE', 'this team metadata update was already applied or was never prepared; run npx --no cockpit sync --config <your cockpit.toml> again', 'team-metadata');
+    issuedMetadata.delete(prepared);
+    const { authority, files } = record;
+    try {
+        const loaded = await loadCockpitConfig(record.configPath);
+        if (loaded.kind !== 'complete' || loaded.result.source.sha256 !== record.sourceSha256)
+            throw new RefusalError('configuration changed before metadata replacement');
+        await authenticateRoot(authority);
+        for (const file of files) {
+            if ((await readOptional(authority, file.path))?.identity !== file.before?.identity)
+                throw new RefusalError('team metadata changed before replacement');
+        }
+        for (const file of files)
+            if (file.before?.bytes !== file.bytes)
+                await replaceAuthenticated(authority, file.path, file.before, file.bytes);
+        return { kind: 'complete', changed: prepared.changes.length > 0, changes: prepared.changes };
+    }
+    catch (error) {
+        return refuse('TEAM_METADATA_UNAVAILABLE', `team metadata could not be updated (${errorCause(error)})`, authority.root);
+    }
+}
+export async function validateTeamMetadata(configPath) {
+    const root = dirname(resolve(configPath));
+    const packagePath = join(root, 'package.json');
+    try {
+        const authority = await captureRoot(root);
+        const current = await readOptional(authority, packagePath);
+        const decoded = current ? parseJsonText(current.bytes, 'package.json', PACKAGE_JSON_SHAPE) : { value: undefined };
+        if ('refusal' in decoded)
+            return refuse('TEAM_METADATA_UNAVAILABLE', `${decoded.refusal}; repair it, then run ${cockpitCommand('sync', { config: configPath })}`, packagePath);
+        const parsed = decoded.value;
+        const slots = object(parsed) ? packageDependencySlots(parsed) : undefined;
+        if (object(parsed) && !slots)
+            return refuse('TEAM_METADATA_UNAVAILABLE', 'package.json direct npm dependency sections must be objects; repair package.json, then run npx --no cockpit sync --config <your cockpit.toml> again', packagePath);
+        if (slots?.misplaced.length)
+            return refuse('TEAM_METADATA_UNAVAILABLE', misplacedDependencyMessage(slots.misplaced), packagePath);
+        const pinned = slots?.devDependencies[PACKAGE];
+        if (typeof pinned === 'string' && pinned.startsWith('file:')) {
+            if (pinned !== await verifiedLocalPin(authority, current?.bytes))
+                return refuse('COCKPIT_VERSION_MISMATCH', `package.json pins ${PACKAGE} to ${pinned}, but package-lock.json and node_modules do not resolve that archive to the running ${VERSION}; run npm install, then ${cockpitCommand('check')}`, packagePath);
+        }
+        else if (pinned !== VERSION)
+            return refuse('COCKPIT_VERSION_MISMATCH', `package.json pins ${PACKAGE} ${String(pinned ?? '(missing)')}, but ${VERSION} is running; run npm install --save-dev --save-exact ${PACKAGE}@${VERSION}`, packagePath);
+        const scripts = object(parsed) && object(parsed.scripts) ? parsed.scripts : undefined;
+        if (!scripts || Object.entries(SCRIPTS).some(([name, command]) => scripts[name] !== command)) {
+            return refuse('TEAM_METADATA_UNAVAILABLE', `package.json does not contain the exact cockpit:* scripts that sync writes; run ${cockpitCommand('sync', { config: configPath })}`, packagePath);
+        }
+        const loaded = await loadCockpitConfig(configPath);
+        await authenticateRoot(authority);
+        if (loaded.kind !== 'complete')
+            return configRefusal(loaded, configPath);
+        const block = await ignoreBlock(root, loaded.result.config);
+        if (block === undefined) {
+            return refuse('TEAM_METADATA_UNAVAILABLE', `cockpit.siblings_root must be a single-line path without NUL because .gitignore cannot represent it literally; fix cockpit.toml and run ${cockpitCommand('sync', { config: configPath })}`, 'cockpit.siblings_root');
+        }
+        const ignorePath = join(root, '.gitignore');
+        const ignore = await readOptional(authority, ignorePath);
+        const expected = ignoreCandidate(ignore?.bytes ?? '', block);
+        if (expected === undefined)
+            return refuse('TEAM_METADATA_UNAVAILABLE', `the cockpit-owned .gitignore block was edited; restore it exactly, or remove the whole ${START} through ${END} region and run npx --no cockpit sync --config <your cockpit.toml> again`, ignorePath);
+        if (!ignore || expected !== ignore.bytes)
+            return refuse('TEAM_METADATA_UNAVAILABLE', 'the cockpit-owned .gitignore block is missing or does not match cockpit.toml and the sibling directories on disk; run npx --no cockpit sync --config <your cockpit.toml> to rewrite it', ignorePath);
+        return { kind: 'complete', changed: false, changes: [] };
+    }
+    catch (error) {
+        return refuse('TEAM_METADATA_UNAVAILABLE', `team metadata could not be verified (${errorCause(error)})`, root);
+    }
+}
+/**
+ * What a teammate's clone of this cockpit, or the cockpit itself, will lack, read from the
+ * cockpit root and its declaration without changing anything. `init` runs from a temporary copy of
+ * cockpit and leaves none in the cockpit, so every printed `npx --no cockpit` then failed and the
+ * guard hook stayed bound to that copy; and a sibling repository recorded without a remote is one
+ * a teammate's `setup` silently leaves absent.
+ */
+export async function inspectTeamReadiness(configPath) {
+    const root = dirname(resolve(configPath));
+    const findings = [];
+    const installed = join(root, 'node_modules', ...PACKAGE.split('/'));
+    const present = await lstat(installed).then((status) => status.isDirectory(), (error) => {
+        if (isMissing(error))
+            return false;
+        throw error;
+    });
+    if (!present) {
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'COCKPIT_NOT_INSTALLED',
+            message: `cockpit is not installed in ${root}, so every npx --no cockpit command the generated instructions print fails there, and the guard hook runs whichever copy last ran sync`,
+            target: 'node_modules',
+            fix: `in a terminal in ${root}, run npm install (package.json pins the version), then run npx --no cockpit sync --config <your cockpit.toml> so the guard hook runs the installed copy`,
+        });
+    }
+    else {
+        const read = await readBoundedInput(join(root, GUARD_LOCAL_PATHS.identity)).catch((error) => {
+            if (hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            throw error;
+        });
+        const identity = read?.kind === 'complete' ? parseGuardLocalIdentity(Buffer.from(read.bytes).toString('utf8')) : undefined;
+        const own = await realpath(installed);
+        if (identity && relative(own, identity.module).startsWith('..'))
+            findings.push({
+                severity: 'warning',
+                // A literal, so the diagnostic inventory captures the fix beside the code.
+                code: 'COCKPIT_NOT_INSTALLED',
+                message: `the guard hook runs the cockpit copy at ${identity.module}, not the one installed in ${own}, so it stops working when that copy is removed and can differ from the pinned version`,
+                target: GUARD_LOCAL_PATHS.identity,
+                fix: `in a terminal in ${root}, run npx --no cockpit sync --config <your cockpit.toml>, which binds the guard hook to the installed copy`,
+            });
+        // The guard's own proof, run as it runs it from the cockpit root once it runs the installed copy.
+        // A root .npmrc, a bin the root package.json declares, or a link that is not npm's leaves every
+        // printed npx form asking a person.
+        const launcher = join(own, 'bin/cockpit.mjs');
+        if (!findings.length && guardLauncherEvidence('npx', ['--no', 'cockpit'], root, root, launcher, '') === undefined) {
+            const linked = guardLauncherEvidence('./node_modules/.bin/cockpit', [], root, root, launcher, '') !== undefined;
+            findings.push({
+                severity: 'warning',
+                // A literal, so the diagnostic inventory captures the fix beside the code.
+                code: 'COCKPIT_LAUNCHER_UNPROVEN',
+                message: `the guard cannot prove that npx --no cockpit run in ${root} starts the cockpit installed there, so it asks a person before every such command and Codex and OpenCode refuse it; `
+                    + (linked ? './node_modules/.bin/cockpit <command> --config cockpit.toml is proven by its path and runs without asking'
+                        : 'node_modules/.bin/cockpit is not npm\'s link to the installed package either'),
+                target: 'npx --no cockpit',
+                fix: 'run cockpit as ./node_modules/.bin/cockpit <command> --config <your cockpit.toml> from the cockpit root, or remove what stops npx from proving it: a .npmrc in the cockpit root, a bin or directories.bin in its package.json, or a node_modules/.bin/cockpit that npm install did not link to the installed package',
+            });
+        }
+    }
+    const loaded = await loadCockpitConfig(configPath);
+    if (loaded.kind !== 'complete')
+        return findings;
+    const siblings = resolve(root, loaded.result.config.cockpit.siblings_root);
+    for (const sibling of loaded.result.config.sibling) {
+        const path = resolve(siblings, sibling.dir);
+        // The cockpit's own directory is cloned with the cockpit; a plain directory is tracked by it.
+        if (sibling.acquire !== 'none' || path === root || !await holdsGitMetadata(path))
+            continue;
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_REMOTE_UNRECORDED',
+            message: `sibling ${sibling.slug} is its own Git repository, but cockpit.toml records no remote for it (acquire = "none"), so setup in a teammate's clone of this cockpit leaves ${sibling.dir} absent`,
+            target: `sibling:${sibling.slug}`,
+            fix: `once the repository is pushed, run npx --no cockpit sibling add ${sibling.slug} --remote <url> --config <your cockpit.toml> and commit cockpit.toml`,
+        });
+    }
+    return findings;
+}

package/dist/testing/gates.d.ts

@@ -0,0 +1,91 @@
+import { type EnvironmentSnapshot, type RuntimeEvidence } from '../environment/evidence.js';
+import { type ProjectionPlannerInput, type StandingCost } from '../surfaces/projection.js';
+import { type RunClassification, type StageObservation, type StageResult } from './verdict.js';
+export declare const GATE_SELECTOR_OPTION = "--select";
+export type GateSelector = Readonly<{
+    kind: 'spec';
+    value: string;
+}> | Readonly<{
+    kind: 'file';
+    value: string;
+}> | Readonly<{
+    kind: 'test';
+    value: string;
+}> | Readonly<{
+    kind: 'route';
+    value: string;
+}>;
+export interface GateStage {
+    readonly id: string;
+    readonly command: readonly [string, ...string[]];
+    readonly requiresStack: boolean;
+    readonly timeoutSeconds: number;
+    readonly select?: Readonly<Partial<Record<GateSelector['kind'], readonly string[]>>>;
+}
+export interface GateDefinition {
+    readonly id: string;
+    readonly tier: 'targeted' | 'full';
+    readonly stages: readonly string[];
+    readonly changes: string;
+}
+export interface GateDeclarations {
+    readonly stages: readonly GateStage[];
+    readonly gates: readonly GateDefinition[];
+}
+export interface GateRegistry extends GateDeclarations {
+    readonly kind: 'bound' | 'unbound';
+    readonly tiers: readonly Readonly<{
+        id: 'none' | 'targeted' | 'full';
+        title: string;
+        changes: string;
+        gate: string;
+    }>[];
+}
+export declare const TESTING_GUIDE_REGISTRY: GateRegistry;
+export declare function createGateRegistry(input: GateDeclarations): GateRegistry;
+export interface ProductGateInvocation {
+    readonly gate: string;
+    readonly stage: string;
+    readonly command: readonly [string, ...string[]];
+    readonly timeoutSeconds: number;
+    readonly select: GateSelector | null;
+}
+export interface GateRequest {
+    readonly gate: string;
+    readonly stages?: readonly string[];
+    readonly select?: GateSelector;
+    readonly staged?: boolean;
+    readonly stack?: Readonly<{
+        state: 'available';
+    }> | Readonly<{
+        state: 'unavailable';
+        reason: string;
+    }>;
+}
+export interface GateDependencies {
+    readonly subject: () => Promise<string>;
+    readonly runProductTool: (invocation: ProductGateInvocation) => Promise<StageResult>;
+    readonly runtime?: Readonly<{
+        snapshot: EnvironmentSnapshot;
+        capture: () => Promise<RuntimeEvidence>;
+    }>;
+}
+export interface GateRun extends RunClassification {
+    readonly observations: readonly StageObservation[];
+}
+export declare function runGate(registry: GateRegistry, request: GateRequest, deps: GateDependencies): Promise<GateRun>;
+export type TierGuideResult = Readonly<{
+    kind: 'complete';
+    bytes: string;
+    lines: number;
+    costs: readonly StandingCost[];
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+    exceeded?: Readonly<{
+        target: string;
+        value: number;
+        cap: number;
+    }>;
+}>;
+export declare function renderTierGuide(registry: GateRegistry, projection: ProjectionPlannerInput): TierGuideResult;