@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/instruction-pointer.js

@@ -0,0 +1,144 @@
+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 { basename, dirname, join, relative, sep } from 'node:path';
+import { readBoundedInput } from '../config/load.js';
+import { errorCause, hasErrorCode } from './contract.js';
+const BEGIN = '<!-- cockpit:instruction-pointer:start -->';
+const END = '<!-- cockpit:instruction-pointer:end -->';
+export const INSTRUCTION_POINTER_MARKERS = Object.freeze({ begin: BEGIN, end: END });
+function block(target) {
+    const destination = target.split('/').map(segment => encodeURIComponent(segment)).join('/');
+    return `${BEGIN}\nRead [the cockpit instructions](<${destination}>) before editing this repository.\n${END}`;
+}
+async function syncDirectory(path) {
+    const directory = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+/** Appends one bounded marked block; bytes outside that block always remain product-owned. */
+export async function synchronizeInstructionPointer(input) {
+    const path = join(input.siblingRoot, 'AGENTS.md');
+    try {
+        const [cockpitRoot, siblingRoot] = await Promise.all([realpath(input.cockpitRoot), realpath(input.siblingRoot)]);
+        if (cockpitRoot !== input.cockpitRoot || siblingRoot !== input.siblingRoot) {
+            return { kind: 'refusal', path, reason: 'instruction pointer roots must be canonical directories without symlink redirects' };
+        }
+        const directories = new Map();
+        for (const root of [cockpitRoot, siblingRoot]) {
+            for (let parent = root;; parent = dirname(parent)) {
+                const status = await lstat(parent);
+                if (!status.isDirectory() || status.isSymbolicLink())
+                    return { kind: 'refusal', path, reason: 'instruction pointer ancestry is not ordinary directories' };
+                directories.set(parent, { dev: status.dev, ino: status.ino });
+                if (dirname(parent) === parent)
+                    break;
+                if (directories.size > 128)
+                    return { kind: 'refusal', path, reason: 'instruction pointer ancestry exceeds the verification bound' };
+            }
+        }
+        const directoriesCurrent = async () => {
+            for (const [directory, expected] of directories) {
+                const current = await lstat(directory);
+                if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== expected.dev || current.ino !== expected.ino)
+                    return false;
+            }
+            return true;
+        };
+        if (cockpitRoot === siblingRoot) {
+            return { kind: 'refusal', path, reason: 'instruction pointer roots are not distinct ordinary directories' };
+        }
+        const target = relative(siblingRoot, join(cockpitRoot, 'AGENTS.md')).split(sep).join('/');
+        if (target.length === 0 || target.startsWith('/'))
+            return { kind: 'refusal', path, reason: 'instruction pointer target is not relative' };
+        const desired = block(target);
+        let before;
+        try {
+            before = await lstat(path);
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                throw error;
+        }
+        if (before?.isSymbolicLink() || before && !before.isFile())
+            return { kind: 'refusal', path, reason: 'AGENTS.md is not an ordinary file' };
+        const read = before ? await readBoundedInput(path) : undefined;
+        if (before && read?.kind !== 'complete')
+            return { kind: 'refusal', path, reason: 'AGENTS.md could not be read as bounded UTF-8 input' };
+        const original = read?.kind === 'complete' ? new TextDecoder('utf-8', { fatal: true }).decode(read.bytes) : '';
+        const starts = original.split(BEGIN).length - 1;
+        const ends = original.split(END).length - 1;
+        if (starts !== ends || starts > 1)
+            return { kind: 'refusal', path, reason: 'instruction pointer markers are partial or duplicated' };
+        if (starts === 1) {
+            const start = original.indexOf(BEGIN);
+            const end = original.indexOf(END, start) + END.length;
+            if (original.slice(start, end) !== desired)
+                return { kind: 'refusal', path, reason: 'the existing instruction pointer was edited' };
+            return { kind: 'unchanged', path, target };
+        }
+        if (!input.write)
+            return { kind: 'offered', path, target };
+        if (!await directoriesCurrent())
+            return { kind: 'refusal', path, reason: 'instruction pointer roots changed before writing' };
+        const next = `${original}${original.length === 0 || original.endsWith('\n') ? '' : '\n'}${desired}\n`;
+        const originalSha256 = read?.kind === 'complete' ? sha256Hex(read.bytes) : undefined;
+        if (before) {
+            const temporary = join(dirname(path), `.${basename(path)}.cockpit-pointer-${randomBytes(8).toString('hex')}`);
+            let temporaryCreated = false;
+            try {
+                const temporaryHandle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, Number(before.mode) & 0o777);
+                temporaryCreated = true;
+                try {
+                    await temporaryHandle.writeFile(next);
+                    await temporaryHandle.sync();
+                }
+                finally {
+                    await temporaryHandle.close();
+                }
+                if (!await directoriesCurrent())
+                    return { kind: 'refusal', path, reason: 'instruction pointer roots changed before publication' };
+                const current = await lstat(path);
+                const reread = await readBoundedInput(path);
+                if (current.dev !== before.dev || current.ino !== before.ino || current.size !== before.size
+                    || current.mtimeMs !== before.mtimeMs || reread.kind !== 'complete' || sha256Hex(reread.bytes) !== originalSha256) {
+                    return { kind: 'refusal', path, reason: 'AGENTS.md changed before the pointer could be written' };
+                }
+                await rename(temporary, path);
+                temporaryCreated = false;
+            }
+            finally {
+                if (temporaryCreated)
+                    await unlink(temporary);
+            }
+        }
+        else {
+            if (!await directoriesCurrent())
+                return { kind: 'refusal', path, reason: 'instruction pointer roots changed before publication' };
+            const destination = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+            try {
+                await destination.writeFile(next);
+                await destination.sync();
+            }
+            finally {
+                await destination.close();
+            }
+        }
+        await syncDirectory(dirname(path));
+        if (!await directoriesCurrent())
+            return { kind: 'refusal', path, reason: 'instruction pointer roots changed during publication' };
+        const written = await readBoundedInput(path);
+        if (written.kind !== 'complete' || written.bytes.toString('utf8') !== next) {
+            return { kind: 'refusal', path, reason: 'instruction pointer postcheck failed' };
+        }
+        return { kind: 'written', path, target };
+    }
+    catch (error) {
+        return { kind: 'refusal', path, reason: errorCause(error) };
+    }
+}

package/dist/environment/lifecycle-composition.d.ts

@@ -0,0 +1,29 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type LifecycleRunContext, type ReadinessRefusal, type RuntimeReadinessPurpose, type SleepCommandAdapters, type UpCommandAdapters } from './application/lifecycle-context.js';
+import { type HolderProcess } from './claims.js';
+import { type ExecutionStep } from './contract.js';
+import { type PortLeaseProjection } from './ports.js';
+import { type RuntimeMeasurementProbeAuthority, type RuntimeLifecycleProjection, type RuntimeTopologyEvidence } from './runtime.js';
+export interface LifecycleCommandCompositionInput {
+    readonly configPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly sessionId: string;
+    readonly timeoutMs: number;
+    readonly activeProfiles?: readonly string[];
+    readonly runtimeMeasurementProbeAuthority?: RuntimeMeasurementProbeAuthority | (() => RuntimeMeasurementProbeAuthority);
+    readonly holderProcess?: HolderProcess;
+}
+export type LifecycleCommandAdapterComposition = Omit<UpCommandAdapters & SleepCommandAdapters, 'withRuntimeReadiness' | 'seed'> & {
+    seed: NonNullable<UpCommandAdapters['seed']>;
+    withMachineFloorReadiness<T>(context: LifecycleRunContext, use: (observations: readonly import('./contract.js').EnvironmentObservation[]) => Promise<T>, refuse?: ReadinessRefusal<T>): Promise<T | undefined>;
+    withRuntimeReadiness<T>(context: LifecycleRunContext, use: (runtime: LifecycleRuntimeReadiness) => Promise<T>, ports?: PortLeaseProjection, refuse?: ReadinessRefusal<T>, purpose?: RuntimeReadinessPurpose): Promise<T | undefined>;
+};
+interface LifecycleRuntimeReadiness {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly lifecycle: RuntimeLifecycleProjection;
+    readonly hostObservations: readonly import('./contract.js').EnvironmentObservation[];
+    readonly runtimeObservations: readonly import('./contract.js').EnvironmentObservation[];
+    readonly inputs: Readonly<Record<string, string>>;
+}
+export declare function createLifecycleCommandAdapters(rawInput: LifecycleCommandCompositionInput, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): LifecycleCommandAdapterComposition;
+export {};