@tomflow/proflow-platform-cli 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tomflow/proflow-platform-cli
 
+## 0.1.2
+
+### Patch Changes
+
+- Close the Real-1 global Platform control-plane contract across every published ProFlow package. Platform CLI now owns one durable global Workspace binding with canonical identity, cross-process operation locking, cwd/`--workspace` install targeting, cross-directory instance commands, whole-instance uninstall/rebind, and deterministic npm/yarn/pnpm Workspace package-manager selection. Every package-owned install entry, including newly generated Module Template packages, delegates to the Shell-global `platform` command and fails closed when that global CLI is unavailable; Deployment Conformance and the formal test plans mechanically enforce the same rule across all 24 packages.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -8,10 +8,20 @@ Business Fact Owner: none
 
 ## Purpose
 
-The single platform-level deterministic Deployment planner/executor. It understands only the Module Contract and public lifecycle/verification contracts; it does not import other domains' business internals.
+The single platform-level deterministic Deployment planner/executor and v1 global `platform` control plane. It understands only the Module Contract and public lifecycle/verification contracts; it does not import other domains' business internals. The global CLI binary is distinct from the single bound Platform Instance.
 
 For the v1 Custom GPT carrier it may plan/verify Web-only setup, role-scoped Action auth/schema, File Bridge/Code Interpreter/Web Search requirements, `x-openai-isConsequential:false` + Always Allow target configuration, Chrome/runtime prerequisites and current verification freshness. It never creates/guesses Task `workerRef/c-id`, never uses exact ChatGPT model id as READY truth, and never accepts System Observer assessment as Deployment READY truth.
 
+## Global CLI bootstrap
+
+The v1 `platform` command is a Shell-global control plane. A straightforward bootstrap is:
+
+```text
+npm install --global @tomflow/proflow-platform-cli
+```
+
+This choice installs the global CLI only. It does **not** force the managed Workspace to use npm: a bound Workspace may independently use `npm`, `yarn`, or `pnpm`, selected from its own package-manager facts.
+
 ## Commands
 
 ```
@@ -20,8 +30,8 @@ platform modules [module|package]
 platform docs [module|package] [documentId]
 platform preflight [module]
 platform preflight --intent install
-platform install [package]
-platform uninstall <module|package>
+platform install [package] [--workspace <path>]
+platform uninstall [module|package]
 platform upgrade [module|package]
 platform plan --intent install|configure|upgrade|uninstall|repair [options]
 platform apply <planRef>
@@ -35,3 +45,14 @@ platform manifest [module]
 ```
 
 `install` / `upgrade` / `uninstall` are AI-friendly high-level commands that reuse the same frozen Plan -> Apply engine. `search` reads the npm Registry installable world; `modules` reads the current Workspace managed world; `docs` mechanically aggregates package-owned Descriptor, npm `bin/exports`, and declared documentation without maintaining a second package-knowledge catalog. Package mutation is real Workspace package-manager mutation and is never satisfied by the historical no-op driver seam.
+
+
+## v1 global workspace semantics
+
+- The `platform` binary is installed globally and can be invoked from any shell directory.
+- At most one ProFlow Workspace may be bound globally at a time.
+- `platform install` targets the current working directory by default; `platform install --workspace <path>` explicitly selects the requested Workspace for Agent/automation use.
+- Requested Workspace paths are canonicalized before binding comparison. A second distinct Workspace is rejected with `WORKSPACE_ALREADY_BOUND` until the current Platform Instance is uninstalled.
+- `status/start/stop/restart/modules/docs/verify/doctor/upgrade/uninstall` resolve the durable global binding rather than the caller's cwd. `platform status` exposes the bound Workspace path.
+- `platform uninstall` without a module/package removes the current Platform Instance and clears its binding; it does not uninstall the global CLI package.
+- Workspace package mutation is package-manager agnostic for v1: `npm`, `yarn`, and `pnpm` are supported. The CLI installation manager and the bound Workspace manager are independent facts.

package/dist/deployment/adapter.d.ts

@@ -5,7 +5,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -27,7 +27,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -38,7 +38,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         observedEffects: never[];
@@ -49,7 +49,7 @@ export declare const behaviorAdapter: {
             ok: boolean;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.1";
+            moduleVersion: "0.1.2";
             data?: {} | null;
         };
         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.1";
+    readonly moduleVersion: "0.1.2";
     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.1",
+    moduleVersion: "0.1.2",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/apply/driver.d.ts

@@ -20,4 +20,5 @@ export declare function workspaceResidentDriver(): PackageManagerDriver;
 export declare function createWorkspacePackageManagerDriver(options: {
     workspaceRoot: string;
     runner?: PackageCommandRunner;
+    executableAvailable?: (command: string) => boolean;
 }): PackageManagerDriver;

package/dist/src/apply/driver.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { PlatformError } from "../errors.js";
-import { readWorkspacePackageManagerSelection, systemPackageCommandRunner, } from "../install/package-manager.js";
+import { findExecutable, readWorkspacePackageManagerSelection, systemPackageCommandRunner, } from "../install/package-manager.js";
 import { atomicWrite } from "../paths.js";
 /**
  * Monorepo/test seam retained for source-resident planning. Production CLI must
@@ -20,26 +20,27 @@ export function workspaceResidentDriver() {
 }
 export function createWorkspacePackageManagerDriver(options) {
     const runner = options.runner ?? systemPackageCommandRunner();
+    const executableAvailable = options.executableAvailable ?? findExecutable;
     return {
         observeInstalledVersion: (module) => observeInstalledVersion(options.workspaceRoot, module.packageName),
         install: async (module) => {
             await ensureWorkspacePackageJson(options.workspaceRoot);
-            const manager = await requirePackageManager(options.workspaceRoot);
+            const manager = await requirePackageManager(options.workspaceRoot, executableAvailable);
             await mutatePackage(runner, manager, options.workspaceRoot, "install", `${module.packageName}@${module.moduleVersion}`);
         },
         upgrade: async (module) => {
             await ensureWorkspacePackageJson(options.workspaceRoot);
-            const manager = await requirePackageManager(options.workspaceRoot);
+            const manager = await requirePackageManager(options.workspaceRoot, executableAvailable);
             await mutatePackage(runner, manager, options.workspaceRoot, "upgrade", `${module.packageName}@${module.moduleVersion}`);
         },
         remove: async (module) => {
-            const manager = await requirePackageManager(options.workspaceRoot);
+            const manager = await requirePackageManager(options.workspaceRoot, executableAvailable);
             await mutatePackage(runner, manager, options.workspaceRoot, "remove", module.packageName);
         },
     };
 }
 async function mutatePackage(runner, manager, workspaceRoot, operation, packageSpec) {
-    const args = packageManagerArgs(manager.name, operation, packageSpec);
+    const args = await packageManagerArgs(runner, manager, workspaceRoot, operation, packageSpec);
     try {
         await runner.run(manager.name, args, workspaceRoot);
     }
@@ -47,20 +48,47 @@ async function mutatePackage(runner, manager, workspaceRoot, operation, packageS
         throw new PlatformError(operation === "upgrade" ? "UPGRADE_FAILED" : "APPLY_FAILED", `${manager.name} ${operation} failed for ${packageSpec}: ${errorMessage(error)}`);
     }
 }
-function packageManagerArgs(manager, operation, packageSpec) {
-    if (manager === "pnpm") {
+async function packageManagerArgs(runner, manager, workspaceRoot, operation, packageSpec) {
+    if (manager.name === "pnpm") {
         return operation === "remove"
             ? ["remove", "--ignore-scripts", packageSpec]
             : ["add", "--save-exact", "--ignore-scripts", packageSpec];
     }
+    if (manager.name === "npm") {
+        return operation === "remove"
+            ? ["uninstall", "--ignore-scripts", packageSpec]
+            : ["install", "--save-exact", "--ignore-scripts", packageSpec];
+    }
+    const major = await yarnMajorVersion(runner, manager, workspaceRoot);
+    if (major <= 1) {
+        return operation === "remove"
+            ? ["remove", "--ignore-scripts", packageSpec]
+            : ["add", "--exact", "--ignore-scripts", packageSpec];
+    }
     return operation === "remove"
-        ? ["uninstall", "--ignore-scripts", packageSpec]
-        : ["install", "--save-exact", "--ignore-scripts", packageSpec];
+        ? ["remove", "--mode=skip-build", packageSpec]
+        : ["add", "--exact", "--mode=skip-build", packageSpec];
+}
+async function yarnMajorVersion(runner, manager, workspaceRoot) {
+    const declaredVersion = declaredPackageManagerVersion(manager.declared);
+    const value = declaredVersion ??
+        (await runner.run("yarn", ["--version"], workspaceRoot)).trim();
+    const major = Number.parseInt(value.split(".")[0] ?? "", 10);
+    if (!Number.isInteger(major) || major < 1) {
+        throw new PlatformError("PACKAGE_MANAGER_UNAVAILABLE", `cannot determine a supported Yarn major version from ${value || "<empty>"}`);
+    }
+    return major;
+}
+function declaredPackageManagerVersion(declared) {
+    if (declared === undefined)
+        return undefined;
+    const separator = declared.lastIndexOf("@");
+    return separator > 0 ? declared.slice(separator + 1) : undefined;
 }
-async function requirePackageManager(workspaceRoot) {
+async function requirePackageManager(workspaceRoot, executableAvailable) {
     const manager = await readWorkspacePackageManagerSelection(workspaceRoot);
-    if (manager === undefined) {
-        throw new PlatformError("APPLY_FAILED", "workspace packageManager is not supported; expected npm or pnpm");
+    if (!executableAvailable(manager.name)) {
+        throw new PlatformError("PACKAGE_MANAGER_UNAVAILABLE", `workspace package manager ${manager.name} is not available on PATH`);
     }
     return manager;
 }

package/dist/src/binding/global-binding.d.ts

@@ -0,0 +1,69 @@
+export declare const GLOBAL_BINDING_CONTRACT: "deployment.global-binding.v1";
+export declare const WORKSPACE_INSTANCE_CONTRACT: "deployment.workspace-instance.v1";
+export type GlobalBindingState = "INSTALLING" | "INSTALLED" | "UNINSTALLING" | "BROKEN";
+export interface GlobalWorkspaceBinding {
+    contract: typeof GLOBAL_BINDING_CONTRACT;
+    state: GlobalBindingState;
+    workspacePath: string;
+    workspaceRealPath: string;
+    workspaceInstanceId: string;
+    createdAt: string;
+    updatedAt: string;
+    failure?: {
+        code: string;
+        message: string;
+    };
+}
+export interface WorkspaceInstanceMarker {
+    contract: typeof WORKSPACE_INSTANCE_CONTRACT;
+    workspaceInstanceId: string;
+    workspaceRealPath: string;
+    createdAt: string;
+}
+export interface GlobalPlatformPaths {
+    root: string;
+    bindingJson: string;
+    bindingLock: string;
+    operationLock: string;
+}
+export interface BoundWorkspaceObservation {
+    binding: GlobalWorkspaceBinding;
+    workspaceExists: boolean;
+}
+export interface GlobalBindingLockHandle {
+    release(): Promise<void>;
+}
+export declare function globalPlatformPaths(globalRoot?: string): GlobalPlatformPaths;
+export declare function canonicalizeWorkspace(workspace: string): Promise<{
+    workspacePath: string;
+    workspaceRealPath: string;
+}>;
+export declare function loadGlobalBinding(globalRoot?: string): Promise<GlobalWorkspaceBinding | undefined>;
+export declare function observeBoundWorkspace(globalRoot?: string): Promise<BoundWorkspaceObservation | undefined>;
+export declare function requireBoundWorkspace(globalRoot?: string): Promise<GlobalWorkspaceBinding>;
+export declare function claimWorkspaceBinding(options: {
+    workspace: string;
+    globalRoot?: string | undefined;
+}): Promise<{
+    binding: GlobalWorkspaceBinding;
+    alreadyBound: boolean;
+}>;
+export declare function updateGlobalBindingState(options: {
+    workspaceInstanceId: string;
+    state: GlobalBindingState;
+    globalRoot?: string | undefined;
+    failure?: {
+        code: string;
+        message: string;
+    };
+}): Promise<GlobalWorkspaceBinding>;
+export declare function clearGlobalBinding(options: {
+    workspaceInstanceId: string;
+    globalRoot?: string | undefined;
+    removeWorkspaceMarker?: boolean;
+}): Promise<void>;
+export declare function forgetMissingWorkspaceBinding(options: {
+    globalRoot?: string | undefined;
+}): Promise<GlobalWorkspaceBinding>;
+export declare function acquireGlobalBindingLock(paths: GlobalPlatformPaths): Promise<GlobalBindingLockHandle>;
+export declare function acquireGlobalOperationLock(globalRoot?: string): Promise<GlobalBindingLockHandle>;

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

@@ -29,7 +29,7 @@ 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>>;
+export declare function importRawAdapter(packageName: string, source: ResolvedSource, workspaceRoot: string): 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