@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/init/render.d.ts

@@ -0,0 +1,35 @@
+import type { CockpitConfig, configurationDefaults, UNCONFIRMABLE_ANSWERS } from '../schema.js';
+import type { DocumentedSibling, Gap } from '../registry-resolve/registry.js';
+/**
+ * Who gave an interview answer: a person, the setup agent choosing a default it was allowed to
+ * choose, or no one said (an answers file that does not attribute a value cockpit never proposes).
+ * Only a person's answer is written as stated; the others are listed under `unconfirmed`.
+ */
+export declare const ANSWER_PROVENANCES: readonly ['operator-confirmed', 'agent-default', 'unattributed'];
+export type AnswerProvenance = typeof ANSWER_PROVENANCES[number];
+export type UnconfirmableAnswer = typeof UNCONFIRMABLE_ANSWERS[number];
+export type UnconfirmedAnswer = Readonly<{
+    field: UnconfirmableAnswer;
+    provenance: Exclude<AnswerProvenance, 'operator-confirmed'>;
+}>;
+export declare function unconfirmedReason(row: UnconfirmedAnswer): string;
+export declare const UNCONFIRMED_FIX = "confirm the value with whoever owns the product and correct it in cockpit.toml if it is wrong, then delete its entry from unconfirmed and run npx --no cockpit sync --config <your cockpit.toml>";
+export interface Attribution {
+    target: string;
+    value: unknown;
+    from: 'inferred' | 'default';
+    because: string;
+}
+export interface DocumentModel {
+    name?: string;
+    defaults: ReturnType<typeof configurationDefaults>;
+    siblings: readonly DocumentedSibling[];
+    attributions: readonly Attribution[];
+    gaps: readonly Gap[];
+    unconfirmed?: readonly UnconfirmedAnswer[];
+    /** Values read from the cockpit root's own files, keyed by their target. */
+    inferred?: Readonly<Partial<Record<'ports.bases' | 'environment.compose_files', unknown>>>;
+}
+export declare function renderIncompleteDocument(model: DocumentModel, schemaDirective: string, configuration?: CockpitConfig): string;
+/** Decisions are comments: the schema has no field for them, and the reader of the file needs them. */
+export declare function renderCompleteDocument(config: CockpitConfig, schemaDirective: string, decisions?: readonly string[], unconfirmed?: readonly UnconfirmedAnswer[]): string;

package/dist/init/render.js

@@ -0,0 +1,82 @@
+import { AUTONOMY_DEFAULTS, GATE_DEFAULTS } from '../autonomy.js';
+import { emitGaps, emitToml, toSiblingRows } from '../emit.js';
+/**
+ * Who gave an interview answer: a person, the setup agent choosing a default it was allowed to
+ * choose, or no one said (an answers file that does not attribute a value cockpit never proposes).
+ * Only a person's answer is written as stated; the others are listed under `unconfirmed`.
+ */
+export const ANSWER_PROVENANCES = ['operator-confirmed', 'agent-default', 'unattributed'];
+export function unconfirmedReason(row) {
+    return row.provenance === 'agent-default'
+        ? `${row.field} was chosen by the setup agent as a default; no person stated it`
+        : `${row.field} came from an answers file that did not say who chose it; no person is known to have stated it`;
+}
+export const UNCONFIRMED_FIX = 'confirm the value with whoever owns the product and correct it in cockpit.toml if it is wrong, then delete its entry from unconfirmed and run npx --no cockpit sync --config <your cockpit.toml>';
+function renderUnconfirmed(rows = []) {
+    if (rows.length === 0)
+        return '';
+    return `${rows.map(row => `# Unconfirmed: ${unconfirmedReason(row)}.\n`).join('')}# To confirm: ${UNCONFIRMED_FIX}; until then doctor warns.\n`;
+}
+/** Every decision with its default, commented out: flip one to "person" to take that decision yourself. */
+function renderDecisionDefaults() {
+    const table = (name, defaults) => [`# [${name}]`, ...Object.entries(defaults).map(([key, value]) => `# ${key} = "${value}"`)];
+    return `\n${[
+        '# Who takes each decision. All default to "agent" except reset and mcp_approve; set one to "person" to take it yourself.',
+        '# mcp_approve = "agent" lets an agent start processes outside the guard: sync then enables every server',
+        '# a sibling MCP source declares, and an agent can write that file.',
+        ...table('work.gates', GATE_DEFAULTS), ...table('autonomy', AUTONOMY_DEFAULTS),
+    ].join('\n')}\n`;
+}
+function renderAttributions(attributions) {
+    if (attributions.length === 0)
+        return '';
+    const lines = ['# Provenance — every unread value names its source and reason.'];
+    for (const attribution of attributions) {
+        lines.push(`# [${attribution.from}] ${attribution.target} = ${JSON.stringify(attribution.value)}: ${attribution.because}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function draftConfig(model) {
+    // Written, the guard hosts read as a decision that none exists, even as the schema default [].
+    const { hosted_db_hosts: _hosted, vendor_endpoint_hosts: _vendors, ...guards } = model.defaults.guards;
+    // No registry dialect records the work-order time budgets, grading, gates, evaluator tools or
+    // autonomy, so a draft that wrote the schema's values would present them as this product's
+    // decisions; left out, the loader applies the same defaults.
+    const { autonomy: _autonomy, ...defaults } = model.defaults;
+    const work = { attempt_cap: model.defaults.work.attempt_cap, wip_cap: model.defaults.work.wip_cap };
+    const bases = model.inferred?.['ports.bases'];
+    const composeFiles = model.inferred?.['environment.compose_files'];
+    return {
+        ...defaults,
+        cockpit: {
+            ...model.defaults.cockpit,
+            ...(model.name ? { name: model.name } : {}),
+        },
+        sibling: toSiblingRows(model.siblings).map((sibling) => ({
+            ...sibling,
+            ...model.defaults.sibling,
+        })),
+        ports: { ...model.defaults.ports, ...(bases === undefined ? {} : { bases }) },
+        guards,
+        work,
+        environment: { ...model.defaults.environment, ...(composeFiles === undefined ? {} : { compose_files: composeFiles }) },
+    };
+}
+export function renderIncompleteDocument(model, schemaDirective, configuration) {
+    const config = configuration ?? draftConfig(model);
+    return [
+        `#:schema ${schemaDirective}\n`,
+        configuration || !model.gaps.some(gap => gap.blocking)
+            ? '# COCKPIT DOCUMENT: REVIEW DRAFT — confirm the inferred and default values before publication.\n'
+            : '# COCKPIT DOCUMENT: INCOMPLETE DRAFT — this file intentionally fails validation.\n',
+        renderAttributions(model.attributions),
+        renderUnconfirmed(model.unconfirmed),
+        emitGaps(model.gaps),
+        emitToml(config),
+        renderDecisionDefaults(),
+    ].join('');
+}
+/** Decisions are comments: the schema has no field for them, and the reader of the file needs them. */
+export function renderCompleteDocument(config, schemaDirective, decisions = [], unconfirmed = []) {
+    return `#:schema ${schemaDirective}\n${decisions.map(decision => `# Decision: ${decision}\n`).join('')}${renderUnconfirmed(unconfirmed)}${emitToml(config)}${renderDecisionDefaults()}`;
+}

package/dist/init/scaffold.d.ts

@@ -0,0 +1,53 @@
+export declare const SCAFFOLD_BACKING_SERVICES: Readonly<{
+    postgres: Readonly<{
+        image: "postgres:17-alpine";
+        environment: Readonly<{
+            POSTGRES_PASSWORD: "postgres";
+        }>;
+        volume: "/var/lib/postgresql/data";
+        healthcheck: readonly string[];
+        url: readonly string[];
+    }>;
+    redis: Readonly<{
+        image: "redis:7-alpine";
+        environment: Readonly<{}>;
+        volume: "/data";
+        healthcheck: readonly string[];
+        url: readonly string[];
+    }>;
+}>;
+export type ScaffoldBackingService = keyof typeof SCAFFOLD_BACKING_SERVICES;
+export interface ComposeScaffoldInput {
+    /** The app directory, relative to the cockpit root; `.` for the root itself. */
+    readonly dir: string;
+    /** Whether the app directory holds a Dockerfile, which then builds the app image. */
+    readonly dockerfile: boolean;
+    /** Whether it holds a package.json, so a stock Node image can run it without a Dockerfile. */
+    readonly packageJson: boolean;
+    /** The command the app service runs; required without a Dockerfile, which otherwise sets it. */
+    readonly command?: readonly string[];
+    readonly port: number;
+    readonly with: readonly ScaffoldBackingService[];
+}
+export type ComposeScaffold = Readonly<{
+    kind: 'complete';
+    service: string;
+    portVariable: string;
+    volumes: readonly string[];
+    bytes: string;
+}> | Readonly<{
+    kind: 'refusal';
+    message: string;
+    fix: string;
+}>;
+/** The compose.yml text for the declared app, with the [ports.bases] variable and volumes it introduces. */
+export declare function renderComposeScaffold(input: ComposeScaffoldInput): ComposeScaffold;
+export type ComposeScaffoldWrite = Readonly<{
+    kind: 'written';
+    path: string;
+}> | Readonly<{
+    kind: 'exists';
+    path: string;
+}>;
+/** Creates root/compose.yml unless any Compose file is already there; it never replaces one. */
+export declare function writeComposeScaffold(root: string, bytes: string): Promise<ComposeScaffoldWrite>;

package/dist/init/scaffold.js

@@ -0,0 +1,121 @@
+// Writes a starting compose.yml for a small app that has none, once. The file is the user's from then
+// on: cockpit never rewrites it, and cockpit.toml runs it as written through environment.compose_files.
+// It is deliberately small (one app service, an optional database and cache from a fixed list), so
+// anything beyond that is plain Compose the user adds, not more options here.
+import { lstat, open } from 'node:fs/promises';
+import { basename, isAbsolute, join, normalize } from 'node:path';
+import { deriveSiblingVariable } from '../schema.js';
+import { hasErrorCode } from '../environment/contract.js';
+/** The names Compose looks for; any one of them already present means the product has a Compose file. */
+const COMPOSE_FILE_NAMES = Object.freeze(['compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml']);
+// Tags pinned to a major version, so a scaffold written today runs the same release line tomorrow.
+// The credentials are local-only defaults for a stack bound to loopback; the app reads the URL.
+export const SCAFFOLD_BACKING_SERVICES = Object.freeze({
+    postgres: Object.freeze({
+        image: 'postgres:17-alpine',
+        environment: Object.freeze({ POSTGRES_PASSWORD: 'postgres' }),
+        volume: '/var/lib/postgresql/data',
+        healthcheck: Object.freeze(['CMD', 'pg_isready', '-U', 'postgres']),
+        url: Object.freeze(['DATABASE_URL', 'postgres://postgres:postgres@postgres:5432/postgres']),
+    }),
+    redis: Object.freeze({
+        image: 'redis:7-alpine',
+        environment: Object.freeze({}),
+        volume: '/data',
+        healthcheck: Object.freeze(['CMD', 'redis-cli', 'ping']),
+        url: Object.freeze(['REDIS_URL', 'redis://redis:6379']),
+    }),
+});
+// One image per toolchain cockpit can recognise without a Dockerfile; anything else brings its own.
+const TOOLCHAIN_IMAGE = 'node:22-alpine';
+const json = (value) => JSON.stringify(value);
+/** The compose.yml text for the declared app, with the [ports.bases] variable and volumes it introduces. */
+export function renderComposeScaffold(input) {
+    const dir = input.dir === '.' ? '.' : normalize(input.dir);
+    if (isAbsolute(dir) || dir.split('/').includes('..') || dir.includes('\\') || /[\x00-\x1f\x7f$]/.test(dir))
+        return {
+            kind: 'refusal', message: `the app directory ${json(input.dir)} is not a plain path inside the cockpit root`,
+            fix: 'pass --scaffold-compose the app directory relative to the cockpit root, or . for the root itself'
+        };
+    if (!Number.isInteger(input.port) || input.port < 1 || input.port > 65_535)
+        return {
+            kind: 'refusal', message: `--port ${input.port} is not a TCP port`, fix: 'pass --port the port the app listens on inside its container'
+        };
+    if (!input.dockerfile && !input.packageJson)
+        return {
+            kind: 'refusal', message: `${dir === '.' ? 'the cockpit root' : dir} has neither a Dockerfile nor a package.json, so no image is known to run it`,
+            fix: 'add a Dockerfile to the app directory, then rerun the scaffold'
+        };
+    if (!input.dockerfile && !input.command?.length)
+        return {
+            kind: 'refusal', message: `${dir === '.' ? 'the cockpit root' : dir} has no Dockerfile, so the scaffold needs the command that starts the app`,
+            fix: 'pass --command with the start command, such as --command "npm start", or add a Dockerfile to the app directory'
+        };
+    const service = (dir === '.' ? 'app' : basename(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'app';
+    const portVariable = `${service.toUpperCase().replaceAll('-', '_')}_HOST_PORT`;
+    const siblingVariable = deriveSiblingVariable(service);
+    const source = dir === '.' ? '.' : `./${dir}`;
+    const backing = [...new Set(input.with)].sort();
+    const lines = [
+        "# Written once by cockpit's Compose scaffold; it is yours to edit. cockpit runs it as",
+        '# written and never rewrites it. Every published port binds 127.0.0.1 and comes from a',
+        '# [ports.bases] variable, so parallel stacks do not collide.',
+        'services:',
+        `  ${service}:`,
+        ...input.dockerfile ? [`    build: \${${siblingVariable}:-${source}}`] : [`    image: ${TOOLCHAIN_IMAGE}`],
+        // A minimal init as PID 1 forwards SIGTERM, so sleep and down stop the app promptly.
+        '    init: true',
+        '    working_dir: /app',
+        ...input.command?.length ? [`    command: ${json(input.command)}`] : [],
+        `    ports: [${json(`127.0.0.1:\${${portVariable}:-${input.port}}:${input.port}`)}]`,
+        `    volumes: [${json(`${source}:/app`)}]`,
+        ...backing.length > 0 ? [
+            '    environment:',
+            ...backing.map(name => `      ${SCAFFOLD_BACKING_SERVICES[name].url[0]}: ${json(SCAFFOLD_BACKING_SERVICES[name].url[1])}`),
+            '    depends_on:',
+            ...backing.flatMap(name => [`      ${name}:`, '        condition: service_healthy']),
+        ] : [],
+        ...backing.flatMap(name => {
+            const declared = SCAFFOLD_BACKING_SERVICES[name];
+            return [
+                `  ${name}:`,
+                `    image: ${declared.image}`,
+                ...Object.keys(declared.environment).length > 0 ? ['    environment:',
+                    ...Object.entries(declared.environment).map(([key, value]) => `      ${key}: ${json(value)}`)] : [],
+                `    volumes: [${json(`${name}-data:${declared.volume}`)}]`,
+                '    healthcheck:',
+                `      test: ${json(declared.healthcheck)}`,
+                '      interval: 5s',
+                '      retries: 10',
+            ];
+        }),
+        ...backing.length > 0 ? ['volumes:', ...backing.map(name => `  ${name}-data: {}`)] : [],
+        '',
+    ];
+    return { kind: 'complete', service, portVariable, volumes: backing.map(name => `${name}-data`),
+        bytes: lines.join('\n') };
+}
+/** Creates root/compose.yml unless any Compose file is already there; it never replaces one. */
+export async function writeComposeScaffold(root, bytes) {
+    for (const name of COMPOSE_FILE_NAMES) {
+        const path = join(root, name);
+        try {
+            await lstat(path);
+            return { kind: 'exists', path };
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                throw error;
+        }
+    }
+    const path = join(root, 'compose.yml');
+    // `wx` fails if the file appeared since the check, so a concurrent write is never replaced.
+    const handle = await open(path, 'wx', 0o644);
+    try {
+        await handle.writeFile(bytes);
+    }
+    finally {
+        await handle.close();
+    }
+    return { kind: 'written', path };
+}

package/dist/invocation.d.ts

@@ -0,0 +1,13 @@
+export declare const EXIT_CODES: Readonly<{
+    readonly success: 0;
+    readonly failure: 2;
+    readonly cancelled: 130;
+}>;
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+export interface InvocationRecord {
+    readonly verb: string;
+    readonly durationMs: number;
+    readonly exitCode: ExitCode;
+    readonly resolvedConfigPath: string | null;
+}
+export declare function createInvocationRecord(input: InvocationRecord): InvocationRecord;

package/dist/invocation.js

@@ -0,0 +1,20 @@
+import { isAbsolute, normalize } from 'node:path';
+export const EXIT_CODES = Object.freeze({ success: 0, failure: 2, cancelled: 130 });
+export function createInvocationRecord(input) {
+    const { verb, durationMs, exitCode, resolvedConfigPath } = input;
+    if (typeof verb !== 'string' || !/^[a-z][a-z0-9-]*(?: [a-z][a-z0-9-]*)*$/.test(verb)) {
+        throw new Error('Invocation verb must be non-empty command words without control characters');
+    }
+    if (!Number.isSafeInteger(durationMs) || durationMs < 0) {
+        throw new Error('Invocation durationMs must be a non-negative finite safe integer');
+    }
+    if (!Object.values(EXIT_CODES).includes(exitCode)) {
+        throw new Error('Invocation exitCode must be success (0), failure (2), or cancellation (130)');
+    }
+    if (resolvedConfigPath !== null && (typeof resolvedConfigPath !== 'string'
+        || !isAbsolute(resolvedConfigPath) || normalize(resolvedConfigPath) !== resolvedConfigPath
+        || /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/.test(resolvedConfigPath))) {
+        throw new Error('Invocation resolvedConfigPath must be null or a normalized absolute path without control characters');
+    }
+    return { verb, durationMs, exitCode, resolvedConfigPath };
+}

package/dist/package-metadata.d.ts

@@ -0,0 +1,9 @@
+export interface InstalledPackageMetadata {
+    readonly name: string;
+    readonly version: string;
+    readonly engines: Readonly<{
+        node: string;
+    }>;
+    readonly cockpitSourceRevision: string;
+}
+export declare const installedPackageMetadata: InstalledPackageMetadata;

package/dist/package-metadata.js

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+const actual = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const record = actual !== null && typeof actual === 'object' && !Array.isArray(actual) ? actual : undefined;
+const fields = record;
+const engines = fields?.engines;
+const text = (value) => typeof value === 'string' && value.length > 0
+    && value.length <= 256 && value.trim() === value && !/[\u0000-\u0020\u007f-\u009f]/.test(value);
+if (!fields || !text(fields.name) || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(fields.name)
+    || !text(fields.version) || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(fields.version)
+    || !engines || typeof engines.node !== 'string' || engines.node.length === 0 || engines.node.length > 256
+    || !/^[0-9v<>=~^.*|xX+ -]+$/.test(engines.node) || !/\d/.test(engines.node)
+    || !text(fields.cockpitSourceRevision))
+    throw new Error('Installed package metadata is invalid: name, version, engines.node and cockpitSourceRevision are required');
+export const installedPackageMetadata = Object.freeze({
+    name: fields.name,
+    version: fields.version,
+    engines: Object.freeze({ node: engines.node }),
+    cockpitSourceRevision: fields.cockpitSourceRevision,
+});

package/dist/readiness.d.ts

@@ -0,0 +1,53 @@
+/** A cockpit that only publishes agent surfaces, or one that also declares a runtime. */
+export type ReadinessState = 'surfaces-only' | 'runtime';
+export interface ReadinessEntry {
+    readonly id: string;
+    /** Why cockpit needs it, in one sentence. */
+    readonly needs: string;
+    /** Required prerequisites are refused by `refusedBy`; recommended ones only warn. */
+    readonly level: 'required' | 'recommended';
+    readonly appliesTo: readonly ReadinessState[];
+    /** The existing diagnostics that report this prerequisite missing. */
+    readonly codes: readonly string[];
+    /** The command that refuses while a required prerequisite is missing, and the code it refuses with. */
+    readonly refusedBy?: Readonly<{
+        command: string;
+        code: string;
+    }>;
+    /** What to do when a finding carries no fix of its own. */
+    readonly fix: string;
+    /** The agent tools the prerequisite concerns; it applies only while one of them is listed. */
+    readonly tools?: readonly string[];
+}
+export declare const READINESS_CATALOGUE: readonly ReadinessEntry[];
+export interface ReadinessFinding {
+    readonly code: string;
+    readonly severity: string;
+    readonly target?: string;
+    readonly message: string;
+    readonly fix: string;
+}
+export interface ReadinessGap {
+    readonly id: string;
+    readonly level: ReadinessEntry['level'];
+    readonly needs: string;
+    readonly findings: readonly ReadinessFinding[];
+}
+export interface ReadinessReport {
+    /** Undetermined before init has classified the estate and while no cockpit.toml says. */
+    readonly state: ReadinessState | 'undetermined';
+    /** Prerequisites some reported diagnostic says are missing, in catalogue order. */
+    readonly gaps: readonly ReadinessGap[];
+    /** Catalogue ids that apply to this state and that no reported diagnostic named. */
+    readonly noFinding: readonly string[];
+}
+type ReportedDiagnostic = Readonly<{
+    code: string;
+    severity: string;
+    message: string;
+    target?: string;
+    fix?: string;
+}>;
+/** Groups the diagnostics a command reported under the prerequisites they name, for the listed tools. */
+export declare function readinessReport(state: ReadinessReport['state'], diagnostics: readonly ReportedDiagnostic[], tools: readonly string[]): ReadinessReport;
+export {};

package/dist/readiness.js

@@ -0,0 +1,88 @@
+// The prerequisites cockpit itself depends on in a product and its cockpit, each with why it is
+// needed and the diagnostics that already report its absence. It detects nothing: the owners of
+// those diagnostics do, and a required prerequisite is refused by the command that needs it. This
+// module only gathers what a command reported into one list a person, or the setup agent walking
+// them through it, can act on. Judgement (which test runner, whether existing tests mean anything)
+// stays with them; a gap here is a fact.
+import { ENVIRONMENT_CODES } from './environment/contract.js';
+const C = ENVIRONMENT_CODES;
+const BOTH = Object.freeze(['surfaces-only', 'runtime']);
+const RUNTIME = Object.freeze(['runtime']);
+export const READINESS_CATALOGUE = [
+    { id: 'cockpit-git', level: 'required', appliesTo: BOTH, codes: [C.SETUP_PATH_TYPE_INVALID],
+        refusedBy: { command: 'setup', code: C.SETUP_PATH_TYPE_INVALID },
+        needs: 'setup confines every repository write to the cockpit\'s Git working tree, and teammates get the cockpit by cloning it',
+        fix: 'run git init in the cockpit root' },
+    { id: 'cockpit-committed', level: 'required', appliesTo: BOTH, codes: [C.GIT_STATE_UNHEALTHY, C.CHECKOUT_ADJACENCY_UNHEALTHY],
+        refusedBy: { command: 'preflight', code: C.GIT_STATE_UNHEALTHY },
+        needs: 'preflight vouches only for a committed cockpit, and a teammate\'s clone holds only what was committed',
+        fix: 'review git status --short in the cockpit root with a person, then commit the cockpit files' },
+    { id: 'cockpit-installed', level: 'recommended', appliesTo: BOTH, codes: [C.COCKPIT_NOT_INSTALLED],
+        needs: 'every instruction cockpit generates runs npx --no cockpit from the cockpit root, and the guard hook runs the copy installed there',
+        fix: 'run npm install in the cockpit root, then npx --no cockpit sync --config <your cockpit.toml> in a terminal' },
+    { id: 'cockpit-launcher-proven', level: 'recommended', appliesTo: BOTH, codes: [C.COCKPIT_LAUNCHER_UNPROVEN],
+        needs: 'the guard runs a printed npx --no cockpit command without asking only when it can prove npx starts the installed cockpit, and a tool that cannot ask a person refuses what it would ask about',
+        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' },
+    { id: 'siblings-present', level: 'required', appliesTo: BOTH, codes: [C.SIBLING_MISSING, C.SETUP_NONE_ABSENT],
+        refusedBy: { command: 'check', code: C.SIBLING_MISSING },
+        needs: 'mounts, directory grants, guides and generated services all point at each declared repository',
+        fix: 'run npx --no cockpit setup --config <your cockpit.toml>, or clone the repository where cockpit.toml declares it' },
+    { id: 'sibling-remote', level: 'recommended', appliesTo: BOTH, codes: [C.SIBLING_REMOTE_UNRECORDED],
+        needs: 'setup in a teammate\'s clone of the cockpit obtains only the repositories whose remote cockpit.toml records',
+        fix: 'record the pushed repository with npx --no cockpit sibling add <slug> --remote <url> --config <your cockpit.toml>' },
+    { id: 'sibling-instructions', level: 'recommended', appliesTo: BOTH,
+        codes: [C.SIBLING_INSTRUCTIONS_AGENTS_ONLY, C.SIBLING_INSTRUCTIONS_CLAUDE_ONLY, C.SIBLING_INSTRUCTIONS_UNLINKED,
+            C.SIBLING_INSTRUCTIONS_MISSING, C.SIBLING_INSTRUCTIONS_TOOL_ONLY],
+        needs: 'each agent tool loads only the instruction files it reads in a repository, so an agent started there gets the repository\'s instructions in every listed tool only when they sit in the files those tools read',
+        fix: 'follow the fix on each finding; npx --no cockpit setup --config <your cockpit.toml> proposes the changes that need no judgement' },
+    { id: 'container-runtime', level: 'required', appliesTo: RUNTIME, codes: [C.RUNTIME_UNAVAILABLE, C.RUNTIME_UNMEASURED],
+        refusedBy: { command: 'up', code: C.RUNTIME_UNMEASURED },
+        needs: 'up runs the stack with Docker Compose, and only on a runtime this machine has measured',
+        fix: 'start Docker, then run npx --no cockpit runtime measure --config <your cockpit.toml> --image <local-image>' },
+    { id: 'machine-floor', level: 'required', appliesTo: RUNTIME,
+        codes: [C.MACHINE_MEMORY_BELOW_FLOOR, C.MACHINE_CPU_BELOW_FLOOR, C.MACHINE_DISK_BELOW_FLOOR],
+        refusedBy: { command: 'up', code: C.MACHINE_MEMORY_BELOW_FLOOR },
+        needs: 'up refuses to start a stack the container runtime cannot hold, measured against environment.machine',
+        fix: 'give the container runtime more capacity, or lower environment.machine deliberately with whoever owns the product' },
+    { id: 'env-schema', level: 'required', appliesTo: RUNTIME, codes: [C.ENV_SCHEMA_UNHEALTHY, C.ENV_SCHEMA_TOOL_MISSING],
+        refusedBy: { command: 'preflight', code: C.ENV_SCHEMA_UNHEALTHY },
+        needs: 'preflight validates a repository\'s .env.schema with Varlock, without reading a value, wherever the repository has one',
+        fix: 'install Varlock, then make the environment satisfy the schema' },
+    { id: 'guard-hosts', level: 'recommended', appliesTo: RUNTIME, codes: [C.GUARD_HOSTS_UNDECLARED],
+        needs: 'the guard denies agent commands that reach a non-local database or vendor API only when cockpit.toml names its hosts',
+        fix: 'list the hosts under [guards] in cockpit.toml, or write both lists empty to record that none exists' },
+    { id: 'testing-gate', level: 'recommended', appliesTo: RUNTIME, codes: [C.TESTING_GATE_UNDECLARED],
+        needs: 'test-run runs only the declared [testing] gates, and no work is graded PASS without one',
+        fix: 'declare the product test commands as [testing] stages with a targeted and a full gate' },
+    { id: 'secrets-untracked', level: 'recommended', appliesTo: BOTH, codes: [C.SECRET_FILE_TRACKED],
+        needs: 'the guard keeps agents from reading secret files, but a committed one is in every clone already',
+        fix: 'stop tracking the file, ignore it, rotate what it held, and commit a .env.example of the variable names' },
+    { id: 'harness-path-absolute', level: 'recommended', appliesTo: BOTH, codes: [C.GUARD_SEARCH_PATH_RELATIVE],
+        needs: 'the guard asks a person before every agent command while the PATH the agent harness runs with holds a relative entry, and a tool that cannot ask a person refuses what it asks about',
+        fix: 'remove relative and empty entries from the PATH the agent harness starts with' },
+    { id: 'codex-hook-trusted', level: 'recommended', appliesTo: BOTH, codes: [C.CODEX_HOOK_UNTRUSTED], tools: ['codexcli'],
+        needs: 'Codex runs the guard hook only once a person on this machine has trusted it',
+        fix: 'a person trusts the hook from codex in a terminal in the cockpit root' },
+    { id: 'work-evaluator', level: 'recommended', appliesTo: BOTH, codes: [C.EVALUATOR_UNAVAILABLE],
+        needs: 'work grade and cockpit grade run the first agent tool work.evaluators lists that can run, as the evaluator independent of the agent that did the work',
+        fix: 'install and sign in to an evaluator tool work.evaluators lists, or list one you have' },
+];
+/** Groups the diagnostics a command reported under the prerequisites they name, for the listed tools. */
+export function readinessReport(state, diagnostics, tools) {
+    const gaps = [];
+    const noFinding = [];
+    for (const entry of READINESS_CATALOGUE) {
+        if (entry.tools && !entry.tools.some(tool => tools.includes(tool)))
+            continue;
+        const findings = diagnostics.filter(({ code }) => entry.codes.includes(code));
+        if (findings.length > 0) {
+            gaps.push({ id: entry.id, level: entry.level, needs: entry.needs,
+                findings: findings.map(({ code, severity, target, message, fix }) => ({
+                    code, severity, ...(target === undefined ? {} : { target }), message, fix: fix ?? entry.fix
+                })) });
+        }
+        else if (state === 'undetermined' ? entry.appliesTo.length === BOTH.length : entry.appliesTo.includes(state))
+            noFinding.push(entry.id);
+    }
+    return { state, gaps, noFinding };
+}

package/dist/references/named.d.ts

@@ -0,0 +1,24 @@
+import { type GeneratedPathProducer, type OwnershipAuthority, type OwnershipManifest } from '../surfaces/ownership.js';
+interface NamedAuthority {
+    readonly manifest: OwnershipManifest;
+    readonly authority: OwnershipAuthority;
+    readonly declarations: unknown;
+}
+export interface NamedPathInput extends NamedAuthority {
+    readonly path: string;
+    readonly exists: boolean;
+}
+export type NamedPathResult = Readonly<{
+    kind: 'resolved';
+    path: string;
+}> | Readonly<{
+    kind: 'declared-before-sync' | 'unavailable';
+    path: string;
+    producer: GeneratedPathProducer;
+}> | Readonly<{
+    kind: 'refusal';
+    path: string;
+    reason: string;
+}>;
+export declare function resolveNamedPath(input: NamedPathInput): NamedPathResult;
+export {};

package/dist/references/named.js

@@ -0,0 +1,27 @@
+import { projectGeneratedPathFacts, } from '../surfaces/ownership.js';
+function safePath(path) {
+    return typeof path === 'string' && path.length > 0 && !/[\\\u0000-\u001f\u007f]/.test(path)
+        && !path.startsWith('/') && !/^[A-Za-z]:/.test(path)
+        && path.split('/').every(part => part !== '' && part !== '.' && part !== '..');
+}
+function resolveProjectedPath(path, exists, facts) {
+    if (!safePath(path))
+        return { kind: 'refusal', path, reason: 'reference must name an exact repository-relative path' };
+    if (exists)
+        return { kind: 'resolved', path };
+    const fact = facts.find(fact => fact.path === path);
+    const declaration = fact?.declaration;
+    if (declaration?.applicability === 'sibling-unavailable') {
+        return { kind: 'unavailable', path, producer: declaration.producer };
+    }
+    if (fact?.allowsMissing && declaration?.applicability === 'declared-before-sync') {
+        return { kind: 'declared-before-sync', path, producer: declaration.producer };
+    }
+    return { kind: 'refusal', path, reason: 'missing reference has no applicable exact producer declaration' };
+}
+export function resolveNamedPath(input) {
+    const projected = projectGeneratedPathFacts(input.manifest, input.authority, input.declarations);
+    if (projected.kind === 'refusal')
+        return { kind: 'refusal', path: input.path, reason: 'generated path authority was refused' };
+    return resolveProjectedPath(input.path, input.exists, projected.facts);
+}

package/dist/refusal.d.ts

@@ -0,0 +1,15 @@
+/** A command refusal with one error diagnostic: exit status 2, no result and nothing to write. */
+export declare function refusalOutcome(code: string, message: string, target?: string, fix?: string): {
+    kind: 'refusal';
+    status: 2;
+    artifact: null;
+    destination: null;
+    result: null;
+    diagnostics: {
+        severity: 'error';
+        code: string;
+        message: string;
+        target?: string | undefined;
+        fix?: string | undefined;
+    }[];
+};

package/dist/refusal.js

@@ -0,0 +1,7 @@
+/** A command refusal with one error diagnostic: exit status 2, no result and nothing to write. */
+export function refusalOutcome(code, message, target, fix) {
+    return {
+        kind: 'refusal', status: 2, artifact: null, destination: null, result: null,
+        diagnostics: [{ severity: 'error', code, message, ...(target === undefined ? {} : { target }), ...(fix === undefined ? {} : { fix }) }],
+    };
+}

package/dist/registry-derivation.d.ts

@@ -0,0 +1,31 @@
+import { type CockpitConfig as CockpitConfigValue, type Provenance } from './schema.js';
+export interface RegistryMcpSource {
+    readonly slug: string;
+    readonly siblingDir: string;
+    readonly path: string;
+    readonly provenance: Provenance;
+}
+export interface RegistrySecretPath {
+    readonly slug: string;
+    readonly siblingDir: string;
+    readonly path: string;
+    readonly kind: 'instance';
+}
+type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: DeepReadonly<T[Key]>;
+} : T;
+export interface DerivedRegistry {
+    readonly config: DeepReadonly<CockpitConfigValue>;
+    readonly mcpSources: readonly RegistryMcpSource[];
+    readonly secretPaths: readonly RegistrySecretPath[];
+}
+export type RegistryDerivationResult = Readonly<{
+    kind: 'complete';
+    result: DerivedRegistry;
+}> | Readonly<{
+    kind: 'refusal';
+    code: 'REGISTRY_INPUT_INVALID';
+    message: string;
+}>;
+export declare function deriveRegistry(input: unknown): RegistryDerivationResult;
+export {};