@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/config/sibling-toml.js

@@ -0,0 +1,160 @@
+/**
+ * Owns the text edits `sibling add` and `sibling remove` make to cockpit.toml: append one
+ * `[[sibling]]` table, delete one table with its sub-tables, or switch one `acquire = "none"`
+ * row to a recorded remote.
+ *
+ * It edits lines and leaves every other byte alone, so comments and formatting elsewhere in the
+ * file survive. It does not judge the result: `verified-write.ts` re-parses the edited file through
+ * the real schema and refuses anything that is not exactly the intended change. A layout this
+ * module cannot locate rows in (an inline `sibling = [...]` array, dotted keys) is refused by name
+ * rather than guessed at.
+ */
+const HEADER = /^\s*(\[\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/;
+/** Remove strings and comments so bracket counting sees only structure. */
+function structuralText(line) {
+    let out = '';
+    let quote = null;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (quote !== null) {
+            if (quote === '"' && char === '\\')
+                index += 1;
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === '#')
+            break;
+        else
+            out += char;
+    }
+    return out;
+}
+function delimiterCount(line, delimiter) {
+    return line.split(delimiter).length - 1;
+}
+/** Every table header outside multi-line strings and open arrays, by zero-based line. */
+export function scanHeaders(lines) {
+    const headers = [];
+    let multiline = null;
+    let depth = 0;
+    for (const [line, text] of lines.entries()) {
+        if (multiline !== null) {
+            if (delimiterCount(text, multiline) % 2 === 1)
+                multiline = null;
+            continue;
+        }
+        const match = depth === 0 ? HEADER.exec(text) : null;
+        if (match) {
+            headers.push({ line, array: match[1] === '[[', path: match[2] });
+            continue;
+        }
+        for (const delimiter of ['"""', "'''"]) {
+            if (multiline === null && delimiterCount(text, delimiter) % 2 === 1)
+                multiline = delimiter;
+        }
+        if (multiline !== null)
+            continue;
+        const structure = structuralText(text);
+        depth = Math.max(0, depth + (structure.match(/[[{]/g)?.length ?? 0) - (structure.match(/[\]}]/g)?.length ?? 0));
+    }
+    return headers;
+}
+const isSiblingRow = (header) => header.array && header.path === 'sibling';
+const isSiblingSubtable = (header) => /^sibling\s*\./.test(header.path);
+function locateSiblingTables(text) {
+    const lines = text.split('\n');
+    const headers = scanHeaders(lines);
+    const locations = [];
+    for (const [index, header] of headers.entries()) {
+        if (!isSiblingRow(header))
+            continue;
+        let nextOwn = lines.length;
+        let next = lines.length;
+        for (const following of headers.slice(index + 1)) {
+            if (nextOwn === lines.length)
+                nextOwn = following.line;
+            if (isSiblingSubtable(following))
+                continue;
+            next = following.line;
+            break;
+        }
+        // Blank lines and comments just before the next header introduce that header, not this row.
+        let end = next - 1;
+        while (end > header.line && /^\s*(?:#.*)?$/.test(lines[end]))
+            end -= 1;
+        locations.push({ start: header.line, end, ownKeysEnd: Math.min(nextOwn, end + 1) });
+    }
+    return locations;
+}
+const quote = (value) => JSON.stringify(value);
+function siblingTable(row) {
+    return ['[[sibling]]',
+        `slug = ${quote(row.slug)}`,
+        `dir = ${quote(row.dir)}`,
+        ...(row.remote === undefined ? [] : [`remote = ${quote(row.remote)}`]),
+        `mount = ${quote(row.mount)}`,
+        `acquire = ${quote(row.acquire)}`,
+        `var = ${quote(row.var)}`,
+        `toolchain = ${quote(row.toolchain)}`,
+        ...(row.instruction_pointer === true ? ['instruction_pointer = true'] : []),
+        `purpose = ${quote(row.purpose)}`, ''].join('\n');
+}
+function unsupported(reason) {
+    return { kind: 'unsupported', reason };
+}
+/** `expected` is how many sibling rows the parsed configuration has; every one must be a `[[sibling]]` table. */
+function locateAll(text, expected) {
+    const found = locateSiblingTables(text);
+    return found.length === expected ? found
+        : `found ${found.length} \`[[sibling]]\` tables for ${expected} parsed siblings; the file declares siblings some other way (an inline array or dotted keys) and cockpit will not guess at it`;
+}
+/** Placed after the last sibling row so the siblings stay together; the first row when the file has none. */
+export function appendSiblingTable(text, row, existingRows) {
+    const located = locateAll(text, existingRows);
+    if (typeof located === 'string')
+        return unsupported(located);
+    const lines = text.split('\n');
+    const last = located.at(-1);
+    if (last === undefined) {
+        const separator = text.length === 0 || text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+        return { kind: 'edited', text: `${text}${separator}${siblingTable(row)}` };
+    }
+    lines.splice(last.end + 1, 0, '', ...siblingTable(row).split('\n').slice(0, -1));
+    return { kind: 'edited', text: lines.join('\n') };
+}
+export function removeSiblingTable(text, index, existingRows) {
+    const located = locateAll(text, existingRows);
+    if (typeof located === 'string')
+        return unsupported(located);
+    const { start, end } = located[index];
+    const lines = text.split('\n');
+    let after = end + 1;
+    while (after < lines.length && lines[after].trim() === '')
+        after += 1;
+    const kept = [...lines.slice(0, start), ...lines.slice(after)];
+    // Removing the last table must not leave the blank line that separated it from the table before.
+    if (after >= lines.length) {
+        while (kept.length > 0 && kept.at(-1).trim() === '')
+            kept.pop();
+        kept.push('');
+    }
+    return { kind: 'edited', text: kept.join('\n') };
+}
+export function recordSiblingRemote(text, index, existingRows, remote) {
+    const located = locateAll(text, existingRows);
+    if (typeof located === 'string')
+        return unsupported(located);
+    const { start, ownKeysEnd } = located[index];
+    const lines = text.split('\n');
+    const own = (pattern) => lines.slice(start + 1, ownKeysEnd).flatMap((line, offset) => pattern.test(line) ? [start + 1 + offset] : []);
+    const acquire = own(/^\s*acquire\s*=\s*"none"\s*(?:#.*)?$/);
+    if (acquire.length !== 1)
+        return unsupported('the row has no single `acquire = "none"` line to switch; edit it by hand');
+    const dir = own(/^\s*dir\s*=/);
+    lines[acquire[0]] = lines[acquire[0]].replace('"none"', '"auto"');
+    lines.splice((dir[0] ?? acquire[0]) + 1, 0, `remote = ${quote(remote)}`);
+    return { kind: 'edited', text: lines.join('\n') };
+}

package/dist/config/surface-tools-toml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Owns the text edit `tool add` and `tool remove` make to cockpit.toml: set the one `tools` line of
+ * the `[surfaces]` table, adding the table when the file has none. Every other byte is left alone.
+ * The verified write re-parses the result and refuses anything beyond that one change; a layout this
+ * module cannot locate the list in (a multi-line array, an inline or dotted `surfaces`) is refused by
+ * name rather than guessed at.
+ */
+import { type SiblingEdit } from './sibling-toml.js';
+export declare function setSurfaceTools(text: string, tools: readonly string[]): SiblingEdit;

package/dist/config/surface-tools-toml.js

@@ -0,0 +1,37 @@
+/**
+ * Owns the text edit `tool add` and `tool remove` make to cockpit.toml: set the one `tools` line of
+ * the `[surfaces]` table, adding the table when the file has none. Every other byte is left alone.
+ * The verified write re-parses the result and refuses anything beyond that one change; a layout this
+ * module cannot locate the list in (a multi-line array, an inline or dotted `surfaces`) is refused by
+ * name rather than guessed at.
+ */
+import { scanHeaders } from './sibling-toml.js';
+const TOOLS_KEY = /^\s*tools\s*=/;
+const SINGLE_LINE_ARRAY = /^\s*tools\s*=\s*\[[^\]#]*\]\s*(#.*)?$/;
+export function setSurfaceTools(text, tools) {
+    const line = `tools = [${tools.map(tool => JSON.stringify(tool)).join(', ')}]`;
+    const lines = text.split('\n');
+    const headers = scanHeaders(lines);
+    const firstHeader = headers[0]?.line ?? lines.length;
+    if (lines.slice(0, firstHeader).some(row => /^\s*surfaces\s*[.=]/.test(row))) {
+        return { kind: 'unsupported', reason: 'surfaces is written as a top-level inline table or dotted key, and cockpit edits only a [surfaces] table' };
+    }
+    const index = headers.findIndex(header => !header.array && header.path === 'surfaces');
+    if (index < 0) {
+        const separator = text.length === 0 || text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+        return { kind: 'edited', text: `${text}${separator}[surfaces]\n${line}\n` };
+    }
+    const start = headers[index].line;
+    const end = headers[index + 1]?.line ?? lines.length;
+    const keys = lines.slice(start + 1, end).flatMap((row, offset) => TOOLS_KEY.test(row) ? [start + 1 + offset] : []);
+    if (keys.length === 0) {
+        lines.splice(start + 1, 0, line);
+        return { kind: 'edited', text: lines.join('\n') };
+    }
+    const current = SINGLE_LINE_ARRAY.exec(lines[keys[0]]);
+    if (keys.length > 1 || !current) {
+        return { kind: 'unsupported', reason: 'the [surfaces] tools list is not written on one line as tools = [...]' };
+    }
+    lines[keys[0]] = current[1] === undefined ? line : `${line} ${current[1]}`;
+    return { kind: 'edited', text: lines.join('\n') };
+}

package/dist/config/unconfirmed-toml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Owns the text edit `confirm` makes to cockpit.toml: drop one answer from the top-level
+ * `unconfirmed = [...]` line, or the whole line once the list empties. Every other byte, comments
+ * included, is left alone. The verified write re-parses the result and refuses anything beyond that
+ * change; a layout this module cannot locate the list in (a multi-line array, a list inside a table)
+ * is refused by name rather than guessed at.
+ */
+import { type SiblingEdit } from './sibling-toml.js';
+export declare function removeUnconfirmedAnswer(text: string, answer: string): SiblingEdit;

package/dist/config/unconfirmed-toml.js

@@ -0,0 +1,29 @@
+/**
+ * Owns the text edit `confirm` makes to cockpit.toml: drop one answer from the top-level
+ * `unconfirmed = [...]` line, or the whole line once the list empties. Every other byte, comments
+ * included, is left alone. The verified write re-parses the result and refuses anything beyond that
+ * change; a layout this module cannot locate the list in (a multi-line array, a list inside a table)
+ * is refused by name rather than guessed at.
+ */
+import { scanHeaders } from './sibling-toml.js';
+const UNCONFIRMED_KEY = /^\s*unconfirmed\s*=/;
+const SINGLE_LINE_ARRAY = /^(\s*unconfirmed\s*=\s*)\[([^\]#]*)\](\s*(?:#.*)?)$/;
+export function removeUnconfirmedAnswer(text, answer) {
+    const lines = text.split('\n');
+    const firstHeader = scanHeaders(lines)[0]?.line ?? lines.length;
+    const keys = lines.slice(0, firstHeader).flatMap((row, index) => UNCONFIRMED_KEY.test(row) ? [index] : []);
+    const at = keys[0];
+    const current = at === undefined ? null : SINGLE_LINE_ARRAY.exec(lines[at]);
+    if (keys.length !== 1 || !current) {
+        return { kind: 'unsupported', reason: 'the unconfirmed list is not written on one line as unconfirmed = [...] before the first table' };
+    }
+    const rows = current[2].split(',').map(row => row.trim()).filter(row => row !== '');
+    const kept = rows.filter(row => row !== JSON.stringify(answer) && row !== `'${answer}'`);
+    if (kept.length === rows.length)
+        return { kind: 'unsupported', reason: `the unconfirmed list does not spell ${answer} as a plain string` };
+    if (kept.length === 0)
+        lines.splice(at, 1);
+    else
+        lines[at] = `${current[1]}[${kept.join(', ')}]${current[3]}`;
+    return { kind: 'edited', text: lines.join('\n') };
+}

package/dist/config/verified-write.d.ts

@@ -0,0 +1,43 @@
+/** What failed and the remedy, kept apart so the remedy reaches the reader as the diagnostic's fix. */
+export interface VerifiedWriteRefusal {
+    readonly message: string;
+    readonly fix: string;
+}
+export interface VerifiedWriteMessages {
+    /** Said when the file changed between the caller's read and the write. */
+    readonly changedBefore: VerifiedWriteRefusal;
+    /** Said when the file changed while the candidate was being prepared. */
+    readonly changedDuring: VerifiedWriteRefusal;
+    /** Said when the candidate does not parse; `reason` is the loader's own summary. */
+    readonly invalid: (reason: string) => VerifiedWriteRefusal;
+    /** Said when the candidate parses but is more than the intended change. */
+    readonly notExact: VerifiedWriteRefusal;
+    /** Said when re-reading the written file shows more than the intended change. */
+    readonly writtenMismatch: VerifiedWriteRefusal;
+}
+export interface VerifiedWriteInput {
+    readonly path: string;
+    /** Digest of the bytes the caller decided from; a different file on disk is never overwritten. */
+    readonly expectedSha256: string;
+    /** Names the temporary file (`.<name>.<tag>-<random>`). */
+    readonly temporaryTag: string;
+    readonly edit: (original: string) => string;
+    /** True only for a parsed configuration that is the caller's base plus exactly the intended change. */
+    readonly isExactChange: (config: unknown) => boolean;
+    readonly messages: VerifiedWriteMessages;
+}
+export type VerifiedWriteResult = Readonly<{
+    kind: 'complete';
+}> | Readonly<{
+    kind: 'refused';
+    code: string;
+    message: string;
+    fix: string;
+}>;
+/**
+ * Write through a sibling temporary file and an atomic rename, so a reader sees the old or the new
+ * configuration and never half of one. The original's identity and digest are checked again just
+ * before the rename: the caller may have run for minutes, and an edit made meanwhile must not be
+ * overwritten.
+ */
+export declare function writeVerifiedConfig(input: VerifiedWriteInput): Promise<VerifiedWriteResult>;

package/dist/config/verified-write.js

@@ -0,0 +1,89 @@
+/**
+ * Owns the one way cockpit rewrites an existing cockpit.toml: edit through a sibling temporary
+ * file, re-parse it through the real schema, accept it only when it is exactly the intended
+ * change, then rename it over the original.
+ *
+ * It does not decide what the edit is: callers supply the text edit and the predicate that
+ * recognises the intended change. It never spawns a process. Callers: `sibling add` /
+ * `sibling remove` and `sync --adopt`.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, rmdir, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { ENVIRONMENT_CODES } from '../environment/contract.js';
+import { loadCockpitConfig, readBoundedInput } from './load.js';
+/**
+ * Write through a sibling temporary file and an atomic rename, so a reader sees the old or the new
+ * configuration and never half of one. The original's identity and digest are checked again just
+ * before the rename: the caller may have run for minutes, and an edit made meanwhile must not be
+ * overwritten.
+ */
+export async function writeVerifiedConfig(input) {
+    const { path, expectedSha256, messages } = input;
+    const refuse = (code, refusal) => ({ kind: 'refused', code, ...refusal });
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink())
+        return refuse(ENVIRONMENT_CODES.CONFIG_UNREADABLE, { message: 'cockpit.toml is not a regular file; nothing was written',
+            fix: 'replace the link or special file at the --config path with the cockpit.toml file itself, then run the command again' });
+    const read = await readBoundedInput(path);
+    if (read.kind !== 'complete')
+        return refuse(ENVIRONMENT_CODES.CONFIG_UNREADABLE, { message: 'cockpit.toml exceeds the input limit; nothing was written',
+            fix: 'cut cockpit.toml below the input limit by moving embedded data into the files it names, then run the command again' });
+    if (createHash('sha256').update(read.bytes).digest('hex') !== expectedSha256) {
+        return refuse(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, messages.changedBefore);
+    }
+    const next = input.edit(read.bytes.toString('utf8'));
+    // Keep the candidate's basename equal to the real configuration name. Declared provenance
+    // may intentionally name cockpit.toml without observed_on; validating it under a random
+    // temporary basename would reject bytes that become valid at the atomic destination.
+    const temporaryRoot = join(dirname(path), `.${basename(path)}.${input.temporaryTag}-${randomBytes(8).toString('hex')}`);
+    const temporary = join(temporaryRoot, basename(path));
+    let created = false;
+    let rootCreated = false;
+    try {
+        await mkdir(temporaryRoot, { mode: 0o700 });
+        rootCreated = true;
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, before.mode & 0o777);
+        created = true;
+        try {
+            await handle.writeFile(next);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        const candidate = await loadCockpitConfig(temporary);
+        if (candidate.kind !== 'complete') {
+            return refuse(candidate.diagnostics[0]?.code ?? ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, messages.invalid(candidate.diagnostics[0]?.message ?? 'unreadable'));
+        }
+        if (!input.isExactChange(candidate.result.config))
+            return refuse(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, messages.notExact);
+        const current = await lstat(path);
+        const recheck = await readBoundedInput(path);
+        if (current.dev !== before.dev || current.ino !== before.ino || current.size !== before.size || current.mtimeMs !== before.mtimeMs
+            || recheck.kind !== 'complete' || createHash('sha256').update(recheck.bytes).digest('hex') !== expectedSha256) {
+            return refuse(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, messages.changedDuring);
+        }
+        await rename(temporary, path);
+        created = false;
+        const directory = await open(dirname(path), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        if (created)
+            await unlink(temporary);
+        if (rootCreated)
+            await rmdir(temporaryRoot);
+    }
+    const written = await loadCockpitConfig(path);
+    if (written.kind !== 'complete' || !input.isExactChange(written.result.config)) {
+        return refuse(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, messages.writtenMismatch);
+    }
+    return { kind: 'complete' };
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,26 @@
+import { type Diagnostic, type SetupRefusalEvidence } from './environment/contract.js';
+import type { InvocationRecord } from './invocation.js';
+import { type FixContext } from './fix-catalogue.js';
+export type { Diagnostic } from './environment/contract.js';
+interface HumanReviewOutcome {
+    readonly status: number;
+    readonly result: unknown;
+    readonly diagnostics?: readonly Diagnostic[];
+}
+interface HumanReviewContext {
+    readonly command: string | undefined;
+    readonly outcome: HumanReviewOutcome;
+}
+export declare function renderHumanValue(value: unknown): string;
+export declare function renderHumanDiagnostics(diagnostics: readonly Diagnostic[], review?: HumanReviewContext, fixContext?: FixContext, usageHint?: string): string;
+export declare function renderJsonResponse(outcome: {
+    result: unknown;
+    diagnostics: readonly Diagnostic[];
+    evidence?: SetupRefusalEvidence;
+    invocation?: InvocationRecord;
+    progress?: Readonly<{
+        applied: readonly string[];
+        notApplied: readonly string[];
+        attempted?: readonly string[];
+    }>;
+}, fixContext?: FixContext): string;