whywhy-mcp 0.1.0

package/dist/store.js

@@ -0,0 +1,181 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ConfigSchema, DEFAULT_CONFIG, DecisionRecordSchema, IndexSchema, SCHEMA_VERSION, } from "./schema.js";
+/**
+ * The on-disk decision store.
+ *
+ * Layout (relative to repo root):
+ *   .whywhy/
+ *     config.json
+ *     index.json
+ *     decisions/
+ *       DR-0001.json
+ *       ...
+ *
+ * Records are never deleted. The index is a derived, rolled-up view kept in
+ * sync on every write, but can be rebuilt from the decision files if needed.
+ */
+export class DecisionStore {
+    root;
+    storeDir;
+    decisionsDir;
+    indexPath;
+    configPath;
+    constructor(repoRoot, storePath = ".whywhy") {
+        this.root = repoRoot;
+        this.storeDir = path.resolve(repoRoot, storePath);
+        this.decisionsDir = path.join(this.storeDir, "decisions");
+        this.indexPath = path.join(this.storeDir, "index.json");
+        this.configPath = path.join(this.storeDir, "config.json");
+    }
+    async exists() {
+        try {
+            await fs.access(this.indexPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Create the store directories and seed config/index if missing. */
+    async init(config = {}) {
+        await fs.mkdir(this.decisionsDir, { recursive: true });
+        let cfg;
+        try {
+            cfg = await this.readConfig();
+        }
+        catch {
+            cfg = ConfigSchema.parse({ ...DEFAULT_CONFIG, ...config });
+            await this.writeConfig(cfg);
+        }
+        if (!(await this.exists())) {
+            const emptyIndex = {
+                schema_version: SCHEMA_VERSION,
+                next_id: 1,
+                decisions: [],
+            };
+            await this.writeIndex(emptyIndex);
+        }
+        return cfg;
+    }
+    async readConfig() {
+        const raw = await fs.readFile(this.configPath, "utf8");
+        return ConfigSchema.parse(JSON.parse(raw));
+    }
+    async writeConfig(config) {
+        await fs.mkdir(this.storeDir, { recursive: true });
+        await writeJson(this.configPath, config);
+    }
+    async readIndex() {
+        const raw = await fs.readFile(this.indexPath, "utf8");
+        return IndexSchema.parse(JSON.parse(raw));
+    }
+    async writeIndex(index) {
+        await writeJson(this.indexPath, index);
+    }
+    recordPath(id) {
+        return path.join(this.decisionsDir, `${id}.json`);
+    }
+    async readRecord(id) {
+        const raw = await fs.readFile(this.recordPath(id), "utf8");
+        return DecisionRecordSchema.parse(JSON.parse(raw));
+    }
+    async tryReadRecord(id) {
+        try {
+            return await this.readRecord(id);
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeRecord(record) {
+        DecisionRecordSchema.parse(record);
+        await fs.mkdir(this.decisionsDir, { recursive: true });
+        await writeJson(this.recordPath(record.id), record);
+        await this.upsertIndexEntry(record);
+    }
+    /** Reserve the next sequential ID, advancing the index counter. */
+    async allocateId() {
+        const index = await this.readIndex();
+        const id = `DR-${String(index.next_id).padStart(4, "0")}`;
+        index.next_id += 1;
+        await this.writeIndex(index);
+        return { id, index };
+    }
+    /** Insert or replace a record's index entry and persist the index. */
+    async upsertIndexEntry(record) {
+        const index = await this.readIndex();
+        const entry = {
+            id: record.id,
+            title: record.title,
+            category: record.category,
+            status: record.status,
+            tags: record.tags,
+            updated_at: record.updated_at,
+        };
+        const i = index.decisions.findIndex((d) => d.id === record.id);
+        if (i >= 0)
+            index.decisions[i] = entry;
+        else
+            index.decisions.push(entry);
+        await this.writeIndex(index);
+    }
+    async listEntries() {
+        const index = await this.readIndex();
+        return index.decisions;
+    }
+    async readAllRecords() {
+        const entries = await this.listEntries();
+        const records = [];
+        for (const entry of entries) {
+            const rec = await this.tryReadRecord(entry.id);
+            if (rec)
+                records.push(rec);
+        }
+        return records;
+    }
+    /** Rebuild index.json from the decision files on disk. */
+    async rebuildIndex() {
+        let files = [];
+        try {
+            files = await fs.readdir(this.decisionsDir);
+        }
+        catch {
+            files = [];
+        }
+        const decisions = [];
+        let maxId = 0;
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            const id = file.replace(/\.json$/, "");
+            const rec = await this.tryReadRecord(id);
+            if (!rec)
+                continue;
+            decisions.push({
+                id: rec.id,
+                title: rec.title,
+                category: rec.category,
+                status: rec.status,
+                tags: rec.tags,
+                updated_at: rec.updated_at,
+            });
+            const n = Number(rec.id.replace("DR-", ""));
+            if (Number.isFinite(n))
+                maxId = Math.max(maxId, n);
+        }
+        decisions.sort((a, b) => a.id.localeCompare(b.id));
+        const index = {
+            schema_version: SCHEMA_VERSION,
+            next_id: maxId + 1,
+            decisions,
+        };
+        await this.writeIndex(index);
+        return index;
+    }
+}
+async function writeJson(filePath, data) {
+    const json = JSON.stringify(data, null, 2) + "\n";
+    await fs.writeFile(filePath, json, "utf8");
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "whywhy-mcp",
+  "version": "0.1.0",
+  "description": "Agent-agnostic MCP server that records WHY architectural, product, and development decisions are made during AI-assisted coding.",
+  "license": "MIT",
+  "author": "Micky Multani",
+  "homepage": "https://github.com/mickymultani/whywhy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mickymultani/whywhy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mickymultani/whywhy/issues"
+  },
+  "type": "module",
+  "bin": {
+    "whywhy-mcp": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "server": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "decision-records",
+    "adr",
+    "ai-coding"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "simple-git": "^3.27.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}