@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/sibling-pull.js

@@ -0,0 +1,95 @@
+/**
+ * Owns bringing one checkout up to its upstream, the way a careful person would: fetch, then
+ * fast-forward the branch that is checked out, and nothing else. It never merges, rebases,
+ * stashes, switches branch or touches a modified file; a checkout it cannot fast-forward cleanly
+ * is left exactly as it was and reported with the reason. That is what makes it safe to run
+ * unprompted: the only change it can make is one `git merge --ff-only` would make.
+ */
+import { formatShellCommand } from '../fix-catalogue.js';
+import { parseGitBranchStatus } from './git-observation.js';
+// Keys that make fetch or merge spawn a command the repository's own configuration names. Agents cannot
+// write under `.git`, so this is defence in depth. Git lower-cases section and variable names in its output.
+const COMMAND_KEYS = /^(?:core\.(?:sshcommand|askpass|gitproxy)|credential\.(?:.+\.)?helper|remote\..+\.(?:uploadpack|receivepack))$/;
+async function commandBearingKey(git, path) {
+    const listed = await git.run(path, 'pull:config', ['config', '--list', '--name-only']);
+    if (listed.kind !== 'complete')
+        return { reason: `its Git configuration could not be read (${listed.detail})` };
+    return listed.stdout.split('\n').find(key => COMMAND_KEYS.test(key));
+}
+async function branchStatus(git, path) {
+    const status = await git.run(path, 'pull:status', ['status', '--porcelain=v2', '--branch', '--untracked-files=no']);
+    if (status.kind !== 'complete')
+        return { reason: `git status failed (${status.detail})` };
+    const parsed = parseGitBranchStatus(status.stdout);
+    return parsed.kind === 'complete' ? parsed : { reason: parsed.reason };
+}
+/**
+ * The filter drivers the upstream's attributes name that the repository's own configuration does
+ * not define. cockpit's Git reads no global configuration, where `git lfs install` puts its driver,
+ * and a checkout through an undefined filter writes the stored pointer silently, with no error.
+ */
+async function unconfiguredFilters(git, path) {
+    const named = await git.run(path, 'pull:filters', ['grep', '-h', '-o', '-I', '-E', 'filter=[^[:space:]]+', '@{upstream}', '--', ':(glob)**/.gitattributes']);
+    // grep exits 1 when nothing matches.
+    if (named.kind !== 'complete')
+        return named.exitCode === 1 ? [] : { reason: `its attributes could not be read (${named.detail})` };
+    const drivers = [...new Set(named.stdout.split('\n').map(line => line.trim().slice('filter='.length)).filter(Boolean))];
+    // One call lists every filter variable; git exits 1 when there are none. Section and variable
+    // names are lower-cased in the output, the driver (subsection) keeps its case.
+    const configured = await git.run(path, 'pull:filter-drivers', ['config', '--get-regexp', '^filter\\.']);
+    if (configured.kind !== 'complete' && configured.exitCode !== 1)
+        return { reason: `its Git configuration could not be read (${configured.detail})` };
+    const defined = new Set();
+    for (const line of configured.kind === 'complete' ? configured.stdout.split('\n') : []) {
+        const match = /^filter\.(.+)\.(smudge|process)(?:\s|$)/.exec(line);
+        if (match)
+            defined.add(match[1]);
+    }
+    return drivers.filter(driver => !defined.has(driver));
+}
+export async function fastForwardCheckout(git, path) {
+    const shell = (...args) => formatShellCommand(['git', '-C', path, ...args]);
+    const skipped = (reason, fix, blocked = true) => ({ state: 'skipped', path, reason, fix, blocked });
+    const before = await branchStatus(git, path);
+    if ('reason' in before)
+        return skipped(`it is not a readable Git checkout: ${before.reason}`, `inspect it with ${shell('status')}`);
+    if (before.revision === '(initial)')
+        return skipped('it has no commits yet', `commit in it, or ignore it until it has a history`);
+    if (before.branch === '(detached)')
+        return skipped('HEAD is detached, so there is no branch to move', `check out a branch with ${shell('switch', '<branch>')} if it should follow one`, false);
+    if (before.upstream === null)
+        return skipped(`branch ${before.branch} tracks no upstream`, `set one with ${shell('branch', '--set-upstream-to', '<remote>/<branch>')} if it should follow one`, false);
+    const command = await commandBearingKey(git, path);
+    if (typeof command === 'object')
+        return skipped(command.reason, `inspect it with ${shell('config', '--list')}`);
+    if (command !== undefined)
+        return skipped(`its Git configuration sets ${command}, which would run a command during the fetch`, `review ${shell('config', '--list', '--show-origin')}; if you trust the setting, run ${shell('pull', '--ff-only')} yourself`);
+    const fetched = await git.run(path, 'pull:fetch', ['fetch', '--quiet', '--prune'], { timeoutMs: 120_000 });
+    if (fetched.kind !== 'complete') {
+        return skipped(`fetching ${before.upstream} failed (${fetched.detail})`, `run ${shell('fetch')} yourself to see why; cockpit fetches without the global Git configuration, so a credential helper set only there is not used`);
+    }
+    const after = await branchStatus(git, path);
+    if ('reason' in after)
+        return skipped(`it could not be read after fetching: ${after.reason}`, `inspect it with ${shell('status')}`);
+    const upstream = after.upstream ?? before.upstream;
+    if (!after.adjacencyReported)
+        return skipped(`${upstream}, which ${after.branch} tracks, no longer exists`, `push the branch to recreate it, or stop tracking it with ${shell('branch', '--unset-upstream')}`);
+    if (after.behind === 0)
+        return { state: 'current', path, branch: after.branch, upstream, ahead: after.ahead };
+    if (after.ahead > 0)
+        return skipped(`${after.branch} has diverged from ${upstream} (${after.behind} behind, ${after.ahead} ahead)`, `reconcile it by hand, for example with ${shell('rebase', upstream)}; cockpit only fast-forwards`);
+    if (after.trackedDirtyCount > 0)
+        return skipped(`${after.branch} is ${after.behind} behind ${upstream}, but ${after.trackedDirtyCount} tracked file(s) are modified`, `commit or stash the changes (see ${shell('status', '--short')}), then run pull again; cockpit never moves a checkout with work in it`);
+    const filters = await unconfiguredFilters(git, path);
+    if ('reason' in filters)
+        return skipped(filters.reason, `inspect it with ${shell('check-attr', '-a', '--', '<path>')}`);
+    if (filters.length > 0)
+        return skipped(`it uses the Git filter ${filters.join(', ')} (Git LFS, for one), which is configured only outside the repository, `
+            + 'so a fast-forward here would check out its placeholder files instead of their content', `run ${shell('pull', '--ff-only')} yourself`);
+    const merged = await git.run(path, 'pull:fast-forward', ['merge', '--ff-only', '--quiet', '@{upstream}'], { timeoutMs: 120_000 });
+    if (merged.kind !== 'complete')
+        return skipped(`fast-forwarding ${after.branch} to ${upstream} failed (${merged.detail})`, `run ${shell('merge', '--ff-only', '@{upstream}')} yourself to see what is in the way`);
+    const head = await git.run(path, 'pull:head', ['rev-parse', 'HEAD']);
+    return { state: 'advanced', path, branch: after.branch, upstream, from: after.revision,
+        to: head.kind === 'complete' ? head.stdout : 'unknown', commits: after.behind };
+}

package/dist/environment/stack-inputs.d.ts

@@ -0,0 +1,18 @@
+import type { CockpitConfig } from '../schema.js';
+import { type EnvironmentDiagnostic } from './contract.js';
+import { type ServedSibling } from './sibling-checkouts.js';
+/**
+ * Record the inputs of every sibling the stack mounts; a warning, never a refusal, when that fails.
+ * With `keepExisting`, a record already there stays: the stack it describes is still the one running.
+ */
+export declare function recordStackInputs(cockpitRoot: string, config: Pick<CockpitConfig, 'sibling' | 'environment'>, served: ReadonlyMap<string, ServedSibling>, options: Readonly<{
+    keepExisting: boolean;
+}>): Promise<readonly EnvironmentDiagnostic[]>;
+/** Forget the record once no stack runs, so a later doctor compares nothing against a stack that is gone. */
+export declare function forgetStackInputs(cockpitRoot: string): Promise<readonly EnvironmentDiagnostic[]>;
+/**
+ * One warning per mounted sibling whose served checkout, lockfiles or declared rebuild inputs differ
+ * from what the running stack started with. Nothing recorded means no stack came up since the last
+ * `down`, and is no finding.
+ */
+export declare function staleStackDiagnostics(cockpitRoot: string, served: ReadonlyMap<string, ServedSibling>): Promise<readonly EnvironmentDiagnostic[]>;

package/dist/environment/stack-inputs.js

@@ -0,0 +1,210 @@
+/**
+ * Owns the stale-stack detector: what each mounted sibling's dependencies and schema looked like
+ * when the stack came up, and whether they still do. A bind mount follows a pulled branch at once,
+ * but installed dependencies usually live in an image or a volume built before it and a database
+ * keeps the schema it was migrated to, so a stack that kept running after a lockfile or migration
+ * changed fails like a product bug and its tests pass against code nobody is running.
+ *
+ * It decides nothing: `up` records, `down` and a stopping `sleep` forget, and doctor and preflight
+ * warn. The record is machine-local beside the sibling checkout record, under `.cockpit/local`.
+ */
+import { lstatIfPresent } from './presence.js';
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, readlink, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readBoundedFile } from '../bounded-read.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { sha256Hex } from '../sha256.js';
+import { GUARD_LOCAL_PATHS, writeCockpitLocalFiles } from '../guards/local-identity.js';
+import { ENVIRONMENT_CODES, errorCause, hasErrorCode, RefusalError, tryParseJson } from './contract.js';
+import { mapLimit } from './map-limit.js';
+import { servedPath } from './sibling-checkouts.js';
+const FORMAT = 'cockpit-stack-inputs/v1';
+const RECORD_NAME = 'stack-inputs';
+const RECORD_PATH = `${GUARD_LOCAL_PATHS.directory}/${RECORD_NAME}`;
+const RECORD_MAX_BYTES = 1_048_576;
+// A migrations directory is small; one this large is the wrong path, and hashing it would stall every doctor.
+const DIRECTORY_ENTRY_LIMIT = 20_000;
+// Each in-flight digest may hold a file descriptor.
+const DIGEST_CONCURRENCY = 16;
+// The lockfiles the common toolchains write, watched when no install policy names the sibling's.
+const COMMON_LOCKFILES = Object.freeze([
+    'package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb',
+    'poetry.lock', 'uv.lock', 'Pipfile.lock', 'pdm.lock', 'Gemfile.lock', 'go.sum', 'Cargo.lock',
+    'composer.lock', 'packages.lock.json', 'mix.lock',
+]);
+// Directory hashes name each entry relative to the directory, so moving a checkout is no change.
+async function digestPath(path) {
+    let status;
+    try {
+        status = await lstat(path);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT', 'ENOTDIR'))
+            return null;
+        throw error;
+    }
+    if (status.isSymbolicLink())
+        return sha256Hex(`link\0${await readlink(path)}`);
+    if (status.isFile())
+        return sha256Hex(await readFile(path));
+    if (!status.isDirectory())
+        return sha256Hex(`other\0${status.mode}`);
+    const hash = createHash('sha256');
+    // Entries are digested concurrently but folded into the hash in sorted order, so the digest is deterministic.
+    let entries = 0;
+    const walk = async (directory, prefix) => {
+        const listed = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name < right.name ? -1 : 1);
+        entries += listed.length;
+        if (entries > DIRECTORY_ENTRY_LIMIT)
+            throw new RefusalError(`${path} holds more than ${DIRECTORY_ENTRY_LIMIT} entries`);
+        return (await mapLimit(listed, DIGEST_CONCURRENCY, async (entry) => {
+            const relative = `${prefix}${entry.name}`;
+            return entry.isDirectory()
+                ? [`dir\0${relative}\0`, ...await walk(join(directory, entry.name), `${relative}/`)]
+                : [`${relative}\0${await digestPath(join(directory, entry.name))}\0`];
+        })).flat();
+    };
+    for (const line of await walk(path, ''))
+        hash.update(line);
+    return hash.digest('hex');
+}
+async function exists(path) {
+    return await lstatIfPresent(path) !== undefined;
+}
+/** The paths watched for one sibling and where each came from: its own list, then the toolchain's lockfiles. */
+async function watchedInputs(config, sibling, served) {
+    const declared = (sibling.rebuild_inputs ?? []).map(path => ({ path, source: 'rebuild_inputs' }));
+    const policies = config.environment.install_policies.filter(policy => policy.toolchain === sibling.toolchain)
+        .map(policy => ({ path: policy.lockfile, source: 'environment.install_policies' }));
+    // Without a policy only the lockfiles present at up are watched; one created later is a new
+    // toolchain, which a person adds to install_policies.
+    const common = policies.length > 0 ? [] : (await Promise.all(COMMON_LOCKFILES.map(async (path) => await exists(join(served, path)) ? [{ path, source: 'common lockfile names' }] : []))).flat();
+    const seen = new Set();
+    return [...declared, ...policies, ...common].filter(row => !seen.has(row.path) && seen.add(row.path));
+}
+function stackSiblings(config) {
+    return config.sibling.filter(sibling => sibling.mount === 'always' || sibling.mount.startsWith('profile:'));
+}
+/**
+ * Record the inputs of every sibling the stack mounts; a warning, never a refusal, when that fails.
+ * With `keepExisting`, a record already there stays: the stack it describes is still the one running.
+ */
+export async function recordStackInputs(cockpitRoot, config, served, options) {
+    try {
+        if (options.keepExisting) {
+            try {
+                await lstat(join(cockpitRoot, RECORD_PATH));
+                return [];
+            }
+            catch (error) {
+                if (!hasErrorCode(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+        const siblings = await Promise.all(stackSiblings(config).map(async (sibling) => {
+            const directory = servedPath(served, sibling.slug);
+            const inputs = await Promise.all((await watchedInputs(config, sibling, directory)).map(async (row) => ({ ...row, sha256: await digestPath(join(directory, row.path)) })));
+            return { slug: sibling.slug, served: directory, inputs };
+        }));
+        const record = { format: FORMAT, recordedAt: new Date().toISOString(), siblings };
+        const written = await writeCockpitLocalFiles(cockpitRoot, [{ name: RECORD_NAME, bytes: `${JSON.stringify(record)}\n` }]);
+        if (written.kind !== 'complete')
+            throw new RefusalError(written.message);
+        return [];
+    }
+    catch (error) {
+        return [unrecorded(`the lockfiles and declared rebuild inputs could not be recorded (${errorCause(error)})`)];
+    }
+}
+function unrecorded(reason) {
+    return {
+        severity: 'warning',
+        code: 'STACK_INPUTS_UNRECORDED',
+        message: `${reason}, so doctor and preflight cannot tell when this stack falls behind its siblings' dependencies or migrations`,
+        target: RECORD_PATH,
+        fix: `run ${cockpitCommand('down')} and ${cockpitCommand('up')} to record them again`,
+    };
+}
+/** Forget the record once no stack runs, so a later doctor compares nothing against a stack that is gone. */
+export async function forgetStackInputs(cockpitRoot) {
+    try {
+        await rm(join(cockpitRoot, RECORD_PATH), { force: true });
+        return [];
+    }
+    catch (error) {
+        return [{
+                severity: 'warning',
+                code: 'STACK_INPUTS_UNRECORDED',
+                message: `the stack stopped, but ${join(cockpitRoot, RECORD_PATH)} could not be removed (${errorCause(error)}), so doctor may still compare against it`,
+                target: RECORD_PATH,
+                fix: `delete ${join(cockpitRoot, RECORD_PATH)}`,
+            }];
+    }
+}
+function decode(bytes) {
+    const value = tryParseJson(bytes.toString('utf8'));
+    const text = (field) => typeof field === 'string' && field.length > 0;
+    if (!value || typeof value !== 'object' || value.format !== FORMAT || !text(value.recordedAt) || !Array.isArray(value.siblings)
+        || !value.siblings.every(row => row && text(row.slug) && text(row.served) && Array.isArray(row.inputs)
+            && row.inputs.every((input) => input && text(input.path) && text(input.source) && (input.sha256 === null || text(input.sha256)))))
+        return undefined;
+    return value;
+}
+/**
+ * One warning per mounted sibling whose served checkout, lockfiles or declared rebuild inputs differ
+ * from what the running stack started with. Nothing recorded means no stack came up since the last
+ * `down`, and is no finding.
+ */
+export async function staleStackDiagnostics(cockpitRoot, served) {
+    const path = join(cockpitRoot, RECORD_PATH);
+    let bytes;
+    try {
+        const read = readBoundedFile(path, RECORD_MAX_BYTES);
+        if (read.kind === 'too-large')
+            return [unrecorded(`${path} is not a record cockpit wrote`)];
+        bytes = read.bytes;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return [];
+        if (hasErrorCode(error, 'ELOOP', 'EISDIR'))
+            return [unrecorded(`${path} is not a record cockpit wrote`)];
+        return [unrecorded(`${path} could not be read (${errorCause(error)})`)];
+    }
+    const record = decode(bytes);
+    if (!record)
+        return [unrecorded(`${path} is not a record cockpit wrote`)];
+    const findings = await Promise.all(record.siblings.map(async (sibling) => {
+        const current = served.get(sibling.slug);
+        if (!current)
+            return undefined;
+        let changes;
+        if (current.served !== sibling.served)
+            changes = [`it is now served from ${current.served}`];
+        else {
+            changes = (await mapLimit(sibling.inputs, DIGEST_CONCURRENCY, async (input) => {
+                let digest;
+                try {
+                    digest = await digestPath(join(sibling.served, input.path));
+                }
+                catch (error) {
+                    return `${input.path} (${input.source}) could not be read: ${errorCause(error)}`;
+                }
+                return digest === input.sha256 ? undefined : `${input.path} (${input.source}) ${digest === null ? 'was removed' : input.sha256 === null ? 'was created' : 'changed'}`;
+            })).filter(change => change !== undefined);
+        }
+        if (changes.length === 0)
+            return undefined;
+        return {
+            severity: 'warning',
+            code: 'STACK_INPUTS_CHANGED',
+            message: `the stack came up at ${record.recordedAt} with sibling ${sibling.slug} from ${sibling.served}; since then ${changes.join(', ')}, `
+                + 'so its services may still run the old dependencies, schema or code',
+            target: `sibling:${sibling.slug}`,
+            fix: `run ${cockpitCommand('down')} and then ${cockpitCommand('up')} so every service starts on the current files; `
+                + 'a service whose image installs the dependencies needs that image rebuilt before up',
+        };
+    }));
+    return findings.filter(finding => finding !== undefined);
+}

package/dist/environment/stack-inventory-prune.d.ts

@@ -0,0 +1,31 @@
+import { type Executor, type StacksContext, type StacksInput, type StacksOutcome } from './stack-inventory-report.js';
+/**
+ * Whose orphans a prune removes. An agent's `--apply` passes this cockpit's `[autonomy]` policy, which
+ * says nothing for another cockpit's stacks, so it covers this cockpit's stacks and the state folders
+ * earlier builds left; a person who approved the preview covers the machine.
+ */
+export type StacksPruneScope = 'this-cockpit' | 'machine';
+/** What a person or an agent approves: the exact prune a fresh observation shows, and how to apply it. */
+export interface StacksPruneSession {
+    readonly preview: StacksOutcome;
+    /** The digest of the whole preview, which a person types to approve it. */
+    readonly digest: string;
+    /** Whether the scope the session applies holds nothing to remove, and whether it deletes volumes. */
+    readonly empty: boolean;
+    readonly deletesData: boolean;
+    apply(): Promise<StacksOutcome>;
+}
+/**
+ * Observes the machine and plans the prune of every orphaned stack and state folder. The preview lists
+ * them all; `apply` removes those in `scope`, after observing again and only while that part of the plan
+ * still has the digest it had at the preview: containers first, then networks and volumes, then the
+ * state that holds the port lease, then unreadable state folders. A failed step stops the prune and
+ * keeps the state, so the stack stays listed and the next prune resumes it.
+ */
+export declare function beginStacksPrune(input: StacksInput, scope: StacksPruneScope, dependencies: Readonly<{
+    execute: Executor;
+}>): Promise<StacksPruneSession | StacksOutcome>;
+/** The prune of an already identified checkout's machine: what `beginStacksPrune` opens once the context is loaded. */
+export declare function openStacksPrune(context: StacksContext, scope: StacksPruneScope, dependencies: Readonly<{
+    execute: Executor;
+}>): Promise<StacksPruneSession | StacksOutcome>;

package/dist/environment/stack-inventory-prune.js

@@ -0,0 +1,129 @@
+/**
+ * `cockpit stacks prune`: plans the removal of every orphaned stack and unreadable state folder the
+ * inventory shows, binds the plan to a digest, and removes exactly that plan once it is approved.
+ */
+import { randomUUID } from 'node:crypto';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { sha256Hex } from '../sha256.js';
+import { ENVIRONMENT_CODES } from './contract.js';
+import { holderId } from './identity.js';
+import { machineStackRemovalSteps } from './reclaim.js';
+import { loadStacksContext, observeWithDocker, refusalStatus } from './stack-inventory-report.js';
+import { removeStackState, removeStateNamespaceFolder } from './state.js';
+function plannedRow({ row, resources, files }) {
+    const named = (kind) => resources.filter((resource) => resource.kind === kind).map(({ name }) => name);
+    return { cockpitId: row.cockpitId, stackId: row.stackId, checkout: row.checkout, reason: row.reason,
+        containers: named('container'), networks: named('network'), volumes: named('volume'), stateFiles: files.map(({ path }) => path) };
+}
+function planOf(observed, inScope) {
+    const stacks = observed.stacks.filter(({ row }) => row.verdict === 'orphaned' && inScope(row));
+    const folders = observed.folders.filter(({ row }) => row.verdict === 'orphaned');
+    // The digest binds the exact resources and file bytes, so an approval covers only what was shown.
+    const bound = {
+        stacks: stacks.map(({ row, resources, files }) => ({ cockpitId: row.cockpitId, stackId: row.stackId,
+            resources: resources.map(({ kind, id }) => `${kind}:${id}`), files: files.map(({ kind, path, sha256 }) => `${kind}:${path}:${sha256}`) })),
+        folders: folders.map(({ row, fingerprint }) => `${row.path}:${fingerprint}`),
+    };
+    return { stacks, folders, digest: sha256Hex(JSON.stringify(bound)),
+        deletesData: stacks.some(({ resources }) => resources.some(({ kind }) => kind === 'volume')) };
+}
+function otherCockpitsWarning(stacks, configPath) {
+    if (stacks.length === 0)
+        return [];
+    return [{ severity: 'warning', target: 'stacks',
+            code: 'STACKS_PRUNE_UNCONFIRMED',
+            message: `orphaned stacks of other cockpits are removed only with a person's approval, because this cockpit's [autonomy] policy does not speak for them; an agent's --apply leaves ${stacks.map(({ row }) => row.stackId).join(', ')}`,
+            fix: `a person runs ${cockpitCommand('stacks prune', { config: configPath, args: '--interactive' })} in a terminal outside CI, reads the preview and types its digest` }];
+}
+// Containers first, so no network or volume is still held when its removal runs.
+const PRUNE_ORDER = ['container', 'network', 'volume'];
+/**
+ * Observes the machine and plans the prune of every orphaned stack and state folder. The preview lists
+ * them all; `apply` removes those in `scope`, after observing again and only while that part of the plan
+ * still has the digest it had at the preview: containers first, then networks and volumes, then the
+ * state that holds the port lease, then unreadable state folders. A failed step stops the prune and
+ * keeps the state, so the stack stays listed and the next prune resumes it.
+ */
+export async function beginStacksPrune(input, scope, dependencies) {
+    const context = await loadStacksContext(input, dependencies.execute);
+    return 'kind' in context ? refusalStatus(context) : openStacksPrune(context, scope, dependencies);
+}
+/** The prune of an already identified checkout's machine: what `beginStacksPrune` opens once the context is loaded. */
+export async function openStacksPrune(context, scope, dependencies) {
+    const observed = await observeWithDocker(context, dependencies.execute);
+    if ('kind' in observed)
+        return refusalStatus(observed);
+    const thisCockpit = (row) => row.cockpitId === context.own.cockpitId;
+    const inScope = scope === 'machine' ? () => true : thisCockpit;
+    const whole = planOf(observed, () => true);
+    const plan = planOf(observed, inScope);
+    const kept = observed.inventory.stacks.filter(({ verdict }) => verdict !== 'orphaned').length;
+    const summary = { digest: whole.digest, deletesData: whole.deletesData,
+        stacks: whole.stacks.map((stack) => ({ ...plannedRow(stack), thisCockpit: thisCockpit(stack.row) })),
+        stateFolders: whole.folders.map(({ row }) => ({ path: row.path, reason: row.reason })), kept };
+    const wholeEmpty = whole.stacks.length === 0 && whole.folders.length === 0;
+    return {
+        digest: whole.digest, empty: plan.stacks.length === 0 && plan.folders.length === 0, deletesData: plan.deletesData,
+        preview: { status: 0, diagnostics: otherCockpitsWarning(whole.stacks.filter(({ row }) => !thisCockpit(row)), context.configPath),
+            result: { dryRun: true, ...summary, apply: wholeEmpty ? null : cockpitCommand('stacks prune', { config: context.configPath, args: '--apply' }) } },
+        apply: async () => {
+            const again = await observeWithDocker(context, dependencies.execute);
+            if ('kind' in again)
+                return refusalStatus(again);
+            const current = planOf(again, inScope);
+            if (current.digest !== plan.digest)
+                return { status: 2, result: null, diagnostics: [{ severity: 'error', target: 'stacks',
+                            code: 'STACKS_PRUNE_UNCONFIRMED',
+                            message: 'the orphaned stacks changed between the preview and the removal, so nothing was removed',
+                            fix: `preview again with ${cockpitCommand('stacks prune', { config: context.configPath })} and approve the new preview` }] };
+            const ownerId = holderId({ stackId: context.own.stackId, checkoutId: context.own.checkoutId, sessionId: randomUUID() });
+            const removed = [];
+            const incomplete = (what) => ({ status: 2, result: { removed }, diagnostics: [{ severity: 'error', target: 'stacks',
+                        code: 'STACKS_PRUNE_INCOMPLETE',
+                        message: `prune stopped: ${what}; what it had not removed is still listed`,
+                        fix: `inspect the named resource, then run ${cockpitCommand('stacks prune', { config: context.configPath, args: '--apply' })} again to resume` }] });
+            for (const stack of current.stacks) {
+                for (const kind of PRUNE_ORDER) {
+                    const batch = stack.resources.filter((resource) => resource.kind === kind);
+                    if (batch.length === 0)
+                        continue;
+                    const removals = machineStackRemovalSteps(context.docker, again.selection, batch) ?? [{ step: undefined, resources: batch }];
+                    for (const { step, resources } of removals) {
+                        const outcome = step === undefined ? undefined : authenticatedExecutionOutcome(await dependencies.execute(step), step);
+                        if (outcome?.kind !== 'complete')
+                            return incomplete(`docker could not remove ${kind} ${resources.map(({ name }) => name).join(', ')} of ${stack.row.stackId}${outcome ? ` (${outcome.code})` : ''}`);
+                    }
+                }
+                if (stack.namespace !== undefined && stack.files.length > 0) {
+                    const state = await removeStackState(stack.namespace, stack.row.stackId, stack.files, { ownerId });
+                    if (state.kind !== 'complete')
+                        return incomplete(`the state of ${stack.row.stackId} could not be removed: ${state.kind === 'refusal' ? state.message : 'it disappeared'}`);
+                    if (state.value.kind === 'changed')
+                        return incomplete(state.value.reason);
+                }
+                removed.push(plannedRow(stack));
+            }
+            const folders = [];
+            for (const { row, fingerprint } of current.folders) {
+                const folder = await removeStateNamespaceFolder(context.namespace, row.path, fingerprint, { ownerId });
+                if (folder.kind !== 'complete')
+                    return incomplete(`${row.path} could not be removed: ${folder.kind === 'refusal' ? folder.message : 'it disappeared'}`);
+                if (folder.value.kind === 'changed')
+                    return incomplete(folder.value.reason);
+                folders.push(row.path);
+            }
+            // The removal is reported only once a fresh observation no longer lists what was removed.
+            const after = await observeWithDocker(context, dependencies.execute);
+            if ('kind' in after)
+                return refusalStatus(after);
+            const left = planOf(after, inScope);
+            const remaining = removed.filter(({ cockpitId, stackId }) => left.stacks.some(({ row }) => row.cockpitId === cockpitId && row.stackId === stackId));
+            if (remaining.length > 0 || left.folders.some(({ row }) => folders.includes(row.path))) {
+                return incomplete(`a fresh inventory still lists ${remaining.map(({ stackId }) => stackId).join(', ') || 'a removed state folder'}`);
+            }
+            return { status: 0, diagnostics: otherCockpitsWarning(planOf(after, (row) => !inScope(row)).stacks, context.configPath),
+                result: { digest: plan.digest, removed, removedStateFolders: folders } };
+        },
+    };
+}

package/dist/environment/stack-inventory-report.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `cockpit stacks`: identifies the checkout running the command, observes the machine through the
+ * local Docker daemon, and lists every stack with its verdict. It changes nothing; the prune in
+ * `stack-inventory-prune.ts` opens from the same context.
+ */
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type Diagnostic, type ExecutionStep } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+import { checkoutId as deriveCheckoutId } from './identity.js';
+import { type Observation, type OwnCheckout, type Refusal } from './stack-inventory.js';
+import { type StateNamespace } from './state.js';
+export type Executor = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+/** What `cockpit stacks` and its prune are run with: the configuration and the caller's environment. */
+export interface StacksInput {
+    readonly configPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface StacksContext {
+    readonly configPath: string;
+    readonly namespace: StateNamespace;
+    readonly own: OwnCheckout & Readonly<{
+        checkoutId: ReturnType<typeof deriveCheckoutId>;
+    }>;
+    readonly docker: Readonly<{
+        executable: ResolvedExecutable;
+        context: string;
+        host?: string;
+        cwd: string;
+        env: Readonly<Record<string, string>>;
+        timeoutMs: number;
+    }>;
+}
+export declare function loadStacksContext({ configPath, env }: StacksInput, execute: Executor): Promise<StacksContext | Refusal>;
+export declare function observeWithDocker(context: StacksContext, execute: Executor): Promise<Observation | Refusal>;
+export interface StacksOutcome {
+    readonly status: number;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function refusalStatus(refusal: Refusal): StacksOutcome;
+/** `cockpit stacks`: lists every stack this machine knows about, and changes nothing. */
+export declare function runStacksInventory(input: StacksInput, dependencies: Readonly<{
+    execute: Executor;
+}>): Promise<StacksOutcome>;

package/dist/environment/stack-inventory-report.js

@@ -0,0 +1,78 @@
+import { loadCockpitConfig } from '../config/load.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { ENVIRONMENT_CODES } from './contract.js';
+import { selectLocalDockerDaemon } from './docker-daemon.js';
+import { resolveDockerExecutable, resolveGitExecutable } from './executable.js';
+import { checkoutId as deriveCheckoutId, stackId as deriveStackId } from './identity.js';
+import { discoverMachineStacks } from './reclaim.js';
+import { consumeSetupCheckoutProjection, observeSetupCheckout, withSetupCheckoutProjection } from './setup-observation.js';
+import { observeMachineStacks, refuse } from './stack-inventory.js';
+import { selectStateRoot } from './state.js';
+const STEP_TIMEOUT_MS = 10_000;
+export async function loadStacksContext({ configPath, env }, execute) {
+    const loaded = await loadCockpitConfig(configPath);
+    if (loaded.kind !== 'complete')
+        return { kind: 'refusal', diagnostics: loaded.diagnostics };
+    const source = loaded.result.source;
+    if (process.platform !== 'darwin' && process.platform !== 'linux')
+        return refuse(ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE, 'cockpit state is kept on macOS or Linux only', process.platform);
+    const git = await resolveGitExecutable(env);
+    if (git.state !== 'available')
+        return refuse(ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID, git.reason, 'git');
+    const observedAt = new Date().toISOString();
+    const observed = await observeSetupCheckout({ source, cockpitName: loaded.result.config.cockpit.name, observedAt,
+        env: Object.fromEntries(Object.entries(env).filter((entry) => typeof entry[1] === 'string')), gitExecutable: git.value });
+    if (observed.state === 'failed')
+        return refuse(observed.code, observed.reason, source.path);
+    const checkout = await withSetupCheckoutProjection(observed, { source, cockpitName: loaded.result.config.cockpit.name,
+        evaluatedAt: Date.parse(observedAt) }, consumeSetupCheckoutProjection);
+    if (!checkout)
+        return refuse(ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID, 'the checkout running this command could not be identified', source.path);
+    const namespace = await selectStateRoot({ platform: process.platform, home: env.HOME, xdgStateHome: env.XDG_STATE_HOME,
+        checkoutRoots: [checkout.currentCheckoutPath, checkout.mainCheckoutPath], cockpitId: checkout.cockpitId });
+    if (namespace.kind !== 'complete')
+        return namespace.kind === 'refusal' ? refuse(namespace.code, namespace.message, namespace.target)
+            : refuse(ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE, 'the state root is unavailable', source.path);
+    // Prune deletes, so the daemon is fixed once, as for down and reset, and every step addresses it.
+    const daemon = await selectLocalDockerDaemon(env, STEP_TIMEOUT_MS, execute, { command: 'stacks',
+        localOnly: 'the inventory and its prune describe this machine, which a remote daemon says nothing about' });
+    if (daemon.kind === 'refusal')
+        return { kind: 'refusal', diagnostics: [daemon.diagnostic] };
+    const docker = await resolveDockerExecutable(env);
+    if (docker.state !== 'available')
+        return refuse(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, docker.reason, 'docker');
+    return {
+        configPath: source.path, namespace: namespace.value,
+        own: { cockpitId: checkout.cockpitId, checkoutId: checkout.checkoutId, mainCheckoutPath: checkout.mainCheckoutPath,
+            stackId: deriveStackId({ cockpitId: checkout.cockpitId, checkoutId: checkout.checkoutId, variant: { kind: 'shared' } }) },
+        docker: { executable: docker.value, context: daemon.dockerContext, ...(env.DOCKER_HOST === undefined ? {} : { host: env.DOCKER_HOST }),
+            cwd: checkout.currentCheckoutPath, env: { PATH: env.PATH ?? '' }, timeoutMs: STEP_TIMEOUT_MS },
+    };
+}
+export async function observeWithDocker(context, execute) {
+    const discovery = await discoverMachineStacks(context.docker, execute);
+    if (discovery === undefined)
+        return refuse(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, `the containers, networks and volumes cockpit labels could not be listed on Docker context ${context.docker.context}`, 'docker', 'start Docker, or select the local context that runs cockpit stacks, then retry');
+    return observeMachineStacks({ namespace: context.namespace, own: context.own, discovery });
+}
+export function refusalStatus(refusal) {
+    return { status: 2, result: null, diagnostics: refusal.diagnostics };
+}
+/** `cockpit stacks`: lists every stack this machine knows about, and changes nothing. */
+export async function runStacksInventory(input, dependencies) {
+    const context = await loadStacksContext(input, dependencies.execute);
+    if ('kind' in context)
+        return refusalStatus(context);
+    const observed = await observeWithDocker(context, dependencies.execute);
+    if ('kind' in observed)
+        return refusalStatus(observed);
+    const orphaned = observed.inventory.stacks.filter(({ verdict }) => verdict === 'orphaned').length
+        + observed.inventory.stateFolders.filter(({ verdict }) => verdict === 'orphaned').length;
+    return { status: 0, result: observed.inventory, diagnostics: orphaned === 0 ? [] : [orphanedWarning(orphaned, context.configPath)] };
+}
+function orphanedWarning(count, configPath) {
+    return { severity: 'warning', target: 'stacks',
+        code: 'STACKS_ORPHANED',
+        message: `${count === 1 ? '1 stack or state folder on this machine is' : `${count} stacks or state folders on this machine are`} orphaned: its checkout is gone or its state cannot be read, and it still holds containers, volumes, a port lease or state`,
+        fix: `preview the removal with ${cockpitCommand('stacks prune', { config: configPath })}, then apply it with --apply` };
+}