catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/mcp_v2/package.json

@@ -6,9 +6,20 @@
     "main": "mcp.js",
     "scripts": {
         "setup": "node setup.js",
-        "start": "node mcp.js"
+        "start": "node mcp.js",
+        "test": "npm run test:types && vitest run",
+        "test:watch": "vitest",
+        "test:types": "tsc --noEmit"
     },
     "dependencies": {
-        "better-sqlite3": "^9.4.3"
+        "better-sqlite3": "12.4.6"
+    },
+    "devDependencies": {
+        "typescript": "^7.0.2",
+        "vitest": "^4.1.11",
+        "yaml": "^2.5.0"
+    },
+    "engines": {
+        "node": ">=20"
     }
 }

package/mcp_v2/scripts/copyErrorsIndex.cjs

@@ -0,0 +1,34 @@
+"use strict"
+
+// Copies the monorepo-root errors/index.json into this package's dist/ so
+// mcp_v2/tools/errors.js#explain_error can find it once catalyst-core is
+// installed as a real npm dependency — the repo-root errors/ directory is a
+// sibling of packages/catalyst-core, not inside it, so it never ends up in
+// a published tarball on its own.
+//
+// Run as part of the "prepare"/"prepublishOnly" scripts. Non-fatal if the
+// source file doesn't exist (e.g. running outside this monorepo, or before
+// generateDocs.js has ever run) — explain_error degrades to reporting every
+// code as non-catalyst-owned rather than failing the whole build.
+
+const fs = require("fs")
+const path = require("path")
+
+const SOURCE_PATH = path.join(__dirname, "..", "..", "..", "..", "errors", "index.json")
+const DEST_PATH = path.join(__dirname, "..", "..", "dist", "errors-index.json")
+
+function copyErrorsIndex() {
+    if (!fs.existsSync(SOURCE_PATH)) {
+        console.log(`[copyErrorsIndex] ${SOURCE_PATH} not found, skipping (run generateDocs.js first for explain_error to work)`)
+        return
+    }
+    fs.mkdirSync(path.dirname(DEST_PATH), { recursive: true })
+    fs.copyFileSync(SOURCE_PATH, DEST_PATH)
+    console.log(`[copyErrorsIndex] copied ${SOURCE_PATH} -> ${DEST_PATH}`)
+}
+
+if (require.main === module) {
+    copyErrorsIndex()
+}
+
+module.exports = { copyErrorsIndex }

package/mcp_v2/test/errors.test.ts

@@ -0,0 +1,123 @@
+// describe/it/expect come from vitest's `globals: true` config (see
+// vitest.config.mjs) — vitest's own exports can't be require()'d, only
+// import'd, so globals injects them instead.
+//
+// tools/errors.js itself is loaded via require() rather than import — it's
+// a CommonJS module, matching how it's actually loaded in production.
+// Typed against the hand-written declaration in ../tools/errors.d.ts rather
+// than left as `unknown` (errors.js stays plain JS until #420's source
+// conversion).
+const fs = require("fs")
+const path = require("path")
+const { init, handle_explain_error }: typeof import("../tools/errors.js") = require("../tools/errors.js")
+
+// Framework-level (Tier 1) contract tests for the explain_error MCP tool —
+// see issue #340/#411. Covers both real load paths (packaged dist/ copy and
+// the monorepo-root fallback) rather than mocking fs, since the whole point
+// of this module is "does the real file get found on disk."
+//
+// CAUTION: these tests move/restore errors/index.json and
+// dist/errors-index.json on real disk (with try/finally restoration). This
+// is safe run standalone or sequentially after other suites (see the root
+// test:unit script's `&&` chaining) but would race against any other suite
+// reading those same files concurrently in the same checkout — don't
+// parallelize this file's run against docsDrift.test.js or generateDocs.js.
+
+const PACKAGED_INDEX_PATH = path.join(__dirname, "..", "..", "dist", "errors-index.json")
+const MONOREPO_INDEX_PATH = path.join(__dirname, "..", "..", "..", "..", "errors", "index.json")
+
+function packagedIndexExists() {
+    return fs.existsSync(PACKAGED_INDEX_PATH)
+}
+
+describe("init() + handle_explain_error() — packaged path (dist/errors-index.json)", () => {
+    beforeAll(() => {
+        // This test only means something when the packaged copy actually
+        // exists — it's a build artifact (see mcp_v2/scripts/copyErrorsIndex.cjs
+        // + the "prepare" script), not guaranteed present in every checkout.
+        // Skip rather than false-fail if `npm run prepare` hasn't run yet.
+        if (!packagedIndexExists()) return
+        init()
+    })
+
+    it.runIf(packagedIndexExists())("finds a known code via the packaged path and reports it as catalyst-owned", () => {
+        const result = handle_explain_error({ code: "PREFLIGHT-001" })
+        expect(result.is_catalyst_owned).toBe(true)
+        expect(result.category).toBe("PREFLIGHT")
+        expect(result.message).toBeTruthy()
+        expect(result.docUrl).toContain("PREFLIGHT-001.md")
+    })
+})
+
+describe("init() + handle_explain_error() — monorepo-root fallback (errors/index.json)", () => {
+    let packagedBackup: Buffer | undefined
+
+    beforeAll(() => {
+        // Force the fallback path: temporarily move the packaged copy aside
+        // (if present) so init() must fall through to MONOREPO_INDEX_PATH.
+        if (fs.existsSync(PACKAGED_INDEX_PATH)) {
+            packagedBackup = fs.readFileSync(PACKAGED_INDEX_PATH)
+            fs.unlinkSync(PACKAGED_INDEX_PATH)
+        }
+        init()
+    })
+
+    afterAll(() => {
+        if (packagedBackup) fs.writeFileSync(PACKAGED_INDEX_PATH, packagedBackup)
+    })
+
+    it("finds a known code via the monorepo-root fallback", () => {
+        const result = handle_explain_error({ code: "PREFLIGHT-001" })
+        expect(result.is_catalyst_owned).toBe(true)
+        expect(result.category).toBe("PREFLIGHT")
+    })
+
+    it("reports a non-catalyst code as not owned, with a helpful note", () => {
+        const result = handle_explain_error({ code: "SOME-UPSTREAM-CODE" })
+        expect(result.is_catalyst_owned).toBe(false)
+        expect(result.note).toContain("not a catalyst-owned error code")
+    })
+
+    it("requires code and returns a clear error when it's missing", () => {
+        const result = handle_explain_error({})
+        expect(result.error).toMatch(/code is required/)
+    })
+
+    it("uses an own-property lookup — a code matching an inherited Object.prototype member is never misreported as catalyst-owned", () => {
+        expect(handle_explain_error({ code: "toString" }).is_catalyst_owned).toBe(false)
+        expect(handle_explain_error({ code: "constructor" }).is_catalyst_owned).toBe(false)
+        expect(handle_explain_error({ code: "hasOwnProperty" }).is_catalyst_owned).toBe(false)
+    })
+})
+
+describe("init() — neither path resolvable", () => {
+    let packagedBackup: Buffer | undefined
+
+    beforeAll(() => {
+        if (fs.existsSync(PACKAGED_INDEX_PATH)) {
+            packagedBackup = fs.readFileSync(PACKAGED_INDEX_PATH)
+            fs.unlinkSync(PACKAGED_INDEX_PATH)
+        }
+    })
+
+    afterAll(() => {
+        if (packagedBackup) fs.writeFileSync(PACKAGED_INDEX_PATH, packagedBackup)
+        // Restore real state for any test file that runs after this one in
+        // the same process (vitest may share workers across files).
+        init()
+    })
+
+    it("degrades gracefully — reports a load error instead of throwing, when errors/index.json genuinely can't be read", () => {
+        // Simulate by pointing init() at a broken state: rename the real
+        // monorepo index aside temporarily.
+        const monorepoBackup = fs.readFileSync(MONOREPO_INDEX_PATH)
+        fs.unlinkSync(MONOREPO_INDEX_PATH)
+        try {
+            init()
+            const result = handle_explain_error({ code: "PREFLIGHT-001" })
+            expect(result.error).toMatch(/Could not load errors\/index\.json/)
+        } finally {
+            fs.writeFileSync(MONOREPO_INDEX_PATH, monorepoBackup)
+        }
+    })
+})

package/mcp_v2/test/github.test.ts

@@ -0,0 +1,177 @@
+// describe/it/expect come from vitest's `globals: true` config (see
+// vitest.config.mjs). tools/github.js is CommonJS, loaded via require() and
+// typed against the hand-written declaration in ../tools/github.d.ts (that
+// file stays plain JS for now — same rationale as errors.js / issue #420).
+const fs = require("fs")
+const path = require("path")
+const YAML = require("yaml")
+const github: typeof import("../tools/github.js") = require("../tools/github.js")
+
+// Drift guard: the MCP carries a code-embedded copy of the repo's issue and
+// PR templates (ISSUE_TEMPLATES / PR_TEMPLATES in tools/github.js) so an
+// agent raising an issue or PR through the MCP produces the same structure
+// as one raised through the GitHub UI. This suite asserts the two copies
+// can't diverge — the same stance as test/errors.test.ts: check the real
+// files on disk, don't mock fs.
+//
+// mcp_v2 lives four levels under the repo root
+// (packages/catalyst-core/mcp_v2/test → repo root), matching
+// MONOREPO_INDEX_PATH's resolution in errors.test.ts.
+const ISSUE_TEMPLATE_DIR = path.join(__dirname, "..", "..", "..", "..", ".github", "ISSUE_TEMPLATE")
+const PR_TEMPLATE_DIR = path.join(__dirname, "..", "..", "..", "..", ".github", "PULL_REQUEST_TEMPLATE")
+
+function templatesOnDisk() {
+    return fs.existsSync(ISSUE_TEMPLATE_DIR) && fs.existsSync(PR_TEMPLATE_DIR)
+}
+
+// The ordered `##` headings of a Markdown PR template, minus the shared
+// footer checklist (which lives in PR_FOOTER_CHECKLIST, asserted separately).
+function prTemplateSections(md: string): string[] {
+    return [...md.matchAll(/^##\s+(.+?)\s*$/gm)].map((m) => m[1])
+}
+
+// The ordered field labels of a GitHub issue form, minus `markdown` blocks
+// (intro prose) and the `checkboxes` Preflight Checklist (form-only UX, not
+// a content section the MCP renders).
+function issueFormSections(form: { body?: Array<Record<string, any>> }): string[] {
+    return (form.body || [])
+        .filter((b) => b.type !== "markdown")
+        .filter((b) => !(b.type === "checkboxes" && b.attributes?.label === "Preflight Checklist"))
+        .map((b) => b.attributes.label)
+}
+
+describe.skipIf(!templatesOnDisk())("issue forms ↔ ISSUE_TEMPLATES", () => {
+    for (const key of Object.keys(github.ISSUE_TEMPLATES)) {
+        const tmpl = github.ISSUE_TEMPLATES[key]
+
+        it(`${key}.yml exists and its label matches`, () => {
+            const file = path.join(ISSUE_TEMPLATE_DIR, `${key}.yml`)
+            expect(fs.existsSync(file)).toBe(true)
+            const form = YAML.parse(fs.readFileSync(file, "utf8"))
+            expect(form.labels).toContain(tmpl.label)
+        })
+
+        it(`${key}.yml body fields match ISSUE_TEMPLATES.${key}.sections in order`, () => {
+            const form = YAML.parse(fs.readFileSync(path.join(ISSUE_TEMPLATE_DIR, `${key}.yml`), "utf8"))
+            // "Preflight Checklist" may appear in tmpl.sections (bug) — the MCP
+            // renders it there — but it's a checkboxes block in the form, so
+            // compare against the form's non-preflight sections either way.
+            const want = tmpl.sections.filter((s) => s !== "Preflight Checklist")
+            expect(issueFormSections(form)).toEqual(want)
+        })
+    }
+
+    it("config.yml disables blank issues", () => {
+        const cfg = YAML.parse(fs.readFileSync(path.join(ISSUE_TEMPLATE_DIR, "config.yml"), "utf8"))
+        expect(cfg.blank_issues_enabled).toBe(false)
+    })
+
+    it("every ISSUE_TEMPLATE/*.yml (except config) has a matching ISSUE_TEMPLATES key", () => {
+        const files = fs
+            .readdirSync(ISSUE_TEMPLATE_DIR)
+            .filter((f: string) => f.endsWith(".yml") && f !== "config.yml")
+            .map((f: string) => f.replace(/\.yml$/, ""))
+        expect(files.sort()).toEqual(Object.keys(github.ISSUE_TEMPLATES).sort())
+    })
+})
+
+describe.skipIf(!templatesOnDisk())("PR templates ↔ PR_TEMPLATES", () => {
+    for (const key of Object.keys(github.PR_TEMPLATES) as Array<"fix" | "feature" | "chore">) {
+        const tmpl = github.PR_TEMPLATES[key]
+
+        it(`${key}.md exists and its ## headings match PR_TEMPLATES.${key}.sections in order`, () => {
+            const file = path.join(PR_TEMPLATE_DIR, `${key}.md`)
+            expect(fs.existsSync(file)).toBe(true)
+            const md = fs.readFileSync(file, "utf8")
+            expect(prTemplateSections(md)).toEqual(tmpl.sections)
+        })
+
+        it(`${key}.md ends with the shared footer checklist`, () => {
+            const md = fs.readFileSync(path.join(PR_TEMPLATE_DIR, `${key}.md`), "utf8")
+            for (const line of github.PR_FOOTER_CHECKLIST.split("\n")) {
+                expect(md).toContain(line)
+            }
+        })
+    }
+
+    it("the default PULL_REQUEST_TEMPLATE.md carries the shared footer checklist", () => {
+        const md = fs.readFileSync(path.join(PR_TEMPLATE_DIR, "..", "PULL_REQUEST_TEMPLATE.md"), "utf8")
+        for (const line of github.PR_FOOTER_CHECKLIST.split("\n")) {
+            expect(md).toContain(line)
+        }
+    })
+
+    it("every PULL_REQUEST_TEMPLATE/*.md has a matching PR_TEMPLATES key", () => {
+        const files = fs
+            .readdirSync(PR_TEMPLATE_DIR)
+            .filter((f: string) => f.endsWith(".md"))
+            .map((f: string) => f.replace(/\.md$/, ""))
+        expect(files.sort()).toEqual(Object.keys(github.PR_TEMPLATES).sort())
+    })
+})
+
+describe("handle_create_github_pr() — dry run rendering", () => {
+    beforeAll(() => github.init({ dir: process.cwd() }))
+
+    it("renders a fix PR body in template section order with the footer", async () => {
+        const res: any = await github.handle_create_github_pr({
+            change_type: "fix",
+            title: "fix: thing",
+            root_cause: "the widget cache key collided",
+            repro: "1. open two tabs",
+            fix: "namespace the key",
+            regression_test: "added cache-key.test.ts",
+            head: "feature/x",
+            base: "epic/329",
+            dry_run: true,
+        })
+        expect(res.ok).toBe(true)
+        expect(res.dry_run).toBe(true)
+        expect(res.preview.change_type).toBe("fix")
+        const headings = prTemplateSections(res.preview.body)
+        expect(headings).toEqual(["Root cause", "Repro", "Fix", "Regression test", "Affected error codes"])
+        expect(res.preview.body).toContain(github.PR_FOOTER_CHECKLIST.split("\n")[0])
+    })
+
+    it("infers change_type from the title when not given", async () => {
+        const res: any = await github.handle_create_github_pr({
+            title: "feat: add useTool hook",
+            summary: "new imperative WebMCP hook",
+            head: "feature/x",
+            base: "main",
+            dry_run: true,
+        })
+        expect(res.preview.change_type).toBe("feature")
+    })
+
+    it("prepends Closes #<n> when closes_issue is set", async () => {
+        const res: any = await github.handle_create_github_pr({
+            change_type: "chore",
+            title: "chore: bump x",
+            summary: "routine bump",
+            closes_issue: 441,
+            head: "feature/x",
+            base: "main",
+            dry_run: true,
+        })
+        expect(res.preview.body.startsWith("Closes #441")).toBe(true)
+    })
+
+    it("requires a title", async () => {
+        const res: any = await github.handle_create_github_pr({ summary: "x" })
+        expect(res.ok).toBe(false)
+        expect(res.error).toMatch(/title is required/)
+    })
+
+    it("rejects head === base", async () => {
+        const res: any = await github.handle_create_github_pr({
+            title: "chore: x",
+            summary: "x",
+            head: "main",
+            base: "main",
+            dry_run: true,
+        })
+        expect(res.ok).toBe(false)
+        expect(res.error).toMatch(/same branch/)
+    })
+})

package/mcp_v2/tools/errors.d.ts

@@ -0,0 +1,20 @@
+// Hand-written type declaration for errors.js — that file stays plain CJS
+// until a future source conversion (see issue #420); this exists only so
+// require("../tools/errors.js") gets real types in test/errors.test.ts
+// instead of `unknown`. Keep in sync with errors.js's actual shape by hand
+// for now.
+
+export interface ExplainErrorResult {
+    code?: string
+    error?: string
+    is_catalyst_owned?: boolean
+    category?: string
+    message?: string
+    details?: string
+    suggestedAction?: string
+    docUrl?: string
+    note?: string
+}
+
+export function init(): void
+export function handle_explain_error(args?: { code?: string }): ExplainErrorResult

package/mcp_v2/tools/errors.js

@@ -0,0 +1,63 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+let _index = null
+let _loadError = null
+
+// Prefer the copy published inside the package itself (dist/errors-index.json,
+// see the "prepare" script) — the repo-root errors/ directory is a sibling of
+// packages/catalyst-core, not inside it, so it never ends up in a published
+// tarball. Fall back to the repo-root path for local dev inside this
+// monorepo, where dist/errors-index.json may not have been generated yet.
+const PACKAGED_INDEX_PATH = path.join(__dirname, "..", "..", "dist", "errors-index.json")
+const MONOREPO_INDEX_PATH = path.join(__dirname, "..", "..", "..", "..", "errors", "index.json")
+
+function init() {
+    for (const candidate of [PACKAGED_INDEX_PATH, MONOREPO_INDEX_PATH]) {
+        try {
+            _index = JSON.parse(fs.readFileSync(candidate, "utf-8"))
+            _loadError = null
+            return
+        } catch (e) {
+            _loadError = e
+        }
+    }
+    _index = {}
+}
+
+function handle_explain_error({ code } = {}) {
+    if (!code) {
+        return { error: "code is required, e.g. 'PREFLIGHT-001'" }
+    }
+
+    if (_loadError) {
+        return {
+            code,
+            error: `Could not load errors/index.json (run generateDocs.js): ${_loadError.message}`,
+        }
+    }
+
+    const entry = Object.prototype.hasOwnProperty.call(_index, code) ? _index[code] : null
+
+    if (!entry) {
+        return {
+            code,
+            is_catalyst_owned: false,
+            note: `"${code}" is not a catalyst-owned error code. It likely came from an upstream tool (Vite, Rollup, Xcode, Gradle, etc). Catalyst does not reinterpret foreign error codes — check the upstream tool's own documentation for this code.`,
+        }
+    }
+
+    return {
+        code,
+        is_catalyst_owned: true,
+        category: entry.category,
+        message: entry.message,
+        details: entry.details,
+        suggestedAction: entry.suggestedAction,
+        docUrl: entry.docUrl,
+    }
+}
+
+module.exports = { init, handle_explain_error }

package/mcp_v2/tools/github.d.ts

@@ -0,0 +1,41 @@
+// Hand-written type declaration for github.js — that file stays plain CJS
+// for now (same rationale as errors.d.ts / issue #420). This exists only so
+// require("../tools/github.js") gets real types in test/github.test.ts
+// instead of `unknown`. Keep in sync with github.js's actual exports by hand.
+
+export interface IssueTemplate {
+    label: string
+    name: string
+    use_when: string
+    sections: string[]
+}
+
+export interface PrTemplate {
+    change_type: "fix" | "feature" | "chore"
+    name: string
+    use_when: string
+    sections: string[]
+}
+
+export const ISSUE_TEMPLATES: Record<string, IssueTemplate>
+export const PR_TEMPLATES: Record<"fix" | "feature" | "chore", PrTemplate>
+export const PR_FOOTER_CHECKLIST: string
+export const DEFAULT_LABELS: string[]
+
+export function init(projectInfo?: unknown): void
+
+export function handle_create_github_issue(args?: Record<string, unknown>): Promise<Record<string, unknown>>
+
+export function handle_create_github_pr(args?: {
+    change_type?: "fix" | "feature" | "chore"
+    title?: string
+    body?: string
+    summary?: string
+    head?: string
+    base?: string
+    draft?: boolean
+    dry_run?: boolean
+    closes_issue?: string | number
+    project_path?: string
+    [key: string]: unknown
+}): Promise<Record<string, unknown>>