@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/surfaces/projection.d.ts

@@ -0,0 +1,136 @@
+import { type SurfaceTarget } from './contract.js';
+type Mount = 'always' | 'host' | 'none' | `profile:${string}`;
+export interface GuideObservationRequest {
+    readonly slug: string;
+    readonly root: string;
+    readonly sourcePath: string;
+}
+export interface GuideObservation {
+    readonly slug: string;
+    readonly sourcePath: string;
+    readonly sourceEntryType: 'file' | 'symlink';
+    readonly sourceLinkTarget?: string;
+    readonly contentPath: string;
+    readonly content: string;
+    readonly contentBytes: number;
+    readonly contentSha256: string;
+    readonly contentIdentity: string;
+}
+export type GuideObservationResult = {
+    readonly kind: 'complete';
+    readonly observations: readonly GuideObservation[];
+    readonly missing: readonly string[];
+} | {
+    readonly kind: 'refusal' | 'unavailable';
+    readonly diagnostic: ProjectionDiagnostic;
+};
+export interface ProjectionSiblingInput {
+    slug: string;
+    mount: Mount;
+    directoryAuthority: string;
+    declaredOverride?: string;
+    guides?: string[];
+}
+export interface ProjectionPlannerInput {
+    canonicalMainCheckout: string;
+    siblingsRoot: string;
+    invocationCwd?: string;
+    activeProfiles: string[];
+    guideCapLines: number;
+    siblings: ProjectionSiblingInput[];
+    mountedPaths: Array<{
+        slug: string;
+        path: string;
+    }>;
+    directoryGrants: Array<{
+        slug: string;
+        target: SurfaceTarget;
+        path: string;
+    }>;
+    guideObservations: readonly GuideObservation[];
+    standingSources: Array<{
+        target: SurfaceTarget;
+        path: string;
+        content: string;
+        scope: 'always' | 'scoped';
+    }>;
+    loadCharacterizations: Partial<Record<SurfaceTarget, LoadCostCharacterization | undefined>>;
+    /** The tools cockpit.toml lists; grants and start-up costs cover exactly these. Every shipped tool when absent. */
+    targets?: readonly SurfaceTarget[];
+}
+export interface LoadCostCharacterization {
+    measuredOn: string;
+    provenance: string;
+    metric: 'lines';
+    scopeSemantics: 'conditional' | 'full';
+}
+export interface ProjectionDiagnostic {
+    readonly code: 'PROJECTION_INPUT_INVALID' | 'PROJECTION_GUIDE_UNAVAILABLE' | 'PROJECTION_GUIDE_CHANGED' | 'PROJECTION_GUIDE_ESCAPE' | 'PROJECTION_GUIDE_READ_FAILED' | 'PROJECTION_GUIDE_CLOSE_FAILED' | 'PROJECTION_ROOT_AMBIGUOUS' | 'PROJECTION_RESULT_BOUNDS' | 'PROJECTION_MOUNT_MISMATCH' | 'PROJECTION_GRANT_MISMATCH';
+    readonly message: string;
+    readonly target?: string;
+    readonly expected?: string;
+    readonly actual?: string;
+}
+/** A sibling guide copied into the region of the root AGENTS.md that cockpit owns. */
+export interface ProjectedGuide {
+    readonly sibling: string;
+    /** The guide's path inside its sibling, as declared. */
+    readonly guide: string;
+    readonly sourceGuidePath: string;
+    readonly sourceContentIdentity: string;
+    readonly sourceContentSha256: string;
+    /** The block written into the root AGENTS.md: a heading, a provenance marker and the guide's text. */
+    readonly bytes: string;
+}
+export interface ShippedInstructionCapability {
+    readonly target: SurfaceTarget;
+    readonly mechanism: 'root-agents-guide' | 'rulesync-rules';
+    readonly capability: 'instructed' | 'generated';
+    readonly evidence: 'pending_evidence' | 'not_applicable';
+    readonly characterizedOn: string;
+    readonly measuredVersion: string | null;
+    readonly provenance: string;
+}
+export interface DirectoryGrant {
+    readonly slug: string;
+    readonly target: SurfaceTarget;
+    readonly path: string;
+    readonly spelling: string;
+    readonly capability: 'instructed';
+    readonly evidence: 'pending_evidence';
+}
+export type StandingCost = {
+    readonly target: SurfaceTarget;
+    readonly status: 'within_cap' | 'exceeded';
+    readonly metric: 'lines';
+    readonly value: number;
+    readonly conditionalValue: number;
+    readonly cap: number;
+    readonly measuredOn: string;
+    readonly provenance: string;
+    readonly scopeSemantics: 'conditional' | 'full';
+} | {
+    readonly target: SurfaceTarget;
+    readonly status: 'unavailable';
+    readonly reason: string;
+};
+export type ProjectionPlanResult = {
+    readonly kind: 'complete';
+    readonly guides: readonly ProjectedGuide[];
+    readonly grants: readonly DirectoryGrant[];
+    readonly costs: readonly StandingCost[];
+    readonly headline?: {
+        readonly metric: 'lines';
+        readonly value: number;
+        readonly target: SurfaceTarget;
+    };
+} | {
+    readonly kind: 'refusal';
+    readonly diagnostic: ProjectionDiagnostic;
+};
+export declare function observeSiblingGuides(input: unknown): Promise<GuideObservationResult>;
+export declare const SIBLING_GUIDE_MARKER: RegExp;
+export declare function shippedInstructionCapabilities(): readonly ShippedInstructionCapability[];
+export declare function codexWritableRoot(rootRelativePath: string): string;
+export declare function planSiblingProjection(input: unknown): ProjectionPlanResult;
+export {};