@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment-exec/libexec-program.d.ts

@@ -0,0 +1,6 @@
+export interface LibexecProgram {
+    readonly path: string;
+    readonly sha256: string;
+    readonly maxBytes: number;
+}
+export declare function libexecProgram(name: string): LibexecProgram;

package/dist/environment-exec/libexec-program.js

@@ -0,0 +1,22 @@
+// Locates and fingerprints the programs cockpit ships in packages/cockpit/libexec/. A step that runs
+// one lists it as a consumed file with this digest, so the executor runs a private snapshot of exactly
+// the bytes hashed here and refuses a program edited or replaced in between. The snapshot runs outside
+// libexec/, so a program launched this way must not require its sibling files.
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { RefusalError, errorCause } from '../environment/contract.js';
+import { readBoundedFile } from '../bounded-read.js';
+const PROGRAM_MAX_BYTES = 1_048_576;
+export function libexecProgram(name) {
+    const path = fileURLToPath(new URL(`../../libexec/${name}`, import.meta.url));
+    try {
+        const read = readBoundedFile(path, PROGRAM_MAX_BYTES);
+        if (read.kind !== 'complete')
+            throw new RefusalError(`larger than ${PROGRAM_MAX_BYTES} bytes`);
+        return { path, sha256: createHash('sha256').update(read.bytes).digest('hex'), maxBytes: PROGRAM_MAX_BYTES };
+    }
+    catch (error) {
+        throw new RefusalError(`cockpit's bundled program ${path} cannot be authenticated (${errorCause(error)}); `
+            + 'cockpit runs only bundled programs whose bytes it hashed — fix: reinstall @b00dea/cockpit', { cause: error });
+    }
+}

package/dist/environment-exec/verified-digest.d.ts

@@ -0,0 +1,4 @@
+import type { Stats } from 'node:fs';
+export declare function fileFingerprint(path: string, status: Pick<Stats, 'dev' | 'ino' | 'size' | 'mode' | 'mtimeMs' | 'ctimeMs'>): string;
+export declare function recordVerifiedDigest(fingerprint: string, sha256: string): void;
+export declare function verifiedDigest(fingerprint: string): string | undefined;

package/dist/environment-exec/verified-digest.js

@@ -0,0 +1,16 @@
+const MAX_ENTRIES = 64;
+const verified = new Map();
+export function fileFingerprint(path, status) {
+    return JSON.stringify([path, status.dev, status.ino, status.size, status.mode, status.mtimeMs, status.ctimeMs]);
+}
+export function recordVerifiedDigest(fingerprint, sha256) {
+    if (!/^[a-f0-9]{64}$/.test(sha256))
+        throw new TypeError('verified digest must be a SHA-256 hex string');
+    verified.delete(fingerprint);
+    verified.set(fingerprint, sha256);
+    if (verified.size > MAX_ENTRIES)
+        verified.delete(verified.keys().next().value);
+}
+export function verifiedDigest(fingerprint) {
+    return verified.get(fingerprint);
+}

package/dist/exact-keys.d.ts

@@ -0,0 +1,7 @@
+/** True when `value` has every `required` own enumerable key and no key outside `required` and `optional`. */
+export declare function exactKeys(value: object, required: readonly string[], optional?: readonly string[]): boolean;
+/**
+ * The same check over every own key, enumerable or not, refusing symbol keys and accessors. Envelopes a
+ * caller hands back are checked this way, so that reading them later invokes nothing the caller planted.
+ */
+export declare function exactOwnKeys(value: object, required: readonly string[]): boolean;

package/dist/exact-keys.js

@@ -0,0 +1,15 @@
+/** True when `value` has every `required` own enumerable key and no key outside `required` and `optional`. */
+export function exactKeys(value, required, optional = []) {
+    const keys = Object.keys(value);
+    return required.every((key) => keys.includes(key)) && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+/**
+ * The same check over every own key, enumerable or not, refusing symbol keys and accessors. Envelopes a
+ * caller hands back are checked this way, so that reading them later invokes nothing the caller planted.
+ */
+export function exactOwnKeys(value, required) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Reflect.ownKeys(descriptors);
+    return keys.every((key) => typeof key === 'string' && 'value' in descriptors[key] && required.includes(key))
+        && required.every((key) => keys.includes(key));
+}

package/dist/fix-catalogue.d.ts

@@ -0,0 +1,32 @@
+import type { Diagnostic } from './environment/contract.js';
+export type ConfiguredCommand = 'setup' | 'sync' | 'check' | 'confirm' | 'selftest' | 'upgrade' | 'up' | 'sleep' | 'session' | 'down' | 'reset' | 'preflight' | 'doctor' | 'logs' | 'runtime measure' | 'sibling add' | 'sibling remove' | 'stacks' | 'stacks prune' | 'docs check' | 'use' | 'pull';
+export interface FixContext {
+    readonly resolvedConfigPath: string | null;
+    readonly generatedTargets: readonly string[];
+}
+export interface ExecutableFix {
+    readonly argv: readonly ['npx', '--no', 'cockpit', 'sync', '--config', string];
+    readonly command: string;
+}
+export declare function formatShellCommand(argv: readonly string[]): string;
+/**
+ * The runnable spelling of a cockpit command. `operand` (a sibling slug) precedes --config as in
+ * the command's usage line; `args` follows it as written, so it may hold `<placeholders>`.
+ */
+export declare function cockpitCommand(command: ConfiguredCommand, options?: Readonly<{
+    config?: string;
+    operand?: string;
+    args?: string;
+}>): string;
+/**
+ * The runnable spelling of init, which takes its root operand and --target instead of --config.
+ * A root or target the producer does not know prints as a placeholder for the reader to fill in.
+ */
+export declare function initCommand(options?: Readonly<{
+    root?: string;
+    target?: string;
+    args?: string;
+}>): string;
+/** Replaces the configuration placeholder in printed text with the resolved path, shell-quoted. */
+export declare function bindConfigPath(text: string, context?: FixContext): string;
+export declare function admitDiagnosticFix(diagnostic: Diagnostic, context?: FixContext): ExecutableFix | undefined;

package/dist/fix-catalogue.js

@@ -0,0 +1,60 @@
+import { dirname, isAbsolute, normalize } from 'node:path';
+// A printed command has to run as printed. Nothing goes in front of npx: the guard asks before a
+// wrapped command such as `env -u NAME …`, and Codex and OpenCode treat an ask as a denial. Every
+// configured command refuses without --config, so a remedy written where the path is unknown names
+// this placeholder, and bindConfigPath replaces it with the resolved path wherever the command line
+// supplied one.
+const CONFIG_PLACEHOLDER = '<your cockpit.toml>';
+const unsafeControl = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/;
+const plainShellArgument = /^[A-Za-z0-9_@%+=:,./-]+$/;
+export function formatShellCommand(argv) {
+    return argv.map((argument) => plainShellArgument.test(argument)
+        ? argument
+        : `'${argument.replaceAll("'", "'\"'\"'")}'`).join(' ');
+}
+/**
+ * The runnable spelling of a cockpit command. `operand` (a sibling slug) precedes --config as in
+ * the command's usage line; `args` follows it as written, so it may hold `<placeholders>`.
+ */
+export function cockpitCommand(command, options = {}) {
+    const config = options.config === undefined ? CONFIG_PLACEHOLDER : formatShellCommand([options.config]);
+    const operand = options.operand === undefined ? '' : ` ${formatShellCommand([options.operand])}`;
+    return `npx --no cockpit ${command}${operand} --config ${config}${options.args === undefined ? '' : ` ${options.args}`}`;
+}
+/**
+ * The runnable spelling of init, which takes its root operand and --target instead of --config.
+ * A root or target the producer does not know prints as a placeholder for the reader to fill in.
+ */
+export function initCommand(options = {}) {
+    const root = options.root === undefined ? '<cockpit root>' : formatShellCommand([options.root]);
+    const target = options.target === undefined ? '<target>' : formatShellCommand([options.target]);
+    return `npx --no cockpit init ${root} --target ${target}${options.args === undefined ? '' : ` ${options.args}`}`;
+}
+function bindablePath(path) {
+    return typeof path === 'string' && isAbsolute(path) && normalize(path) === path && dirname(path) !== path
+        && !unsafeControl.test(path);
+}
+/** Replaces the configuration placeholder in printed text with the resolved path, shell-quoted. */
+export function bindConfigPath(text, context) {
+    const path = context?.resolvedConfigPath;
+    return bindablePath(path) ? text.replaceAll(`--config ${CONFIG_PLACEHOLDER}`, `--config ${formatShellCommand([path])}`) : text;
+}
+function safeTarget(target) {
+    return !unsafeControl.test(target) && !target.includes('\\') && !target.includes(':')
+        && target.split('/').every(part => part !== '' && part !== '.' && part !== '..');
+}
+// The one remedy the catalogue executes. Producers keep it as a string literal so the diagnostic
+// inventory captures it beside its code; the catalogue admits only this exact spelling.
+const GENERATED_DRIFT_FIX = `run ${cockpitCommand('sync')}`;
+export function admitDiagnosticFix(diagnostic, context) {
+    if (diagnostic.severity !== 'error' || diagnostic.code !== 'GENERATED_ARTIFACT_DRIFT'
+        || diagnostic.fix !== GENERATED_DRIFT_FIX || !diagnostic.target || !context)
+        return undefined;
+    const path = context.resolvedConfigPath;
+    if (!bindablePath(path) || !safeTarget(diagnostic.target)
+        || !context.generatedTargets.includes(diagnostic.target))
+        return undefined;
+    const argv = ['npx', '--no', 'cockpit', 'sync', '--config', path];
+    const command = formatShellCommand(argv);
+    return { argv, command };
+}

package/dist/freshness.d.ts

@@ -0,0 +1,29 @@
+export type ReleaseFreshness = Readonly<{
+    kind: 'known';
+    package: string;
+    installedVersion: string;
+    latestVersion: string;
+    currency: 'same-version' | 'different-version';
+    observedAt: string;
+    expiresAt: string;
+}> | Readonly<{
+    kind: 'unknown';
+    reason: string;
+    observedAt?: string;
+    expiresAt?: string;
+}>;
+export type ReleaseMetadataTransport = (request: Readonly<{
+    url: string;
+    signal: AbortSignal;
+}>) => Promise<Readonly<{
+    status: number;
+    body: AsyncIterable<Uint8Array>;
+}>>;
+interface ReleaseDiscoveryInput {
+    readonly verb: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly createTransport?: () => ReleaseMetadataTransport;
+    readonly now?: () => number;
+}
+export declare function discoverReleaseFreshness(input: ReleaseDiscoveryInput): Promise<ReleaseFreshness>;
+export {};

package/dist/freshness.js

@@ -0,0 +1,75 @@
+import { get } from 'node:https';
+import { installedPackageMetadata } from './package-metadata.js';
+import { RefusalError, errorCause } from './environment/contract.js';
+const MAX_BYTES = 131_072;
+const TIMEOUT_MS = 2_000;
+const CACHE_MS = 900_000;
+const cache = new WeakMap();
+const createTransport = () => ({ url, signal }) => new Promise((resolve, reject) => {
+    const request = get(url, { signal, headers: { accept: 'application/json' } }, response => {
+        resolve({ status: response.statusCode ?? 0, body: response });
+    });
+    request.on('error', reject);
+});
+async function query(factory, now) {
+    const observedAt = new Date(now).toISOString();
+    const expiresAt = new Date(now + CACHE_MS).toISOString();
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => { controller.abort(); reject(new RefusalError('release metadata query timed out')); }, TIMEOUT_MS);
+    });
+    try {
+        const transport = factory();
+        const result = await Promise.race([timeout, (async () => {
+                const response = await transport({ url: `https://registry.npmjs.org/${encodeURIComponent(installedPackageMetadata.name)}/latest`, signal: controller.signal });
+                if (response.status !== 200)
+                    throw new RefusalError(`release metadata returned HTTP ${response.status}`);
+                const chunks = [];
+                let size = 0;
+                for await (const chunk of response.body) {
+                    size += chunk.byteLength;
+                    if (size > MAX_BYTES) {
+                        controller.abort();
+                        throw new RefusalError('release metadata exceeded byte limit');
+                    }
+                    chunks.push(chunk);
+                }
+                const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+                if (value === null || typeof value !== 'object' || Array.isArray(value)
+                    || !('name' in value) || value.name !== installedPackageMetadata.name || !('version' in value)
+                    || typeof value.version !== 'string' || value.version.length > 256
+                    || !/^(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(value.version))
+                    throw new RefusalError('release metadata schema or package identity is invalid');
+                return { kind: 'known', package: installedPackageMetadata.name,
+                    installedVersion: installedPackageMetadata.version, latestVersion: value.version,
+                    currency: value.version === installedPackageMetadata.version ? 'same-version' : 'different-version', observedAt, expiresAt };
+            })()]);
+        return result;
+    }
+    catch (error) {
+        return { kind: 'unknown', reason: errorCause(error), observedAt, expiresAt };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        controller.abort();
+    }
+}
+export function discoverReleaseFreshness(input) {
+    // Admissions precede even cache access: an opted-out caller must not reuse online evidence.
+    if (input.env.CI)
+        return Promise.resolve({ kind: 'unknown', reason: 'release discovery disabled by CI' });
+    if (input.env.NO_UPDATE_NOTIFIER)
+        return Promise.resolve({ kind: 'unknown', reason: 'release discovery disabled by NO_UPDATE_NOTIFIER' });
+    if (input.verb !== 'doctor')
+        return Promise.resolve({ kind: 'unknown', reason: 'release discovery is doctor-only' });
+    const factory = input.createTransport ?? createTransport;
+    const now = (input.now ?? Date.now)();
+    const existing = cache.get(factory);
+    if (existing && existing.expiresAt > now)
+        return existing.value;
+    const value = query(factory, now);
+    cache.set(factory, { expiresAt: now + CACHE_MS, value });
+    return value;
+}

package/dist/generated-environment/adopt.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic } from '../diagnostics.js';
+import { type PublicationAdapters } from './transaction.js';
+export interface SyncAdoptionInput {
+    readonly configPath: string;
+    readonly adopt: readonly string[];
+}
+export interface SyncAdoptionOutcome {
+    readonly status: number;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly result: unknown;
+    readonly artifact?: string | null;
+    readonly destination?: string | null;
+}
+export declare function runSyncAdoption(input: SyncAdoptionInput, synchronize: (input: Readonly<{
+    configPath: string;
+}>) => Promise<SyncAdoptionOutcome>, adapterOverrides?: Partial<PublicationAdapters>): Promise<SyncAdoptionOutcome>;

package/dist/generated-environment/adopt.js

@@ -0,0 +1,271 @@
+/**
+ * Owns `cockpit sync --adopt <path>`: it takes a team's existing harness settings file into cockpit
+ * without losing it. The file's bytes move to `cockpit/adopted/<path>`, one `[[surfaces.adopted]]`
+ * row records them in cockpit.toml, and the ordinary sync then renders the merge in its place.
+ *
+ * It decides whether a file may be adopted and records it; the merge rules live in
+ * `surfaces/adoption.ts`, the cockpit.toml write in `config/verified-write.ts`, and publication in
+ * the sync it hands off to. Filesystem access crosses the authenticated transaction helper rather
+ * than introducing another runner. A sync that refuses before writing the merged file is rolled
+ * back, so a refused adoption does not silently leave the team's settings moved aside.
+ */
+import { sha256Hex } from '../sha256.js';
+import { canonicalJson } from '../canonical-json.js';
+import { basename, dirname, resolve } from 'node:path';
+import { parse, TomlError } from 'smol-toml';
+import { loadCockpitConfig, STRUCTURED_INPUT_BYTE_LIMIT } from '../config/load.js';
+import { writeVerifiedConfig } from '../config/verified-write.js';
+import { executeProbe } from '../environment-exec/execute.js';
+import { ENVIRONMENT_CODES, errorCause } from '../environment/contract.js';
+import { publicationCockpitId } from '../environment/identity.js';
+import { CockpitConfig, SurfaceAdoption } from '../schema.js';
+import { adoptedCopyPath, inspectAdoptedSettings } from '../surfaces/adoption.js';
+import { ADOPTABLE_SURFACE_PATHS, SURFACE_FILE_MAX_BYTES } from '../surfaces/contract.js';
+import { parseOwnershipManifest } from '../surfaces/ownership.js';
+import { refusalOutcome as refused } from '../refusal.js';
+import { nodeAuthority, readAnchoredEntry, readAnchoredFile, relocateAnchoredFile, restoreAnchoredFile } from './transaction.js';
+const OWNERSHIP_PATH = '.cockpit/generated-environment-ownership.json';
+// A TOML parse error quotes the lines around the failure, and cockpit.toml can hold secrets that must
+// not reach a refusal: name where parsing stopped, never the text there.
+function tomlFailure(error) {
+    return error instanceof TomlError ? `TOML error at line ${error.line}, column ${error.column}` : errorCause(error);
+}
+const ADOPT_BY_HAND_FIX = 'move the settings file to cockpit/adopted/<the same path>, add its [[surfaces.adopted]] row to cockpit.toml by hand with the fields the configuration reference lists, then run npx --no cockpit sync --config <your cockpit.toml>';
+function adoptionTable(row) {
+    return [
+        '[[surfaces.adopted]]',
+        `path = ${JSON.stringify(row.path)}`,
+        `source = ${JSON.stringify(row.source)}`,
+        `sha256 = ${JSON.stringify(row.sha256)}`,
+        `adopted_on = ${JSON.stringify(row.adopted_on)}`,
+        `provenance = { source = ${JSON.stringify(row.provenance.source)}, observed_on = ${JSON.stringify(row.provenance.observed_on)}, kind = "declared", reason = ${JSON.stringify(row.provenance.reason)} }`,
+    ].join('\n');
+}
+/** Validate one requested path completely before anything moves. */
+async function candidate(root, requested, owned, adopted, node, adapters) {
+    if (!ADOPTABLE_SURFACE_PATHS.includes(requested)) {
+        return refused('CLI_USAGE_INVALID', `--adopt ${JSON.stringify(requested)} is not an adoptable harness settings file; adoptable: ${ADOPTABLE_SURFACE_PATHS.join(', ')}`, '--adopt');
+    }
+    const path = requested;
+    const destinationPath = adoptedCopyPath(path);
+    if (adopted.has(path)) {
+        return refused('SURFACE_ADOPTION_REFUSED', `${path} is already adopted from ${destinationPath}. Delete the duplicate ${path} and run npx --no cockpit sync --config <your cockpit.toml>; its settings are kept in ${destinationPath}`, path);
+    }
+    if (owned.has(path))
+        return refused('SURFACE_ADOPTION_REFUSED', `${path} is cockpit's own published output, not a team file; nothing to adopt`, path);
+    const target = path;
+    const source = await readAnchoredFile(root, target, SURFACE_FILE_MAX_BYTES, node, adapters);
+    if (source.kind === 'missing')
+        return refused('SURFACE_ADOPTION_REFUSED', `${path} does not exist; there is nothing to adopt`, path);
+    if (source.kind !== 'complete') {
+        return refused('SURFACE_ADOPTION_REFUSED', `${path} could not be read as one stable regular file no larger than ${SURFACE_FILE_MAX_BYTES} bytes. Replace links, special files, or oversized content with the plain settings file inside the cockpit root, then re-run npx --no cockpit sync --config <your cockpit.toml> --adopt ${path}`, path);
+    }
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(source.bytes);
+    }
+    catch {
+        // undecodable bytes are malformed input the caller refuses.
+        return refused('SURFACE_ADOPTION_REFUSED', `${path} is not UTF-8 text`, path);
+    }
+    const inspected = inspectAdoptedSettings(path, text, path);
+    if (inspected.kind !== 'complete')
+        return refused(inspected.diagnostic.code, inspected.diagnostic.message, inspected.diagnostic.target);
+    const destination = await readAnchoredEntry(root, destinationPath, SURFACE_FILE_MAX_BYTES, node, adapters);
+    if (destination.kind === 'invalid')
+        return refused('SURFACE_ADOPTION_REFUSED', `${destinationPath} could not be confirmed missing through plain directories inside the cockpit root. Remove links, special files, oversized files, or unstable entries on that path, then re-run npx --no cockpit sync --config <your cockpit.toml> --adopt ${path}`, path);
+    if (destination.kind !== 'missing')
+        return refused('SURFACE_ADOPTION_REFUSED', `${destinationPath} already exists; move it aside before adopting ${path}`, destinationPath);
+    return { path, target, destination: destinationPath, sha256: source.sha256 };
+}
+async function ownedPaths(root, configPath, name, node, adapters) {
+    const read = await readAnchoredFile(root, OWNERSHIP_PATH, STRUCTURED_INPUT_BYTE_LIMIT, node, adapters);
+    if (read.kind === 'missing')
+        return new Set();
+    if (read.kind !== 'complete')
+        return refused('GENERATED_OWNERSHIP_INVALID', `generated ownership metadata could not be read as one stable regular file no larger than ${STRUCTURED_INPUT_BYTE_LIMIT} bytes. Restore a plain ${OWNERSHIP_PATH} inside the cockpit root or remove the invalid entry, then re-run the command`, OWNERSHIP_PATH);
+    let bytes;
+    try {
+        bytes = new TextDecoder('utf-8', { fatal: true }).decode(read.bytes);
+    }
+    catch {
+        // undecodable bytes are malformed input the caller refuses.
+        return refused('GENERATED_OWNERSHIP_INVALID', 'generated ownership metadata is not UTF-8 text, so whether a file is cockpit\'s own cannot be decided', OWNERSHIP_PATH);
+    }
+    const manifest = parseOwnershipManifest(bytes, { root, cockpitId: publicationCockpitId({ name }), configPath });
+    if (manifest.kind !== 'complete')
+        return refused('GENERATED_OWNERSHIP_INVALID', 'generated ownership metadata is unreadable, so whether a file is cockpit\'s own cannot be decided', OWNERSHIP_PATH);
+    return new Set(manifest.manifest.entries.map(entry => entry.path));
+}
+/** Undo the moves, newest first. Every failure is reported; none is swallowed. */
+async function restoreMoves(root, moved, node, adapters) {
+    const failures = [];
+    for (const item of [...moved].reverse()) {
+        try {
+            const restored = await restoreAnchoredFile(root, item.target, item.destination, SURFACE_FILE_MAX_BYTES, item.sha256, node, adapters);
+            if (restored.kind !== 'complete')
+                failures.push(`${adoptedCopyPath(item.path)} could not be safely moved back to ${item.path}. Preserve both paths; restore the file whose SHA-256 is ${item.sha256} to ${item.path}, then re-run the command`);
+        }
+        catch (error) {
+            failures.push(`${adoptedCopyPath(item.path)} could not be safely moved back to ${item.path} (${errorCause(error)}). Preserve both paths; restore the file whose SHA-256 is ${item.sha256} to ${item.path}, then re-run the command`);
+        }
+    }
+    return failures;
+}
+export async function runSyncAdoption(input, synchronize, adapterOverrides = {}) {
+    if (input.adopt.length === 0 || new Set(input.adopt).size !== input.adopt.length) {
+        return refused('CLI_USAGE_INVALID', 'name each harness settings file to adopt once with --adopt <path>', '--adopt');
+    }
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: loaded.diagnostics };
+    const configPath = loaded.result.source.path;
+    const root = dirname(configPath);
+    const config = loaded.result.config;
+    const node = await nodeAuthority();
+    if (!node)
+        return refused('GENERATED_EXECUTABLE_UNAVAILABLE', 'adoption requires an authenticated Node filesystem helper; reinstall cockpit and re-run the command', process.execPath);
+    const adapters = { execute: adapterOverrides.execute ?? executeProbe };
+    const owned = await ownedPaths(root, configPath, config.cockpit.name, node, adapters);
+    if (!(owned instanceof Set))
+        return owned;
+    const already = new Set(config.surfaces.adopted.map(row => row.path));
+    const candidates = [];
+    for (const requested of input.adopt) {
+        const checked = await candidate(root, requested, owned, already, node, adapters);
+        if ('status' in checked)
+            return checked;
+        candidates.push(checked);
+    }
+    const original = await readAnchoredFile(root, basename(configPath), STRUCTURED_INPUT_BYTE_LIMIT, node, adapters);
+    if (original.kind !== 'complete' || original.sha256 !== loaded.result.source.sha256) {
+        return refused(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, 'cockpit.toml changed while it was being read; nothing was moved. Re-run the command', configPath);
+    }
+    const originalText = new TextDecoder('utf-8', { fatal: true }).decode(original.bytes);
+    const adoptedOn = new Date().toISOString().slice(0, 10);
+    const rows = candidates.map(item => SurfaceAdoption.parse({
+        path: item.path, source: adoptedCopyPath(item.path), sha256: item.sha256, adopted_on: adoptedOn,
+        provenance: { source: item.path, observed_on: adoptedOn, kind: 'declared', reason: 'the team\'s own harness settings, moved aside by cockpit sync --adopt and merged with cockpit\'s rendering' },
+    }));
+    const nextText = `${originalText}${originalText.endsWith('\n') ? '' : '\n'}${rows.map(row => `\n${adoptionTable(row)}\n`).join('')}`;
+    const expected = { ...config, surfaces: { ...config.surfaces, adopted: [...config.surfaces.adopted, ...rows] } };
+    let candidateConfig;
+    try {
+        candidateConfig = CockpitConfig.safeParse(parse(nextText));
+    }
+    catch (error) {
+        return refused(ENVIRONMENT_CODES.CONFIG_PARSE_INVALID, `recording the adoption would leave cockpit.toml unparseable (${tomlFailure(error)}); nothing was moved`, configPath, ADOPT_BY_HAND_FIX);
+    }
+    if (!candidateConfig.success || canonicalJson(candidateConfig.data) !== canonicalJson(expected)) {
+        return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, 'recording the adoption would change more than the [[surfaces.adopted]] rows; nothing was moved', configPath, ADOPT_BY_HAND_FIX);
+    }
+    const moved = [];
+    const rollback = async (reason, configState, uncertainty = []) => {
+        const failures = await restoreMoves(root, moved, node, adapters);
+        let restoreConfig = configState === 'written';
+        if (configState === 'unknown') {
+            try {
+                const current = await readAnchoredFile(root, basename(configPath), STRUCTURED_INPUT_BYTE_LIMIT, node, adapters);
+                if (current.kind === 'complete' && current.sha256 === sha256Hex(originalText))
+                    restoreConfig = false;
+                else if (current.kind === 'complete' && current.sha256 === sha256Hex(nextText))
+                    restoreConfig = true;
+                else
+                    failures.push(`cockpit.toml could not be matched to either the original or adopted configuration. Preserve it and restore the version whose SHA-256 is ${sha256Hex(originalText)} before retrying`);
+            }
+            catch (error) {
+                failures.push(`cockpit.toml could not be checked after the failed write (${errorCause(error)}). Preserve it and restore the version whose SHA-256 is ${sha256Hex(originalText)} before retrying`);
+            }
+        }
+        if (restoreConfig) {
+            const fix = `restore cockpit.toml to SHA-256 ${sha256Hex(originalText)} before retrying`;
+            try {
+                const restored = await writeVerifiedConfig({
+                    path: configPath, expectedSha256: sha256Hex(nextText), temporaryTag: 'adopt',
+                    edit: () => originalText,
+                    isExactChange: (value) => canonicalJson(value) === canonicalJson(config),
+                    messages: {
+                        changedBefore: { message: 'cockpit.toml changed after the adoption was recorded, so its [[surfaces.adopted]] rows were left in place', fix },
+                        changedDuring: { message: 'cockpit.toml changed while the adoption was being undone, so its [[surfaces.adopted]] rows were left in place', fix },
+                        invalid: (detail) => ({ message: `undoing the adoption would leave cockpit.toml invalid (${detail})`, fix }),
+                        notExact: { message: 'undoing the adoption would change more than the [[surfaces.adopted]] rows', fix },
+                        writtenMismatch: { message: 'cockpit.toml was restored, but re-reading it shows a further change', fix },
+                    },
+                });
+                if (restored.kind !== 'complete')
+                    failures.push(`${restored.message}; ${restored.fix}`);
+            }
+            catch (error) {
+                failures.push(`cockpit.toml restoration failed (${errorCause(error)}). Restore cockpit.toml to SHA-256 ${sha256Hex(originalText)} before retrying`);
+            }
+        }
+        for (const retained of uncertainty)
+            failures.push(`recovery remains indeterminate for ${retained.item.path}. Preserve ${[retained.item.path, ...retained.retainedPaths].join(', ')} until the original inode is confirmed at ${retained.item.path} with SHA-256 ${retained.item.sha256}`);
+        const note = failures.length === 0
+            ? `the adoption was rolled back: ${candidates.map(item => item.path).join(', ')} ${candidates.length === 1 ? 'is' : 'are'} back in place and cockpit.toml is unchanged`
+            : `the adoption could not be fully rolled back: ${failures.join('; ')}`;
+        return { ...reason, status: reason.status === 0 ? 2 : reason.status, diagnostics: [...reason.diagnostics,
+                { severity: 'error', code: 'SURFACE_ADOPTION_REFUSED', message: note, target: candidates[0].path }] };
+    };
+    for (const item of candidates) {
+        const relocated = await relocateAnchoredFile(root, item.target, item.destination, SURFACE_FILE_MAX_BYTES, item.sha256, node, adapters);
+        if (relocated.kind !== 'complete') {
+            if (relocated.recovery === 'indeterminate')
+                moved.push(item);
+            const failure = relocated.failure ? ` Filesystem refusal: ${relocated.failure}.` : '';
+            const recoveryFailures = relocated.recoveryFailures?.length ? ` Recovery refusals: ${relocated.recoveryFailures.join(', ')}.` : '';
+            return rollback(refused('SURFACE_ADOPTION_REFUSED', relocated.recovery === 'unchanged'
+                ? `${item.path} or its adopted-copy destination changed while it was being adopted; nothing was moved.${failure}`
+                : `${item.path} could not be confirmed after the filesystem helper stopped; recovery was attempted.${failure}${recoveryFailures}`, item.path), 'unchanged', relocated.recovery === 'indeterminate' ? [{ item, retainedPaths: relocated.retainedPaths ?? [] }] : []);
+        }
+        moved.push(item);
+    }
+    const rerun = `npx --no cockpit sync --config <your cockpit.toml> ${input.adopt.map(path => `--adopt ${path}`).join(' ')}`;
+    let written;
+    try {
+        written = await writeVerifiedConfig({
+            path: configPath, expectedSha256: loaded.result.source.sha256, temporaryTag: 'adopt',
+            edit: () => nextText,
+            isExactChange: (value) => canonicalJson(value) === canonicalJson(expected),
+            messages: {
+                changedBefore: { message: 'cockpit.toml changed since it was read', fix: `let the other edit finish, then have a human approve ${rerun} again` },
+                changedDuring: { message: 'cockpit.toml changed while the adoption was being recorded', fix: `let the other edit finish, then have a human approve ${rerun} again` },
+                invalid: (detail) => ({ message: `recording the adoption would leave cockpit.toml invalid (${detail})`,
+                    fix: `correct what the message names in cockpit.toml, then have a human approve ${rerun} again` }),
+                notExact: { message: 'recording the adoption would change more than the [[surfaces.adopted]] rows', fix: ADOPT_BY_HAND_FIX },
+                writtenMismatch: { message: 'the adoption was recorded, but re-reading cockpit.toml shows a further change',
+                    fix: 'review cockpit.toml for the change you did not make before running npx --no cockpit sync --config <your cockpit.toml>' },
+            },
+        });
+    }
+    catch (error) {
+        return rollback(refused('SURFACE_ADOPTION_REFUSED', `writing cockpit.toml failed (${errorCause(error)}); owned recovery was attempted. Verify cockpit.toml has SHA-256 ${sha256Hex(originalText)} before retrying`, configPath), 'unknown');
+    }
+    if (written.kind !== 'complete')
+        return rollback(refused(written.code, written.message, configPath, written.fix), 'unknown');
+    let synced;
+    try {
+        synced = await synchronize({ configPath });
+    }
+    catch (error) {
+        return rollback(refused('SURFACE_ADOPTION_REFUSED', `synchronization failed (${errorCause(error)}); owned recovery was attempted. Inspect ${candidates.map(item => item.path).join(', ')} and cockpit.toml before retrying`, configPath), 'written');
+    }
+    if (synced.status !== 0) {
+        let published;
+        try {
+            published = await Promise.all(candidates.map(item => readAnchoredEntry(root, item.target, SURFACE_FILE_MAX_BYTES, node, adapters)
+                .then(entry => entry.kind !== 'missing')));
+        }
+        catch (error) {
+            return rollback(refused('SURFACE_ADOPTION_REFUSED', `published settings could not be checked after synchronization refused (${errorCause(error)}); owned recovery was attempted`, candidates[0].path), 'written');
+        }
+        // A merged file already on disk is consistent with the recorded adoption; undo only a sync that wrote nothing.
+        if (published.every(present => !present))
+            return rollback(synced, 'written');
+        return synced;
+    }
+    const result = synced.result !== null && typeof synced.result === 'object' && !Array.isArray(synced.result) ? synced.result : {};
+    return { ...synced, result: { ...result, adopted: rows.map(row => ({
+                path: row.path, source: resolve(root, row.source), sha256: row.sha256
+            })) } };
+}

package/dist/generated-environment/command.d.ts

@@ -0,0 +1,47 @@
+import type { Diagnostic } from '../diagnostics.js';
+import { loadOperatorPolicy } from '../environment/operator-application.js';
+import { type SyncAdoptionInput, type SyncAdoptionOutcome } from './adopt.js';
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentCommandInput, type GeneratedEnvironmentCommandOutcome, type GeneratedEnvironmentSyncInput, type GeneratedEnvironmentCurrentness, type GeneratedEnvironmentRepairAuthority, type SelectedBootstrapPublicationAuthority, type SelectedBootstrapSurfaceInput, type SelectedBootstrapResumeInput, type SelectedBootstrapResumeOutcome, type SelectedBootstrapSurfaceOutcome, type GeneratedStaleRemovalApproval, type GeneratedStaleRemovalApprovalRequest } from '../environment/generated-application/shared.js';
+export type { GeneratedEnvironmentCommandAdapters, GeneratedEnvironmentChange, GeneratedEnvironmentCommandInput, GeneratedEnvironmentCommandOutcome, GeneratedEnvironmentSyncInput, GeneratedEnvironmentCurrentness, GeneratedEnvironmentRepairAuthority, SelectedBootstrapPublicationAuthority, SelectedBootstrapSurfaceInput, SelectedBootstrapResumeInput, SelectedBootstrapResumeOutcome, SelectedBootstrapSurfaceOutcome, } from '../environment/generated-application/shared.js';
+export declare function prepareSelectedBootstrapSurface(input: SelectedBootstrapSurfaceInput, adapters?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<SelectedBootstrapSurfaceOutcome>;
+export declare function resumeSelectedBootstrapSurface(input: SelectedBootstrapResumeInput, adapters?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<SelectedBootstrapResumeOutcome>;
+export declare function applySelectedBootstrapSurface(authority: SelectedBootstrapPublicationAuthority): Promise<SelectedBootstrapSurfaceOutcome>;
+export declare function prepareGeneratedEnvironmentCurrentness(input: GeneratedEnvironmentCommandInput, adapters?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCurrentness>;
+export declare function applyGeneratedEnvironmentRepair(authority: GeneratedEnvironmentRepairAuthority, options?: Readonly<{
+    dryRun?: boolean;
+}>): Promise<GeneratedEnvironmentCommandOutcome>;
+export declare function syncGeneratedEnvironment(input: GeneratedEnvironmentSyncInput, adapters?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCommandOutcome>;
+export declare function syncTeamGeneratedEnvironment(input: GeneratedEnvironmentSyncInput, adapters?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCommandOutcome>;
+/** `sync --adopt`: record the adoption, then run the ordinary sync that renders the merge. */
+export declare function adoptAndSyncGeneratedEnvironment(input: SyncAdoptionInput): Promise<SyncAdoptionOutcome>;
+export declare function checkGeneratedEnvironment(input: GeneratedEnvironmentCommandInput): Promise<GeneratedEnvironmentCommandOutcome>;
+export interface GeneratedEnvironmentDispatchOutcome {
+    readonly artifact?: string | null;
+    readonly destination?: string | null;
+    readonly status: number;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly result: unknown;
+}
+export type GeneratedEnvironmentSyncHandlerInput = GeneratedEnvironmentSyncInput & Readonly<{
+    authorizeStaleRemoval?: (request: GeneratedStaleRemovalApprovalRequest) => Promise<GeneratedStaleRemovalApproval | undefined>;
+}>;
+type GeneratedEnvironmentSyncHandler = (input: GeneratedEnvironmentSyncHandlerInput) => Promise<GeneratedEnvironmentDispatchOutcome>;
+export interface GeneratedEnvironmentOperatorIo {
+    readonly stderr: Pick<NodeJS.WriteStream, 'write'>;
+    readonly stdin?: NodeJS.ReadStream;
+    readonly confirmStaleRemoval?: (request: GeneratedStaleRemovalApprovalRequest) => Promise<string | undefined>;
+    readonly confirmPolicyWeakening?: (request: Readonly<{
+        weakened: readonly Readonly<{
+            field: string;
+            from: string;
+            to: string;
+        }>[];
+        digest: string;
+    }>) => Promise<string | undefined>;
+}
+export interface GeneratedEnvironmentOperatorOptions {
+    readonly interactive: boolean;
+    readonly json: boolean;
+    readonly ci: string | undefined;
+}
+export declare function runSyncOperatorCommand(input: GeneratedEnvironmentSyncHandlerInput, options: GeneratedEnvironmentOperatorOptions, io: GeneratedEnvironmentOperatorIo, handler: GeneratedEnvironmentSyncHandler, policy?: typeof loadOperatorPolicy): Promise<GeneratedEnvironmentDispatchOutcome>;