@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/surfaces/sync.js

@@ -0,0 +1,164 @@
+import { sha256Hex } from '../sha256.js';
+import { snapshotGeneratedJson } from '../environment/contract.js';
+import { ADOPTABLE_SURFACE_PATHS, safeSurfacePath as safePath } from './contract.js';
+import { classifySurfaceOwnership, removeSharedOwnership, renderSharedPostimage, SURFACE_HAND_EDIT_FIX, SURFACE_UNRECORDED_FIX, } from './ownership.js';
+import { exactKeys } from '../exact-keys.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+function object(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function refuse(message, target, fix) {
+    return { kind: 'refusal', diagnostic: { code: 'SURFACE_STATE_CONFLICT', message,
+            ...(target === undefined ? {} : { target }), ...(fix === undefined ? {} : { fix }) } };
+}
+function base(value, configured) {
+    const harnesses = value.harnesses;
+    return typeof value.path === 'string' && safePath(value.path) && Array.isArray(harnesses) && harnesses.length > 0
+        && harnesses.every((harness, index) => typeof harness === 'string' && configured.has(harness) && (index === 0 || harnesses[index - 1] < harness))
+        && (value.scope === 'always' || value.scope === 'scoped') && (value.capability === 'enforced' || value.capability === 'instructed')
+        && value.writer === 'cockpit' && value.schemaVersion === 1;
+}
+function priorEntry(value, configured) {
+    if (!object(value) || !base(value, configured) || typeof value.kind !== 'string' || typeof value.ownership !== 'string')
+        return undefined;
+    if (value.kind === 'file') {
+        return exactKeys(value, ['kind', 'path', 'harnesses', 'scope', 'capability', 'writer', 'schemaVersion', 'ownership', 'sha256'])
+            && value.ownership === 'whole-file' && typeof value.sha256 === 'string' && SHA256.test(value.sha256)
+            ? value : undefined;
+    }
+    if (value.kind !== 'shared-region' || value.ownership !== 'shared-region'
+        || !exactKeys(value, ['kind', 'path', 'harnesses', 'scope', 'capability', 'writer', 'schemaVersion', 'ownership', 'regionId', 'region'])
+        || typeof value.regionId !== 'string' || !object(value.region) || typeof value.region.sha256 !== 'string' || !SHA256.test(value.region.sha256))
+        return undefined;
+    if (value.region.format === 'markdown-delimited') {
+        return exactKeys(value.region, ['format', 'begin', 'end', 'sha256']) && typeof value.region.begin === 'string' && typeof value.region.end === 'string'
+            ? value : undefined;
+    }
+    const keys = value.region.keys;
+    return value.region.format === 'opencode-json-root-properties' && exactKeys(value.region, ['format', 'keys', 'sha256'])
+        && Array.isArray(keys) && keys.length > 0 && keys.every((key, index) => typeof key === 'string' && (index === 0 || keys[index - 1] < key))
+        ? value : undefined;
+}
+function observedEntry(value) {
+    if (!object(value) || typeof value.path !== 'string' || !safePath(value.path) || typeof value.kind !== 'string')
+        return undefined;
+    if (value.kind === 'missing')
+        return exactKeys(value, ['path', 'kind']) ? value : undefined;
+    if (value.kind === 'file')
+        return exactKeys(value, ['path', 'kind', 'bytes', 'sha256', 'identity']) && typeof value.bytes === 'string'
+            && typeof value.sha256 === 'string' && value.sha256 === sha256Hex(value.bytes) && typeof value.identity === 'string' && value.identity.length > 0
+            ? value : undefined;
+    if (value.kind === 'symlink')
+        return exactKeys(value, ['path', 'kind', 'target', 'identity']) && typeof value.target === 'string'
+            && typeof value.identity === 'string' && value.identity.length > 0 ? value : undefined;
+    return value.kind === 'other' && exactKeys(value, ['path', 'kind', 'identity']) && typeof value.identity === 'string' && value.identity.length > 0
+        ? value : undefined;
+}
+function priorMatchesObserved(prior, observed) {
+    if (prior.kind === 'file')
+        return observed.kind === 'file' && observed.sha256 === prior.sha256;
+    return observed.kind === 'file';
+}
+export function planSurfaceChanges(input) {
+    const captured = snapshotGeneratedJson(input);
+    if (!object(captured) || !exactKeys(captured, ['configuredHarnesses', 'desired', 'priorOwned', 'observed'])
+        || !Array.isArray(captured.configuredHarnesses) || !Array.isArray(captured.desired)
+        || !Array.isArray(captured.priorOwned) || captured.priorOwned.length > 256
+        || !Array.isArray(captured.observed) || captured.observed.length > 257)
+        return refuse('surface change input must be bounded exact data');
+    const ownership = classifySurfaceOwnership({ configuredHarnesses: captured.configuredHarnesses, entries: captured.desired });
+    if (ownership.kind === 'refusal')
+        return ownership;
+    const configured = new Set(captured.configuredHarnesses);
+    const prior = [];
+    const observed = [];
+    let priorPath = '';
+    for (const candidate of captured.priorOwned) {
+        const entry = priorEntry(candidate, configured);
+        if (!entry || entry.path <= priorPath)
+            return refuse('prior ownership rows must be valid, unique and sorted');
+        priorPath = entry.path;
+        prior.push(entry);
+    }
+    let observedPath = '';
+    for (const candidate of captured.observed) {
+        const entry = observedEntry(candidate);
+        if (!entry || entry.path <= observedPath)
+            return refuse('observed rows must be valid, unique and sorted');
+        observedPath = entry.path;
+        observed.push(entry);
+    }
+    const desiredByPath = new Map(ownership.entries.map(entry => [entry.path, entry]));
+    const priorByPath = new Map(prior.map(entry => [entry.path, entry]));
+    const observedByPath = new Map(observed.map(entry => [entry.path, entry]));
+    if (desiredByPath.has('opencode.jsonc')) {
+        const alternate = observedByPath.get('opencode.json');
+        if (alternate && alternate.kind !== 'missing' && !priorByPath.has('opencode.json'))
+            return refuse('unmanaged alternate OpenCode configuration exists', 'opencode.json');
+    }
+    const writes = [];
+    for (const desired of ownership.entries) {
+        const current = observedByPath.get(desired.path) ?? { path: desired.path, kind: 'missing' };
+        const previous = priorByPath.get(desired.path);
+        if (desired.kind === 'file' && current.kind === 'file' && current.sha256 === desired.sha256) {
+            if (!previous || !priorMatchesObserved(previous, current))
+                return refuse('this path already holds exactly what sync would write, but no ownership record names it, so sync cannot tell whether cockpit or a person put it there', desired.path, SURFACE_UNRECORDED_FIX);
+            continue;
+        }
+        if (desired.kind === 'shared-region') {
+            if (current.kind === 'missing') {
+                const baseBytes = desired.region.format === 'opencode-json-root-properties' ? '{}' : '';
+                const rendered = renderSharedPostimage(baseBytes, desired);
+                if (rendered.kind === 'refusal')
+                    return rendered;
+                writes.push({ kind: 'write', path: desired.path, desired, postimage: rendered.bytes });
+                continue;
+            }
+            if (current.kind !== 'file')
+                return refuse('shared surface path is not a regular file', desired.path);
+            const rendered = renderSharedPostimage(current.bytes, desired, previous);
+            if (rendered.kind === 'refusal')
+                return rendered;
+            if (rendered.bytes !== current.bytes)
+                writes.push({ kind: 'write', path: desired.path, desired, postimage: rendered.bytes,
+                    preimage: { identity: current.identity, sha256: current.sha256 } });
+            continue;
+        }
+        if (current.kind !== 'missing' && !previous && ADOPTABLE_SURFACE_PATHS.includes(desired.path)) {
+            return refuse('this harness settings file exists but cockpit has no record of writing it', desired.path, `to keep the settings it holds, have a human approve npx --no cockpit sync --config <your cockpit.toml> --adopt ${desired.path}`);
+        }
+        if (current.kind !== 'missing' && !previous)
+            return refuse('this path holds a file cockpit has no record of writing', desired.path, SURFACE_UNRECORDED_FIX);
+        if (current.kind !== 'missing' && previous && !priorMatchesObserved(previous, current)) {
+            return refuse('this generated file was edited by hand since cockpit last wrote it, and sync does not overwrite hand edits', desired.path, SURFACE_HAND_EDIT_FIX);
+        }
+        writes.push({ kind: 'write', path: desired.path, desired,
+            ...(current.kind === 'missing' ? {} : { preimage: { identity: current.identity, ...(current.kind === 'file' ? { sha256: current.sha256 } : {}) } }) });
+    }
+    const removals = [];
+    for (const stale of prior) {
+        if (desiredByPath.has(stale.path))
+            continue;
+        const current = observedByPath.get(stale.path) ?? { path: stale.path, kind: 'missing' };
+        if (current.kind === 'missing') {
+            removals.push({ kind: 'already-absent', path: stale.path, priorOwned: stale });
+            continue;
+        }
+        if (stale.kind === 'shared-region') {
+            if (current.kind !== 'file')
+                return refuse('stale shared surface changed kind', stale.path);
+            const rendered = removeSharedOwnership(current.bytes, stale);
+            if (rendered.kind === 'refusal')
+                return rendered;
+            removals.push({ kind: 'remove', path: stale.path, priorOwned: stale, postimage: rendered.bytes,
+                preimage: { identity: current.identity, sha256: current.sha256 } });
+            continue;
+        }
+        if (!priorMatchesObserved(stale, current))
+            return refuse('stale owned surface changed', stale.path, SURFACE_HAND_EDIT_FIX);
+        removals.push({ kind: 'remove', path: stale.path, priorOwned: stale,
+            preimage: { identity: current.identity, ...(current.kind === 'file' ? { sha256: current.sha256 } : {}) } });
+    }
+    const result = snapshotGeneratedJson({ kind: 'complete', actions: [...writes, ...removals] });
+    return result ? result : refuse('surface change plan exceeds the captured bounds');
+}

package/dist/team-metadata.d.ts

@@ -0,0 +1,41 @@
+import { type EnvironmentDiagnostic } from './environment/contract.js';
+export interface TeamMetadataChange {
+    readonly operation: 'write';
+    readonly path: string;
+}
+export type TeamMetadataResult = Readonly<{
+    kind: 'complete';
+    changed: boolean;
+    changes: readonly TeamMetadataChange[];
+}> | Readonly<{
+    kind: 'refusal';
+    code: EnvironmentDiagnostic['code'];
+    message: string;
+    target: string;
+    fix?: string;
+}>;
+/**
+ * The package manifest without the entries sync owns in it: the cockpit dependency, under any spec,
+ * and each cockpit script while it is the exact command sync writes. Sections those removals leave
+ * empty are dropped, so a manifest cockpit created and one it edited project the same way.
+ */
+export declare function productPackageManifest(manifest: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export interface TeamMetadataAuthority {
+    readonly changes: readonly TeamMetadataChange[];
+}
+export declare function prepareTeamMetadata(configPath: string): Promise<Extract<TeamMetadataResult, {
+    kind: 'refusal';
+}> | Readonly<{
+    kind: 'complete';
+    authority: TeamMetadataAuthority;
+}>>;
+export declare function applyTeamMetadata(prepared: TeamMetadataAuthority): Promise<TeamMetadataResult>;
+export declare function validateTeamMetadata(configPath: string): Promise<TeamMetadataResult>;
+/**
+ * What a teammate's clone of this cockpit, or the cockpit itself, will lack, read from the
+ * cockpit root and its declaration without changing anything. `init` runs from a temporary copy of
+ * cockpit and leaves none in the cockpit, so every printed `npx --no cockpit` then failed and the
+ * guard hook stayed bound to that copy; and a sibling repository recorded without a remote is one
+ * a teammate's `setup` silently leaves absent.
+ */
+export declare function inspectTeamReadiness(configPath: string): Promise<readonly EnvironmentDiagnostic[]>;