@tomflow/proflow-platform-cli 0.1.14 → 0.1.16

package/dist/src/preflight/requirements.js

@@ -1,231 +0,0 @@
-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, humanVerifiedModuleRefs = new Set()) {
-    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, humanVerifiedModuleRefs));
-        }
-    }
-    return results;
-}
-export async function probeRequirement(moduleRef, requirement, modules, humanVerifiedModuleRefs = new Set()) {
-    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 humanVerifiedModuleRefs.has(moduleRef)
-                ? {
-                    moduleRef,
-                    requirement,
-                    status: "PASS",
-                    message: `human prerequisite verified for ${moduleRef}`,
-                }
-                : {
-                    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

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

package/dist/src/ready/index.js

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

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

@@ -1,40 +0,0 @@
-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

@@ -1,201 +0,0 @@
-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/security/index.d.ts

@@ -1,3 +0,0 @@
-export type { WorkspaceLockHandle } from "./lock.ts";
-export { acquireWorkspaceLock, readWorkspaceLock, workspaceLockPath, } from "./lock.ts";
-export { redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, } from "./redact.ts";

package/dist/src/security/index.js

@@ -1,2 +0,0 @@
-export { acquireWorkspaceLock, readWorkspaceLock, workspaceLockPath, } from "./lock.js";
-export { redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, } from "./redact.js";

package/dist/src/security/lock.d.ts

@@ -1,9 +0,0 @@
-import type { LockRecord } from "../contracts.ts";
-import type { WorkspacePaths } from "../paths.ts";
-export interface WorkspaceLockHandle {
-    record: LockRecord;
-    release(): Promise<void>;
-}
-export declare function workspaceLockPath(paths: WorkspacePaths): string;
-export declare function readWorkspaceLock(paths: WorkspacePaths): Promise<LockRecord | undefined>;
-export declare function acquireWorkspaceLock(paths: WorkspacePaths, planRef: string): Promise<WorkspaceLockHandle>;

package/dist/src/security/lock.js

@@ -1,127 +0,0 @@
-import { createHash } from "node:crypto";
-import { mkdir, open, readFile, realpath, unlink, } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { PlatformError } from "../errors.js";
-import { isLockRecord } from "../persistence/guards.js";
-export function workspaceLockPath(paths) {
-    return join(paths.runtime, "apply.lock");
-}
-function errorHasCode(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
-async function computeFingerprint(root) {
-    let canonical = root;
-    try {
-        canonical = await realpath(root);
-    }
-    catch {
-        canonical = resolve(root);
-    }
-    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
-}
-export async function readWorkspaceLock(paths) {
-    let raw;
-    try {
-        raw = await readFile(workspaceLockPath(paths), "utf8");
-    }
-    catch {
-        return undefined;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-    return isLockRecord(parsed) ? parsed : undefined;
-}
-function lockedError(existing) {
-    const details = existing === undefined
-        ? "existing lock is unreadable"
-        : `pid=${existing.pid} planRef=${existing.planRef} since=${existing.createdAt} fingerprint=${existing.workspaceFingerprint}`;
-    return new PlatformError("WORKSPACE_LOCKED", `workspace apply already in progress (${details})`);
-}
-function isProvablyDeadPid(pid) {
-    try {
-        process.kill(pid, 0);
-        return false;
-    }
-    catch (error) {
-        return errorHasCode(error, "ESRCH");
-    }
-}
-async function reclaimProvablyStaleLock(paths, expectedFingerprint) {
-    const existing = await readWorkspaceLock(paths);
-    if (existing === undefined ||
-        existing.workspaceFingerprint !== expectedFingerprint ||
-        !isProvablyDeadPid(existing.pid)) {
-        return false;
-    }
-    try {
-        await unlink(workspaceLockPath(paths));
-        return true;
-    }
-    catch (error) {
-        if (errorHasCode(error, "ENOENT"))
-            return true;
-        throw error;
-    }
-}
-// v1 single-process exclusive lock: O_EXCL create, no distributed coordination,
-// and no reclaim of a lock that cannot be proven stale.
-export async function acquireWorkspaceLock(paths, planRef) {
-    const file = workspaceLockPath(paths);
-    await mkdir(paths.runtime, { recursive: true });
-    const record = {
-        pid: process.pid,
-        createdAt: new Date().toISOString(),
-        planRef,
-        workspaceFingerprint: await computeFingerprint(paths.root),
-    };
-    let handle;
-    try {
-        handle = await open(file, "wx", 0o644);
-    }
-    catch (error) {
-        if (!errorHasCode(error, "EEXIST"))
-            throw error;
-        if (await reclaimProvablyStaleLock(paths, record.workspaceFingerprint)) {
-            try {
-                handle = await open(file, "wx", 0o644);
-            }
-            catch (retryError) {
-                if (errorHasCode(retryError, "EEXIST")) {
-                    throw lockedError(await readWorkspaceLock(paths));
-                }
-                throw retryError;
-            }
-        }
-        else {
-            throw lockedError(await readWorkspaceLock(paths));
-        }
-    }
-    try {
-        await handle.writeFile(`${JSON.stringify(record, null, 2)}\n`, {
-            encoding: "utf8",
-        });
-    }
-    finally {
-        await handle.close();
-    }
-    return {
-        record,
-        async release() {
-            try {
-                await unlink(file);
-            }
-            catch (error) {
-                if (!errorHasCode(error, "ENOENT"))
-                    throw error;
-            }
-        },
-    };
-}

package/dist/src/security/redact.d.ts

@@ -1,6 +0,0 @@
-import type { DeploymentPlan } from "../contracts.ts";
-export declare const SECRET_REDACTED = "<redacted>";
-export declare function isValidSecretRef(value: string): boolean;
-export declare function redactSecretValues(values: Record<string, string>, _secretRefs: readonly string[]): Record<string, string>;
-export declare function redactDeep(value: unknown, rawSecrets: readonly string[]): unknown;
-export declare function redactPlanSecrets(plan: DeploymentPlan): DeploymentPlan;

package/dist/src/security/redact.js

@@ -1,48 +0,0 @@
-export const SECRET_REDACTED = "<redacted>";
-const SECRET_REF_PATTERN = /^(?:secret:\/\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*|credential-ref:[A-Za-z0-9._-]+)$/;
-export function isValidSecretRef(value) {
-    return SECRET_REF_PATTERN.test(value);
-}
-// secretRef slot values are opaque reference identities (e.g.
-// `secret://model-provider/default`, `credential-ref:local-platform`), NOT raw
-// tokens/passwords. They are safe to persist and display verbatim, so this
-// function preserves them instead of substituting a redaction marker. Raw
-// secret leak scanning is `redactDeep`'s job, not this function's.
-export function redactSecretValues(values, _secretRefs) {
-    return { ...values };
-}
-function redactString(value, secrets) {
-    let out = value;
-    for (const secret of secrets) {
-        if (secret.length === 0)
-            continue;
-        out = out.split(secret).join(SECRET_REDACTED);
-    }
-    return out;
-}
-// Deep-structural redaction: returns a clone with every occurrence of a raw
-// secret value replaced, in any nested string position. This is the leak-scan
-// layer for genuine raw secret values (test sentinels or future non-secretRef
-// sensitive values). secretRef references are NOT raw secrets and must never be
-// passed here as raw secrets.
-export function redactDeep(value, rawSecrets) {
-    const secrets = rawSecrets.filter((secret) => secret.length > 0);
-    if (typeof value === "string")
-        return redactString(value, secrets);
-    if (Array.isArray(value))
-        return value.map((item) => redactDeep(item, secrets));
-    if (typeof value === "object" && value !== null) {
-        const out = {};
-        for (const [key, item] of Object.entries(value)) {
-            out[key] = redactDeep(item, secrets);
-        }
-        return out;
-    }
-    return value;
-}
-// Plans are public DTOs whose secretRef config values are opaque reference
-// identities, not raw secrets. This returns a non-mutating clone that preserves
-// secretRef references verbatim (no `<redacted>` substitution).
-export function redactPlanSecrets(plan) {
-    return structuredClone(plan);
-}

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

@@ -1,2 +0,0 @@
-export type { VerifyResult } from "./verify.ts";
-export { configFingerprint, verificationRefOf, verifyModule, verifyModules, } from "./verify.ts";

package/dist/src/verification/index.js

@@ -1 +0,0 @@
-export { configFingerprint, verificationRefOf, verifyModule, verifyModules, } from "./verify.js";