stoa-mcp 0.1.0

package/dist/utils/spec-helpers.js

@@ -0,0 +1,95 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+export class InvalidSpecNameError extends Error {
+    code = "INVALID_SPEC_NAME";
+    constructor(message = "Invalid spec name") {
+        super(message);
+        this.name = "InvalidSpecNameError";
+    }
+}
+export function validateSpecName(name) {
+    if (name === "" || name.trim() === "") {
+        throw new InvalidSpecNameError("Spec name must not be empty");
+    }
+    if (name.includes("/") || name.includes("\\")) {
+        throw new InvalidSpecNameError("Spec name must not contain path separators");
+    }
+}
+export class SpecNotFoundError extends Error {
+    code = "NO_SPECS";
+    constructor(message = "No specs found. Run stoa refine <task> first.") {
+        super(message);
+        this.name = "SpecNotFoundError";
+    }
+}
+export async function resolveSpecName(name) {
+    if (name !== undefined) {
+        validateSpecName(name);
+        return name;
+    }
+    const specsDir = join(process.cwd(), ".stoa", "specs");
+    let entries;
+    try {
+        entries = await readdir(specsDir);
+    }
+    catch {
+        throw new SpecNotFoundError();
+    }
+    const dirs = [];
+    for (const entry of entries) {
+        const s = await stat(join(specsDir, entry));
+        if (s.isDirectory()) {
+            dirs.push({ name: entry, mtime: s.mtimeMs });
+        }
+    }
+    if (dirs.length === 0) {
+        throw new SpecNotFoundError();
+    }
+    dirs.sort((a, b) => b.mtime - a.mtime);
+    return dirs[0].name;
+}
+const SPEC_FILES = [
+    "01-problem-statement.md",
+    "02-acceptance-criteria.md",
+    "03-constraints.md",
+    "04-decomposition.md",
+    "05-evaluation-design.md",
+    "user-notes.md",
+    "moodboard.md",
+];
+const FrontMatterSchema = z.object({}).passthrough();
+function hasYamlFrontMatter(content) {
+    return content.startsWith("---\n") || content.startsWith("---\r\n");
+}
+function isJsonContent(content) {
+    const trimmed = content.trimStart();
+    return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+export async function snapshotSpecFiles(specDir) {
+    const result = {};
+    for (const filename of SPEC_FILES) {
+        const filePath = join(specDir, filename);
+        let content;
+        try {
+            content = await readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                "code" in err &&
+                err.code === "ENOENT") {
+                continue;
+            }
+            throw err;
+        }
+        if (hasYamlFrontMatter(content)) {
+            FrontMatterSchema.parse({});
+        }
+        else if (isJsonContent(content)) {
+            z.record(z.string(), z.unknown()).parse(JSON.parse(content));
+        }
+        result[filename] = content;
+    }
+    return result;
+}
+//# sourceMappingURL=spec-helpers.js.map

package/dist/utils/spec-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-helpers.js","sourceRoot":"","sources":["../../src/utils/spec-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,mBAA4B,CAAC;IAE7C,YAAY,UAAkB,mBAAmB;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,oBAAoB,CAAC,6BAA6B,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,oBAAoB,CAAC,4CAA4C,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,GAAG,UAAmB,CAAC;IAEpC,YAAY,UAAkB,+CAA+C;QAC3E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAa;IACjD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEvD,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iBAAiB,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,IAAI,GAAsC,EAAE,CAAC;IAEnD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QAC5C,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,iBAAiB,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,GAAG;IACjB,yBAAyB;IACzB,2BAA2B;IAC3B,mBAAmB;IACnB,qBAAqB;IACrB,yBAAyB;IACzB,eAAe;IACf,cAAc;CACN,CAAC;AAEX,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAErD,SAAS,kBAAkB,CAAC,OAAe;IACzC,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IACpC,OAAO,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe;IAEf,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzC,IAAI,OAAe,CAAC;QAEpB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IACE,GAAG,YAAY,KAAK;gBACpB,MAAM,IAAI,GAAG;gBACZ,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAChD,CAAC;gBACD,SAAS;YACX,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC;IAC7B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/spec-helpers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spec-helpers.test.d.ts.map

package/dist/utils/spec-helpers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-helpers.test.d.ts","sourceRoot":"","sources":["../../src/utils/spec-helpers.test.ts"],"names":[],"mappings":""}

package/dist/utils/spec-helpers.test.js

@@ -0,0 +1,114 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveSpecName, snapshotSpecFiles, SpecNotFoundError } from "./spec-helpers.js";
+const TEST_ROOT = join(process.cwd(), ".stoa-test-helpers");
+const SPECS_DIR = join(TEST_ROOT, ".stoa", "specs");
+describe("resolveSpecName", () => {
+    beforeEach(async () => {
+        await rm(TEST_ROOT, { recursive: true, force: true });
+    });
+    afterEach(async () => {
+        await rm(TEST_ROOT, { recursive: true, force: true });
+    });
+    it("returns the provided name when given", async () => {
+        const result = await resolveSpecName("my-spec");
+        assert.equal(result, "my-spec");
+    });
+    it("throws SpecNotFoundError when .stoa/specs/ does not exist", async () => {
+        const originalCwd = process.cwd();
+        await mkdir(TEST_ROOT, { recursive: true });
+        process.chdir(TEST_ROOT);
+        try {
+            await assert.rejects(() => resolveSpecName(), (err) => {
+                assert.ok(err instanceof SpecNotFoundError);
+                assert.equal(err.message, "No specs found. Run stoa refine <task> first.");
+                assert.equal(err.code, "NO_SPECS");
+                return true;
+            });
+        }
+        finally {
+            process.chdir(originalCwd);
+        }
+    });
+    it("throws SpecNotFoundError when .stoa/specs/ has no subdirectories", async () => {
+        const originalCwd = process.cwd();
+        await mkdir(SPECS_DIR, { recursive: true });
+        await writeFile(join(SPECS_DIR, "some-file.txt"), "not a dir");
+        process.chdir(TEST_ROOT);
+        try {
+            await assert.rejects(() => resolveSpecName(), (err) => {
+                assert.ok(err instanceof SpecNotFoundError);
+                return true;
+            });
+        }
+        finally {
+            process.chdir(originalCwd);
+        }
+    });
+    it("returns the most recently modified subdirectory", async () => {
+        const originalCwd = process.cwd();
+        await mkdir(join(SPECS_DIR, "older-spec"), { recursive: true });
+        // Small delay to ensure different mtime
+        await new Promise((r) => setTimeout(r, 50));
+        await mkdir(join(SPECS_DIR, "newer-spec"), { recursive: true });
+        process.chdir(TEST_ROOT);
+        try {
+            const result = await resolveSpecName();
+            assert.equal(result, "newer-spec");
+        }
+        finally {
+            process.chdir(originalCwd);
+        }
+    });
+});
+describe("snapshotSpecFiles", () => {
+    const specDir = join(TEST_ROOT, "test-spec");
+    beforeEach(async () => {
+        await rm(TEST_ROOT, { recursive: true, force: true });
+        await mkdir(specDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await rm(TEST_ROOT, { recursive: true, force: true });
+    });
+    it("returns only filenames that exist on disk", async () => {
+        await writeFile(join(specDir, "01-problem-statement.md"), "# My Description");
+        await writeFile(join(specDir, "02-acceptance-criteria.md"), "## Criteria");
+        const result = await snapshotSpecFiles(specDir);
+        assert.ok("01-problem-statement.md" in result);
+        assert.ok("02-acceptance-criteria.md" in result);
+        assert.ok(!("03-constraints.md" in result));
+        assert.ok(!("04-decomposition.md" in result));
+        assert.ok(!("05-evaluation-design.md" in result));
+        assert.ok(!("user-notes.md" in result));
+        assert.ok(!("moodboard.md" in result));
+        assert.equal(Object.keys(result).length, 2);
+    });
+    it("returns all 7 keys when all files are present", async () => {
+        const allFiles = [
+            "01-problem-statement.md",
+            "02-acceptance-criteria.md",
+            "03-constraints.md",
+            "04-decomposition.md",
+            "05-evaluation-design.md",
+            "user-notes.md",
+            "moodboard.md",
+        ];
+        for (const f of allFiles) {
+            await writeFile(join(specDir, f), `Content of ${f}`);
+        }
+        const result = await snapshotSpecFiles(specDir);
+        assert.equal(Object.keys(result).length, 7);
+        for (const f of allFiles) {
+            assert.ok(f in result);
+            assert.equal(result[f], `Content of ${f}`);
+        }
+    });
+    it("returns empty record when no recognized files exist", async () => {
+        await writeFile(join(specDir, "unrecognized.md"), "content");
+        const result = await snapshotSpecFiles(specDir);
+        assert.equal(Object.keys(result).length, 0);
+    });
+});
+//# sourceMappingURL=spec-helpers.test.js.map

package/dist/utils/spec-helpers.test.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "stoa-mcp",
+  "version": "0.1.0",
+  "description": "The Specification Compiler for AI Agents. Transform vague tasks into executable specs with blind test scenarios.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "stoa": "dist/cli.js",
+    "stoa-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "tsc && node --test dist/core/parsers.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "specification",
+    "ai-coding",
+    "spec-score",
+    "refine",
+    "claude",
+    "cursor",
+    "guardrails"
+  ],
+  "author": "Lambis Stratoudakis",
+  "license": "BSL-1.1",
+  "homepage": "https://stoa.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LambisStratoudakis/stoa-mcp"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "ora": "^9.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/guardrails/ask-when-unclear.md

@@ -0,0 +1,3 @@
+# Ask When Unclear
+
+If requirements are ambiguous or conflicting, stop and ask for clarification before writing code. Do not make silent assumptions about business logic, data models, or user-facing behavior.

package/templates/guardrails/dont-delete-code.md

@@ -0,0 +1,3 @@
+# Don't Delete Code
+
+Do not delete existing code, functions, or files unless the task explicitly asks for removal. Comment out or deprecate instead. If removal seems necessary, explain why before doing it.

package/templates/guardrails/explain-changes.md

@@ -0,0 +1,3 @@
+# Explain Changes
+
+Always explain what you changed and why. Every file modification should have a one-sentence reason. If you're making a choice between approaches, state which you chose and why.

package/templates/guardrails/run-tests.md

@@ -0,0 +1,3 @@
+# Run Tests
+
+Before declaring a task done, run the project's existing test suite. If tests fail, fix them. If no tests exist, state that explicitly. Never say "done" with failing tests.

package/templates/guardrails/small-changes.md

@@ -0,0 +1,3 @@
+# Small Changes
+
+Keep changes small and focused. One task, one purpose. Don't combine a bug fix with a refactor. Don't add a feature while fixing a typo. If you notice something else that needs fixing, note it but don't fix it in this session.

package/templates/roles/builder.md

@@ -0,0 +1,3 @@
+# Builder
+
+You build software. Write clean, working code that follows the project's existing conventions and patterns. When you see an established pattern in the codebase, follow it. If a task is ambiguous, pick the simplest approach that satisfies the acceptance criteria. Don't refactor code that isn't part of the task. Don't add features that weren't requested.

package/templates/roles/fixer.md

@@ -0,0 +1,3 @@
+# Fixer
+
+You fix bugs. Read the error, trace the root cause, fix only what's broken. Don't refactor unrelated code. Don't "improve" things that aren't part of the bug. If the fix requires changing more than 3 files, stop and explain why before proceeding. Always verify your fix by describing how to reproduce the original bug and confirming it no longer occurs.

package/templates/roles/planner.md

@@ -0,0 +1,3 @@
+# Planner
+
+You break big ideas into small, buildable tasks. Each task should be completable in a single session (under 2 hours). Be specific about what "done" looks like for each task. Include file paths when you know them. Order tasks so dependencies come first. If a task is too vague to build, say what information is missing.