@tomflow/proflow-platform-cli 0.1.14 → 0.1.15

package/dist/src/install/bootstrap.js

@@ -1,79 +0,0 @@
-import { PlatformError } from "../errors.js";
-import { PRO_FLOW_PACKAGE_PREFIX, } from "../registry/index.js";
-/**
- * Registry bootstrap targets intentionally carry only facts available before
- * installation. They are package-plan placeholders, never substitutes for the
- * package-owned Module Descriptor that is loaded after installation.
- */
-export function registryCandidateToBootstrapModule(candidate) {
-    if (!candidate.packageName.startsWith(PRO_FLOW_PACKAGE_PREFIX)) {
-        throw new PlatformError("PACKAGE_NOT_PROFLOW", `package ${candidate.packageName} is outside ${PRO_FLOW_PACKAGE_PREFIX}*`);
-    }
-    const moduleRef = candidate.packageName.slice(PRO_FLOW_PACKAGE_PREFIX.length);
-    if (moduleRef === "") {
-        throw new PlatformError("REGISTRY_RESPONSE_INVALID", `cannot derive moduleRef from ${candidate.packageName}`);
-    }
-    return {
-        moduleRef,
-        packageName: candidate.packageName,
-        moduleVersion: candidate.moduleVersion,
-        kind: "registry-package",
-        installClass: candidate.installClass,
-        provides: [],
-        requires: [],
-        requirements: [],
-        configSlots: [],
-        lifecycle: [],
-        verification: { checks: [] },
-        effects: [],
-        documentation: [],
-        source: { type: "registry" },
-    };
-}
-export function selectBootstrapModules(candidates, explicitPackageName) {
-    const byPackage = new Map(candidates.map((candidate) => [candidate.packageName, candidate]));
-    const roots = explicitPackageName === undefined
-        ? candidates.filter((candidate) => candidate.installClass === "core")
-        : candidates.filter((candidate) => candidate.packageName === explicitPackageName);
-    if (roots.length === 0) {
-        throw new PlatformError(explicitPackageName === undefined
-            ? "REGISTRY_RESPONSE_INVALID"
-            : "PACKAGE_NOT_FOUND", explicitPackageName === undefined
-            ? "Registry discovery returned no installable core ProFlow packages"
-            : `no installable ProFlow package found for ${explicitPackageName}`);
-    }
-    const selected = new Map();
-    const queue = [...roots];
-    while (queue.length > 0) {
-        const candidate = queue.shift();
-        if (!candidate)
-            continue;
-        if (selected.has(candidate.packageName))
-            continue;
-        selected.set(candidate.packageName, candidate);
-        for (const dependencyName of candidate.installRequires) {
-            const dependency = byPackage.get(dependencyName);
-            if (dependency === undefined) {
-                throw new PlatformError("DEPENDENCY_UNRESOLVED", `Registry bootstrap dependency ${dependencyName} required by ${candidate.packageName} was not discovered`);
-            }
-            queue.push(dependency);
-        }
-    }
-    return [...selected.values()]
-        .sort((a, b) => a.packageName.localeCompare(b.packageName))
-        .map(registryCandidateToBootstrapModule);
-}
-export function selectUpgradeBootstrapModules(currentModules, candidates) {
-    const byPackage = new Map(candidates.map((candidate) => [candidate.packageName, candidate]));
-    const targets = [];
-    for (const current of currentModules) {
-        const candidate = byPackage.get(current.packageName);
-        if (candidate === undefined) {
-            throw new PlatformError("PACKAGE_NOT_FOUND", `no installable Registry target found for managed package ${current.packageName}`);
-        }
-        if (candidate.moduleVersion === current.moduleVersion)
-            continue;
-        targets.push(registryCandidateToBootstrapModule(candidate));
-    }
-    return targets;
-}

package/dist/src/install/environment.d.ts

@@ -1,30 +0,0 @@
-import { type NpmCommandRunner } from "../registry/index.ts";
-import { type PackageManagerSelectionSource, type SupportedWorkspacePackageManager } from "./package-manager.ts";
-export declare const PLATFORM_INSTALL_NODE_RANGE = ">=24.19.0";
-export type InstallerPreflightStatus = "READY" | "ACTION_REQUIRED" | "BLOCKED";
-export type InstallerFindingSeverity = "info" | "action" | "error";
-export interface InstallerFinding {
-    code: string;
-    severity: InstallerFindingSeverity;
-    message: string;
-}
-export interface InstallerEnvironmentPreflightResult {
-    contract: "deployment.installer-preflight.v1";
-    ok: boolean;
-    status: InstallerPreflightStatus;
-    workspaceRoot: string;
-    nodeVersion: string;
-    npmVersion?: string;
-    packageManager?: {
-        name: SupportedWorkspacePackageManager;
-        source: PackageManagerSelectionSource;
-        declared?: string;
-        version?: string;
-    };
-    registry?: string;
-    findings: InstallerFinding[];
-}
-export declare function preflightInstallerEnvironment(options: {
-    workspaceRoot: string;
-    runner?: NpmCommandRunner;
-}): Promise<InstallerEnvironmentPreflightResult>;

package/dist/src/install/environment.js

@@ -1,230 +0,0 @@
-import { constants } from "node:fs";
-import { access, readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
-import { PlatformError } from "../errors.js";
-import { versionSatisfies } from "../modules.js";
-import { resolveScopeRegistry, systemNpmRunner, } from "../registry/index.js";
-import { findExecutable, readWorkspacePackageManagerSelection, systemPackageCommandRunner, } from "./package-manager.js";
-export const PLATFORM_INSTALL_NODE_RANGE = ">=24.19.0";
-export async function preflightInstallerEnvironment(options) {
-    const runner = options.runner ?? systemNpmRunner();
-    const findings = [];
-    const nodeVersion = process.versions.node;
-    if (!versionSatisfies(nodeVersion, PLATFORM_INSTALL_NODE_RANGE)) {
-        findings.push({
-            code: "NODE_VERSION_UNSUPPORTED",
-            severity: "error",
-            message: `node ${nodeVersion} does not satisfy ${PLATFORM_INSTALL_NODE_RANGE}`,
-        });
-    }
-    else {
-        findings.push({
-            code: "NODE_VERSION_READY",
-            severity: "info",
-            message: `node ${nodeVersion} satisfies ${PLATFORM_INSTALL_NODE_RANGE}`,
-        });
-    }
-    const workspace = await inspectWorkspace(options.workspaceRoot);
-    findings.push(...workspace.findings);
-    let npmVersion;
-    if (!findExecutable("npm")) {
-        findings.push({
-            code: "NPM_UNAVAILABLE",
-            severity: "error",
-            message: "npm executable is not available on PATH",
-        });
-    }
-    else {
-        try {
-            const npm = await runner.run(["--version"], options.workspaceRoot);
-            npmVersion = npm.stdout.trim();
-            findings.push({
-                code: "NPM_READY",
-                severity: "info",
-                message: `npm ${npmVersion || "<unknown>"} is available`,
-            });
-        }
-        catch (error) {
-            findings.push(platformErrorFinding(error, "NPM_UNAVAILABLE"));
-        }
-    }
-    let packageManager;
-    let packageManagerVersion;
-    try {
-        packageManager = await readWorkspacePackageManagerSelection(options.workspaceRoot);
-        if (!findExecutable(packageManager.name)) {
-            findings.push({
-                code: "PACKAGE_MANAGER_UNAVAILABLE",
-                severity: "action",
-                message: `workspace selects ${packageManager.name}, but that executable is not available on PATH`,
-            });
-        }
-        else if (packageManager.name === "npm" && npmVersion !== undefined) {
-            packageManagerVersion = npmVersion;
-        }
-        else {
-            try {
-                packageManagerVersion = (await systemPackageCommandRunner().run(packageManager.name, ["--version"], options.workspaceRoot)).trim();
-            }
-            catch (error) {
-                findings.push({
-                    code: "PACKAGE_MANAGER_UNAVAILABLE",
-                    severity: "action",
-                    message: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-        if (packageManagerVersion !== undefined) {
-            findings.push({
-                code: "PACKAGE_MANAGER_READY",
-                severity: "info",
-                message: `${packageManager.name} ${packageManagerVersion} is selected via ${packageManager.source}`,
-            });
-        }
-    }
-    catch (error) {
-        if (error instanceof PlatformError) {
-            findings.push({
-                code: error.code,
-                severity: error.code === "PACKAGE_MANAGER_CONFLICT" ? "error" : "action",
-                message: error.message,
-            });
-        }
-        else {
-            findings.push({
-                code: "PACKAGE_MANAGER_UNAVAILABLE",
-                severity: "action",
-                message: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    let registry;
-    if (npmVersion !== undefined) {
-        try {
-            registry = await resolveScopeRegistry(options.workspaceRoot, runner);
-            await runner.run(["ping", "--json", "--prefer-online", `--registry=${registry}`], options.workspaceRoot, 10_000);
-            findings.push({
-                code: "REGISTRY_READY",
-                severity: "info",
-                message: `npm registry is reachable: ${registry}`,
-            });
-        }
-        catch (error) {
-            findings.push(platformErrorFinding(error, "REGISTRY_UNAVAILABLE"));
-        }
-    }
-    const status = aggregateInstallerStatus(findings);
-    return {
-        contract: "deployment.installer-preflight.v1",
-        ok: status === "READY",
-        status,
-        workspaceRoot: options.workspaceRoot,
-        nodeVersion,
-        ...(npmVersion === undefined ? {} : { npmVersion }),
-        ...(packageManager === undefined
-            ? {}
-            : {
-                packageManager: {
-                    ...packageManager,
-                    ...(packageManagerVersion === undefined
-                        ? {}
-                        : { version: packageManagerVersion }),
-                },
-            }),
-        ...(registry === undefined ? {} : { registry }),
-        findings,
-    };
-}
-async function inspectWorkspace(workspaceRoot) {
-    const findings = [];
-    try {
-        const info = await stat(workspaceRoot);
-        if (!info.isDirectory()) {
-            return {
-                findings: [
-                    {
-                        code: "WORKSPACE_INVALID",
-                        severity: "error",
-                        message: `${workspaceRoot} is not a directory`,
-                    },
-                ],
-            };
-        }
-        await access(workspaceRoot, constants.R_OK | constants.W_OK);
-        findings.push({
-            code: "WORKSPACE_WRITABLE",
-            severity: "info",
-            message: `workspace is readable and writable: ${workspaceRoot}`,
-        });
-    }
-    catch {
-        return {
-            findings: [
-                {
-                    code: "WORKSPACE_NOT_WRITABLE",
-                    severity: "error",
-                    message: `workspace is missing or not writable: ${workspaceRoot}`,
-                },
-            ],
-        };
-    }
-    const manifestPath = join(workspaceRoot, "package.json");
-    try {
-        const raw = await readFile(manifestPath, "utf8");
-        const parsed = JSON.parse(raw);
-        if (!isRecord(parsed))
-            throw new Error("package.json root is not an object");
-        const manifest = parsed;
-        findings.push({
-            code: "PACKAGE_JSON_READY",
-            severity: "info",
-            message: "workspace package.json is readable",
-        });
-        return {
-            ...(typeof manifest.packageManager === "string"
-                ? { packageManager: manifest.packageManager }
-                : {}),
-            findings,
-        };
-    }
-    catch (error) {
-        if (isMissingFile(error)) {
-            findings.push({
-                code: "PACKAGE_JSON_CREATABLE",
-                severity: "info",
-                message: "workspace has no package.json; installer may create one before the first package mutation",
-            });
-            return { findings };
-        }
-        findings.push({
-            code: "PACKAGE_JSON_INVALID",
-            severity: "error",
-            message: error instanceof Error ? error.message : String(error),
-        });
-        return { findings };
-    }
-}
-function aggregateInstallerStatus(findings) {
-    if (findings.some((finding) => finding.severity === "error"))
-        return "BLOCKED";
-    if (findings.some((finding) => finding.severity === "action")) {
-        return "ACTION_REQUIRED";
-    }
-    return "READY";
-}
-function platformErrorFinding(error, fallbackCode) {
-    if (error instanceof PlatformError) {
-        return { code: error.code, severity: "error", message: error.message };
-    }
-    return {
-        code: fallbackCode,
-        severity: "error",
-        message: error instanceof Error ? error.message : String(error),
-    };
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isMissingFile(error) {
-    return isRecord(error) && error.code === "ENOENT";
-}

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

@@ -1,6 +0,0 @@
-export { registryCandidateToBootstrapModule, selectBootstrapModules, } from "./bootstrap.ts";
-export type { InstallerEnvironmentPreflightResult, InstallerFinding, InstallerFindingSeverity, InstallerPreflightStatus, } from "./environment.ts";
-export { PLATFORM_INSTALL_NODE_RANGE, preflightInstallerEnvironment, } from "./environment.ts";
-export type { GenerateInstallDocInput, InstallDocInput, } from "./install.ts";
-export { generateInstallDoc, renderInstallDoc } from "./install.ts";
-export type { SupportedWorkspacePackageManager, WorkspacePackageManagerSelection, } from "./package-manager.ts";

package/dist/src/install/index.js

@@ -1,3 +0,0 @@
-export { registryCandidateToBootstrapModule, selectBootstrapModules, } from "./bootstrap.js";
-export { PLATFORM_INSTALL_NODE_RANGE, preflightInstallerEnvironment, } from "./environment.js";
-export { generateInstallDoc, renderInstallDoc } from "./install.js";

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

@@ -1,19 +0,0 @@
-import type { ResolvedModule } from "../contracts.ts";
-import type { WorkspacePaths } from "../paths.ts";
-export interface InstallDocInput {
-    modules: readonly ResolvedModule[];
-    config?: Record<string, Record<string, string>>;
-    now?: Date;
-}
-export interface GenerateInstallDocInput extends InstallDocInput {
-    paths: WorkspacePaths;
-}
-/**
- * Renders the generated INSTALL document from the real selected module set:
- * module refs/versions, machine/runtime requirements, secret-redacted config
- * slots, external resources, effects, human actions, and the verification plan.
- * No raw secret value may survive — config values are redacted by key, and the
- * whole document is deep-redacted against every known raw secret value.
- */
-export declare function renderInstallDoc(input: InstallDocInput): string;
-export declare function generateInstallDoc(input: GenerateInstallDocInput): Promise<string>;

package/dist/src/install/install.js

@@ -1,172 +0,0 @@
-import { writeInstallDoc } from "../persistence/index.js";
-import { resolveModuleConfig } from "../preflight/index.js";
-import { redactDeep, redactSecretValues } from "../security/index.js";
-function compareRef(a, b) {
-    return a < b ? -1 : a > b ? 1 : 0;
-}
-function requirementLine(moduleRef, requirement) {
-    switch (requirement.kind) {
-        case "runtime":
-            return `- \`${moduleRef}\`: runtime \`${requirement.runtime}\` ${requirement.versionRange}`;
-        case "executable":
-            return `- \`${moduleRef}\`: executable \`${requirement.command}\`${requirement.versionRange !== undefined
-                ? ` ${requirement.versionRange}`
-                : ""}`;
-        case "filesystem":
-            return `- \`${moduleRef}\`: filesystem \`${requirement.path}\` (${requirement.access})`;
-        case "port":
-            return `- \`${moduleRef}\`: port ${requirement.port}/${requirement.protocol}`;
-        case "network":
-            return `- \`${moduleRef}\`: network \`${requirement.url}\``;
-        case "module-contract":
-            return `- \`${moduleRef}\`: module-contract \`${requirement.contractRef}\` ${requirement.versionRange}`;
-        case "human":
-            return `- \`${moduleRef}\`: human — ${requirement.action}`;
-    }
-}
-function collectRawSecrets(modules, config) {
-    const secrets = [];
-    for (const module of modules) {
-        const resolved = resolveModuleConfig(module, config?.[module.moduleRef]);
-        const sensitiveKeys = new Set(module.configSlots
-            .filter((slot) => slot.sensitive === true && slot.type !== "secretRef")
-            .map((slot) => slot.key));
-        for (const [key, value] of Object.entries(resolved.values)) {
-            if (sensitiveKeys.has(key) && value.length > 0)
-                secrets.push(value);
-        }
-    }
-    return secrets;
-}
-/**
- * Renders the generated INSTALL document from the real selected module set:
- * module refs/versions, machine/runtime requirements, secret-redacted config
- * slots, external resources, effects, human actions, and the verification plan.
- * No raw secret value may survive — config values are redacted by key, and the
- * whole document is deep-redacted against every known raw secret value.
- */
-export function renderInstallDoc(input) {
-    const generatedAt = (input.now ?? new Date()).toISOString();
-    const modules = [...input.modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
-    const lines = [];
-    lines.push("# ProFlow Deployment — Generated INSTALL");
-    lines.push("");
-    lines.push(`> Generated at ${generatedAt}. Regenerated by \`platform manifest\`.`);
-    lines.push("");
-    lines.push("## Selected Module Set");
-    lines.push("");
-    for (const module of modules) {
-        lines.push(`- \`${module.moduleRef}\` (\`${module.packageName}@${module.moduleVersion}\`, kind: \`${module.kind}\`)`);
-    }
-    lines.push("");
-    lines.push("## Requirements");
-    lines.push("");
-    for (const module of modules) {
-        for (const requirement of module.requirements) {
-            lines.push(requirementLine(module.moduleRef, requirement));
-        }
-    }
-    lines.push("");
-    lines.push("## Config Slots");
-    lines.push("");
-    for (const module of modules) {
-        const resolved = resolveModuleConfig(module, input.config?.[module.moduleRef]);
-        const values = redactSecretValues(resolved.values, resolved.secretRefs);
-        for (const slot of module.configSlots) {
-            const value = values[slot.key];
-            const suffix = value !== undefined ? ` = \`${value}\`` : "";
-            const required = slot.required ? " (required)" : "";
-            lines.push(`- \`${module.moduleRef}\`.\`${slot.key}\` [${slot.type}]${required}${suffix}`);
-        }
-    }
-    lines.push("");
-    const external = modules.filter((module) => module.kind === "external-resource");
-    if (external.length > 0) {
-        lines.push("## External Resources");
-        lines.push("");
-        for (const module of external) {
-            lines.push(`- \`${module.moduleRef}\` (\`${module.packageName}@${module.moduleVersion}\`)`);
-        }
-        lines.push("");
-    }
-    lines.push("## Effects");
-    lines.push("");
-    for (const module of modules) {
-        for (const effect of module.effects) {
-            lines.push(`- \`${module.moduleRef}\`: [${effect.kind}] ${effect.description}`);
-        }
-    }
-    lines.push("");
-    const humanActions = modules.flatMap((module) => module.requirements
-        .filter((requirement) => requirement.kind === "human")
-        .map((requirement) => ({
-        moduleRef: module.moduleRef,
-        action: requirement.action,
-    })));
-    if (humanActions.length > 0) {
-        lines.push("## Human Actions");
-        lines.push("");
-        for (const action of humanActions) {
-            lines.push(`- \`${action.moduleRef}\`: ${action.action}`);
-        }
-        lines.push("");
-    }
-    const missingRequiredConfig = {};
-    for (const module of modules) {
-        const resolved = resolveModuleConfig(module, input.config?.[module.moduleRef]);
-        for (const slot of module.configSlots) {
-            if (!slot.required || resolved.values[slot.key] !== undefined)
-                continue;
-            const placeholder = slot.type === "secretRef"
-                ? "secret://provider/name"
-                : slot.type === "url"
-                    ? "https://example.invalid"
-                    : slot.type === "path"
-                        ? "/absolute/path"
-                        : slot.type === "moduleRef"
-                            ? "module-ref"
-                            : "<value>";
-            const moduleConfig = missingRequiredConfig[module.moduleRef] ?? {};
-            moduleConfig[slot.key] = placeholder;
-            missingRequiredConfig[module.moduleRef] = moduleConfig;
-        }
-    }
-    lines.push("## Configure Before Start");
-    lines.push("");
-    if (Object.keys(missingRequiredConfig).length === 0) {
-        lines.push("No required configuration is currently missing. Re-run `platform preflight --intent start` before starting to confirm current runtime readiness.");
-    }
-    else {
-        lines.push("Create a JSON config file (for example `./proflow-config.json`) using the required missing slots below. Replace placeholders with real environment-specific values. `secretRef` values must remain opaque references such as `secret://provider/name`; do not place raw secrets in this file.");
-        lines.push("");
-        lines.push("```json");
-        lines.push(JSON.stringify({ modules: missingRequiredConfig }, null, 2));
-        lines.push("```");
-        lines.push("");
-        lines.push("Apply and re-check the configuration:");
-        lines.push("");
-        lines.push("1. `platform plan --intent configure --config ./proflow-config.json`");
-        lines.push("2. Copy the returned `planRef`.");
-        lines.push("3. `platform apply <planRef>`");
-        lines.push("4. `platform preflight --intent start`");
-        lines.push("5. Resolve any remaining human or external-resource actions reported by preflight, then run the same preflight command again until the Platform reports the expected readiness state.");
-    }
-    lines.push("");
-    lines.push("## Verification Plan");
-    lines.push("");
-    for (const module of modules) {
-        for (const verificationCheck of module.verification.checks) {
-            lines.push(`- \`${module.moduleRef}\`: \`${verificationCheck.id}\` (${verificationCheck.lifecycle}) — ${verificationCheck.description}`);
-        }
-    }
-    const content = `${lines.join("\n")}\n`;
-    // defense-in-depth: deep-redact every raw secret value wherever it appears
-    const rawSecrets = collectRawSecrets(modules, input.config);
-    const redacted = redactDeep(content, rawSecrets);
-    return typeof redacted === "string" ? redacted : content;
-}
-export async function generateInstallDoc(input) {
-    const content = renderInstallDoc(input);
-    await writeInstallDoc(input.paths, content);
-    return content;
-}

package/dist/src/lifecycle/service-process.d.ts

@@ -1,11 +0,0 @@
-import { type ModuleOperationResult } from "@tomflow/proflow-module-contract";
-import type { ResolvedModule } from "../contracts.ts";
-import type { WorkspacePaths } from "../paths.ts";
-export interface ManagedServiceInvocation {
-    result: ModuleOperationResult;
-    observedEffects: string[];
-}
-export declare function managedServiceStatus(paths: WorkspacePaths, module: ResolvedModule): Promise<ManagedServiceInvocation>;
-export declare function startManagedService(paths: WorkspacePaths, module: ResolvedModule, rawBinding: unknown): Promise<ManagedServiceInvocation>;
-export declare function stopManagedService(paths: WorkspacePaths, module: ResolvedModule): Promise<ManagedServiceInvocation>;
-export declare function restartManagedService(paths: WorkspacePaths, module: ResolvedModule, binding: unknown): Promise<ManagedServiceInvocation>;