@tomflow/proflow-platform-cli 0.1.1 → 0.1.2

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

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+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";
@@ -21,15 +22,16 @@ function managedServiceAdapter(workspaceRoot, module, serviceProcess, probeAdapt
         uninstall: () => stopManagedService(paths, module),
     };
 }
-export async function importRawAdapter(packageName, source) {
+export async function importRawAdapter(packageName, source, workspaceRoot) {
     if (source.type === "workspace") {
         if (source.path === undefined)
             return {};
         const url = pathToFileURL(join(source.path, "deployment", "adapter.ts"));
         return (await /* architecture-allow-local-file-url-import */ import(__rewriteRelativeImportExtension(url.href)));
     }
-    const resolved = import.meta.resolve(`${packageName}/deployment/adapter`);
-    const url = new URL(resolved);
+    const workspaceRequire = createRequire(pathToFileURL(join(workspaceRoot, "package.json")));
+    const resolved = workspaceRequire.resolve(`${packageName}/deployment/adapter`);
+    const url = pathToFileURL(resolved);
     return (await /* architecture-allow-local-file-url-import */ import(__rewriteRelativeImportExtension(url.href)));
 }
 /**

package/dist/src/cli.d.ts

@@ -1,12 +1,23 @@
 #!/usr/bin/env node
+import { type GlobalWorkspaceBinding } from "./binding/global-binding.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;
     data?: unknown;
+    workspace?: CliWorkspaceSummary;
     error?: {
         code: string;
         message: string;
     };
 }
-export declare function runCli(argv: readonly string[]): Promise<string>;
+export interface CliRuntimeOptions {
+    cwd?: string;
+    globalRoot?: string;
+}
+export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<string>;

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.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);
 }
@@ -493,7 +515,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 +528,301 @@ 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 claimed = await claimWorkspaceBinding({
+            workspace: requestedWorkspace,
+            globalRoot: runtime.globalRoot,
+        });
+        const initialBinding = claimed.binding;
+        if (claimed.alreadyBound &&
+            initialBinding.state === "INSTALLED" &&
+            args.positional[0] === undefined) {
+            return withWorkspace(outcome("install", "SUCCEEDED", {
+                alreadyInstalled: true,
+                changed: false,
+                boundWorkspace: initialBinding.workspaceRealPath,
+            }), initialBinding);
+        }
+        if (initialBinding.state === "UNINSTALLING") {
+            throw new PlatformError("GLOBAL_OPERATION_LOCKED", "the bound Platform Instance is marked UNINSTALLING; finish recovery before installing");
+        }
+        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]);
@@ -591,8 +908,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 +927,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 +1073,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 +1096,7 @@ function toMachineResult(outcomeResult) {
             : {}),
     });
 }
-export async function runCli(argv) {
+export async function runCli(argv, runtime = {}) {
     if (argv.includes("--help") || argv.includes("-h")) {
         return JSON.stringify({
             contract: "deployment.result.v1",
@@ -698,7 +1120,7 @@ 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));

package/dist/src/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const platformErrorCodes: readonly ["INVALID_REQUEST", "DESCRIPTOR_INVALID", "DUPLICATE_IDENTITY", "DEPENDENCY_UNRESOLVED", "DEPENDENCY_INCOMPATIBLE", "DEPENDENCY_CYCLE", "CONFIG_MISSING", "SECRET_REF_INVALID", "PLAN_STALE", "PLAN_NOT_FOUND", "PLAN_INVALID", "WORKSPACE_LOCKED", "LIFECYCLE_UNSUPPORTED", "SECRET_LEAK", "APPLY_FAILED", "UPGRADE_FAILED", "CORE_PACKAGE_REQUIRED", "UNINSTALL_FAILED", "VERIFY_FAILED", "REGISTRY_UNAVAILABLE", "REGISTRY_AUTH_REQUIRED", "REGISTRY_RESPONSE_INVALID", "PACKAGE_NOT_FOUND", "PACKAGE_NOT_PROFLOW", "COMMAND_FAILED"];
+export declare const platformErrorCodes: readonly ["INVALID_REQUEST", "DESCRIPTOR_INVALID", "DUPLICATE_IDENTITY", "DEPENDENCY_UNRESOLVED", "DEPENDENCY_INCOMPATIBLE", "DEPENDENCY_CYCLE", "CONFIG_MISSING", "SECRET_REF_INVALID", "PLAN_STALE", "PLAN_NOT_FOUND", "PLAN_INVALID", "WORKSPACE_LOCKED", "WORKSPACE_NOT_FOUND", "WORKSPACE_NOT_WRITABLE", "WORKSPACE_NOT_BOUND", "WORKSPACE_ALREADY_BOUND", "BOUND_WORKSPACE_MISSING", "WORKSPACE_INSTANCE_INVALID", "GLOBAL_BINDING_INVALID", "GLOBAL_BINDING_LOCKED", "GLOBAL_OPERATION_LOCKED", "PACKAGE_MANAGER_UNSUPPORTED", "PACKAGE_MANAGER_CONFLICT", "PACKAGE_MANAGER_UNAVAILABLE", "LIFECYCLE_UNSUPPORTED", "SECRET_LEAK", "APPLY_FAILED", "UPGRADE_FAILED", "CORE_PACKAGE_REQUIRED", "UNINSTALL_FAILED", "VERIFY_FAILED", "REGISTRY_UNAVAILABLE", "REGISTRY_AUTH_REQUIRED", "REGISTRY_RESPONSE_INVALID", "PACKAGE_NOT_FOUND", "PACKAGE_NOT_PROFLOW", "COMMAND_FAILED"];
 export type PlatformErrorCode = (typeof platformErrorCodes)[number];
 export declare class PlatformError extends Error {
     readonly code: PlatformErrorCode;