@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/init/draft.d.ts

@@ -0,0 +1,138 @@
+import type { Diagnostic } from '../diagnostics.js';
+import { type AnswerProvenance, type UnconfirmedAnswer } from './render.js';
+/**
+ * The directory holding the repositories, and optionally the direct children to observe. A cockpit
+ * created beside a product repository observes only that repository in their shared parent, which
+ * also holds unrelated checkouts that are not part of this estate. A cockpit kept inside a product
+ * repository sets rootIsRepository, so the root's own manifests are observed as the sibling at ".".
+ */
+export interface EstateObservationInput {
+    readonly root: string;
+    readonly repositories?: readonly string[];
+    readonly rootIsRepository?: true;
+}
+export interface EstateObservationAdapters {
+    readonly observe: (input: EstateObservationInput) => Promise<unknown>;
+}
+export type EstateClassification = 'one-sibling' | 'incomplete-multi-repository' | 'no-runnable-product' | 'ready-multi-repository';
+export interface EstateClassificationResult {
+    readonly classification: EstateClassification;
+    readonly sourceObservationSha256: string;
+    readonly notice: string;
+    readonly gaps: readonly Readonly<{
+        field: string;
+        source: string;
+        why: string;
+    }>[];
+    readonly runnable: readonly Readonly<{
+        slug: string;
+        path: string;
+        disposition: 'confirmed' | 'absent' | 'unknown';
+    }>[];
+}
+export type EstateClassificationOutcome = Readonly<{
+    kind: 'complete';
+    status: 0;
+    diagnostics: readonly Diagnostic[];
+    result: EstateClassificationResult;
+}> | Readonly<{
+    kind: 'refusal';
+    status: 2;
+    diagnostics: readonly Diagnostic[];
+    result: null;
+}>;
+interface OutcomeBase {
+    artifact: string | null;
+    destination: string | null;
+    diagnostics: Diagnostic[];
+    result: {
+        document: string;
+        unconfirmed?: readonly UnconfirmedAnswer[];
+    } | null;
+    status: number;
+    question?: DocumentConfigurationQuestion | null;
+}
+export interface CompleteDocumentOutcome extends OutcomeBase {
+    kind: 'complete';
+    artifact: string;
+    result: {
+        document: string;
+        unconfirmed?: readonly UnconfirmedAnswer[];
+    };
+    status: 0;
+}
+export interface GapDraftOutcome extends OutcomeBase {
+    kind: 'gap-draft';
+    artifact: string;
+    result: {
+        document: string;
+    };
+}
+export interface SkippedScopeOutcome extends OutcomeBase {
+    kind: 'skipped-scope';
+    artifact: null;
+    result: null;
+}
+export interface RefusedDocumentOutcome extends OutcomeBase {
+    kind: 'refusal';
+    artifact: null;
+    result: null;
+}
+export type DocumentOutcome = CompleteDocumentOutcome | GapDraftOutcome | SkippedScopeOutcome | RefusedDocumentOutcome;
+export interface DocumentCommandInput {
+    root: string;
+    registry?: string;
+    /** Where init will write cockpit.toml; it is reported back as the outcome's destination. */
+    output?: string;
+    configuration: DocumentConfigurationInput;
+    /** How init observed the estate when it is not the cockpit root's children: a dedicated or an in-repo cockpit. */
+    estate?: EstateObservationInput;
+}
+export type DocumentConfigurationField = 'cockpit.name' | 'sibling' | 'estate.runnable' | 'ports.bases' | 'environment.install_policies' | 'environment.test_data' | 'environment.compose_files' | 'environment.machine' | 'environment.posture' | 'testing' | 'guards' | 'configuration.defaults';
+export interface DocumentConfigurationQuestion {
+    readonly id: `question:${string}`;
+    readonly field: DocumentConfigurationField;
+    readonly source: string;
+    readonly why: string;
+    readonly expectedSha256?: string;
+}
+export type { AnswerProvenance, UnconfirmedAnswer } from './render.js';
+export declare function isAnswerProvenance(value: unknown): value is AnswerProvenance;
+export interface DocumentConfigurationAnswer {
+    readonly questionId: string;
+    readonly bytes: string;
+    readonly sha256: string;
+    readonly provenance: AnswerProvenance;
+}
+export interface DocumentConfigurationInput {
+    readonly sourceObservationSha256: string;
+    readonly classification?: EstateClassification;
+    readonly answers: readonly DocumentConfigurationAnswer[];
+    /** The agent tools the person chose for init; written as surfaces.tools. */
+    readonly tools?: readonly string[];
+}
+export declare function observePublicEstate(input: EstateObservationInput): Promise<unknown>;
+/**
+ * A product repository is a git checkout whose own root carries a public manifest. Running init
+ * there must ask where the cockpit lives, because the answer decides where init writes; an empty,
+ * documents-only or not-yet-versioned directory simply is the cockpit.
+ */
+export declare function observeCockpitRoot(input: Readonly<{
+    root: string;
+}>): Promise<'product-repository' | 'cockpit-root'>;
+export declare function classifyEstateObservation(input: EstateObservationInput, adapters: EstateObservationAdapters): Promise<EstateClassificationOutcome>;
+/**
+ * The questions a greenfield estate interview asks, in order. Init lists them before any answer
+ * exists so an unattended caller can prepare every answer in one pass; the loop in
+ * completeConfigurationDocument asks the same questions in the same order.
+ */
+export declare function plannedGreenfieldQuestions(input: Readonly<{
+    root: string;
+    classification: EstateClassification;
+    gaps: EstateClassificationResult['gaps'];
+}>): readonly Readonly<{
+    field: DocumentConfigurationField;
+    why: string;
+}>[];
+export declare function draftFromRegistry(input: DocumentCommandInput, estateGaps?: EstateClassificationResult['gaps'], estateRunnable?: EstateClassificationResult['runnable']): Promise<DocumentOutcome>;
+export declare function draftFromEstate(input: DocumentCommandInput): Promise<DocumentOutcome>;