@tomflow/proflow-platform-cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @tomflow/proflow-platform-cli
+
+## 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
+
+- Read installed package versions directly from the Workspace `node_modules` package manifest so postcondition checks cannot reuse stale Node module-resolution cache entries after an in-process package upgrade.

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.0";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.0";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -27,7 +27,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.0";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -38,7 +38,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.0";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -49,7 +49,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.0";
+            moduleVersion: "0.1.2";
             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.0";
+    readonly moduleVersion: "0.1.2";
     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.0",
+    moduleVersion: "0.1.2",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

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,9 +1,7 @@
 import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { pathToFileURL } from "node:url";
+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
@@ -22,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);
     }
@@ -49,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;
 }
@@ -92,35 +118,21 @@ async function observeInstalledVersion(workspaceRoot, packageName) {
             !hasOwn(manifest.devDependencies, packageName))) {
         return undefined;
     }
-    const require = createRequire(pathToFileURL(join(workspaceRoot, "package.json")));
-    let entry;
     try {
-        entry = require.resolve(packageName);
+        const raw = await readFile(join(workspaceRoot, "node_modules", ...packageName.split("/"), "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            Reflect.get(parsed, "name") === packageName &&
+            typeof Reflect.get(parsed, "version") === "string") {
+            return Reflect.get(parsed, "version");
+        }
+        return undefined;
     }
     catch {
         return undefined;
     }
-    let current = dirname(entry);
-    for (;;) {
-        try {
-            const raw = await readFile(join(current, "package.json"), "utf8");
-            const parsed = JSON.parse(raw);
-            if (typeof parsed === "object" &&
-                parsed !== null &&
-                !Array.isArray(parsed) &&
-                Reflect.get(parsed, "name") === packageName &&
-                typeof Reflect.get(parsed, "version") === "string") {
-                return Reflect.get(parsed, "version");
-            }
-        }
-        catch {
-            // keep walking to the package root
-        }
-        const parent = dirname(current);
-        if (parent === current)
-            return undefined;
-        current = parent;
-    }
 }
 async function readWorkspaceManifest(workspaceRoot) {
     try {

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>;