sequant 1.1.0 → 1.1.1

package/dist/src/lib/workflow/log-writer.js

@@ -0,0 +1,193 @@
+/**
+ * Log writer for structured workflow run logs
+ *
+ * Writes JSON logs to disk for analysis and debugging.
+ *
+ * @example
+ * ```typescript
+ * import { LogWriter } from './log-writer';
+ *
+ * const writer = new LogWriter({ projectPath: '.sequant/logs' });
+ * await writer.initialize(config);
+ * await writer.logPhase(phaseLog);
+ * await writer.finalize();
+ * ```
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { createEmptyRunLog, finalizeRunLog, generateLogFilename, LOG_PATHS, } from "./run-log-schema.js";
+/**
+ * Manages writing structured run logs to disk
+ */
+export class LogWriter {
+    runLog = null;
+    currentIssue = null;
+    logPath;
+    writeToUserLogs;
+    verbose;
+    constructor(options = {}) {
+        this.logPath = options.logPath ?? LOG_PATHS.project;
+        this.writeToUserLogs = options.writeToUserLogs ?? false;
+        this.verbose = options.verbose ?? false;
+    }
+    /**
+     * Initialize a new run log
+     *
+     * @param config - Run configuration
+     */
+    async initialize(config) {
+        this.runLog = createEmptyRunLog(config);
+        // Ensure log directory exists
+        await this.ensureLogDirectory(this.logPath);
+        if (this.writeToUserLogs) {
+            const userPath = LOG_PATHS.user.replace("~", os.homedir());
+            await this.ensureLogDirectory(userPath);
+        }
+        if (this.verbose && this.runLog) {
+            console.log(`📝 Log initialized: ${this.runLog.runId}`);
+        }
+    }
+    /**
+     * Start logging a new issue
+     *
+     * @param issueNumber - GitHub issue number
+     * @param title - Issue title
+     * @param labels - Issue labels
+     */
+    startIssue(issueNumber, title, labels) {
+        if (!this.runLog) {
+            throw new Error("LogWriter not initialized. Call initialize() first.");
+        }
+        this.currentIssue = {
+            issueNumber,
+            title,
+            labels,
+            phases: [],
+            status: "success",
+            totalDurationSeconds: 0,
+        };
+        if (this.verbose) {
+            console.log(`📝 Started logging issue #${issueNumber}`);
+        }
+    }
+    /**
+     * Log a completed phase
+     *
+     * @param phaseLog - Complete phase log entry
+     */
+    logPhase(phaseLog) {
+        if (!this.currentIssue) {
+            throw new Error("No current issue. Call startIssue() first.");
+        }
+        this.currentIssue.phases = [...(this.currentIssue.phases ?? []), phaseLog];
+        // Update issue status based on phase result
+        if (phaseLog.status === "failure") {
+            this.currentIssue.status = "failure";
+        }
+        else if (phaseLog.status === "timeout" &&
+            this.currentIssue.status !== "failure") {
+            this.currentIssue.status = "partial";
+        }
+        if (this.verbose) {
+            console.log(`📝 Logged phase: ${phaseLog.phase} (${phaseLog.status}) - ${phaseLog.durationSeconds.toFixed(1)}s`);
+        }
+    }
+    /**
+     * Complete the current issue and add it to the run log
+     */
+    completeIssue() {
+        if (!this.runLog || !this.currentIssue) {
+            throw new Error("No current issue to complete.");
+        }
+        // Calculate total duration from phases
+        const totalDurationSeconds = this.currentIssue.phases?.reduce((sum, p) => sum + p.durationSeconds, 0) ?? 0;
+        const issueLog = {
+            issueNumber: this.currentIssue.issueNumber,
+            title: this.currentIssue.title,
+            labels: this.currentIssue.labels,
+            status: this.currentIssue.status,
+            phases: this.currentIssue.phases,
+            totalDurationSeconds,
+        };
+        this.runLog.issues.push(issueLog);
+        this.currentIssue = null;
+        if (this.verbose) {
+            console.log(`📝 Completed issue #${issueLog.issueNumber} (${issueLog.status})`);
+        }
+    }
+    /**
+     * Finalize the run log and write to disk
+     *
+     * @returns Path to the written log file
+     */
+    async finalize() {
+        if (!this.runLog) {
+            throw new Error("LogWriter not initialized.");
+        }
+        // Complete any pending issue
+        if (this.currentIssue) {
+            this.completeIssue();
+        }
+        const finalLog = finalizeRunLog(this.runLog);
+        const filename = generateLogFilename(finalLog.runId, new Date(finalLog.startTime));
+        // Write to project logs
+        const projectPath = path.join(this.resolvePath(this.logPath), filename);
+        await this.writeLogFile(projectPath, finalLog);
+        // Optionally write to user logs
+        if (this.writeToUserLogs) {
+            const userPath = path.join(this.resolvePath(LOG_PATHS.user), filename);
+            await this.writeLogFile(userPath, finalLog);
+        }
+        if (this.verbose) {
+            console.log(`📝 Log written: ${projectPath}`);
+        }
+        return projectPath;
+    }
+    /**
+     * Get the current run log (for inspection)
+     */
+    getRunLog() {
+        return this.runLog;
+    }
+    /**
+     * Get the run ID
+     */
+    getRunId() {
+        return this.runLog?.runId ?? null;
+    }
+    resolvePath(logPath) {
+        return logPath.replace("~", os.homedir());
+    }
+    async ensureLogDirectory(logPath) {
+        const resolved = this.resolvePath(logPath);
+        if (!fs.existsSync(resolved)) {
+            fs.mkdirSync(resolved, { recursive: true });
+        }
+    }
+    async writeLogFile(filePath, log) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, JSON.stringify(log, null, 2));
+    }
+}
+/**
+ * Create a simple phase log from timing data
+ *
+ * Utility function for creating phase logs when you have start/end times.
+ */
+export function createPhaseLogFromTiming(phase, issueNumber, startTime, endTime, status, options) {
+    const durationSeconds = (endTime.getTime() - startTime.getTime()) / 1000;
+    return {
+        phase,
+        issueNumber,
+        startTime: startTime.toISOString(),
+        endTime: endTime.toISOString(),
+        durationSeconds,
+        status,
+        ...options,
+    };
+}
+//# sourceMappingURL=log-writer.js.map

package/dist/src/lib/workflow/log-writer.js.map

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

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Zod schemas for structured workflow run logs
+ *
+ * These schemas define the structure of JSON logs produced by `sequant run`
+ * for analysis, debugging, and automation purposes.
+ *
+ * @example
+ * ```typescript
+ * import { RunLogSchema, type RunLog } from './run-log-schema';
+ *
+ * // Validate a log file
+ * const log = RunLogSchema.parse(JSON.parse(logContent));
+ *
+ * // Type-safe access
+ * console.log(log.summary.passed, log.summary.failed);
+ * ```
+ */
+import { z } from "zod";
+/**
+ * Available workflow phases
+ */
+export declare const PhaseSchema: z.ZodEnum<{
+    loop: "loop";
+    spec: "spec";
+    exec: "exec";
+    qa: "qa";
+    testgen: "testgen";
+    test: "test";
+}>;
+export type Phase = z.infer<typeof PhaseSchema>;
+/**
+ * Phase execution status
+ */
+export declare const PhaseStatusSchema: z.ZodEnum<{
+    timeout: "timeout";
+    success: "success";
+    failure: "failure";
+    skipped: "skipped";
+}>;
+export type PhaseStatus = z.infer<typeof PhaseStatusSchema>;
+/**
+ * Issue execution status
+ */
+export declare const IssueStatusSchema: z.ZodEnum<{
+    success: "success";
+    failure: "failure";
+    partial: "partial";
+}>;
+export type IssueStatus = z.infer<typeof IssueStatusSchema>;
+/**
+ * Log entry for a single phase execution
+ */
+export declare const PhaseLogSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        loop: "loop";
+        spec: "spec";
+        exec: "exec";
+        qa: "qa";
+        testgen: "testgen";
+        test: "test";
+    }>;
+    issueNumber: z.ZodNumber;
+    startTime: z.ZodString;
+    endTime: z.ZodString;
+    durationSeconds: z.ZodNumber;
+    status: z.ZodEnum<{
+        timeout: "timeout";
+        success: "success";
+        failure: "failure";
+        skipped: "skipped";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+    iterations: z.ZodOptional<z.ZodNumber>;
+    filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    testsRun: z.ZodOptional<z.ZodNumber>;
+    testsPassed: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PhaseLog = z.infer<typeof PhaseLogSchema>;
+/**
+ * Complete execution record for a single issue
+ */
+export declare const IssueLogSchema: z.ZodObject<{
+    issueNumber: z.ZodNumber;
+    title: z.ZodString;
+    labels: z.ZodArray<z.ZodString>;
+    status: z.ZodEnum<{
+        success: "success";
+        failure: "failure";
+        partial: "partial";
+    }>;
+    phases: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            loop: "loop";
+            spec: "spec";
+            exec: "exec";
+            qa: "qa";
+            testgen: "testgen";
+            test: "test";
+        }>;
+        issueNumber: z.ZodNumber;
+        startTime: z.ZodString;
+        endTime: z.ZodString;
+        durationSeconds: z.ZodNumber;
+        status: z.ZodEnum<{
+            timeout: "timeout";
+            success: "success";
+            failure: "failure";
+            skipped: "skipped";
+        }>;
+        error: z.ZodOptional<z.ZodString>;
+        iterations: z.ZodOptional<z.ZodNumber>;
+        filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        testsRun: z.ZodOptional<z.ZodNumber>;
+        testsPassed: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    totalDurationSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type IssueLog = z.infer<typeof IssueLogSchema>;
+/**
+ * Run configuration
+ */
+export declare const RunConfigSchema: z.ZodObject<{
+    phases: z.ZodArray<z.ZodEnum<{
+        loop: "loop";
+        spec: "spec";
+        exec: "exec";
+        qa: "qa";
+        testgen: "testgen";
+        test: "test";
+    }>>;
+    sequential: z.ZodBoolean;
+    qualityLoop: z.ZodBoolean;
+    maxIterations: z.ZodNumber;
+}, z.core.$strip>;
+export type RunConfig = z.infer<typeof RunConfigSchema>;
+/**
+ * Summary statistics for a run
+ */
+export declare const RunSummarySchema: z.ZodObject<{
+    totalIssues: z.ZodNumber;
+    passed: z.ZodNumber;
+    failed: z.ZodNumber;
+    totalDurationSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type RunSummary = z.infer<typeof RunSummarySchema>;
+/**
+ * Complete run log schema
+ *
+ * This is the top-level schema for a workflow run log file.
+ */
+export declare const RunLogSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    startTime: z.ZodString;
+    endTime: z.ZodString;
+    config: z.ZodObject<{
+        phases: z.ZodArray<z.ZodEnum<{
+            loop: "loop";
+            spec: "spec";
+            exec: "exec";
+            qa: "qa";
+            testgen: "testgen";
+            test: "test";
+        }>>;
+        sequential: z.ZodBoolean;
+        qualityLoop: z.ZodBoolean;
+        maxIterations: z.ZodNumber;
+    }, z.core.$strip>;
+    issues: z.ZodArray<z.ZodObject<{
+        issueNumber: z.ZodNumber;
+        title: z.ZodString;
+        labels: z.ZodArray<z.ZodString>;
+        status: z.ZodEnum<{
+            success: "success";
+            failure: "failure";
+            partial: "partial";
+        }>;
+        phases: z.ZodArray<z.ZodObject<{
+            phase: z.ZodEnum<{
+                loop: "loop";
+                spec: "spec";
+                exec: "exec";
+                qa: "qa";
+                testgen: "testgen";
+                test: "test";
+            }>;
+            issueNumber: z.ZodNumber;
+            startTime: z.ZodString;
+            endTime: z.ZodString;
+            durationSeconds: z.ZodNumber;
+            status: z.ZodEnum<{
+                timeout: "timeout";
+                success: "success";
+                failure: "failure";
+                skipped: "skipped";
+            }>;
+            error: z.ZodOptional<z.ZodString>;
+            iterations: z.ZodOptional<z.ZodNumber>;
+            filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            testsRun: z.ZodOptional<z.ZodNumber>;
+            testsPassed: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        totalDurationSeconds: z.ZodNumber;
+    }, z.core.$strip>>;
+    summary: z.ZodObject<{
+        totalIssues: z.ZodNumber;
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+        totalDurationSeconds: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RunLog = z.infer<typeof RunLogSchema>;
+/**
+ * Default log directory paths
+ */
+export declare const LOG_PATHS: {
+    /** User-level logs */
+    readonly user: "~/.sequant/logs";
+    /** Project-level logs */
+    readonly project: ".sequant/logs";
+};
+/**
+ * Generate a log filename from run metadata
+ *
+ * @param runId - Unique run identifier
+ * @param startTime - Run start time
+ * @returns Filename in format: run-<timestamp>-<runId>.json
+ */
+export declare function generateLogFilename(runId: string, startTime: Date): string;
+/**
+ * Create an empty run log with initial values
+ *
+ * @param config - Run configuration
+ * @returns Initial RunLog structure
+ */
+export declare function createEmptyRunLog(config: RunConfig): Omit<RunLog, "endTime">;
+/**
+ * Create a phase log entry
+ *
+ * @param phase - Phase being executed
+ * @param issueNumber - GitHub issue number
+ * @returns PhaseLog with start time set
+ */
+export declare function createPhaseLog(phase: Phase, issueNumber: number): Omit<PhaseLog, "endTime" | "durationSeconds" | "status">;
+/**
+ * Complete a phase log entry
+ *
+ * @param phaseLog - Partial phase log
+ * @param status - Final status
+ * @param options - Additional fields (error, filesModified, etc.)
+ * @returns Complete PhaseLog
+ */
+export declare function completePhaseLog(phaseLog: Omit<PhaseLog, "endTime" | "durationSeconds" | "status">, status: PhaseStatus, options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed">>): PhaseLog;
+/**
+ * Finalize a run log with summary statistics
+ *
+ * @param runLog - Partial run log
+ * @returns Complete RunLog with endTime and summary
+ */
+export declare function finalizeRunLog(runLog: Omit<RunLog, "endTime">): RunLog;
+//# sourceMappingURL=run-log-schema.d.ts.map

package/dist/src/lib/workflow/run-log-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-log-schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/workflow/run-log-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;EAOtB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;EAK5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;EAA4C,CAAC;AAE3E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;iBAuBzB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAazB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;iBAS1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAS3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAevB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,SAAS;IACpB,sBAAsB;;IAEtB,yBAAyB;;CAEjB,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,CAG1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAiB5E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,MAAM,GAClB,IAAI,CAAC,QAAQ,EAAE,SAAS,GAAG,iBAAiB,GAAG,QAAQ,CAAC,CAM1D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,GAAG,iBAAiB,GAAG,QAAQ,CAAC,EAClE,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,OAAO,CACf,IAAI,CACF,QAAQ,EACR,OAAO,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,aAAa,CACtE,CACF,GACA,QAAQ,CAYV;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,CAsBtE"}

package/dist/src/lib/workflow/run-log-schema.js

@@ -0,0 +1,234 @@
+/**
+ * Zod schemas for structured workflow run logs
+ *
+ * These schemas define the structure of JSON logs produced by `sequant run`
+ * for analysis, debugging, and automation purposes.
+ *
+ * @example
+ * ```typescript
+ * import { RunLogSchema, type RunLog } from './run-log-schema';
+ *
+ * // Validate a log file
+ * const log = RunLogSchema.parse(JSON.parse(logContent));
+ *
+ * // Type-safe access
+ * console.log(log.summary.passed, log.summary.failed);
+ * ```
+ */
+import { z } from "zod";
+/**
+ * Available workflow phases
+ */
+export const PhaseSchema = z.enum([
+    "spec",
+    "testgen",
+    "exec",
+    "test",
+    "qa",
+    "loop",
+]);
+/**
+ * Phase execution status
+ */
+export const PhaseStatusSchema = z.enum([
+    "success",
+    "failure",
+    "timeout",
+    "skipped",
+]);
+/**
+ * Issue execution status
+ */
+export const IssueStatusSchema = z.enum(["success", "failure", "partial"]);
+/**
+ * Log entry for a single phase execution
+ */
+export const PhaseLogSchema = z.object({
+    /** Phase that was executed */
+    phase: PhaseSchema,
+    /** GitHub issue number */
+    issueNumber: z.number().int().positive(),
+    /** When the phase started */
+    startTime: z.string().datetime(),
+    /** When the phase ended */
+    endTime: z.string().datetime(),
+    /** Duration in seconds */
+    durationSeconds: z.number().nonnegative(),
+    /** Execution result */
+    status: PhaseStatusSchema,
+    /** Error message if failed */
+    error: z.string().optional(),
+    /** Number of iterations (for loop phase) */
+    iterations: z.number().int().nonnegative().optional(),
+    /** Files modified during this phase */
+    filesModified: z.array(z.string()).optional(),
+    /** Number of tests run (for test/qa phases) */
+    testsRun: z.number().int().nonnegative().optional(),
+    /** Number of tests passed */
+    testsPassed: z.number().int().nonnegative().optional(),
+});
+/**
+ * Complete execution record for a single issue
+ */
+export const IssueLogSchema = z.object({
+    /** GitHub issue number */
+    issueNumber: z.number().int().positive(),
+    /** Issue title */
+    title: z.string(),
+    /** Issue labels */
+    labels: z.array(z.string()),
+    /** Overall execution result */
+    status: IssueStatusSchema,
+    /** Log entries for each phase executed */
+    phases: z.array(PhaseLogSchema),
+    /** Total execution time in seconds */
+    totalDurationSeconds: z.number().nonnegative(),
+});
+/**
+ * Run configuration
+ */
+export const RunConfigSchema = z.object({
+    /** Phases that were configured to run */
+    phases: z.array(PhaseSchema),
+    /** Whether issues were run sequentially */
+    sequential: z.boolean(),
+    /** Whether quality loop was enabled */
+    qualityLoop: z.boolean(),
+    /** Maximum iterations for fix loops */
+    maxIterations: z.number().int().positive(),
+});
+/**
+ * Summary statistics for a run
+ */
+export const RunSummarySchema = z.object({
+    /** Total number of issues processed */
+    totalIssues: z.number().int().nonnegative(),
+    /** Number of issues that passed */
+    passed: z.number().int().nonnegative(),
+    /** Number of issues that failed */
+    failed: z.number().int().nonnegative(),
+    /** Total execution time in seconds */
+    totalDurationSeconds: z.number().nonnegative(),
+});
+/**
+ * Complete run log schema
+ *
+ * This is the top-level schema for a workflow run log file.
+ */
+export const RunLogSchema = z.object({
+    /** Schema version for backwards compatibility */
+    version: z.literal(1),
+    /** Unique identifier for this run */
+    runId: z.string().uuid(),
+    /** When the run started */
+    startTime: z.string().datetime(),
+    /** When the run ended */
+    endTime: z.string().datetime(),
+    /** Run configuration */
+    config: RunConfigSchema,
+    /** Execution logs for each issue */
+    issues: z.array(IssueLogSchema),
+    /** Summary statistics */
+    summary: RunSummarySchema,
+});
+/**
+ * Default log directory paths
+ */
+export const LOG_PATHS = {
+    /** User-level logs */
+    user: "~/.sequant/logs",
+    /** Project-level logs */
+    project: ".sequant/logs",
+};
+/**
+ * Generate a log filename from run metadata
+ *
+ * @param runId - Unique run identifier
+ * @param startTime - Run start time
+ * @returns Filename in format: run-<timestamp>-<runId>.json
+ */
+export function generateLogFilename(runId, startTime) {
+    const timestamp = startTime.toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    return `run-${timestamp}-${runId}.json`;
+}
+/**
+ * Create an empty run log with initial values
+ *
+ * @param config - Run configuration
+ * @returns Initial RunLog structure
+ */
+export function createEmptyRunLog(config) {
+    const runId = crypto.randomUUID();
+    const startTime = new Date().toISOString();
+    return {
+        version: 1,
+        runId,
+        startTime,
+        config,
+        issues: [],
+        summary: {
+            totalIssues: 0,
+            passed: 0,
+            failed: 0,
+            totalDurationSeconds: 0,
+        },
+    };
+}
+/**
+ * Create a phase log entry
+ *
+ * @param phase - Phase being executed
+ * @param issueNumber - GitHub issue number
+ * @returns PhaseLog with start time set
+ */
+export function createPhaseLog(phase, issueNumber) {
+    return {
+        phase,
+        issueNumber,
+        startTime: new Date().toISOString(),
+    };
+}
+/**
+ * Complete a phase log entry
+ *
+ * @param phaseLog - Partial phase log
+ * @param status - Final status
+ * @param options - Additional fields (error, filesModified, etc.)
+ * @returns Complete PhaseLog
+ */
+export function completePhaseLog(phaseLog, status, options) {
+    const endTime = new Date();
+    const startTime = new Date(phaseLog.startTime);
+    const durationSeconds = (endTime.getTime() - startTime.getTime()) / 1000;
+    return {
+        ...phaseLog,
+        endTime: endTime.toISOString(),
+        durationSeconds,
+        status,
+        ...options,
+    };
+}
+/**
+ * Finalize a run log with summary statistics
+ *
+ * @param runLog - Partial run log
+ * @returns Complete RunLog with endTime and summary
+ */
+export function finalizeRunLog(runLog) {
+    const endTime = new Date();
+    const startTime = new Date(runLog.startTime);
+    const totalDurationSeconds = (endTime.getTime() - startTime.getTime()) / 1000;
+    const passed = runLog.issues.filter((i) => i.status === "success").length;
+    const failed = runLog.issues.filter((i) => i.status === "failure").length;
+    return {
+        ...runLog,
+        endTime: endTime.toISOString(),
+        summary: {
+            totalIssues: runLog.issues.length,
+            passed,
+            failed,
+            totalDurationSeconds,
+        },
+    };
+}
+//# sourceMappingURL=run-log-schema.js.map