@gtrabanco/agentic-workflow 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Incremental sync engine for the `doc` retrieval index (unit 65, P4).
3
+ *
4
+ * Change detection is hash-based (per-file sha256 from the canonical
5
+ * manifest, AC10): only files whose hash changed — or that disappeared —
6
+ * are reprocessed. Deletions reap every chunk of the removed file, and the
7
+ * external-content FTS5 table is kept in step by triggers, so no orphan
8
+ * chunk or ghost row survives (AC11). Determinism (AC12): the canonical
9
+ * manifest export written per sync is byte-identical for an unchanged
10
+ * corpus — sorted keys, git HEAD, no timestamps.
11
+ *
12
+ * Freshness invariant (AC9): `ensureFresh` compares the stored manifest
13
+ * (hashes + git HEAD) against the live corpus on every call; a stale store
14
+ * gets an inline incremental sync before the caller answers.
15
+ */
16
+
17
+ import { readFileSync, writeFileSync, rmSync } from "node:fs";
18
+ import { join } from "node:path";
19
+ import { openDatabase } from "./sqlite.mjs";
20
+ import { storePath, storePresent, manifestExportPath } from "./store.mjs";
21
+ import { loadConfig } from "./config.mjs";
22
+ import { collectManifest, canonicalJson } from "./manifest.mjs";
23
+ import { scanChunks } from "./chunks.mjs";
24
+
25
+ const SCHEMA = `
26
+ CREATE TABLE IF NOT EXISTS chunks (
27
+ chunk_id TEXT UNIQUE NOT NULL,
28
+ path TEXT NOT NULL,
29
+ section TEXT,
30
+ line_start INTEGER NOT NULL,
31
+ line_end INTEGER NOT NULL,
32
+ meta TEXT NOT NULL,
33
+ body TEXT NOT NULL,
34
+ embedding BLOB,
35
+ emb_model TEXT
36
+ );
37
+ CREATE INDEX IF NOT EXISTS chunks_path ON chunks(path);
38
+ CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(body, content='chunks', content_rowid='rowid');
39
+ CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
40
+ INSERT INTO chunks_fts(rowid, body) VALUES (new.rowid, new.body);
41
+ END;
42
+ CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
43
+ INSERT INTO chunks_fts(chunks_fts, rowid, body) VALUES ('delete', old.rowid, old.body);
44
+ END;
45
+ CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
46
+ `;
47
+
48
+ /** Read the manifest persisted in the store's meta table (null if absent). */
49
+ export function storedManifest(db) {
50
+ try {
51
+ const row = db.prepare("select value from meta where key = 'manifest'").get();
52
+ return row ? JSON.parse(row.value) : null;
53
+ } catch {
54
+ return null;
55
+ }
56
+ }
57
+
58
+ /** Counts for `--status`: `{files, chunks}` over the store at `root`. */
59
+ export async function storeStats(root) {
60
+ const { db } = await openDatabase(storePath(root));
61
+ const files = db.prepare("select count(distinct path) as n from chunks").get().n;
62
+ const chunks = db.prepare("select count(*) as n from chunks").get().n;
63
+ db.close();
64
+ return { files, chunks };
65
+ }
66
+
67
+ /**
68
+ * One incremental sync pass over the tracked markdown corpus at `root`.
69
+ * Returns `{filesScanned, filesChanged, filesDeleted, chunks}`.
70
+ */
71
+ export async function syncIndex(root) {
72
+ loadConfig(root); // config errors surface here too (usage/IO), even in sync
73
+ const manifest = collectManifest(root);
74
+ const { db } = await openDatabase(storePath(root));
75
+ db.exec(SCHEMA);
76
+
77
+ const stored = storedManifest(db);
78
+ const oldFiles = stored?.files ?? {};
79
+ const changed = [];
80
+ const deleted = [];
81
+ for (const [path, info] of Object.entries(manifest.files)) {
82
+ if (oldFiles[path] === undefined || oldFiles[path].sha256 !== info.sha256) changed.push(path);
83
+ }
84
+ for (const path of Object.keys(oldFiles)) {
85
+ if (manifest.files[path] === undefined) deleted.push(path);
86
+ }
87
+
88
+ const reap = db.prepare("DELETE FROM chunks WHERE path = ?");
89
+ const insert = db.prepare(
90
+ "INSERT INTO chunks (chunk_id, path, section, line_start, line_end, meta, body) VALUES (?, ?, ?, ?, ?, ?, ?)",
91
+ );
92
+ for (const path of deleted) reap.run(path);
93
+ for (const path of changed) {
94
+ const src = join(root, path);
95
+ try {
96
+ // Reap existing chunks for this path before re-inserting (original
97
+ // reap.run(path) before the read — preserved for the non-ENOENT path).
98
+ reap.run(path);
99
+ const rows = scanChunks(readFileSync(src, "utf8"), path);
100
+ for (const c of rows) {
101
+ insert.run(c.id, c.path, c.section, c.lines[0], c.lines[1], JSON.stringify(c.meta), c.body);
102
+ }
103
+ } catch (e) {
104
+ if (e.code === "ENOENT") {
105
+ // File deleted in working tree but not yet committed → reap
106
+ // (AC11: treat as deletion).
107
+ reap.run(path);
108
+ deleted.push(path);
109
+ } else throw e;
110
+ }
111
+ }
112
+
113
+ // Persist + export the canonical manifest (AC12's compared artifact).
114
+ db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('manifest', ?)").run(canonicalJson(manifest));
115
+ db.close();
116
+ writeFileSync(manifestExportPath(root), `${canonicalJson(manifest)}\n`);
117
+
118
+ const stats = await storeStats(root);
119
+ return {
120
+ filesScanned: Object.keys(manifest.files).length,
121
+ filesChanged: changed.length,
122
+ filesDeleted: deleted.length,
123
+ chunks: stats.chunks,
124
+ };
125
+ }
126
+
127
+ /**
128
+ * Freshness invariant (AC9): manifest hashes + git HEAD checked against the
129
+ * store; stale or missing ⇒ inline incremental sync before answering.
130
+ * Returns `{fresh, synced}`.
131
+ */
132
+ export async function ensureFresh(root) {
133
+ const current = collectManifest(root);
134
+ if (storePresent(root)) {
135
+ const { db } = await openDatabase(storePath(root));
136
+ const stored = storedManifest(db);
137
+ db.close();
138
+ if (stored !== null && canonicalJson(stored) === canonicalJson(current)) {
139
+ return { fresh: true, synced: false };
140
+ }
141
+ }
142
+ await syncIndex(root);
143
+ return { fresh: false, synced: true };
144
+ }
145
+
146
+ /**
147
+ * `--rebuild`: discard the disposable cache entirely (db + WAL/SHM + the
148
+ * manifest export) and resync from scratch. Returns the fresh sync counts
149
+ * with `rebuilt: true`.
150
+ */
151
+ export async function rebuildIndex(root) {
152
+ const base = storePath(root);
153
+ rmSync(base, { force: true });
154
+ rmSync(`${base}-wal`, { force: true });
155
+ rmSync(`${base}-shm`, { force: true });
156
+ rmSync(manifestExportPath(root), { force: true });
157
+ const r = await syncIndex(root);
158
+ return { rebuilt: true, ...r };
159
+ }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * File-schema vocabularies for agwo edit typed file services.
2
+ * File-schema vocabularies for agentic-workflow edit typed file services.
3
3
  *
4
4
  * Canonical definitions: section lists, table columns, operation names,
5
5
  * and operation receipts. Consumers in UnitDoc, Roadmap, Changelog,
@@ -1,358 +0,0 @@
1
- /**
2
- * Tests for agwo edit — typed file services SDK.
3
- *
4
- * Uses node:test with temp directories for isolation.
5
- * Covers: UnitDoc, Roadmap, Changelog, Budgets, Manifest, receipts, CLI smoke.
6
- */
7
-
8
- import { describe, it, before, after } from "node:test";
9
- import { strictEqual, ok, throws } from "node:assert";
10
- import { mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync, mkdirSync } from "node:fs";
11
- import { tmpdir } from "node:os";
12
- import { join } from "node:path";
13
- import { spawn } from "node:child_process";
14
-
15
- // ── SDK imports ──────────────────────────────────────────────────────────
16
- import { create, setSection, evidence_addRow, progress_logEntry, validate } from "../src/edit/UnitDoc.mjs";
17
- import { rowUpsert, annotate } from "../src/edit/Roadmap.mjs";
18
- import { rowAdd } from "../src/edit/Changelog.mjs";
19
- import { ceilingRebase } from "../src/edit/Budgets.mjs";
20
- import { skillAdd, skillRemove } from "../src/edit/Manifest.mjs";
21
-
22
- // ── Test fixtures ────────────────────────────────────────────────────────
23
-
24
- let tmpDir;
25
- let unitDir;
26
- let specPath;
27
-
28
- before(() => {
29
- tmpDir = mkdtempSync(join(tmpdir(), "agwo-edit-"));
30
- unitDir = join(tmpDir, "docs", "features", "61-test-slug");
31
- mkdirSync(unitDir, { recursive: true });
32
- specPath = join(unitDir, "SPEC.md");
33
- });
34
-
35
- after(() => {
36
- if (tmpDir && existsSync(tmpDir)) {
37
- rmSync(tmpDir, { recursive: true, force: true });
38
- }
39
- });
40
-
41
- // ── UnitDoc tests ────────────────────────────────────────────────────────
42
-
43
- describe("UnitDoc", () => {
44
- it("create produces 13 sections in order", () => {
45
- const receipt = create(unitDir, "61-test-slug");
46
- strictEqual(receipt.ok, true);
47
- strictEqual(receipt.service, "unitDoc");
48
- strictEqual(receipt.op, "create");
49
-
50
- const content = readFileSync(specPath, "utf8");
51
- const sections = [
52
- "Objective", "Why", "User outcome", "Acceptance criteria",
53
- "Non-goals", "Future cost", "Applicable tests",
54
- "Known pre-existing issues", "Tasks", "Evidence",
55
- "Progress log", "Next", "References",
56
- ];
57
-
58
- // All 13 sections must exist in order
59
- let lastIdx = -1;
60
- for (const section of sections) {
61
- const idx = content.indexOf(`## ${section}`);
62
- ok(idx !== -1, `Section "${section}" not found`);
63
- ok(idx > lastIdx, `Section "${section}" out of order`);
64
- lastIdx = idx;
65
- }
66
- });
67
-
68
- it("setSection refuses an unknown section", () => {
69
- throws(() => {
70
- setSection(specPath, "UnknownSection", "body");
71
- }, /Unknown section/);
72
- });
73
-
74
- it("setSection updates an existing section", () => {
75
- const receipt = setSection(specPath, "Objective", "New objective body");
76
- strictEqual(receipt.ok, true);
77
-
78
- const content = readFileSync(specPath, "utf8");
79
- ok(content.includes("New objective body"));
80
- });
81
-
82
- it("evidence.addRow writes the exact column shape", () => {
83
- const receipt = evidence_addRow(specPath, {
84
- ac: "AC-14",
85
- command: "bun test edit.test.mjs",
86
- exitDigest: "sha256:abc123",
87
- output: "2 tests passed",
88
- verifiedBy: "test-agent",
89
- });
90
- strictEqual(receipt.ok, true);
91
-
92
- const content = readFileSync(specPath, "utf8");
93
- ok(content.includes("| AC-14"));
94
- ok(content.includes("| bun test edit.test.mjs"));
95
- ok(content.includes("| sha256:abc123"));
96
- ok(content.includes("| 2 tests passed"));
97
- ok(content.includes("| test-agent |"));
98
- });
99
-
100
- it("progress entry with a bad timestamp is refused", () => {
101
- throws(() => {
102
- progress_logEntry(specPath, {
103
- ts: "not-a-timestamp",
104
- what: "did something",
105
- ref: "abc123",
106
- next: "do more",
107
- });
108
- }, /Progress entry does not match/);
109
- });
110
-
111
- it("progress entry with valid format succeeds", () => {
112
- const receipt = progress_logEntry(specPath, {
113
- ts: "2026-09-22 14:30",
114
- what: "implemented agwo edit",
115
- ref: "abc123def",
116
- next: "write tests",
117
- });
118
- strictEqual(receipt.ok, true);
119
-
120
- const content = readFileSync(specPath, "utf8");
121
- ok(content.includes("2026-09-22 14:30 — implemented agwo edit → abc123def — next: write tests"));
122
- });
123
-
124
- it("validate returns violations for missing sections", () => {
125
- const content = "# Test\n\n## Objective\n\nOnly one section";
126
- const result = validate(content);
127
- strictEqual(result.ok, false);
128
- ok(result.violations.length > 0);
129
- ok(result.violations.some((v) => v.includes("Why")));
130
- });
131
- });
132
-
133
- // ── Roadmap tests ────────────────────────────────────────────────────────
134
-
135
- describe("Roadmap", () => {
136
- let roadmapPath;
137
-
138
- before(() => {
139
- roadmapPath = join(tmpDir, "ROADMAP.md");
140
- const content = `# Roadmap
141
-
142
- | NN | slug | status | depends-on | description |
143
- |---|---|---|---|---|
144
- `;
145
- writeFileSync(roadmapPath, content, "utf8");
146
- });
147
-
148
- it("rowUpsert inserts a new row", () => {
149
- const receipt = rowUpsert(roadmapPath, {
150
- nn: "61",
151
- slug: "adaptive-unit-lane",
152
- status: "active",
153
- dependsOn: "",
154
- description: "Adaptive unit lane implementation",
155
- });
156
- strictEqual(receipt.ok, true);
157
-
158
- const updated = readFileSync(roadmapPath, "utf8");
159
- ok(updated.includes("| 61 | adaptive-unit-lane |"));
160
- });
161
-
162
- it("rowUpsert updates the same NN without duplicating", () => {
163
- const receipt = rowUpsert(roadmapPath, {
164
- nn: "61",
165
- slug: "adaptive-unit-lane-v2",
166
- status: "completed",
167
- dependsOn: "",
168
- description: "Updated description",
169
- });
170
- strictEqual(receipt.ok, true);
171
-
172
- const content = readFileSync(roadmapPath, "utf8");
173
- const count = content.split("| 61 |").length - 1;
174
- strictEqual(count, 1);
175
- });
176
-
177
- it("annotate appends to the description", () => {
178
- annotate(roadmapPath, "61", "Added annotation note");
179
- const content = readFileSync(roadmapPath, "utf8");
180
- ok(content.includes("— Added annotation note"));
181
- });
182
- });
183
-
184
- // ── Changelog tests ──────────────────────────────────────────────────────
185
-
186
- describe("Changelog", () => {
187
- it("changelog row lands inside the named section's table", () => {
188
- const changelogPath = join(tmpDir, "CHANGELOG.md");
189
- const content = `# Changelog
190
-
191
- #### \`unit-doc\`
192
-
193
- | Version | Date | Type | What changed |
194
- |---|---|---|---|
195
-
196
- #### \`roadmap\`
197
-
198
- | Version | Date | Type | What changed |
199
- |---|---|---|---|
200
- `;
201
- writeFileSync(changelogPath, content, "utf8");
202
-
203
- const receipt = rowAdd(changelogPath, "unit-doc", {
204
- version: "0.1.0",
205
- date: "2026-09-22",
206
- type: "feature",
207
- what: "Added agwo edit typed file services",
208
- });
209
- strictEqual(receipt.ok, true);
210
-
211
- const updated = readFileSync(changelogPath, "utf8");
212
- // The row should appear under unit-doc section, not roadmap
213
- const parts = updated.split("#### `unit-doc`");
214
- ok(parts.length >= 2);
215
- const unitDocContent = parts[1];
216
- const roadmapIdx = unitDocContent.indexOf("#### `roadmap`");
217
- const unitDocOnly = roadmapIdx === -1 ? unitDocContent : unitDocContent.slice(0, roadmapIdx);
218
- ok(unitDocOnly.includes("| 0.1.0 | 2026-09-22 | feature | Added agwo edit"));
219
- });
220
- });
221
-
222
- // ── Budgets tests ────────────────────────────────────────────────────────
223
-
224
- describe("Budgets", () => {
225
- let budgetPath;
226
-
227
- before(() => {
228
- budgetPath = join(tmpDir, "budgets.json");
229
- const content = JSON.stringify({
230
- routes: {
231
- "execute-phase": { estimateMax: 1000, linesMax: 500, sources: {} },
232
- },
233
- }, null, 2);
234
- writeFileSync(budgetPath, content, "utf8");
235
- });
236
-
237
- it("budgets shrink without growth source is refused", () => {
238
- const receipt = ceilingRebase(budgetPath, "execute-phase", 500, 250, "");
239
- strictEqual(receipt.ok, false);
240
- });
241
-
242
- it("budgets shrink WITH growth source succeeds", () => {
243
- const receipt = ceilingRebase(budgetPath, "execute-phase", 500, 250, "Optimization: reduced scope");
244
- strictEqual(receipt.ok, true);
245
-
246
- const content = readFileSync(budgetPath, "utf8");
247
- const data = JSON.parse(content);
248
- strictEqual(data.routes["execute-phase"].estimateMax, 500);
249
- strictEqual(data.routes["execute-phase"].linesMax, 250);
250
- strictEqual(data.routes["execute-phase"].sources.ceilingRebase, "Optimization: reduced scope");
251
- });
252
- });
253
-
254
- // ── Manifest tests ───────────────────────────────────────────────────────
255
-
256
- describe("Manifest", () => {
257
- let pluginJsonPath;
258
-
259
- before(() => {
260
- pluginJsonPath = join(tmpDir, ".claude-plugin", "plugin.json");
261
- mkdirSync(join(pluginJsonPath, ".."), { recursive: true });
262
- const data = { skills: [] };
263
- writeFileSync(pluginJsonPath, JSON.stringify(data, null, 2), "utf8");
264
- });
265
-
266
- it("manifest add keeps alphabetical order", () => {
267
- skillAdd(pluginJsonPath, "zebra-skill", { description: "Z" });
268
- skillAdd(pluginJsonPath, "alpha-skill", { description: "A" });
269
- skillAdd(pluginJsonPath, "middle-skill", { description: "M" });
270
-
271
- const content = readFileSync(pluginJsonPath, "utf8");
272
- const parsed = JSON.parse(content);
273
- const names = parsed.skills.map((s) => s.name);
274
- strictEqual(names.length, 3);
275
- strictEqual(names[0], "alpha-skill");
276
- strictEqual(names[1], "middle-skill");
277
- strictEqual(names[2], "zebra-skill");
278
- });
279
-
280
- it("manifest add refuses duplicate", () => {
281
- throws(() => {
282
- skillAdd(pluginJsonPath, "alpha-skill", { description: "duplicate" });
283
- }, /already exists/);
284
- });
285
-
286
- it("manifest remove keeps alphabetical order", () => {
287
- skillRemove(pluginJsonPath, "middle-skill");
288
-
289
- const content = readFileSync(pluginJsonPath, "utf8");
290
- const parsed = JSON.parse(content);
291
- const names = parsed.skills.map((s) => s.name);
292
- strictEqual(names.length, 2);
293
- strictEqual(names[0], "alpha-skill");
294
- strictEqual(names[1], "zebra-skill");
295
- });
296
- });
297
-
298
- // ── Receipt tests ────────────────────────────────────────────────────────
299
-
300
- describe("Receipts", () => {
301
- it("receipts carry matching sha256 digests", () => {
302
- const receipt = setSection(specPath, "Why", "New reason");
303
- strictEqual(typeof receipt.before, "string");
304
- strictEqual(typeof receipt.after, "string");
305
- strictEqual(receipt.before.length, 8); // sha256 prefix is 8 chars
306
- strictEqual(receipt.after.length, 8);
307
- // Content changed so digests differ
308
- strictNotEqual(receipt.before, receipt.after);
309
- });
310
- });
311
-
312
- // ── CLI smoke test ───────────────────────────────────────────────────────
313
-
314
- describe("CLI smoke", () => {
315
- it("spawn bin/agwo.mjs unit-doc create --json parses", (t, done) => {
316
- const testDir = mkdtempSync(join(tmpdir(), "agwo-cli-"));
317
- const testUnitDir = join(testDir, "docs", "features", "cli-test");
318
- mkdirSync(testUnitDir, { recursive: true });
319
-
320
- const agwoPath = join(process.cwd(), "bin", "agwo.mjs");
321
-
322
- const proc = spawn("node", [agwoPath, "unit-doc", "cli-test", "create", "--json"], {
323
- cwd: testDir,
324
- timeout: 10000,
325
- });
326
-
327
- let stdout = "";
328
- let stderr = "";
329
-
330
- proc.stdout.on("data", (data) => { stdout += data.toString(); });
331
- proc.stderr.on("data", (data) => { stderr += data.toString(); });
332
-
333
- proc.on("close", (code) => {
334
- try {
335
- strictEqual(code, 0);
336
- const parsed = JSON.parse(stdout);
337
- strictEqual(parsed.ok, true);
338
- strictEqual(parsed.service, "unitDoc");
339
- strictEqual(parsed.op, "create");
340
- // Cleanup
341
- rmSync(testDir, { recursive: true, force: true });
342
- done();
343
- } catch (e) {
344
- rmSync(testDir, { recursive: true, force: true });
345
- done(e);
346
- }
347
- });
348
-
349
- proc.on("error", (e) => {
350
- rmSync(testDir, { recursive: true, force: true });
351
- done(e);
352
- });
353
- });
354
- });
355
-
356
- function strictNotEqual(a, b) {
357
- if (a === b) throw new Error(`Expected ${a} !== ${b}`);
358
- }