@tomflow/proflow-platform-cli 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @tomflow/proflow-platform-cli
+
+## 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
+
+- Align all Modules to the seven-command setup contract with executable package-owned setup guidance and full Platform setup aggregation.

package/SETUP.md

@@ -1,7 +1,27 @@
 # @tomflow/proflow-platform-cli — Module Setup
 
-No user or external setup is required by the current frozen Module contract. `Module.install` completes deterministic preparation; `Module.setup` only re-observes current reality and must not ask the user to supply private paths, loopback endpoints, tokens or cross-Module facts.
+The Platform CLI owns orchestration only. It never interprets another Module's setup details. Global `platform setup` traverses every discovered Module, skips `READY` Modules, lets each non-ready Module run its own package-owned setup workflow, and aggregates every remaining `ACTION_REQUIRED` or `FAILED` result in one response.
 
-## Completion
+## Step 1 — Verify the Platform CLI Module
 
-Setup is complete only when the Module's own `status` reports `setupStatus=READY`. Re-running setup must re-observe reality; it must not resume from a blind historical step index.
+**Executable:**
+
+```bash
+platform setup --module platform-cli
+```
+
+**Success condition:**
+
+`platform status` reports `platform-cli setup=READY`. No user/private path, token, loopback endpoint, or cross-Module fact is requested.
+
+## Step 2 — Run the full workspace setup guide
+
+**Executable:**
+
+```bash
+platform setup
+```
+
+**Success condition:**
+
+All automatically solvable Module setup work is completed in the same run, and every remaining human/external action is listed together. Re-running the command re-observes reality and continues until all required Modules report `setupStatus=READY`.

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.17";
+            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.17";
+            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.17";
+            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.17";
+            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.17";
+            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.17";
+            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.17";
+            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.17";
+    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.17",
+    moduleVersion: "0.1.19",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.js

@@ -81,8 +81,6 @@ function parseArgs(argv) {
     if (!COMMANDS.includes(raw))
         throw new PlatformError("INVALID_REQUEST", `unknown command ${raw}`);
     const command = raw;
-    if (workspace !== undefined && command !== "install")
-        throw new PlatformError("INVALID_REQUEST", "--workspace is only valid with install");
     if ((moduleRef !== undefined || inputSeen) && command !== "setup")
         throw new PlatformError("INVALID_REQUEST", "--module/--input are only valid with setup");
     if (inputSeen && moduleRef === undefined)
@@ -137,7 +135,14 @@ function batchStatus(result) {
         return result.blockedBy.setupStatus === "ACTION_REQUIRED"
             ? "ACTION_REQUIRED"
             : "FAILED";
-    return statusFromModule(result.results.at(-1)?.result.status ?? "FAILED");
+    const statuses = result.results.map((item) => statusFromModule(item.result.status));
+    if (statuses.includes("FAILED"))
+        return "FAILED";
+    if (statuses.includes("BLOCKED"))
+        return "BLOCKED";
+    if (statuses.includes("ACTION_REQUIRED"))
+        return "ACTION_REQUIRED";
+    return "FAILED";
 }
 async function handleStatus(root) {
     const { catalog, modules } = await buildContext(root);
@@ -312,10 +317,10 @@ async function handleStop(root) {
 }
 function helpOutcome() {
     return outcome("help", "SUCCEEDED", undefined, {
-        usage: "platform <install|uninstall|status|setup|docs|start|stop> [--json]",
+        usage: "platform <install|uninstall|status|setup|docs|start|stop> [--workspace <path>] [--json]",
         commands: [...COMMANDS],
         install: "platform install [--workspace <path>]",
-        setup: "platform setup [--module <moduleRef> --input '<json>']",
+        setup: "platform setup [--workspace <path>] [--module <moduleRef> --input '<json>']",
     });
 }
 export async function runCli(argv, runtime = {}) {
@@ -333,10 +338,7 @@ export async function runCli(argv, runtime = {}) {
             return JSON.stringify(outcome("version", "SUCCEEDED", undefined, {
                 version: platformCliDescriptor.moduleVersion,
             }));
-        const cwd = await canonicalWorkspace(runtime.cwd ?? process.cwd());
-        const root = parsed.command === "install" && parsed.workspace !== undefined
-            ? await canonicalWorkspace(cwd, parsed.workspace)
-            : cwd;
+        const root = await canonicalWorkspace(runtime.cwd ?? process.cwd(), parsed.workspace);
         switch (parsed.command) {
             case "install":
                 return JSON.stringify(await handleInstall(root, runtime));
@@ -395,7 +397,54 @@ function renderDocs(data) {
             lines.push("", `## ${String(raw.moduleRef)} @ ${String(raw.version)}`, JSON.stringify(raw.docs ?? {}, null, 2));
     return lines.join("\n");
 }
+function renderSetup(data) {
+    if (!isRecord(data) || !Array.isArray(data.results))
+        return "No setup actions are required.";
+    const lines = ["ProFlow Setup", ""];
+    let automatic = 0;
+    let pending = 0;
+    for (const raw of data.results) {
+        if (!isRecord(raw) || !isRecord(raw.result))
+            continue;
+        const moduleRef = String(raw.moduleRef ?? raw.result.moduleRef ?? "unknown");
+        const status = String(raw.result.status ?? "UNKNOWN");
+        if (status === "SUCCEEDED") {
+            automatic += 1;
+            continue;
+        }
+        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));
+        }
+        lines.push("");
+    }
+    if (pending === 0)
+        lines.push("All discovered Modules are setup-ready.");
+    if (automatic > 0)
+        lines.push(`Automatically completed in this run: ${automatic}`);
+    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")
@@ -412,6 +461,8 @@ export function renderHumanResult(result) {
         return String(result.data.version ?? platformCliDescriptor.moduleVersion);
     if (result.command === "status")
         return renderStatus(result.data);
+    if (result.command === "setup")
+        return renderSetup(result.data);
     if (result.command === "docs")
         return renderDocs(result.data);
     return [

package/dist/src/lifecycle/thin.js

@@ -40,28 +40,33 @@ export const stopModulesThin = (catalog, modules, workspaceRoot) => runOrdered(c
 export async function setupModulesThin(catalog, modules, workspaceRoot, target) {
     const results = [];
     let matched = target === undefined;
+    let completed = true;
     for (const module of ordered(modules)) {
         if (target !== undefined && module.moduleRef !== target.moduleRef)
             continue;
         matched = true;
         const status = await dispatchModuleCommand(catalog, module, "status", context(workspaceRoot));
-        if (!succeeded(status.result))
-            return {
-                phase: "setup",
-                results: [...results, status],
-                completed: false,
-            };
+        if (!succeeded(status.result)) {
+            results.push(status);
+            completed = false;
+            if (target !== undefined)
+                break;
+            continue;
+        }
         const observed = moduleStatusObservationSchema.parse(status.result.data);
         if (observed.setupStatus === "READY" && target?.input === undefined)
             continue;
         const setup = await dispatchModuleCommand(catalog, module, "setup", context(workspaceRoot, target?.input));
         results.push(setup);
-        if (!succeeded(setup.result))
-            return { phase: "setup", results, completed: false };
+        if (!succeeded(setup.result)) {
+            completed = false;
+            if (target !== undefined)
+                break;
+        }
     }
     if (!matched)
         throw new PlatformError("INVALID_REQUEST", `setup target module ${target?.moduleRef ?? ""} was not discovered`);
-    return { phase: "setup", results, completed: true };
+    return { phase: "setup", results, completed };
 }
 export async function startModulesThin(catalog, modules, workspaceRoot) {
     const results = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-platform-cli",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -23,11 +23,11 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.4"
+    "@tomflow/proflow-module-contract": "^0.1.5"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.4",
-    "@tomflow/proflow-module-template": "^0.1.4"
+    "@tomflow/proflow-module-template": "^0.1.5",
+    "@tomflow/proflow-deployment-conformance": "^0.1.5"
   },
   "description": "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.",
   "keywords": [

package/proflow.module.json

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