open-local-audit 0.66.0 → 0.67.0

package/dist/workflow-state.js

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { workflowConfigFingerprint } from "./workflow-config.js";
+import { writeWorkflowOutputFile } from "./workflow-output.js";
+const stateKeys = [
+    "version",
+    "configFingerprint",
+    "phase",
+    "currentStage",
+    "checkpointHash",
+    "startedAt",
+    "updatedAt",
+    "summary"
+];
+const workflowStageNames = ["discovery", "shortlist", "review", "packaging"];
+const workflowStageStatuses = ["success", "failed", "skipped", "not-run"];
+const workflowPackageStatuses = ["packaged", "skipped", "failed"];
+const workflowManagedPathKeys = [
+    "leadsCsv",
+    "discoverySummaryJson",
+    "shortlistCsv",
+    "shortlistSummaryJson",
+    "reviewSummaryJson",
+    "workflowSummaryJson",
+    "reportsDir",
+    "packagesDir"
+];
+export function workflowStatePath(config) {
+    return join(config.outDir, "workflow-state.json");
+}
+export function createWorkflowState(config, summary, timestamp = new Date().toISOString()) {
+    return {
+        version: 1,
+        configFingerprint: workflowConfigFingerprint(config),
+        phase: "running",
+        currentStage: null,
+        checkpointHash: null,
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        summary
+    };
+}
+export function transitionWorkflowState(state, transition, timestamp = new Date().toISOString()) {
+    return {
+        ...state,
+        ...transition,
+        updatedAt: timestamp
+    };
+}
+export function parseWorkflowState(value, config) {
+    if (!isWorkflowState(value, config)) {
+        return { kind: "invalid", message: "Workflow state is invalid" };
+    }
+    return { kind: "valid", state: value };
+}
+export async function readWorkflowState(config) {
+    const path = workflowStatePath(config);
+    let content;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            return { kind: "invalid", message: "Workflow state is invalid" };
+        }
+        content = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingPath(error)) {
+            return { kind: "missing" };
+        }
+        return { kind: "invalid", message: "Workflow state is invalid" };
+    }
+    try {
+        return parseWorkflowState(JSON.parse(content), config);
+    }
+    catch {
+        return { kind: "invalid", message: "Workflow state is invalid" };
+    }
+}
+export async function writeWorkflowState(config, state) {
+    const parsed = parseWorkflowState(state, config);
+    if (parsed.kind !== "valid") {
+        throw new Error(parsed.kind === "invalid" ? parsed.message : "Workflow state is missing");
+    }
+    const path = workflowStatePath(config);
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            throw new Error("Workflow state must be a regular file");
+        }
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            throw error;
+        }
+    }
+    await writeWorkflowOutputFile(path, `${JSON.stringify(parsed.state, null, 2)}\n`, {
+        managedOutputRoot: config.outDir
+    });
+}
+export async function hashWorkflowCheckpoint(config) {
+    const checkpointPath = join(config.outDir, "workflow-checkpoint.json");
+    try {
+        const info = await lstat(checkpointPath);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            throw new Error("Workflow checkpoint must be a regular file");
+        }
+        return createHash("sha256").update(await readFile(checkpointPath)).digest("hex");
+    }
+    catch (error) {
+        if (isMissingPath(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function isMissingPath(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function isHash(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function isTimestamp(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+function isCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isStageName(value) {
+    return typeof value === "string" && workflowStageNames.includes(value);
+}
+function isStageSummary(value, countKeys) {
+    return (isRecord(value) &&
+        hasOnlyKeys(value, ["status", ...countKeys]) &&
+        typeof value.status === "string" &&
+        workflowStageStatuses.includes(value.status) &&
+        countKeys.every((key) => value[key] === undefined || isCount(value[key])));
+}
+function isPackageEntry(value) {
+    if (!isRecord(value) || typeof value.leadKey !== "string" || typeof value.companyName !== "string") {
+        return false;
+    }
+    if (value.status === "packaged") {
+        return hasExactKeys(value, ["leadKey", "companyName", "status", "outDir"]) && typeof value.outDir === "string";
+    }
+    if (value.status === "skipped") {
+        return hasExactKeys(value, ["leadKey", "companyName", "status"]);
+    }
+    return (value.status === "failed" &&
+        hasExactKeys(value, ["leadKey", "companyName", "status", "error"]) &&
+        typeof value.error === "string");
+}
+function isWorkflowSummary(value) {
+    if (!isRecord(value) ||
+        !hasOnlyKeys(value, ["version", "status", "stages", "outputs", "discoveredLeads", "selectedLeads", "packages", "error"]) ||
+        value.version !== 1 ||
+        (value.status !== "success" && value.status !== "failed") ||
+        !isRecord(value.stages) ||
+        !hasExactKeys(value.stages, workflowStageNames) ||
+        !isRecord(value.outputs) ||
+        !hasExactKeys(value.outputs, workflowManagedPathKeys) ||
+        !isCount(value.discoveredLeads) ||
+        !isCount(value.selectedLeads) ||
+        !isRecord(value.packages) ||
+        !hasExactKeys(value.packages, ["packaged", "skipped", "failed", "entries"])) {
+        return false;
+    }
+    const stages = value.stages;
+    const outputs = value.outputs;
+    const packages = value.packages;
+    const error = value.error;
+    return (isStageSummary(stages.discovery, ["totalCandidates", "suppressedCandidates", "audited"]) &&
+        isStageSummary(stages.shortlist, ["totalRows", "suppressedRows", "filteredRows", "selected"]) &&
+        isStageSummary(stages.review, ["totalRows", "reviewedRows", "actionableLeads", "staleRows", "invalidReviewedAtRows", "unreviewedRows"]) &&
+        isStageSummary(stages.packaging, ["packaged", "skipped", "failed"]) &&
+        workflowManagedPathKeys.every((key) => typeof outputs[key] === "string") &&
+        isCount(packages.packaged) &&
+        isCount(packages.skipped) &&
+        isCount(packages.failed) &&
+        Array.isArray(packages.entries) &&
+        packages.entries.every(isPackageEntry) &&
+        (error === undefined || (isRecord(error) && hasExactKeys(error, ["stage", "message"]) && isStageName(error.stage) && typeof error.message === "string")));
+}
+function isWorkflowState(value, config) {
+    if (!isRecord(value) || !hasExactKeys(value, stateKeys)) {
+        return false;
+    }
+    const structuralValidity = value.version === 1 &&
+        isHash(value.configFingerprint) &&
+        (value.phase === "running" || value.phase === "failed" || value.phase === "completed") &&
+        (value.currentStage === null || isStageName(value.currentStage)) &&
+        (value.checkpointHash === null || isHash(value.checkpointHash)) &&
+        isTimestamp(value.startedAt) &&
+        isTimestamp(value.updatedAt);
+    if (!structuralValidity || !isWorkflowSummary(value.summary)) {
+        return false;
+    }
+    const summary = value.summary;
+    const phase = value.phase;
+    const currentStage = value.currentStage;
+    if (config &&
+        (value.configFingerprint !== workflowConfigFingerprint(config) ||
+            !workflowManagedPathKeys.every((key) => summary.outputs[key] === config.paths[key]))) {
+        return false;
+    }
+    if (phase === "completed") {
+        return (summary.status === "success" &&
+            summary.error === undefined &&
+            currentStage === null &&
+            hasValidStageProgress(summary, phase, currentStage, config));
+    }
+    if (phase === "failed") {
+        return (summary.status === "failed" &&
+            summary.error !== undefined &&
+            currentStage === summary.error.stage &&
+            hasValidStageProgress(summary, phase, currentStage, config));
+    }
+    return (summary.status === "success" &&
+        summary.error === undefined &&
+        hasValidStageProgress(summary, phase, currentStage, config));
+}
+function hasValidStageProgress(summary, phase, currentStage, config) {
+    const stageStatuses = workflowStageNames.map((name) => [name, summary.stages[name].status]);
+    const enabled = (stage) => stage === "discovery" ||
+        stage === "shortlist" ||
+        (stage === "review"
+            ? config === undefined || config.review !== undefined
+            : config === undefined || config.packageReports);
+    const isOptional = (stage) => stage === "review" || stage === "packaging";
+    if (stageStatuses.some(([stage, status]) => {
+        if (!isOptional(stage)) {
+            return status === "skipped";
+        }
+        if (config) {
+            return enabled(stage) ? status === "skipped" : status !== "skipped";
+        }
+        return false;
+    })) {
+        return false;
+    }
+    const activeStages = stageStatuses.filter(([stage, status]) => !(isOptional(stage) && status === "skipped"));
+    if (phase === "completed") {
+        return activeStages.every(([, status]) => status === "success");
+    }
+    if (phase === "running") {
+        if (activeStages.some(([, status]) => status !== "success" && status !== "not-run")) {
+            return false;
+        }
+        let foundNotRun = false;
+        for (const [stage, status] of activeStages) {
+            if (status === "not-run") {
+                foundNotRun = true;
+            }
+            else if (foundNotRun || status !== "success") {
+                return false;
+            }
+            if (currentStage === stage && status !== "not-run") {
+                return false;
+            }
+        }
+        return currentStage === null || (enabled(currentStage) && summary.stages[currentStage].status === "not-run");
+    }
+    if (!currentStage || summary.stages[currentStage].status !== "failed" || !enabled(currentStage)) {
+        return false;
+    }
+    let foundFailedStage = false;
+    for (const [stage, status] of activeStages) {
+        if (stage === currentStage) {
+            foundFailedStage = true;
+            if (status !== "failed") {
+                return false;
+            }
+            continue;
+        }
+        if (!foundFailedStage ? status !== "success" : status !== "not-run") {
+            return false;
+        }
+    }
+    return foundFailedStage;
+}
+//# sourceMappingURL=workflow-state.js.map

package/dist/workflow-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-state.js","sourceRoot":"","sources":["../src/workflow-state.ts"],"names":[],"mappings":"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"}

package/dist/workflow-status.d.ts

@@ -0,0 +1,26 @@
+import { type WorkflowStageName, type WorkflowSummary } from "./workflow.js";
+export type WorkflowStatusReportStatus = "not-started" | "running-or-interrupted" | "failed" | "completed" | "invalid";
+export type WorkflowArtifactValidation = "valid" | "invalid" | "not-applicable";
+export type WorkflowStatusNextActionKind = "run" | "resume" | "confirm-active-process" | "none" | "inspect";
+export interface WorkflowStatusNextAction {
+    kind: WorkflowStatusNextActionKind;
+    argv: string[] | null;
+    message: string;
+}
+export interface WorkflowStatusReport {
+    version: 1;
+    status: WorkflowStatusReportStatus;
+    currentStage: WorkflowStageName | null;
+    lastSuccessfulStage: WorkflowStageName | null;
+    resumeAvailable: boolean;
+    updatedAt: string | null;
+    stages: WorkflowSummary["stages"];
+    artifactValidation: WorkflowArtifactValidation;
+    nextAction: WorkflowStatusNextAction;
+    error: {
+        message: string;
+    } | null;
+}
+export declare function runWorkflowStatus(configPath: string): Promise<WorkflowStatusReport>;
+export declare function renderWorkflowStatusTerminal(report: WorkflowStatusReport, configPath: string): string;
+export declare function renderWorkflowStatusJson(report: WorkflowStatusReport): string;

package/dist/workflow-status.js

@@ -0,0 +1,154 @@
+import { readWorkflowConfig } from "./workflow-config.js";
+import { readWorkflowState } from "./workflow-state.js";
+import { inspectWorkflowCheckpoint } from "./workflow.js";
+const stageNames = ["discovery", "shortlist", "review", "packaging"];
+function initialStages(config) {
+    return {
+        discovery: { status: "not-run" },
+        shortlist: { status: "not-run" },
+        review: { status: config.review ? "not-run" : "skipped" },
+        packaging: { status: config.packageReports ? "not-run" : "skipped" }
+    };
+}
+function lastSuccessfulStage(stages) {
+    let last = null;
+    for (const stage of stageNames) {
+        if (stages[stage].status === "success") {
+            last = stage;
+        }
+    }
+    return last;
+}
+function nextIncompleteStage(stages) {
+    return stageNames.find((stage) => stages[stage].status !== "success" && stages[stage].status !== "skipped") ?? null;
+}
+function runAction(configPath) {
+    return {
+        kind: "run",
+        argv: ["workflow", "--config", configPath],
+        message: "Run the workflow from the beginning."
+    };
+}
+function resumeAction(configPath) {
+    return {
+        kind: "resume",
+        argv: ["workflow", "--config", configPath, "--resume"],
+        message: "Resume from the latest validated checkpoint."
+    };
+}
+function runningAction(configPath, resumeAvailable) {
+    return {
+        kind: "confirm-active-process",
+        argv: resumeAvailable ? ["workflow", "--config", configPath, "--resume"] : ["workflow", "--config", configPath],
+        message: "Confirm that no workflow process is active before running this command."
+    };
+}
+function invalidReport(stages, artifactValidation, message) {
+    return {
+        version: 1,
+        status: "invalid",
+        currentStage: null,
+        lastSuccessfulStage: lastSuccessfulStage(stages),
+        resumeAvailable: false,
+        updatedAt: null,
+        stages,
+        artifactValidation,
+        nextAction: { kind: "inspect", argv: null, message: "Inspect workflow state and checkpoint files before running." },
+        error: { message }
+    };
+}
+function hasCompletedStages(stages) {
+    return stageNames.every((stage) => stages[stage].status === "success" || stages[stage].status === "skipped");
+}
+function checkpointIsUsable(inspection, hash) {
+    return inspection.kind === "valid" && hash !== null && inspection.checkpointHash === hash;
+}
+export async function runWorkflowStatus(configPath) {
+    const config = await readWorkflowConfig(configPath);
+    const [stateResult, checkpoint] = await Promise.all([readWorkflowState(config), inspectWorkflowCheckpoint(config)]);
+    if (stateResult.kind === "invalid") {
+        return invalidReport(initialStages(config), "invalid", "Workflow state is invalid.");
+    }
+    if (stateResult.kind === "missing") {
+        if (checkpoint.kind === "missing") {
+            const stages = initialStages(config);
+            return {
+                version: 1,
+                status: "not-started",
+                currentStage: null,
+                lastSuccessfulStage: null,
+                resumeAvailable: false,
+                updatedAt: null,
+                stages,
+                artifactValidation: "not-applicable",
+                nextAction: runAction(configPath),
+                error: null
+            };
+        }
+        if (checkpoint.kind === "invalid") {
+            return invalidReport(initialStages(config), "invalid", "Workflow checkpoint is invalid.");
+        }
+        const completed = hasCompletedStages(checkpoint.summary.stages);
+        return {
+            version: 1,
+            status: completed ? "completed" : "running-or-interrupted",
+            currentStage: completed ? null : nextIncompleteStage(checkpoint.summary.stages),
+            lastSuccessfulStage: lastSuccessfulStage(checkpoint.summary.stages),
+            resumeAvailable: !completed,
+            updatedAt: null,
+            stages: checkpoint.summary.stages,
+            artifactValidation: "valid",
+            nextAction: completed
+                ? { kind: "none", argv: null, message: "Workflow completion is recorded." }
+                : runningAction(configPath, true),
+            error: null
+        };
+    }
+    const state = stateResult.state;
+    const stages = state.summary.stages;
+    if (state.checkpointHash !== null && !checkpointIsUsable(checkpoint, state.checkpointHash)) {
+        return invalidReport(stages, "invalid", "Workflow checkpoint is missing, invalid, or does not match the state.");
+    }
+    if (state.phase === "completed" && !checkpointIsUsable(checkpoint, state.checkpointHash)) {
+        return invalidReport(stages, "invalid", "Completed workflow state requires a matching checkpoint.");
+    }
+    const resumeAvailable = checkpointIsUsable(checkpoint, state.checkpointHash);
+    const status = state.phase === "running" ? "running-or-interrupted" : state.phase === "failed" ? "failed" : "completed";
+    const nextAction = state.phase === "running"
+        ? runningAction(configPath, resumeAvailable)
+        : state.phase === "failed"
+            ? resumeAvailable
+                ? resumeAction(configPath)
+                : runAction(configPath)
+            : { kind: "none", argv: null, message: "Workflow completion is recorded." };
+    return {
+        version: 1,
+        status,
+        currentStage: state.currentStage,
+        lastSuccessfulStage: lastSuccessfulStage(stages),
+        resumeAvailable,
+        updatedAt: state.updatedAt,
+        stages,
+        artifactValidation: resumeAvailable ? "valid" : "not-applicable",
+        nextAction,
+        error: state.phase === "failed" && state.currentStage ? { message: `Workflow failed during ${state.currentStage}` } : null
+    };
+}
+export function renderWorkflowStatusTerminal(report, configPath) {
+    const command = report.nextAction.argv === null ? [] : [`Command: ${report.nextAction.argv.join(" ")}`];
+    const error = report.error === null ? [] : [`Error: ${report.error.message}`];
+    return `${[
+        `Workflow status: ${report.status.toUpperCase().replaceAll("-", " ")}`,
+        `Config: ${configPath}`,
+        `Current stage: ${report.currentStage ?? "none"}`,
+        `Last successful stage: ${report.lastSuccessfulStage ?? "none"}`,
+        `Artifact validation: ${report.artifactValidation.toUpperCase().replaceAll("-", " ")}`,
+        `Next action: ${report.nextAction.kind.toUpperCase().replaceAll("-", " ")}`,
+        ...command,
+        ...error
+    ].join("\n")}\n`;
+}
+export function renderWorkflowStatusJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+//# sourceMappingURL=workflow-status.js.map

package/dist/workflow-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-status.js","sourceRoot":"","sources":["../src/workflow-status.ts"],"names":[],"mappings":"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"}

package/dist/workflow.d.ts

@@ -5,10 +5,12 @@ import { type ShortlistRunOptions } from "./shortlist-runner.js";
 import type { ShortlistResult } from "./shortlist.js";
 import { resolveGoogleMapsApiKey } from "./secrets.js";
 import { readWorkflowConfig, type ResolvedWorkflowConfig, type WorkflowManagedPaths } from "./workflow-config.js";
+import { writeWorkflowState } from "./workflow-state.js";
 export type WorkflowStatus = "success" | "failed";
 export type WorkflowStageStatus = "success" | "failed" | "skipped" | "not-run";
 export type WorkflowStageName = "discovery" | "shortlist" | "review" | "packaging";
 export type WorkflowPackageStatus = "packaged" | "skipped" | "failed";
+export { workflowConfigFingerprint } from "./workflow-config.js";
 export interface WorkflowDiscoveryStageSummary {
     status: WorkflowStageStatus;
     totalCandidates?: number;
@@ -75,14 +77,28 @@ export interface WorkflowDependencies {
     summarizeReviewCsvFile: typeof summarizeReviewCsvFile;
     packageReport: (options: Parameters<typeof packageReport>[0]) => Promise<ReportPackResult>;
     resolveGoogleMapsApiKey: typeof resolveGoogleMapsApiKey;
+    now: () => Date;
+    writeWorkflowState: typeof writeWorkflowState;
 }
 export interface WorkflowRunOptions {
     resume?: boolean;
 }
+export type WorkflowCheckpointInspection = {
+    kind: "missing";
+} | {
+    kind: "invalid";
+    message: string;
+} | {
+    kind: "valid";
+    summary: WorkflowSummary;
+    checkpointPath: string;
+    checkpointHash: string;
+};
 export declare class WorkflowRunError extends Error {
     readonly summary: WorkflowSummary;
     constructor(summary: WorkflowSummary);
 }
 export declare function safeLeadSlug(leadKey: string, companyName: string): string;
+export declare function inspectWorkflowCheckpoint(config: ResolvedWorkflowConfig): Promise<WorkflowCheckpointInspection>;
 export declare function runWorkflow(configPath: string, dependencies?: Partial<WorkflowDependencies>, options?: WorkflowRunOptions): Promise<WorkflowSummary>;
 export declare function runResolvedWorkflow(config: ResolvedWorkflowConfig, dependencies?: Partial<WorkflowDependencies>, options?: WorkflowRunOptions): Promise<WorkflowSummary>;