@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/surfaces/merge.js

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { snapshotJson } from '../environment/contract.js';
+import { SurfaceDeclaration, SurfaceOverlay } from '../schema.js';
+function immutable(value) {
+    return snapshotJson(value);
+}
+function isObject(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function refusal(code, message) {
+    return immutable({ kind: 'refusal', code, message });
+}
+function canonicalDeclaration(declaration) {
+    return {
+        name: declaration.name,
+        feature: declaration.feature,
+        sources: declaration.sources.map((source) => ({ path: source.path, bytes: source.bytes })),
+        source: declaration.source,
+        ...(declaration.replaces ? { replaces: declaration.replaces } : {}),
+    };
+}
+export function surfaceDeclarationSha256(declaration) {
+    return createHash('sha256').update(JSON.stringify(canonicalDeclaration(declaration))).digest('hex');
+}
+function duplicateName(declarations) {
+    const names = new Set();
+    for (const declaration of declarations) {
+        if (names.has(declaration.name))
+            return declaration.name;
+        names.add(declaration.name);
+    }
+    return undefined;
+}
+function compareName(left, right) {
+    return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+}
+export function mergeSurfaceDeclarations(coreInput, overlayInput) {
+    const captured = snapshotJson({ core: coreInput, overlays: overlayInput });
+    if (!isObject(captured)) {
+        return refusal('SURFACE_INPUT_INVALID', 'core and overlay declarations must be bounded immutable data');
+    }
+    const coreResult = SurfaceDeclaration.array().safeParse(captured.core);
+    const overlayResult = SurfaceOverlay.array().safeParse(captured.overlays);
+    if (!coreResult.success || !overlayResult.success) {
+        return refusal('SURFACE_INPUT_INVALID', 'core or overlay declarations are invalid');
+    }
+    const core = coreResult.data;
+    const overlays = overlayResult.data;
+    const repeated = duplicateName(core) ?? duplicateName(overlays);
+    if (repeated)
+        return refusal('SURFACE_NAME_DUPLICATE', `surface name "${repeated}" is declared more than once`);
+    if (core.some((declaration) => declaration.replaces)) {
+        return refusal('SURFACE_OVERRIDE_INVALID', 'core declarations cannot replace another surface');
+    }
+    const resolved = new Map(core.map((declaration) => [declaration.name, declaration]));
+    const overrides = [];
+    const findings = [];
+    for (const overlay of overlays) {
+        const original = resolved.get(overlay.name);
+        if (!original) {
+            if (overlay.replaces)
+                return refusal('SURFACE_OVERRIDE_INVALID', `override "${overlay.name}" has no core original`);
+            resolved.set(overlay.name, overlay);
+            continue;
+        }
+        if (original.feature !== overlay.feature) {
+            return refusal('SURFACE_KIND_AMBIGUOUS', `surface "${overlay.name}" changes feature from ${original.feature} to ${overlay.feature}`);
+        }
+        if (!overlay.replaces || overlay.replaces.name !== overlay.name) {
+            return refusal('SURFACE_OVERRIDE_INVALID', `surface "${overlay.name}" collides with core without an explicit replacement`);
+        }
+        const originalSha256 = surfaceDeclarationSha256(original);
+        overrides.push({
+            name: overlay.name,
+            feature: overlay.feature,
+            originalSha256,
+            recordedSha256: overlay.replaces.sha256,
+            overlaySource: overlay.source,
+        });
+        if (originalSha256 !== overlay.replaces.sha256) {
+            findings.push({
+                code: 'OVERRIDDEN_CORE_CHANGED',
+                name: overlay.name,
+                recordedSha256: overlay.replaces.sha256,
+                currentSha256: originalSha256,
+                overlaySource: overlay.source,
+            });
+        }
+        resolved.set(overlay.name, overlay);
+    }
+    const paths = new Map();
+    const surfaces = [...resolved.values()];
+    for (const declaration of surfaces) {
+        for (const source of declaration.sources) {
+            const owner = paths.get(source.path);
+            if (owner)
+                return refusal('SURFACE_PATH_CONFLICT', `surface path "${source.path}" is owned by both "${owner}" and "${declaration.name}"`);
+            paths.set(source.path, declaration.name);
+        }
+    }
+    surfaces.sort(compareName);
+    overrides.sort(compareName);
+    findings.sort(compareName);
+    return immutable({ kind: 'complete', surfaces, overrides, findings });
+}

package/dist/surfaces/ownership.d.ts

@@ -0,0 +1,190 @@
+export type SurfaceOwnership = 'whole-file' | 'shared-region';
+export type SurfaceScope = 'always' | 'scoped';
+export type SurfaceCapability = 'enforced' | 'instructed';
+interface SurfaceEntryBase {
+    readonly path: string;
+    readonly harnesses: readonly [string, ...string[]];
+    readonly scope: SurfaceScope;
+    readonly capability: SurfaceCapability;
+    readonly writer: 'cockpit';
+    readonly schemaVersion: 1;
+}
+export interface OpenCodeRootMember {
+    readonly key: string;
+    readonly valueBytes: string;
+}
+export type SurfaceDesiredEntry = Readonly<SurfaceEntryBase & {
+    kind: 'file';
+    ownership: 'whole-file';
+    bytes: string;
+    sha256: string;
+}> | Readonly<SurfaceEntryBase & {
+    kind: 'shared-region';
+    ownership: 'shared-region';
+    regionId: string;
+    region: Readonly<{
+        format: 'markdown-delimited';
+        begin: string;
+        end: string;
+        bytes: string;
+        sha256: string;
+    } | {
+        format: 'opencode-json-root-properties';
+        members: readonly OpenCodeRootMember[];
+        sha256: string;
+    }>;
+}>;
+export type SurfacePriorOwnedEntry = Readonly<SurfaceEntryBase & {
+    kind: 'file';
+    ownership: 'whole-file';
+    sha256: string;
+}> | Readonly<SurfaceEntryBase & {
+    kind: 'shared-region';
+    ownership: 'shared-region';
+    regionId: string;
+    region: Readonly<{
+        format: 'markdown-delimited';
+        begin: string;
+        end: string;
+        sha256: string;
+    } | {
+        format: 'opencode-json-root-properties';
+        keys: readonly string[];
+        sha256: string;
+    }>;
+}>;
+export interface SurfaceDiagnostic {
+    readonly code: 'SURFACE_INPUT_INVALID' | 'SURFACE_BOUNDS' | 'SURFACE_PATH_CONFLICT' | 'SURFACE_OWNERSHIP_INVALID' | 'SURFACE_STATE_CONFLICT';
+    readonly message: string;
+    readonly target?: string;
+    readonly fix?: string;
+}
+export declare const SURFACE_HAND_EDIT_FIX = "keep the edit by moving it into cockpit.toml or a surface overlay, then ask the person who owns the cockpit before you discard the hand edit (undo it or delete the file), and rerun npx --no cockpit sync --config <your cockpit.toml>";
+export declare const SURFACE_UNRECORDED_FIX = "ask the person who owns the cockpit whether this file is theirs; move anything they want kept into cockpit.toml or a surface overlay, and only with their approval move the file away or delete it, then rerun npx --no cockpit sync --config <your cockpit.toml>";
+export type SurfaceOwnershipResult = Readonly<{
+    kind: 'complete';
+    entries: readonly SurfaceDesiredEntry[];
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: SurfaceDiagnostic;
+}>;
+export interface SurfaceOwnershipInput {
+    readonly configuredHarnesses: readonly string[];
+    readonly entries: readonly SurfaceDesiredEntry[];
+}
+export declare function bindSurfaceOwnershipIdentity(entries: readonly SurfaceDesiredEntry[], cockpitId: string): SurfaceOwnershipResult;
+export declare function classifySurfaceOwnership(input: unknown): SurfaceOwnershipResult;
+export declare function captureOpenCodeRootMembers(bytes: string): readonly OpenCodeRootMember[] | undefined;
+export type SharedPostimageResult = Readonly<{
+    kind: 'complete';
+    bytes: string;
+}> | Extract<SurfaceOwnershipResult, {
+    kind: 'refusal';
+}>;
+export declare function renderSharedPostimage(existingBytes: string, entry: SurfaceDesiredEntry, priorOwned?: OwnershipEntry, manifest?: OwnershipManifest): SharedPostimageResult;
+export declare function removeSharedOwnership(existingBytes: string, priorOwned: OwnershipEntry, manifest?: OwnershipManifest): SharedPostimageResult;
+export type OwnershipEntry = Readonly<{
+    kind: 'file';
+    path: string;
+    ownership: 'whole-file';
+    sha256: string;
+}> | SurfacePriorOwnedEntry;
+export type EnvironmentOwnershipEntry = Readonly<{
+    kind: 'file';
+    path: string;
+    ownership: 'whole-file';
+    sha256: string;
+}>;
+export interface GeneratedProducer {
+    readonly package: string;
+    readonly version: string;
+    readonly sourceRevision: string;
+}
+export interface OwnershipManifestPayload {
+    readonly format: 'cockpit-generated-ownership/v3';
+    readonly producer: GeneratedProducer;
+    readonly cockpitId: string;
+    readonly generation: string;
+    readonly source: Readonly<{
+        path: string;
+        sha256: string;
+    }>;
+    readonly entries: readonly OwnershipEntry[];
+}
+export interface OwnershipManifest extends OwnershipManifestPayload {
+    readonly integrity: string;
+}
+export interface OwnershipAuthority {
+    readonly root: string;
+    readonly cockpitId: string;
+    readonly configPath: string;
+}
+export interface OwnershipManifestInput extends OwnershipAuthority {
+    readonly generation: string;
+    readonly sourceSha256: string;
+    readonly owned: readonly Readonly<{
+        path: string;
+        sha256: string;
+    }>[];
+    readonly surfaces: readonly SurfaceDesiredEntry[];
+}
+export type OwnershipManifestResult = Readonly<{
+    kind: "complete";
+    manifest: OwnershipManifest;
+}> | Readonly<{
+    kind: "invalid";
+}> | Readonly<{
+    kind: "unsupported";
+    format: string;
+}>;
+export declare function parseOwnershipManifest(bytes: string, authority: OwnershipAuthority): OwnershipManifestResult;
+export declare function encodeOwnershipManifest(prepared: OwnershipManifestInput): Readonly<{
+    bytes: string;
+    manifest: OwnershipManifest;
+}>;
+export type GeneratedPathProducer = 'generated-environment' | 'environment-data-plane' | 'surface-render';
+export type GeneratedPathApplicability = 'declared-before-sync' | 'sibling-unavailable' | 'required-after-sync';
+export type GeneratedPathDeclaration = Readonly<{
+    producer: GeneratedPathProducer;
+    applicability: 'declared-before-sync' | 'required-after-sync';
+    entry: OwnershipEntry;
+}> | Readonly<{
+    producer: GeneratedPathProducer;
+    applicability: 'sibling-unavailable';
+    path: string;
+}>;
+export interface GeneratedPathFact {
+    readonly path: string;
+    readonly authority: OwnershipAuthority & Readonly<{
+        generation: string;
+        source: OwnershipManifest['source'];
+        integrity: string;
+    }>;
+    readonly entry: OwnershipEntry;
+    readonly declaration: GeneratedPathDeclaration | null;
+    readonly allowsMissing: boolean;
+    readonly harnesses: readonly string[];
+    readonly scope: SurfaceScope;
+    readonly ownership: SurfaceOwnership;
+}
+export type GeneratedPathFactsResult = Readonly<{
+    kind: 'complete';
+    facts: readonly GeneratedPathFact[];
+}> | Extract<SurfaceOwnershipResult, {
+    kind: 'refusal';
+}>;
+export declare function projectGeneratedPathFacts(manifest: OwnershipManifest, authority: OwnershipAuthority, declarations: unknown): GeneratedPathFactsResult;
+export interface GeneratedPathClassification {
+    readonly fact: GeneratedPathFact;
+    readonly state: 'unchanged' | 'modified' | 'unknown' | 'missing';
+    readonly rawSha256?: string;
+    readonly diagnostics: readonly SurfaceDiagnostic[];
+}
+export type GeneratedPathClassificationResult = Readonly<{
+    kind: 'complete';
+    paths: readonly GeneratedPathClassification[];
+}> | Extract<SurfaceOwnershipResult, {
+    kind: 'refusal';
+}>;
+export declare function classifyGeneratedPaths(facts: readonly GeneratedPathFact[], observations: unknown): GeneratedPathClassificationResult;
+export {};