@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/app/init.d.ts

@@ -0,0 +1,143 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { DiagnosticCode } from '../schemas/errors.js';
+import { type InitChoices, type InitExternalAction, type InitPlan } from '../schemas/init.js';
+import { type MachineConfig } from '../schemas/machine.js';
+import { type WorkspaceConfig, type WorkspaceValidation } from '../schemas/workspace.js';
+import type { MachineConfigInspection, WorkspaceConfigInspection } from '../workspace/config.js';
+import { type WorkspaceDiscovery } from '../workspace/discover.js';
+import { type PlannedFileContent } from '../install/plan.js';
+export type InitFailureStatus = 'needs_input' | 'invalid' | 'conflict' | 'unavailable';
+export interface InitFailure {
+    readonly ok: false;
+    readonly status: InitFailureStatus;
+    readonly code: DiagnosticCode;
+    readonly message: string;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly nextAction: string | null;
+}
+export interface InitRootResolution {
+    readonly requestedRoot: string;
+    readonly root: string;
+    readonly registered: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type InitRootResult = {
+    readonly ok: true;
+    readonly value: InitRootResolution;
+} | InitFailure;
+export interface InitContext {
+    readonly requestedRoot: string;
+    readonly root: string;
+    readonly registered: boolean;
+    /** Directory identity captured before inspection and discovery. */
+    readonly rootIdentity: RootIdentity;
+    readonly workspaceInspection: WorkspaceConfigInspection;
+    readonly machineInspection: MachineConfigInspection;
+    readonly discovery: WorkspaceDiscovery;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type InitContextResult = {
+    readonly ok: true;
+    readonly context: InitContext;
+} | InitFailure;
+export interface InitScopeRepository {
+    readonly id: string;
+    readonly path: string;
+    readonly access: 'read' | 'write';
+    readonly external: boolean;
+    readonly root: string | null;
+    readonly kind: string | null;
+    readonly dirty: boolean | null;
+    readonly declaredBy: 'existing' | 'planned';
+}
+export interface InitScope {
+    readonly workspaceRoot: string;
+    readonly workspaceId: string;
+    readonly name: string;
+    readonly runtimeVersion: string;
+    readonly configSource: 'existing' | 'planned';
+    readonly repositories: readonly InitScopeRepository[];
+    readonly knowledge: WorkspaceConfig['knowledge'];
+    readonly code: WorkspaceConfig['code'];
+    readonly validation: readonly WorkspaceValidation[];
+    readonly excludes: readonly string[];
+    readonly hosts: readonly MachineConfig['selectedHosts'][number][];
+    readonly boundaries: readonly string[];
+}
+export interface RootIdentity {
+    readonly dev: number;
+    readonly ino: number;
+}
+export interface InitPlanBundle {
+    readonly plan: InitPlan;
+    readonly scope: InitScope;
+    readonly writes: readonly PlannedFileContent[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** Filesystem identity of the planned workspace root; not persisted in plan JSON. */
+    readonly rootIdentity: RootIdentity;
+}
+export type InitPreparation = {
+    readonly ok: true;
+    readonly bundle: InitPlanBundle;
+} | InitFailure;
+export type InitApplyStatus = 'applied' | 'external-actions-pending' | 'no-changes' | 'stale' | 'conflict' | 'unsupported' | 'failed';
+export interface InitApplyResult {
+    readonly ok: boolean;
+    readonly status: InitApplyStatus;
+    readonly appliedFiles: readonly string[];
+    readonly pendingExternalActions: readonly InitExternalAction[];
+    /** Planned files that could not be safely removed after a failed apply. */
+    readonly residualPaths: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface InitApplyOptions {
+    /** Fault-injection seam for tests; the CLI never supplies this hook. */
+    readonly beforeWrite?: (relativePath: string, index: number) => Promise<void> | void;
+}
+export interface KnowledgeCandidate {
+    readonly path: string;
+    readonly kind: string;
+    readonly origin: string | null;
+    readonly repositoryId: string | null;
+}
+export interface RepositoryCandidate {
+    readonly key: string;
+    readonly id: string | null;
+    readonly external: boolean;
+    readonly access: 'read' | 'write';
+    readonly root: string;
+    readonly kind: string;
+    readonly dirty: boolean | null;
+    readonly configured: boolean;
+}
+export interface PlanInitOptions {
+    readonly root: string;
+    readonly choices?: InitChoices | null;
+    readonly runtimeVersion?: string;
+    readonly planId?: string;
+    readonly discoveredAt?: string;
+    /** Reuse an immediately preceding inspectInitContext result. */
+    readonly context?: InitContext;
+}
+/** Resolves the explicit root and refuses to create a hidden nested workspace. */
+export declare function resolveInitRoot(rootPath: string): Promise<InitRootResult>;
+/**
+ * Loads the discovery inputs and rejects changed or invalid existing state.
+ * This function is read-only.
+ */
+export declare function inspectInitContext(rootPath: string): Promise<InitContextResult>;
+/** Lists discovered repository scope choices for a UI. */
+export declare function listRepositoryCandidates(discovery: WorkspaceDiscovery): readonly RepositoryCandidate[];
+/** Lists knowledge source choices derived only from current discovery. */
+export declare function listKnowledgeCandidates(discovery: WorkspaceDiscovery): readonly KnowledgeCandidate[];
+/**
+ * Produces a strict plan and exact in-memory writes. No target file is created
+ * or modified by this function.
+ */
+export declare function planWorkspaceInit(options: PlanInitOptions): Promise<InitPreparation>;
+/**
+ * Applies only create operations from a plan, after revalidating root,
+ * configuration digest, target absence and exact bytes. External actions are
+ * reported as pending and never executed here.
+ */
+export declare function applyInitPlan(bundle: InitPlanBundle, options?: InitApplyOptions): Promise<InitApplyResult>;