@tomflow/proflow-platform-cli 0.1.0

package/dist/src/preflight/requirements.d.ts

@@ -0,0 +1,11 @@
+import type { ModuleRequirement } from "@tomflow/proflow-module-contract";
+import type { ResolvedModule } from "../contracts.ts";
+export type ProbeStatus = "PASS" | "FAIL" | "ACTION_REQUIRED";
+export interface RequirementProbe {
+    moduleRef: string;
+    requirement: ModuleRequirement;
+    status: ProbeStatus;
+    message: string;
+}
+export declare function probeAllRequirements(modules: readonly ResolvedModule[]): Promise<RequirementProbe[]>;
+export declare function probeRequirement(moduleRef: string, requirement: ModuleRequirement, modules: readonly ResolvedModule[]): Promise<RequirementProbe>;

package/dist/src/preflight/requirements.js

@@ -0,0 +1,224 @@
+import { accessSync, constants } from "node:fs";
+import { connect } from "node:net";
+import { join } from "node:path";
+import { versionSatisfies } from "../modules.js";
+function compareRef(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export async function probeAllRequirements(modules) {
+    const sorted = [...modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
+    const results = [];
+    for (const module of sorted) {
+        for (const requirement of module.requirements) {
+            results.push(await probeRequirement(module.moduleRef, requirement, modules));
+        }
+    }
+    return results;
+}
+export async function probeRequirement(moduleRef, requirement, modules) {
+    switch (requirement.kind) {
+        case "runtime":
+            return probeRuntime(moduleRef, requirement);
+        case "executable":
+            return probeExecutable(moduleRef, requirement);
+        case "filesystem":
+            return probeFilesystem(moduleRef, requirement);
+        case "port":
+            return probePort(moduleRef, requirement);
+        case "network":
+            return probeNetwork(moduleRef, requirement);
+        case "module-contract":
+            return probeModuleContract(moduleRef, requirement, modules);
+        case "human":
+            return {
+                moduleRef,
+                requirement,
+                status: "ACTION_REQUIRED",
+                message: requirement.action,
+            };
+    }
+}
+function probeRuntime(moduleRef, requirement) {
+    if (requirement.runtime !== "node") {
+        return {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `${requirement.runtime} runtime availability is not probed by platform-cli`,
+        };
+    }
+    const version = process.version.startsWith("v")
+        ? process.version.slice(1)
+        : process.version;
+    const satisfied = versionSatisfies(version, requirement.versionRange);
+    return satisfied
+        ? {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `node ${version} satisfies ${requirement.versionRange}`,
+        }
+        : {
+            moduleRef,
+            requirement,
+            status: "FAIL",
+            message: `node ${version} does not satisfy ${requirement.versionRange}`,
+        };
+}
+function probeExecutable(moduleRef, requirement) {
+    const found = findOnPath(requirement.command);
+    return found
+        ? {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `executable ${requirement.command} found on PATH`,
+        }
+        : {
+            moduleRef,
+            requirement,
+            status: "FAIL",
+            message: `executable ${requirement.command} not found on PATH`,
+        };
+}
+// Bounded by construction: a synchronous scan of the finite PATH directory
+// list. It spawns no subprocess, so it cannot hang.
+function findOnPath(command) {
+    const path = process.env.PATH ?? "";
+    const directories = path.split(":").filter((entry) => entry !== "");
+    for (const directory of directories) {
+        const candidate = join(directory, command);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return true;
+        }
+        catch {
+            // keep searching
+        }
+    }
+    return false;
+}
+function probeFilesystem(moduleRef, requirement) {
+    const mode = requirement.access === "read"
+        ? constants.R_OK
+        : requirement.access === "write"
+            ? constants.W_OK
+            : constants.R_OK | constants.W_OK;
+    try {
+        accessSync(requirement.path, mode);
+        return {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `path ${requirement.path} is ${requirement.access} accessible`,
+        };
+    }
+    catch {
+        return {
+            moduleRef,
+            requirement,
+            status: "FAIL",
+            message: `path ${requirement.path} is not ${requirement.access} accessible`,
+        };
+    }
+}
+async function probePort(moduleRef, requirement) {
+    if (requirement.protocol === "udp") {
+        return {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `udp port ${requirement.port} is not probed by platform-cli`,
+        };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const socket = connect({ host: "127.0.0.1", port: requirement.port });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({
+                moduleRef,
+                requirement,
+                status: "FAIL",
+                message: `port ${requirement.port} probe timed out`,
+            });
+        }, 2_000);
+        socket.once("connect", () => {
+            clearTimeout(timer);
+            finish({
+                moduleRef,
+                requirement,
+                status: "FAIL",
+                message: `port ${requirement.port} is already in use`,
+            });
+        });
+        socket.once("error", () => {
+            clearTimeout(timer);
+            finish({
+                moduleRef,
+                requirement,
+                status: "PASS",
+                message: `port ${requirement.port} is available`,
+            });
+        });
+    });
+}
+async function probeNetwork(moduleRef, requirement) {
+    try {
+        const response = await fetch(requirement.url, {
+            method: "GET",
+            signal: AbortSignal.timeout(3_000),
+        });
+        return {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `network ${requirement.url} reachable (HTTP ${response.status})`,
+        };
+    }
+    catch {
+        return {
+            moduleRef,
+            requirement,
+            status: "FAIL",
+            message: `network ${requirement.url} unreachable`,
+        };
+    }
+}
+function probeModuleContract(moduleRef, requirement, modules) {
+    const providers = modules.filter((module) => module.provides.some((provide) => provide.contractRef === requirement.contractRef));
+    const matching = providers.filter((module) => module.provides.some((provide) => provide.contractRef === requirement.contractRef &&
+        versionSatisfies(provide.version, requirement.versionRange)));
+    if (matching.length > 0) {
+        const refs = matching
+            .map((module) => module.moduleRef)
+            .sort(compareRef)
+            .join(", ");
+        return {
+            moduleRef,
+            requirement,
+            status: "PASS",
+            message: `module-contract ${requirement.contractRef} satisfied by ${refs}`,
+        };
+    }
+    if (providers.length > 0) {
+        return {
+            moduleRef,
+            requirement,
+            status: "FAIL",
+            message: `module-contract ${requirement.contractRef} providers incompatible with ${requirement.versionRange}`,
+        };
+    }
+    return {
+        moduleRef,
+        requirement,
+        status: "FAIL",
+        message: `module-contract ${requirement.contractRef} has no provider`,
+    };
+}

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

@@ -0,0 +1,2 @@
+export type { BlockingAction, PlatformReadyInput, PlatformReadyResult, ReadyFinding, ReadyFindingCode, ReadyFindingSeverity, ResourceReality, } from "./ready.ts";
+export { assessPlatformReady } from "./ready.ts";

package/dist/src/ready/index.js

@@ -0,0 +1 @@
+export { assessPlatformReady } from "./ready.js";

package/dist/src/ready/ready.d.ts

@@ -0,0 +1,40 @@
+import type { PlatformState, ResolvedModule, VerificationRecord } from "../contracts.ts";
+import type { LifecycleRunResult } from "../lifecycle/index.ts";
+export type ReadyFindingSeverity = "blocking" | "degraded";
+export type ReadyFindingCode = "DEPENDENCY_UNRESOLVED" | "DEPENDENCY_INCOMPATIBLE" | "DEPENDENCY_CYCLE" | "MODULE_REF_UNRESOLVED" | "CONFIG_MISSING" | "RUNTIME_STATUS_UNAVAILABLE" | "RUNTIME_NOT_READY" | "RUNTIME_ACTION_REQUIRED" | "RUNTIME_CHECK_FAIL" | "RUNTIME_CHECK_WARN" | "VERIFICATION_MISSING" | "VERIFICATION_STALE" | "VERIFICATION_FAIL" | "BLOCKING_ACTION";
+export interface ReadyFinding {
+    severity: ReadyFindingSeverity;
+    code: ReadyFindingCode;
+    moduleRef?: string;
+    message: string;
+}
+export interface BlockingAction {
+    moduleRef?: string;
+    action: string;
+    description?: string;
+}
+export interface ResourceReality {
+    moduleRef: string;
+    resourceIdentity?: string;
+    resourceVersion?: string;
+}
+export interface PlatformReadyInput {
+    modules: readonly ResolvedModule[];
+    status: readonly LifecycleRunResult[];
+    verification: readonly VerificationRecord[];
+    config?: Record<string, Record<string, string>>;
+    blockingActions?: readonly BlockingAction[];
+    resources?: readonly ResourceReality[];
+}
+export interface PlatformReadyResult {
+    state: PlatformState;
+    findings: ReadyFinding[];
+}
+/**
+ * Aggregates current reality into a single PlatformState. READY is derived only
+ * from live runtime status, current-version verification records, resolved
+ * dependencies, required config, and the absence of blocking human actions.
+ * Persisted PASS history, a bare SUCCEEDED operation, or a schema-valid but
+ * non-success structured result can never fabricate READY on their own.
+ */
+export declare function assessPlatformReady(input: PlatformReadyInput): PlatformReadyResult;

package/dist/src/ready/ready.js

@@ -0,0 +1,201 @@
+import { PlatformError } from "../errors.js";
+import { buildDependencyGraph, ModuleRefUnresolvedError, } from "../graph/index.js";
+import { checkConfigReadiness } from "../preflight/index.js";
+function compareRef(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function toDependencyCode(code) {
+    switch (code) {
+        case "DEPENDENCY_UNRESOLVED":
+        case "DEPENDENCY_INCOMPATIBLE":
+        case "DEPENDENCY_CYCLE":
+            return code;
+        default:
+            return undefined;
+    }
+}
+function isHumanAction(code) {
+    return code === "RUNTIME_ACTION_REQUIRED" || code === "BLOCKING_ACTION";
+}
+function deriveState(findings) {
+    let hardFailure = false;
+    let humanAction = false;
+    let degraded = false;
+    for (const finding of findings) {
+        if (finding.severity === "degraded") {
+            degraded = true;
+            continue;
+        }
+        if (isHumanAction(finding.code))
+            humanAction = true;
+        else
+            hardFailure = true;
+    }
+    if (hardFailure)
+        return "NOT_READY";
+    if (humanAction)
+        return "ACTION_REQUIRED";
+    if (degraded)
+        return "DEGRADED";
+    return "READY";
+}
+/**
+ * Aggregates current reality into a single PlatformState. READY is derived only
+ * from live runtime status, current-version verification records, resolved
+ * dependencies, required config, and the absence of blocking human actions.
+ * Persisted PASS history, a bare SUCCEEDED operation, or a schema-valid but
+ * non-success structured result can never fabricate READY on their own.
+ */
+export function assessPlatformReady(input) {
+    const findings = [];
+    const modules = [...input.modules].sort((a, b) => compareRef(a.moduleRef, b.moduleRef));
+    // logical dependencies, cross-module compatibility, and moduleRef bindings
+    try {
+        buildDependencyGraph(modules, input.config === undefined ? {} : { config: input.config });
+    }
+    catch (error) {
+        if (error instanceof ModuleRefUnresolvedError) {
+            findings.push({
+                severity: "blocking",
+                code: "MODULE_REF_UNRESOLVED",
+                moduleRef: error.from,
+                message: error.message,
+            });
+        }
+        else if (error instanceof PlatformError) {
+            const code = toDependencyCode(error.code);
+            if (code === undefined)
+                throw error;
+            findings.push({ severity: "blocking", code, message: error.message });
+        }
+        else {
+            throw error;
+        }
+    }
+    // required config ready
+    for (const finding of checkConfigReadiness(modules, input.config)) {
+        findings.push({
+            severity: "blocking",
+            code: "CONFIG_MISSING",
+            ...(finding.moduleRef !== undefined
+                ? { moduleRef: finding.moduleRef }
+                : {}),
+            message: finding.message,
+        });
+    }
+    // required runtimes current READY (live status, never persisted)
+    const statusByRef = new Map(input.status.map((run) => [run.moduleRef, run]));
+    for (const module of modules) {
+        if (!module.lifecycle.includes("status"))
+            continue;
+        const run = statusByRef.get(module.moduleRef);
+        if (run === undefined ||
+            run.status !== "EXECUTED" ||
+            run.result === undefined) {
+            findings.push({
+                severity: "blocking",
+                code: "RUNTIME_STATUS_UNAVAILABLE",
+                moduleRef: module.moduleRef,
+                message: `no live status observed for ${module.moduleRef}`,
+            });
+            continue;
+        }
+        const result = run.result;
+        if (result.status === "ACTION_REQUIRED") {
+            const action = result.actionRequired;
+            findings.push({
+                severity: "blocking",
+                code: "RUNTIME_ACTION_REQUIRED",
+                moduleRef: module.moduleRef,
+                message: action !== undefined
+                    ? `${module.moduleRef} requires action "${action.action}"`
+                    : `${module.moduleRef} requires an unspecified human action`,
+            });
+        }
+        else if (result.status !== "SUCCEEDED") {
+            findings.push({
+                severity: "blocking",
+                code: "RUNTIME_NOT_READY",
+                moduleRef: module.moduleRef,
+                message: `runtime ${module.moduleRef} is ${result.status.toLowerCase()}`,
+            });
+        }
+        for (const runtimeCheck of result.checks ?? []) {
+            if (runtimeCheck.status === "FAIL") {
+                findings.push({
+                    severity: "blocking",
+                    code: "RUNTIME_CHECK_FAIL",
+                    moduleRef: module.moduleRef,
+                    message: `runtime check ${runtimeCheck.id} failed for ${module.moduleRef}`,
+                });
+            }
+            else if (runtimeCheck.status === "WARN") {
+                findings.push({
+                    severity: "degraded",
+                    code: "RUNTIME_CHECK_WARN",
+                    moduleRef: module.moduleRef,
+                    message: `runtime check ${runtimeCheck.id} warns for ${module.moduleRef}`,
+                });
+            }
+        }
+    }
+    // current-version verification PASS against current resource reality
+    const recordsByRef = new Map();
+    for (const record of input.verification) {
+        const list = recordsByRef.get(record.moduleRef) ?? [];
+        list.push(record);
+        recordsByRef.set(record.moduleRef, list);
+    }
+    const resourcesByRef = new Map((input.resources ?? []).map((resource) => [resource.moduleRef, resource]));
+    for (const module of modules) {
+        if (!module.lifecycle.includes("verify"))
+            continue;
+        const records = recordsByRef.get(module.moduleRef) ?? [];
+        const reality = resourcesByRef.get(module.moduleRef);
+        const current = records.filter((record) => {
+            if (record.moduleVersion !== module.moduleVersion)
+                return false;
+            if (reality === undefined)
+                return true;
+            if (reality.resourceIdentity !== undefined &&
+                record.resourceIdentity !== reality.resourceIdentity) {
+                return false;
+            }
+            if (reality.resourceVersion !== undefined &&
+                record.resourceVersion !== reality.resourceVersion) {
+                return false;
+            }
+            return true;
+        });
+        const latestCurrent = current[current.length - 1];
+        if (latestCurrent === undefined) {
+            const code = records.length === 0 ? "VERIFICATION_MISSING" : "VERIFICATION_STALE";
+            findings.push({
+                severity: "blocking",
+                code,
+                moduleRef: module.moduleRef,
+                message: `no current-version verification record for ${module.moduleRef}@${module.moduleVersion}`,
+            });
+        }
+        else if (latestCurrent.result !== "PASS") {
+            findings.push({
+                severity: "blocking",
+                code: "VERIFICATION_FAIL",
+                moduleRef: module.moduleRef,
+                message: `current-version verification FAIL for ${module.moduleRef}@${module.moduleVersion}`,
+            });
+        }
+    }
+    // blocking ACTION_REQUIRED count must be zero
+    for (const action of input.blockingActions ?? []) {
+        findings.push({
+            severity: "blocking",
+            code: "BLOCKING_ACTION",
+            ...(action.moduleRef !== undefined
+                ? { moduleRef: action.moduleRef }
+                : {}),
+            message: action.description ?? action.action,
+        });
+    }
+    return { state: deriveState(findings), findings };
+}

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

@@ -0,0 +1,2 @@
+export type { NpmCommandResult, NpmCommandRunner, RegistryDiscoveryResult, RegistryModuleCandidate, RegistryRejectedPackage, } from "./npm-registry.ts";
+export { discoverRegistryInstallClosure, discoverRegistryModules, loadRegistryModuleDescriptor, PRO_FLOW_PACKAGE_PREFIX, PRO_FLOW_SCOPE, resolveScopeRegistry, systemNpmRunner, } from "./npm-registry.ts";

package/dist/src/registry/index.js

@@ -0,0 +1 @@
+export { discoverRegistryInstallClosure, discoverRegistryModules, loadRegistryModuleDescriptor, PRO_FLOW_PACKAGE_PREFIX, PRO_FLOW_SCOPE, resolveScopeRegistry, systemNpmRunner, } from "./npm-registry.js";

package/dist/src/registry/npm-registry.d.ts

@@ -0,0 +1,51 @@
+import { type ModuleDescriptor, type ModuleInstallClass } from "@tomflow/proflow-module-contract";
+export declare const PRO_FLOW_SCOPE = "@tomflow";
+export declare const PRO_FLOW_PACKAGE_PREFIX = "@tomflow/proflow-";
+export interface NpmCommandResult {
+    stdout: string;
+    stderr: string;
+}
+export interface NpmCommandRunner {
+    run(args: readonly string[], cwd: string): Promise<NpmCommandResult>;
+}
+export interface RegistryModuleCandidate {
+    packageName: string;
+    moduleVersion: string;
+    description?: string;
+    installClass: ModuleInstallClass;
+    descriptor: string;
+    manifest: "./proflow.module.json";
+    installRequires: string[];
+    nodeVersionRange?: string;
+    registry: string;
+}
+export interface RegistryRejectedPackage {
+    packageName: string;
+    moduleVersion?: string;
+    reason: "NOT_PROFLOW_MODULE" | "DEPRECATED" | "NODE_INCOMPATIBLE" | "METADATA_INVALID";
+    message: string;
+}
+export interface RegistryDiscoveryResult {
+    registry: string;
+    candidates: RegistryModuleCandidate[];
+    rejected: RegistryRejectedPackage[];
+}
+export declare function systemNpmRunner(): NpmCommandRunner;
+export declare function resolveScopeRegistry(workspaceRoot: string, runner?: NpmCommandRunner): Promise<string>;
+export declare function discoverRegistryModules(options: {
+    workspaceRoot: string;
+    packageName?: string;
+    runner?: NpmCommandRunner;
+    nodeVersion?: string;
+}): Promise<RegistryDiscoveryResult>;
+export declare function loadRegistryModuleDescriptor(options: {
+    workspaceRoot: string;
+    candidate: RegistryModuleCandidate;
+    runner?: NpmCommandRunner;
+}): Promise<ModuleDescriptor>;
+export declare function discoverRegistryInstallClosure(options: {
+    workspaceRoot: string;
+    packageName: string;
+    runner?: NpmCommandRunner;
+    nodeVersion?: string;
+}): Promise<RegistryDiscoveryResult>;