voratiq 0.1.0-beta.0

package/dist/utils/errors.js

@@ -0,0 +1,53 @@
+export class GitRepositoryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitRepositoryError";
+    }
+}
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+export class HintedError extends Error {
+    headline;
+    detailLines;
+    hintLines;
+    constructor(headline, options = {}) {
+        const { cause, detailLines, hintLines } = options;
+        super(headline, cause !== undefined ? { cause } : undefined);
+        this.headline = headline;
+        this.detailLines = detailLines ? Array.from(detailLines) : [];
+        this.hintLines = hintLines ? Array.from(hintLines) : [];
+    }
+}
+/**
+ * Base class for errors that include a messageForDisplay() method.
+ * Reduces boilerplate for errors that return their stored message unchanged.
+ */
+export class DisplayableError extends HintedError {
+    displayMessage;
+    constructor(message, options = {}) {
+        super(message, options);
+        this.displayMessage = message;
+    }
+    messageForDisplay() {
+        return this.displayMessage;
+    }
+}
+export class GitHeadRequiredError extends HintedError {
+    constructor() {
+        super("Repository has no commits yet.", {
+            hintLines: ["Create an initial commit and re-run."],
+        });
+        this.name = "GitHeadRequiredError";
+    }
+}
+export function toErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message;
+}
+export function toError(error) {
+    return error instanceof Error ? error : new Error(toErrorMessage(error));
+}

package/dist/utils/fs.d.ts

@@ -0,0 +1,13 @@
+export declare const F_OK: number;
+type ErrorOrFactory = Error | (() => Error);
+export declare function isFileSystemError(error: unknown): error is NodeJS.ErrnoException & {
+    code: string;
+};
+export declare function isMissing(error: unknown): boolean;
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function isDirectory(path: string): Promise<boolean>;
+export declare function isFile(path: string): Promise<boolean>;
+export declare function ensureDirectoryExists(path: string, error: ErrorOrFactory): Promise<void>;
+export declare function ensureFileExists(path: string, error: ErrorOrFactory): Promise<void>;
+export declare function safeUnlink(path: string): Promise<void>;
+export { readFileSync as readUtf8File } from "node:fs";

package/dist/utils/fs.js

@@ -0,0 +1,70 @@
+import { constants as fsConstants } from "node:fs";
+import { access, rm, stat } from "node:fs/promises";
+export const { F_OK } = fsConstants;
+export function isFileSystemError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string");
+}
+export function isMissing(error) {
+    return isFileSystemError(error) && error.code === "ENOENT";
+}
+export async function pathExists(path) {
+    try {
+        await access(path, F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isDirectory(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function isFile(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isFile();
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function ensureDirectoryExists(path, error) {
+    if (!(await isDirectory(path))) {
+        throw resolveError(error);
+    }
+}
+export async function ensureFileExists(path, error) {
+    if (!(await isFile(path))) {
+        throw resolveError(error);
+    }
+}
+export async function safeUnlink(path) {
+    try {
+        await rm(path);
+    }
+    catch (error) {
+        if (isFileSystemError(error) && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
+function resolveError(error) {
+    return typeof error === "function" ? error() : error;
+}
+export { readFileSync as readUtf8File } from "node:fs";

package/dist/utils/git.d.ts

@@ -0,0 +1,40 @@
+export declare const GIT_AUTHOR_NAME = "voratiq-runs";
+export declare const GIT_AUTHOR_EMAIL = "runs@voratiq.com";
+export declare const GIT_COMMITTER_NAME = "voratiq-runs";
+export declare const GIT_COMMITTER_EMAIL = "runs@voratiq.com";
+export interface GitCommandOptions {
+    cwd: string;
+    trim?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export interface DirtyPathSummary {
+    path: string;
+    annotation: string;
+}
+export declare function assertGitRepository(root: string): Promise<void>;
+export declare function runGitCommand(args: string[], options: GitCommandOptions): Promise<string>;
+export declare function getHeadRevision(cwd: string): Promise<string>;
+export interface CreateWorktreeOptions {
+    root: string;
+    worktreePath: string;
+    branch: string;
+    baseRevision: string;
+}
+export declare function createWorktree(options: CreateWorktreeOptions): Promise<void>;
+export declare function gitAddAll(cwd: string): Promise<void>;
+export declare function gitHasStagedChanges(cwd: string): Promise<boolean>;
+export interface GitCommitOptions {
+    cwd: string;
+    message: string;
+    authorName?: string;
+    authorEmail?: string;
+}
+export declare function gitCommitAll(options: GitCommitOptions): Promise<void>;
+export interface GitDiffStatOptions {
+    cwd: string;
+    baseRevision: string;
+    targetRevision: string;
+}
+export declare function gitDiffShortStat(options: GitDiffStatOptions): Promise<string | undefined>;
+export declare function gitDiff(options: GitDiffStatOptions): Promise<string>;
+export declare function getGitStderr(error: unknown): string | undefined;

package/dist/utils/git.js

@@ -0,0 +1,126 @@
+import { execFile } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { GitHeadRequiredError, GitRepositoryError } from "./errors.js";
+const execFileAsync = promisify(execFile);
+const { F_OK } = fsConstants;
+export const GIT_AUTHOR_NAME = "voratiq-runs";
+export const GIT_AUTHOR_EMAIL = "runs@voratiq.com";
+export const GIT_COMMITTER_NAME = GIT_AUTHOR_NAME;
+export const GIT_COMMITTER_EMAIL = GIT_AUTHOR_EMAIL;
+export async function assertGitRepository(root) {
+    const gitPath = join(root, ".git");
+    try {
+        await access(gitPath, F_OK);
+    }
+    catch {
+        // Check if we're inside a git repo but not at its root
+        const repoRoot = await getGitRepositoryRoot(root);
+        if (repoRoot !== null) {
+            // We're in a repo but not at the root
+            throw new GitRepositoryError("Run `voratiq init` from the repository root.");
+        }
+        // No git repository exists at all
+        throw new GitRepositoryError("No git repository found. Run `git init` or switch to an existing repository.");
+    }
+}
+/**
+ * Attempts to find the root of a git repository by running `git rev-parse --show-toplevel`.
+ * Returns the repository root path if inside a git repo, or null if not.
+ */
+async function getGitRepositoryRoot(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            encoding: "utf8",
+        });
+        return stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export async function runGitCommand(args, options) {
+    const { cwd, trim = true, env } = options;
+    const execEnv = env ? { ...process.env, ...env } : undefined;
+    const { stdout } = await execFileAsync("git", args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024,
+        env: execEnv,
+    });
+    return trim ? stdout.trim() : stdout;
+}
+export async function getHeadRevision(cwd) {
+    try {
+        return await runGitCommand(["rev-parse", "HEAD"], { cwd });
+    }
+    catch (error) {
+        if (isHeadMissing(error)) {
+            throw new GitHeadRequiredError();
+        }
+        throw error;
+    }
+}
+export async function createWorktree(options) {
+    const { root, worktreePath, branch, baseRevision } = options;
+    await runGitCommand(["worktree", "add", "-b", branch, worktreePath, baseRevision], { cwd: root });
+}
+export async function gitAddAll(cwd) {
+    await runGitCommand(["add", "-A"], { cwd });
+}
+export async function gitHasStagedChanges(cwd) {
+    const output = await runGitCommand(["diff", "--cached", "--name-only"], {
+        cwd,
+        trim: true,
+    });
+    return output.length > 0;
+}
+export async function gitCommitAll(options) {
+    const { cwd, message, authorName = GIT_AUTHOR_NAME, authorEmail = GIT_AUTHOR_EMAIL, } = options;
+    await runGitCommand(["commit", "-m", message], {
+        cwd,
+        env: {
+            GIT_AUTHOR_NAME: authorName,
+            GIT_AUTHOR_EMAIL: authorEmail,
+            GIT_COMMITTER_NAME: authorName,
+            GIT_COMMITTER_EMAIL: authorEmail,
+        },
+    });
+}
+export async function gitDiffShortStat(options) {
+    const { cwd, baseRevision, targetRevision } = options;
+    const output = await runGitCommand(["diff", "--shortstat", baseRevision, targetRevision], { cwd });
+    return output.length === 0 ? undefined : output;
+}
+export async function gitDiff(options) {
+    const { cwd, baseRevision, targetRevision } = options;
+    return runGitCommand(["diff", "--no-color", baseRevision, targetRevision], {
+        cwd,
+        trim: false,
+    });
+}
+export function getGitStderr(error) {
+    if (error &&
+        typeof error === "object" &&
+        "stderr" in error &&
+        typeof error.stderr === "string") {
+        const stderr = error.stderr.trim();
+        if (stderr.length > 0) {
+            return stderr;
+        }
+    }
+    return undefined;
+}
+function isHeadMissing(error) {
+    const stderr = getGitStderr(error);
+    const normalized = stderr?.toLowerCase() ?? "";
+    const code = error.code;
+    const headMissingMessage = normalized.includes("ambiguous argument 'head'") ||
+        normalized.includes("unknown revision or path not in the working tree") ||
+        normalized.includes("needed a single revision");
+    const isHeadExitCode = code === 128 || code === "128";
+    return headMissingMessage || (isHeadExitCode && normalized.includes("head"));
+}

package/dist/utils/output.d.ts

@@ -0,0 +1,4 @@
+import { type TerminalColor } from "./colors.js";
+export declare function formatCliOutput(value: string): string;
+export declare function formatAlertMessage(label: string, color: TerminalColor, message: string): string;
+export declare function formatErrorMessage(message: string): string;

package/dist/utils/output.js

@@ -0,0 +1,12 @@
+import { colorize } from "./colors.js";
+export function formatCliOutput(value) {
+    const trimmedEnd = value.trimEnd();
+    return `\n${trimmedEnd}\n\n`;
+}
+export function formatAlertMessage(label, color, message) {
+    const prefix = colorize(`${label}:`, color);
+    return `${prefix} ${message}`;
+}
+export function formatErrorMessage(message) {
+    return formatAlertMessage("Error", "red", message);
+}

package/dist/utils/path.d.ts

@@ -0,0 +1,11 @@
+export declare function isRepoRelativePath(value: string): boolean;
+export declare function assertRepoRelativePath(value: string, message?: string): string;
+export declare function resolvePath(root: string, ...segments: string[]): string;
+export interface PathWithinRootOptions {
+    message?: string;
+}
+export declare function assertPathWithinRoot(root: string, targetPath: string, options?: PathWithinRootOptions): string;
+export declare function resolvePathWithinRoot(root: string, segments: readonly string[], options?: PathWithinRootOptions): string;
+export declare function relativeToRoot(root: string, target: string): string;
+export declare function normalizePathForDisplay(value: string): string;
+export declare function resolveDisplayPath(root: string, displayPath: string | null | undefined): string | null;

package/dist/utils/path.js

@@ -0,0 +1,84 @@
+import { isAbsolute, join, relative, resolve as resolveAbsolute, } from "node:path";
+function isWindowsAbsolutePath(value) {
+    return /^[A-Za-z]:/.test(value);
+}
+export function isRepoRelativePath(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    if (value.trim() !== value) {
+        return false;
+    }
+    if (value.length === 0) {
+        return false;
+    }
+    if (value === ".") {
+        return true;
+    }
+    if (value.startsWith("/")) {
+        return false;
+    }
+    if (isWindowsAbsolutePath(value)) {
+        return false;
+    }
+    if (value.includes("\\")) {
+        return false;
+    }
+    const segments = value.split("/");
+    return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+export function assertRepoRelativePath(value, message = `Path "${value}" must be repo-relative, use forward slashes, and omit '.' or '..' segments.`) {
+    if (!isRepoRelativePath(value)) {
+        throw new Error(message);
+    }
+    return value;
+}
+export function resolvePath(root, ...segments) {
+    return join(root, ...segments);
+}
+function normalizeRoot(root) {
+    return resolveAbsolute(root);
+}
+function isWithinRoot(root, target) {
+    const relativePath = relative(root, target);
+    if (relativePath === "" || relativePath === ".") {
+        return true;
+    }
+    if (relativePath.startsWith("..")) {
+        return false;
+    }
+    if (isAbsolute(relativePath)) {
+        return false;
+    }
+    return true;
+}
+export function assertPathWithinRoot(root, targetPath, options) {
+    const normalizedRoot = normalizeRoot(root);
+    const normalizedTarget = isAbsolute(targetPath)
+        ? resolveAbsolute(targetPath)
+        : resolveAbsolute(normalizedRoot, targetPath);
+    if (!isWithinRoot(normalizedRoot, normalizedTarget)) {
+        throw new Error(options?.message ??
+            `Path "${normalizedTarget}" escapes root "${normalizedRoot}".`);
+    }
+    return normalizedTarget;
+}
+export function resolvePathWithinRoot(root, segments, options) {
+    const resolved = resolveAbsolute(root, ...segments);
+    return assertPathWithinRoot(root, resolved, options);
+}
+export function relativeToRoot(root, target) {
+    return relative(root, target) || ".";
+}
+export function normalizePathForDisplay(value) {
+    const normalized = value.replaceAll("\\", "/");
+    return normalized.replace(/\/+$/u, "");
+}
+export function resolveDisplayPath(root, displayPath) {
+    if (!displayPath) {
+        return null;
+    }
+    return isAbsolute(displayPath)
+        ? displayPath
+        : resolveAbsolute(root, displayPath);
+}

package/dist/utils/process.d.ts

@@ -0,0 +1,37 @@
+import type { Writable } from "node:stream";
+export interface StreamTarget {
+    writable: Writable;
+    endOnClose?: boolean;
+}
+export interface SpawnStreamingProcessOptions {
+    command: string;
+    args?: string[];
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+    stdin?: string | Buffer;
+    stdout: StreamTarget;
+    stderr: StreamTarget;
+    /** Optional callback invoked for each chunk of stdout/stderr data. */
+    onData?: (chunk: Buffer) => void;
+    /** Optional callback invoked when the process is spawned, providing the child process. */
+    onSpawn?: (child: import("node:child_process").ChildProcess) => void;
+    /**
+     * Optional AbortSignal to force-resolve the process promise even if the child
+     * hasn't exited. Used by the watchdog to ensure bounded termination.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * If true, spawn the child in a new process group. This enables killing
+     * the entire process tree by sending signals to the negative PID.
+     * Required for proper cleanup of agent child processes on watchdog termination.
+     */
+    detached?: boolean;
+}
+export interface SpawnStreamingProcessResult {
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+    /** True if the process was force-aborted via AbortSignal before natural exit. */
+    aborted?: boolean;
+}
+export declare function spawnStreamingProcess(options: SpawnStreamingProcessOptions): Promise<SpawnStreamingProcessResult>;

package/dist/utils/process.js

@@ -0,0 +1,152 @@
+import { spawn } from "node:child_process";
+import { RunProcessStreamError } from "../commands/run/errors.js";
+import { composeRestrictedEnvironment } from "./env.js";
+export async function spawnStreamingProcess(options) {
+    const { command, args = [], cwd, env, shell = false, stdin, stdout, stderr, onData, onSpawn, abortSignal, detached = false, } = options;
+    return await new Promise((resolve, reject) => {
+        let resolved = false;
+        const child = spawn(command, args, {
+            cwd,
+            env: buildSpawnEnvironment(env),
+            shell,
+            stdio: ["pipe", "pipe", "pipe"],
+            detached,
+        });
+        if (onSpawn) {
+            onSpawn(child);
+        }
+        const childStdout = child.stdout;
+        const childStderr = child.stderr;
+        const childStdin = child.stdin;
+        if (!childStdout || !childStderr) {
+            void finalizeStreams([stdout, stderr], true);
+            reject(new RunProcessStreamError("Failed to capture process output streams"));
+            return;
+        }
+        if (onData) {
+            childStdout.on("data", onData);
+            childStderr.on("data", onData);
+        }
+        childStdout.pipe(stdout.writable, { end: false });
+        childStderr.pipe(stderr.writable, { end: false });
+        if (stdin !== undefined) {
+            if (childStdin) {
+                childStdin.end(stdin);
+            }
+            else {
+                childStdout.unpipe(stdout.writable);
+                childStderr.unpipe(stderr.writable);
+                void finalizeStreams([stdout, stderr], true);
+                reject(new RunProcessStreamError("Process does not expose stdin"));
+                return;
+            }
+        }
+        else if (childStdin) {
+            childStdin.end();
+        }
+        const finalize = async (forceEnd) => {
+            childStdout.unpipe(stdout.writable);
+            childStderr.unpipe(stderr.writable);
+            await finalizeStreams([stdout, stderr], forceEnd);
+        };
+        // Handle abort signal for force-termination after watchdog timeout
+        const handleAbort = () => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            // Don't wait for stream finalization on force abort - resolve immediately
+            // to ensure bounded termination. Streams will be cleaned up by caller.
+            childStdout.unpipe(stdout.writable);
+            childStderr.unpipe(stderr.writable);
+            resolve({ exitCode: 1, signal: "SIGKILL", aborted: true });
+        };
+        if (abortSignal) {
+            if (abortSignal.aborted) {
+                handleAbort();
+                return;
+            }
+            abortSignal.addEventListener("abort", handleAbort, { once: true });
+        }
+        child.on("error", (error) => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            abortSignal?.removeEventListener("abort", handleAbort);
+            void finalize(true).finally(() => {
+                reject(error);
+            });
+        });
+        child.on("close", (code, signal) => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            abortSignal?.removeEventListener("abort", handleAbort);
+            void finalize(false).finally(() => {
+                resolve({ exitCode: code ?? 0, signal });
+            });
+        });
+    });
+}
+function buildSpawnEnvironment(overrides) {
+    return composeRestrictedEnvironment(overrides);
+}
+async function finalizeStreams(targets, forceEnd) {
+    const streams = new Map();
+    for (const target of targets) {
+        const shouldEnd = forceEnd || target.endOnClose !== false;
+        const previous = streams.get(target.writable) ?? false;
+        streams.set(target.writable, previous || shouldEnd);
+    }
+    const closures = [];
+    for (const [stream, shouldEnd] of streams) {
+        if (!shouldEnd) {
+            continue;
+        }
+        closures.push(waitForWritableClosure(stream));
+        try {
+            stream.end();
+        }
+        catch {
+            // Ignore errors raised while ending the writable; the closure promise
+            // will resolve once the stream reports its terminal state.
+        }
+    }
+    if (closures.length > 0) {
+        await Promise.all(closures);
+    }
+}
+function waitForWritableClosure(stream) {
+    const state = stream;
+    if (state.destroyed ||
+        state.writableFinished ||
+        state.writableEnded ||
+        state.closed) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            stream.removeListener("close", handleClose);
+            stream.removeListener("finish", handleFinish);
+            stream.removeListener("error", handleError);
+        };
+        const handleComplete = () => {
+            cleanup();
+            resolve();
+        };
+        const handleClose = () => {
+            handleComplete();
+        };
+        const handleFinish = () => {
+            handleComplete();
+        };
+        const handleError = () => {
+            handleComplete();
+        };
+        stream.once("close", handleClose);
+        stream.once("finish", handleFinish);
+        stream.once("error", handleError);
+    });
+}

package/dist/utils/terminal.d.ts

@@ -0,0 +1,5 @@
+export interface InteractiveShellOptions {
+    input?: NodeJS.ReadStream | null;
+    output?: NodeJS.WriteStream | null;
+}
+export declare function isInteractiveShell(options?: InteractiveShellOptions): boolean;

package/dist/utils/terminal.js

@@ -0,0 +1,5 @@
+export function isInteractiveShell(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    return Boolean(input?.isTTY && output?.isTTY);
+}

package/dist/utils/validators.d.ts

@@ -0,0 +1 @@
+export declare function parsePositiveInteger(value: unknown, invalidMessage: string, nonPositiveMessage?: string): number;

package/dist/utils/validators.js

@@ -0,0 +1,15 @@
+import { ValidationError } from "./errors.js";
+export function parsePositiveInteger(value, invalidMessage, nonPositiveMessage) {
+    if (typeof value !== "string") {
+        throw new ValidationError(invalidMessage);
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/u.test(trimmed)) {
+        throw new ValidationError(invalidMessage);
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new ValidationError(nonPositiveMessage ?? invalidMessage);
+    }
+    return parsed;
+}

package/dist/utils/version.d.ts

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

package/dist/utils/version.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { getCliAssetPath } from "./cli-root.js";
+let cachedVersion;
+export function getVoratiqVersion() {
+    if (cachedVersion) {
+        return cachedVersion;
+    }
+    try {
+        const packageJsonPath = getCliAssetPath("package.json");
+        const packageJsonRaw = readFileSync(packageJsonPath, "utf-8");
+        const packageJson = JSON.parse(packageJsonRaw);
+        if (typeof packageJson.version === "string") {
+            const normalizedVersion = packageJson.version.trim();
+            if (normalizedVersion) {
+                cachedVersion = normalizedVersion;
+                return cachedVersion;
+            }
+        }
+    }
+    catch {
+        // Swallow parsing/IO errors; fallback below keeps CLI usable.
+    }
+    cachedVersion = "unknown";
+    return cachedVersion;
+}