@b00dea/cockpit 0.0.0-stage → 0.1.1

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 {};