@tomflow/proflow-platform-cli 0.1.13 → 0.1.15

package/dist/src/apply/current.js

@@ -1,95 +0,0 @@
-import { parseModuleDescriptor, } from "@tomflow/proflow-module-contract";
-import { discoverModules } from "../discovery/index.js";
-import { doctorModules } from "../doctor/index.js";
-import { mergeEffectiveConfig } from "../persistence/effective-config.js";
-import { diagnoseRepair } from "../planner/repair.js";
-function moduleSourceOf(module) {
-    if (module.source.type === "registry") {
-        throw new Error(`registry bootstrap target ${module.packageName} has no local descriptor`);
-    }
-    const source = {
-        type: module.source.type,
-        packageName: module.packageName,
-    };
-    if (module.source.path !== undefined)
-        source.path = module.source.path;
-    return source;
-}
-async function loadDescriptors(catalog, modules) {
-    const descriptors = [];
-    for (const module of modules) {
-        const raw = await catalog.loadDescriptor(moduleSourceOf(module));
-        descriptors.push(parseModuleDescriptor(raw));
-    }
-    return descriptors;
-}
-// Rebuilds a plan's stable current assumptions from the CURRENT module catalog
-// and current reality. The old plan's resolvedModules are never reused: modules
-// are re-discovered and re-parsed so descriptor drift reaches the staleness
-// gate. Upgrade additionally re-discovers current descriptors and reuses the
-// plan's frozen target descriptors; repair re-runs doctor for fresh facts.
-export async function rebuildCurrentAssumptions(catalog, plan, paths) {
-    if ((plan.intent === "install" || plan.intent === "upgrade") &&
-        plan.resolvedModules.every((module) => module.source.type === "registry")) {
-        return {
-            intent: plan.intent,
-            modules: plan.resolvedModules,
-            targets: plan.moduleTargets,
-        };
-    }
-    const discovered = await discoverModules({ catalog });
-    const byRef = new Map(discovered.map((module) => [module.moduleRef, module]));
-    const modules = [];
-    for (const target of plan.moduleTargets) {
-        const module = byRef.get(target.moduleRef);
-        if (module !== undefined)
-            modules.push(module);
-    }
-    if (plan.intent === "upgrade") {
-        const currentDescriptors = await loadDescriptors(catalog, modules);
-        const config = await mergeEffectiveConfig(paths, modules, {});
-        if (plan.targetDescriptors === undefined)
-            return {
-                intent: plan.intent,
-                modules,
-                targets: plan.moduleTargets,
-                config,
-            };
-        return {
-            intent: plan.intent,
-            modules,
-            targets: plan.moduleTargets,
-            config,
-            currentDescriptors,
-            targetDescriptors: plan.targetDescriptors,
-        };
-    }
-    if (plan.intent === "repair") {
-        const diagnosis = diagnoseRepair(await doctorModules(catalog, modules));
-        return {
-            intent: plan.intent,
-            modules,
-            targets: plan.moduleTargets,
-            facts: diagnosis.facts,
-        };
-    }
-    if (plan.intent === "uninstall") {
-        // A persisted uninstall plan does not store uninstallScope. Recover the only
-        // legal scope from its module set for the staleness re-plan: any core module
-        // can only have entered the plan through whole-instance uninstall.
-        const uninstallScope = plan.resolvedModules.some((module) => module.installClass === "core")
-            ? "platform-instance"
-            : "module";
-        return {
-            intent: plan.intent,
-            modules,
-            targets: plan.moduleTargets,
-            uninstallScope,
-        };
-    }
-    return {
-        intent: plan.intent,
-        modules,
-        targets: plan.moduleTargets,
-    };
-}

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

@@ -1,28 +0,0 @@
-import type { ResolvedModule } from "../contracts.ts";
-import { type PackageCommandRunner } from "../install/package-manager.ts";
-/**
- * Package-level installation seam. Apply never invokes an arbitrary shell: a
- * package step is satisfied or mutated only through this injected driver. The
- * production driver executes a fixed package-manager binary with argv arrays.
- */
-export interface PackageManagerDriver {
-    observeInstalledVersion(module: ResolvedModule): Promise<string | undefined>;
-    install(module: ResolvedModule): Promise<void>;
-    upgrade(module: ResolvedModule): Promise<void>;
-    remove(module: ResolvedModule): Promise<void>;
-}
-/**
- * Monorepo/test seam retained for source-resident planning. Production CLI must
- * inject createWorkspacePackageManagerDriver(); it must never rely on this
- * no-op driver to claim a product Workspace package mutation succeeded.
- */
-export declare function workspaceResidentDriver(): PackageManagerDriver;
-export declare function cleanupWorkspacePackageManagerArtifacts(options: {
-    workspaceRoot: string;
-    removedModules: readonly ResolvedModule[];
-}): Promise<void>;
-export declare function createWorkspacePackageManagerDriver(options: {
-    workspaceRoot: string;
-    runner?: PackageCommandRunner;
-    executableAvailable?: (command: string) => boolean;
-}): PackageManagerDriver;

package/dist/src/apply/driver.js

@@ -1,239 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { PlatformError } from "../errors.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
- * inject createWorkspacePackageManagerDriver(); it must never rely on this
- * no-op driver to claim a product Workspace package mutation succeeded.
- */
-export function workspaceResidentDriver() {
-    return {
-        async observeInstalledVersion(module) {
-            return module.moduleVersion;
-        },
-        async install() { },
-        async upgrade() { },
-        async remove() { },
-    };
-}
-export async function cleanupWorkspacePackageManagerArtifacts(options) {
-    const manager = await readWorkspacePackageManagerSelection(options.workspaceRoot);
-    if (manager.name !== "pnpm")
-        return;
-    const removedPackageNames = new Set(options.removedModules.map((module) => module.packageName));
-    await cleanupPnpmReleaseAgeExcludes(options.workspaceRoot, removedPackageNames);
-    await normalizeEmptyPnpmRootImporter(options.workspaceRoot);
-}
-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, 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, executableAvailable);
-            await mutatePackage(runner, manager, options.workspaceRoot, "upgrade", `${module.packageName}@${module.moduleVersion}`);
-        },
-        remove: async (module) => {
-            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 = await packageManagerArgs(runner, manager, workspaceRoot, operation, packageSpec);
-    try {
-        await runner.run(manager.name, args, workspaceRoot);
-    }
-    catch (error) {
-        throw new PlatformError(operation === "upgrade" ? "UPGRADE_FAILED" : "APPLY_FAILED", `${manager.name} ${operation} failed for ${packageSpec}: ${errorMessage(error)}`);
-    }
-}
-async function packageManagerArgs(runner, manager, workspaceRoot, operation, packageSpec) {
-    if (manager.name === "pnpm") {
-        return operation === "remove"
-            ? ["--config.ignore-scripts=true", "remove", 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"
-        ? ["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, 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 ensureWorkspacePackageJson(workspaceRoot) {
-    const path = join(workspaceRoot, "package.json");
-    try {
-        const raw = await readFile(path, "utf8");
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== "object" ||
-            parsed === null ||
-            Array.isArray(parsed)) {
-            throw new Error("package.json root must be an object");
-        }
-        return;
-    }
-    catch (error) {
-        if (!isMissingFile(error)) {
-            throw new PlatformError("APPLY_FAILED", `workspace package.json is invalid: ${errorMessage(error)}`);
-        }
-    }
-    await atomicWrite(path, `${JSON.stringify({ private: true }, null, 2)}\n`);
-}
-async function observeInstalledVersion(workspaceRoot, packageName) {
-    const manifest = await readWorkspaceManifest(workspaceRoot);
-    if (manifest === undefined ||
-        (!hasOwn(manifest.dependencies, packageName) &&
-            !hasOwn(manifest.devDependencies, packageName))) {
-        return undefined;
-    }
-    try {
-        const raw = await readFile(join(workspaceRoot, "node_modules", ...packageName.split("/"), "package.json"), "utf8");
-        const parsed = JSON.parse(raw);
-        if (typeof parsed === "object" &&
-            parsed !== null &&
-            !Array.isArray(parsed) &&
-            Reflect.get(parsed, "name") === packageName &&
-            typeof Reflect.get(parsed, "version") === "string") {
-            return Reflect.get(parsed, "version");
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function readWorkspaceManifest(workspaceRoot) {
-    try {
-        const raw = await readFile(join(workspaceRoot, "package.json"), "utf8");
-        const parsed = JSON.parse(raw);
-        return typeof parsed === "object" &&
-            parsed !== null &&
-            !Array.isArray(parsed)
-            ? parsed
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function cleanupPnpmReleaseAgeExcludes(workspaceRoot, removedPackageNames) {
-    const path = join(workspaceRoot, "pnpm-workspace.yaml");
-    let raw;
-    try {
-        raw = await readFile(path, "utf8");
-    }
-    catch (error) {
-        if (isMissingFile(error))
-            return;
-        throw error;
-    }
-    const lines = raw.split("\n");
-    const keyIndex = lines.indexOf("minimumReleaseAgeExclude:");
-    if (keyIndex < 0)
-        return;
-    let endIndex = keyIndex + 1;
-    while (endIndex < lines.length &&
-        (lines[endIndex]?.trim() === "" || /^\s/.test(lines[endIndex] ?? ""))) {
-        endIndex += 1;
-    }
-    const retained = lines.slice(keyIndex + 1, endIndex).filter((line) => {
-        const match = /^\s*-\s+(.+?)\s*$/.exec(line);
-        if (match === null)
-            return true;
-        const value = stripYamlQuotes(match[1] ?? "");
-        for (const packageName of removedPackageNames) {
-            if (value === packageName || value.startsWith(`${packageName}@`))
-                return false;
-        }
-        return true;
-    });
-    const hasListItem = retained.some((line) => /^\s*-\s+/.test(line));
-    const replacement = hasListItem ? [lines[keyIndex] ?? "", ...retained] : [];
-    let next = [
-        ...lines.slice(0, keyIndex),
-        ...replacement,
-        ...lines.slice(endIndex),
-    ].join("\n");
-    if (raw.endsWith("\n") && !next.endsWith("\n"))
-        next += "\n";
-    if (next !== raw)
-        await atomicWrite(path, next);
-}
-async function normalizeEmptyPnpmRootImporter(workspaceRoot) {
-    const path = join(workspaceRoot, "pnpm-lock.yaml");
-    let raw;
-    try {
-        raw = await readFile(path, "utf8");
-    }
-    catch (error) {
-        if (isMissingFile(error))
-            return;
-        throw error;
-    }
-    const next = raw.replace("\nimporters:\n\n  .: {}\n", "\nimporters:\n  .: {}\n");
-    if (next !== raw)
-        await atomicWrite(path, next);
-}
-function stripYamlQuotes(value) {
-    if ((value.startsWith("'") && value.endsWith("'")) ||
-        (value.startsWith('"') && value.endsWith('"'))) {
-        return value.slice(1, -1);
-    }
-    return value;
-}
-function hasOwn(record, key) {
-    return record !== undefined && Object.hasOwn(record, key);
-}
-function isMissingFile(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        Reflect.get(error, "code") === "ENOENT");
-}
-function errorMessage(error) {
-    if (typeof error === "object" && error !== null) {
-        const stderr = Reflect.get(error, "stderr");
-        if (typeof stderr === "string" && stderr.trim() !== "")
-            return stderr.trim();
-    }
-    return error instanceof Error ? error.message : String(error);
-}

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

@@ -1,36 +0,0 @@
-import type { HumanAction } from "@tomflow/proflow-module-contract";
-import type { DeploymentPlan, DeploymentStep } from "../contracts.ts";
-import type { ModuleCatalog } from "../modules.ts";
-import type { WorkspacePaths } from "../paths.ts";
-import type { PackageManagerDriver } from "./driver.ts";
-export interface ExecuteDeps {
-    paths: WorkspacePaths;
-    catalog: ModuleCatalog;
-    driver: PackageManagerDriver;
-}
-/**
- * Structured result of executing one non-human step. A lifecycle adapter's
- * `ModuleOperationResult` is preserved verbatim: ACTION_REQUIRED / BLOCKED /
- * FAILED are returned as values, never collapsed into a thrown APPLY_FAILED.
- * Only genuine boundary violations (missing module, unsupported strategy,
- * malformed adapter result) still throw.
- */
-export type ExecuteStepOutcome = {
-    kind: "SUCCEEDED";
-} | {
-    kind: "ACTION_REQUIRED";
-    actionRequired: HumanAction;
-} | {
-    kind: "BLOCKED";
-    reason: string;
-} | {
-    kind: "FAILED";
-    reason: string;
-};
-/**
- * Executes a single non-human step by kind + execute strategy, returning a
- * structured outcome instead of throwing for ACTION_REQUIRED / BLOCKED / FAILED
- * lifecycle results. Package/config mutations still throw on genuine driver or
- * boundary errors; those are not lifecycle outcomes and must not be swallowed.
- */
-export declare function executeStep(deps: ExecuteDeps, step: DeploymentStep, plan: DeploymentPlan): Promise<ExecuteStepOutcome>;

package/dist/src/apply/execute.js

@@ -1,152 +0,0 @@
-import { PlatformError } from "../errors.js";
-import { dispatchLifecycle } from "../lifecycle/index.js";
-import { materializeConfig } from "../persistence/index.js";
-import { ExecuteStrategy } from "../planner/index.js";
-import { cleanupRemovableFilesystemEffects } from "./cleanup.js";
-function moduleOf(plan, step) {
-    return plan.resolvedModules.find((module) => module.moduleRef === step.moduleRef);
-}
-function moduleSourceForMaterialization(module) {
-    if (module.source.type === "registry") {
-        throw new PlatformError("APPLY_FAILED", `registry bootstrap target ${module.packageName} has no local config materializer`);
-    }
-    return {
-        type: module.source.type,
-        packageName: module.packageName,
-        ...(module.source.path === undefined ? {} : { path: module.source.path }),
-    };
-}
-async function materializeModuleOwnedConfig(deps, module, config) {
-    const namespace = await deps.catalog.loadAdapter(moduleSourceForMaterialization(module));
-    if (typeof namespace !== "object" || namespace === null)
-        return;
-    const materializer = Reflect.get(namespace, "materializeProductionConfig");
-    if (typeof materializer !== "function")
-        return;
-    await materializer({
-        moduleRef: module.moduleRef,
-        config: config.values,
-        workspaceRoot: deps.paths.root,
-    });
-}
-function configForStep(plan, step, module) {
-    const target = plan.moduleTargets.find((entry) => entry.moduleRef === step.moduleRef);
-    if (target?.config === undefined)
-        return undefined;
-    const secretRefs = module.configSlots
-        .filter((slot) => slot.type === "secretRef")
-        .map((slot) => slot.key);
-    return {
-        moduleRef: step.moduleRef,
-        values: target.config,
-        secretRefs,
-    };
-}
-function lifecyclePrimitive(step) {
-    switch (step.executeStrategy) {
-        case ExecuteStrategy.lifecycleStart:
-            return "start";
-        case ExecuteStrategy.lifecycleStop:
-            return "stop";
-        case ExecuteStrategy.lifecycleRestart:
-            return "restart";
-        case ExecuteStrategy.lifecycleUninstall:
-            return "uninstall";
-        case ExecuteStrategy.lifecycleMigrate:
-            return "migrate";
-        default:
-            throw new PlatformError("APPLY_FAILED", `unsupported lifecycle strategy ${step.executeStrategy ?? "<none>"}`);
-    }
-}
-function externalResourcePrimitive(step) {
-    if (step.executeStrategy === ExecuteStrategy.externalResourceConfigure) {
-        return "start";
-    }
-    throw new PlatformError("APPLY_FAILED", `unsupported external-resource strategy ${step.executeStrategy ?? "<none>"}`);
-}
-function requiredActionRequired(result) {
-    const actionRequired = result.actionRequired;
-    if (actionRequired === undefined) {
-        throw new PlatformError("APPLY_FAILED", `module ${result.moduleRef} reported ACTION_REQUIRED without a recoverable action`);
-    }
-    return actionRequired;
-}
-function operationOutcome(result) {
-    switch (result.status) {
-        case "SUCCEEDED":
-            return { kind: "SUCCEEDED" };
-        case "ACTION_REQUIRED":
-            return {
-                kind: "ACTION_REQUIRED",
-                actionRequired: requiredActionRequired(result),
-            };
-        case "BLOCKED":
-            return {
-                kind: "BLOCKED",
-                reason: `module ${result.moduleRef} is blocked`,
-            };
-        case "FAILED":
-            return {
-                kind: "FAILED",
-                reason: result.error?.message ?? `module ${result.moduleRef} failed`,
-            };
-    }
-}
-/**
- * Executes a single non-human step by kind + execute strategy, returning a
- * structured outcome instead of throwing for ACTION_REQUIRED / BLOCKED / FAILED
- * lifecycle results. Package/config mutations still throw on genuine driver or
- * boundary errors; those are not lifecycle outcomes and must not be swallowed.
- */
-export async function executeStep(deps, step, plan) {
-    const module = moduleOf(plan, step);
-    if (module === undefined) {
-        throw new PlatformError("APPLY_FAILED", `module ${step.moduleRef} is not in the plan`);
-    }
-    switch (step.kind) {
-        case "package": {
-            if (step.executeStrategy === ExecuteStrategy.packageRemove) {
-                await deps.driver.remove(module);
-            }
-            else if (step.executeStrategy === ExecuteStrategy.packageUpgrade) {
-                await deps.driver.upgrade(module);
-            }
-            else {
-                await deps.driver.install(module);
-            }
-            return { kind: "SUCCEEDED" };
-        }
-        case "config": {
-            const config = configForStep(plan, step, module);
-            if (config === undefined) {
-                throw new PlatformError("APPLY_FAILED", `module ${step.moduleRef} has no config target to materialize`);
-            }
-            // The Platform-owned public config is authoritative apply reality. Do not
-            // commit it until the module-owned materializer has accepted the target;
-            // otherwise a failed materializer can leave a false-satisfied config step
-            // that a same-plan resume would incorrectly SKIP.
-            await materializeModuleOwnedConfig(deps, module, config);
-            await materializeConfig(deps.paths, config);
-            return { kind: "SUCCEEDED" };
-        }
-        case "lifecycle": {
-            const primitive = lifecyclePrimitive(step);
-            const dispatched = await dispatchLifecycle(deps.catalog, module, primitive);
-            const operation = operationOutcome(dispatched.result);
-            if (primitive === "uninstall" && operation.kind === "SUCCEEDED") {
-                await cleanupRemovableFilesystemEffects({
-                    workspaceRoot: deps.paths.root,
-                    effects: module.effects,
-                });
-            }
-            return operation;
-        }
-        case "external-resource": {
-            const primitive = externalResourcePrimitive(step);
-            const dispatched = await dispatchLifecycle(deps.catalog, module, primitive);
-            return operationOutcome(dispatched.result);
-        }
-        case "human":
-            throw new PlatformError("APPLY_FAILED", `human step ${step.stepRef} must be routed to ACTION_REQUIRED, not executed`);
-    }
-}

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

@@ -1,8 +0,0 @@
-export type { ApplyContext } from "./apply.ts";
-export { applyPlan } from "./apply.ts";
-export type { PackageManagerDriver } from "./driver.ts";
-export { createWorkspacePackageManagerDriver } from "./driver.ts";
-export type { ExecuteDeps, ExecuteStepOutcome } from "./execute.ts";
-export { executeStep } from "./execute.ts";
-export type { RealityObserver, RealityObserverDeps } from "./reality.ts";
-export { createRealityObserver } from "./reality.ts";

package/dist/src/apply/index.js

@@ -1,4 +0,0 @@
-export { applyPlan } from "./apply.js";
-export { createWorkspacePackageManagerDriver } from "./driver.js";
-export { executeStep } from "./execute.js";
-export { createRealityObserver } from "./reality.js";

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

@@ -1,20 +0,0 @@
-import type { DeploymentPlan, DeploymentStep } from "../contracts.ts";
-import type { ModuleCatalog } from "../modules.ts";
-import type { WorkspacePaths } from "../paths.ts";
-import type { StepReality } from "../planner/index.ts";
-import type { PackageManagerDriver } from "./driver.ts";
-/**
- * Observes the current reality of a single step. The apply loop consults this
- * before every decision so that persisted history can never impersonate current
- * reality; a step that is no longer satisfied is re-executed, never faked as
- * skipped.
- */
-export interface RealityObserver {
-    observe(step: DeploymentStep, plan: DeploymentPlan): Promise<StepReality | undefined>;
-}
-export interface RealityObserverDeps {
-    paths: WorkspacePaths;
-    catalog: ModuleCatalog;
-    driver: PackageManagerDriver;
-}
-export declare function createRealityObserver(deps: RealityObserverDeps): RealityObserver;