@tomflow/proflow-platform-cli 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.3
+
+### Patch Changes
+
+- Real-1 final remediation and black-box release closure
+
+## 0.1.2
+
+### Patch Changes
+
+- Close the Real-1 global Platform control-plane contract across every published ProFlow package. Platform CLI now owns one durable global Workspace binding with canonical identity, cross-process operation locking, cwd/`--workspace` install targeting, cross-directory instance commands, whole-instance uninstall/rebind, and deterministic npm/yarn/pnpm Workspace package-manager selection. Every package-owned install entry, including newly generated Module Template packages, delegates to the Shell-global `platform` command and fails closed when that global CLI is unavailable; Deployment Conformance and the formal test plans mechanically enforce the same rule across all 24 packages.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -8,10 +8,20 @@ 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.
+The single platform-level deterministic Deployment planner/executor and v1 global `platform` control plane. It understands only the Module Contract and public lifecycle/verification contracts; it does not import other domains' business internals. The global CLI binary is distinct from the single bound Platform Instance.
 
 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.
 
+## Global CLI bootstrap
+
+The v1 `platform` command is a Shell-global control plane. A straightforward bootstrap is:
+
+```text
+npm install --global @tomflow/proflow-platform-cli
+```
+
+This choice installs the global CLI only. It does **not** force the managed Workspace to use npm: a bound Workspace may independently use `npm`, `yarn`, or `pnpm`, selected from its own package-manager facts.
+
 ## Commands
 
 ```
@@ -20,8 +30,8 @@ platform modules [module|package]
 platform docs [module|package] [documentId]
 platform preflight [module]
 platform preflight --intent install
-platform install [package]
-platform uninstall <module|package>
+platform install [package] [--workspace <path>]
+platform uninstall [module|package]
 platform upgrade [module|package]
 platform plan --intent install|configure|upgrade|uninstall|repair [options]
 platform apply <planRef>
@@ -35,3 +45,14 @@ 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.
+
+
+## v1 global workspace semantics
+
+- The `platform` binary is installed globally and can be invoked from any shell directory.
+- At most one ProFlow Workspace may be bound globally at a time.
+- `platform install` targets the current working directory by default; `platform install --workspace <path>` explicitly selects the requested Workspace for Agent/automation use.
+- Requested Workspace paths are canonicalized before binding comparison. A second distinct Workspace is rejected with `WORKSPACE_ALREADY_BOUND` until the current Platform Instance is uninstalled.
+- `status/start/stop/restart/modules/docs/verify/doctor/upgrade/uninstall` resolve the durable global binding rather than the caller's cwd. `platform status` exposes the bound Workspace path.
+- `platform uninstall` without a module/package removes the current Platform Instance and clears its binding; it does not uninstall the global CLI package.
+- Workspace package mutation is package-manager agnostic for v1: `npm`, `yarn`, and `pnpm` are supported. The CLI installation manager and the bound Workspace manager are independent facts.

package/dist/deployment/adapter.d.ts

@@ -5,7 +5,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.3";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.3";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -27,7 +27,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.3";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -38,7 +38,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.3";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -49,7 +49,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.3";
             data?: {} | null;
         };
         observedEffects: never[];

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "platform-cli";
     readonly packageName: "@tomflow/proflow-platform-cli";
-    readonly moduleVersion: "0.1.1";
+    readonly moduleVersion: "0.1.3";
     readonly kind: "cli";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "platform-cli",
     packageName: "@tomflow/proflow-platform-cli",
-    moduleVersion: "0.1.1",
+    moduleVersion: "0.1.3",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

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

@@ -12,6 +12,8 @@ export interface ApplyContext {
     current: PlanInput;
     driver: PackageManagerDriver;
     observer?: RealityObserver;
+    /** Rebuilds installed descriptors/bindings after a package mutation. */
+    refreshCatalog?: () => Promise<ModuleCatalog>;
 }
 /**
  * Applies a frozen deployment plan deterministically. Every step is re-checked

package/dist/src/apply/apply.js

@@ -1,7 +1,7 @@
 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 { checkPlanStale, ExecuteStrategy, evaluateStepCheck, } from "../planner/index.js";
 import { acquireWorkspaceLock } from "../security/index.js";
 import { executeStep } from "./execute.js";
 import { createRealityObserver } from "./reality.js";
@@ -21,10 +21,11 @@ function failureMessage(error) {
  */
 export async function applyPlan(context) {
     const driver = context.driver;
-    const observer = context.observer ??
+    let catalog = context.catalog;
+    let observer = context.observer ??
         createRealityObserver({
             paths: context.paths,
-            catalog: context.catalog,
+            catalog,
             driver,
         });
     await ensureLayout(context.paths);
@@ -105,7 +106,7 @@ export async function applyPlan(context) {
             }
             let outcome;
             try {
-                outcome = await executeStep({ paths: context.paths, catalog: context.catalog, driver }, step, plan);
+                outcome = await executeStep({ paths: context.paths, catalog, driver }, step, plan);
             }
             catch (error) {
                 stepResults.push({
@@ -125,6 +126,20 @@ export async function applyPlan(context) {
             }
             switch (outcome.kind) {
                 case "SUCCEEDED": {
+                    if (step.executeStrategy === ExecuteStrategy.lifecycleUninstall) {
+                        // A lifecycle uninstall is owned by the module adapter. Its typed
+                        // SUCCEEDED result is the authoritative teardown confirmation. An
+                        // idempotent uninstall can legitimately leave status UNBOUND/UNKNOWN,
+                        // so a second status probe must not reinterpret that successful
+                        // teardown as a failed lifecycle:stopped postcondition.
+                        stepResults.push({
+                            stepRef: step.stepRef,
+                            moduleRef: step.moduleRef,
+                            status: "EXECUTED",
+                            message: `${step.moduleRef} owner confirmed lifecycle uninstall`,
+                        });
+                        break;
+                    }
                     // Postcondition re-check: only a genuinely successful mutation is
                     // confirmed; an effect that cannot be confirmed stops the apply
                     // rather than blindly repeating it.
@@ -168,6 +183,34 @@ export async function applyPlan(context) {
                         status: "EXECUTED",
                         message: post.reason,
                     });
+                    if (step.kind === "package" && context.refreshCatalog !== undefined) {
+                        try {
+                            catalog = await context.refreshCatalog();
+                            if (context.observer === undefined) {
+                                observer = createRealityObserver({
+                                    paths: context.paths,
+                                    catalog,
+                                    driver,
+                                });
+                            }
+                        }
+                        catch (error) {
+                            stepResults.push({
+                                stepRef: step.stepRef,
+                                moduleRef: step.moduleRef,
+                                status: "FAILED",
+                                message: `post-package catalog refresh failed: ${failureMessage(error)}`,
+                            });
+                            state.updatedAt = nowIso();
+                            await saveDeploymentState(context.paths, state);
+                            return {
+                                planRef: plan.planRef,
+                                outcome: "FAILED",
+                                stepResults,
+                                completedAt: nowIso(),
+                            };
+                        }
+                    }
                     break;
                 }
                 case "ACTION_REQUIRED": {

package/dist/src/apply/current.js

@@ -65,6 +65,20 @@ export async function rebuildCurrentAssumptions(catalog, plan) {
             facts: diagnosis.facts,
         };
     }
+    if (plan.intent === "uninstall") {
+        // A persisted uninstall plan does not store uninstallScope. Recover the only
+        // legal scope from its module set for the staleness re-plan: any core module
+        // can only have entered the plan through whole-instance uninstall.
+        const uninstallScope = plan.resolvedModules.some((module) => module.installClass === "core")
+            ? "platform-instance"
+            : "module";
+        return {
+            intent: plan.intent,
+            modules,
+            targets: plan.moduleTargets,
+            uninstallScope,
+        };
+    }
     return {
         intent: plan.intent,
         modules,

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

@@ -20,4 +20,5 @@ export declare function workspaceResidentDriver(): PackageManagerDriver;
 export declare function createWorkspacePackageManagerDriver(options: {
     workspaceRoot: string;
     runner?: PackageCommandRunner;
+    executableAvailable?: (command: string) => boolean;
 }): PackageManagerDriver;

package/dist/src/apply/driver.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { PlatformError } from "../errors.js";
-import { readWorkspacePackageManagerSelection, systemPackageCommandRunner, } from "../install/package-manager.js";
+import { findExecutable, readWorkspacePackageManagerSelection, systemPackageCommandRunner, } from "../install/package-manager.js";
 import { atomicWrite } from "../paths.js";
 /**
  * Monorepo/test seam retained for source-resident planning. Production CLI must
@@ -20,26 +20,27 @@ export function workspaceResidentDriver() {
 }
 export function createWorkspacePackageManagerDriver(options) {
     const runner = options.runner ?? systemPackageCommandRunner();
+    const executableAvailable = options.executableAvailable ?? findExecutable;
     return {
         observeInstalledVersion: (module) => observeInstalledVersion(options.workspaceRoot, module.packageName),
         install: async (module) => {
             await ensureWorkspacePackageJson(options.workspaceRoot);
-            const manager = await requirePackageManager(options.workspaceRoot);
+            const manager = await requirePackageManager(options.workspaceRoot, executableAvailable);
             await mutatePackage(runner, manager, options.workspaceRoot, "install", `${module.packageName}@${module.moduleVersion}`);
         },
         upgrade: async (module) => {
             await ensureWorkspacePackageJson(options.workspaceRoot);
-            const manager = await requirePackageManager(options.workspaceRoot);
+            const manager = await requirePackageManager(options.workspaceRoot, executableAvailable);
             await mutatePackage(runner, manager, options.workspaceRoot, "upgrade", `${module.packageName}@${module.moduleVersion}`);
         },
         remove: async (module) => {
-            const manager = await requirePackageManager(options.workspaceRoot);
+            const manager = await requirePackageManager(options.workspaceRoot, executableAvailable);
             await mutatePackage(runner, manager, options.workspaceRoot, "remove", module.packageName);
         },
     };
 }
 async function mutatePackage(runner, manager, workspaceRoot, operation, packageSpec) {
-    const args = packageManagerArgs(manager.name, operation, packageSpec);
+    const args = await packageManagerArgs(runner, manager, workspaceRoot, operation, packageSpec);
     try {
         await runner.run(manager.name, args, workspaceRoot);
     }
@@ -47,20 +48,47 @@ async function mutatePackage(runner, manager, workspaceRoot, operation, packageS
         throw new PlatformError(operation === "upgrade" ? "UPGRADE_FAILED" : "APPLY_FAILED", `${manager.name} ${operation} failed for ${packageSpec}: ${errorMessage(error)}`);
     }
 }
-function packageManagerArgs(manager, operation, packageSpec) {
-    if (manager === "pnpm") {
+async function packageManagerArgs(runner, manager, workspaceRoot, operation, packageSpec) {
+    if (manager.name === "pnpm") {
         return operation === "remove"
             ? ["remove", "--ignore-scripts", packageSpec]
             : ["add", "--save-exact", "--ignore-scripts", packageSpec];
     }
+    if (manager.name === "npm") {
+        return operation === "remove"
+            ? ["uninstall", "--ignore-scripts", packageSpec]
+            : ["install", "--save-exact", "--ignore-scripts", packageSpec];
+    }
+    const major = await yarnMajorVersion(runner, manager, workspaceRoot);
+    if (major <= 1) {
+        return operation === "remove"
+            ? ["remove", "--ignore-scripts", packageSpec]
+            : ["add", "--exact", "--ignore-scripts", packageSpec];
+    }
     return operation === "remove"
-        ? ["uninstall", "--ignore-scripts", packageSpec]
-        : ["install", "--save-exact", "--ignore-scripts", packageSpec];
+        ? ["remove", "--mode=skip-build", packageSpec]
+        : ["add", "--exact", "--mode=skip-build", packageSpec];
+}
+async function yarnMajorVersion(runner, manager, workspaceRoot) {
+    const declaredVersion = declaredPackageManagerVersion(manager.declared);
+    const value = declaredVersion ??
+        (await runner.run("yarn", ["--version"], workspaceRoot)).trim();
+    const major = Number.parseInt(value.split(".")[0] ?? "", 10);
+    if (!Number.isInteger(major) || major < 1) {
+        throw new PlatformError("PACKAGE_MANAGER_UNAVAILABLE", `cannot determine a supported Yarn major version from ${value || "<empty>"}`);
+    }
+    return major;
+}
+function declaredPackageManagerVersion(declared) {
+    if (declared === undefined)
+        return undefined;
+    const separator = declared.lastIndexOf("@");
+    return separator > 0 ? declared.slice(separator + 1) : undefined;
 }
-async function requirePackageManager(workspaceRoot) {
+async function requirePackageManager(workspaceRoot, executableAvailable) {
     const manager = await readWorkspacePackageManagerSelection(workspaceRoot);
-    if (manager === undefined) {
-        throw new PlatformError("APPLY_FAILED", "workspace packageManager is not supported; expected npm or pnpm");
+    if (!executableAvailable(manager.name)) {
+        throw new PlatformError("PACKAGE_MANAGER_UNAVAILABLE", `workspace package manager ${manager.name} is not available on PATH`);
     }
     return manager;
 }

package/dist/src/apply/execute.js

@@ -6,6 +6,29 @@ import { cleanupRemovableFilesystemEffects } from "./cleanup.js";
 function moduleOf(plan, step) {
     return plan.resolvedModules.find((module) => module.moduleRef === step.moduleRef);
 }
+function moduleSourceForMaterialization(module) {
+    if (module.source.type === "registry") {
+        throw new PlatformError("APPLY_FAILED", `registry bootstrap target ${module.packageName} has no local config materializer`);
+    }
+    return {
+        type: module.source.type,
+        packageName: module.packageName,
+        ...(module.source.path === undefined ? {} : { path: module.source.path }),
+    };
+}
+async function materializeModuleOwnedConfig(deps, module, config) {
+    const namespace = await deps.catalog.loadAdapter(moduleSourceForMaterialization(module));
+    if (typeof namespace !== "object" || namespace === null)
+        return;
+    const materializer = Reflect.get(namespace, "materializeProductionConfig");
+    if (typeof materializer !== "function")
+        return;
+    await materializer({
+        moduleRef: module.moduleRef,
+        config: config.values,
+        workspaceRoot: deps.paths.root,
+    });
+}
 function configForStep(plan, step, module) {
     const target = plan.moduleTargets.find((entry) => entry.moduleRef === step.moduleRef);
     if (target?.config === undefined)
@@ -98,6 +121,11 @@ export async function executeStep(deps, step, plan) {
             if (config === undefined) {
                 throw new PlatformError("APPLY_FAILED", `module ${step.moduleRef} has no config target to materialize`);
             }
+            // The Platform-owned public config is authoritative apply reality. Do not
+            // commit it until the module-owned materializer has accepted the target;
+            // otherwise a failed materializer can leave a false-satisfied config step
+            // that a same-plan resume would incorrectly SKIP.
+            await materializeModuleOwnedConfig(deps, module, config);
             await materializeConfig(deps.paths, config);
             return { kind: "SUCCEEDED" };
         }

package/dist/src/binding/global-binding.d.ts

@@ -0,0 +1,69 @@
+export declare const GLOBAL_BINDING_CONTRACT: "deployment.global-binding.v1";
+export declare const WORKSPACE_INSTANCE_CONTRACT: "deployment.workspace-instance.v1";
+export type GlobalBindingState = "INSTALLING" | "INSTALLED" | "UNINSTALLING" | "BROKEN";
+export interface GlobalWorkspaceBinding {
+    contract: typeof GLOBAL_BINDING_CONTRACT;
+    state: GlobalBindingState;
+    workspacePath: string;
+    workspaceRealPath: string;
+    workspaceInstanceId: string;
+    createdAt: string;
+    updatedAt: string;
+    failure?: {
+        code: string;
+        message: string;
+    };
+}
+export interface WorkspaceInstanceMarker {
+    contract: typeof WORKSPACE_INSTANCE_CONTRACT;
+    workspaceInstanceId: string;
+    workspaceRealPath: string;
+    createdAt: string;
+}
+export interface GlobalPlatformPaths {
+    root: string;
+    bindingJson: string;
+    bindingLock: string;
+    operationLock: string;
+}
+export interface BoundWorkspaceObservation {
+    binding: GlobalWorkspaceBinding;
+    workspaceExists: boolean;
+}
+export interface GlobalBindingLockHandle {
+    release(): Promise<void>;
+}
+export declare function globalPlatformPaths(globalRoot?: string): GlobalPlatformPaths;
+export declare function canonicalizeWorkspace(workspace: string): Promise<{
+    workspacePath: string;
+    workspaceRealPath: string;
+}>;
+export declare function loadGlobalBinding(globalRoot?: string): Promise<GlobalWorkspaceBinding | undefined>;
+export declare function observeBoundWorkspace(globalRoot?: string): Promise<BoundWorkspaceObservation | undefined>;
+export declare function requireBoundWorkspace(globalRoot?: string): Promise<GlobalWorkspaceBinding>;
+export declare function claimWorkspaceBinding(options: {
+    workspace: string;
+    globalRoot?: string | undefined;
+}): Promise<{
+    binding: GlobalWorkspaceBinding;
+    alreadyBound: boolean;
+}>;
+export declare function updateGlobalBindingState(options: {
+    workspaceInstanceId: string;
+    state: GlobalBindingState;
+    globalRoot?: string | undefined;
+    failure?: {
+        code: string;
+        message: string;
+    };
+}): Promise<GlobalWorkspaceBinding>;
+export declare function clearGlobalBinding(options: {
+    workspaceInstanceId: string;
+    globalRoot?: string | undefined;
+    removeWorkspaceMarker?: boolean;
+}): Promise<void>;
+export declare function forgetMissingWorkspaceBinding(options: {
+    globalRoot?: string | undefined;
+}): Promise<GlobalWorkspaceBinding>;
+export declare function acquireGlobalBindingLock(paths: GlobalPlatformPaths): Promise<GlobalBindingLockHandle>;
+export declare function acquireGlobalOperationLock(globalRoot?: string): Promise<GlobalBindingLockHandle>;