@tomflow/proflow-platform-cli 0.1.1 → 0.1.3

package/dist/src/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
+import { readFile, rm } from "node:fs/promises";
 import { parseModuleDescriptor, } from "@tomflow/proflow-module-contract";
 import { descriptor as platformCliDescriptor } from "../deployment/descriptor.js";
 import { applyPlan } from "./apply/apply.js";
 import { rebuildCurrentAssumptions } from "./apply/current.js";
 import { createWorkspacePackageManagerDriver } from "./apply/driver.js";
+import { acquireGlobalOperationLock, canonicalizeWorkspace, claimWorkspaceBinding, clearGlobalBinding, forgetMissingWorkspaceBinding, loadGlobalBinding, observeBoundWorkspace, requireBoundWorkspace, updateGlobalBindingState, } from "./binding/global-binding.js";
 import { buildProductionBindings, importRawAdapter, } from "./binding/production-bindings.js";
 import { AutoModuleCatalog, discoverModules } from "./discovery/discover.js";
 import { describeModule, readModuleDocument } from "./docs/docs.js";
@@ -52,6 +53,7 @@ function parseArgs(argv) {
         workspace: undefined,
         intent: undefined,
         configFile: undefined,
+        forget: false,
         positional,
     };
     for (let index = 1; index < argv.length; index += 1) {
@@ -59,18 +61,22 @@ function parseArgs(argv) {
         if (token === undefined)
             continue;
         if (token === "--workspace") {
-            parsed.workspace = argv[index + 1];
+            parsed.workspace = requiredOptionValue(argv, index, token);
             index += 1;
         }
         else if (token === "--intent") {
-            parsed.intent = argv[index + 1];
+            parsed.intent = requiredOptionValue(argv, index, token);
             index += 1;
         }
         else if (token === "--config") {
-            parsed.configFile = argv[index + 1];
+            parsed.configFile = requiredOptionValue(argv, index, token);
             index += 1;
         }
+        else if (token === "--forget") {
+            parsed.forget = true;
+        }
         else if (token.startsWith("-")) {
+            throw new PlatformError("INVALID_REQUEST", `unknown option: ${token}`);
         }
         else {
             positional.push(token);
@@ -78,12 +84,29 @@ function parseArgs(argv) {
     }
     return parsed;
 }
+function requiredOptionValue(argv, index, option) {
+    const value = argv[index + 1];
+    if (value === undefined || value === "" || value.startsWith("-")) {
+        throw new PlatformError("INVALID_REQUEST", `${option} requires a value`);
+    }
+    return value;
+}
 function outcome(command, status, data) {
     const result = { command, status };
     if (data !== undefined)
         result.data = data;
     return result;
 }
+function workspaceSummary(binding) {
+    return {
+        boundWorkspace: binding.workspaceRealPath,
+        workspaceInstanceId: binding.workspaceInstanceId,
+        bindingState: binding.state,
+    };
+}
+function withWorkspace(result, binding) {
+    return { ...result, workspace: workspaceSummary(binding) };
+}
 function aggregateStatus(statuses) {
     if (statuses.includes("FAILED"))
         return "FAILED";
@@ -166,8 +189,7 @@ async function loadConfigFile(path) {
     }
     return result;
 }
-async function buildContext(workspace) {
-    const root = workspace ?? process.cwd();
+async function buildContext(root) {
     const paths = workspacePaths(root);
     const catalog = await buildCatalogWithProductionBindings(root, paths);
     return { catalog, paths };
@@ -196,7 +218,7 @@ async function buildCatalogWithProductionBindings(root, paths) {
         workspaceRoot: root,
         modules,
         configByModuleRef,
-        importAdapter: (packageName, source) => importRawAdapter(packageName, source),
+        importAdapter: (packageName, source) => importRawAdapter(packageName, source, root),
     });
     return new AutoModuleCatalog(root, bindings);
 }
@@ -287,14 +309,41 @@ async function handleInstallerPreflight(root) {
             : "BLOCKED";
     return outcome("preflight", status, result);
 }
+async function loadEffectiveConfig(ctx, modules, configFile) {
+    const effective = {};
+    for (const module of modules) {
+        const stored = await loadConfig(ctx.paths, module.moduleRef);
+        if (stored === undefined)
+            continue;
+        effective[module.moduleRef] = {
+            ...stored.publicValues,
+            ...stored.secretValues,
+        };
+    }
+    const provided = await loadConfigFile(configFile);
+    for (const [moduleRef, values] of Object.entries(provided)) {
+        effective[moduleRef] = {
+            ...(effective[moduleRef] ?? {}),
+            ...values,
+        };
+    }
+    return effective;
+}
 async function handlePreflight(ctx, args) {
     const modules = await discoverModules({ catalog: ctx.catalog });
     const selected = selectModules(modules, args.positional[0]);
-    const config = await loadConfigFile(args.configFile);
-    const result = await runPreflight(selected, { config, catalog: ctx.catalog });
-    return result.ok
-        ? outcome("preflight", "SUCCEEDED", result)
-        : outcome("preflight", "BLOCKED", result);
+    const config = await loadEffectiveConfig(ctx, selected, args.configFile);
+    const result = await runPreflight(selected, {
+        config,
+        catalog: ctx.catalog,
+        paths: ctx.paths,
+    });
+    const status = result.status === "READY"
+        ? "SUCCEEDED"
+        : result.status === "ACTION_REQUIRED"
+            ? "ACTION_REQUIRED"
+            : "BLOCKED";
+    return outcome("preflight", status, result);
 }
 async function handlePlan(ctx, args) {
     const intent = args.intent;
@@ -401,6 +450,7 @@ async function handlePlan(ctx, args) {
             currentDescriptors,
             targetDescriptors,
             targets,
+            config,
         });
         await savePlan(ctx.paths, plan);
         return outcome("plan", "SUCCEEDED", {
@@ -409,9 +459,15 @@ async function handlePlan(ctx, args) {
             plan,
         });
     }
+    if (intent === "configure") {
+        const plan = planDeployment({ intent, modules: selected, config });
+        await savePlan(ctx.paths, plan);
+        return outcome("plan", "SUCCEEDED", { planRef: plan.planRef, plan });
+    }
     const preflight = await runPreflight(selected, {
         config,
         catalog: ctx.catalog,
+        paths: ctx.paths,
     });
     if (preflight.status === "NOT_READY" ||
         preflight.status === "ACTION_REQUIRED") {
@@ -450,6 +506,11 @@ async function handleApply(ctx, args) {
         driver: createWorkspacePackageManagerDriver({
             workspaceRoot: ctx.paths.root,
         }),
+        ...(plan.intent === "upgrade"
+            ? {
+                refreshCatalog: async () => (await buildContext(ctx.paths.root)).catalog,
+            }
+            : {}),
     });
     const status = result.outcome === "COMPLETE"
         ? "SUCCEEDED"
@@ -477,6 +538,23 @@ async function handleManagedMutation(ctx, args, intent) {
     if (planned.status !== "SUCCEEDED") {
         return { ...planned, command: intent };
     }
+    if (intent === "upgrade") {
+        const data = planned.data;
+        if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+            const plan = Reflect.get(data, "plan");
+            if (typeof plan === "object" &&
+                plan !== null &&
+                !Array.isArray(plan) &&
+                Array.isArray(Reflect.get(plan, "steps")) &&
+                Reflect.get(plan, "steps").length === 0) {
+                return outcome("upgrade", "SUCCEEDED", {
+                    ...data,
+                    alreadyLatest: true,
+                    changed: false,
+                });
+            }
+        }
+    }
     const planRef = planRefFromOutcome(planned);
     const applied = await handleApply(ctx, {
         ...args,
@@ -493,7 +571,7 @@ async function handleManagedMutation(ctx, args, intent) {
     // Package mutations change Workspace package reality. Rebuild the catalog
     // before reporting the managed set so the result can never be sourced from
     // the pre-mutation catalog.
-    const refreshed = await buildContext(args.workspace);
+    const refreshed = await buildContext(ctx.paths.root);
     const managed = await handleModules(refreshed, {
         ...args,
         command: "modules",
@@ -506,6 +584,315 @@ async function handleManagedMutation(ctx, args, intent) {
         managedModules: managed.data,
     });
 }
+async function resolveRequestedInstallWorkspace(args, runtime) {
+    const requested = args.workspace ?? runtime.cwd ?? process.cwd();
+    return (await canonicalizeWorkspace(requested)).workspaceRealPath;
+}
+async function handleInstallPlanBeforeBinding(args, runtime) {
+    const requestedWorkspace = await resolveRequestedInstallWorkspace(args, runtime);
+    const current = await loadGlobalBinding(runtime.globalRoot);
+    if (current !== undefined &&
+        current.workspaceRealPath !== requestedWorkspace) {
+        throw new PlatformError("WORKSPACE_ALREADY_BOUND", `ProFlow is already bound to ${current.workspaceRealPath}; uninstall it before planning an install for ${requestedWorkspace}`);
+    }
+    const ctx = await buildContext(current?.workspaceRealPath ?? requestedWorkspace);
+    const result = await handlePlan(ctx, args);
+    return current === undefined ? result : withWorkspace(result, current);
+}
+async function handleApplyWithGlobalBinding(args, runtime) {
+    const planRef = args.positional[0];
+    if (planRef === undefined) {
+        throw new PlatformError("INVALID_REQUEST", "apply requires <planRef>");
+    }
+    const operationLock = await acquireGlobalOperationLock(runtime.globalRoot);
+    let binding = await loadGlobalBinding(runtime.globalRoot);
+    try {
+        let ctx;
+        if (binding === undefined) {
+            const requestedWorkspace = await resolveRequestedInstallWorkspace(args, runtime);
+            ctx = await buildContext(requestedWorkspace);
+            const plan = await loadPlan(ctx.paths, planRef);
+            if (plan === undefined) {
+                throw new PlatformError("PLAN_NOT_FOUND", `plan ${planRef} not found`);
+            }
+            if (plan.intent !== "install") {
+                throw new PlatformError("WORKSPACE_NOT_BOUND", "only an install plan may establish the first global Workspace binding");
+            }
+            binding = (await claimWorkspaceBinding({
+                workspace: requestedWorkspace,
+                globalRoot: runtime.globalRoot,
+            })).binding;
+        }
+        else {
+            if (args.workspace !== undefined) {
+                const requested = await canonicalizeWorkspace(args.workspace);
+                if (requested.workspaceRealPath !== binding.workspaceRealPath) {
+                    throw new PlatformError("WORKSPACE_ALREADY_BOUND", `command targets ${requested.workspaceRealPath}, but the global Platform Instance is bound to ${binding.workspaceRealPath}`);
+                }
+            }
+            ctx = await buildContext(binding.workspaceRealPath);
+        }
+        const plan = await loadPlan(ctx.paths, planRef);
+        if (plan === undefined) {
+            throw new PlatformError("PLAN_NOT_FOUND", `plan ${planRef} not found`);
+        }
+        const controlsPlatformState = plan.intent === "install" && binding.state !== "INSTALLED";
+        if (binding.state === "UNINSTALLING") {
+            throw new PlatformError("GLOBAL_OPERATION_LOCKED", "the bound Platform Instance is marked UNINSTALLING; finish recovery before apply");
+        }
+        if (controlsPlatformState && binding.state !== "INSTALLING") {
+            binding = await updateGlobalBindingState({
+                workspaceInstanceId: binding.workspaceInstanceId,
+                state: "INSTALLING",
+                globalRoot: runtime.globalRoot,
+            });
+        }
+        try {
+            const result = await handleApply(ctx, args);
+            if (controlsPlatformState) {
+                if (result.status === "SUCCEEDED") {
+                    binding = await updateGlobalBindingState({
+                        workspaceInstanceId: binding.workspaceInstanceId,
+                        state: "INSTALLED",
+                        globalRoot: runtime.globalRoot,
+                    });
+                }
+                else if (result.status === "FAILED" || result.status === "BLOCKED") {
+                    binding = await updateGlobalBindingState({
+                        workspaceInstanceId: binding.workspaceInstanceId,
+                        state: "BROKEN",
+                        globalRoot: runtime.globalRoot,
+                        failure: {
+                            code: result.error?.code ?? result.status,
+                            message: result.error?.message ??
+                                "install apply did not reach a successful postcondition",
+                        },
+                    });
+                }
+            }
+            return withWorkspace(result, binding);
+        }
+        catch (error) {
+            if (controlsPlatformState) {
+                binding = await updateGlobalBindingState({
+                    workspaceInstanceId: binding.workspaceInstanceId,
+                    state: "BROKEN",
+                    globalRoot: runtime.globalRoot,
+                    failure: {
+                        code: error instanceof PlatformError ? error.code : "COMMAND_FAILED",
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            throw error;
+        }
+    }
+    finally {
+        await operationLock.release();
+    }
+}
+async function handleInstallWithGlobalBinding(args, runtime) {
+    const operationLock = await acquireGlobalOperationLock(runtime.globalRoot);
+    try {
+        const requestedWorkspace = await resolveRequestedInstallWorkspace(args, runtime);
+        const existing = await loadGlobalBinding(runtime.globalRoot);
+        if (existing !== undefined &&
+            existing.workspaceRealPath !== requestedWorkspace) {
+            throw new PlatformError("WORKSPACE_ALREADY_BOUND", `ProFlow is already bound to ${existing.workspaceRealPath}; uninstall it before installing ${requestedWorkspace}`);
+        }
+        if (existing?.state === "INSTALLED" && args.positional[0] === undefined) {
+            return withWorkspace(outcome("install", "SUCCEEDED", {
+                alreadyInstalled: true,
+                changed: false,
+                boundWorkspace: existing.workspaceRealPath,
+            }), existing);
+        }
+        if (existing?.state === "UNINSTALLING") {
+            throw new PlatformError("GLOBAL_OPERATION_LOCKED", "the bound Platform Instance is marked UNINSTALLING; finish recovery before installing");
+        }
+        // Gate A runs before claiming a fresh global binding. Deterministic local
+        // failures (package-manager conflict, missing executable, registry down,
+        // unwritable Workspace) therefore do not leave a fake BROKEN installation.
+        // The global operation lock keeps this preflight + claim sequence atomic
+        // against other Platform mutations.
+        const installer = await preflightInstallerEnvironment({
+            workspaceRoot: requestedWorkspace,
+        });
+        if (installer.status !== "READY") {
+            return outcome("install", installer.status === "ACTION_REQUIRED" ? "ACTION_REQUIRED" : "BLOCKED", { requestedWorkspace, preflight: installer });
+        }
+        const claimed = await claimWorkspaceBinding({
+            workspace: requestedWorkspace,
+            globalRoot: runtime.globalRoot,
+        });
+        const initialBinding = claimed.binding;
+        let activeBinding = initialBinding;
+        const controlsPlatformState = !claimed.alreadyBound || initialBinding.state !== "INSTALLED";
+        if (controlsPlatformState && initialBinding.state !== "INSTALLING") {
+            activeBinding = await updateGlobalBindingState({
+                workspaceInstanceId: initialBinding.workspaceInstanceId,
+                state: "INSTALLING",
+                globalRoot: runtime.globalRoot,
+            });
+        }
+        try {
+            const ctx = await buildContext(activeBinding.workspaceRealPath);
+            const result = await handleManagedMutation(ctx, args, "install");
+            if (controlsPlatformState) {
+                if (result.status === "SUCCEEDED") {
+                    activeBinding = await updateGlobalBindingState({
+                        workspaceInstanceId: activeBinding.workspaceInstanceId,
+                        state: "INSTALLED",
+                        globalRoot: runtime.globalRoot,
+                    });
+                }
+                else if (result.status === "FAILED" || result.status === "BLOCKED") {
+                    activeBinding = await updateGlobalBindingState({
+                        workspaceInstanceId: activeBinding.workspaceInstanceId,
+                        state: "BROKEN",
+                        globalRoot: runtime.globalRoot,
+                        failure: {
+                            code: result.error?.code ?? result.status,
+                            message: result.error?.message ??
+                                "Platform install did not reach a successful postcondition",
+                        },
+                    });
+                }
+            }
+            return withWorkspace(result, activeBinding);
+        }
+        catch (error) {
+            if (controlsPlatformState) {
+                activeBinding = await updateGlobalBindingState({
+                    workspaceInstanceId: activeBinding.workspaceInstanceId,
+                    state: "BROKEN",
+                    globalRoot: runtime.globalRoot,
+                    failure: {
+                        code: error instanceof PlatformError ? error.code : "COMMAND_FAILED",
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            throw error;
+        }
+    }
+    finally {
+        await operationLock.release();
+    }
+}
+async function resolveBoundContext(runtime, requestedWorkspace) {
+    const binding = await requireBoundWorkspace(runtime.globalRoot);
+    if (requestedWorkspace !== undefined) {
+        const requested = await canonicalizeWorkspace(requestedWorkspace);
+        if (requested.workspaceRealPath !== binding.workspaceRealPath) {
+            throw new PlatformError("WORKSPACE_ALREADY_BOUND", `command targets ${requested.workspaceRealPath}, but the global Platform Instance is bound to ${binding.workspaceRealPath}`);
+        }
+    }
+    return {
+        ctx: await buildContext(binding.workspaceRealPath),
+        binding,
+    };
+}
+async function handleBoundMutatingCommand(args, runtime) {
+    const operationLock = await acquireGlobalOperationLock(runtime.globalRoot);
+    try {
+        const { ctx, binding } = await resolveBoundContext(runtime, args.workspace);
+        if (binding.state === "UNINSTALLING") {
+            throw new PlatformError("GLOBAL_OPERATION_LOCKED", "the bound Platform Instance is marked UNINSTALLING; finish uninstall recovery before another mutation");
+        }
+        let result;
+        if (args.command === "upgrade" || args.command === "uninstall") {
+            result = await handleManagedMutation(ctx, args, args.command);
+        }
+        else {
+            result = await handleLifecycle(ctx, args, args.command);
+        }
+        return withWorkspace(result, binding);
+    }
+    finally {
+        await operationLock.release();
+    }
+}
+async function handlePlatformInstanceUninstall(args, runtime) {
+    const operationLock = await acquireGlobalOperationLock(runtime.globalRoot);
+    let binding;
+    try {
+        binding = await requireBoundWorkspace(runtime.globalRoot);
+        if (args.workspace !== undefined) {
+            const requested = await canonicalizeWorkspace(args.workspace);
+            if (requested.workspaceRealPath !== binding.workspaceRealPath) {
+                throw new PlatformError("WORKSPACE_ALREADY_BOUND", `uninstall targets ${requested.workspaceRealPath}, but the global Platform Instance is bound to ${binding.workspaceRealPath}`);
+            }
+        }
+        binding = await updateGlobalBindingState({
+            workspaceInstanceId: binding.workspaceInstanceId,
+            state: "UNINSTALLING",
+            globalRoot: runtime.globalRoot,
+        });
+        const ctx = await buildContext(binding.workspaceRealPath);
+        const modules = await discoverModules({ catalog: ctx.catalog });
+        let removedModules = [];
+        if (modules.length > 0) {
+            const plan = planDeployment({
+                intent: "uninstall",
+                modules,
+                uninstallScope: "platform-instance",
+            });
+            await savePlan(ctx.paths, plan);
+            const current = await rebuildCurrentAssumptions(ctx.catalog, plan);
+            const applied = await applyPlan({
+                paths: ctx.paths,
+                planRef: plan.planRef,
+                catalog: ctx.catalog,
+                current,
+                driver: createWorkspacePackageManagerDriver({
+                    workspaceRoot: ctx.paths.root,
+                }),
+            });
+            if (applied.outcome !== "COMPLETE") {
+                throw new PlatformError("UNINSTALL_FAILED", `Platform Instance uninstall stopped with ${applied.outcome}`);
+            }
+            removedModules = modules.map((module) => module.moduleRef);
+        }
+        const refreshed = await buildContext(binding.workspaceRealPath);
+        const remaining = await discoverModules({ catalog: refreshed.catalog });
+        if (remaining.length > 0) {
+            throw new PlatformError("UNINSTALL_FAILED", `Platform Instance uninstall left managed modules: ${remaining.map((module) => module.moduleRef).join(", ")}`);
+        }
+        // Deployment-owned plans/state/verification/instance identity must not leak
+        // into a future install of the same directory. Business/domain data outside
+        // `.proflow/deployment` is intentionally preserved.
+        await rm(ctx.paths.deployment, { recursive: true, force: true });
+        const completed = binding;
+        await clearGlobalBinding({
+            workspaceInstanceId: binding.workspaceInstanceId,
+            globalRoot: runtime.globalRoot,
+        });
+        binding = undefined;
+        return outcome("uninstall", "SUCCEEDED", {
+            uninstalledWorkspace: completed.workspaceRealPath,
+            removedModules,
+            bindingCleared: true,
+        });
+    }
+    catch (error) {
+        if (binding !== undefined) {
+            await updateGlobalBindingState({
+                workspaceInstanceId: binding.workspaceInstanceId,
+                state: "BROKEN",
+                globalRoot: runtime.globalRoot,
+                failure: {
+                    code: error instanceof PlatformError ? error.code : "UNINSTALL_FAILED",
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+        throw error;
+    }
+    finally {
+        await operationLock.release();
+    }
+}
 async function handleLifecycle(ctx, args, primitive) {
     const modules = await discoverModules({ catalog: ctx.catalog });
     const selected = selectModules(modules, args.positional[0]);
@@ -572,7 +959,7 @@ async function handleDoctor(ctx, args) {
 async function handleManifest(ctx, args) {
     const modules = await discoverModules({ catalog: ctx.catalog });
     const selected = selectModules(modules, args.positional[0]);
-    const config = await loadConfigFile(args.configFile);
+    const config = await loadEffectiveConfig(ctx, selected, args.configFile);
     const manifest = await buildManifest({
         catalog: ctx.catalog,
         modules: selected,
@@ -591,8 +978,14 @@ async function handleManifest(ctx, args) {
             return outcome("manifest", "FAILED", manifest);
     }
 }
-async function dispatchCommand(argv) {
-    const args = parseArgs(argv);
+async function dispatchCommand(argv, runtime = {}) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        return failure(argv[0] ?? "", error);
+    }
     if (!COMMANDS.includes(args.command)) {
         return {
             command: args.command,
@@ -604,47 +997,143 @@ async function dispatchCommand(argv) {
         };
     }
     try {
-        const root = args.workspace ?? process.cwd();
-        if (args.command === "search")
+        const cwd = runtime.cwd ?? process.cwd();
+        if (args.command === "search") {
+            const current = await loadGlobalBinding(runtime.globalRoot);
+            const root = args.workspace ?? current?.workspaceRealPath ?? cwd;
             return await handleSearch(root, args);
+        }
         if (args.command === "preflight" && args.intent === "install") {
+            const root = await resolveRequestedInstallWorkspace(args, runtime);
+            const current = await loadGlobalBinding(runtime.globalRoot);
+            if (current !== undefined && current.workspaceRealPath !== root) {
+                throw new PlatformError("WORKSPACE_ALREADY_BOUND", `ProFlow is already bound to ${current.workspaceRealPath}; uninstall it before installing ${root}`);
+            }
             return await handleInstallerPreflight(root);
         }
-        const ctx = await buildContext(args.workspace);
+        if (args.command === "plan") {
+            if (args.intent === "install") {
+                return await handleInstallPlanBeforeBinding(args, runtime);
+            }
+            if (args.intent === undefined ||
+                !["configure", "upgrade", "uninstall", "repair"].includes(args.intent)) {
+                const current = await loadGlobalBinding(runtime.globalRoot);
+                const root = args.workspace ??
+                    current?.workspaceRealPath ??
+                    runtime.cwd ??
+                    process.cwd();
+                return await handlePlan(await buildContext(root), args);
+            }
+        }
+        if (args.command === "apply") {
+            return await handleApplyWithGlobalBinding(args, runtime);
+        }
+        if (args.command === "install") {
+            return await handleInstallWithGlobalBinding(args, runtime);
+        }
+        if (args.command === "status") {
+            const observation = await observeBoundWorkspace(runtime.globalRoot);
+            if (observation === undefined) {
+                return outcome("status", "SUCCEEDED", {
+                    installed: false,
+                    bindingState: "UNBOUND",
+                    boundWorkspace: null,
+                    nextAction: "Run platform install [--workspace <path>]",
+                });
+            }
+            if (!observation.workspaceExists) {
+                return withWorkspace(outcome("status", "BLOCKED", {
+                    installed: false,
+                    code: "BOUND_WORKSPACE_MISSING",
+                    boundWorkspace: observation.binding.workspaceRealPath,
+                    nextAction: "Restore the Workspace or run platform uninstall --forget to clear only the stale binding",
+                }), observation.binding);
+            }
+        }
+        if (args.command === "uninstall" && args.forget) {
+            if (args.positional.length > 0 || args.workspace !== undefined) {
+                throw new PlatformError("INVALID_REQUEST", "platform uninstall --forget only clears the current stale global binding; do not combine it with a module/package or --workspace");
+            }
+            const operationLock = await acquireGlobalOperationLock(runtime.globalRoot);
+            try {
+                const forgotten = await forgetMissingWorkspaceBinding({
+                    globalRoot: runtime.globalRoot,
+                });
+                return outcome("uninstall", "SUCCEEDED", {
+                    forgottenWorkspace: forgotten.workspaceRealPath,
+                    bindingCleared: true,
+                    resourcesCleaned: false,
+                });
+            }
+            finally {
+                await operationLock.release();
+            }
+        }
+        if (args.command === "uninstall" && args.positional.length === 0) {
+            const current = await loadGlobalBinding(runtime.globalRoot);
+            if (current === undefined) {
+                return outcome("uninstall", "SUCCEEDED", {
+                    alreadyUninstalled: true,
+                    bindingCleared: true,
+                });
+            }
+            return await handlePlatformInstanceUninstall(args, runtime);
+        }
+        if (args.command === "upgrade" ||
+            (args.command === "uninstall" && args.positional.length > 0) ||
+            args.command === "start" ||
+            args.command === "stop" ||
+            args.command === "restart") {
+            return await handleBoundMutatingCommand(args, runtime);
+        }
+        const { ctx, binding } = await resolveBoundContext(runtime, args.workspace);
+        let result;
         switch (args.command) {
             case "search":
-                return await handleSearch(root, args);
+            case "install":
+                throw new PlatformError("COMMAND_FAILED", "unreachable command routing");
             case "modules":
-                return await handleModules(ctx, args);
+                result = await handleModules(ctx, args);
+                break;
             case "docs":
-                return await handleDocs(ctx, args);
-            case "install":
+                result = await handleDocs(ctx, args);
+                break;
             case "uninstall":
             case "upgrade":
-                return await handleManagedMutation(ctx, args, args.command);
-            case "preflight":
-                return await handlePreflight(ctx, args);
-            case "plan":
-                return await handlePlan(ctx, args);
-            case "apply":
-                return await handleApply(ctx, args);
             case "start":
             case "stop":
             case "restart":
+                throw new PlatformError("COMMAND_FAILED", "unreachable mutating command routing");
+            case "preflight":
+                result = await handlePreflight(ctx, args);
+                break;
+            case "plan":
+                result = await handlePlan(ctx, args);
+                break;
+            case "apply":
+                result = await handleApply(ctx, args);
+                break;
             case "status":
-                return await handleLifecycle(ctx, args, args.command);
+                result = await handleLifecycle(ctx, args, "status");
+                break;
             case "verify":
-                return await handleVerify(ctx, args);
+                result = await handleVerify(ctx, args);
+                break;
             case "doctor":
-                return await handleDoctor(ctx, args);
+                result = await handleDoctor(ctx, args);
+                break;
             case "manifest":
-                return await handleManifest(ctx, args);
+                result = await handleManifest(ctx, args);
+                break;
+        }
+        if (result === undefined) {
+            throw new PlatformError("COMMAND_FAILED", "unreachable command routing");
         }
+        return withWorkspace(result, binding);
     }
     catch (error) {
         return failure(args.command, error);
     }
-    return failure(args.command, new PlatformError("COMMAND_FAILED", "unreachable"));
 }
 function toMachineResult(outcomeResult) {
     const ok = outcomeResult.status === "SUCCEEDED";
@@ -654,6 +1143,9 @@ function toMachineResult(outcomeResult) {
         status: outcomeResult.status,
         moduleRef: MODULE_REF,
         moduleVersion: MODULE_VERSION,
+        ...(outcomeResult.workspace !== undefined
+            ? { workspace: outcomeResult.workspace }
+            : {}),
         ...(outcomeResult.data !== undefined ? { data: outcomeResult.data } : {}),
         ...(outcomeResult.status === "ACTION_REQUIRED"
             ? {
@@ -674,7 +1166,125 @@ function toMachineResult(outcomeResult) {
             : {}),
     });
 }
-export async function runCli(argv) {
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function humanDetailLines(data) {
+    if (!isRecord(data)) {
+        return data === undefined ? [] : [String(data)];
+    }
+    const lines = [];
+    for (const key of [
+        "installed",
+        "bindingState",
+        "boundWorkspace",
+        "requestedWorkspace",
+        "alreadyInstalled",
+        "alreadyLatest",
+        "changed",
+        "bindingCleared",
+        "resourcesCleaned",
+        "planRef",
+        "outcome",
+    ]) {
+        const value = data[key];
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            lines.push(`${key}: ${String(value)}`);
+        }
+    }
+    if (typeof data.nextAction === "string" && data.nextAction !== "") {
+        lines.push(`Next: ${data.nextAction}`);
+    }
+    const findings = data.findings;
+    let hasMissingConfig = false;
+    if (Array.isArray(findings) && findings.length > 0) {
+        lines.push("Findings:");
+        for (const finding of findings) {
+            if (!isRecord(finding))
+                continue;
+            const severity = typeof finding.severity === "string"
+                ? finding.severity.toUpperCase()
+                : "INFO";
+            const code = typeof finding.code === "string" ? finding.code : "CHECK";
+            if (code === "CONFIG_MISSING")
+                hasMissingConfig = true;
+            const moduleRef = typeof finding.moduleRef === "string" ? ` ${finding.moduleRef}` : "";
+            const message = typeof finding.message === "string" ? finding.message : "";
+            lines.push(`- [${severity}] ${code}${moduleRef}${message === "" ? "" : `: ${message}`}`);
+        }
+    }
+    if (hasMissingConfig) {
+        lines.push("Next: review .proflow/deployment/generated/INSTALL.md, create the required config file, then run platform plan --intent configure --config <file> and platform apply <planRef>.");
+    }
+    const preflight = data.preflight;
+    if (isRecord(preflight)) {
+        const nested = humanDetailLines(preflight);
+        if (nested.length > 0) {
+            lines.push("Preflight:", ...nested.map((line) => `  ${line}`));
+        }
+    }
+    return lines;
+}
+export function renderHumanResult(machineOutput) {
+    const parsed = JSON.parse(machineOutput);
+    if (!isRecord(parsed))
+        return machineOutput;
+    const data = parsed.data;
+    if (isRecord(data) && typeof data.version === "string") {
+        return `ProFlow Platform CLI ${data.version}`;
+    }
+    if (isRecord(data) && typeof data.usage === "string") {
+        const commands = Array.isArray(data.commands)
+            ? data.commands.filter((item) => typeof item === "string")
+            : [];
+        const examples = Array.isArray(data.examples)
+            ? data.examples.filter((item) => typeof item === "string")
+            : [];
+        return [
+            "ProFlow Platform CLI",
+            "",
+            `Usage: ${data.usage}`,
+            ...(commands.length === 0
+                ? []
+                : ["", `Commands: ${commands.join(", ")}`]),
+            ...(examples.length === 0
+                ? []
+                : ["", "Common flows:", ...examples.map((item) => `  ${item}`)]),
+        ].join("\n");
+    }
+    const status = typeof parsed.status === "string" ? parsed.status : "UNKNOWN";
+    const lines = [`ProFlow: ${status}`];
+    const workspace = parsed.workspace;
+    if (isRecord(workspace) && typeof workspace.boundWorkspace === "string") {
+        lines.push(`Workspace: ${workspace.boundWorkspace}`);
+    }
+    const error = parsed.error;
+    if (isRecord(error)) {
+        const code = typeof error.code === "string" ? error.code : "COMMAND_FAILED";
+        const message = typeof error.message === "string" ? error.message : "Unknown error";
+        lines.push(`Error: ${code}: ${message}`);
+    }
+    lines.push(...humanDetailLines(data));
+    if (lines.length === 1 && status === "SUCCEEDED") {
+        lines.push(`Version: ${MODULE_VERSION}`, "Next: run platform --help");
+    }
+    return lines.join("\n");
+}
+export async function runCli(argv, runtime = {}) {
+    const filtered = argv.filter((argument) => argument !== "--json");
+    if (filtered.length === 1 &&
+        (filtered[0] === "--version" || filtered[0] === "-v")) {
+        return JSON.stringify({
+            contract: "deployment.result.v1",
+            ok: true,
+            status: "SUCCEEDED",
+            moduleRef: MODULE_REF,
+            moduleVersion: MODULE_VERSION,
+            data: { version: MODULE_VERSION },
+        });
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         return JSON.stringify({
             contract: "deployment.result.v1",
@@ -685,10 +1295,19 @@ export async function runCli(argv) {
             data: {
                 usage: "platform <command> [module|package] [--workspace <path>] [--json]",
                 commands: [...COMMANDS],
+                examples: [
+                    "platform preflight --intent install --workspace <path>",
+                    "platform install [module|package] [--workspace <path>]",
+                    "platform preflight  # startup/runtime readiness for the bound Workspace",
+                    "platform plan --intent configure --config <file>",
+                    "platform apply <planRef>",
+                    "platform start | status | verify | doctor | stop | restart",
+                    "platform uninstall  # uninstall the bound Platform Instance, not the global CLI",
+                    "append --json for the stable machine-readable contract",
+                ],
             },
         });
     }
-    const filtered = argv.filter((argument) => argument !== "--json");
     if (filtered.length === 0) {
         return JSON.stringify({
             contract: "deployment.result.v1",
@@ -698,11 +1317,13 @@ export async function runCli(argv) {
             moduleVersion: MODULE_VERSION,
         });
     }
-    return toMachineResult(await dispatchCommand(filtered));
+    return toMachineResult(await dispatchCommand(filtered, runtime));
 }
 if (import.meta.main) {
-    const output = await runCli(process.argv.slice(2));
-    process.stdout.write(`${output}\n`);
+    const argv = process.argv.slice(2);
+    const output = await runCli(argv);
+    const rendered = argv.includes("--json") ? output : renderHumanResult(output);
+    process.stdout.write(`${rendered}\n`);
     const parsed = JSON.parse(output);
     if (typeof parsed === "object" &&
         parsed !== null &&