@tomflow/proflow-platform-cli 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# platform-cli
+
+Domain Owner: deployment-governance  
+Module Kind: cli  
+Service: none  
+Process: none  
+Business Fact Owner: none
+
+## Purpose
+
+The single platform-level deterministic Deployment planner/executor. It understands only the Module Contract and public lifecycle/verification contracts; it does not import other domains' business internals.
+
+For the v1 Custom GPT carrier it may plan/verify Web-only setup, role-scoped Action auth/schema, File Bridge/Code Interpreter/Web Search requirements, `x-openai-isConsequential:false` + Always Allow target configuration, Chrome/runtime prerequisites and current verification freshness. It never creates/guesses Task `workerRef/c-id`, never uses exact ChatGPT model id as READY truth, and never accepts System Observer assessment as Deployment READY truth.
+
+## Commands
+
+```
+platform search [package]
+platform modules [module|package]
+platform docs [module|package] [documentId]
+platform preflight [module]
+platform preflight --intent install
+platform install [package]
+platform uninstall <module|package>
+platform upgrade [module|package]
+platform plan --intent install|configure|upgrade|uninstall|repair [options]
+platform apply <planRef>
+platform start [module]
+platform stop [module]
+platform restart [module]
+platform status [module]
+platform verify [module]
+platform doctor [module]
+platform manifest [module]
+```
+
+`install` / `upgrade` / `uninstall` are AI-friendly high-level commands that reuse the same frozen Plan -> Apply engine. `search` reads the npm Registry installable world; `modules` reads the current Workspace managed world; `docs` mechanically aggregates package-owned Descriptor, npm `bin/exports`, and declared documentation without maintaining a second package-knowledge catalog. Package mutation is real Workspace package-manager mutation and is never satisfied by the historical no-op driver seam.

package/conformance.json

@@ -0,0 +1 @@
+{ "contract": "proflow.conformance.v1", "levels": ["C1", "C2", "C3"] }

package/dist/deployment/adapter.d.ts

@@ -0,0 +1,57 @@
+export declare const behaviorAdapter: {
+    describe: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "SUCCEEDED";
+            moduleRef: "platform-cli";
+            moduleVersion: "0.1.0";
+            data?: {} | null;
+        };
+        observedEffects: never[];
+    };
+    preflight: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "SUCCEEDED";
+            moduleRef: "platform-cli";
+            moduleVersion: "0.1.0";
+            data?: {} | null;
+        };
+        observedEffects: never[];
+    };
+    status: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "SUCCEEDED";
+            moduleRef: "platform-cli";
+            moduleVersion: "0.1.0";
+            data?: {} | null;
+        };
+        observedEffects: never[];
+    };
+    verify: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "SUCCEEDED";
+            moduleRef: "platform-cli";
+            moduleVersion: "0.1.0";
+            data?: {} | null;
+        };
+        observedEffects: never[];
+    };
+    doctor: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "SUCCEEDED";
+            moduleRef: "platform-cli";
+            moduleVersion: "0.1.0";
+            data?: {} | null;
+        };
+        observedEffects: never[];
+    };
+};

package/dist/deployment/adapter.js

@@ -0,0 +1,25 @@
+import { descriptor } from "./descriptor.js";
+const success = (data) => ({
+    contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+    ...(data === undefined ? {} : { data }),
+});
+export const behaviorAdapter = {
+    describe: () => ({
+        result: success({ role: "deployment-governance", kind: descriptor.kind }),
+        observedEffects: [],
+    }),
+    preflight: () => ({ result: success(), observedEffects: [] }),
+    status: () => ({
+        result: success({ runnable: true }),
+        observedEffects: [],
+    }),
+    verify: () => ({
+        result: success(),
+        observedEffects: [],
+    }),
+    doctor: () => ({ result: success(), observedEffects: [] }),
+};

package/dist/deployment/descriptor.d.ts

@@ -0,0 +1,39 @@
+export declare const descriptor: {
+    readonly contract: "module";
+    readonly contractVersion: "1.0.0";
+    readonly moduleRef: "platform-cli";
+    readonly packageName: "@tomflow/proflow-platform-cli";
+    readonly moduleVersion: "0.1.0";
+    readonly kind: "cli";
+    readonly templateVersion: "1.0.0";
+    readonly platformCompatibility: ">=1.0.0 <2.0.0";
+    readonly installClass: "core";
+    readonly identity: {
+        readonly domain: "deployment-governance";
+        readonly summary: "Deterministic platform-level deployment discovery, planning, lifecycle and verification CLI.";
+    };
+    readonly provides: readonly [];
+    readonly requires: readonly [];
+    readonly requirements: readonly [{
+        readonly kind: "runtime";
+        readonly runtime: "node";
+        readonly versionRange: ">=24.19.0";
+    }];
+    readonly configSlots: readonly [];
+    readonly lifecycle: {
+        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor"];
+    };
+    readonly verification: {
+        readonly checks: readonly [{
+            readonly id: "cli-surface";
+            readonly description: "Deterministic command surface parses and dispatches";
+            readonly lifecycle: "verify";
+        }];
+    };
+    readonly effects: readonly [];
+    readonly documentation: readonly [{
+        readonly id: "overview";
+        readonly path: "./README.md";
+        readonly description: "Platform CLI package overview and command surface";
+    }];
+};

package/dist/deployment/descriptor.js

@@ -0,0 +1,41 @@
+export const descriptor = {
+    contract: "module",
+    contractVersion: "1.0.0",
+    moduleRef: "platform-cli",
+    packageName: "@tomflow/proflow-platform-cli",
+    moduleVersion: "0.1.0",
+    kind: "cli",
+    templateVersion: "1.0.0",
+    platformCompatibility: ">=1.0.0 <2.0.0",
+    installClass: "core",
+    identity: {
+        domain: "deployment-governance",
+        summary: "Deterministic platform-level deployment discovery, planning, lifecycle and verification CLI.",
+    },
+    provides: [],
+    requires: [],
+    requirements: [
+        { kind: "runtime", runtime: "node", versionRange: ">=24.19.0" },
+    ],
+    configSlots: [],
+    lifecycle: {
+        supported: ["describe", "preflight", "status", "verify", "doctor"],
+    },
+    verification: {
+        checks: [
+            {
+                id: "cli-surface",
+                description: "Deterministic command surface parses and dispatches",
+                lifecycle: "verify",
+            },
+        ],
+    },
+    effects: [],
+    documentation: [
+        {
+            id: "overview",
+            path: "./README.md",
+            description: "Platform CLI package overview and command surface",
+        },
+    ],
+};

package/dist/src/apply/apply.d.ts

@@ -0,0 +1,24 @@
+import type { ApplyResult } from "../contracts.ts";
+import type { ModuleCatalog } from "../modules.ts";
+import { type WorkspacePaths } from "../paths.ts";
+import { type PlanInput } from "../planner/index.ts";
+import type { PackageManagerDriver } from "./driver.ts";
+import type { RealityObserver } from "./reality.ts";
+export interface ApplyContext {
+    paths: WorkspacePaths;
+    planRef: string;
+    catalog: ModuleCatalog;
+    /** Current stable assumptions the plan must still match (staleness gate). */
+    current: PlanInput;
+    driver: PackageManagerDriver;
+    observer?: RealityObserver;
+}
+/**
+ * Applies a frozen deployment plan deterministically. Every step is re-checked
+ * against current reality before any action: satisfied steps SKIP, human steps
+ * and ACTION_REQUIRED mutations persist a structured pendingAction and STOP with
+ * ACTION_REQUIRED, a BLOCKED/FAILED mutation STOPs with the matching outcome,
+ * and only a fully applied plan is recorded in `lastAppliedPlans`. The exclusive
+ * workspace lock is released in all paths.
+ */
+export declare function applyPlan(context: ApplyContext): Promise<ApplyResult>;

package/dist/src/apply/apply.js

@@ -0,0 +1,271 @@
+import { PlatformError } from "../errors.js";
+import { ensureLayout } from "../paths.js";
+import { emptyDeploymentState, loadDeploymentState, loadPlan, saveDeploymentState, } from "../persistence/index.js";
+import { checkPlanStale, evaluateStepCheck, } from "../planner/index.js";
+import { acquireWorkspaceLock } from "../security/index.js";
+import { executeStep } from "./execute.js";
+import { createRealityObserver } from "./reality.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+function failureMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Applies a frozen deployment plan deterministically. Every step is re-checked
+ * against current reality before any action: satisfied steps SKIP, human steps
+ * and ACTION_REQUIRED mutations persist a structured pendingAction and STOP with
+ * ACTION_REQUIRED, a BLOCKED/FAILED mutation STOPs with the matching outcome,
+ * and only a fully applied plan is recorded in `lastAppliedPlans`. The exclusive
+ * workspace lock is released in all paths.
+ */
+export async function applyPlan(context) {
+    const driver = context.driver;
+    const observer = context.observer ??
+        createRealityObserver({
+            paths: context.paths,
+            catalog: context.catalog,
+            driver,
+        });
+    await ensureLayout(context.paths);
+    const lock = await acquireWorkspaceLock(context.paths, context.planRef);
+    try {
+        const plan = await loadPlan(context.paths, context.planRef);
+        if (plan === undefined) {
+            throw new PlatformError("PLAN_NOT_FOUND", `plan ${context.planRef} not found`);
+        }
+        const staleness = checkPlanStale(plan, context.current);
+        if (staleness.stale) {
+            return {
+                planRef: plan.planRef,
+                outcome: "BLOCKED",
+                stepResults: [],
+                completedAt: nowIso(),
+            };
+        }
+        const state = (await loadDeploymentState(context.paths)) ?? emptyDeploymentState();
+        const stepResults = [];
+        for (const step of plan.steps) {
+            const reality = await observer.observe(step, plan);
+            if (reality === undefined) {
+                // UNKNOWN: current reality could not be observed. Stop without
+                // replaying any lifecycle/external effect, then doctor/repair.
+                stepResults.push({
+                    stepRef: step.stepRef,
+                    moduleRef: step.moduleRef,
+                    status: "FAILED",
+                    message: `blocked: current reality for ${step.moduleRef} could not be observed`,
+                });
+                state.updatedAt = nowIso();
+                await saveDeploymentState(context.paths, state);
+                return {
+                    planRef: plan.planRef,
+                    outcome: "BLOCKED",
+                    stepResults,
+                    completedAt: nowIso(),
+                };
+            }
+            const check = evaluateStepCheck(step, plan, reality);
+            if (check.status === "SATISFIED") {
+                // A previously-pending action for this step can no longer block a
+                // resume: the step is satisfied in current reality, so clear it.
+                state.pendingActions = state.pendingActions.filter((pending) => !(pending.planRef === plan.planRef &&
+                    pending.stepRef === step.stepRef));
+                stepResults.push({
+                    stepRef: step.stepRef,
+                    moduleRef: step.moduleRef,
+                    status: "SKIP",
+                    message: check.reason,
+                });
+                continue;
+            }
+            if (step.kind === "human") {
+                const completedAt = nowIso();
+                state.pendingActions.push({
+                    planRef: plan.planRef,
+                    stepRef: step.stepRef,
+                    moduleRef: step.moduleRef,
+                    action: step.expectedEffect,
+                    createdAt: completedAt,
+                });
+                state.updatedAt = completedAt;
+                await saveDeploymentState(context.paths, state);
+                stepResults.push({
+                    stepRef: step.stepRef,
+                    moduleRef: step.moduleRef,
+                    status: "ACTION_REQUIRED",
+                    message: check.reason,
+                });
+                return {
+                    planRef: plan.planRef,
+                    outcome: "ACTION_REQUIRED",
+                    stepResults,
+                    completedAt,
+                };
+            }
+            let outcome;
+            try {
+                outcome = await executeStep({ paths: context.paths, catalog: context.catalog, driver }, step, plan);
+            }
+            catch (error) {
+                stepResults.push({
+                    stepRef: step.stepRef,
+                    moduleRef: step.moduleRef,
+                    status: "FAILED",
+                    message: failureMessage(error),
+                });
+                state.updatedAt = nowIso();
+                await saveDeploymentState(context.paths, state);
+                return {
+                    planRef: plan.planRef,
+                    outcome: "FAILED",
+                    stepResults,
+                    completedAt: nowIso(),
+                };
+            }
+            switch (outcome.kind) {
+                case "SUCCEEDED": {
+                    // Postcondition re-check: only a genuinely successful mutation is
+                    // confirmed; an effect that cannot be confirmed stops the apply
+                    // rather than blindly repeating it.
+                    const postReality = await observer.observe(step, plan);
+                    if (postReality === undefined) {
+                        stepResults.push({
+                            stepRef: step.stepRef,
+                            moduleRef: step.moduleRef,
+                            status: "FAILED",
+                            message: `blocked: postcondition reality for ${step.moduleRef} could not be observed`,
+                        });
+                        state.updatedAt = nowIso();
+                        await saveDeploymentState(context.paths, state);
+                        return {
+                            planRef: plan.planRef,
+                            outcome: "BLOCKED",
+                            stepResults,
+                            completedAt: nowIso(),
+                        };
+                    }
+                    const post = evaluateStepCheck(step, plan, postReality);
+                    if (post.status !== "SATISFIED") {
+                        stepResults.push({
+                            stepRef: step.stepRef,
+                            moduleRef: step.moduleRef,
+                            status: "FAILED",
+                            message: `postcondition not satisfied after execution: ${post.reason}`,
+                        });
+                        state.updatedAt = nowIso();
+                        await saveDeploymentState(context.paths, state);
+                        return {
+                            planRef: plan.planRef,
+                            outcome: "FAILED",
+                            stepResults,
+                            completedAt: nowIso(),
+                        };
+                    }
+                    stepResults.push({
+                        stepRef: step.stepRef,
+                        moduleRef: step.moduleRef,
+                        status: "EXECUTED",
+                        message: post.reason,
+                    });
+                    break;
+                }
+                case "ACTION_REQUIRED": {
+                    const completedAt = nowIso();
+                    state.pendingActions.push({
+                        planRef: plan.planRef,
+                        stepRef: step.stepRef,
+                        moduleRef: step.moduleRef,
+                        action: outcome.actionRequired.action,
+                        description: outcome.actionRequired.description,
+                        createdAt: completedAt,
+                    });
+                    state.updatedAt = completedAt;
+                    await saveDeploymentState(context.paths, state);
+                    stepResults.push({
+                        stepRef: step.stepRef,
+                        moduleRef: step.moduleRef,
+                        status: "ACTION_REQUIRED",
+                        message: outcome.actionRequired.action,
+                    });
+                    return {
+                        planRef: plan.planRef,
+                        outcome: "ACTION_REQUIRED",
+                        stepResults,
+                        completedAt,
+                    };
+                }
+                case "BLOCKED": {
+                    stepResults.push({
+                        stepRef: step.stepRef,
+                        moduleRef: step.moduleRef,
+                        status: "FAILED",
+                        message: `blocked: ${outcome.reason}`,
+                    });
+                    state.updatedAt = nowIso();
+                    await saveDeploymentState(context.paths, state);
+                    return {
+                        planRef: plan.planRef,
+                        outcome: "BLOCKED",
+                        stepResults,
+                        completedAt: nowIso(),
+                    };
+                }
+                case "FAILED": {
+                    stepResults.push({
+                        stepRef: step.stepRef,
+                        moduleRef: step.moduleRef,
+                        status: "FAILED",
+                        message: outcome.reason,
+                    });
+                    state.updatedAt = nowIso();
+                    await saveDeploymentState(context.paths, state);
+                    return {
+                        planRef: plan.planRef,
+                        outcome: "FAILED",
+                        stepResults,
+                        completedAt: nowIso(),
+                    };
+                }
+            }
+        }
+        const completedAt = nowIso();
+        if (plan.intent === "uninstall") {
+            const removed = new Set(plan.resolvedModules.map((module) => module.moduleRef));
+            state.selectedModules = state.selectedModules.filter((module) => !removed.has(module.moduleRef));
+        }
+        else if ((plan.intent === "install" || plan.intent === "upgrade") &&
+            plan.resolvedModules.every((module) => module.source.type === "registry")) {
+            const byRef = new Map(state.selectedModules.map((module) => [module.moduleRef, module]));
+            for (const module of plan.resolvedModules) {
+                byRef.set(module.moduleRef, {
+                    moduleRef: module.moduleRef,
+                    moduleVersion: module.moduleVersion,
+                });
+            }
+            state.selectedModules = [...byRef.values()].sort((left, right) => left.moduleRef.localeCompare(right.moduleRef));
+        }
+        else {
+            state.selectedModules = plan.resolvedModules.map((module) => ({
+                moduleRef: module.moduleRef,
+                moduleVersion: module.moduleVersion,
+            }));
+        }
+        state.lastAppliedPlans.push({
+            planRef: plan.planRef,
+            intent: plan.intent,
+            appliedAt: completedAt,
+        });
+        state.updatedAt = completedAt;
+        await saveDeploymentState(context.paths, state);
+        return {
+            planRef: plan.planRef,
+            outcome: "COMPLETE",
+            stepResults,
+            completedAt,
+        };
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/src/apply/cleanup.d.ts

@@ -0,0 +1,12 @@
+import type { DeploymentEffect } from "@tomflow/proflow-module-contract";
+/**
+ * Removes only package-declared ephemeral filesystem effects under the
+ * Workspace-owned `.proflow` state tree. Persistent and explicit-purge effects
+ * are never deleted by ordinary uninstall. Paths outside `.proflow` are left to
+ * the package-owned uninstall adapter so a descriptor can never turn the
+ * platform package manager into an arbitrary recursive-delete primitive.
+ */
+export declare function cleanupRemovableFilesystemEffects(input: {
+    workspaceRoot: string;
+    effects: readonly DeploymentEffect[];
+}): Promise<string[]>;

package/dist/src/apply/cleanup.js

@@ -0,0 +1,37 @@
+import { rm } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { PlatformError } from "../errors.js";
+/**
+ * Removes only package-declared ephemeral filesystem effects under the
+ * Workspace-owned `.proflow` state tree. Persistent and explicit-purge effects
+ * are never deleted by ordinary uninstall. Paths outside `.proflow` are left to
+ * the package-owned uninstall adapter so a descriptor can never turn the
+ * platform package manager into an arbitrary recursive-delete primitive.
+ */
+export async function cleanupRemovableFilesystemEffects(input) {
+    const workspaceRoot = resolve(input.workspaceRoot);
+    const proflowRoot = resolve(workspaceRoot, ".proflow");
+    const removed = [];
+    for (const effect of input.effects) {
+        if (effect.kind !== "filesystem" ||
+            effect.retention !== "remove" ||
+            effect.path === undefined) {
+            continue;
+        }
+        if (isAbsolute(effect.path)) {
+            throw new PlatformError("UNINSTALL_FAILED", `removable filesystem effect must use a Workspace-relative .proflow path: ${effect.path}`);
+        }
+        const target = resolve(workspaceRoot, effect.path);
+        const withinProflow = relative(proflowRoot, target);
+        if (target === proflowRoot ||
+            withinProflow === "" ||
+            withinProflow === ".." ||
+            withinProflow.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) ||
+            isAbsolute(withinProflow)) {
+            throw new PlatformError("UNINSTALL_FAILED", `refusing unsafe removable filesystem effect outside a .proflow child path: ${effect.path}`);
+        }
+        await rm(target, { recursive: true, force: true });
+        removed.push(effect.path);
+    }
+    return removed;
+}

package/dist/src/apply/current.d.ts

@@ -0,0 +1,4 @@
+import type { DeploymentPlan } from "../contracts.ts";
+import type { ModuleCatalog } from "../modules.ts";
+import type { PlanInput } from "../planner/plan.ts";
+export declare function rebuildCurrentAssumptions(catalog: ModuleCatalog, plan: DeploymentPlan): Promise<PlanInput>;

package/dist/src/apply/current.js

@@ -0,0 +1,73 @@
+import { parseModuleDescriptor, } from "@tomflow/proflow-module-contract";
+import { discoverModules } from "../discovery/index.js";
+import { doctorModules } from "../doctor/index.js";
+import { diagnoseRepair } from "../planner/repair.js";
+function moduleSourceOf(module) {
+    if (module.source.type === "registry") {
+        throw new Error(`registry bootstrap target ${module.packageName} has no local descriptor`);
+    }
+    const source = {
+        type: module.source.type,
+        packageName: module.packageName,
+    };
+    if (module.source.path !== undefined)
+        source.path = module.source.path;
+    return source;
+}
+async function loadDescriptors(catalog, modules) {
+    const descriptors = [];
+    for (const module of modules) {
+        const raw = await catalog.loadDescriptor(moduleSourceOf(module));
+        descriptors.push(parseModuleDescriptor(raw));
+    }
+    return descriptors;
+}
+// Rebuilds a plan's stable current assumptions from the CURRENT module catalog
+// and current reality. The old plan's resolvedModules are never reused: modules
+// are re-discovered and re-parsed so descriptor drift reaches the staleness
+// gate. Upgrade additionally re-discovers current descriptors and reuses the
+// plan's frozen target descriptors; repair re-runs doctor for fresh facts.
+export async function rebuildCurrentAssumptions(catalog, plan) {
+    if ((plan.intent === "install" || plan.intent === "upgrade") &&
+        plan.resolvedModules.every((module) => module.source.type === "registry")) {
+        return {
+            intent: plan.intent,
+            modules: plan.resolvedModules,
+            targets: plan.moduleTargets,
+        };
+    }
+    const discovered = await discoverModules({ catalog });
+    const byRef = new Map(discovered.map((module) => [module.moduleRef, module]));
+    const modules = [];
+    for (const target of plan.moduleTargets) {
+        const module = byRef.get(target.moduleRef);
+        if (module !== undefined)
+            modules.push(module);
+    }
+    if (plan.intent === "upgrade") {
+        const currentDescriptors = await loadDescriptors(catalog, modules);
+        if (plan.targetDescriptors === undefined)
+            return { intent: plan.intent, modules, targets: plan.moduleTargets };
+        return {
+            intent: plan.intent,
+            modules,
+            targets: plan.moduleTargets,
+            currentDescriptors,
+            targetDescriptors: plan.targetDescriptors,
+        };
+    }
+    if (plan.intent === "repair") {
+        const diagnosis = diagnoseRepair(await doctorModules(catalog, modules));
+        return {
+            intent: plan.intent,
+            modules,
+            targets: plan.moduleTargets,
+            facts: diagnosis.facts,
+        };
+    }
+    return {
+        intent: plan.intent,
+        modules,
+        targets: plan.moduleTargets,
+    };
+}

package/dist/src/apply/driver.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedModule } from "../contracts.ts";
+import { type PackageCommandRunner } from "../install/package-manager.ts";
+/**
+ * Package-level installation seam. Apply never invokes an arbitrary shell: a
+ * package step is satisfied or mutated only through this injected driver. The
+ * production driver executes a fixed package-manager binary with argv arrays.
+ */
+export interface PackageManagerDriver {
+    observeInstalledVersion(module: ResolvedModule): Promise<string | undefined>;
+    install(module: ResolvedModule): Promise<void>;
+    upgrade(module: ResolvedModule): Promise<void>;
+    remove(module: ResolvedModule): Promise<void>;
+}
+/**
+ * Monorepo/test seam retained for source-resident planning. Production CLI must
+ * inject createWorkspacePackageManagerDriver(); it must never rely on this
+ * no-op driver to claim a product Workspace package mutation succeeded.
+ */
+export declare function workspaceResidentDriver(): PackageManagerDriver;
+export declare function createWorkspacePackageManagerDriver(options: {
+    workspaceRoot: string;
+    runner?: PackageCommandRunner;
+}): PackageManagerDriver;