ralph-research 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 research-ratchet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# ralph-research
+
+Local-first runtime for recursive research improvement.
+
+`ralph-research` runs a bounded improvement loop over a real artifact:
+
+1. define a metric
+2. generate one candidate change
+3. evaluate it
+4. keep only verified improvements
+
+The v0.1 focus is a writing workflow that is runnable in under five minutes on a local machine.
+
+## Quickstart
+
+### Zero-config demo
+
+```bash
+npx ralph-research demo writing
+```
+
+This creates a temporary writing repo, runs one accepted cycle, and prints the path plus the run id. The v0.1 demo supports the bundled `writing` template only.
+
+### Template flow
+
+```bash
+npx ralph-research init --template writing
+npx ralph-research run --json
+npx ralph-research inspect run-0001 --json
+```
+
+This path is the v0.1 success bar: `init -> run -> inspect` should work quickly and produce an acceptance reason you can inspect. The bundled template set is currently `writing` only.
+
+## Core Concepts
+
+- `Manifest`: `ralph.yaml` defines the research program.
+- `Metric`: how candidate quality is measured.
+- `Frontier`: the currently accepted best candidate set.
+- `Ratchet`: the acceptance policy that decides whether the frontier advances.
+- `Proposer`: how a bounded candidate change is generated.
+- `Judge`: how qualitative outputs are compared when numeric metrics are not enough.
+
+## Writing Template
+
+The bundled writing template is self-contained:
+
+- `docs/draft.md`: sample draft
+- `scripts/propose.mjs`: bounded rewrite
+- `scripts/experiment.mjs`: output materialization
+- `scripts/metric.mjs`: local heuristic metric
+- `prompts/judge.md`: pairwise judge prompt you can upgrade to later
+
+The default template uses a local command metric so the first run does not require API keys. When you are ready, replace the numeric metric with an `llm_judge` extractor and use the included pairwise prompt as a starting point.
+
+## CLI
+
+```text
+rrx validate
+rrx doctor
+rrx init --template writing
+rrx demo writing
+rrx run
+rrx status
+rrx frontier
+rrx inspect <runId>
+rrx accept <runId>
+rrx reject <runId>
+rrx serve-mcp --stdio
+```
+
+## MCP
+
+The bundled MCP server currently supports stdio transport and exposes three thin tools backed by the same service layer as the CLI:
+
+- `run_research_cycle`
+- `get_research_status`
+- `get_frontier`
+
+## Design Principles
+
+- local-first execution
+- bounded changes
+- recoverable state transitions
+- trusted signal before automation
+- inspectable accept/reject decisions
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+## License
+
+MIT

package/dist/adapters/extractor/command-extractor.d.ts

@@ -0,0 +1,9 @@
+import type { CommandMetricExtractorConfig } from "../../core/manifest/schema.js";
+import type { MetricResult } from "../../core/model/metric.js";
+export interface ExtractCommandMetricInput {
+    metricId: string;
+    direction: "maximize" | "minimize";
+    workspacePath: string;
+    env?: Record<string, string>;
+}
+export declare function extractCommandMetric(config: CommandMetricExtractorConfig, input: ExtractCommandMetricInput): Promise<MetricResult>;

package/dist/adapters/extractor/command-extractor.js

@@ -0,0 +1,93 @@
+import { resolve } from "node:path";
+import { execaCommand } from "execa";
+export async function extractCommandMetric(config, input) {
+    const cwd = config.cwd ? resolve(input.workspacePath, config.cwd) : resolve(input.workspacePath);
+    const result = await execaCommand(config.command, {
+        cwd,
+        env: { ...process.env, ...config.env, ...input.env },
+        reject: false,
+        shell: true,
+        timeout: config.timeoutSec * 1_000,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(`command metric extractor failed with exit code ${result.exitCode}: ${result.stderr || result.stdout}`);
+    }
+    return {
+        metricId: input.metricId,
+        direction: input.direction,
+        value: parseMetricValue(result.stdout, config),
+        details: {
+            parser: config.parser,
+            command: config.command,
+            cwd,
+        },
+    };
+}
+function parseMetricValue(stdout, config) {
+    switch (config.parser) {
+        case "plain_number":
+            return parseNumericValue(stdout.trim(), "plain_number");
+        case "regex":
+            return parseRegexValue(stdout, config.pattern);
+        case "json_path":
+            return parseJsonPathValue(stdout, config.valuePath);
+    }
+}
+function parseRegexValue(stdout, pattern) {
+    if (!pattern) {
+        throw new Error('command metric extractor with parser="regex" requires a pattern');
+    }
+    const match = new RegExp(pattern, "m").exec(stdout);
+    if (!match) {
+        throw new Error(`regex parser did not match pattern ${pattern}`);
+    }
+    const candidate = match.groups?.value ?? match[1] ?? match[0];
+    return parseNumericValue(candidate, "regex");
+}
+function parseJsonPathValue(stdout, valuePath) {
+    if (!valuePath) {
+        throw new Error('command metric extractor with parser="json_path" requires a valuePath');
+    }
+    const json = JSON.parse(stdout);
+    const value = readJsonPath(json, valuePath);
+    return parseNumericValue(value, "json_path");
+}
+function readJsonPath(root, path) {
+    if (!path.startsWith("$")) {
+        throw new Error(`unsupported JSONPath: ${path}`);
+    }
+    const tokens = path
+        .slice(1)
+        .replace(/\[(\d+)\]/g, ".$1")
+        .split(".")
+        .filter(Boolean);
+    let current = root;
+    for (const token of tokens) {
+        if (current === null || current === undefined) {
+            throw new Error(`JSONPath ${path} resolved to undefined at token ${token}`);
+        }
+        if (Array.isArray(current)) {
+            const index = Number.parseInt(token, 10);
+            current = current[index];
+            continue;
+        }
+        if (typeof current === "object") {
+            current = current[token];
+            continue;
+        }
+        throw new Error(`JSONPath ${path} could not descend into non-object value at token ${token}`);
+    }
+    return current;
+}
+function parseNumericValue(value, parserName) {
+    const numericValue = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number.parseFloat(value.trim())
+            : Number.NaN;
+    if (!Number.isFinite(numericValue)) {
+        throw new Error(`${parserName} parser did not resolve to a finite number`);
+    }
+    return numericValue;
+}
+//# sourceMappingURL=command-extractor.js.map

package/dist/adapters/extractor/command-extractor.js.map

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

package/dist/adapters/extractor/llm-judge-extractor.d.ts

@@ -0,0 +1,9 @@
+import type { LlmJudgeMetricExtractorConfig, JudgePack } from "../../core/manifest/schema.js";
+import type { MetricResult } from "../../core/model/metric.js";
+import type { JudgeProvider } from "../judge/llm-judge-provider.js";
+export interface ExtractLlmJudgeMetricInput {
+    metricId: string;
+    direction: "maximize" | "minimize";
+    prompt: string;
+}
+export declare function extractLlmJudgeMetric(config: LlmJudgeMetricExtractorConfig, pack: JudgePack, input: ExtractLlmJudgeMetricInput, provider: JudgeProvider): Promise<MetricResult>;

package/dist/adapters/extractor/llm-judge-extractor.js

@@ -0,0 +1,12 @@
+import { runLlmJudgeMetric } from "../../core/engine/judge-pack.js";
+export async function extractLlmJudgeMetric(config, pack, input, provider) {
+    return runLlmJudgeMetric({
+        metricId: input.metricId,
+        direction: input.direction,
+        extractor: config,
+        pack,
+        prompt: input.prompt,
+        provider,
+    });
+}
+//# sourceMappingURL=llm-judge-extractor.js.map

package/dist/adapters/extractor/llm-judge-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-judge-extractor.js","sourceRoot":"","sources":["../../../src/adapters/extractor/llm-judge-extractor.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAQpE,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAqC,EACrC,IAAe,EACf,KAAiC,EACjC,QAAuB;IAEvB,OAAO,iBAAiB,CAAC;QACvB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,MAAM;QACjB,IAAI;QACJ,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ;KACT,CAAC,CAAC;AACL,CAAC"}

package/dist/adapters/fs/json-file-decision-store.d.ts

@@ -0,0 +1,10 @@
+import { type DecisionRecord } from "../../core/model/decision-record.js";
+import type { DecisionStore } from "../../core/ports/decision-store.js";
+export declare class JsonFileDecisionStore implements DecisionStore {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    put(record: DecisionRecord): Promise<void>;
+    get(decisionId: string): Promise<DecisionRecord | null>;
+    list(): Promise<DecisionRecord[]>;
+    private getPath;
+}

package/dist/adapters/fs/json-file-decision-store.js

@@ -0,0 +1,53 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { decisionRecordSchema } from "../../core/model/decision-record.js";
+import { isMissingFileError } from "../../shared/fs-errors.js";
+export class JsonFileDecisionStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = resolve(rootDir);
+    }
+    async put(record) {
+        const parsed = decisionRecordSchema.parse(record);
+        const path = this.getPath(parsed.decisionId);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    }
+    async get(decisionId) {
+        const path = this.getPath(decisionId);
+        try {
+            const raw = await readFile(path, "utf8");
+            return decisionRecordSchema.parse(JSON.parse(raw));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async list() {
+        try {
+            const entries = await readdir(this.rootDir, { withFileTypes: true });
+            const records = [];
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith(".json")) {
+                    continue;
+                }
+                const raw = await readFile(join(this.rootDir, entry.name), "utf8");
+                records.push(decisionRecordSchema.parse(JSON.parse(raw)));
+            }
+            return records.sort((left, right) => left.decisionId.localeCompare(right.decisionId));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    getPath(decisionId) {
+        return join(this.rootDir, `${decisionId}.json`);
+    }
+}
+//# sourceMappingURL=json-file-decision-store.js.map

package/dist/adapters/fs/json-file-decision-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-file-decision-store.js","sourceRoot":"","sources":["../../../src/adapters/fs/json-file-decision-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,oBAAoB,EAAuB,MAAM,qCAAqC,CAAC;AAEhG,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,OAAO,qBAAqB;IACf,OAAO,CAAS;IAEjC,YAAmB,OAAe;QAChC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,MAAsB;QACrC,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,UAAkB;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzC,OAAO,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,IAAI;QACf,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,MAAM,OAAO,GAAqB,EAAE,CAAC;YACrC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACrD,SAAS;gBACX,CAAC;gBACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;gBACnE,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5D,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;QACxF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,UAAkB;QAChC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,UAAU,OAAO,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/adapters/fs/json-file-frontier-store.d.ts

@@ -0,0 +1,8 @@
+import { type FrontierEntry } from "../../core/model/frontier-entry.js";
+import type { FrontierStore } from "../../core/ports/frontier-store.js";
+export declare class JsonFileFrontierStore implements FrontierStore {
+    private readonly path;
+    constructor(path: string);
+    save(entries: FrontierEntry[]): Promise<void>;
+    load(): Promise<FrontierEntry[]>;
+}

package/dist/adapters/fs/json-file-frontier-store.js

@@ -0,0 +1,29 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { frontierEntrySchema } from "../../core/model/frontier-entry.js";
+import { isMissingFileError } from "../../shared/fs-errors.js";
+const frontierSnapshotSchema = frontierEntrySchema.array();
+export class JsonFileFrontierStore {
+    path;
+    constructor(path) {
+        this.path = resolve(path);
+    }
+    async save(entries) {
+        const parsed = frontierSnapshotSchema.parse(entries);
+        await mkdir(dirname(this.path), { recursive: true });
+        await writeFile(this.path, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    }
+    async load() {
+        try {
+            const raw = await readFile(this.path, "utf8");
+            return frontierSnapshotSchema.parse(JSON.parse(raw));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=json-file-frontier-store.js.map

package/dist/adapters/fs/json-file-frontier-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-file-frontier-store.js","sourceRoot":"","sources":["../../../src/adapters/fs/json-file-frontier-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,mBAAmB,EAAsB,MAAM,oCAAoC,CAAC;AAE7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,sBAAsB,GAAG,mBAAmB,CAAC,KAAK,EAAE,CAAC;AAE3D,MAAM,OAAO,qBAAqB;IACf,IAAI,CAAS;IAE9B,YAAmB,IAAY;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,OAAwB;QACxC,MAAM,MAAM,GAAG,sBAAsB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7E,CAAC;IAEM,KAAK,CAAC,IAAI;QACf,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9C,OAAO,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/adapters/fs/json-file-run-store.d.ts

@@ -0,0 +1,10 @@
+import { type RunRecord } from "../../core/model/run-record.js";
+import type { RunStore } from "../../core/ports/run-store.js";
+export declare class JsonFileRunStore implements RunStore {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    put(record: RunRecord): Promise<void>;
+    get(runId: string): Promise<RunRecord | null>;
+    list(): Promise<RunRecord[]>;
+    private getPath;
+}

package/dist/adapters/fs/json-file-run-store.js

@@ -0,0 +1,53 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { runRecordSchema } from "../../core/model/run-record.js";
+import { isMissingFileError } from "../../shared/fs-errors.js";
+export class JsonFileRunStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = resolve(rootDir);
+    }
+    async put(record) {
+        const parsed = runRecordSchema.parse(record);
+        const path = this.getPath(parsed.runId);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    }
+    async get(runId) {
+        const path = this.getPath(runId);
+        try {
+            const raw = await readFile(path, "utf8");
+            return runRecordSchema.parse(JSON.parse(raw));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async list() {
+        try {
+            const entries = await readdir(this.rootDir, { withFileTypes: true });
+            const records = [];
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith(".json")) {
+                    continue;
+                }
+                const raw = await readFile(join(this.rootDir, entry.name), "utf8");
+                records.push(runRecordSchema.parse(JSON.parse(raw)));
+            }
+            return records.sort((left, right) => left.runId.localeCompare(right.runId));
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    getPath(runId) {
+        return join(this.rootDir, `${runId}.json`);
+    }
+}
+//# sourceMappingURL=json-file-run-store.js.map

package/dist/adapters/fs/json-file-run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-file-run-store.js","sourceRoot":"","sources":["../../../src/adapters/fs/json-file-run-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAkB,MAAM,gCAAgC,CAAC;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,OAAO,gBAAgB;IACV,OAAO,CAAS;IAEjC,YAAmB,OAAe;QAChC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,MAAiB;QAChC,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,KAAa;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzC,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,IAAI;QACf,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,MAAM,OAAO,GAAgB,EAAE,CAAC;YAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACrD,SAAS;gBACX,CAAC;gBACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;gBACnE,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvD,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,KAAa;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/adapters/fs/lockfile.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+declare const lockfileMetadataSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    token: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    ttlMs: z.ZodNumber;
+}, z.core.$strip>;
+export type LockfileMetadata = z.infer<typeof lockfileMetadataSchema>;
+export interface AcquireLockOptions {
+    ttlMs?: number;
+}
+export interface LockHandle {
+    path: string;
+    metadata: LockfileMetadata;
+}
+export declare class LockAcquisitionError extends Error {
+    constructor(message: string);
+}
+export declare function acquireLock(path: string, options?: AcquireLockOptions): Promise<LockHandle>;
+export declare function releaseLock(path: string, token?: string): Promise<void>;
+export declare function isStaleLock(path: string): Promise<boolean>;
+export declare function readLockMetadata(path: string): Promise<LockfileMetadata | null>;
+export {};

package/dist/adapters/fs/lockfile.js

@@ -0,0 +1,110 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+import { isMissingFileError } from "../../shared/fs-errors.js";
+const lockfileMetadataSchema = z.object({
+    pid: z.number().int().positive(),
+    token: z.string().min(1),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    ttlMs: z.number().int().positive(),
+});
+export class LockAcquisitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LockAcquisitionError";
+    }
+}
+const DEFAULT_LOCK_TTL_MS = 5 * 60 * 1000;
+export async function acquireLock(path, options = {}) {
+    const resolvedPath = resolve(path);
+    const ttlMs = options.ttlMs ?? DEFAULT_LOCK_TTL_MS;
+    await mkdir(dirname(resolvedPath), { recursive: true });
+    const metadata = {
+        pid: process.pid,
+        token: randomUUID(),
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        ttlMs,
+    };
+    try {
+        await writeFile(resolvedPath, `${JSON.stringify(metadata, null, 2)}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+        });
+        return { path: resolvedPath, metadata };
+    }
+    catch (error) {
+        if (!isAlreadyExistsError(error)) {
+            throw error;
+        }
+    }
+    const stale = await isStaleLock(resolvedPath);
+    if (!stale) {
+        throw new LockAcquisitionError(`Active lock already exists at ${resolvedPath}`);
+    }
+    await rm(resolvedPath, { force: true });
+    await writeFile(resolvedPath, `${JSON.stringify(metadata, null, 2)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+    });
+    return { path: resolvedPath, metadata };
+}
+export async function releaseLock(path, token) {
+    const resolvedPath = resolve(path);
+    const metadata = await readLockMetadata(resolvedPath);
+    if (!metadata) {
+        return;
+    }
+    if (token && metadata.token !== token) {
+        throw new LockAcquisitionError(`Refusing to release lock at ${resolvedPath}: token mismatch`);
+    }
+    await rm(resolvedPath, { force: true });
+}
+export async function isStaleLock(path) {
+    const metadata = await readLockMetadata(path);
+    if (!metadata) {
+        return false;
+    }
+    const ageMs = Date.now() - Date.parse(metadata.updatedAt);
+    if (ageMs > metadata.ttlMs) {
+        return true;
+    }
+    return !isProcessAlive(metadata.pid);
+}
+export async function readLockMetadata(path) {
+    const resolvedPath = resolve(path);
+    try {
+        const raw = await readFile(resolvedPath, "utf8");
+        return lockfileMetadataSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function isAlreadyExistsError(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error) {
+            const code = error.code;
+            if (code === "ESRCH") {
+                return false;
+            }
+            if (code === "EPERM") {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/adapters/fs/lockfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.js","sourceRoot":"","sources":["../../../src/adapters/fs/lockfile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAChC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAaH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,UAA8B,EAAE;IAC9E,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC;IAEnD,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAExD,MAAM,QAAQ,GAAqB;QACjC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,UAAU,EAAE;QACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK;KACN,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YACtE,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,YAAY,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,oBAAoB,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,EAAE,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,SAAS,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACtE,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,KAAc;IAC5D,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,YAAY,CAAC,CAAC;IACtD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IAED,IAAI,KAAK,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,oBAAoB,CAAC,+BAA+B,YAAY,kBAAkB,CAAC,CAAC;IAChG,CAAC;IAED,MAAM,EAAE,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACjD,OAAO,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,CAAC;AACzG,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;YACnD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/adapters/fs/manifest-loader.d.ts

@@ -0,0 +1,10 @@
+import { type RalphManifest } from "../../core/manifest/schema.js";
+export interface LoadedManifest {
+    path: string;
+    manifest: RalphManifest;
+}
+export declare class ManifestLoadError extends Error {
+    readonly causeValue?: unknown;
+    constructor(message: string, causeValue?: unknown);
+}
+export declare function loadManifestFromFile(path?: string): Promise<LoadedManifest>;

package/dist/adapters/fs/manifest-loader.js

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parse } from "yaml";
+import { ZodError } from "zod";
+import { DEFAULT_MANIFEST_FILENAME, RalphManifestSchema } from "../../core/manifest/schema.js";
+export class ManifestLoadError extends Error {
+    causeValue;
+    constructor(message, causeValue) {
+        super(message);
+        this.name = "ManifestLoadError";
+        this.causeValue = causeValue;
+    }
+}
+export async function loadManifestFromFile(path = DEFAULT_MANIFEST_FILENAME) {
+    const resolvedPath = resolve(path);
+    let rawText;
+    try {
+        rawText = await readFile(resolvedPath, "utf8");
+    }
+    catch (error) {
+        throw new ManifestLoadError(`Failed to read manifest at ${resolvedPath}`, error);
+    }
+    let parsedYaml;
+    try {
+        parsedYaml = parse(rawText);
+    }
+    catch (error) {
+        throw new ManifestLoadError(`Failed to parse YAML from ${resolvedPath}`, error);
+    }
+    try {
+        return {
+            path: resolvedPath,
+            manifest: RalphManifestSchema.parse(parsedYaml),
+        };
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            throw new ManifestLoadError(`Manifest validation failed for ${resolvedPath}`, error.flatten());
+        }
+        throw new ManifestLoadError(`Manifest validation failed for ${resolvedPath}`, error);
+    }
+}
+//# sourceMappingURL=manifest-loader.js.map

package/dist/adapters/fs/manifest-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-loader.js","sourceRoot":"","sources":["../../../src/adapters/fs/manifest-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAE/B,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAsB,MAAM,+BAA+B,CAAC;AAOnH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1B,UAAU,CAAW;IAErC,YAAmB,OAAe,EAAE,UAAoB;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAI,GAAG,yBAAyB;IACzE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,8BAA8B,YAAY,EAAE,EAAE,KAAK,CAAC,CAAC;IACnF,CAAC;IAED,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACH,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,6BAA6B,YAAY,EAAE,EAAE,KAAK,CAAC,CAAC;IAClF,CAAC;IAED,IAAI,CAAC;QACH,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC;SAChD,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,iBAAiB,CAAC,kCAAkC,YAAY,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjG,CAAC;QAED,MAAM,IAAI,iBAAiB,CAAC,kCAAkC,YAAY,EAAE,EAAE,KAAK,CAAC,CAAC;IACvF,CAAC;AACH,CAAC"}