@tomflow/proflow-platform-cli 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.20
+
+### Patch Changes
+
+- Close the frozen seven-command contract: enforce start and install safety gates, align Module result semantics and published documentation, and refresh current test evidence.
+
+## 0.1.19
+
+### Patch Changes
+
+- Preserve the complete platform setup guidance when machine failures and human actions are present together.
+
 ## 0.1.18
 
 ### Patch Changes

package/README.md

@@ -1,64 +1,68 @@
 # @tomflow/proflow-platform-cli
 
-Deterministic Workspace-level CLI for ProFlow Platform installation, discovery, knowledge aggregation and lifecycle dispatch.
+Thin Workspace-level orchestration CLI for ProFlow package discovery, dependency ordering, command forwarding, result aggregation and package-manager operations.
 
-## Frozen CLI
+## Standard CLI
+
+The top-level management surface is exactly seven commands:
 
 ```bash
-platform modules
-platform docs
 platform install
 platform uninstall
+platform status
+platform setup
+platform docs
 platform start
 platform stop
 ```
 
-Removed top-level commands: `search`, `plan`, `apply`, `upgrade`, `preflight`, `restart`, `status`, `verify`, `doctor`, `manifest`.
+Removed Platform routes such as `modules`, `preflight`, `verify`, `doctor`, `restart`, `plan`, `apply`, `upgrade` and `manifest` are not routable. Module-specific commands remain owned by their Module and are not proxied by Platform.
+
+All seven commands accept `--workspace <path>`; without it, the CLI uses `process.cwd()`.
 
 ## Ownership
 
 ```text
-Module / package owns logic and truth.
-Platform CLI owns discovery, dispatch, aggregation and ordering.
-Package manager owns npm dependency operations.
+Module owns its behavior, private configuration and operational truth.
+Platform owns discovery, dependency ordering, invocation, aggregation and package-manager orchestration.
+Package manager owns npm dependency mutation.
 ```
 
-## Workspace
-
-`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.
+Platform does not interpret Module-private configuration or recreate a cross-Module configuration bus.
 
-`.proflow` is Workspace/user data and may survive uninstall/reinstall. `platform uninstall` removes ProFlow package dependencies only and never deletes `.proflow`.
+## Install / Uninstall
 
-## Install
+`platform install` validates or creates the minimal Workspace metadata, discovers the complete governed package set from the Registry, synchronizes that set, validates the installed descriptors, then invokes `Module.install` in dependency order. It does not perform human setup work.
 
-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.
+`platform uninstall` invokes `Module.uninstall` in reverse dependency order before package removal. `.proflow` is Workspace/user data and is preserved unless an owning Module explicitly removes its own artifacts.
 
-There is no Core package class, `installRequires`, install closure, Plan/Apply or independent Upgrade flow.
+## Status
 
-## Modules
-
-`platform modules` aggregates Module-owned status observations only:
+`platform status` validates and aggregates only Module-owned observations:
 
 ```text
-moduleRef
-version
-configStatus: READY | INCOMPLETE | INVALID
-missingConfig?  # only when INCOMPLETE
-runtimeStatus: RUNNING | STOPPED | FAILED | UNKNOWN
+setupStatus: READY | ACTION_REQUIRED | FAILED
+runtimeStatus: RUNNING | STOPPED | FAILED | NOT_APPLICABLE
 ```
 
-Platform does not infer private health/config/runtime facts.
+There is no Platform-derived configuration status, missing-input list, overall readiness or verification state.
+
+## Setup
+
+`platform setup` scans all discovered Modules in dependency order. It skips `READY` Modules, invokes `Module.setup` for every non-ready Module, continues after `ACTION_REQUIRED` or `FAILED`, and returns one complete aggregate.
+
+Targeted `platform setup --module <moduleRef> --input '<json>'` forwards opaque input to the owning Module. Platform neither interprets that input nor creates Module-specific instructions.
 
 ## Docs
 
-`platform docs` aggregates each installed Module's `provides`, `requires`, `configSlots` and static documentation. It accepts no module/document positional argument.
+`platform docs` invokes and aggregates `Module.docs`. `DOCS.md` and `SETUP.md` remain Module-owned knowledge.
 
 ## 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.
+`platform start` first completes the dependency-ordered `Module.status` setup gate. If any applicable Module has `setupStatus != READY`, no `Module.start` call is made. Once every Module is ready, starts run in dependency order and fail fast. A start failure does not trigger automatic rollback.
 
-Stop dispatches Module stop in reverse dependency order and fails fast.
+`platform stop` invokes `Module.stop` in reverse dependency order and fails fast.
 
 ## Boundary
 
-The CLI must remain thin: new compliant Modules should become discoverable/observable/startable without adding module-specific business logic here.
+The CLI remains a thin, generic orchestration layer. Adding a conforming Module must not require Module-specific Platform business logic.

package/dist/deployment/adapter.d.ts

@@ -6,7 +6,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.18";
+            readonly moduleVersion: "0.1.19";
         };
         observedEffects: never[];
     }>;
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.18";
+            readonly moduleVersion: "0.1.19";
         };
         observedEffects: never[];
     }>;
@@ -26,7 +26,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.18";
+            moduleVersion: "0.1.19";
             data: {
                 readonly setupStatus: "READY";
                 readonly runtimeStatus: "NOT_APPLICABLE";
@@ -40,7 +40,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.18";
+            readonly moduleVersion: "0.1.19";
         };
         observedEffects: never[];
     }>;
@@ -50,7 +50,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.18";
+            moduleVersion: "0.1.19";
             data: {
                 docs: string;
                 setup: string;
@@ -64,7 +64,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.18";
+            readonly moduleVersion: "0.1.19";
         };
         observedEffects: never[];
     }>;
@@ -74,7 +74,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.18";
+            readonly moduleVersion: "0.1.19";
         };
         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.18";
+    readonly moduleVersion: "0.1.19";
     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.18",
+    moduleVersion: "0.1.19",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.js

@@ -415,12 +415,20 @@ function renderSetup(data) {
         pending += 1;
         lines.push(`## ${moduleRef} — ${status}`);
         const actionRequired = raw.result.actionRequired;
+        const error = raw.result.error;
         if (isRecord(actionRequired)) {
             if (actionRequired.action !== undefined)
                 lines.push(`Action: ${String(actionRequired.action)}`);
             if (actionRequired.description !== undefined)
                 lines.push(String(actionRequired.description));
         }
+        else if (isRecord(error)) {
+            const code = error.code === undefined ? "FAILED" : String(error.code);
+            const message = error.message === undefined
+                ? "Module setup failed."
+                : String(error.message);
+            lines.push(`Error: ${code} — ${message}`);
+        }
         else if (raw.result.data !== undefined) {
             lines.push(JSON.stringify(raw.result.data, null, 2));
         }
@@ -433,6 +441,10 @@ function renderSetup(data) {
     return lines.join("\n").trimEnd();
 }
 export function renderHumanResult(result) {
+    if (result.command === "setup" &&
+        isRecord(result.data) &&
+        Array.isArray(result.data.results))
+        return renderSetup(result.data);
     if (result.status === "FAILED")
         return `${result.command.toUpperCase()} FAILED${result.error ? ` [${result.error.code}] ${result.error.message}` : ""}`;
     if (result.command === "help")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -23,7 +23,7 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.5"
+    "@tomflow/proflow-module-contract": "^0.1.6"
   },
   "devDependencies": {
     "@tomflow/proflow-module-template": "^0.1.5",

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "platform-cli",
 	"packageName": "@tomflow/proflow-platform-cli",
-	"moduleVersion": "0.1.18",
+	"moduleVersion": "0.1.20",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",