@tomflow/proflow-platform-cli 0.1.1 → 0.1.3

package/dist/src/binding/global-binding.js

@@ -0,0 +1,349 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, mkdir, open, readFile, realpath, rm, stat, unlink, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { PlatformError } from "../errors.js";
+import { atomicWrite } from "../paths.js";
+export const GLOBAL_BINDING_CONTRACT = "deployment.global-binding.v1";
+export const WORKSPACE_INSTANCE_CONTRACT = "deployment.workspace-instance.v1";
+export function globalPlatformPaths(globalRoot) {
+    const root = globalRoot ??
+        process.env.PROFLOW_GLOBAL_HOME ??
+        join(homedir(), ".proflow", "platform");
+    return {
+        root,
+        bindingJson: join(root, "binding.json"),
+        bindingLock: join(root, "binding.lock"),
+        operationLock: join(root, "operation.lock"),
+    };
+}
+export async function canonicalizeWorkspace(workspace) {
+    const workspacePath = resolve(workspace);
+    let info;
+    try {
+        info = await stat(workspacePath);
+    }
+    catch {
+        throw new PlatformError("WORKSPACE_NOT_FOUND", `workspace does not exist: ${workspacePath}`);
+    }
+    if (!info.isDirectory()) {
+        throw new PlatformError("WORKSPACE_NOT_FOUND", `workspace is not a directory: ${workspacePath}`);
+    }
+    try {
+        await access(workspacePath, constants.R_OK | constants.W_OK);
+    }
+    catch {
+        throw new PlatformError("WORKSPACE_NOT_WRITABLE", `workspace is not readable and writable: ${workspacePath}`);
+    }
+    return { workspacePath, workspaceRealPath: await realpath(workspacePath) };
+}
+export async function loadGlobalBinding(globalRoot) {
+    const paths = globalPlatformPaths(globalRoot);
+    try {
+        const raw = await readFile(paths.bindingJson, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isGlobalWorkspaceBinding(parsed)) {
+            throw new PlatformError("GLOBAL_BINDING_INVALID", `global binding is invalid: ${paths.bindingJson}`);
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        if (error instanceof PlatformError)
+            throw error;
+        throw new PlatformError("GLOBAL_BINDING_INVALID", `cannot read global binding ${paths.bindingJson}: ${errorMessage(error)}`);
+    }
+}
+export async function observeBoundWorkspace(globalRoot) {
+    const binding = await loadGlobalBinding(globalRoot);
+    if (binding === undefined)
+        return undefined;
+    return {
+        binding,
+        workspaceExists: await directoryExists(binding.workspaceRealPath),
+    };
+}
+export async function requireBoundWorkspace(globalRoot) {
+    const observation = await observeBoundWorkspace(globalRoot);
+    if (observation === undefined) {
+        throw new PlatformError("WORKSPACE_NOT_BOUND", "no ProFlow Workspace is currently installed/bound");
+    }
+    if (!observation.workspaceExists) {
+        throw new PlatformError("BOUND_WORKSPACE_MISSING", `bound Workspace no longer exists: ${observation.binding.workspaceRealPath}`);
+    }
+    return observation.binding;
+}
+export async function claimWorkspaceBinding(options) {
+    const requested = await canonicalizeWorkspace(options.workspace);
+    const paths = globalPlatformPaths(options.globalRoot);
+    const lock = await acquireGlobalBindingLock(paths);
+    try {
+        const current = await loadGlobalBinding(options.globalRoot);
+        if (current !== undefined) {
+            if (current.workspaceRealPath !== requested.workspaceRealPath) {
+                throw new PlatformError("WORKSPACE_ALREADY_BOUND", `ProFlow is already bound to ${current.workspaceRealPath}; uninstall it before installing ${requested.workspaceRealPath}`);
+            }
+            return { binding: current, alreadyBound: true };
+        }
+        const existingMarker = await loadWorkspaceInstanceMarker(requested.workspaceRealPath);
+        const now = new Date().toISOString();
+        const binding = {
+            contract: GLOBAL_BINDING_CONTRACT,
+            state: "INSTALLING",
+            workspacePath: requested.workspacePath,
+            workspaceRealPath: requested.workspaceRealPath,
+            workspaceInstanceId: existingMarker?.workspaceInstanceId ?? randomUUID(),
+            createdAt: existingMarker?.createdAt ?? now,
+            updatedAt: now,
+        };
+        await saveGlobalBinding(paths, binding);
+        if (existingMarker === undefined) {
+            try {
+                await writeWorkspaceInstanceMarker(binding);
+            }
+            catch (error) {
+                const broken = withBindingState(binding, "BROKEN", {
+                    code: "WORKSPACE_INSTANCE_WRITE_FAILED",
+                    message: errorMessage(error),
+                });
+                await saveGlobalBinding(paths, broken);
+                throw new PlatformError("GLOBAL_BINDING_INVALID", `failed to materialize Workspace instance identity: ${errorMessage(error)}`);
+            }
+        }
+        return { binding, alreadyBound: false };
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function updateGlobalBindingState(options) {
+    const paths = globalPlatformPaths(options.globalRoot);
+    const lock = await acquireGlobalBindingLock(paths);
+    try {
+        const current = await loadGlobalBinding(options.globalRoot);
+        if (current === undefined) {
+            throw new PlatformError("WORKSPACE_NOT_BOUND", "cannot update global binding because no Workspace is bound");
+        }
+        if (current.workspaceInstanceId !== options.workspaceInstanceId) {
+            throw new PlatformError("GLOBAL_BINDING_INVALID", "global binding instance identity changed during the operation");
+        }
+        const next = withBindingState(current, options.state, options.failure);
+        await saveGlobalBinding(paths, next);
+        return next;
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function clearGlobalBinding(options) {
+    const paths = globalPlatformPaths(options.globalRoot);
+    const lock = await acquireGlobalBindingLock(paths);
+    try {
+        const current = await loadGlobalBinding(options.globalRoot);
+        if (current === undefined)
+            return;
+        if (current.workspaceInstanceId !== options.workspaceInstanceId) {
+            throw new PlatformError("GLOBAL_BINDING_INVALID", "refusing to clear a different Workspace binding");
+        }
+        await rm(paths.bindingJson, { force: true });
+        if (options.removeWorkspaceMarker === true) {
+            await rm(workspaceInstanceMarkerPath(current.workspaceRealPath), {
+                force: true,
+            });
+        }
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function forgetMissingWorkspaceBinding(options) {
+    const paths = globalPlatformPaths(options.globalRoot);
+    const lock = await acquireGlobalBindingLock(paths);
+    try {
+        const current = await loadGlobalBinding(options.globalRoot);
+        if (current === undefined) {
+            throw new PlatformError("WORKSPACE_NOT_BOUND", "no ProFlow Workspace binding exists to forget");
+        }
+        if (await directoryExists(current.workspaceRealPath)) {
+            throw new PlatformError("INVALID_REQUEST", "bound Workspace still exists; use normal platform uninstall instead of forget");
+        }
+        await rm(paths.bindingJson, { force: true });
+        return current;
+    }
+    finally {
+        await lock.release();
+    }
+}
+export async function acquireGlobalBindingLock(paths) {
+    return acquireExclusiveGlobalLock(paths.root, paths.bindingLock, "GLOBAL_BINDING_LOCKED", "another process is mutating the global Workspace binding");
+}
+export async function acquireGlobalOperationLock(globalRoot) {
+    const paths = globalPlatformPaths(globalRoot);
+    return acquireExclusiveGlobalLock(paths.root, paths.operationLock, "GLOBAL_OPERATION_LOCKED", "another Platform install/uninstall operation is already running");
+}
+async function acquireExclusiveGlobalLock(root, file, code, message) {
+    await mkdir(root, { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = await open(file, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            return {
+                async release() {
+                    try {
+                        await unlink(file);
+                    }
+                    catch (error) {
+                        if (!isMissingFile(error))
+                            throw error;
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+            const record = await readLockRecord(file);
+            if (record !== undefined && !pidIsAlive(record.pid)) {
+                await rm(file, { force: true });
+                continue;
+            }
+            throw new PlatformError(code, `${message}: ${file}`);
+        }
+    }
+    throw new PlatformError(code, `${message}: ${file}`);
+}
+function workspaceInstanceMarkerPath(workspaceRoot) {
+    return join(workspaceRoot, ".proflow", "deployment", "instance.json");
+}
+async function loadWorkspaceInstanceMarker(workspaceRoot) {
+    const path = workspaceInstanceMarkerPath(workspaceRoot);
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isWorkspaceInstanceMarker(parsed)) {
+            throw new PlatformError("WORKSPACE_INSTANCE_INVALID", `Workspace instance marker is invalid: ${path}`);
+        }
+        if (parsed.workspaceRealPath !== workspaceRoot) {
+            throw new PlatformError("WORKSPACE_INSTANCE_INVALID", `Workspace instance marker belongs to ${parsed.workspaceRealPath}, not ${workspaceRoot}`);
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        if (error instanceof PlatformError)
+            throw error;
+        throw new PlatformError("WORKSPACE_INSTANCE_INVALID", `cannot read Workspace instance marker ${path}: ${errorMessage(error)}`);
+    }
+}
+function isWorkspaceInstanceMarker(value) {
+    if (!isRecord(value))
+        return false;
+    return (value.contract === WORKSPACE_INSTANCE_CONTRACT &&
+        typeof value.workspaceInstanceId === "string" &&
+        value.workspaceInstanceId.length > 0 &&
+        typeof value.workspaceRealPath === "string" &&
+        typeof value.createdAt === "string");
+}
+async function writeWorkspaceInstanceMarker(binding) {
+    const path = workspaceInstanceMarkerPath(binding.workspaceRealPath);
+    const marker = {
+        contract: WORKSPACE_INSTANCE_CONTRACT,
+        workspaceInstanceId: binding.workspaceInstanceId,
+        workspaceRealPath: binding.workspaceRealPath,
+        createdAt: binding.createdAt,
+    };
+    await mkdir(dirname(path), { recursive: true });
+    await atomicWrite(path, `${JSON.stringify(marker, null, 2)}\n`);
+    await chmod(path, 0o600);
+}
+async function saveGlobalBinding(paths, binding) {
+    await mkdir(paths.root, { recursive: true });
+    await atomicWrite(paths.bindingJson, `${JSON.stringify(binding, null, 2)}\n`);
+    await chmod(paths.bindingJson, 0o600);
+}
+function withBindingState(binding, state, failure) {
+    const { failure: _previousFailure, ...base } = binding;
+    return {
+        ...base,
+        state,
+        updatedAt: new Date().toISOString(),
+        ...(failure === undefined ? {} : { failure }),
+    };
+}
+function isGlobalWorkspaceBinding(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.contract !== GLOBAL_BINDING_CONTRACT)
+        return false;
+    if (!isBindingState(value.state))
+        return false;
+    return (typeof value.workspacePath === "string" &&
+        typeof value.workspaceRealPath === "string" &&
+        typeof value.workspaceInstanceId === "string" &&
+        typeof value.createdAt === "string" &&
+        typeof value.updatedAt === "string" &&
+        (value.failure === undefined ||
+            (isRecord(value.failure) &&
+                typeof value.failure.code === "string" &&
+                typeof value.failure.message === "string")));
+}
+function isBindingState(value) {
+    return (value === "INSTALLING" ||
+        value === "INSTALLED" ||
+        value === "UNINSTALLING" ||
+        value === "BROKEN");
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readLockRecord(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (isRecord(parsed) &&
+            typeof parsed.pid === "number" &&
+            Number.isInteger(parsed.pid) &&
+            parsed.pid > 0) {
+            return { pid: parsed.pid };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isPermissionError(error);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMissingFile(error) {
+    return isRecord(error) && error.code === "ENOENT";
+}
+function isAlreadyExists(error) {
+    return isRecord(error) && error.code === "EEXIST";
+}
+function isPermissionError(error) {
+    return isRecord(error) && error.code === "EPERM";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -2,6 +2,7 @@ import type { ResolvedModule } from "../contracts.ts";
 type ResolvedSource = ResolvedModule["source"];
 export interface DeploymentAdapterBinding {
     behaviorAdapter: Record<string, unknown>;
+    materializeProductionConfig?: (...args: unknown[]) => unknown;
 }
 export type ProductionBindingFactory = (input: {
     moduleRef: string;
@@ -29,17 +30,6 @@ export interface ProductionBindingOptions {
     configByModuleRef: ReadonlyMap<string, Record<string, string>>;
     importAdapter: (packageName: string, source: ResolvedSource) => Promise<Record<string, unknown>>;
 }
-export declare function importRawAdapter(packageName: string, source: ResolvedSource): Promise<Record<string, unknown>>;
-/**
- * The shipped Platform CLI production binding factory. For every discovered
- * module it imports the module's own `deployment/adapter.ts` and, when that
- * adapter exposes a `createProductionBinding` factory, invokes it with the
- * module's materialized config to obtain a real bound adapter. A module without
- * a production factory — or whose import/factory fails, or which has no
- * materialized config the adapter accepts — is left out of the map, so the
- * catalog falls back to the module's unbound default, which must fail-closed
- * (ACTION_REQUIRED / NOT_READY). Platform CLI never invents a service or
- * resource reality: it only relays the adapter's own current reality.
- */
+export declare function importRawAdapter(packageName: string, source: ResolvedSource, workspaceRoot: string): Promise<Record<string, unknown>>;
 export declare function buildProductionBindings(options: ProductionBindingOptions): Promise<ReadonlyMap<string, DeploymentAdapterBinding>>;
 export {};

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)));
 }
 /**
@@ -43,6 +45,14 @@ export async function importRawAdapter(packageName, source) {
  * (ACTION_REQUIRED / NOT_READY). Platform CLI never invents a service or
  * resource reality: it only relays the adapter's own current reality.
  */
+function materializerBinding(namespace) {
+    const materializer = namespace.materializeProductionConfig;
+    return typeof materializer === "function"
+        ? {
+            materializeProductionConfig: materializer,
+        }
+        : {};
+}
 export async function buildProductionBindings(options) {
     const bindings = new Map();
     for (const module of options.modules) {
@@ -67,6 +77,7 @@ export async function buildProductionBindings(options) {
                             : {});
                     bindings.set(module.packageName, {
                         behaviorAdapter: managedServiceAdapter(options.workspaceRoot, module, processBinding.serviceProcess, probeAdapter),
+                        ...materializerBinding(namespace),
                     });
                 }
                 // A formal service package that exposes the process seam must never fall
@@ -90,7 +101,10 @@ export async function buildProductionBindings(options) {
                 binding !== null &&
                 typeof binding.behaviorAdapter === "object" &&
                 binding.behaviorAdapter !== null) {
-                bindings.set(module.packageName, binding);
+                bindings.set(module.packageName, {
+                    ...binding,
+                    ...materializerBinding(namespace),
+                });
             }
         }
         catch {

package/dist/src/cli.d.ts

@@ -1,12 +1,24 @@
 #!/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 renderHumanResult(machineOutput: string): string;
+export declare function runCli(argv: readonly string[], runtime?: CliRuntimeOptions): Promise<string>;