@tomflow/proflow-platform-cli 0.1.0

package/dist/src/docs/docs.d.ts

@@ -0,0 +1,47 @@
+import type { ModuleDescriptor } from "@tomflow/proflow-module-contract";
+import type { ModuleSource } from "../modules.ts";
+export interface PublishedCommand {
+    name: string;
+    target: string;
+}
+export interface PublicApiEntry {
+    subpath: string;
+    target?: string;
+}
+export interface ModuleDocsView {
+    moduleRef: string;
+    packageName: string;
+    moduleVersion: string;
+    kind: ModuleDescriptor["kind"];
+    installClass: ModuleDescriptor["installClass"];
+    identity: ModuleDescriptor["identity"];
+    commands: PublishedCommand[];
+    publicApiEntries: PublicApiEntry[];
+    provides: ModuleDescriptor["provides"];
+    requires: ModuleDescriptor["requires"];
+    requirements: ModuleDescriptor["requirements"];
+    configSlots: ModuleDescriptor["configSlots"];
+    lifecycle: ModuleDescriptor["lifecycle"]["supported"];
+    verification: ModuleDescriptor["verification"];
+    effects: ModuleDescriptor["effects"];
+    documentation: ModuleDescriptor["documentation"];
+}
+export interface ModuleDocumentContent {
+    moduleRef: string;
+    packageName: string;
+    documentId: string;
+    path: string;
+    description?: string;
+    content: string;
+}
+export declare function describeModule(input: {
+    workspaceRoot: string;
+    source: ModuleSource;
+    descriptor: ModuleDescriptor;
+}): Promise<ModuleDocsView>;
+export declare function readModuleDocument(input: {
+    workspaceRoot: string;
+    source: ModuleSource;
+    descriptor: ModuleDescriptor;
+    documentId: string;
+}): Promise<ModuleDocumentContent>;

package/dist/src/docs/docs.js

@@ -0,0 +1,129 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PlatformError } from "../errors.js";
+function executableName(packageName) {
+    return packageName.split("/").pop() ?? packageName;
+}
+function commandsFrom(manifest, packageName) {
+    if (typeof manifest.bin === "string") {
+        return [{ name: executableName(packageName), target: manifest.bin }];
+    }
+    if (typeof manifest.bin !== "object" || manifest.bin === null)
+        return [];
+    return Object.entries(manifest.bin)
+        .flatMap(([name, target]) => typeof target === "string" ? [{ name, target }] : [])
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function publicApiEntriesFrom(manifest) {
+    if (typeof manifest.exports === "string") {
+        return [{ subpath: ".", target: manifest.exports }];
+    }
+    if (typeof manifest.exports !== "object" || manifest.exports === null)
+        return [];
+    return Object.entries(manifest.exports)
+        .filter(([subpath]) => subpath.startsWith("."))
+        .map(([subpath, target]) => ({
+        subpath,
+        ...(typeof target === "string" ? { target } : {}),
+    }))
+        .sort((left, right) => left.subpath.localeCompare(right.subpath));
+}
+async function packageRootFor(workspaceRoot, source) {
+    if (source.type === "workspace") {
+        if (source.path === undefined) {
+            throw new PlatformError("DESCRIPTOR_INVALID", `workspace source missing path for ${source.packageName}`);
+        }
+        return await realpath(source.path);
+    }
+    const require = createRequire(pathToFileURL(join(workspaceRoot, "package.json")));
+    let current;
+    try {
+        current = dirname(require.resolve(`${source.packageName}/deployment/descriptor`));
+    }
+    catch (error) {
+        throw new PlatformError("DESCRIPTOR_INVALID", `cannot resolve installed package ${source.packageName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (;;) {
+        try {
+            const manifest = JSON.parse(await readFile(join(current, "package.json"), "utf8"));
+            if (manifest.name === source.packageName)
+                return await realpath(current);
+        }
+        catch {
+            // Export maps commonly hide package.json; keep walking from a resolved
+            // package-owned descriptor until the package root is found.
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new PlatformError("DESCRIPTOR_INVALID", `package root not found for ${source.packageName}`);
+}
+async function readManifest(packageRoot, packageName) {
+    try {
+        const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+        if (manifest.name !== packageName) {
+            throw new Error(`expected package ${packageName}`);
+        }
+        return manifest;
+    }
+    catch (error) {
+        throw new PlatformError("DESCRIPTOR_INVALID", `invalid package metadata for ${packageName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function describeModule(input) {
+    const packageRoot = await packageRootFor(input.workspaceRoot, input.source);
+    const manifest = await readManifest(packageRoot, input.descriptor.packageName);
+    return {
+        moduleRef: input.descriptor.moduleRef,
+        packageName: input.descriptor.packageName,
+        moduleVersion: input.descriptor.moduleVersion,
+        kind: input.descriptor.kind,
+        installClass: input.descriptor.installClass,
+        identity: input.descriptor.identity,
+        commands: commandsFrom(manifest, input.descriptor.packageName),
+        publicApiEntries: publicApiEntriesFrom(manifest),
+        provides: input.descriptor.provides,
+        requires: input.descriptor.requires,
+        requirements: input.descriptor.requirements,
+        configSlots: input.descriptor.configSlots,
+        lifecycle: input.descriptor.lifecycle.supported,
+        verification: input.descriptor.verification,
+        effects: input.descriptor.effects,
+        documentation: input.descriptor.documentation,
+    };
+}
+export async function readModuleDocument(input) {
+    const entry = input.descriptor.documentation.find((candidate) => candidate.id === input.documentId);
+    if (entry === undefined) {
+        throw new PlatformError("INVALID_REQUEST", `document "${input.documentId}" is not declared by ${input.descriptor.moduleRef}`);
+    }
+    const packageRoot = await packageRootFor(input.workspaceRoot, input.source);
+    const root = resolve(packageRoot);
+    const target = resolve(root, entry.path);
+    if (target === root || !target.startsWith(`${root}${sep}`)) {
+        throw new PlatformError("DESCRIPTOR_INVALID", `documentation path escapes package root for ${input.descriptor.moduleRef}`);
+    }
+    try {
+        const info = await stat(target);
+        if (!info.isFile())
+            throw new Error("not a file");
+        const content = await readFile(target, "utf8");
+        return {
+            moduleRef: input.descriptor.moduleRef,
+            packageName: input.descriptor.packageName,
+            documentId: entry.id,
+            path: entry.path,
+            ...(entry.description === undefined
+                ? {}
+                : { description: entry.description }),
+            content,
+        };
+    }
+    catch (error) {
+        throw new PlatformError("DESCRIPTOR_INVALID", `cannot read document ${entry.id} for ${input.descriptor.moduleRef}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/src/docs/index.d.ts

@@ -0,0 +1 @@
+export * from "./docs.ts";

package/dist/src/docs/index.js

@@ -0,0 +1 @@
+export * from "./docs.js";

package/dist/src/doctor/doctor.d.ts

@@ -0,0 +1,41 @@
+import type { DeploymentCheck, DeploymentError, ModuleOperationResult } from "@tomflow/proflow-module-contract";
+import type { ResolvedModule } from "../contracts.ts";
+import type { ModuleCatalog } from "../modules.ts";
+export type DoctorNextAction = {
+    kind: "none";
+} | {
+    kind: "human-action";
+    action: string;
+    description: string;
+} | {
+    kind: "repair-plan";
+    summary: string;
+};
+export interface DoctorReport {
+    moduleRef: string;
+    moduleVersion: string;
+    status: ModuleOperationResult["status"];
+    checks: DeploymentCheck[];
+    errors: DeploymentError[];
+    evidenceRefs: string[];
+    nextAction: DoctorNextAction;
+    observedEffects: string[];
+}
+/**
+ * Maps a doctor result to the recommended next step. Doctor only recommends:
+ * it never performs a repair. A failing or blocked module yields a `repair-plan`
+ * recommendation (to be followed by `plan --intent repair` → confirm → apply);
+ * an ACTION_REQUIRED result yields the recoverable human action as-is.
+ */
+export declare function nextActionOf(result: ModuleOperationResult): DoctorNextAction;
+/**
+ * Diagnoses a single module by dispatching its public `doctor` primitive. The
+ * report carries live checks, typed errors, evidence refs, and a recommended
+ * next action — but performs no side effects and never auto-repairs.
+ */
+export declare function doctorModule(catalog: ModuleCatalog, module: ResolvedModule): Promise<DoctorReport>;
+/**
+ * Diagnoses every module that declares the `doctor` primitive; modules without
+ * it are skipped.
+ */
+export declare function doctorModules(catalog: ModuleCatalog, modules: readonly ResolvedModule[]): Promise<DoctorReport[]>;

package/dist/src/doctor/doctor.js

@@ -0,0 +1,80 @@
+import { dispatchLifecycle } from "../lifecycle/index.js";
+/**
+ * Maps a doctor result to the recommended next step. Doctor only recommends:
+ * it never performs a repair. A failing or blocked module yields a `repair-plan`
+ * recommendation (to be followed by `plan --intent repair` → confirm → apply);
+ * an ACTION_REQUIRED result yields the recoverable human action as-is.
+ */
+export function nextActionOf(result) {
+    switch (result.status) {
+        case "SUCCEEDED":
+            return { kind: "none" };
+        case "ACTION_REQUIRED": {
+            const action = result.actionRequired;
+            if (action !== undefined) {
+                return {
+                    kind: "human-action",
+                    action: action.action,
+                    description: action.description,
+                };
+            }
+            return {
+                kind: "repair-plan",
+                summary: "action required but unspecified",
+            };
+        }
+        case "BLOCKED":
+        case "FAILED": {
+            const summary = result.error !== undefined
+                ? `${result.error.code}: ${result.error.message}`
+                : `module ${result.moduleRef} is ${result.status.toLowerCase()}`;
+            return { kind: "repair-plan", summary };
+        }
+    }
+}
+/**
+ * Diagnoses a single module by dispatching its public `doctor` primitive. The
+ * report carries live checks, typed errors, evidence refs, and a recommended
+ * next action — but performs no side effects and never auto-repairs.
+ */
+export async function doctorModule(catalog, module) {
+    const primitives = ["status", "verify", "doctor"].filter((primitive) => module.lifecycle.includes(primitive));
+    const dispatched = [];
+    for (const primitive of primitives) {
+        dispatched.push(await dispatchLifecycle(catalog, module, primitive));
+    }
+    const severity = {
+        SUCCEEDED: 0,
+        ACTION_REQUIRED: 1,
+        BLOCKED: 2,
+        FAILED: 3,
+    };
+    const effective = dispatched
+        .map((item) => item.result)
+        .reduce((worst, current) => severity[current.status] > severity[worst.status] ? current : worst);
+    const checks = dispatched.flatMap((item) => item.result.checks ?? []);
+    const errors = dispatched.flatMap((item) => item.result.error === undefined ? [] : [item.result.error]);
+    return {
+        moduleRef: module.moduleRef,
+        moduleVersion: module.moduleVersion,
+        status: effective.status,
+        checks,
+        errors,
+        evidenceRefs: checks.map((check) => `check:${check.id}:${check.status}`),
+        nextAction: nextActionOf(effective),
+        observedEffects: dispatched.flatMap((item) => item.observedEffects),
+    };
+}
+/**
+ * Diagnoses every module that declares the `doctor` primitive; modules without
+ * it are skipped.
+ */
+export async function doctorModules(catalog, modules) {
+    const reports = [];
+    for (const module of modules) {
+        if (!module.lifecycle.includes("doctor"))
+            continue;
+        reports.push(await doctorModule(catalog, module));
+    }
+    return reports;
+}

package/dist/src/doctor/index.d.ts

@@ -0,0 +1,2 @@
+export type { DoctorNextAction, DoctorReport } from "./doctor.ts";
+export { doctorModule, doctorModules, nextActionOf } from "./doctor.ts";

package/dist/src/doctor/index.js

@@ -0,0 +1 @@
+export { doctorModule, doctorModules, nextActionOf } from "./doctor.js";

package/dist/src/errors.d.ts

@@ -0,0 +1,6 @@
+export declare const platformErrorCodes: readonly ["INVALID_REQUEST", "DESCRIPTOR_INVALID", "DUPLICATE_IDENTITY", "DEPENDENCY_UNRESOLVED", "DEPENDENCY_INCOMPATIBLE", "DEPENDENCY_CYCLE", "CONFIG_MISSING", "SECRET_REF_INVALID", "PLAN_STALE", "PLAN_NOT_FOUND", "PLAN_INVALID", "WORKSPACE_LOCKED", "LIFECYCLE_UNSUPPORTED", "SECRET_LEAK", "APPLY_FAILED", "UPGRADE_FAILED", "CORE_PACKAGE_REQUIRED", "UNINSTALL_FAILED", "VERIFY_FAILED", "REGISTRY_UNAVAILABLE", "REGISTRY_AUTH_REQUIRED", "REGISTRY_RESPONSE_INVALID", "PACKAGE_NOT_FOUND", "PACKAGE_NOT_PROFLOW", "COMMAND_FAILED"];
+export type PlatformErrorCode = (typeof platformErrorCodes)[number];
+export declare class PlatformError extends Error {
+    readonly code: PlatformErrorCode;
+    constructor(code: PlatformErrorCode, message: string);
+}

package/dist/src/errors.js

@@ -0,0 +1,35 @@
+export const platformErrorCodes = [
+    "INVALID_REQUEST",
+    "DESCRIPTOR_INVALID",
+    "DUPLICATE_IDENTITY",
+    "DEPENDENCY_UNRESOLVED",
+    "DEPENDENCY_INCOMPATIBLE",
+    "DEPENDENCY_CYCLE",
+    "CONFIG_MISSING",
+    "SECRET_REF_INVALID",
+    "PLAN_STALE",
+    "PLAN_NOT_FOUND",
+    "PLAN_INVALID",
+    "WORKSPACE_LOCKED",
+    "LIFECYCLE_UNSUPPORTED",
+    "SECRET_LEAK",
+    "APPLY_FAILED",
+    "UPGRADE_FAILED",
+    "CORE_PACKAGE_REQUIRED",
+    "UNINSTALL_FAILED",
+    "VERIFY_FAILED",
+    "REGISTRY_UNAVAILABLE",
+    "REGISTRY_AUTH_REQUIRED",
+    "REGISTRY_RESPONSE_INVALID",
+    "PACKAGE_NOT_FOUND",
+    "PACKAGE_NOT_PROFLOW",
+    "COMMAND_FAILED",
+];
+export class PlatformError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PlatformError";
+    }
+}

package/dist/src/graph/graph.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedModule } from "../contracts.ts";
+export type DependencyEdgeKind = "moduleRef" | "capability";
+export interface DependencyEdge {
+    from: string;
+    to: string;
+    kind: DependencyEdgeKind;
+    contractRef?: string;
+}
+export interface DependencyGraph {
+    nodes: string[];
+    edges: DependencyEdge[];
+    order: string[];
+}
+export interface GraphOptions {
+    config?: Record<string, Record<string, string>>;
+}
+export declare class ModuleRefUnresolvedError extends Error {
+    readonly code: "MODULE_REF_UNRESOLVED";
+    readonly from: string;
+    readonly target: string;
+    constructor(from: string, target: string, message: string);
+}
+export declare function buildDependencyGraph(modules: readonly ResolvedModule[], options?: GraphOptions): DependencyGraph;

package/dist/src/graph/graph.js

@@ -0,0 +1,132 @@
+import { PlatformError } from "../errors.js";
+import { versionSatisfies } from "../modules.js";
+export class ModuleRefUnresolvedError extends Error {
+    code = "MODULE_REF_UNRESOLVED";
+    from;
+    target;
+    constructor(from, target, message) {
+        super(message);
+        this.from = from;
+        this.target = target;
+        this.name = "ModuleRefUnresolvedError";
+    }
+}
+function compareRef(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function buildDependencyGraph(modules, options = {}) {
+    const nodes = [...new Set(modules.map((module) => module.moduleRef))].sort(compareRef);
+    const nodeSet = new Set(nodes);
+    const providersByContract = new Map();
+    for (const module of modules) {
+        for (const provide of module.provides) {
+            const list = providersByContract.get(provide.contractRef) ?? [];
+            list.push({ moduleRef: module.moduleRef, version: provide.version });
+            providersByContract.set(provide.contractRef, list);
+        }
+    }
+    const edges = [];
+    const edgeSet = new Set();
+    const addEdge = (from, to, kind, contractRef) => {
+        const key = `${kind}|${from}|${to}|${contractRef ?? ""}`;
+        if (edgeSet.has(key))
+            return;
+        edgeSet.add(key);
+        const edge = { from, to, kind };
+        if (contractRef !== undefined)
+            edge.contractRef = contractRef;
+        edges.push(edge);
+    };
+    const sorted = [...modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
+    for (const module of sorted) {
+        for (const slot of module.configSlots) {
+            if (slot.type !== "moduleRef")
+                continue;
+            const effective = options.config?.[module.moduleRef]?.[slot.key] ?? slot.default;
+            if (typeof effective !== "string")
+                continue;
+            if (!nodeSet.has(effective)) {
+                throw new ModuleRefUnresolvedError(module.moduleRef, effective, `moduleRef binding ${slot.key}=${effective} for ${module.moduleRef} does not resolve to a selected module`);
+            }
+            addEdge(module.moduleRef, effective, "moduleRef");
+        }
+        for (const requirement of module.requires) {
+            const candidates = providersByContract.get(requirement.contractRef) ?? [];
+            const matching = candidates
+                .filter((provider) => versionSatisfies(provider.version, requirement.versionRange))
+                .sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
+            if (matching.length > 0) {
+                for (const provider of matching) {
+                    addEdge(module.moduleRef, provider.moduleRef, "capability", requirement.contractRef);
+                }
+                continue;
+            }
+            if (candidates.length > 0) {
+                throw new PlatformError("DEPENDENCY_INCOMPATIBLE", `${module.moduleRef} requires ${requirement.contractRef} ${requirement.versionRange} but no provider satisfies it`);
+            }
+            if (requirement.optional !== true) {
+                throw new PlatformError("DEPENDENCY_UNRESOLVED", `${module.moduleRef} requires ${requirement.contractRef} ${requirement.versionRange} but no module provides it`);
+            }
+        }
+    }
+    edges.sort((a, b) => {
+        const byFrom = compareRef(a.from, b.from);
+        if (byFrom !== 0)
+            return byFrom;
+        const byTo = compareRef(a.to, b.to);
+        if (byTo !== 0)
+            return byTo;
+        return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;
+    });
+    const order = computeOrder(nodes, edges);
+    return { nodes, edges, order };
+}
+function computeOrder(nodes, edges) {
+    const deps = new Map();
+    for (const node of nodes)
+        deps.set(node, new Set());
+    for (const edge of edges) {
+        const set = deps.get(edge.from);
+        if (set === undefined)
+            continue;
+        set.add(edge.to);
+    }
+    const depth = new Map();
+    const state = new Map();
+    const visit = (node) => {
+        const current = state.get(node);
+        if (current === "done")
+            return depth.get(node) ?? 0;
+        if (current === "visiting") {
+            throw new PlatformError("DEPENDENCY_CYCLE", `dependency cycle detected at ${node}`);
+        }
+        state.set(node, "visiting");
+        let maxDepth = 0;
+        const nodeDeps = [...(deps.get(node) ?? new Set())].sort(compareRef);
+        for (const dependency of nodeDeps) {
+            const dependencyDepth = visit(dependency);
+            if (dependencyDepth + 1 > maxDepth)
+                maxDepth = dependencyDepth + 1;
+        }
+        state.set(node, "done");
+        depth.set(node, maxDepth);
+        return maxDepth;
+    };
+    for (const node of nodes)
+        visit(node);
+    const layers = new Map();
+    for (const node of nodes) {
+        const nodeDepth = depth.get(node) ?? 0;
+        const layer = layers.get(nodeDepth) ?? [];
+        layer.push(node);
+        layers.set(nodeDepth, layer);
+    }
+    const depths = [...layers.keys()].sort((a, b) => a - b);
+    const order = [];
+    for (const nodeDepth of depths) {
+        const layer = layers.get(nodeDepth) ?? [];
+        layer.sort(compareRef);
+        order.push(...layer);
+    }
+    return order;
+}

package/dist/src/graph/index.d.ts

@@ -0,0 +1,2 @@
+export type { DependencyEdge, DependencyEdgeKind, DependencyGraph, GraphOptions, } from "./graph.ts";
+export { buildDependencyGraph, ModuleRefUnresolvedError } from "./graph.ts";

package/dist/src/graph/index.js

@@ -0,0 +1 @@
+export { buildDependencyGraph, ModuleRefUnresolvedError } from "./graph.js";

package/dist/src/index.d.ts

@@ -0,0 +1,28 @@
+export type { PackageManagerDriver } from "./apply/driver.ts";
+export { applyPlan, createWorkspacePackageManagerDriver, } from "./apply/index.ts";
+export type { CliOutcome, CliStatus } from "./cli.ts";
+export { runCli } from "./cli.ts";
+export type { DeploymentIntent, DeploymentPlan, DeploymentState, DeploymentStep, ModuleTarget, PlatformState, ResolvedModule, VerificationRecord, VerificationStep, } from "./contracts.ts";
+export { AutoModuleCatalog, discoverModules } from "./discovery/discover.ts";
+export type { ModuleDocsView, ModuleDocumentContent, PublicApiEntry, PublishedCommand, } from "./docs/index.ts";
+export { describeModule, readModuleDocument } from "./docs/index.ts";
+export { doctorModule, doctorModules } from "./doctor/index.ts";
+export type { PlatformErrorCode } from "./errors.ts";
+export { PlatformError } from "./errors.ts";
+export { generateInstallDoc, preflightInstallerEnvironment, renderInstallDoc, } from "./install/index.ts";
+export { dispatchLifecycle, restartModules, startModules, statusModules, stopModules, } from "./lifecycle/index.ts";
+export { buildManifest, MANIFEST_CONTRACT } from "./manifest/index.ts";
+export type { ModuleCatalog, ModuleSource } from "./modules.ts";
+export { versionSatisfies } from "./modules.ts";
+export type { WorkspacePaths } from "./paths.ts";
+export { atomicWrite, workspacePaths } from "./paths.ts";
+export { appendVerification, emptyDeploymentState, listPlans, loadConfig, loadDeploymentState, loadLatestVerification, loadPlan, loadVerificationHistory, materializeConfig, saveDeploymentState, savePlan, writeInstallDoc, } from "./persistence/index.ts";
+export { assessUpgrade, CheckStrategy, checkPlanStale, computeFingerprint, ExecuteStrategy, evaluateStepCheck, planDeployment, planRepair, planUpgrade, repairFactCodes, } from "./planner/index.ts";
+export type { PlanInput } from "./planner/plan.ts";
+export type { PreflightResult } from "./preflight/findings.ts";
+export { runPreflight } from "./preflight/preflight.ts";
+export { assessPlatformReady } from "./ready/index.ts";
+export type { RegistryDiscoveryResult, RegistryModuleCandidate, RegistryRejectedPackage, } from "./registry/index.ts";
+export { discoverRegistryModules } from "./registry/index.ts";
+export { acquireWorkspaceLock, readWorkspaceLock, redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, workspaceLockPath, } from "./security/index.ts";
+export { verifyModule, verifyModules } from "./verification/index.ts";

package/dist/src/index.js

@@ -0,0 +1,18 @@
+export { applyPlan, createWorkspacePackageManagerDriver, } from "./apply/index.js";
+export { runCli } from "./cli.js";
+export { AutoModuleCatalog, discoverModules } from "./discovery/discover.js";
+export { describeModule, readModuleDocument } from "./docs/index.js";
+export { doctorModule, doctorModules } from "./doctor/index.js";
+export { PlatformError } from "./errors.js";
+export { generateInstallDoc, preflightInstallerEnvironment, renderInstallDoc, } from "./install/index.js";
+export { dispatchLifecycle, restartModules, startModules, statusModules, stopModules, } from "./lifecycle/index.js";
+export { buildManifest, MANIFEST_CONTRACT } from "./manifest/index.js";
+export { versionSatisfies } from "./modules.js";
+export { atomicWrite, workspacePaths } from "./paths.js";
+export { appendVerification, emptyDeploymentState, listPlans, loadConfig, loadDeploymentState, loadLatestVerification, loadPlan, loadVerificationHistory, materializeConfig, saveDeploymentState, savePlan, writeInstallDoc, } from "./persistence/index.js";
+export { assessUpgrade, CheckStrategy, checkPlanStale, computeFingerprint, ExecuteStrategy, evaluateStepCheck, planDeployment, planRepair, planUpgrade, repairFactCodes, } from "./planner/index.js";
+export { runPreflight } from "./preflight/preflight.js";
+export { assessPlatformReady } from "./ready/index.js";
+export { discoverRegistryModules } from "./registry/index.js";
+export { acquireWorkspaceLock, readWorkspaceLock, redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, workspaceLockPath, } from "./security/index.js";
+export { verifyModule, verifyModules } from "./verification/index.js";

package/dist/src/install/bootstrap.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedModule } from "../contracts.ts";
+import { type RegistryModuleCandidate } from "../registry/index.ts";
+/**
+ * Registry bootstrap targets intentionally carry only facts available before
+ * installation. They are package-plan placeholders, never substitutes for the
+ * package-owned Module Descriptor that is loaded after installation.
+ */
+export declare function registryCandidateToBootstrapModule(candidate: RegistryModuleCandidate): ResolvedModule;
+export declare function selectBootstrapModules(candidates: readonly RegistryModuleCandidate[], explicitPackageName?: string): ResolvedModule[];
+export declare function selectUpgradeBootstrapModules(currentModules: readonly ResolvedModule[], candidates: readonly RegistryModuleCandidate[]): ResolvedModule[];

package/dist/src/install/bootstrap.js

@@ -0,0 +1,79 @@
+import { PlatformError } from "../errors.js";
+import { PRO_FLOW_PACKAGE_PREFIX, } from "../registry/index.js";
+/**
+ * Registry bootstrap targets intentionally carry only facts available before
+ * installation. They are package-plan placeholders, never substitutes for the
+ * package-owned Module Descriptor that is loaded after installation.
+ */
+export function registryCandidateToBootstrapModule(candidate) {
+    if (!candidate.packageName.startsWith(PRO_FLOW_PACKAGE_PREFIX)) {
+        throw new PlatformError("PACKAGE_NOT_PROFLOW", `package ${candidate.packageName} is outside ${PRO_FLOW_PACKAGE_PREFIX}*`);
+    }
+    const moduleRef = candidate.packageName.slice(PRO_FLOW_PACKAGE_PREFIX.length);
+    if (moduleRef === "") {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", `cannot derive moduleRef from ${candidate.packageName}`);
+    }
+    return {
+        moduleRef,
+        packageName: candidate.packageName,
+        moduleVersion: candidate.moduleVersion,
+        kind: "registry-package",
+        installClass: candidate.installClass,
+        provides: [],
+        requires: [],
+        requirements: [],
+        configSlots: [],
+        lifecycle: [],
+        verification: { checks: [] },
+        effects: [],
+        documentation: [],
+        source: { type: "registry" },
+    };
+}
+export function selectBootstrapModules(candidates, explicitPackageName) {
+    const byPackage = new Map(candidates.map((candidate) => [candidate.packageName, candidate]));
+    const roots = explicitPackageName === undefined
+        ? candidates.filter((candidate) => candidate.installClass === "core")
+        : candidates.filter((candidate) => candidate.packageName === explicitPackageName);
+    if (roots.length === 0) {
+        throw new PlatformError(explicitPackageName === undefined
+            ? "REGISTRY_RESPONSE_INVALID"
+            : "PACKAGE_NOT_FOUND", explicitPackageName === undefined
+            ? "Registry discovery returned no installable core ProFlow packages"
+            : `no installable ProFlow package found for ${explicitPackageName}`);
+    }
+    const selected = new Map();
+    const queue = [...roots];
+    while (queue.length > 0) {
+        const candidate = queue.shift();
+        if (!candidate)
+            continue;
+        if (selected.has(candidate.packageName))
+            continue;
+        selected.set(candidate.packageName, candidate);
+        for (const dependencyName of candidate.installRequires) {
+            const dependency = byPackage.get(dependencyName);
+            if (dependency === undefined) {
+                throw new PlatformError("DEPENDENCY_UNRESOLVED", `Registry bootstrap dependency ${dependencyName} required by ${candidate.packageName} was not discovered`);
+            }
+            queue.push(dependency);
+        }
+    }
+    return [...selected.values()]
+        .sort((a, b) => a.packageName.localeCompare(b.packageName))
+        .map(registryCandidateToBootstrapModule);
+}
+export function selectUpgradeBootstrapModules(currentModules, candidates) {
+    const byPackage = new Map(candidates.map((candidate) => [candidate.packageName, candidate]));
+    const targets = [];
+    for (const current of currentModules) {
+        const candidate = byPackage.get(current.packageName);
+        if (candidate === undefined) {
+            throw new PlatformError("PACKAGE_NOT_FOUND", `no installable Registry target found for managed package ${current.packageName}`);
+        }
+        if (candidate.moduleVersion === current.moduleVersion)
+            continue;
+        targets.push(registryCandidateToBootstrapModule(candidate));
+    }
+    return targets;
+}