@b00dea/cockpit 0.0.0-stage → 0.1.0

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-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>;

package/dist/environment/sibling-instructions.js

@@ -0,0 +1,224 @@
+// Which root instruction files each agent tool loads in a repository, measured 2026-11-03 by asking
+// each tool for words only a file it had loaded could tell it, beside a decoy file it must not load:
+// Codex 0.166.0 and OpenCode 1.19.5 loaded AGENTS.md; Claude Code 2.1.317 loaded only CLAUDE.md (its
+// built-in AGENTS.md reader is an option user settings can turn on and project settings cannot). With
+// no AGENTS.md, OpenCode fell back to CLAUDE.md and Codex loaded nothing. None of the three loaded
+// .cursorrules, .cursor/rules, GEMINI.md, .github/copilot-instructions.md or .windsurfrules. So a
+// repository's instructions reach every tool alike only when AGENTS.md holds them and CLAUDE.md
+// imports it; anything else leaves some tool without them.
+import { randomBytes } from 'node:crypto';
+import { sha256Hex } from '../sha256.js';
+import { constants } from 'node:fs';
+import { lstat, open, realpath, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readBoundedInput } from '../config/load.js';
+import { ENVIRONMENT_CODES, errorCause, isMissing, RefusalError } from './contract.js';
+const CLAUDE_IMPORT = '@AGENTS.md\n';
+const TOOL_ONLY_FILES = ['.cursorrules', '.cursor/rules', 'GEMINI.md', '.github/copilot-instructions.md', '.windsurfrules'];
+async function readInstructionFile(path) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { kind: 'absent' };
+        throw error;
+    }
+    // A link is read where it resolves, so CLAUDE.md linked to AGENTS.md counts as one file.
+    const real = await realpath(path);
+    const read = await readBoundedInput(real);
+    if (read.kind !== 'complete')
+        throw new RefusalError(`${path} is larger than cockpit reads`);
+    return { kind: 'present', real, bytes: read.bytes, text: new TextDecoder('utf-8', { fatal: true }).decode(read.bytes) };
+}
+async function classify(root) {
+    const agents = await readInstructionFile(join(root, 'AGENTS.md'));
+    const claude = await readInstructionFile(join(root, 'CLAUDE.md'));
+    // Claude Code resolves `@path` at the start of a line or after whitespace; an email address has neither.
+    const claudeImports = claude.kind === 'present' && /(^|\s)@\S/.test(claude.text);
+    if (agents.kind === 'absent')
+        return { state: claude.kind === 'absent' ? 'neither' : 'claude-only', claudeImports, agents, claude };
+    if (claude.kind === 'absent')
+        return { state: 'agents-only', claudeImports, agents, claude };
+    const linked = claude.real === agents.real || /^[ \t]*@(\.\/)?AGENTS\.md[ \t]*$/m.test(claude.text);
+    return { state: linked ? 'linked' : 'unlinked', claudeImports, agents, claude };
+}
+/**
+ * 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 async function inspectSiblingInstructions(repository, tools) {
+    const claude = tools.includes('claudecode');
+    // OpenCode falls back to CLAUDE.md when AGENTS.md is absent; Codex does not.
+    const agentsReaders = tools.includes('codexcli') || tools.includes('opencode');
+    const target = `sibling:${repository.slug}`;
+    const findings = [];
+    let classified;
+    const toolOnly = [];
+    try {
+        classified = await classify(repository.root);
+        for (const name of TOOL_ONLY_FILES) {
+            try {
+                await lstat(join(repository.root, name));
+                toolOnly.push(name);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+    }
+    catch (error) {
+        return [{
+                severity: 'warning',
+                code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `which agent tools load the instructions of sibling ${repository.slug} could not be checked: ${errorCause(error)}`,
+                target,
+                fix: `make the instruction files at the root of ${repository.root} readable UTF-8 files, then rerun this command`,
+            }];
+    }
+    if (classified.state === 'agents-only' && claude)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_AGENTS_ONLY',
+            message: `sibling ${repository.slug} has AGENTS.md but no CLAUDE.md, so Claude Code started there loads none of its instructions`,
+            target,
+            fix: 'run npx --no cockpit setup --config <your cockpit.toml> to see the CLAUDE.md it proposes (one line, @AGENTS.md); once a person approves it, run npx --no cockpit setup --config <your cockpit.toml> --write-instruction-files',
+        });
+    if (classified.state === 'claude-only' && tools.includes('codexcli'))
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_CLAUDE_ONLY',
+            message: `sibling ${repository.slug} has CLAUDE.md but no AGENTS.md, so Codex started there loads none of its instructions`
+                + (classified.claudeImports ? '; CLAUDE.md imports other files with @, which only Claude Code follows, so setup proposes no move' : ''),
+            target,
+            fix: 'run npx --no cockpit setup --config <your cockpit.toml> to see the move it proposes (CLAUDE.md copied byte for byte to AGENTS.md, CLAUDE.md replaced by @AGENTS.md) and, once a person approves it, rerun it with --write-instruction-files; when CLAUDE.md imports other files with @, setup proposes nothing and a person moves the shared instructions into AGENTS.md by hand',
+        });
+    if (classified.state === 'unlinked' && claude && agentsReaders)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_UNLINKED',
+            message: `sibling ${repository.slug} has both AGENTS.md and CLAUDE.md, but CLAUDE.md does not import AGENTS.md, so Claude Code loads only CLAUDE.md and Codex only AGENTS.md`,
+            target,
+            fix: 'a person merges the instructions every tool needs into AGENTS.md, then makes CLAUDE.md a line reading @AGENTS.md followed only by instructions that apply to Claude Code alone',
+        });
+    if (classified.state === 'neither')
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_MISSING',
+            message: `sibling ${repository.slug} has neither AGENTS.md nor CLAUDE.md, so no agent tool started there loads instructions for it`,
+            target,
+            fix: 'a person writes AGENTS.md with what an agent must know to work in the repository, then runs npx --no cockpit setup --config <your cockpit.toml> --write-instruction-files to add the CLAUDE.md that imports it',
+        });
+    if (toolOnly.length > 0)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_TOOL_ONLY',
+            message: `sibling ${repository.slug} keeps instructions in ${toolOnly.join(', ')}, which Claude Code, Codex and OpenCode do not load`,
+            target,
+            fix: 'a person moves the instructions every tool needs from those files into AGENTS.md, and keeps only settings specific to one tool where they are',
+        });
+    return findings;
+}
+async function createExclusive(path, bytes, mode) {
+    const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncDirectory(path) {
+    const directory = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+async function holds(path, expected) {
+    const read = await readBoundedInput(path);
+    return read.kind === 'complete' && Buffer.from(read.bytes).equals(Buffer.from(expected));
+}
+/**
+ * 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 async function synchronizeSiblingInstructionFiles(input) {
+    const root = input.siblingRoot;
+    const agentsPath = join(root, 'AGENTS.md');
+    const claudePath = join(root, 'CLAUDE.md');
+    let created;
+    try {
+        if (await realpath(root) !== root)
+            return { kind: 'refusal', root, reason: 'the sibling root must be a canonical directory without symlink redirects' };
+        const classified = await classify(root);
+        const change = classified.state === 'agents-only' ? 'claude-import'
+            : classified.state === 'claude-only' && !classified.claudeImports ? 'move-to-agents' : undefined;
+        if (!change)
+            return { kind: 'none', root };
+        const before = await lstat(change === 'claude-import' ? agentsPath : claudePath);
+        if (!before.isFile())
+            return { kind: 'refusal', root, reason: `${change === 'claude-import' ? 'AGENTS.md' : 'CLAUDE.md'} is not an ordinary file` };
+        if (!input.write)
+            return { kind: 'offered', root, change };
+        if (change === 'claude-import') {
+            await createExclusive(claudePath, CLAUDE_IMPORT, 0o644);
+            created = claudePath;
+        }
+        else {
+            const original = classified.claude.kind === 'present' ? classified.claude.bytes : new Uint8Array();
+            await createExclusive(agentsPath, original, Number(before.mode) & 0o777);
+            created = agentsPath;
+            const temporary = join(root, `.CLAUDE.md.cockpit-instructions-${randomBytes(8).toString('hex')}`);
+            try {
+                await createExclusive(temporary, CLAUDE_IMPORT, Number(before.mode) & 0o777);
+                const current = await lstat(claudePath);
+                const reread = await readBoundedInput(claudePath);
+                if (!current.isFile() || current.dev !== before.dev || current.ino !== before.ino || current.size !== before.size
+                    || current.mtimeMs !== before.mtimeMs || reread.kind !== 'complete' || sha256Hex(reread.bytes) !== sha256Hex(original)) {
+                    throw new RefusalError('CLAUDE.md changed before it could be replaced');
+                }
+                await rename(temporary, claudePath);
+            }
+            finally {
+                await unlink(temporary).catch((cleanup) => { if (!isMissing(cleanup))
+                    throw cleanup; });
+            }
+        }
+        // From here the instructions live only in what was written; nothing is undone any more.
+        created = undefined;
+        await syncDirectory(root);
+        if (!await holds(claudePath, CLAUDE_IMPORT))
+            return { kind: 'refusal', root, reason: 'CLAUDE.md does not hold the import after writing' };
+        if (change === 'move-to-agents' && !await holds(agentsPath, classified.claude.kind === 'present' ? classified.claude.bytes : '')) {
+            return { kind: 'refusal', root, reason: 'AGENTS.md does not hold the moved instructions after writing' };
+        }
+        return { kind: 'written', root, change };
+    }
+    catch (error) {
+        // A file this run created is removed when the change could not complete, so a half-made move
+        // never leaves two copies of the instructions that can drift apart.
+        if (created) {
+            try {
+                await unlink(created);
+            }
+            catch (cleanup) {
+                if (!isMissing(cleanup))
+                    return { kind: 'refusal', root, reason: `${errorCause(error)}; ${created} could not be removed: ${errorCause(cleanup)}` };
+            }
+        }
+        return { kind: 'refusal', root, reason: errorCause(error) };
+    }
+}

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

@@ -0,0 +1,45 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import type { Diagnostic } from '../diagnostics.js';
+import { type ExecutionStep } from './contract.js';
+export interface SiblingAddInput {
+    readonly configPath: string;
+    readonly slug: string;
+    readonly create: boolean;
+    readonly from?: string;
+    readonly remote?: string;
+    readonly dir?: string;
+    readonly purpose?: string;
+    readonly varName?: string;
+    /** How the stack uses the checkout; defaulted from the declared runtime when absent. */
+    readonly mount?: string;
+    readonly instructionPointer?: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface SiblingRemoveInput {
+    readonly configPath: string;
+    readonly slug: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface SiblingDependencies {
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}
+export interface SiblingOutcome {
+    readonly status: number;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly artifact?: string | null;
+    readonly destination?: string | null;
+}
+export type GitRepositoryInitializationOutcome = Readonly<{
+    kind: 'complete';
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+}>;
+/** Initialises one local repository through the authenticated process seam used by sibling creation. */
+export declare function initializeLocalGitRepository(input: Readonly<{
+    path: string;
+    env: Readonly<Record<string, string | undefined>>;
+}>, dependencies: SiblingDependencies): Promise<GitRepositoryInitializationOutcome>;
+export declare function runSiblingAdd(input: SiblingAddInput, dependencies: SiblingDependencies): Promise<SiblingOutcome>;
+export declare function runSiblingRemove(input: SiblingRemoveInput): Promise<SiblingOutcome>;