@tomflow/proflow-platform-cli 0.1.14 → 0.1.15

package/dist/src/contracts.d.ts

@@ -1,17 +1,10 @@
-import type { ConfigSlot, DeploymentEffect, HumanAction, ModuleDescriptor, ModuleRequirement } from "@tomflow/proflow-module-contract";
-export type DeploymentIntent = "install" | "configure" | "upgrade" | "uninstall" | "repair";
-export interface ModuleTarget {
-    moduleRef: string;
-    targetVersion?: string;
-    config?: Record<string, string>;
-}
+import type { ConfigSlot, DeploymentEffect, ModuleDescriptor, ModuleRequirement } from "@tomflow/proflow-module-contract";
 export interface ResolvedModule {
     moduleRef: string;
     packageName: string;
     moduleVersion: string;
-    kind: ModuleDescriptor["kind"] | "registry-package";
-    installClass: ModuleDescriptor["installClass"];
-    identity?: ModuleDescriptor["identity"];
+    kind: ModuleDescriptor["kind"];
+    identity: ModuleDescriptor["identity"];
     documentation: ModuleDescriptor["documentation"];
     provides: ModuleDescriptor["provides"];
     requires: ModuleDescriptor["requires"];
@@ -21,93 +14,7 @@ export interface ResolvedModule {
     verification: ModuleDescriptor["verification"];
     effects: DeploymentEffect[];
     source: {
-        type: "workspace" | "installed" | "registry";
+        type: "workspace" | "installed";
         path?: string;
     };
 }
-export interface DeploymentStep {
-    stepRef: string;
-    moduleRef: string;
-    kind: "config" | "package" | "lifecycle" | "external-resource" | "human";
-    preconditions: string[];
-    expectedEffect: string;
-    checkStrategy: string;
-    executeStrategy?: string;
-    postcondition: string;
-}
-export interface VerificationStep {
-    moduleRef: string;
-    checks: string[];
-}
-export interface DeploymentPlan {
-    planRef: string;
-    intent: DeploymentIntent;
-    moduleTargets: ModuleTarget[];
-    resolvedModules: ResolvedModule[];
-    targetDescriptors?: ModuleDescriptor[];
-    steps: DeploymentStep[];
-    effects: DeploymentEffect[];
-    humanActions: HumanAction[];
-    verification: VerificationStep[];
-    fingerprint: string;
-    createdAt: string;
-}
-export interface VerificationRecord {
-    verificationRef: string;
-    moduleRef: string;
-    moduleVersion: string;
-    resourceIdentity?: string;
-    resourceVersion?: string;
-    result: "PASS" | "FAIL";
-    summary: string;
-    evidenceRefs: string[];
-    verifiedAt: string;
-}
-export type PlatformState = "READY" | "DEGRADED" | "ACTION_REQUIRED" | "NOT_READY";
-export interface SelectedModuleFact {
-    moduleRef: string;
-    moduleVersion: string;
-}
-export interface DeploymentState {
-    contract: "proflow.deployment-state.v1";
-    selectedModules: SelectedModuleFact[];
-    lastAppliedPlans: {
-        planRef: string;
-        intent: DeploymentIntent;
-        appliedAt: string;
-    }[];
-    verificationIndex: {
-        moduleRef: string;
-        latestRef: string;
-    }[];
-    pendingActions: PendingActionRecord[];
-    updatedAt: string;
-}
-export interface PendingActionRecord {
-    planRef: string;
-    stepRef: string;
-    moduleRef: string;
-    action: string;
-    description?: string;
-    createdAt: string;
-}
-export interface LockRecord {
-    pid: number;
-    createdAt: string;
-    planRef: string;
-    workspaceFingerprint: string;
-}
-export type ApplyStepStatus = "SKIP" | "EXECUTED" | "ACTION_REQUIRED" | "FAILED";
-export interface ApplyStepResult {
-    stepRef: string;
-    moduleRef: string;
-    status: ApplyStepStatus;
-    message: string;
-}
-export type ApplyOutcome = "COMPLETE" | "ACTION_REQUIRED" | "FAILED" | "BLOCKED";
-export interface ApplyResult {
-    planRef: string;
-    outcome: ApplyOutcome;
-    stepResults: ApplyStepResult[];
-    completedAt: string;
-}

package/dist/src/discovery/discover.js

@@ -90,7 +90,6 @@ function toResolvedModule(descriptor, source) {
         packageName: descriptor.packageName,
         moduleVersion: descriptor.moduleVersion,
         kind: descriptor.kind,
-        installClass: descriptor.installClass,
         identity: descriptor.identity,
         documentation: descriptor.documentation,
         provides: descriptor.provides,

package/dist/src/docs/aggregate.d.ts

@@ -0,0 +1,18 @@
+import { type ConfigSlot, type ModuleProvide, type ModuleRequire } from "@tomflow/proflow-module-contract";
+import type { ResolvedModule } from "../contracts.ts";
+import type { ModuleCatalog } from "../modules.ts";
+export interface AggregatedDocument {
+    id: string;
+    path: string;
+    description?: string;
+    content: string;
+}
+export interface AggregatedModuleDocs {
+    moduleRef: string;
+    version: string;
+    provides: ModuleProvide[];
+    requires: ModuleRequire[];
+    configSlots: ConfigSlot[];
+    documents: AggregatedDocument[];
+}
+export declare function aggregateModuleDocs(workspaceRoot: string, catalog: ModuleCatalog, modules: readonly ResolvedModule[]): Promise<AggregatedModuleDocs[]>;

package/dist/src/docs/aggregate.js

@@ -0,0 +1,44 @@
+import { parseModuleDescriptor, } from "@tomflow/proflow-module-contract";
+import { readModuleDocument } from "./docs.js";
+function sourceOf(module) {
+    return module.source.path === undefined
+        ? { type: module.source.type, packageName: module.packageName }
+        : {
+            type: module.source.type,
+            packageName: module.packageName,
+            path: module.source.path,
+        };
+}
+export async function aggregateModuleDocs(workspaceRoot, catalog, modules) {
+    const output = [];
+    for (const module of [...modules].sort((a, b) => a.moduleRef.localeCompare(b.moduleRef))) {
+        const source = sourceOf(module);
+        const descriptor = parseModuleDescriptor(await catalog.loadDescriptor(source));
+        const documents = [];
+        for (const entry of descriptor.documentation) {
+            const document = await readModuleDocument({
+                workspaceRoot,
+                source,
+                descriptor,
+                documentId: entry.id,
+            });
+            documents.push({
+                id: document.documentId,
+                path: document.path,
+                ...(document.description === undefined
+                    ? {}
+                    : { description: document.description }),
+                content: document.content,
+            });
+        }
+        output.push({
+            moduleRef: module.moduleRef,
+            version: module.moduleVersion,
+            provides: [...descriptor.provides],
+            requires: [...descriptor.requires],
+            configSlots: [...descriptor.configSlots],
+            documents,
+        });
+    }
+    return output;
+}

package/dist/src/docs/docs.d.ts

@@ -1,31 +1,5 @@
 import type { ModuleDescriptor } from "@tomflow/proflow-module-contract";
 import type { ModuleSource } from "../modules.ts";
-export interface PublishedCommand {
-    name: string;
-    target: string;
-}
-export interface PublicApiEntry {
-    subpath: string;
-    target?: string;
-}
-export interface ModuleDocsView {
-    moduleRef: string;
-    packageName: string;
-    moduleVersion: string;
-    kind: ModuleDescriptor["kind"];
-    installClass: ModuleDescriptor["installClass"];
-    identity: ModuleDescriptor["identity"];
-    commands: PublishedCommand[];
-    publicApiEntries: PublicApiEntry[];
-    provides: ModuleDescriptor["provides"];
-    requires: ModuleDescriptor["requires"];
-    requirements: ModuleDescriptor["requirements"];
-    configSlots: ModuleDescriptor["configSlots"];
-    lifecycle: ModuleDescriptor["lifecycle"]["supported"];
-    verification: ModuleDescriptor["verification"];
-    effects: ModuleDescriptor["effects"];
-    documentation: ModuleDescriptor["documentation"];
-}
 export interface ModuleDocumentContent {
     moduleRef: string;
     packageName: string;
@@ -34,11 +8,6 @@ export interface ModuleDocumentContent {
     description?: string;
     content: string;
 }
-export declare function describeModule(input: {
-    workspaceRoot: string;
-    source: ModuleSource;
-    descriptor: ModuleDescriptor;
-}): Promise<ModuleDocsView>;
 export declare function readModuleDocument(input: {
     workspaceRoot: string;
     source: ModuleSource;

package/dist/src/docs/docs.js

@@ -3,33 +3,6 @@ import { createRequire } from "node:module";
 import { dirname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { PlatformError } from "../errors.js";
-function executableName(packageName) {
-    return packageName.split("/").pop() ?? packageName;
-}
-function commandsFrom(manifest, packageName) {
-    if (typeof manifest.bin === "string") {
-        return [{ name: executableName(packageName), target: manifest.bin }];
-    }
-    if (typeof manifest.bin !== "object" || manifest.bin === null)
-        return [];
-    return Object.entries(manifest.bin)
-        .flatMap(([name, target]) => typeof target === "string" ? [{ name, target }] : [])
-        .sort((left, right) => left.name.localeCompare(right.name));
-}
-function publicApiEntriesFrom(manifest) {
-    if (typeof manifest.exports === "string") {
-        return [{ subpath: ".", target: manifest.exports }];
-    }
-    if (typeof manifest.exports !== "object" || manifest.exports === null)
-        return [];
-    return Object.entries(manifest.exports)
-        .filter(([subpath]) => subpath.startsWith("."))
-        .map(([subpath, target]) => ({
-        subpath,
-        ...(typeof target === "string" ? { target } : {}),
-    }))
-        .sort((left, right) => left.subpath.localeCompare(right.subpath));
-}
 async function packageRootFor(workspaceRoot, source) {
     if (source.type === "workspace") {
         if (source.path === undefined) {
@@ -62,40 +35,6 @@ async function packageRootFor(workspaceRoot, source) {
     }
     throw new PlatformError("DESCRIPTOR_INVALID", `package root not found for ${source.packageName}`);
 }
-async function readManifest(packageRoot, packageName) {
-    try {
-        const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
-        if (manifest.name !== packageName) {
-            throw new Error(`expected package ${packageName}`);
-        }
-        return manifest;
-    }
-    catch (error) {
-        throw new PlatformError("DESCRIPTOR_INVALID", `invalid package metadata for ${packageName}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-export async function describeModule(input) {
-    const packageRoot = await packageRootFor(input.workspaceRoot, input.source);
-    const manifest = await readManifest(packageRoot, input.descriptor.packageName);
-    return {
-        moduleRef: input.descriptor.moduleRef,
-        packageName: input.descriptor.packageName,
-        moduleVersion: input.descriptor.moduleVersion,
-        kind: input.descriptor.kind,
-        installClass: input.descriptor.installClass,
-        identity: input.descriptor.identity,
-        commands: commandsFrom(manifest, input.descriptor.packageName),
-        publicApiEntries: publicApiEntriesFrom(manifest),
-        provides: input.descriptor.provides,
-        requires: input.descriptor.requires,
-        requirements: input.descriptor.requirements,
-        configSlots: input.descriptor.configSlots,
-        lifecycle: input.descriptor.lifecycle.supported,
-        verification: input.descriptor.verification,
-        effects: input.descriptor.effects,
-        documentation: input.descriptor.documentation,
-    };
-}
 export async function readModuleDocument(input) {
     const entry = input.descriptor.documentation.find((candidate) => candidate.id === input.documentId);
     if (entry === undefined) {

package/dist/src/docs/index.d.ts

@@ -1 +1,2 @@
-export * from "./docs.ts";
+export type { AggregatedDocument, AggregatedModuleDocs, } from "./aggregate.ts";
+export { aggregateModuleDocs } from "./aggregate.ts";

package/dist/src/docs/index.js

@@ -1 +1 @@
-export * from "./docs.js";
+export { aggregateModuleDocs } from "./aggregate.js";

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", "CONFIG_INVALID", "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 declare const platformErrorCodes: readonly ["INVALID_REQUEST", "DESCRIPTOR_INVALID", "DUPLICATE_IDENTITY", "DEPENDENCY_UNRESOLVED", "DEPENDENCY_INCOMPATIBLE", "DEPENDENCY_CYCLE", "CONFIG_INVALID", "WORKSPACE_NOT_FOUND", "WORKSPACE_INSTANCE_INVALID", "PACKAGE_MANAGER_UNSUPPORTED", "PACKAGE_MANAGER_CONFLICT", "PACKAGE_MANAGER_UNAVAILABLE", "LIFECYCLE_UNSUPPORTED", "UNINSTALL_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;

package/dist/src/errors.js

@@ -5,32 +5,14 @@ export const platformErrorCodes = [
     "DEPENDENCY_UNRESOLVED",
     "DEPENDENCY_INCOMPATIBLE",
     "DEPENDENCY_CYCLE",
-    "CONFIG_MISSING",
     "CONFIG_INVALID",
-    "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/dist/src/graph/graph.d.ts

@@ -11,13 +11,10 @@ export interface DependencyGraph {
     edges: DependencyEdge[];
     order: string[];
 }
-export interface GraphOptions {
-    config?: Record<string, Record<string, string>>;
-}
 export declare class ModuleRefUnresolvedError extends Error {
     readonly code: "MODULE_REF_UNRESOLVED";
     readonly from: string;
     readonly target: string;
     constructor(from: string, target: string, message: string);
 }
-export declare function buildDependencyGraph(modules: readonly ResolvedModule[], options?: GraphOptions): DependencyGraph;
+export declare function buildDependencyGraph(modules: readonly ResolvedModule[]): DependencyGraph;

package/dist/src/graph/graph.js

@@ -14,9 +14,8 @@ export class ModuleRefUnresolvedError extends Error {
 function compareRef(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
-export function buildDependencyGraph(modules, options = {}) {
+export function buildDependencyGraph(modules) {
     const nodes = [...new Set(modules.map((module) => module.moduleRef))].sort(compareRef);
-    const nodeSet = new Set(nodes);
     const providersByContract = new Map();
     for (const module of modules) {
         for (const provide of module.provides) {
@@ -39,17 +38,6 @@ export function buildDependencyGraph(modules, options = {}) {
     };
     const sorted = [...modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
     for (const module of sorted) {
-        for (const slot of module.configSlots) {
-            if (slot.type !== "moduleRef")
-                continue;
-            const effective = options.config?.[module.moduleRef]?.[slot.key] ?? slot.default;
-            if (typeof effective !== "string")
-                continue;
-            if (!nodeSet.has(effective)) {
-                throw new ModuleRefUnresolvedError(module.moduleRef, effective, `moduleRef binding ${slot.key}=${effective} for ${module.moduleRef} does not resolve to a selected module`);
-            }
-            addEdge(module.moduleRef, effective, "moduleRef");
-        }
         for (const requirement of module.requires) {
             const candidates = providersByContract.get(requirement.contractRef) ?? [];
             const matching = candidates

package/dist/src/graph/index.d.ts

@@ -1,2 +1,2 @@
-export type { DependencyEdge, DependencyEdgeKind, DependencyGraph, GraphOptions, } from "./graph.ts";
-export { buildDependencyGraph, ModuleRefUnresolvedError } from "./graph.ts";
+export type { DependencyEdge, DependencyEdgeKind, DependencyGraph, } from "./graph.ts";
+export { buildDependencyGraph } from "./graph.ts";

package/dist/src/graph/index.js

@@ -1 +1 @@
-export { buildDependencyGraph, ModuleRefUnresolvedError } from "./graph.js";
+export { buildDependencyGraph } from "./graph.js";

package/dist/src/index.d.ts

@@ -1,28 +1,8 @@
-export type { PackageManagerDriver } from "./apply/driver.ts";
-export { applyPlan, createWorkspacePackageManagerDriver, } from "./apply/index.ts";
-export type { CliOutcome, CliStatus } from "./cli.ts";
-export { runCli } from "./cli.ts";
-export type { DeploymentIntent, DeploymentPlan, DeploymentState, DeploymentStep, ModuleTarget, PlatformState, ResolvedModule, VerificationRecord, VerificationStep, } from "./contracts.ts";
+export type { CliOutcome, CliRuntimeOptions, CliStatus, } from "./cli.ts";
+export { renderHumanResult, runCli } from "./cli.ts";
 export { AutoModuleCatalog, discoverModules } from "./discovery/discover.ts";
-export type { ModuleDocsView, ModuleDocumentContent, PublicApiEntry, PublishedCommand, } from "./docs/index.ts";
-export { describeModule, readModuleDocument } from "./docs/index.ts";
-export { doctorModule, doctorModules } from "./doctor/index.ts";
+export type { AggregatedDocument, AggregatedModuleDocs, } from "./docs/aggregate.ts";
+export { aggregateModuleDocs } from "./docs/aggregate.ts";
 export type { PlatformErrorCode } from "./errors.ts";
 export { PlatformError } from "./errors.ts";
-export { generateInstallDoc, preflightInstallerEnvironment, renderInstallDoc, } from "./install/index.ts";
-export { dispatchLifecycle, restartModules, startModules, statusModules, stopModules, } from "./lifecycle/index.ts";
-export { buildManifest, MANIFEST_CONTRACT } from "./manifest/index.ts";
 export type { ModuleCatalog, ModuleSource } from "./modules.ts";
-export { versionSatisfies } from "./modules.ts";
-export type { WorkspacePaths } from "./paths.ts";
-export { atomicWrite, workspacePaths } from "./paths.ts";
-export { appendVerification, emptyDeploymentState, listPlans, loadConfig, loadDeploymentState, loadLatestVerification, loadPlan, loadVerificationHistory, materializeConfig, saveDeploymentState, savePlan, writeInstallDoc, } from "./persistence/index.ts";
-export { assessUpgrade, CheckStrategy, checkPlanStale, computeFingerprint, ExecuteStrategy, evaluateStepCheck, planDeployment, planRepair, planUpgrade, repairFactCodes, } from "./planner/index.ts";
-export type { PlanInput } from "./planner/plan.ts";
-export type { PreflightResult } from "./preflight/findings.ts";
-export { runPreflight } from "./preflight/preflight.ts";
-export { assessPlatformReady } from "./ready/index.ts";
-export type { RegistryDiscoveryResult, RegistryModuleCandidate, RegistryRejectedPackage, } from "./registry/index.ts";
-export { discoverRegistryModules } from "./registry/index.ts";
-export { acquireWorkspaceLock, readWorkspaceLock, redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, workspaceLockPath, } from "./security/index.ts";
-export { verifyModule, verifyModules } from "./verification/index.ts";

package/dist/src/index.js

@@ -1,18 +1,4 @@
-export { applyPlan, createWorkspacePackageManagerDriver, } from "./apply/index.js";
-export { runCli } from "./cli.js";
+export { renderHumanResult, runCli } from "./cli.js";
 export { AutoModuleCatalog, discoverModules } from "./discovery/discover.js";
-export { describeModule, readModuleDocument } from "./docs/index.js";
-export { doctorModule, doctorModules } from "./doctor/index.js";
+export { aggregateModuleDocs } from "./docs/aggregate.js";
 export { PlatformError } from "./errors.js";
-export { generateInstallDoc, preflightInstallerEnvironment, renderInstallDoc, } from "./install/index.js";
-export { dispatchLifecycle, restartModules, startModules, statusModules, stopModules, } from "./lifecycle/index.js";
-export { buildManifest, MANIFEST_CONTRACT } from "./manifest/index.js";
-export { versionSatisfies } from "./modules.js";
-export { atomicWrite, workspacePaths } from "./paths.js";
-export { appendVerification, emptyDeploymentState, listPlans, loadConfig, loadDeploymentState, loadLatestVerification, loadPlan, loadVerificationHistory, materializeConfig, saveDeploymentState, savePlan, writeInstallDoc, } from "./persistence/index.js";
-export { assessUpgrade, CheckStrategy, checkPlanStale, computeFingerprint, ExecuteStrategy, evaluateStepCheck, planDeployment, planRepair, planUpgrade, repairFactCodes, } from "./planner/index.js";
-export { runPreflight } from "./preflight/preflight.js";
-export { assessPlatformReady } from "./ready/index.js";
-export { discoverRegistryModules } from "./registry/index.js";
-export { acquireWorkspaceLock, readWorkspaceLock, redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, workspaceLockPath, } from "./security/index.js";
-export { verifyModule, verifyModules } from "./verification/index.js";

package/dist/src/install/package-manager.d.ts

@@ -11,3 +11,24 @@ export interface PackageCommandRunner {
 export declare function systemPackageCommandRunner(): PackageCommandRunner;
 export declare function readWorkspacePackageManagerSelection(workspaceRoot: string): Promise<WorkspacePackageManagerSelection>;
 export declare function findExecutable(command: string): boolean;
+export interface WorkspacePackageTarget {
+    packageName: string;
+    version: string;
+}
+export interface WorkspacePackageMutationResult {
+    packageManager: SupportedWorkspacePackageManager;
+    packages: string[];
+}
+export declare function syncWorkspacePackages(options: {
+    workspaceRoot: string;
+    packages: readonly WorkspacePackageTarget[];
+    runner?: PackageCommandRunner;
+    executableAvailable?: (command: string) => boolean;
+}): Promise<WorkspacePackageMutationResult>;
+export declare function removeWorkspacePackages(options: {
+    workspaceRoot: string;
+    packageNames: readonly string[];
+    runner?: PackageCommandRunner;
+    executableAvailable?: (command: string) => boolean;
+}): Promise<WorkspacePackageMutationResult>;
+export declare function observeWorkspaceInstalledVersion(workspaceRoot: string, packageName: string): Promise<string | undefined>;

package/dist/src/install/package-manager.js

@@ -4,6 +4,7 @@ import { access, readFile } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import { promisify } from "node:util";
 import { PlatformError } from "../errors.js";
+import { atomicWrite } from "../paths.js";
 const execFileAsync = promisify(execFile);
 export function systemPackageCommandRunner() {
     return {
@@ -112,3 +113,155 @@ function isMissingFile(error) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+export async function syncWorkspacePackages(options) {
+    if (options.packages.length === 0) {
+        return { packageManager: "npm", packages: [] };
+    }
+    await ensureWorkspaceManifest(options.workspaceRoot);
+    const runner = options.runner ?? systemPackageCommandRunner();
+    const manager = await requireWorkspacePackageManager(options.workspaceRoot, options.executableAvailable ?? findExecutable);
+    const targets = [...options.packages].sort((a, b) => a.packageName.localeCompare(b.packageName));
+    const specs = targets.map((item) => `${item.packageName}@${item.version}`);
+    await writeManagedPackageSet(options.workspaceRoot, targets);
+    const args = await packageManagerInstallArgs(runner, manager, options.workspaceRoot);
+    try {
+        await runner.run(manager.name, args, options.workspaceRoot);
+    }
+    catch (error) {
+        throw new PlatformError("COMMAND_FAILED", `${manager.name} install failed: ${packageMutationError(error)}`);
+    }
+    return { packageManager: manager.name, packages: specs };
+}
+async function writeManagedPackageSet(workspaceRoot, targets) {
+    const path = join(workspaceRoot, "package.json");
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (!isRecord(parsed)) {
+        throw new PlatformError("INVALID_REQUEST", "workspace package.json root must be an object");
+    }
+    const dependencies = isRecord(parsed.dependencies)
+        ? { ...parsed.dependencies }
+        : {};
+    const devDependencies = isRecord(parsed.devDependencies)
+        ? { ...parsed.devDependencies }
+        : {};
+    for (const record of [dependencies, devDependencies]) {
+        for (const name of Object.keys(record)) {
+            if (name.startsWith("@tomflow/proflow-"))
+                delete record[name];
+        }
+    }
+    for (const target of targets)
+        dependencies[target.packageName] = target.version;
+    const next = { ...parsed, dependencies };
+    if ("devDependencies" in parsed || Object.keys(devDependencies).length > 0) {
+        next.devDependencies = devDependencies;
+    }
+    await atomicWrite(path, `${JSON.stringify(next, null, 2)}\n`);
+}
+async function packageManagerInstallArgs(runner, manager, workspaceRoot) {
+    if (manager.name === "pnpm")
+        return ["install", "--ignore-scripts"];
+    if (manager.name === "npm")
+        return ["install", "--ignore-scripts"];
+    const major = await batchYarnMajorVersion(runner, manager, workspaceRoot);
+    return major <= 1
+        ? ["install", "--ignore-scripts"]
+        : ["install", "--mode=skip-build"];
+}
+export async function removeWorkspacePackages(options) {
+    const packageNames = [...new Set(options.packageNames)].sort();
+    if (packageNames.length === 0) {
+        return { packageManager: "npm", packages: [] };
+    }
+    const runner = options.runner ?? systemPackageCommandRunner();
+    const manager = await requireWorkspacePackageManager(options.workspaceRoot, options.executableAvailable ?? findExecutable);
+    const args = await batchPackageManagerArgs(runner, manager, options.workspaceRoot, "remove", packageNames);
+    try {
+        await runner.run(manager.name, args, options.workspaceRoot);
+    }
+    catch (error) {
+        throw new PlatformError("UNINSTALL_FAILED", `${manager.name} remove failed: ${packageMutationError(error)}`);
+    }
+    return { packageManager: manager.name, packages: packageNames };
+}
+export async function observeWorkspaceInstalledVersion(workspaceRoot, packageName) {
+    try {
+        const raw = await readFile(join(workspaceRoot, "node_modules", ...packageName.split("/"), "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed) ||
+            parsed.name !== packageName ||
+            typeof parsed.version !== "string") {
+            return undefined;
+        }
+        return parsed.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function ensureWorkspaceManifest(workspaceRoot) {
+    const path = join(workspaceRoot, "package.json");
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            throw new Error("package.json root must be an object");
+        return;
+    }
+    catch (error) {
+        if (!isMissingFile(error)) {
+            throw new PlatformError("INVALID_REQUEST", `workspace package.json is invalid: ${errorMessage(error)}`);
+        }
+    }
+    await atomicWrite(path, `${JSON.stringify({ private: true }, null, 2)}\n`);
+}
+async function requireWorkspacePackageManager(workspaceRoot, executableAvailable) {
+    const manager = await readWorkspacePackageManagerSelection(workspaceRoot);
+    if (!executableAvailable(manager.name)) {
+        throw new PlatformError("PACKAGE_MANAGER_UNAVAILABLE", `workspace package manager ${manager.name} is not available on PATH`);
+    }
+    return manager;
+}
+async function batchPackageManagerArgs(runner, manager, workspaceRoot, operation, packages) {
+    if (manager.name === "pnpm") {
+        return operation === "remove"
+            ? ["--config.ignore-scripts=true", "remove", ...packages]
+            : ["add", "--save-exact", "--ignore-scripts", ...packages];
+    }
+    if (manager.name === "npm") {
+        return operation === "remove"
+            ? ["uninstall", "--ignore-scripts", ...packages]
+            : ["install", "--save-exact", "--ignore-scripts", ...packages];
+    }
+    const major = await batchYarnMajorVersion(runner, manager, workspaceRoot);
+    if (major <= 1) {
+        return operation === "remove"
+            ? ["remove", "--ignore-scripts", ...packages]
+            : ["add", "--exact", "--ignore-scripts", ...packages];
+    }
+    return operation === "remove"
+        ? ["remove", "--mode=skip-build", ...packages]
+        : ["add", "--exact", "--mode=skip-build", ...packages];
+}
+async function batchYarnMajorVersion(runner, manager, workspaceRoot) {
+    const declared = manager.declared;
+    const separator = declared?.lastIndexOf("@") ?? -1;
+    const declaredVersion = declared !== undefined && separator > 0
+        ? declared.slice(separator + 1)
+        : undefined;
+    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 packageMutationError(error) {
+    if (isRecord(error) &&
+        typeof error.stderr === "string" &&
+        error.stderr.trim() !== "") {
+        return error.stderr.trim();
+    }
+    return errorMessage(error);
+}