@hilbras/omninode 1.0.0 → 2.0.0-alpha.1

package/README.md

@@ -18,13 +18,24 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v1.0.0 — Phases 10 + 11: Production Release.** The plan is complete: the
+**v2.0.0-alpha.1 — v2 Phase 1: Architecture & API Stabilization** (the v2
+roadmap is [docs/ROADMAP_V2.md](docs/ROADMAP_V2.md); the v1 plan is complete:
+the
 full loop from §28 runs in one command —
 `User → project context → memory → research agents → reports → aggregation →
 planner → plan → execution → result` — with audit logging, error recovery and
 production hardening (see [docs/DEVELOPMENT_PLAN.md](docs/DEVELOPMENT_PLAN.md)
 for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
+### What changed in v2 Phase 1
+
+- All local stores now build on one shared `JsonFileStore` (atomic writes,
+  serialized read-modify-write, schema-versioned files, corruption tolerance)
+  with a `ProjectStores` facade.
+- Dependency direction corrected (adapters no longer import engine modules).
+- API surface stabilized and guarded: [API_STABILITY.md](docs/API_STABILITY.md),
+  [API.md](docs/API.md), [DEPRECATIONS.md](docs/DEPRECATIONS.md).
+
 ### What's in v1.0
 
 | Capability | Where |
@@ -284,6 +295,8 @@ required for the core engine.
 - [Development plan](docs/DEVELOPMENT_PLAN.md) — the full 12-phase roadmap
 - [Architecture](docs/ARCHITECTURE.md) — module map, workflow, local state
 - [Security model](docs/SECURITY.md) — secrets, process execution, env isolation, audit log
+- [API stability policy](docs/API_STABILITY.md) and [public API inventory](docs/API.md)
+- [Deprecations](docs/DEPRECATIONS.md) · [Changelog](CHANGELOG.md) · [v2 roadmap](docs/ROADMAP_V2.md)
 - [Example project](examples/demo/) — a runnable end-to-end demo (`./demo.sh`)
 
 Prefer a container? `docker build -t omninode .` then

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "1.0.0";
+var OMNINODE_VERSION = "2.0.0-alpha.1";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -1302,40 +1302,54 @@ function registerRoleCommands(program) {
   });
 }
 
-// src/tasks/store.ts
+// src/persistence/json-file-store.ts
 import { mkdir, readFile, rename, writeFile } from "fs/promises";
 import { dirname } from "path";
-var FileTaskStore = class {
+var JsonFileStore = class {
   filePath;
-  /**
-   * Read-modify-write operations are serialized: parallel pipeline tasks
-   * would otherwise race on the JSON file (last writer wins).
-   */
+  schemaVersion;
+  onCorrupt;
+  log;
   queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/tasks.json`;
+  constructor(options) {
+    this.filePath = `${options.directory ?? `${process.cwd()}/.omninode`}/${options.fileName}`;
+    this.schemaVersion = options.schemaVersion ?? 1;
+    this.onCorrupt = options.onCorrupt;
+    this.log = logger.child({ component: "persistence", file: options.fileName });
   }
-  async save(task) {
-    return this.synchronized(async () => {
-      const tasks = await this.load();
-      const index = tasks.findIndex((t) => t.id === task.id);
-      if (index >= 0) tasks[index] = task;
-      else tasks.push(task);
-      await this.write(tasks);
-    });
+  get path() {
+    return this.filePath;
   }
-  async get(id) {
-    return this.synchronized(async () => {
-      const tasks = await this.load();
-      return tasks.find((t) => t.id === id);
-    });
+  /** All items, or [] when missing/corrupt. */
+  async readAll() {
+    let raw;
+    try {
+      raw = await readFile(this.filePath, "utf8");
+    } catch {
+      return [];
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+      if (parsed !== null && typeof parsed === "object" && Array.isArray(parsed.items)) {
+        return parsed.items;
+      }
+      throw new Error("persisted file has an unrecognized shape");
+    } catch (error) {
+      this.log.warn(`Treating ${this.filePath} as empty \u2014 it could not be parsed.`);
+      this.onCorrupt?.(this.filePath, error);
+      return [];
+    }
   }
-  async list(filter = {}) {
-    return this.synchronized(async () => {
-      const tasks = await this.load();
-      return tasks.filter((task) => filter.status ? task.status === filter.status : true).filter((task) => filter.project ? task.project === filter.project : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
+  async writeAll(items) {
+    const document = { schemaVersion: this.schemaVersion, items };
+    const tmp = `${this.filePath}.tmp`;
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(tmp, `${JSON.stringify(document, null, 2)}
+`, "utf8");
+    await rename(tmp, this.filePath);
   }
+  /** Serializes an async operation against this file. */
   synchronized(operation) {
     const result = this.queue.then(operation, operation);
     this.queue = result.then(
@@ -1344,21 +1358,37 @@ var FileTaskStore = class {
     );
     return result;
   }
-  async load() {
-    try {
-      const raw = await readFile(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
+  /** Read-modify-write helper: applies `mutate` to the current items. */
+  async mutate(mutate) {
+    return this.synchronized(async () => {
+      const items = await this.readAll();
+      const [next, result] = await mutate(items);
+      await this.writeAll(next);
+      return result;
+    });
   }
-  async write(tasks) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir(dirname(this.filePath), { recursive: true });
-    await writeFile(tmp, `${JSON.stringify(tasks, null, 2)}
-`, "utf8");
-    await rename(tmp, this.filePath);
+};
+
+// src/tasks/store.ts
+var FileTaskStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "tasks.json" });
+  }
+  save(task) {
+    return this.mutate((tasks) => {
+      const index = tasks.findIndex((t) => t.id === task.id);
+      if (index >= 0) tasks[index] = task;
+      else tasks.push(task);
+      return [tasks, void 0];
+    });
+  }
+  async get(id) {
+    const tasks = await this.readAll();
+    return tasks.find((t) => t.id === id);
+  }
+  async list(filter = {}) {
+    const tasks = await this.readAll();
+    return tasks.filter((task) => filter.status ? task.status === filter.status : true).filter((task) => filter.project ? task.project === filter.project : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
 };
 
@@ -1575,10 +1605,10 @@ var FileAuditLog = class {
   }
   /** Recent events, oldest first; used by the CLI. */
   async recent(limit = 20) {
-    const { readFile: readFile6 } = await import("fs/promises");
+    const { readFile: readFile2 } = await import("fs/promises");
     let raw;
     try {
-      raw = await readFile6(this.filePath, "utf8");
+      raw = await readFile2(this.filePath, "utf8");
     } catch {
       return [];
     }
@@ -1594,8 +1624,6 @@ var FileAuditLog = class {
 };
 
 // src/memory/local.ts
-import { mkdir as mkdir3, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3 } from "path";
 var STOPWORDS = /* @__PURE__ */ new Set([
   "the",
   "and",
@@ -1652,29 +1680,24 @@ function relevanceScore(queryKeywords, entry2) {
   }
   return overlap * 2 + tagMatches * 1.5;
 }
-var LocalMemoryProvider = class {
+var LocalMemoryProvider = class extends JsonFileStore {
   name = "local";
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/memory.json`;
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "memory.json" });
   }
   async query(query) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      const filtered = entries.filter((entry2) => query.scope ? entry2.scope === query.scope : true).filter(
-        (entry2) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry2.tags ?? []).includes(tag)) : true
-      );
-      if (!query.text || query.text.trim().length === 0) {
-        return filtered.sort((a, b) => (b.updatedAt ?? b.createdAt ?? "").localeCompare(a.updatedAt ?? a.createdAt ?? "")).slice(0, query.limit ?? 10);
-      }
-      const queryKeywords = keywords(query.text);
-      return filtered.map((entry2) => ({ entry: entry2, score: relevanceScore(queryKeywords, entry2) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry: entry2 }) => entry2);
-    });
+    const entries = await this.readAll();
+    const filtered = entries.filter((entry2) => query.scope ? entry2.scope === query.scope : true).filter(
+      (entry2) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry2.tags ?? []).includes(tag)) : true
+    );
+    if (!query.text || query.text.trim().length === 0) {
+      return filtered.sort((a, b) => (b.updatedAt ?? b.createdAt ?? "").localeCompare(a.updatedAt ?? a.createdAt ?? "")).slice(0, query.limit ?? 10);
+    }
+    const queryKeywords = keywords(query.text);
+    return filtered.map((entry2) => ({ entry: entry2, score: relevanceScore(queryKeywords, entry2) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry: entry2 }) => entry2);
   }
-  async write(entry2) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
+  write(entry2) {
+    return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry2.key);
       const stamped = {
         ...entry2,
@@ -1683,35 +1706,11 @@ var LocalMemoryProvider = class {
       };
       if (index >= 0) entries[index] = stamped;
       else entries.push(stamped);
-      await this.saveAll(entries);
+      return [entries, void 0];
     });
   }
   async count() {
-    return (await this.load()).length;
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile2(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async saveAll(entries) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir3(dirname3(this.filePath), { recursive: true });
-    await writeFile2(tmp, `${JSON.stringify(entries, null, 2)}
-`, "utf8");
-    await rename2(tmp, this.filePath);
+    return (await this.readAll()).length;
   }
 };
 
@@ -2228,84 +2227,39 @@ var ReportService = class {
 };
 
 // src/reports/store.ts
-import { mkdir as mkdir4, readFile as readFile3, rename as rename3, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname4 } from "path";
-var FileReportStore = class {
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/reports.json`;
+var FileReportStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "reports.json" });
   }
   async saveReports(reports) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
+    await this.mutate((entries) => {
       for (const report of reports) {
-        const index = entries.findIndex(
-          (e) => e.kind === "report" && e.report.id === report.id
-        );
+        const index = entries.findIndex((e) => e.kind === "report" && e.report.id === report.id);
         const entry2 = { kind: "report", report };
         if (index >= 0) entries[index] = entry2;
         else entries.push(entry2);
       }
-      await this.write(entries);
+      return [entries, void 0];
     });
   }
   async listReports(filter = {}) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      return entries.filter((e) => e.kind === "report").map((e) => e.report).filter((report) => filter.taskId ? report.taskId === filter.taskId : true).filter((report) => filter.agent ? report.agent === filter.agent : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
+    return (await this.readAll()).filter((e) => e.kind === "report").map((e) => e.report).filter((report) => filter.taskId ? report.taskId === filter.taskId : true).filter((report) => filter.agent ? report.agent === filter.agent : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
   async saveCombined(combined) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      const index = entries.findIndex(
-        (e) => e.kind === "combined" && e.combined.id === combined.id
-      );
+    await this.mutate((entries) => {
+      const index = entries.findIndex((e) => e.kind === "combined" && e.combined.id === combined.id);
       const entry2 = { kind: "combined", combined };
       if (index >= 0) entries[index] = entry2;
       else entries.push(entry2);
-      await this.write(entries);
+      return [entries, void 0];
     });
   }
   async getCombined(id) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      const found = entries.find((e) => e.kind === "combined" && e.combined.id === id);
-      return found?.kind === "combined" ? found.combined : void 0;
-    });
+    const found = (await this.readAll()).find((e) => e.kind === "combined" && e.combined.id === id);
+    return found?.kind === "combined" ? found.combined : void 0;
   }
   async listCombined(filter = {}) {
-    return this.synchronized(async () => {
-      const entries = await this.load();
-      return entries.filter((e) => e.kind === "combined").map((e) => e.combined).filter(
-        (combined) => filter.pipelineRunId ? combined.pipelineRunId === filter.pipelineRunId : true
-      ).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile3(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async write(entries) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir4(dirname4(this.filePath), { recursive: true });
-    await writeFile3(tmp, `${JSON.stringify(entries, null, 2)}
-`, "utf8");
-    await rename3(tmp, this.filePath);
+    return (await this.readAll()).filter((e) => e.kind === "combined").map((e) => e.combined).filter((combined) => filter.pipelineRunId ? combined.pipelineRunId === filter.pipelineRunId : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
 };
 
@@ -3053,114 +3007,44 @@ function createDefaultChatFn(providers) {
 }
 
 // src/pipelines/store.ts
-import { mkdir as mkdir5, readFile as readFile4, rename as rename4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5 } from "path";
-var FilePipelineRunStore = class {
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/pipelines.json`;
+var FilePipelineRunStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "pipelines.json" });
   }
-  async save(run2) {
-    return this.synchronized(async () => {
-      const runs = await this.load();
+  save(run2) {
+    return this.mutate((runs) => {
       const index = runs.findIndex((r) => r.id === run2.id);
       if (index >= 0) runs[index] = run2;
       else runs.push(run2);
-      await this.write(runs);
+      return [runs, void 0];
     });
   }
   async get(id) {
-    return this.synchronized(async () => {
-      const runs = await this.load();
-      return runs.find((r) => r.id === id);
-    });
+    return (await this.readAll()).find((r) => r.id === id);
   }
   async list(filter = {}) {
-    return this.synchronized(async () => {
-      const runs = await this.load();
-      return runs.filter((run2) => filter.pipelineId ? run2.pipelineId === filter.pipelineId : true).filter((run2) => filter.status ? run2.status === filter.status : true).sort((a, b) => (a.startedAt ?? "").localeCompare(b.startedAt ?? ""));
-    });
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile4(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async write(runs) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir5(dirname5(this.filePath), { recursive: true });
-    await writeFile4(tmp, `${JSON.stringify(runs, null, 2)}
-`, "utf8");
-    await rename4(tmp, this.filePath);
+    return (await this.readAll()).filter((run2) => filter.pipelineId ? run2.pipelineId === filter.pipelineId : true).filter((run2) => filter.status ? run2.status === filter.status : true).sort((a, b) => (a.startedAt ?? "").localeCompare(b.startedAt ?? ""));
   }
 };
 
 // src/planner/store.ts
-import { mkdir as mkdir6, readFile as readFile5, rename as rename5, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname6 } from "path";
-var FilePlanStore = class {
-  filePath;
-  queue = Promise.resolve();
-  constructor(directory = `${process.cwd()}/.omninode`) {
-    this.filePath = `${directory}/plans.json`;
+var FilePlanStore = class extends JsonFileStore {
+  constructor(directory) {
+    super({ ...directory !== void 0 ? { directory } : {}, fileName: "plans.json" });
   }
-  async save(plan) {
-    return this.synchronized(async () => {
-      const plans = await this.load();
+  save(plan) {
+    return this.mutate((plans) => {
       const index = plans.findIndex((p) => p.id === plan.id);
       if (index >= 0) plans[index] = plan;
       else plans.push(plan);
-      await this.write(plans);
+      return [plans, void 0];
     });
   }
   async get(id) {
-    return this.synchronized(async () => {
-      const plans = await this.load();
-      return plans.find((p) => p.id === id);
-    });
+    return (await this.readAll()).find((p) => p.id === id);
   }
   async list(filter = {}) {
-    return this.synchronized(async () => {
-      const plans = await this.load();
-      return plans.filter((plan) => filter.pipelineRunId ? plan.pipelineRunId === filter.pipelineRunId : true).filter((plan) => filter.taskId ? plan.taskId === filter.taskId : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    });
-  }
-  synchronized(operation) {
-    const result = this.queue.then(operation, operation);
-    this.queue = result.then(
-      () => void 0,
-      () => void 0
-    );
-    return result;
-  }
-  async load() {
-    try {
-      const raw = await readFile5(this.filePath, "utf8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? parsed : [];
-    } catch {
-      return [];
-    }
-  }
-  async write(plans) {
-    const tmp = `${this.filePath}.tmp`;
-    await mkdir6(dirname6(this.filePath), { recursive: true });
-    await writeFile5(tmp, `${JSON.stringify(plans, null, 2)}
-`, "utf8");
-    await rename5(tmp, this.filePath);
+    return (await this.readAll()).filter((plan) => filter.pipelineRunId ? plan.pipelineRunId === filter.pipelineRunId : true).filter((plan) => filter.taskId ? plan.taskId === filter.taskId : true).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
   }
 };