@tomflow/proflow-platform-cli 0.1.14 → 0.1.16

package/README.md

@@ -1,59 +1,64 @@
-# platform-cli
+# @tomflow/proflow-platform-cli
 
-Domain Owner: deployment-governance  
-Module Kind: cli  
-Service: none  
-Process: none  
-Business Fact Owner: none
+Deterministic Workspace-level CLI for ProFlow Platform installation, discovery, knowledge aggregation and lifecycle dispatch.
 
-## Purpose
+## Frozen CLI
 
-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.
+```bash
+platform modules
+platform docs
+platform install
+platform uninstall
+platform start
+platform stop
+```
 
-## Global CLI bootstrap
+Removed top-level commands: `search`, `plan`, `apply`, `upgrade`, `preflight`, `restart`, `status`, `verify`, `doctor`, `manifest`.
 
-The v1 `platform` command is a Shell-global control plane. A straightforward bootstrap is:
+## Ownership
 
 ```text
-npm install --global @tomflow/proflow-platform-cli
+Module / package owns logic and truth.
+Platform CLI owns discovery, dispatch, aggregation and ordering.
+Package manager owns npm dependency operations.
 ```
 
-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.
+## Workspace
 
-## Commands
+`platform install [--workspace <path>]` resolves the explicit workspace or `process.cwd()`. The other five commands operate on `process.cwd()` and do not depend on a global current-workspace binding.
 
+`.proflow` is Workspace/user data and may survive uninstall/reinstall. `platform uninstall` removes ProFlow package dependencies only and never deletes `.proflow`.
+
+## Install
+
+Install dynamically discovers the complete managed ProFlow package/version set from the private npm scope, synchronizes it in one package-manager transaction where possible, re-observes installed packages, validates descriptors, then initializes/reuses minimal Workspace-local metadata.
+
+There is no Core package class, `installRequires`, install closure, Plan/Apply or independent Upgrade flow.
+
+## Modules
+
+`platform modules` aggregates Module-owned status observations only:
+
+```text
+moduleRef
+version
+configStatus: READY | INCOMPLETE | INVALID
+missingConfig?  # only when INCOMPLETE
+runtimeStatus: RUNNING | STOPPED | FAILED | UNKNOWN
 ```
-platform search [package]
-platform modules [module|package]
-platform docs [module|package] [documentId]
-platform preflight [module]
-platform preflight --intent install
-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>
-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.
+Platform does not infer private health/config/runtime facts.
+
+## Docs
+
+`platform docs` aggregates each installed Module's `provides`, `requires`, `configSlots` and static documentation. It accepts no module/document positional argument.
+
+## Start / Stop
+
+Start builds Runtime dependency order from `provides/requires`, dispatches all applicable Module validate/preflight first (fail-fast), then starts in dependency order (fail-fast). It does not rollback already-started Modules.
 
+Stop dispatches Module stop in reverse dependency order and fails fast.
 
-## v1 global workspace semantics
+## Boundary
 
-- 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.
-- Whole-instance uninstall removes managed ProFlow modules plus Deployment-owned `.proflow/deployment` state (plans, deployment state, verification, and instance identity). Business/domain data outside `.proflow/deployment` is intentionally preserved. v1 has no purge mode, so ordinary uninstall never claims to delete preserved domain data.
-- 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.
+The CLI must remain thin: new compliant Modules should become discoverable/observable/startable without adding module-specific business logic here.

package/dist/deployment/adapter.d.ts

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

package/dist/deployment/adapter.js

@@ -1,3 +1,4 @@
+import { observeDeclaredModuleStatus } from "@tomflow/proflow-module-contract";
 import { descriptor } from "./descriptor.js";
 const success = (data) => ({
     contract: "deployment.result.v1",
@@ -14,7 +15,7 @@ export const behaviorAdapter = {
     }),
     preflight: () => ({ result: success(), observedEffects: [] }),
     status: () => ({
-        result: success({ runnable: true }),
+        result: success(observeDeclaredModuleStatus(descriptor, undefined, "UNKNOWN")),
         observedEffects: [],
     }),
     verify: () => ({

package/dist/deployment/descriptor.d.ts

@@ -3,14 +3,13 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "platform-cli";
     readonly packageName: "@tomflow/proflow-platform-cli";
-    readonly moduleVersion: "0.1.14";
+    readonly moduleVersion: "0.1.16";
     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 summary: "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.";
     };
     readonly provides: readonly [];
     readonly requires: readonly [];

package/dist/deployment/descriptor.js

@@ -3,14 +3,13 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "platform-cli",
     packageName: "@tomflow/proflow-platform-cli",
-    moduleVersion: "0.1.14",
+    moduleVersion: "0.1.16",
     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.",
+        summary: "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.",
     },
     provides: [],
     requires: [],

package/dist/src/binding/production-bindings.d.ts

@@ -2,7 +2,6 @@ import type { ResolvedModule } from "../contracts.ts";
 type ResolvedSource = ResolvedModule["source"];
 export interface DeploymentAdapterBinding {
     behaviorAdapter: Record<string, unknown>;
-    materializeProductionConfig?: (...args: unknown[]) => unknown;
 }
 export type ProductionBindingFactory = (input: {
     moduleRef: string;
@@ -11,25 +10,28 @@ export type ProductionBindingFactory = (input: {
     modules: readonly ResolvedModule[];
     configByModuleRef: ReadonlyMap<string, Record<string, string>>;
 }) => Promise<DeploymentAdapterBinding | undefined> | DeploymentAdapterBinding | undefined;
-export type ServiceProcessBindingFactory = (input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    workspaceRoot: string;
-    modules: readonly ResolvedModule[];
-    configByModuleRef: ReadonlyMap<string, Record<string, string>>;
-}) => Promise<{
-    serviceProcess: unknown;
-    behaviorAdapter?: Record<string, unknown>;
-} | undefined> | {
-    serviceProcess: unknown;
-    behaviorAdapter?: Record<string, unknown>;
-} | undefined;
 export interface ProductionBindingOptions {
     workspaceRoot: string;
     modules: readonly ResolvedModule[];
-    configByModuleRef: ReadonlyMap<string, Record<string, string>>;
+    configByModuleRef: ReadonlyMap<string, {
+        publicValues: Record<string, string>;
+        secretValues: Record<string, string>;
+    }>;
     importAdapter: (packageName: string, source: ResolvedSource) => Promise<Record<string, unknown>>;
 }
 export declare function importRawAdapter(packageName: string, source: ResolvedSource, workspaceRoot: string): Promise<Record<string, unknown>>;
+/**
+ * The shipped Platform CLI production binding factory. For every discovered
+ * module it imports the module's own `deployment/adapter.ts` and, when that
+ * adapter exposes a `createProductionBinding` factory, invokes it with the
+ * module's materialized config to obtain a real bound adapter. A module without
+ * a production factory, or whose materialized config the adapter does not accept,
+ * is left out of the map. Import/factory exceptions are surfaced with module
+ * identity instead of being mistaken for ordinary unconfigured state. The
+ * catalog falls back to the module's unbound default only for explicit undefined
+ * bindings, which must fail-closed
+ * (ACTION_REQUIRED / NOT_READY). Platform CLI never invents a service or
+ * resource reality: it only relays the adapter's own current reality.
+ */
 export declare function buildProductionBindings(options: ProductionBindingOptions): Promise<ReadonlyMap<string, DeploymentAdapterBinding>>;
 export {};

package/dist/src/binding/production-bindings.js

@@ -9,19 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { managedServiceStatus, restartManagedService, startManagedService, stopManagedService, } from "../lifecycle/service-process.js";
-import { workspacePaths } from "../paths.js";
-function managedServiceAdapter(workspaceRoot, module, serviceProcess, probeAdapter) {
-    const paths = workspacePaths(workspaceRoot);
-    return {
-        ...probeAdapter,
-        status: () => managedServiceStatus(paths, module),
-        start: () => startManagedService(paths, module, serviceProcess),
-        stop: () => stopManagedService(paths, module),
-        restart: () => restartManagedService(paths, module, serviceProcess),
-        uninstall: () => stopManagedService(paths, module),
-    };
-}
+import { PlatformError } from "../errors.js";
 export async function importRawAdapter(packageName, source, workspaceRoot) {
     if (source.type === "workspace") {
         if (source.path === undefined)
@@ -39,52 +27,27 @@ export async function importRawAdapter(packageName, source, workspaceRoot) {
  * module it imports the module's own `deployment/adapter.ts` and, when that
  * adapter exposes a `createProductionBinding` factory, invokes it with the
  * module's materialized config to obtain a real bound adapter. A module without
- * a production factory — or whose import/factory fails, or which has no
- * materialized config the adapter accepts — is left out of the map, so the
- * catalog falls back to the module's unbound default, which must fail-closed
+ * a production factory, or whose materialized config the adapter does not accept,
+ * is left out of the map. Import/factory exceptions are surfaced with module
+ * identity instead of being mistaken for ordinary unconfigured state. The
+ * catalog falls back to the module's unbound default only for explicit undefined
+ * bindings, which must fail-closed
  * (ACTION_REQUIRED / NOT_READY). Platform CLI never invents a service or
  * resource reality: it only relays the adapter's own current reality.
  */
-function materializerBinding(namespace) {
-    const materializer = namespace.materializeProductionConfig;
-    return typeof materializer === "function"
-        ? {
-            materializeProductionConfig: materializer,
-        }
-        : {};
-}
 export async function buildProductionBindings(options) {
     const bindings = new Map();
+    const publicConfigByModuleRef = new Map([...options.configByModuleRef].map(([moduleRef, config]) => [
+        moduleRef,
+        { ...config.publicValues },
+    ]));
     for (const module of options.modules) {
         try {
             const namespace = await options.importAdapter(module.packageName, module.source);
-            const config = options.configByModuleRef.get(module.moduleRef) ?? {};
-            const serviceFactory = namespace.createServiceProcessBinding;
-            if (module.kind === "service" && typeof serviceFactory === "function") {
-                const processBinding = await serviceFactory({
-                    moduleRef: module.moduleRef,
-                    config,
-                    workspaceRoot: options.workspaceRoot,
-                    modules: options.modules,
-                    configByModuleRef: options.configByModuleRef,
-                });
-                if (processBinding !== undefined) {
-                    const defaultProbe = namespace
-                        .behaviorAdapter;
-                    const probeAdapter = processBinding.behaviorAdapter ??
-                        (typeof defaultProbe === "object" && defaultProbe !== null
-                            ? defaultProbe
-                            : {});
-                    bindings.set(module.packageName, {
-                        behaviorAdapter: managedServiceAdapter(options.workspaceRoot, module, processBinding.serviceProcess, probeAdapter),
-                        ...materializerBinding(namespace),
-                    });
-                }
-                // A formal service package that exposes the process seam must never fall
-                // back to legacy in-memory production binding. Missing config remains
-                // unbound and therefore fails closed.
-                continue;
-            }
+            const materialized = options.configByModuleRef.get(module.moduleRef);
+            const config = materialized === undefined
+                ? {}
+                : { ...materialized.publicValues, ...materialized.secretValues };
             const factory = namespace
                 .createProductionBinding;
             if (typeof factory !== "function")
@@ -94,22 +57,18 @@ export async function buildProductionBindings(options) {
                 config,
                 workspaceRoot: options.workspaceRoot,
                 modules: options.modules,
-                configByModuleRef: options.configByModuleRef,
+                configByModuleRef: publicConfigByModuleRef,
             });
             if (binding !== undefined &&
                 typeof binding === "object" &&
                 binding !== null &&
                 typeof binding.behaviorAdapter === "object" &&
                 binding.behaviorAdapter !== null) {
-                bindings.set(module.packageName, {
-                    ...binding,
-                    ...materializerBinding(namespace),
-                });
+                bindings.set(module.packageName, binding);
             }
         }
-        catch {
-            // Import/factory failure for one module must not break the rest of the
-            // CLI; that module simply remains unbound and fails closed when used.
+        catch (error) {
+            throw new PlatformError("COMMAND_FAILED", `production binding failed for ${module.moduleRef}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     return bindings;

package/dist/src/cli.d.ts

@@ -1,16 +1,12 @@
 #!/usr/bin/env node
-import { type GlobalWorkspaceBinding } from "./binding/global-binding.ts";
+import { type PackageCommandRunner } from "./install/package-manager.ts";
+import { type NpmCommandRunner } from "./registry/index.ts";
 export type CliStatus = "SUCCEEDED" | "ACTION_REQUIRED" | "BLOCKED" | "FAILED";
-export interface CliWorkspaceSummary {
-    boundWorkspace: string;
-    workspaceInstanceId: string;
-    bindingState: GlobalWorkspaceBinding["state"];
-}
 export interface CliOutcome {
     command: string;
     status: CliStatus;
+    workspaceRoot?: string;
     data?: unknown;
-    workspace?: CliWorkspaceSummary;
     error?: {
         code: string;
         message: string;
@@ -18,7 +14,9 @@ export interface CliOutcome {
 }
 export interface CliRuntimeOptions {
     cwd?: string;
-    globalRoot?: string;
+    registryRunner?: NpmCommandRunner;
+    packageRunner?: PackageCommandRunner;
+    executableAvailable?: (command: string) => boolean;
 }
-export declare function renderHumanResult(machineOutput: string): string;
 export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<string>;
+export declare function renderHumanResult(result: CliOutcome): string;