voratiq 0.1.0-beta.0

package/dist/render/utils/errors.js

@@ -0,0 +1,14 @@
+import { formatErrorMessage } from "../../utils/output.js";
+import { renderTranscript } from "./transcript.js";
+export function renderCliError(error) {
+    const sections = [];
+    const primary = [formatErrorMessage(error.headline)];
+    if (error.detailLines.length > 0) {
+        primary.push("", ...error.detailLines);
+    }
+    sections.push(primary);
+    if (error.hintLines.length > 0) {
+        sections.push([...error.hintLines]);
+    }
+    return renderTranscript({ sections });
+}

package/dist/render/utils/records.d.ts

@@ -0,0 +1 @@
+export declare function formatRunTimestamp(isoTimestamp: string): string;

package/dist/render/utils/records.js

@@ -0,0 +1,32 @@
+const RUN_TIME_ZONE = "America/Los_Angeles";
+const RUN_TIMESTAMP_FORMAT = new Intl.DateTimeFormat("en-CA", {
+    timeZone: RUN_TIME_ZONE,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+});
+export function formatRunTimestamp(isoTimestamp) {
+    try {
+        const date = new Date(isoTimestamp);
+        if (Number.isNaN(date.getTime())) {
+            return isoTimestamp;
+        }
+        const parts = RUN_TIMESTAMP_FORMAT.formatToParts(date);
+        const lookup = (type) => parts.find((part) => part.type === type)?.value;
+        const year = lookup("year");
+        const month = lookup("month");
+        const day = lookup("day");
+        const hour = lookup("hour");
+        const minute = lookup("minute");
+        if (!year || !month || !day || !hour || !minute) {
+            return isoTimestamp;
+        }
+        return `${year}-${month}-${day} ${hour}:${minute}`;
+    }
+    catch {
+        return isoTimestamp;
+    }
+}

package/dist/render/utils/runs.d.ts

@@ -0,0 +1,16 @@
+import type { RunStatus } from "../../status/index.js";
+export interface RunDisplayInfo {
+    runId: string;
+    status?: RunStatus;
+    specPath?: string;
+    workspacePath?: string;
+    createdAt?: string;
+    baseRevisionSha?: string;
+}
+type RunMetadataRow = {
+    label: string;
+    value: string;
+};
+export declare function getRunMetadata(info: RunDisplayInfo): RunMetadataRow[];
+export declare function buildRunMetadataSection(info: RunDisplayInfo): string[];
+export {};

package/dist/render/utils/runs.js

@@ -0,0 +1,50 @@
+import { getRunStatusStyle } from "../../status/colors.js";
+import { colorize } from "../../utils/colors.js";
+import { formatRunBadge } from "./badges.js";
+import { renderTable } from "./table.js";
+export function getRunMetadata(info) {
+    const detailRows = [
+        { label: "Created", value: info.createdAt },
+        { label: "Spec", value: info.specPath },
+        { label: "Workspace", value: info.workspacePath },
+        {
+            label: "Base Revision",
+            value: info.baseRevisionSha
+                ? info.baseRevisionSha.slice(0, 8)
+                : undefined,
+        },
+    ];
+    return detailRows.filter((row) => typeof row.value === "string" && row.value.length > 0);
+}
+export function buildRunMetadataSection(info) {
+    const lines = [];
+    const badge = formatRunBadge(info.runId);
+    if (info.status) {
+        const statusStyle = getRunStatusStyle(info.status);
+        lines.push(`${badge} ${colorize(info.status.toUpperCase(), statusStyle.cli)}`);
+    }
+    else {
+        lines.push(badge);
+    }
+    const detailRows = getRunMetadata(info);
+    if (detailRows.length > 0) {
+        const tableLines = renderTable({
+            columns: [
+                {
+                    header: "FIELD",
+                    accessor: (row) => row.label,
+                },
+                {
+                    header: "VALUE",
+                    accessor: (row) => row.value ?? "—",
+                },
+            ],
+            rows: detailRows,
+        });
+        const [, ...bodyLines] = tableLines;
+        if (bodyLines.length > 0) {
+            lines.push("", ...bodyLines);
+        }
+    }
+    return lines;
+}

package/dist/render/utils/table.d.ts

@@ -0,0 +1,12 @@
+interface TableColumn<Row> {
+    header: string;
+    accessor: (row: Row) => string;
+    align?: "left" | "right";
+}
+interface RenderTableOptions<Row> {
+    columns: readonly TableColumn<Row>[];
+    rows: readonly Row[];
+    columnGap?: string;
+}
+export declare function renderTable<Row>({ columns, rows, columnGap, }: RenderTableOptions<Row>): string[];
+export {};

package/dist/render/utils/table.js

@@ -0,0 +1,32 @@
+const ESCAPE_CHARACTER = String.fromCharCode(27);
+const ANSI_PATTERN = new RegExp(`${ESCAPE_CHARACTER}\\[[0-9;]*m`, "g");
+function visibleLength(value) {
+    return value.replace(ANSI_PATTERN, "").length;
+}
+function padValue(value, width, align = "left") {
+    const length = visibleLength(value);
+    if (length >= width) {
+        return value;
+    }
+    const padding = " ".repeat(width - length);
+    return align === "right" ? padding + value : value + padding;
+}
+export function renderTable({ columns, rows, columnGap = "  ", }) {
+    if (columns.length === 0) {
+        return [];
+    }
+    const widths = columns.map((column) => {
+        const headerLength = visibleLength(column.header);
+        const rowLengths = rows.map((row) => visibleLength(column.accessor(row)));
+        return Math.max(headerLength, ...rowLengths);
+    });
+    const headerLine = columns
+        .map((column, index) => padValue(column.header, widths[index], column.align))
+        .join(columnGap);
+    const lines = [headerLine];
+    for (const row of rows) {
+        const values = columns.map((column, index) => padValue(column.accessor(row), widths[index], column.align));
+        lines.push(values.join(columnGap));
+    }
+    return lines;
+}

package/dist/render/utils/transcript.d.ts

@@ -0,0 +1,14 @@
+export interface TranscriptMetadataEntry {
+    label: string;
+    value?: string | null;
+}
+export interface TranscriptHintOptions {
+    message: string;
+    requireRerunSuffix?: boolean;
+}
+export interface TranscriptOptions {
+    metadata?: TranscriptMetadataEntry[];
+    sections?: string[][];
+    hint?: TranscriptHintOptions;
+}
+export declare function renderTranscript({ metadata, sections, hint, }: TranscriptOptions): string;

package/dist/render/utils/transcript.js

@@ -0,0 +1,44 @@
+export function renderTranscript({ metadata = [], sections = [], hint, }) {
+    const lines = [];
+    const metadataLines = metadata
+        .filter((entry) => {
+        return typeof entry.value === "string" && entry.value.length > 0;
+    })
+        .map((entry) => `${entry.label}: ${entry.value}`);
+    if (metadataLines.length > 0) {
+        lines.push(...metadataLines, "");
+    }
+    sections.forEach((block, index) => {
+        if (block.length === 0) {
+            return;
+        }
+        lines.push(...block);
+        if (index < sections.length - 1) {
+            lines.push("");
+        }
+    });
+    if (hint) {
+        const resolvedHint = resolveHint(hint);
+        if (sections.length > 0 || metadataLines.length > 0) {
+            lines.push("");
+        }
+        lines.push(resolvedHint);
+    }
+    return trimTrailingBlankLines(lines).join("\n");
+}
+function withRerunHint(message) {
+    return message.endsWith(" and rerun.") ? message : `${message} and rerun.`;
+}
+function resolveHint(hint) {
+    if (hint.requireRerunSuffix) {
+        return withRerunHint(hint.message);
+    }
+    return hint.message;
+}
+function trimTrailingBlankLines(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1]?.trim() === "") {
+        end -= 1;
+    }
+    return lines.slice(0, end);
+}

package/dist/status/colors.d.ts

@@ -0,0 +1,10 @@
+import type { EvalStatus } from "../configs/evals/types.js";
+import type { TerminalColor } from "../utils/colors.js";
+import type { AgentStatus, RunStatus } from "./index.js";
+interface StatusStyle {
+    cli: TerminalColor;
+}
+export declare function getAgentStatusStyle(status: AgentStatus): StatusStyle;
+export declare function getEvalStatusStyle(status: EvalStatus): StatusStyle;
+export declare function getRunStatusStyle(status: RunStatus): StatusStyle;
+export {};

package/dist/status/colors.js

@@ -0,0 +1,33 @@
+const agentStatusStyles = {
+    succeeded: { cli: "green" },
+    failed: { cli: "red" },
+    errored: { cli: "red" },
+    skipped: { cli: "yellow" },
+    aborted: { cli: "yellow" },
+    running: { cli: "cyan" },
+    queued: { cli: "gray" },
+};
+const evalStatusStyles = {
+    succeeded: { cli: "green" },
+    failed: { cli: "red" },
+    errored: { cli: "red" },
+    skipped: { cli: "gray" },
+};
+const runStatusStyles = {
+    succeeded: { cli: "green" },
+    failed: { cli: "red" },
+    errored: { cli: "red" },
+    aborted: { cli: "yellow" },
+    pruned: { cli: "gray" },
+    running: { cli: "cyan" },
+    queued: { cli: "gray" },
+};
+export function getAgentStatusStyle(status) {
+    return agentStatusStyles[status];
+}
+export function getEvalStatusStyle(status) {
+    return evalStatusStyles[status];
+}
+export function getRunStatusStyle(status) {
+    return runStatusStyles[status];
+}

package/dist/status/index.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export declare const RUN_STATUS_VALUES: readonly ["queued", "running", "succeeded", "failed", "errored", "aborted", "pruned"];
+export type RunStatus = (typeof RUN_STATUS_VALUES)[number];
+export declare const AGENT_STATUS_VALUES: readonly ["queued", "running", "succeeded", "failed", "errored", "skipped", "aborted"];
+export type AgentStatus = (typeof AGENT_STATUS_VALUES)[number];
+export declare const EVAL_STATUS_VALUES: readonly ["succeeded", "failed", "errored", "skipped"];
+export type EvalStatus = (typeof EVAL_STATUS_VALUES)[number];
+export declare const APPLY_STATUS_VALUES: readonly ["succeeded", "failed"];
+export type ApplyStatus = (typeof APPLY_STATUS_VALUES)[number];
+export declare const runStatusSchema: z.ZodEnum<{
+    queued: "queued";
+    running: "running";
+    succeeded: "succeeded";
+    failed: "failed";
+    errored: "errored";
+    aborted: "aborted";
+    pruned: "pruned";
+}>;
+export declare const agentStatusSchema: z.ZodEnum<{
+    queued: "queued";
+    running: "running";
+    succeeded: "succeeded";
+    failed: "failed";
+    errored: "errored";
+    aborted: "aborted";
+    skipped: "skipped";
+}>;
+export declare const evalStatusSchema: z.ZodEnum<{
+    succeeded: "succeeded";
+    failed: "failed";
+    errored: "errored";
+    skipped: "skipped";
+}>;
+export declare const applyStatusEnum: z.ZodEnum<{
+    succeeded: "succeeded";
+    failed: "failed";
+}>;

package/dist/status/index.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export const RUN_STATUS_VALUES = [
+    "queued",
+    "running",
+    "succeeded",
+    "failed",
+    "errored",
+    "aborted",
+    "pruned",
+];
+export const AGENT_STATUS_VALUES = [
+    "queued",
+    "running",
+    "succeeded",
+    "failed",
+    "errored",
+    "skipped",
+    "aborted",
+];
+export const EVAL_STATUS_VALUES = [
+    "succeeded",
+    "failed",
+    "errored",
+    "skipped",
+];
+export const APPLY_STATUS_VALUES = ["succeeded", "failed"];
+export const runStatusSchema = z.enum(RUN_STATUS_VALUES);
+export const agentStatusSchema = z.enum(AGENT_STATUS_VALUES);
+export const evalStatusSchema = z.enum(EVAL_STATUS_VALUES);
+export const applyStatusEnum = z.enum(APPLY_STATUS_VALUES);

package/dist/testing/test-hooks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Explicit opt-in for test-only global hooks. Calling this keeps production
+ * bundles clean while giving Jest helpers a single switch to flip.
+ */
+export declare function enableTestHookRegistration(): void;
+export declare function isTestHookRegistrationEnabled(): boolean;
+export declare function assertTestHookRegistrationEnabled(feature: string): void;

package/dist/testing/test-hooks.js

@@ -0,0 +1,16 @@
+let testHookRegistrationEnabled = false;
+/**
+ * Explicit opt-in for test-only global hooks. Calling this keeps production
+ * bundles clean while giving Jest helpers a single switch to flip.
+ */
+export function enableTestHookRegistration() {
+    testHookRegistrationEnabled = true;
+}
+export function isTestHookRegistrationEnabled() {
+    return testHookRegistrationEnabled;
+}
+export function assertTestHookRegistrationEnabled(feature) {
+    if (!testHookRegistrationEnabled) {
+        throw new Error(`Test hooks for ${feature} are unavailable. Call enableTestHookRegistration() before accessing ${feature} helpers.`);
+    }
+}

package/dist/utils/binaries.d.ts

@@ -0,0 +1 @@
+export declare function detectBinary(command: string): string | undefined;

package/dist/utils/binaries.js

@@ -0,0 +1,13 @@
+import { spawnSync } from "node:child_process";
+export function detectBinary(command) {
+    const result = spawnSync("bash", ["-lc", `command -v ${command}`], {
+        encoding: "utf8",
+    });
+    if (result.status === 0) {
+        const path = result.stdout.trim();
+        if (path.length > 0) {
+            return path;
+        }
+    }
+    return undefined;
+}

package/dist/utils/cli-root.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveCliAssetRoot(): string;
+export declare function getCliAssetPath(...segments: string[]): string;

package/dist/utils/cli-root.js

@@ -0,0 +1,42 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve as resolveNative } from "node:path";
+import { fileURLToPath } from "node:url";
+const PACKAGE_JSON_FILENAME = "package.json";
+const CLI_ROOT_ERROR_MESSAGE = "Unable to locate Voratiq CLI root directory. Ensure the Voratiq binary is running from its install directory.";
+let cachedCliRoot;
+export function resolveCliAssetRoot() {
+    if (cachedCliRoot) {
+        return cachedCliRoot;
+    }
+    const helperDirectory = fileURLToPath(new URL(".", import.meta.url));
+    const derivedRoot = ascendToPackageRoot(helperDirectory);
+    if (derivedRoot) {
+        cachedCliRoot = derivedRoot;
+        return cachedCliRoot;
+    }
+    throw buildResolutionError(`Attempted discovery starting from "${helperDirectory}".`);
+}
+export function getCliAssetPath(...segments) {
+    const root = resolveCliAssetRoot();
+    return resolveNative(root, ...segments);
+}
+function ascendToPackageRoot(start) {
+    let current = start;
+    while (true) {
+        if (isValidCliRoot(current)) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+function isValidCliRoot(candidate) {
+    const packagePath = resolveNative(candidate, PACKAGE_JSON_FILENAME);
+    return existsSync(packagePath);
+}
+function buildResolutionError(detail) {
+    return new Error(`${CLI_ROOT_ERROR_MESSAGE} ${detail}`);
+}

package/dist/utils/colors.d.ts

@@ -0,0 +1,2 @@
+export type TerminalColor = "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "gray";
+export declare function colorize(text: string, color: TerminalColor): string;

package/dist/utils/colors.js

@@ -0,0 +1,23 @@
+import chalk from "chalk";
+export function colorize(text, color) {
+    if (!text) {
+        return text;
+    }
+    switch (color) {
+        case "red":
+            return chalk.red(text);
+        case "green":
+            return chalk.green(text);
+        case "yellow":
+            return chalk.yellow(text);
+        case "blue":
+            return chalk.blue(text);
+        case "magenta":
+            return chalk.magenta(text);
+        case "cyan":
+            return chalk.cyan(text);
+        case "gray":
+        default:
+            return chalk.gray(text);
+    }
+}

package/dist/utils/diff.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalize git shortstat output before persisting.
+ * Trims surrounding whitespace and guards against oversized strings.
+ */
+export declare function normalizeDiffStatistics(value?: string | null): string | undefined;
+/**
+ * Produce a compact representation such as `3f +12/-2` for the CHANGES column.
+ */
+export declare function formatCompactDiffStatistics(value?: string | null): string | undefined;

package/dist/utils/diff.js

@@ -0,0 +1,61 @@
+const MAX_DIFF_STATISTICS_LENGTH = 256;
+const FILES_CHANGED_PATTERN = /(\d+)\s+file/;
+const INSERTIONS_PATTERN = /(\d+)\s+insertion/;
+const DELETIONS_PATTERN = /(\d+)\s+deletion/;
+/**
+ * Normalize git shortstat output before persisting.
+ * Trims surrounding whitespace and guards against oversized strings.
+ */
+export function normalizeDiffStatistics(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    if (trimmed.length > MAX_DIFF_STATISTICS_LENGTH) {
+        return trimmed.slice(0, MAX_DIFF_STATISTICS_LENGTH);
+    }
+    return trimmed;
+}
+function extractStat(pattern, input) {
+    const match = input.match(pattern);
+    if (!match) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(match[1], 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+/**
+ * Produce a compact representation such as `3f +12/-2` for the CHANGES column.
+ */
+export function formatCompactDiffStatistics(value) {
+    const normalized = normalizeDiffStatistics(value);
+    if (!normalized) {
+        return undefined;
+    }
+    const files = extractStat(FILES_CHANGED_PATTERN, normalized);
+    const insertions = extractStat(INSERTIONS_PATTERN, normalized);
+    const deletions = extractStat(DELETIONS_PATTERN, normalized);
+    if (files === undefined &&
+        insertions === undefined &&
+        deletions === undefined) {
+        return normalized;
+    }
+    const parts = [];
+    if (files !== undefined) {
+        parts.push(`${files}f`);
+    }
+    const delta = [];
+    if (insertions !== undefined) {
+        delta.push(`+${insertions}`);
+    }
+    if (deletions !== undefined) {
+        delta.push(`-${deletions}`);
+    }
+    if (delta.length > 0) {
+        parts.push(delta.join("/"));
+    }
+    return parts.join(" ") || normalized;
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,10 @@
+export interface EnvironmentFilterOptions {
+    allow?: readonly string[];
+    prefixes?: readonly string[];
+}
+export interface ComposeEnvironmentOptions extends EnvironmentFilterOptions {
+    base?: NodeJS.ProcessEnv;
+    includeBase?: boolean;
+}
+export declare function composeRestrictedEnvironment(overrides?: NodeJS.ProcessEnv, options?: ComposeEnvironmentOptions): NodeJS.ProcessEnv;
+export declare function filterEnvironmentVariables(source: NodeJS.ProcessEnv, options?: EnvironmentFilterOptions): NodeJS.ProcessEnv;

package/dist/utils/env.js

@@ -0,0 +1,56 @@
+const DEFAULT_ALLOWED_VARIABLES = [
+    "CI",
+    "COLUMNS",
+    "HOME",
+    "HOSTNAME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "LC_MESSAGES",
+    "NODE_OPTIONS",
+    "PATH",
+    "PWD",
+    "SHELL",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+    "NODE_EXTRA_CA_CERTS",
+    "SSL_CERT_FILE",
+    "TERM",
+    "TMP",
+    "TMPDIR",
+    "TEMP",
+    "TZ",
+    "USER",
+    "USERNAME",
+    "ANTHROPIC_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+];
+const DEFAULT_ALLOWED_PREFIXES = ["LC_", "VORATIQ_", "SRT_"];
+export function composeRestrictedEnvironment(overrides, options = {}) {
+    const includeBase = options.includeBase ?? true;
+    const baseEnv = includeBase
+        ? filterEnvironmentVariables(options.base ?? process.env, options)
+        : {};
+    return overrides ? { ...baseEnv, ...overrides } : baseEnv;
+}
+export function filterEnvironmentVariables(source, options = {}) {
+    const allowedKeys = new Set(options.allow ?? DEFAULT_ALLOWED_VARIABLES);
+    const allowedPrefixes = options.prefixes ?? DEFAULT_ALLOWED_PREFIXES;
+    const filtered = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (allowedKeys.has(key)) {
+            filtered[key] = value;
+            continue;
+        }
+        if (allowedPrefixes.some((prefix) => key.startsWith(prefix))) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,31 @@
+export declare class GitRepositoryError extends Error {
+    constructor(message: string);
+}
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+export interface HintedErrorOptions {
+    readonly detailLines?: readonly string[];
+    readonly hintLines?: readonly string[];
+    readonly cause?: unknown;
+}
+export declare class HintedError extends Error {
+    readonly headline: string;
+    readonly detailLines: readonly string[];
+    readonly hintLines: readonly string[];
+    constructor(headline: string, options?: HintedErrorOptions);
+}
+/**
+ * Base class for errors that include a messageForDisplay() method.
+ * Reduces boilerplate for errors that return their stored message unchanged.
+ */
+export declare abstract class DisplayableError extends HintedError {
+    protected readonly displayMessage: string;
+    constructor(message: string, options?: HintedErrorOptions);
+    messageForDisplay(): string;
+}
+export declare class GitHeadRequiredError extends HintedError {
+    constructor();
+}
+export declare function toErrorMessage(error: unknown): string;
+export declare function toError(error: unknown): Error;