@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/setup.d.ts

@@ -0,0 +1,43 @@
+import { type EnvironmentCommandOutcome, type FilesystemCheck, type Observation, type SetupActionKind } from './contract.js';
+import type { Sibling } from '../schema.js';
+import { type ResolvedExecutable } from './executable.js';
+type ObservedPathKind = 'absent' | 'directory' | 'repository' | 'symlink';
+export interface SetupPathEvidence {
+    kind: ObservedPathKind;
+    missingParent?: string;
+    remotes?: Readonly<Record<string, string>>;
+    filesystemChecks?: readonly FilesystemCheck[];
+}
+export type SetupObservation = Observation<SetupPathEvidence>;
+export interface SetupResult {
+    sibling: string;
+    target: string;
+    observed: ObservedPathKind;
+    action: SetupActionKind;
+    changed: boolean;
+}
+interface PlanSetupBaseInput {
+    siblingsRoot: string;
+    sibling: Sibling;
+    env: Readonly<Record<string, string>>;
+    gitExecutable: ResolvedExecutable;
+}
+export type PlanSetupInput = PlanSetupBaseInput & ({
+    observation: SetupObservation;
+    observe?: never;
+} | {
+    observation?: never;
+    observe(target: string, siblingsRoot: string, env: Readonly<Record<string, string>>, gitExecutable: ResolvedExecutable): Promise<SetupObservation>;
+});
+export declare function gitEnvironment(ambient: Readonly<Record<string, string | undefined>>): Readonly<Record<string, string>>;
+export type LocalRemoteResolution = {
+    readonly kind: 'resolved';
+    readonly remote: string;
+} | {
+    readonly kind: 'unresolvable';
+    readonly declared: string;
+    readonly errno: string;
+};
+export declare function resolveLocalRemote(remote: string, siblingsRoot: string): LocalRemoteResolution;
+export declare function planSetup(input: PlanSetupInput): Promise<EnvironmentCommandOutcome<SetupResult>>;
+export {};

package/dist/environment/setup.js

@@ -0,0 +1,176 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { ENVIRONMENT_CODES, forwardedRefusal, } from './contract.js';
+import { resolvedGitExecutable } from './executable.js';
+function refusal(code, message, target) {
+    return forwardedRefusal([{ severity: 'error', code, message, target }]);
+}
+const APPROVED_GIT_ENVIRONMENT = [
+    'PATH', 'HOME', 'SSH_AUTH_SOCK', 'TMPDIR', 'LANG', 'LC_ALL',
+];
+const NONE_POSTURE = {
+    absent: { code: ENVIRONMENT_CODES.SETUP_NONE_ABSENT, found: 'nothing exists there yet' },
+    directory: { code: ENVIRONMENT_CODES.SETUP_NONE_DIRECTORY, found: 'it is a plain directory, not a Git checkout' },
+    repository: { code: ENVIRONMENT_CODES.SETUP_NONE_REPOSITORY, found: 'it is an existing Git checkout' },
+};
+export function gitEnvironment(ambient) {
+    const approved = {};
+    for (const name of APPROVED_GIT_ENVIRONMENT) {
+        const value = ambient[name];
+        if (value !== undefined)
+            approved[name] = value;
+    }
+    return {
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_CONFIG_NOSYSTEM: '1',
+        GIT_CONFIG_SYSTEM: '/dev/null',
+        GIT_TERMINAL_PROMPT: '0',
+        ...approved,
+    };
+}
+export function resolveLocalRemote(remote, siblingsRoot) {
+    const resolved = (value) => ({ kind: 'resolved', remote: value });
+    if (remote === '' || remote.startsWith('-') || isAbsolute(remote) || remote.startsWith('~'))
+        return resolved(remote);
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(remote))
+        return resolved(remote);
+    const colon = remote.indexOf(':');
+    if (colon !== -1 && !remote.slice(0, colon).includes('/'))
+        return resolved(remote);
+    const path = resolve(siblingsRoot, remote);
+    try {
+        return resolved(realpathSync(path));
+    }
+    catch (error) {
+        const errno = error.code;
+        if (errno === 'ENOENT')
+            return resolved(path);
+        return { kind: 'unresolvable', declared: remote, errno: errno ?? 'unknown error' };
+    }
+}
+function unresolvableRemoteRefusal(value, which, target) {
+    return {
+        kind: 'refusal',
+        status: 2,
+        diagnostics: [{
+                severity: 'error',
+                code: ENVIRONMENT_CODES.SETUP_REMOTE_UNRESOLVABLE,
+                message: `cannot resolve ${which} local remote ${JSON.stringify(value.declared)} (${value.errno})`,
+                target,
+                fix: 'make the remote path readable, or declare the remote as a URL or an absolute path to an existing repository, then run npx --no cockpit setup --config <your cockpit.toml> again',
+            }],
+        result: null,
+    };
+}
+function fallbackChecks(observation, siblingsRoot, target) {
+    if (observation.kind === 'absent') {
+        return [
+            { path: siblingsRoot, expected: 'directory' },
+            { path: target, expected: 'absent' },
+        ];
+    }
+    if (observation.kind === 'repository')
+        return [{ path: target, expected: 'directory' }];
+    return [];
+}
+function step(id, argv, cwd, env, target, filesystemChecks, executable) {
+    return {
+        id, argv, argv0: executable.invocationPath, cwd, env, timeoutMs: 120_000, stdoutLimitBytes: 65_536, stderrLimitBytes: 65_536,
+        failureOutput: 'stderr-tail',
+        paths: [target], ports: [], labels: { operation: 'setup' },
+        expected: [{ kind: 'path', target, state: 'repository' }],
+        consumedFiles: [{ path: executable.canonicalPath, sha256: executable.sha256, maxBytes: 536_870_912, argvIndexes: [0], executable: true, executionMode: executable.executionMode }],
+        filesystemChecks, compensation: [],
+    };
+}
+function preview(result, mutation, diagnostics = []) {
+    const plan = { steps: [mutation] };
+    return { kind: 'preview', status: 0, diagnostics, result, plan };
+}
+export async function planSetup(input) {
+    const siblingsRoot = resolve(input.siblingsRoot);
+    const target = resolve(siblingsRoot, input.sibling.dir);
+    const fromRoot = relative(siblingsRoot, target);
+    const gitExecutable = resolvedGitExecutable(input.gitExecutable);
+    if (gitExecutable === undefined) {
+        return refusal(ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID, 'Git executable identity is unresolved', target);
+    }
+    const resolvedGitEnvironment = gitEnvironment(input.env);
+    if (isAbsolute(input.sibling.dir) || fromRoot === '..' || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+        return refusal(ENVIRONMENT_CODES.SETUP_PATH_OUTSIDE_ROOT, 'sibling target is outside the declared siblings root', target);
+    }
+    const observed = input.observation ?? await input.observe(target, siblingsRoot, resolvedGitEnvironment, gitExecutable);
+    if (observed.state === 'failed') {
+        return refusal(observed.code, observed.reason, target);
+    }
+    if (observed.state === 'unavailable')
+        return refusal(ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID, observed.reason, target);
+    const observation = observed.value;
+    if (observation.kind === 'symlink') {
+        return refusal(ENVIRONMENT_CODES.SETUP_PATH_SYMLINK, 'sibling target or one of its path components is a symlink', target);
+    }
+    const result = (action, changed) => ({
+        sibling: input.sibling.slug,
+        target,
+        observed: observation.kind,
+        action,
+        changed,
+    });
+    if (input.sibling.acquire === 'none') {
+        return {
+            kind: 'complete',
+            status: 0,
+            diagnostics: [{
+                    severity: 'info',
+                    code: NONE_POSTURE[observation.kind].code,
+                    message: `acquire = "none", so setup leaves this path alone: ${NONE_POSTURE[observation.kind].found}`,
+                    target,
+                }],
+            result: result('report', false),
+        };
+    }
+    const declared = resolveLocalRemote(input.sibling.remote, siblingsRoot);
+    if (declared.kind === 'unresolvable')
+        return unresolvableRemoteRefusal(declared, 'declared', target);
+    const remote = declared.remote;
+    if (observation.kind === 'absent') {
+        if (input.sibling.acquire === 'manual') {
+            return {
+                kind: 'complete',
+                status: 0,
+                diagnostics: [{
+                        severity: 'warning',
+                        code: ENVIRONMENT_CODES.SETUP_MANUAL_MISSING,
+                        message: 'manual checkout is absent',
+                        target,
+                        fix: 'create the checkout, then run npx --no cockpit setup --config <your cockpit.toml> again',
+                    }],
+                result: result('report', false),
+            };
+        }
+        if (observation.missingParent) {
+            return refusal(ENVIRONMENT_CODES.SETUP_PARENT_MISSING, 'automatic checkout parent directory is absent', observation.missingParent);
+        }
+        const branch = input.sibling.branch ? ['--branch', input.sibling.branch] : [];
+        const checks = observation.filesystemChecks ?? fallbackChecks(observation, siblingsRoot, target);
+        return preview(result('clone', true), step(`setup:${input.sibling.slug}:clone`, [gitExecutable.canonicalPath, 'clone', ...branch, '--', remote, target], siblingsRoot, resolvedGitEnvironment, target, checks, gitExecutable));
+    }
+    if (observation.kind !== 'repository') {
+        return refusal(ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID, 'repository acquisition target exists but is not a repository', target);
+    }
+    const observedOrigin = observation.remotes?.origin;
+    const observedResolution = observedOrigin === undefined ? undefined : resolveLocalRemote(observedOrigin, siblingsRoot);
+    if (observedResolution?.kind === 'unresolvable')
+        return unresolvableRemoteRefusal(observedResolution, 'existing origin', target);
+    const current = observedResolution?.remote;
+    if (current === remote)
+        return { kind: 'complete', status: 0, diagnostics: [], result: result('report', false) };
+    if (input.sibling.acquire === 'auto') {
+        return refusal(ENVIRONMENT_CODES.SETUP_REMOTE_MISMATCH, current === undefined
+            ? 'existing automatic checkout has no origin remote'
+            : 'existing automatic checkout has a different origin remote', target);
+    }
+    const verb = current === undefined ? 'add' : 'set-url';
+    const checks = observation.filesystemChecks ?? fallbackChecks(observation, siblingsRoot, target);
+    return preview(result('wire-remote', true), step(`setup:${input.sibling.slug}:remote-${verb}`, [gitExecutable.canonicalPath, '-C', target, 'remote', verb, '--', 'origin', remote], siblingsRoot, resolvedGitEnvironment, target, checks, gitExecutable));
+}

package/dist/environment/sibling-checkouts.d.ts

@@ -0,0 +1,119 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import type { CockpitConfig, Sibling } from '../schema.js';
+import { type EnvironmentDiagnostic, type ExecutionStep } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+export declare const SIBLING_CHECKOUTS_PATH: string;
+/** Each overridden sibling's slug and the canonical absolute directory that serves it. */
+type SiblingCheckoutRecord = Readonly<Record<string, string>>;
+export type SiblingCheckoutRecordRead = Readonly<{
+    kind: 'complete';
+    checkouts: SiblingCheckoutRecord;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+/** The recorded overrides; none when nothing was recorded. A record cockpit did not write is refused, never ignored. */
+export declare function readSiblingCheckouts(cockpitRoot: string): Promise<SiblingCheckoutRecordRead>;
+export declare function writeSiblingCheckouts(cockpitRoot: string, checkouts: SiblingCheckoutRecord): Promise<{
+    readonly kind: 'complete';
+} | {
+    readonly kind: 'refusal';
+    readonly message: string;
+}>;
+export interface ServedSibling {
+    readonly slug: string;
+    /** Where cockpit.toml puts the checkout. */
+    readonly declared: string;
+    /** The checkout the stack, the guard and the health commands use. */
+    readonly served: string;
+    readonly overridden: boolean;
+}
+/** Every declared sibling with the directory that serves it; an override for an undeclared slug serves nothing. */
+export declare function servedSiblings(cockpitRoot: string, config: Readonly<{
+    cockpit: Readonly<{
+        siblings_root: string;
+    }>;
+    sibling: readonly Readonly<{
+        slug: string;
+        dir: string;
+    }>[];
+}>, checkouts: SiblingCheckoutRecord): ReadonlyMap<string, ServedSibling>;
+/** The directory serving a declared sibling; a slug the map lacks is a caller's error, named as one. */
+export declare function servedPath(served: ReadonlyMap<string, ServedSibling>, slug: string): string;
+type ServedSiblingsRead = Readonly<{
+    kind: 'complete';
+    siblings: ReadonlyMap<string, ServedSibling>;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+export declare function loadServedSiblings(cockpitRoot: string, config: Pick<CockpitConfig, 'cockpit' | 'sibling'>): Promise<ServedSiblingsRead>;
+/** The overridden siblings whose recorded directory is gone, such as a removed worktree. */
+export declare function vanishedServedCheckouts(served: ReadonlyMap<string, ServedSibling>): Promise<readonly ServedSibling[]>;
+export declare function vanishedCheckoutFix(slug: string): string;
+/**
+ * A refusal when an override names a directory that is gone. Docker creates a missing bind-mount
+ * source as an empty directory, so the stack would start on nothing. Preflight and doctor report
+ * the same fact as the served-checkouts observation row, so all three agree.
+ */
+export declare function missingServedCheckout(served: ReadonlyMap<string, ServedSibling>): Promise<EnvironmentDiagnostic | undefined>;
+/** The directory variables Compose interpolates: each sibling's `var` and the directory that serves it. */
+export declare function servedSiblingVariables(config: Pick<CockpitConfig, 'sibling'>, served: ReadonlyMap<string, ServedSibling>): Readonly<Record<string, string>>;
+type GitRun = Readonly<{
+    kind: 'complete';
+    stdout: string;
+}> | Readonly<{
+    kind: 'failed';
+    exitCode: number;
+    code: string;
+    detail: string;
+    stderr: string;
+}>;
+/**
+ * `stdoutLimitBytes` replaces the default bound, which keeps only the tail of longer output, with a
+ * hard one: output past it fails with EXECUTION_STDOUT_LIMIT instead of arriving in part.
+ */
+type GitRunOptions = Readonly<{
+    timeoutMs?: number;
+    stdoutLimitBytes?: number;
+}>;
+/** Runs one Git command in a checkout through the authenticated executor and returns its text. */
+export interface GitRunner {
+    readonly executable: ResolvedExecutable;
+    run(cwd: string, id: string, args: readonly string[], options?: GitRunOptions): Promise<GitRun>;
+}
+export declare const GIT_CHILD_CONFIG: readonly ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null'];
+export declare function createGitRunner(env: Readonly<Record<string, string | undefined>>, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<GitRunner | Readonly<{
+    unavailable: string;
+}>>;
+type SiblingCheckoutInspection = Readonly<{
+    kind: 'same-repository';
+    directory: string;
+    evidence: 'object-store' | 'remote';
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+/**
+ * Whether `candidate` is the root of a checkout of the sibling's repository: it shares the declared
+ * checkout's object store (a linked worktree), or its origin names the same repository as the
+ * declared checkout's origin or the declared remote. Anything else is refused: serving an unrelated
+ * repository under a sibling's name would hand its code the sibling's mounts and grants.
+ */
+export declare function inspectSiblingCheckout(input: Readonly<{
+    sibling: Pick<Sibling, 'slug' | 'remote'>;
+    declared: string;
+    candidate: string;
+    git: GitRunner;
+}>): Promise<SiblingCheckoutInspection>;
+/** The declared environment files the served checkout lacks; a fresh worktree has none of the ignored ones. */
+export declare function missingEnvironmentFiles(served: ServedSibling, sibling: Pick<Sibling, 'environment_files'>): Promise<readonly Readonly<{
+    template: string;
+    instance: string;
+}>[]>;
+/** One warning per environment file an overriding checkout lacks, naming who must create it and from what. */
+export declare function missingEnvironmentFileDiagnostics(served: ServedSibling, missing: readonly Readonly<{
+    template: string;
+    instance: string;
+}>[]): readonly EnvironmentDiagnostic[];
+export {};

package/dist/environment/sibling-checkouts.js

@@ -0,0 +1,254 @@
+/**
+ * Owns which checkout serves each sibling: the directory cockpit.toml declares under siblings_root,
+ * or another checkout of the same repository (a linked worktree, usually) that `cockpit use`
+ * recorded for this cockpit checkout alone. Mounts, the guard's allowed roots and the health
+ * commands all read the served directory from here, so they describe the same code.
+ *
+ * The record is machine-local, under `.cockpit/local`, never in cockpit.toml: a worktree path is
+ * one person's disk, and a committed one would point every other clone at a directory it lacks.
+ * Without it, an agent working on a branch in a sibling's worktree had the stack, the checks and
+ * every grade run against the main checkout's branch while reporting green.
+ */
+import { lstatIfPresent } from './presence.js';
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { readBoundedFile } from '../bounded-read.js';
+import { cockpitCommand, formatShellCommand } from '../fix-catalogue.js';
+import { GUARD_LOCAL_PATHS, writeCockpitLocalFiles } from '../guards/local-identity.js';
+import { ENVIRONMENT_CODES, errorCause, hasErrorCode, RefusalError, tryParseJson } from './contract.js';
+import { resolveGitExecutable } from './executable.js';
+import { repositoryIdentity } from './repository-identity.js';
+import { redactSensitiveMessage } from './sensitive.js';
+import { gitEnvironment } from './setup.js';
+const FORMAT = 'cockpit-sibling-checkouts/v1';
+const RECORD_NAME = 'sibling-checkouts';
+export const SIBLING_CHECKOUTS_PATH = `${GUARD_LOCAL_PATHS.directory}/${RECORD_NAME}`;
+const RECORD_MAX_BYTES = 65_536;
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+function canonicalDirectory(value) {
+    return typeof value === 'string' && isAbsolute(value) && normalize(value) === value && value !== '/'
+        && !value.endsWith('/') && !/[\x00-\x1f\x7f]/.test(value);
+}
+function recordRefusal(path, reason) {
+    return { kind: 'refusal', diagnostic: {
+            severity: 'error',
+            code: 'SIBLING_CHECKOUT_RECORD_INVALID',
+            message: `${path} is not a sibling checkout record cockpit wrote (${reason}), so cockpit cannot tell which checkout serves each sibling`,
+            target: SIBLING_CHECKOUTS_PATH,
+            fix: `delete ${path}, then run npx --no cockpit use <slug> <checkout> --config <your cockpit.toml> again for each sibling another checkout should serve`,
+        } };
+}
+/** The recorded overrides; none when nothing was recorded. A record cockpit did not write is refused, never ignored. */
+export async function readSiblingCheckouts(cockpitRoot) {
+    const path = join(cockpitRoot, SIBLING_CHECKOUTS_PATH);
+    let bytes;
+    try {
+        const read = readBoundedFile(path, RECORD_MAX_BYTES);
+        if (read.kind === 'too-large')
+            return recordRefusal(path, `it is larger than ${RECORD_MAX_BYTES} bytes`);
+        bytes = read.bytes;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return { kind: 'complete', checkouts: {} };
+        // ELOOP: a link at the last component; EISDIR: the reader's code for a file that is not regular.
+        if (hasErrorCode(error, 'ELOOP', 'EISDIR'))
+            return recordRefusal(path, 'it is not a plain file');
+        return recordRefusal(path, `it could not be read: ${errorCause(error)}`);
+    }
+    const value = tryParseJson(bytes.toString('utf8'));
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return recordRefusal(path, 'it is not a JSON object');
+    const record = value;
+    if (Object.keys(record).sort().join(',') !== 'checkouts,format' || record.format !== FORMAT) {
+        return recordRefusal(path, `it does not carry the ${FORMAT} format`);
+    }
+    const checkouts = record.checkouts;
+    if (checkouts === null || typeof checkouts !== 'object' || Array.isArray(checkouts)
+        || Object.entries(checkouts).some(([slug, directory]) => !SLUG.test(slug) || !canonicalDirectory(directory))) {
+        return recordRefusal(path, 'a slug or directory in it is malformed');
+    }
+    return { kind: 'complete', checkouts: Object.freeze({ ...checkouts }) };
+}
+export async function writeSiblingCheckouts(cockpitRoot, checkouts) {
+    const ordered = Object.fromEntries(Object.entries(checkouts).sort(([left], [right]) => left < right ? -1 : 1));
+    return writeCockpitLocalFiles(cockpitRoot, [{ name: RECORD_NAME, bytes: `${JSON.stringify({ format: FORMAT, checkouts: ordered })}\n` }]);
+}
+/** Every declared sibling with the directory that serves it; an override for an undeclared slug serves nothing. */
+export function servedSiblings(cockpitRoot, config, checkouts) {
+    const siblingsRoot = resolve(cockpitRoot, config.cockpit.siblings_root);
+    return new Map(config.sibling.map(sibling => {
+        const declared = resolve(siblingsRoot, sibling.dir);
+        const override = Object.hasOwn(checkouts, sibling.slug) ? checkouts[sibling.slug] : undefined;
+        return [sibling.slug, Object.freeze({ slug: sibling.slug, declared, served: override ?? declared, overridden: override !== undefined })];
+    }));
+}
+/** The directory serving a declared sibling; a slug the map lacks is a caller's error, named as one. */
+export function servedPath(served, slug) {
+    const entry = served.get(slug);
+    if (!entry)
+        throw new RefusalError(`sibling ${slug} has no served checkout; it is not declared in cockpit.toml`);
+    return entry.served;
+}
+export async function loadServedSiblings(cockpitRoot, config) {
+    const read = await readSiblingCheckouts(cockpitRoot);
+    return read.kind === 'complete' ? { kind: 'complete', siblings: servedSiblings(cockpitRoot, config, read.checkouts) } : read;
+}
+/** The overridden siblings whose recorded directory is gone, such as a removed worktree. */
+export async function vanishedServedCheckouts(served) {
+    const overridden = [...served.values()].filter(sibling => sibling.overridden);
+    const present = await Promise.all(overridden.map(async (sibling) => (await lstatIfPresent(sibling.served))?.isDirectory() === true));
+    return overridden.filter((_, index) => !present[index]);
+}
+export function vanishedCheckoutFix(slug) {
+    return `serve the declared checkout again with ${cockpitCommand('use', { operand: slug, args: '--clear' })}, or name another checkout of it`;
+}
+/**
+ * A refusal when an override names a directory that is gone. Docker creates a missing bind-mount
+ * source as an empty directory, so the stack would start on nothing. Preflight and doctor report
+ * the same fact as the served-checkouts observation row, so all three agree.
+ */
+export async function missingServedCheckout(served) {
+    const [sibling] = await vanishedServedCheckouts(served);
+    return sibling === undefined ? undefined : {
+        severity: 'error',
+        code: 'SIBLING_CHECKOUT_UNAVAILABLE',
+        message: `sibling ${sibling.slug} is recorded to be served from ${sibling.served}, which is no longer a directory`,
+        target: sibling.served,
+        fix: vanishedCheckoutFix(sibling.slug),
+    };
+}
+/** The directory variables Compose interpolates: each sibling's `var` and the directory that serves it. */
+export function servedSiblingVariables(config, served) {
+    return Object.fromEntries(config.sibling.map(sibling => [sibling.var, servedPath(served, sibling.slug)]));
+}
+// Repository-local `core.fsmonitor` and hooks run code on nearly any Git command. Agents cannot write under
+// `.git`, so this is defence in depth against a checkout whose configuration arrived some other way.
+export const GIT_CHILD_CONFIG = ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null'];
+// Global and system configuration can carry aliases, credential helpers and fsmonitor commands that
+// run code; cockpit's Git children read only the repository's own configuration, as setup's clone does.
+export async function createGitRunner(env, execute) {
+    const git = await resolveGitExecutable(env);
+    if (git.state !== 'available')
+        return { unavailable: git.reason };
+    const executable = git.value;
+    const environment = gitEnvironment(env);
+    return {
+        executable,
+        async run(cwd, id, args, { timeoutMs = 30_000, stdoutLimitBytes } = {}) {
+            const step = {
+                id, argv: [executable.canonicalPath, '-C', cwd, ...GIT_CHILD_CONFIG, ...args], argv0: executable.invocationPath,
+                cwd, env: environment, timeoutMs, stdoutLimitBytes: stdoutLimitBytes ?? 65_536, stderrLimitBytes: 65_536,
+                ...stdoutLimitBytes === undefined ? { outputOverflow: 'retain-tail' } : {},
+                paths: [], ports: [], labels: { purpose: id }, expected: [],
+                consumedFiles: [{ path: executable.canonicalPath, sha256: executable.sha256, maxBytes: 536_870_912,
+                        argvIndexes: [0], executable: true, executionMode: executable.executionMode }],
+                filesystemChecks: [], compensation: [],
+            };
+            const outcome = authenticatedExecutionOutcome(await execute(step), step);
+            if (!outcome)
+                return { kind: 'failed', exitCode: -1, code: 'unauthenticated', detail: 'the execution outcome could not be authenticated', stderr: '' };
+            const text = (bytes) => new TextDecoder('utf-8', { fatal: false }).decode(bytes).trim();
+            if (outcome.kind === 'complete')
+                return { kind: 'complete', stdout: text(outcome.stdout) };
+            // Git's last line names the cause (an unreachable host, a file a merge would overwrite); a
+            // remote URL in it may carry credentials, and a line that cannot be redacted is withheld.
+            const line = text(outcome.stderr).replace(/(\w+:\/\/)[^/@\s]+@/g, '$1[redacted]@').split('\n').filter(Boolean).at(-1);
+            const cause = line === undefined ? undefined : redactSensitiveMessage(line.slice(0, 240));
+            return { kind: 'failed', exitCode: outcome.execution.exitCode, code: outcome.code,
+                detail: cause ? `${outcome.code}: ${cause}` : outcome.code, stderr: text(outcome.stderr) };
+        },
+    };
+}
+async function checkoutIdentity(git, directory) {
+    const located = await git.run(directory, 'checkout:identity', ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir']);
+    if (located.kind !== 'complete')
+        return { reason: `it is not a Git checkout (${located.detail})` };
+    const [toplevel, commonDirectory] = located.stdout.split('\n');
+    if (!toplevel || !commonDirectory)
+        return { reason: 'Git did not name its working tree and object store' };
+    const origin = await git.run(directory, 'checkout:origin', ['config', '--get', 'remote.origin.url']);
+    const identity = origin.kind === 'complete' ? repositoryIdentity(origin.stdout) : undefined;
+    try {
+        return {
+            toplevel: await realpath(toplevel), commonDirectory: await realpath(commonDirectory),
+            origin: identity?.kind === 'known' ? identity.identity : undefined,
+        };
+    }
+    catch (error) {
+        return { reason: `the working tree or object store Git named cannot be resolved (${errorCause(error)})` };
+    }
+}
+function sameIdentity(left, right) {
+    return left.host === right.host && left.owner.toLowerCase() === right.owner.toLowerCase()
+        && left.repository.toLowerCase() === right.repository.toLowerCase();
+}
+function spelled(identity) {
+    return identity === undefined ? 'no recognisable origin remote' : `${identity.host}/${identity.owner}/${identity.repository}`;
+}
+/**
+ * Whether `candidate` is the root of a checkout of the sibling's repository: it shares the declared
+ * checkout's object store (a linked worktree), or its origin names the same repository as the
+ * declared checkout's origin or the declared remote. Anything else is refused: serving an unrelated
+ * repository under a sibling's name would hand its code the sibling's mounts and grants.
+ */
+export async function inspectSiblingCheckout(input) {
+    const unavailable = (message, fix) => ({ kind: 'refusal', diagnostic: {
+            severity: 'error', code: 'SIBLING_CHECKOUT_UNAVAILABLE',
+            message, target: input.candidate, fix,
+        } });
+    const listWorktrees = `list the checkouts of ${input.sibling.slug} with git -C ${input.declared} worktree list, and name one of them`;
+    let directory;
+    try {
+        directory = await realpath(input.candidate);
+        if (!(await lstat(directory)).isDirectory())
+            return unavailable(`${input.candidate} is not a directory`, listWorktrees);
+    }
+    catch (error) {
+        return unavailable(`${input.candidate} cannot be resolved (${errorCause(error)})`, listWorktrees);
+    }
+    // The guard admits an agent's `use` by the path as written; a link in it, swapped in after that
+    // check, would record and then grant a directory the agent was never allowed to reach.
+    if (directory !== input.candidate) {
+        return unavailable(`${input.candidate} reaches ${directory} through a symbolic link, so cockpit will not record it`, `name the directory itself: ${cockpitCommand('use', { operand: input.sibling.slug, args: formatShellCommand([directory]) })}`);
+    }
+    const [candidate, declared] = await Promise.all([checkoutIdentity(input.git, directory), checkoutIdentity(input.git, input.declared)]);
+    if ('reason' in candidate)
+        return unavailable(`${directory} cannot serve sibling ${input.sibling.slug}: ${candidate.reason}`, listWorktrees);
+    if (candidate.toplevel !== directory) {
+        return unavailable(`${directory} is inside the checkout at ${candidate.toplevel}, not its root, so the stack would mount part of a checkout`, `name the checkout's root: ${cockpitCommand('use', { operand: input.sibling.slug, args: formatShellCommand([candidate.toplevel]) })}`);
+    }
+    if (!('reason' in declared) && declared.commonDirectory === candidate.commonDirectory) {
+        return { kind: 'same-repository', directory, evidence: 'object-store' };
+    }
+    // The declared checkout may track a fork while cockpit.toml's remote names the upstream; either counts.
+    const declaredRemote = input.sibling.remote === undefined ? undefined : repositoryIdentity(input.sibling.remote);
+    const expected = [...!('reason' in declared) && declared.origin !== undefined ? [declared.origin] : [],
+        ...declaredRemote?.kind === 'known' ? [declaredRemote.identity] : []];
+    if (candidate.origin !== undefined && expected.some(identity => sameIdentity(identity, candidate.origin))) {
+        return { kind: 'same-repository', directory, evidence: 'remote' };
+    }
+    return { kind: 'refusal', diagnostic: {
+            severity: 'error', code: 'SIBLING_CHECKOUT_FOREIGN',
+            message: `${directory} is not a checkout of sibling ${input.sibling.slug}: it shares no object store with ${input.declared}, `
+                + `and its origin (${spelled(candidate.origin)}) is not the sibling's (${expected.length === 0 ? 'none known' : expected.map(spelled).join(' or ')})`,
+            target: input.candidate,
+            fix: `create a worktree of the sibling with git -C ${input.declared} worktree add <path> <branch> and name that path, or ${listWorktrees}`,
+        } };
+}
+/** The declared environment files the served checkout lacks; a fresh worktree has none of the ignored ones. */
+export async function missingEnvironmentFiles(served, sibling) {
+    const present = await Promise.all((sibling.environment_files ?? []).map(async (file) => await lstatIfPresent(join(served.served, file.instance)) !== undefined));
+    return (sibling.environment_files ?? []).filter((_, index) => !present[index]).map(file => ({ template: file.template, instance: file.instance }));
+}
+/** One warning per environment file an overriding checkout lacks, naming who must create it and from what. */
+export function missingEnvironmentFileDiagnostics(served, missing) {
+    return missing.map(file => ({
+        severity: 'warning',
+        code: 'SIBLING_ENVIRONMENT_FILE_MISSING',
+        message: `sibling ${served.slug} is served from ${served.served}, which has no ${file.instance}; the services that read it would start without its settings`,
+        target: join(served.served, file.instance),
+        fix: `a person creates ${join(served.served, file.instance)} from the template ${join(served.served, file.template)}, or copies the one in ${served.declared}; cockpit never copies environment files between checkouts`,
+    }));
+}

package/dist/environment/sibling-instructions.d.ts

@@ -0,0 +1,33 @@
+import { type EnvironmentDiagnostic } from './contract.js';
+/**
+ * One warning for each way a repository's root instruction files leave a listed agent tool without
+ * them. A team that uses only Claude Code loses nothing when a repository keeps CLAUDE.md alone.
+ */
+export declare function inspectSiblingInstructions(repository: Readonly<{
+    slug: string;
+    root: string;
+}>, tools: readonly string[]): Promise<readonly EnvironmentDiagnostic[]>;
+export type SiblingInstructionFilesChange = 'claude-import' | 'move-to-agents';
+export type SiblingInstructionFilesResult = Readonly<{
+    kind: 'none';
+    root: string;
+}> | Readonly<{
+    kind: 'offered' | 'written';
+    root: string;
+    change: SiblingInstructionFilesChange;
+}> | Readonly<{
+    kind: 'refusal';
+    root: string;
+    reason: string;
+}>;
+/**
+ * Makes AGENTS.md the file every tool loads and CLAUDE.md the import Claude Code needs, in the two
+ * cases that need no judgement: AGENTS.md alone gains a CLAUDE.md reading `@AGENTS.md`, and CLAUDE.md
+ * alone, when it imports nothing of its own, moves byte for byte to AGENTS.md and becomes that import.
+ * Without `write` it only reports the change. It writes only ordinary files directly in a canonical
+ * root, never through a link, and refuses when a file changed after it was read.
+ */
+export declare function synchronizeSiblingInstructionFiles(input: Readonly<{
+    siblingRoot: string;
+    write: boolean;
+}>): Promise<SiblingInstructionFilesResult>;