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

package/mcp_v2/tools/github.js

@@ -120,6 +120,41 @@ const ISSUE_TEMPLATES = {
     },
 }
 
+// Pull-request templates, one per change type. Section lists mirror the
+// `##` headings in .github/PULL_REQUEST_TEMPLATE/<change_type>.md exactly —
+// the drift test in test/github.test.ts asserts that, the same way it
+// checks ISSUE_TEMPLATES against .github/ISSUE_TEMPLATE/*.yml.
+const PR_TEMPLATES = {
+    fix: {
+        change_type: "fix",
+        name: "Bug fix",
+        use_when: "The PR corrects broken, ignored, regressed, or misdocumented behavior.",
+        sections: ["Root cause", "Repro", "Fix", "Regression test", "Affected error codes"],
+    },
+    feature: {
+        change_type: "feature",
+        name: "Feature",
+        use_when: "The PR adds a new capability, hook, CLI behavior, or framework ergonomics change.",
+        sections: ["What", "Why", "New error codes", "Test coverage"],
+    },
+    chore: {
+        change_type: "chore",
+        name: "Chore (no behaviour change)",
+        use_when:
+            "The PR changes deps, CI, tooling, docs, or internal structure with no runtime behavior change.",
+        sections: ["What triggered this", "Change", "No behaviour change"],
+    },
+}
+
+// Appended verbatim to every rendered PR body. Kept in sync with the shared
+// footer in .github/PULL_REQUEST_TEMPLATE*.md (also asserted by the drift test).
+const PR_FOOTER_CHECKLIST = [
+    "- [ ] `npm run test:unit` passes locally",
+    "- [ ] `npm run lint` passes locally",
+    "- [ ] No new raw `throw new Error(...)` in changed files",
+    "- [ ] Coverage gate (`coverage-summary`, #415/#437) not regressed",
+].join("\n")
+
 function init(projectInfo) {
     _projectInfo = projectInfo
 }
@@ -1122,7 +1157,203 @@ async function handle_create_github_issue(args = {}) {
     }
 }
 
+// ── Pull request workflow ────────────────────────────────────────────────────
+
+function resolvePrChangeType(args) {
+    const requested = typeof args.change_type === "string" ? args.change_type.trim().toLowerCase() : ""
+    if (PR_TEMPLATES[requested]) return requested
+
+    const text = `${args.title || ""}\n${args.summary || args.body || ""}`.toLowerCase()
+    if (/\b(fix|bug|regress|broken|crash|incorrect)\b/.test(text)) return "fix"
+    if (/\b(feat|feature|add\s+support|new\s+(hook|api|capability))\b/.test(text)) return "feature"
+    return "chore"
+}
+
+// Compose a PR body in the shape of the matching .github/PULL_REQUEST_TEMPLATE
+// file. Pre-structured markdown (already has `##` headings) is passed through
+// untouched; otherwise the structured per-type fields are laid out in the
+// template's section order. The shared footer checklist is always appended.
+function buildPrBody(args) {
+    const changeType = resolvePrChangeType(args)
+    const rawBody = stripExistingFooter(args.body)
+    const closesLine =
+        args.closes_issue != null && `${args.closes_issue}`.trim()
+            ? `Closes #${`${args.closes_issue}`.replace(/^#/, "").trim()}`
+            : ""
+
+    let content
+    if (rawBody && hasMarkdownHeadings(rawBody)) {
+        content = rawBody
+    } else {
+        const sections = []
+        if (changeType === "fix") {
+            appendSection(sections, "Root cause", firstNonEmpty(args.root_cause, args.summary, rawBody))
+            appendSection(sections, "Repro", args.repro || args.steps_to_reproduce)
+            appendSection(sections, "Fix", firstNonEmpty(args.fix, args.proposed_fix))
+            appendSection(sections, "Regression test", args.regression_test)
+            appendSection(sections, "Affected error codes", firstNonEmpty(args.affected_error_codes, "none"))
+        } else if (changeType === "feature") {
+            appendSection(sections, "What", firstNonEmpty(args.what, args.summary, rawBody))
+            appendSection(sections, "Why", firstNonEmpty(args.why, args.motivation))
+            appendSection(
+                sections,
+                "New error codes",
+                firstNonEmpty(args.new_error_codes, "No new error codes")
+            )
+            appendSection(sections, "Test coverage", args.coverage_delta || args.test_coverage)
+        } else {
+            appendSection(
+                sections,
+                "What triggered this",
+                firstNonEmpty(args.change_trigger, args.summary, rawBody)
+            )
+            appendSection(sections, "Change", firstNonEmpty(args.change, args.summary, rawBody))
+            appendSection(
+                sections,
+                "No behaviour change",
+                args.no_behaviour_change === true || args.no_behaviour_change === "true"
+                    ? "- [x] Confirmed: no runtime behaviour change — output, public API, and error codes are unchanged"
+                    : "- [ ] Confirmed: no runtime behaviour change — output, public API, and error codes are unchanged"
+            )
+        }
+        content = sections.join("\n\n").trim()
+    }
+
+    const body = [closesLine, content, "---", PR_FOOTER_CHECKLIST].filter(Boolean).join("\n\n").trim()
+
+    return { change_type: changeType, body }
+}
+
+async function handle_create_github_pr(args = {}) {
+    const { title } = args
+    if (!title || typeof title !== "string" || title.trim() === "") {
+        return { ok: false, error: "title is required and must be a non-empty string." }
+    }
+    if (
+        !firstNonEmpty(args.body, args.summary, args.root_cause, args.what, args.change, args.change_trigger)
+    ) {
+        return {
+            ok: false,
+            error: "body or a structured field (summary / root_cause / what / change / change_trigger) is required.",
+        }
+    }
+
+    const root = getProjectRoot(args)
+    const head = firstNonEmpty(args.head, runGit(root, "git rev-parse --abbrev-ref HEAD")) || ""
+    if (!head || head === "HEAD") {
+        return {
+            ok: false,
+            error: "Could not resolve the head branch. Pass head explicitly (you may be in a detached HEAD).",
+        }
+    }
+    const base = firstNonEmpty(args.base) || "main"
+    if (head === base) {
+        return { ok: false, error: `head and base are the same branch (${head}).` }
+    }
+
+    const { change_type: changeType, body } = buildPrBody(args)
+    const draft = args.draft !== false
+    const dryRun = args.dry_run !== false
+
+    const remoteHead = runGit(root, `git rev-parse --verify --quiet origin/${head}`)
+    const commits = runGit(root, `git log --oneline origin/${base}..${head} 2>/dev/null`) || ""
+    const tokenResult = getToken()
+
+    const preview = {
+        type: "pull_request",
+        repo: `${GITHUB_OWNER}/${GITHUB_REPO}`,
+        title: title.trim(),
+        head,
+        base,
+        draft,
+        change_type: changeType,
+        suggested_template: PR_TEMPLATES[changeType],
+        body,
+        head_pushed: Boolean(remoteHead),
+        commits_ahead_of_base: commits ? commits.split("\n") : [],
+    }
+
+    if (dryRun) {
+        return {
+            ok: true,
+            dry_run: true,
+            preview,
+            token_source: tokenResult.ok ? tokenResult.source : "none",
+            auth_warning: tokenResult.ok ? null : tokenResult.error,
+            push_warning: remoteHead
+                ? null
+                : `origin/${head} not found — push the branch before publishing: git push -u origin ${head}`,
+            instructions:
+                "Show the rendered PR preview (title, head → base, change type, body) to the developer. Ask whether to edit, cancel, or publish. Publish only after explicit approval with dry_run:false.",
+            next_action:
+                "Wait for explicit developer approval before calling create_github_pr with dry_run:false.",
+        }
+    }
+
+    if (!remoteHead) {
+        return {
+            ok: false,
+            blocked: true,
+            error: `origin/${head} does not exist. Push the branch first: git push -u origin ${head}`,
+            preview,
+        }
+    }
+
+    if (!tokenResult.ok) {
+        return { ok: false, error: tokenResult.error, preview }
+    }
+
+    try {
+        const res = await githubRequest(
+            "POST",
+            `/repos/${GITHUB_OWNER}/${GITHUB_REPO}/pulls`,
+            tokenResult.token,
+            { title: title.trim(), head, base, body, draft }
+        )
+
+        if (res.status === 201) {
+            return {
+                ok: true,
+                message: `PR #${res.body.number} created successfully.`,
+                number: res.body.number,
+                url: res.body.html_url,
+                head,
+                base,
+                draft: res.body.draft,
+                change_type: changeType,
+                token_source: tokenResult.source,
+            }
+        }
+
+        const apiMessage = res.body && res.body.message ? res.body.message : JSON.stringify(res.body)
+        const fallbackDir = ensureFallbackDir(root)
+        const fallbackPath = path.join(
+            fallbackDir,
+            `${new Date().toISOString().replace(/[:.]/g, "-")}-pr-${slugify(title)}.md`
+        )
+        fs.writeFileSync(
+            fallbackPath,
+            [`# ${title.trim()}`, "", `Base: ${base} · Head: ${head}`, "", "## Body", "", body, ""].join(
+                "\n"
+            ),
+            "utf8"
+        )
+        return {
+            ok: false,
+            error: `GitHub API returned HTTP ${res.status}: ${apiMessage}`,
+            fallback: { markdown_path: fallbackPath },
+        }
+    } catch (err) {
+        return { ok: false, error: `Network error while calling GitHub API: ${err.message}` }
+    }
+}
+
 module.exports = {
     init,
     handle_create_github_issue,
+    handle_create_github_pr,
+    ISSUE_TEMPLATES,
+    PR_TEMPLATES,
+    PR_FOOTER_CHECKLIST,
+    DEFAULT_LABELS,
 }

package/mcp_v2/vitest.config.mjs

@@ -0,0 +1,22 @@
+import { defineConfig } from "vitest/config"
+
+// Framework-level (Tier 1) unit tests for catalyst-mcp's own internals.
+// mcp_v2 lives inside packages/catalyst-core/mcp_v2/ (it ships bundled
+// inside the catalyst-core package, see ../mcp_v2/scripts/copyErrorsIndex.cjs
+// and errors.js's own packaged-path handling) and is NOT matched by the
+// packages/* workspace glob, so it's invisible to `npm run test:unit` unless
+// explicitly wired in — see the root package.json's test:unit script.
+export default defineConfig({
+    test: {
+        environment: "node",
+        include: ["test/**/*.test.ts"],
+        // tools/errors.js itself is CommonJS, loaded via require() from the
+        // .ts test file below. .ts, not .cts: this Vite/Rollup version's SSR
+        // transform doesn't strip TS syntax from .cts files at all (fails to
+        // parse even a single type annotation — a real tooling gap,
+        // confirmed empirically, not a config mistake). vitest's own
+        // describe/it/expect exports can't be require()'d, only import'd —
+        // globals injects them instead.
+        globals: true,
+    },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "0.3.0-beta.5",
+    "version": "0.3.0-canary.2",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",
@@ -16,41 +16,71 @@
         "@catalyst/template": "."
     },
     "exports": {
-        ".": "./dist/index.jsx",
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.jsx"
+        },
         "./package.json": "./package.json",
         "./logger": "./dist/logger.js",
-        "./caching": "./dist/caching.js",
-        "./router/ClientRouter": "./dist/router/ClientRouter.js",
-        "./document": "./dist/server/renderer/document/index.jsx",
-        "./WebBridge": "./dist/native/bridge/WebBridge.js",
-        "./hooks": "./dist/native/bridge/hooks.js",
+        "./router/ClientRouter": {
+            "types": "./dist/router/ClientRouter.d.ts",
+            "default": "./dist/router/ClientRouter.js"
+        },
+        "./WebBridge": {
+            "types": "./dist/native/bridge/WebBridge.d.ts",
+            "default": "./dist/native/bridge/WebBridge.js"
+        },
+        "./hooks": {
+            "types": "./dist/native/bridge/hooks.d.ts",
+            "default": "./dist/native/bridge/hooks.js"
+        },
+        "./errors": "./dist/errors/index.js",
         "./sentry": "./dist/sentry.cjs",
         "./otel": "./dist/otel.js"
     },
+    "typesVersions": {
+        "*": {
+            "hooks": [
+                "./dist/native/bridge/hooks.d.ts"
+            ],
+            "WebBridge": [
+                "./dist/native/bridge/WebBridge.d.ts"
+            ],
+            "router/ClientRouter": [
+                "./dist/router/ClientRouter.d.ts"
+            ]
+        }
+    },
     "scripts": {
         "lint": "eslint .",
         "lint-staged": "lint-staged",
         "test:unit": "node --test \"test/**/*.test.js\"",
+        "typecheck": "tsc --noEmit",
         "prettify": "prettier . --write",
-        "prepare": "node ../../scripts/safe-rimraf.js ./dist && cp -r ./src ./dist && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --ignore '**/.build/**' && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs",
+        "prepare": "node ../../scripts/safe-rimraf.js ./dist && node scripts/build-dist.mjs && cp -r ./src/native ./dist/native && babel src/native --out-dir dist/native --config-file ./babel.native.config.cjs --extensions '.js,.jsx,.ts,.tsx' --ignore '**/.build/**' && node scripts/strip-ts-sources.mjs ./dist/native && babel src/sentry.js --out-file dist/sentry.cjs --config-file ./babel.native.config.cjs && tsc -p tsconfig.declarations.json && node ./mcp_v2/scripts/copyErrorsIndex.cjs",
         "prepublishOnly": "npm run prepare",
+        "test": "npm run test:types && vitest run",
+        "test:watch": "vitest",
+        "test:types": "tsc -p tsconfig.test.json --noEmit",
         "test:fixture": "sh ../../scripts/test-catalyst-core.sh"
     },
     "license": "MIT",
+    "engines": {
+        "node": ">=22.12"
+    },
     "dependencies": {
         "@vitejs/plugin-react": "^4.4.1",
+        "ansis": "^4.3.1",
         "body-parser": "^1.20.2",
         "compression": "^1.7.4",
         "cookie-parser": "^1.4.6",
         "express": "^4.18.2",
         "express-static-gzip": "^2.1.7",
-        "picocolors": "^1.0.0",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-helmet-async": "^1.3.0",
         "react-redux": "^9.2.0",
         "react-refresh": "^0.14.0",
-        "react-router": "^7.18.2",
         "redux": "^4.2.1",
         "sanitize-html": "^2.17.6",
         "sass": "^1.89.2",
@@ -60,6 +90,15 @@
         "winston": "^3.11.0",
         "winston-daily-rotate-file": "^5.0.0"
     },
+    "peerDependencies": {
+        "@types/react": "^19.0.0",
+        "react-router": "^7.18.2"
+    },
+    "peerDependenciesMeta": {
+        "@types/react": {
+            "optional": true
+        }
+    },
     "devDependencies": {
         "@babel/cli": "^7.23.0",
         "@babel/core": "^7.23.2",
@@ -69,6 +108,13 @@
         "@babel/preset-typescript": "^7.24.7",
         "@commitlint/cli": "^19.3.0",
         "@commitlint/config-conventional": "^19.2.2",
+        "@testing-library/dom": "10.4.1",
+        "@testing-library/jest-dom": "7.0.1",
+        "@testing-library/react": "16.3.2",
+        "@types/node": "^22.20.1",
+        "@types/react": "^19.2.18",
+        "@types/react-dom": "^19.2.5",
+        "@vitest/coverage-v8": "4.1.9",
         "eslint": "^8.26.0",
         "eslint-plugin-babel": "^5.3.1",
         "eslint-plugin-react": "^7.34.1",
@@ -77,8 +123,11 @@
         "eslint-plugin-risxss": "^2.1.0",
         "eslint-plugin-security": "^3.0.0",
         "husky": "^9.0.11",
+        "jsdom": "30.0.1",
         "lint-staged": "^15.2.2",
-        "prettier": "^3.2.5"
+        "prettier": "^3.2.5",
+        "typescript": "^7.0.2",
+        "vitest": "4.1.9"
     },
     "lint-staged": {
         "*.{js,jsx}": [

package/test/errors/docsDrift.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, afterEach } from "vitest"
+import { mkdtempSync, rmSync, readFileSync, readdirSync, existsSync } from "fs"
+import { tmpdir } from "os"
+import path from "path"
+import { fileURLToPath } from "url"
+import { generateDocs } from "../../src/errors/generateDocs.js"
+import { ERROR_DEFINITIONS } from "../../src/errors/registry.js"
+
+// Framework-level (Tier 1) contract test: catches the "edited registry.js
+// without regenerating docs" or "hand-edited a generated .md directly"
+// mistake. Regenerates into a scratch dir (never touches the committed
+// errors/ tree) and diffs the core-owned slice against what's checked in.
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// test/errors -> repo root /errors (the committed output)
+const COMMITTED_ERRORS_DIR = path.resolve(__dirname, "../../../../errors")
+
+// Shape of one errors/index.json entry, as written by generateDocs.js.
+// registry.js/generateDocs.js stay plain JS until #420's source conversion —
+// this type exists only to give the test file real safety in the meantime.
+interface IndexEntry {
+    category: string
+    message: string
+    details: string
+    suggestedAction: string
+    docUrl: string
+}
+
+let scratchDir: string | undefined
+
+afterEach(() => {
+    if (scratchDir) rmSync(scratchDir, { recursive: true, force: true })
+    scratchDir = undefined
+})
+
+describe("generated error docs match committed output (docs-drift check)", () => {
+    it("regenerating into a scratch dir produces byte-identical .md files for every core-owned code", () => {
+        scratchDir = mkdtempSync(path.join(tmpdir(), "catalyst-core-docs-drift-"))
+        generateDocs(scratchDir)
+
+        const mismatches: string[] = []
+        for (const [code, def] of Object.entries(ERROR_DEFINITIONS)) {
+            const relPath = path.join(def.category, `${code}.md`)
+            const committedPath = path.join(COMMITTED_ERRORS_DIR, relPath)
+            const scratchPath = path.join(scratchDir, relPath)
+
+            if (!existsSync(committedPath)) {
+                mismatches.push(`${relPath}: missing from committed errors/ — run generateDocs.js and commit the output`)
+                continue
+            }
+            const committed = readFileSync(committedPath, "utf8")
+            const fresh = readFileSync(scratchPath, "utf8")
+            if (committed !== fresh) {
+                mismatches.push(`${relPath}: committed content differs from what generateDocs() produces today`)
+            }
+        }
+        expect(mismatches).toEqual([])
+    })
+
+    it("committed index.json has an up-to-date entry for every core-owned code", () => {
+        const indexPath = path.join(COMMITTED_ERRORS_DIR, "index.json")
+        const committedIndex: Record<string, IndexEntry> = JSON.parse(readFileSync(indexPath, "utf8"))
+
+        const mismatches: string[] = []
+        for (const [code, def] of Object.entries(ERROR_DEFINITIONS)) {
+            const entry = committedIndex[code]
+            if (!entry) {
+                mismatches.push(`${code}: missing from committed errors/index.json`)
+                continue
+            }
+            if (entry.category !== def.category) mismatches.push(`${code}: index.json category "${entry.category}" !== registry "${def.category}"`)
+            if (entry.message !== def.defaultMessage) mismatches.push(`${code}: index.json message drifted from registry defaultMessage`)
+            if (entry.details !== def.defaultDetails) mismatches.push(`${code}: index.json details drifted from registry defaultDetails`)
+            if (entry.suggestedAction !== def.suggestedAction) mismatches.push(`${code}: index.json suggestedAction drifted from registry`)
+        }
+        expect(mismatches).toEqual([])
+    })
+
+    it("committed index.json has no stale core-category entry for a code removed from the registry", () => {
+        const indexPath = path.join(COMMITTED_ERRORS_DIR, "index.json")
+        const committedIndex: Record<string, IndexEntry> = JSON.parse(readFileSync(indexPath, "utf8"))
+        const ownedCategories = new Set(Object.values(ERROR_DEFINITIONS).map((d) => d.category))
+
+        const stale: string[] = []
+        for (const [code, entry] of Object.entries(committedIndex)) {
+            if (ownedCategories.has(entry.category) && !(code in ERROR_DEFINITIONS)) {
+                stale.push(`${code}: stale entry in errors/index.json — its category ("${entry.category}") is core-owned but this code no longer exists in the registry`)
+            }
+        }
+        expect(stale).toEqual([])
+    })
+
+    it("committed errors/ tree has no stray core-category .md files not backed by a current registry entry", () => {
+        const ownedCategories = new Set(Object.values(ERROR_DEFINITIONS).map((d) => d.category))
+        const knownFiles = new Set(
+            Object.entries(ERROR_DEFINITIONS).map(([code, def]) => path.join(def.category, `${code}.md`))
+        )
+
+        const stray: string[] = []
+        for (const category of ownedCategories) {
+            const dir = path.join(COMMITTED_ERRORS_DIR, category)
+            if (!existsSync(dir)) continue
+            for (const file of readdirSync(dir)) {
+                if (!file.endsWith(".md")) continue
+                const rel = path.join(category, file)
+                if (!knownFiles.has(rel)) stray.push(rel)
+            }
+        }
+        expect(stray).toEqual([])
+    })
+})