@b00dea/cockpit 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,9 @@
+import type { SiblingOutcome } from './sibling-registration.js';
+export interface ToolChangeInput {
+    readonly operation: 'add' | 'remove';
+    readonly configPath: string;
+    readonly tool: string;
+    /** Show the edited list and write nothing. */
+    readonly dryRun: boolean;
+}
+export declare function runToolChange(input: ToolChangeInput): Promise<SiblingOutcome>;

package/dist/environment/tool-registration.js

@@ -0,0 +1,92 @@
+/**
+ * Owns `cockpit tool add` and `cockpit tool remove`: they edit the `[surfaces] tools` list of
+ * cockpit.toml so nobody hand-edits it. They write no tool's files: the next sync renders an added
+ * tool from the same sources as the others, and offers a removed tool's owned files to the
+ * stale-removal approval that already guards every deletion of a generated file.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { parse, TomlError } from 'smol-toml';
+import { loadCockpitConfig } from '../config/load.js';
+import { canonicalJson } from '../canonical-json.js';
+import { setSurfaceTools } from '../config/surface-tools-toml.js';
+import { writeVerifiedConfig } from '../config/verified-write.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { CockpitConfig } from '../schema.js';
+import { harnessFact, SURFACE_TARGETS } from '../surfaces/harness-registry.js';
+import { ENVIRONMENT_CODES, errorCause } from './contract.js';
+import { refusalOutcome as refused } from '../refusal.js';
+const EDIT_BY_HAND_FIX = 'edit the tools list under [surfaces] in cockpit.toml by hand, then run npx --no cockpit sync --config <your cockpit.toml> --dry-run';
+function done(artifact, result) {
+    return { status: 0, diagnostics: [], destination: null, artifact, result };
+}
+export async function runToolChange(input) {
+    if (!SURFACE_TARGETS.includes(input.tool)) {
+        return refused('CLI_USAGE_INVALID', `unknown tool ${JSON.stringify(input.tool)}; cockpit renders ${SURFACE_TARGETS.join(', ')}`, input.tool);
+    }
+    const tool = input.tool;
+    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 config = loaded.result.config;
+    // The list keeps the order it was written in; an added tool goes last.
+    const before = config.surfaces.tools;
+    const after = input.operation === 'add' ? before.includes(tool) ? before : [...before, tool] : before.filter(row => row !== tool);
+    const preview = cockpitCommand('sync', { config: configPath, args: '--dry-run' });
+    if (after.length === before.length) {
+        return done(`${harnessFact(tool).displayName} (${tool}) is ${input.operation === 'add' ? 'already' : 'not'} listed in ${configPath}; nothing was written.\n`, { action: 'unchanged', config: configPath, tool, tools: before });
+    }
+    const bytes = await readFile(configPath);
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    if (sha256 !== loaded.result.source.sha256) {
+        return refused(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, 'cockpit.toml changed while it was being read; nothing was written', configPath, `run the same npx --no cockpit tool ${input.operation} command again`);
+    }
+    const edit = setSurfaceTools(bytes.toString('utf8'), after);
+    if (edit.kind === 'unsupported') {
+        return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, `cockpit.toml cannot be edited safely: ${edit.reason}; nothing was written`, 'surfaces.tools', EDIT_BY_HAND_FIX);
+    }
+    // The schema decides what a list may hold (a guarded tool, every browser harness), so its refusal is the message.
+    let parsed;
+    try {
+        parsed = CockpitConfig.safeParse(parse(edit.text));
+    }
+    catch (error) {
+        const where = error instanceof TomlError ? `at line ${error.line}, column ${error.column}` : errorCause(error);
+        return refused(ENVIRONMENT_CODES.CONFIG_PARSE_INVALID, `the edit would leave cockpit.toml unparseable (${where}); nothing was written`, 'surfaces.tools', EDIT_BY_HAND_FIX);
+    }
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, `${input.operation === 'add' ? 'adding' : 'removing'} ${tool} would leave cockpit.toml invalid (${issue ? `${issue.path.join('.') || '(root)'}: ${issue.message}` : 'schema'}); nothing was written`, 'surfaces.tools', 'change what the message names first, then run the command again');
+    }
+    const expected = canonicalJson({ ...config, surfaces: { ...config.surfaces, tools: after } });
+    const exact = (candidate) => canonicalJson(candidate) === expected;
+    if (!exact(parsed.data)) {
+        return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, 'the edit would change more than the tools list; nothing was written', 'surfaces.tools', EDIT_BY_HAND_FIX);
+    }
+    const line = `tools = [${after.map(row => JSON.stringify(row)).join(', ')}]`;
+    const next = input.operation === 'add'
+        ? `The next sync writes ${harnessFact(tool).displayName}'s instructions, skills and settings from the same sources as the other tools; preview them with ${preview}.`
+        : `The next sync offers the files cockpit wrote for ${harnessFact(tool).displayName} for removal: ${preview} lists them, and a person approves their removal with ${cockpitCommand('sync', { config: configPath, args: '--interactive' })}.`;
+    const result = { action: input.dryRun ? 'previewed' : input.operation === 'add' ? 'added' : 'removed', config: configPath, tool, tools: after,
+        next: preview };
+    if (input.dryRun)
+        return done(`Would set [surfaces] ${line} in ${configPath}; nothing was written.\n${next}\n`, result);
+    const rerun = `let the other edit finish, then run the same npx --no cockpit tool ${input.operation} command again`;
+    const written = await writeVerifiedConfig({
+        path: configPath, expectedSha256: sha256, temporaryTag: 'tool',
+        edit: () => edit.text,
+        isExactChange: exact,
+        messages: {
+            changedBefore: { message: 'cockpit.toml changed since it was read; nothing was written', fix: rerun },
+            changedDuring: { message: 'cockpit.toml changed while the edit was being prepared; nothing was written', fix: rerun },
+            invalid: (reason) => ({ message: `the edit would leave cockpit.toml invalid (${reason}); nothing was written`, fix: EDIT_BY_HAND_FIX }),
+            notExact: { message: 'the edit would change more than the tools list; nothing was written', fix: EDIT_BY_HAND_FIX },
+            writtenMismatch: { message: 'the tools list was written, but re-reading cockpit.toml shows a change beyond it',
+                fix: 'review cockpit.toml for the change you did not make before running npx --no cockpit sync --config <your cockpit.toml> --dry-run' },
+        },
+    });
+    if (written.kind !== 'complete')
+        return refused(written.code, written.message, configPath, written.fix);
+    return done(`Set [surfaces] ${line} in ${configPath}.\n${next}\n`, result);
+}

package/dist/environment/upgrade-application.d.ts

@@ -0,0 +1,19 @@
+import type { ExecuteProbeOutcome, ForegroundProcessInput, ForegroundProcessOutcome } from '../environment-exec/execute.js';
+import type { Diagnostic } from '../diagnostics.js';
+import { type ExecutionStep } from './contract.js';
+export interface UpgradeInput {
+    readonly configPath: string;
+    readonly version?: string;
+    readonly dryRun: boolean;
+    readonly env: Readonly<Record<string, string>>;
+}
+export interface UpgradeDependencies {
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+    readonly executeForeground: (input: ForegroundProcessInput) => Promise<ForegroundProcessOutcome>;
+}
+export interface UpgradeOutcome {
+    readonly status: number;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function runUpgrade(input: UpgradeInput, dependencies: UpgradeDependencies): Promise<UpgradeOutcome>;

package/dist/environment/upgrade-application.js

@@ -0,0 +1,175 @@
+/**
+ * Owns `cockpit upgrade`: move the exact pin of the installed package, then re-run `sync` in a new
+ * process so the new version renders the generated files (this process holds the old code).
+ *
+ * The pin is exact because `check` refuses a running version that differs from it, so the install
+ * must be exact too. The package manager comes from the single lockfile at the cockpit root. Every
+ * child process crosses the supplied `execute` / `executeForeground`, which production binds to
+ * `environment-exec/execute.ts`; sync's own refusals and exit code pass through unchanged.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { formatShellCommand } from '../fix-catalogue.js';
+import { installedPackageMetadata } from '../package-metadata.js';
+import { ENVIRONMENT_CODES, errorCause, hasErrorCode } from './contract.js';
+import { resolveExecutable } from './executable.js';
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'npm-shrinkwrap.json', 'bun.lock', 'bun.lockb'];
+// Flags checked against each manager's own --help: a dev dependency saved at the exact version.
+const INSTALL = {
+    'package-lock.json': { manager: 'npm', verb: 'install', flags: ['--save-dev', '--save-exact'] },
+    'pnpm-lock.yaml': { manager: 'pnpm', verb: 'add', flags: ['--save-dev', '--save-exact'] },
+    'yarn.lock': { manager: 'yarn', verb: 'add', flags: ['--dev', '--exact'] },
+};
+const LOOKUP_TIMEOUT_MS = 60_000;
+const INSTALL_TIMEOUT_MS = 600_000;
+// Each call site writes its code and fix as literals so the troubleshooting index captures them.
+function refused(diagnostic, status = 2) {
+    return { status, result: null, diagnostics: [diagnostic] };
+}
+/** Orders two versions; a prerelease sorts before its release, and prerelease identifiers compare as semver says. */
+function compareVersions(a, b) {
+    const [x, y] = [VERSION.exec(a), VERSION.exec(b)];
+    for (let i = 1; i <= 3; i++)
+        if (x[i] !== y[i])
+            return Number(x[i]) < Number(y[i]) ? -1 : 1;
+    if (x[4] === y[4])
+        return 0;
+    if (x[4] === undefined || y[4] === undefined)
+        return x[4] === undefined ? 1 : -1;
+    const [p, q] = [x[4].split('.'), y[4].split('.')];
+    for (let i = 0; i < Math.max(p.length, q.length); i++) {
+        if (p[i] === undefined || q[i] === undefined)
+            return p[i] === undefined ? -1 : 1;
+        if (p[i] === q[i])
+            continue;
+        const numeric = [/^\d+$/.test(p[i]), /^\d+$/.test(q[i])];
+        if (numeric[0] && numeric[1])
+            return Number(p[i]) < Number(q[i]) ? -1 : 1;
+        if (numeric[0] !== numeric[1])
+            return numeric[0] ? -1 : 1;
+        return p[i] < q[i] ? -1 : 1;
+    }
+    return 0;
+}
+function step(executable, cwd, env, id, args, timeoutMs) {
+    return {
+        id, argv: [executable.canonicalPath, ...args],
+        argv0: executable.invocationPath, cwd, env, timeoutMs,
+        stdoutLimitBytes: 65_536, stderrLimitBytes: 65_536,
+        outputOverflow: 'retain-tail', failureOutput: 'stderr-tail',
+        paths: [], ports: [], labels: { purpose: id }, expected: [],
+        consumedFiles: [{ path: executable.canonicalPath, sha256: executable.sha256,
+                maxBytes: 536_870_912, argvIndexes: [0], executable: true, executionMode: executable.executionMode }],
+        filesystemChecks: [], compensation: [],
+    };
+}
+async function lockfilesAt(root) {
+    const found = [];
+    for (const name of LOCKFILES) {
+        try {
+            await stat(join(root, name));
+            found.push(name);
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                throw error;
+        }
+    }
+    return found;
+}
+/** The `Upgrade:` lines of every changelog entry after `from` up to and including `to`. */
+function upgradeNotes(changelog, from, to) {
+    const notes = [];
+    let inRange = false;
+    for (const line of changelog.split('\n')) {
+        const heading = /^## (\S+)\s*$/.exec(line);
+        if (heading)
+            inRange = VERSION.test(heading[1]) && compareVersions(heading[1], from) > 0 && compareVersions(heading[1], to) <= 0;
+        else if (inRange && /\bUpgrade:/.test(line))
+            notes.push(line.trim().replace(/^[-*]\s+/, ''));
+    }
+    return notes;
+}
+export async function runUpgrade(input, dependencies) {
+    const { name, version: installed } = installedPackageMetadata;
+    const configPath = resolve(input.configPath);
+    const root = dirname(configPath);
+    const npmPage = (version) => `https://www.npmjs.com/package/${name}/v/${version}`;
+    const found = await lockfilesAt(root);
+    const lockfile = found.length === 1 ? INSTALL[found[0]] : undefined;
+    if (!lockfile)
+        return refused({ severity: 'error', code: 'UPGRADE_PACKAGE_MANAGER_UNKNOWN',
+            message: found.length === 0 ? `no lockfile in ${root}, so the package manager is unknown`
+                : `${found.join(', ')} in ${root} ${found.length > 1 ? 'name more than one package manager' : 'is not a lockfile upgrade supports'}`,
+            fix: 'keep exactly one of package-lock.json, pnpm-lock.yaml or yarn.lock at the cockpit root and put its package manager (npm, pnpm or yarn) on PATH, then run npx --no cockpit upgrade --config <your cockpit.toml>' });
+    const manager = await resolveExecutable(lockfile.manager, input.env);
+    if (manager.state !== 'available')
+        return refused({ severity: 'error', code: 'UPGRADE_PACKAGE_MANAGER_UNKNOWN',
+            message: `${lockfile.manager} is not on PATH: ${manager.reason}`, fix: 'keep exactly one of package-lock.json, pnpm-lock.yaml or yarn.lock at the cockpit root and put its package manager (npm, pnpm or yarn) on PATH, then run npx --no cockpit upgrade --config <your cockpit.toml>' });
+    let target = input.version;
+    if (target === undefined) {
+        const npm = await resolveExecutable('npm', input.env);
+        if (npm.state !== 'available')
+            return refused({ severity: 'error', code: 'UPGRADE_REGISTRY_UNREACHABLE',
+                message: `npm is needed to look up the latest ${name} and is not on PATH: ${npm.reason}`, fix: 'check the network, the registry login and that npm is on PATH, or name the version: npx --no cockpit upgrade --config <your cockpit.toml> <version>' });
+        const lookup = step(npm.value, root, input.env, 'upgrade:latest', ['view', name, 'version', '--json'], LOOKUP_TIMEOUT_MS);
+        const outcome = authenticatedExecutionOutcome(await dependencies.execute(lookup), lookup);
+        let published;
+        try {
+            published = outcome?.kind === 'complete' ? JSON.parse(outcome.stdout.toString('utf8')) : undefined;
+        }
+        catch {
+            published = undefined;
+        } // reported below as an answer that is not a version
+        if (typeof published !== 'string' || !VERSION.test(published))
+            return refused({ severity: 'error', code: 'UPGRADE_REGISTRY_UNREACHABLE',
+                message: `the registry did not give the latest ${name} version (${outcome?.kind === 'complete' ? 'the answer was not a version' : outcome ? `${outcome.code}: ${outcome.stderr.toString('utf8').trim().split('\n').slice(0, 2).join(' | ').slice(0, 256)}` : 'the lookup could not be authenticated'})`,
+                fix: 'check the network, the registry login and that npm is on PATH, or name the version: npx --no cockpit upgrade --config <your cockpit.toml> <version>' });
+        target = published;
+    }
+    else if (!VERSION.test(target))
+        return refused({ severity: 'error', code: 'UPGRADE_VERSION_INVALID', target: '<version>',
+            message: `"${target}" is not an exact version`, fix: 'give a full version such as 1.2.3, not a range or tag' });
+    const order = compareVersions(target, installed);
+    if (order === 0 || order < 0 && input.version === undefined)
+        return refused({ severity: 'error', code: 'UPGRADE_ALREADY_CURRENT',
+            message: `already on ${installed}${order === 0 ? '' : `; the latest published is ${target}`}`,
+            fix: 'nothing to upgrade; to move to another version name it: npx --no cockpit upgrade --config <your cockpit.toml> <version>' });
+    const spec = `${name}@${target}`;
+    const installArgv = [lockfile.manager, lockfile.verb, ...lockfile.flags, spec];
+    const syncArgv = ['npx', '--no', 'cockpit', 'sync', '--config', configPath];
+    const result = { from: installed, to: target, packageManager: lockfile.manager,
+        install: formatShellCommand(installArgv), sync: formatShellCommand(syncArgv), dryRun: input.dryRun };
+    if (input.dryRun)
+        return { status: 0, diagnostics: [],
+            result: { ...result, next: 'nothing was run; drop --dry-run to install and sync' } };
+    const install = step(manager.value, root, input.env, 'upgrade:install', installArgv.slice(1), INSTALL_TIMEOUT_MS);
+    const installOutcome = authenticatedExecutionOutcome(await dependencies.execute(install), install);
+    if (installOutcome?.kind !== 'complete')
+        return refused({ severity: 'error', code: 'UPGRADE_INSTALL_FAILED',
+            message: `${result.install} failed (${installOutcome ? `${installOutcome.code}, exit ${installOutcome.execution.exitCode}: ${installOutcome.stderr.toString('utf8').trim().split('\n').slice(-3).join(' | ').slice(0, 512)}` : 'the outcome could not be authenticated'})`,
+            fix: 'fix what the package manager reported (is the version published?), then run npx --no cockpit upgrade --config <your cockpit.toml> <version>' });
+    const npx = await resolveExecutable('npx', input.env);
+    if (npx.state !== 'available')
+        return refused({ severity: 'error', code: 'UPGRADE_SYNC_FAILED',
+            message: `${spec} is installed but npx is not on PATH: ${npx.reason}`, fix: 'act on what sync reported above or put npx on PATH, then run npx --no cockpit sync --config <your cockpit.toml>' });
+    const synced = await dependencies.executeForeground({ executable: npx.value, argv: syncArgv.slice(1), cwd: root, env: input.env });
+    if (synced.kind !== 'complete' || synced.exitCode !== 0)
+        return refused({ severity: 'error', code: 'UPGRADE_SYNC_FAILED',
+            message: `${spec} is installed but sync did not finish (${synced.kind === 'refusal' ? synced.code : `exit ${synced.exitCode}`}); the generated files are still those of ${installed}`,
+            fix: 'act on what sync reported above or put npx on PATH, then run npx --no cockpit sync --config <your cockpit.toml>' }, synced.exitCode === 0 ? 1 : synced.exitCode);
+    let notes;
+    try {
+        notes = upgradeNotes(await readFile(join(root, 'node_modules', name, 'CHANGELOG.md'), 'utf8'), installed, target);
+    }
+    catch (error) {
+        return { status: 0, diagnostics: [], result: { ...result,
+                upgradeSteps: `the installed package's CHANGELOG.md could not be read (${hasErrorCode(error, 'ENOENT') ? 'missing' : errorCause(error)}); release notes: ${npmPage(target)}`,
+                next: 'review git diff, then commit package.json, the lockfile and the regenerated files together' } };
+    }
+    return { status: 0, diagnostics: [], result: { ...result,
+            upgradeSteps: notes.length === 0 ? 'the changelog lists no Upgrade: steps between these versions' : notes,
+            next: 'review git diff, then commit package.json, the lockfile and the regenerated files together' } };
+}

package/dist/environment-exec/execute.d.ts

@@ -0,0 +1,105 @@
+import { ENVIRONMENT_CODES, type ExecutionFailureCode, type ExecutionPlan, type ExecutionReceipt, type ExecutionStep, type ExecutionFence, type EnvironmentDiagnostic } from '../environment/contract.js';
+export interface FencedExecutionTermination {
+    readonly kind: 'fenced-execution-termination';
+}
+export declare function repairFencedExecution(fence: ExecutionFence): Promise<{
+    readonly kind: 'complete';
+    readonly evidence: FencedExecutionTermination;
+} | {
+    readonly kind: 'refusal';
+    readonly code: typeof ENVIRONMENT_CODES.DRAIN_ATTEMPT_REPAIR_REQUIRED;
+}>;
+export declare function cleanupFencedExecution(fence: ExecutionFence): Promise<boolean>;
+export declare function consumeFencedExecutionTermination(evidence: FencedExecutionTermination, fence: ExecutionFence): boolean;
+export interface ForegroundProcessInput {
+    readonly executable: import('../environment/executable.js').ResolvedExecutable;
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+export type ForegroundProcessOutcome = Readonly<{
+    kind: 'complete';
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+    terminationConfirmed: true;
+}> | Readonly<{
+    kind: 'refusal';
+    code: ExecutionFailureCode;
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+    started: boolean;
+    terminationConfirmed: boolean;
+}>;
+interface StepExecution {
+    id: string;
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+    stdoutBytes: number;
+    stderrBytes: number;
+}
+interface ProbeStepExecution extends StepExecution {
+    started: boolean;
+    stdoutObservedBytes: number;
+    stderrObservedBytes: number;
+    stdoutRetainedBytes: number;
+    stderrRetainedBytes: number;
+}
+interface CompensationFailure {
+    id: string;
+    code: ExecutionFailureCode;
+}
+export type ExecutePlanOutcome = {
+    kind: 'complete';
+    status: 0;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: {
+        steps: readonly StepExecution[];
+    };
+} | {
+    kind: 'refusal';
+    status: 2;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: null;
+    execution: {
+        completedStepIds: readonly string[];
+        failedStep: {
+            id: string;
+            started: boolean;
+            stderr?: string;
+        };
+        compensation: {
+            attemptedStepIds: readonly string[];
+            completedStepIds: readonly string[];
+            failed: readonly CompensationFailure[];
+        };
+    };
+};
+export type ExecuteProbeOutcome = {
+    kind: 'complete';
+    execution: ProbeStepExecution;
+    receipt: ExecutionReceipt;
+    stdout: Buffer;
+    stderr: Buffer;
+} | {
+    kind: 'refusal';
+    code: ExecutionFailureCode;
+    execution: ProbeStepExecution;
+    receipt?: ExecutionReceipt;
+    stdout: Buffer;
+    stderr: Buffer;
+};
+/** The outcome when this executor produced it for exactly `step`; undefined for any other value. */
+export declare function authenticatedExecutionOutcome(outcome: unknown, step: ExecutionStep): ExecuteProbeOutcome | undefined;
+/** Runs one operator/agent session process while retaining ownership of its whole process group. */
+/** Whether a foreground process inherits a terminal on both stdin and stdout, so it may ask for one of its own. */
+export declare function foregroundTerminal(): boolean;
+export declare function executeForegroundProcess(input: ForegroundProcessInput, options?: Readonly<{
+    signal?: AbortSignal;
+}>): Promise<ForegroundProcessOutcome>;
+export declare function executeProbe(step: ExecutionStep, options?: {
+    signal?: AbortSignal;
+}): Promise<ExecuteProbeOutcome>;
+export declare function executePlan(plan: ExecutionPlan, options?: {
+    signal?: AbortSignal;
+}): Promise<ExecutePlanOutcome>;
+export {};