@node-boost/node-boost 0.1.0

package/dist/cli.js

@@ -0,0 +1,3000 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { defineCommand as defineCommand8, runMain } from "citty";
+
+// src/cli/commands/audit.ts
+import { defineCommand } from "citty";
+
+// src/audit/engine.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join as join8 } from "path";
+import { DiagnosticCategory, Project } from "ts-morph";
+
+// src/config/schema.ts
+import { z } from "zod";
+var agentNameSchema = z.enum(["claude-code", "codex", "cursor"]);
+var stackNameSchema = z.enum(["next", "vite-react", "react-generic", "unknown"]);
+var architectureSlugSchema = z.enum([
+  "feature-modules",
+  "server-first-components",
+  "data-access-layer",
+  "typed-contracts",
+  "state-management",
+  "custom-hooks",
+  "component-composition",
+  "styling-tailwind",
+  "testing-strategy",
+  "error-loading-boundaries",
+  "secure-by-default",
+  "modern-typescript",
+  "ui-states"
+]);
+var auditSeveritySchema = z.enum(["off", "warn", "err"]);
+var featureModulesBoundarySchema = z.enum(["public-api", "forbid"]);
+var nonFeatureModuleArchitectureSlugSchema = z.enum([
+  "server-first-components",
+  "data-access-layer",
+  "typed-contracts",
+  "state-management",
+  "custom-hooks",
+  "component-composition",
+  "styling-tailwind",
+  "testing-strategy",
+  "error-loading-boundaries",
+  "secure-by-default",
+  "modern-typescript",
+  "ui-states"
+]);
+var architectureEntrySchema = z.union([
+  architectureSlugSchema,
+  z.strictObject({
+    name: z.literal("feature-modules"),
+    boundary: featureModulesBoundarySchema.default("public-api")
+  }),
+  z.strictObject({
+    name: nonFeatureModuleArchitectureSlugSchema
+  })
+]);
+var defaultFeatures = {
+  guidelines: true,
+  skills: true,
+  mcp: true,
+  architecture: true,
+  hooks: false
+};
+var defaultAudit = {
+  exclude: [],
+  rules: {},
+  ruleOptions: {}
+};
+var featuresSchema = z.object({
+  guidelines: z.boolean().default(true),
+  skills: z.boolean().default(true),
+  mcp: z.boolean().default(true),
+  architecture: z.boolean().default(true),
+  hooks: z.boolean().default(false)
+});
+var auditSchema = z.object({
+  exclude: z.array(z.string()).default([]),
+  rules: z.record(z.string(), auditSeveritySchema).default({}),
+  ruleOptions: z.record(z.string(), z.record(z.string(), z.unknown())).default({})
+}).default(defaultAudit);
+var nodeBoostConfigSchema = z.object({
+  $schema: z.string().optional(),
+  version: z.literal(1),
+  generatedWith: z.string().min(1),
+  stack: stackNameSchema,
+  agents: z.array(agentNameSchema).default([]),
+  features: featuresSchema.default(defaultFeatures),
+  architectures: z.array(architectureEntrySchema).default([]),
+  audit: auditSchema
+});
+function parseNodeBoostConfig(input) {
+  return nodeBoostConfigSchema.parse(input);
+}
+function normalizeArchitectures(config) {
+  return config.architectures.map((architecture) => {
+    if (typeof architecture === "string") {
+      return {
+        name: architecture,
+        options: architecture === "feature-modules" ? { boundary: "public-api" } : {}
+      };
+    }
+    if (architecture.name === "feature-modules") {
+      return {
+        name: architecture.name,
+        options: { boundary: architecture.boundary }
+      };
+    }
+    return {
+      name: architecture.name,
+      options: {}
+    };
+  });
+}
+
+// src/detect/stack.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/detect/package-manager.ts
+import { access, readFile } from "fs/promises";
+import { join } from "path";
+var lockfiles = [
+  { name: "pnpm", file: "pnpm-lock.yaml" },
+  { name: "yarn", file: "yarn.lock" },
+  { name: "bun", file: "bun.lockb" },
+  { name: "bun", file: "bun.lock" },
+  { name: "npm", file: "package-lock.json" }
+];
+async function detectPackageManager(rootDir) {
+  const packageJson = await readJsonObject(join(rootDir, "package.json"));
+  const declaredPackageManager = parsePackageManager(packageJson);
+  for (const lockfile of lockfiles) {
+    if (await fileExists(join(rootDir, lockfile.file))) {
+      return {
+        name: lockfile.name,
+        lockfile: lockfile.file,
+        version: declaredPackageManager?.name === lockfile.name ? declaredPackageManager.version : null,
+        source: "lockfile"
+      };
+    }
+  }
+  if (declaredPackageManager) {
+    return { name: declaredPackageManager.name, lockfile: null, version: declaredPackageManager.version, source: "packageManagerField" };
+  }
+  return { name: "npm", lockfile: null, version: null, source: "default" };
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJsonObject(path) {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return isObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function isPackageManagerName(value) {
+  return value === "npm" || value === "pnpm" || value === "yarn" || value === "bun";
+}
+function parsePackageManager(packageJson) {
+  const packageManager = typeof packageJson?.packageManager === "string" ? packageJson.packageManager : null;
+  const [managerName, version = null] = packageManager?.split("@") ?? [];
+  if (isPackageManagerName(managerName)) {
+    return { name: managerName, version };
+  }
+  return null;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/detect/router.ts
+import { access as access2 } from "fs/promises";
+import { join as join2 } from "path";
+async function detectNextRouter(rootDir) {
+  const hasRootApp = await directoryExists(join2(rootDir, "app"));
+  const hasSrcApp = await directoryExists(join2(rootDir, "src", "app"));
+  const hasRootPages = await directoryExists(join2(rootDir, "pages"));
+  const hasSrcPages = await directoryExists(join2(rootDir, "src", "pages"));
+  if (hasRootApp || hasSrcApp) {
+    return { router: "app", srcDir: hasSrcApp };
+  }
+  if (hasRootPages || hasSrcPages) {
+    return { router: "pages", srcDir: hasSrcPages };
+  }
+  return { router: "unknown", srcDir: false };
+}
+async function directoryExists(path) {
+  try {
+    await access2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/detect/stack.ts
+var trackedPackages = [
+  "next",
+  "react",
+  "vite",
+  "react-router",
+  "typescript",
+  "tailwindcss",
+  "zod",
+  "@tanstack/react-query",
+  "zustand",
+  "vitest",
+  "jest",
+  "playwright",
+  "eslint",
+  "prettier",
+  "@biomejs/biome"
+];
+async function detectStack(rootDir) {
+  const packageJson = await readPackageJson(rootDir);
+  const packageManager = await detectPackageManager(rootDir);
+  const packages = await detectPackages(rootDir, packageJson);
+  const warnings = [];
+  const name = detectStackName(packages);
+  const nextRouter = name === "next" ? await detectNextRouter(rootDir) : null;
+  const router = nextRouter?.router ?? (name === "vite-react" ? "react-router" : "none");
+  const srcDir = nextRouter?.srcDir ?? false;
+  const linting = detectLinting(packages);
+  if (Object.values(packages).some((pkg) => pkg.source === "range")) {
+    warnings.push("node_modules not available for at least one package; using declared version range fallback.");
+  }
+  return {
+    rootDir,
+    name,
+    router,
+    srcDir,
+    linting,
+    packageManager,
+    packages,
+    warnings
+  };
+}
+function detectLinting(packages) {
+  if (packages["@biomejs/biome"]?.version) {
+    return "biome";
+  }
+  if (packages.eslint?.version && packages.prettier?.version) {
+    return "eslint-prettier";
+  }
+  if (packages.eslint?.version) {
+    return "eslint";
+  }
+  return "none";
+}
+async function detectPackages(rootDir, packageJson) {
+  const packages = {};
+  for (const packageName of trackedPackages) {
+    const declaredRange = findDeclaredRange(packageJson, packageName);
+    const installedVersion = await readInstalledVersion(rootDir, packageName);
+    const version = installedVersion ?? extractVersionFromRange(declaredRange);
+    packages[packageName] = {
+      name: packageName,
+      declaredRange,
+      version,
+      major: version ? parseMajor(version) : null,
+      source: installedVersion ? "node_modules" : version ? "range" : "missing"
+    };
+  }
+  return packages;
+}
+function detectStackName(packages) {
+  if (packages.next?.version) {
+    return "next";
+  }
+  if (packages.react?.version && packages.vite?.version && packages["react-router"]?.version) {
+    return "vite-react";
+  }
+  if (packages.react?.version) {
+    return "react-generic";
+  }
+  return "unknown";
+}
+async function readPackageJson(rootDir) {
+  const raw = await readFile2(join3(rootDir, "package.json"), "utf8");
+  const parsed = JSON.parse(raw);
+  if (!isObject2(parsed)) {
+    throw new Error("package.json must contain an object.");
+  }
+  return parsed;
+}
+function findDeclaredRange(packageJson, packageName) {
+  return packageJson.dependencies?.[packageName] ?? packageJson.devDependencies?.[packageName] ?? packageJson.peerDependencies?.[packageName] ?? packageJson.optionalDependencies?.[packageName] ?? null;
+}
+async function readInstalledVersion(rootDir, packageName) {
+  try {
+    const raw = await readFile2(join3(rootDir, "node_modules", packageName, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (isObject2(parsed) && typeof parsed.version === "string") {
+      return parsed.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function extractVersionFromRange(range) {
+  if (!range) {
+    return null;
+  }
+  const match = range.match(/\d+\.\d+\.\d+|\d+\.\d+|\d+/);
+  if (!match) {
+    return null;
+  }
+  const [major = "0", minor = "0", patch = "0"] = match[0].split(".");
+  return `${major}.${minor}.${patch}`;
+}
+function parseMajor(version) {
+  const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+  return Number.isFinite(major) ? major : null;
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/audit/rules/helpers.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join as join4, normalize } from "path";
+import picomatch from "picomatch";
+function hasUseClientDirective(file) {
+  return file.lines.some((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//")) {
+      return false;
+    }
+    return trimmed === '"use client";' || trimmed === '"use client"' || trimmed === "'use client';" || trimmed === "'use client'";
+  });
+}
+function isClientComponent(file, stackName) {
+  return stackName === "vite-react" || hasUseClientDirective(file);
+}
+function isDataLayerFile(file, globs) {
+  if (file.path.endsWith("/route.ts") || file.path.endsWith("/route.tsx")) {
+    return true;
+  }
+  return picomatch(globs)(file.path);
+}
+function dataLayerGlobs(options) {
+  const configured = options.dataLayerGlobs;
+  return Array.isArray(configured) && configured.every((item) => typeof item === "string") ? configured : ["**/api/**", "**/server/**", "lib/api/**", "src/lib/api/**"];
+}
+function lineOf(content, pattern) {
+  const lines = content.split(/\r?\n/);
+  const index = lines.findIndex((line) => pattern.test(line));
+  return index >= 0 ? index + 1 : 1;
+}
+function finding(file, rule, code, line, ref) {
+  return {
+    rule,
+    sev: "warn",
+    file: file.path,
+    line,
+    code,
+    ref
+  };
+}
+function importSpecs(file) {
+  const specs = [];
+  const patterns = [
+    /^\s*import\s+(?:type\s+)?(?:[^'"]+\s+from\s+)?["']([^"']+)["']/,
+    /^\s*export\s+[^'"]+\s+from\s+["']([^"']+)["']/
+  ];
+  file.lines.forEach((line, index) => {
+    for (const pattern of patterns) {
+      const match = line.match(pattern);
+      if (match?.[1]) {
+        specs.push({ spec: match[1], line: index + 1 });
+      }
+    }
+  });
+  return specs;
+}
+function resolveImportPath(file, spec) {
+  if (spec.startsWith(".")) {
+    return toPosix(normalize(join4(dirname(file.path), spec)));
+  }
+  return spec.replace(/^@\/?/, "").replace(/^~\/?/, "");
+}
+function isConfigFile(path) {
+  return /(^|\/)[^/]*\.config\.[cm]?[jt]sx?$/.test(path);
+}
+function hasGeneratedClientDependency(rootDir) {
+  try {
+    const packageJson = JSON.parse(existsSync(join4(rootDir, "package.json")) ? readFileSync(join4(rootDir, "package.json"), "utf8") : "{}");
+    return Boolean(packageJson.devDependencies?.orval || packageJson.devDependencies?.["openapi-typescript"]);
+  } catch {
+    return false;
+  }
+}
+function toPosix(path) {
+  return path.replaceAll("\\", "/");
+}
+
+// src/audit/rules/data-access-layer.ts
+var networkPattern = /\b(fetch\s*\(|axios\.|ky\s*\(|ky\.)/;
+var dataAccessLayerRules = [
+  {
+    id: "NB-ARCH-005",
+    code: "fetch-in-client-component",
+    architecture: "data-access-layer",
+    defaultSeverity: "err",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      const globs = dataLayerGlobs(context.ruleOptions);
+      return context.files.flatMap((file) => {
+        if (!isClientComponent(file, context.stack.name) || isDataLayerFile(file, globs) || isQueryHook(file)) {
+          return [];
+        }
+        return networkFindings(file, "NB-ARCH-005", "fetch-in-client-component");
+      });
+    }
+  },
+  {
+    id: "NB-ARCH-006",
+    code: "raw-fetch-in-rsc",
+    architecture: "data-access-layer",
+    defaultSeverity: "warn",
+    stacks: ["next"],
+    kind: "line",
+    check(context) {
+      const globs = dataLayerGlobs(context.ruleOptions);
+      return context.files.flatMap((file) => {
+        if (isClientComponent(file, context.stack.name) || isDataLayerFile(file, globs)) {
+          return [];
+        }
+        return networkFindings(file, "NB-ARCH-006", "raw-fetch-in-rsc").filter((item) => item.code === "raw-fetch-in-rsc");
+      });
+    }
+  }
+];
+function networkFindings(file, rule, code) {
+  return file.lines.flatMap((line, index) => networkPattern.test(line) ? [finding(file, rule, code, index + 1)] : []);
+}
+function isQueryHook(file) {
+  return /(^|\/)use[A-Z][^/]*\.tsx?$/.test(file.path) && /\buse(Query|Mutation)\s*\(/.test(file.content);
+}
+
+// src/audit/rules/error-loading-boundaries.ts
+import { dirname as dirname2 } from "path";
+var errorLoadingBoundaryRules = [
+  {
+    id: "NB-ARCH-010",
+    code: "segment-without-boundaries",
+    architecture: "error-loading-boundaries",
+    defaultSeverity: "warn",
+    stacks: ["next"],
+    kind: "project",
+    check(context) {
+      return context.files.flatMap((file) => {
+        if (!/(^|\/)app\/.+\/page\.tsx?$/.test(file.path) || !/\b(async|await)\b/.test(file.content)) {
+          return [];
+        }
+        return hasBoundaryInBranch(file.path, context.allPaths) ? [] : [finding(file, "NB-ARCH-010", "segment-without-boundaries", 1)];
+      });
+    }
+  }
+];
+function hasBoundaryInBranch(pagePath, allPaths) {
+  let current = dirname2(pagePath);
+  while (current.includes("/app/") || current.endsWith("/app") || current === "app" || current === "src/app") {
+    for (const name of ["loading.tsx", "loading.ts", "loading.jsx", "loading.js", "error.tsx", "error.ts", "error.jsx", "error.js"]) {
+      if (allPaths.has(`${current}/${name}`)) {
+        return true;
+      }
+    }
+    if (current.endsWith("/app") || current === "app" || current === "src/app") {
+      break;
+    }
+    current = dirname2(current);
+  }
+  return false;
+}
+
+// src/audit/rules/feature-modules.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join5 } from "path";
+var featureModuleRules = [
+  {
+    id: "NB-ARCH-001",
+    code: "cross-feature-deep-import",
+    architecture: "feature-modules",
+    defaultSeverity: "err",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      const featuresDir = typeof context.ruleOptions.featuresDir === "string" ? context.ruleOptions.featuresDir : "src/features";
+      const normalizedFeaturesDir = featuresDir.replace(/\/$/, "");
+      if (!existsSync2(join5(context.rootDir, normalizedFeaturesDir))) {
+        return [];
+      }
+      const boundary = context.architectureOptions.boundary === "forbid" ? "forbid" : "public-api";
+      return context.files.flatMap((file) => {
+        const sourceFeature = featureName(file.path, normalizedFeaturesDir);
+        if (!sourceFeature) {
+          return [];
+        }
+        return importSpecs(file).flatMap(({ spec, line }) => {
+          const targetPath = resolveImportPath(file, spec);
+          const targetFeature = featureName(targetPath, normalizedFeaturesDir);
+          if (!targetFeature || targetFeature === sourceFeature) {
+            return [];
+          }
+          const suffix = targetPath.slice(`${normalizedFeaturesDir}/${targetFeature}/`.length);
+          const allowedPublicApi = boundary === "public-api" && (suffix === "index" || suffix === "index.ts" || suffix === "index.tsx");
+          return allowedPublicApi ? [] : [finding(file, "NB-ARCH-001", "cross-feature-deep-import", line, targetPath)];
+        });
+      });
+    }
+  },
+  {
+    id: "NB-ARCH-002",
+    code: "feature-imports-app",
+    architecture: "feature-modules",
+    defaultSeverity: "err",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      const featuresDir = typeof context.ruleOptions.featuresDir === "string" ? context.ruleOptions.featuresDir : "src/features";
+      return context.files.flatMap((file) => {
+        if (!featureName(file.path, featuresDir)) {
+          return [];
+        }
+        return importSpecs(file).flatMap(({ spec, line }) => {
+          const target = resolveImportPath(file, spec);
+          return /^(src\/)?(app|routes)(\/|$)/.test(target) ? [finding(file, "NB-ARCH-002", "feature-imports-app", line, target)] : [];
+        });
+      });
+    }
+  }
+];
+function featureName(path, featuresDir) {
+  const normalized = featuresDir.replace(/\/$/, "");
+  const prefix = `${normalized}/`;
+  if (!path.startsWith(prefix)) {
+    return null;
+  }
+  return path.slice(prefix.length).split("/")[0] ?? null;
+}
+
+// src/audit/rules/modern-typescript.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join6, resolve } from "path";
+var modernTypeScriptRules = [
+  {
+    id: "NB-ARCH-013",
+    code: "tsconfig-not-strict",
+    architecture: "modern-typescript",
+    defaultSeverity: "warn",
+    stacks: ["next", "vite-react"],
+    kind: "project",
+    check(context) {
+      return tsconfigStrict(context.rootDir) ? [] : [{
+        rule: "NB-ARCH-013",
+        sev: "warn",
+        file: "tsconfig.json",
+        line: 1,
+        code: "tsconfig-not-strict"
+      }];
+    }
+  },
+  {
+    id: "NB-ARCH-014",
+    code: "explicit-any",
+    architecture: "modern-typescript",
+    defaultSeverity: "warn",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      return context.files.flatMap((file) => {
+        if (/(\.d\.ts|\.test\.[jt]sx?|\.spec\.[jt]sx?)$/.test(file.path) || file.path.startsWith("tests/")) {
+          return [];
+        }
+        return file.lines.flatMap(
+          (line, index) => /(:\s*any\b|as\s+any\b|<any>)/.test(line) ? [finding(file, "NB-ARCH-014", "explicit-any", index + 1)] : []
+        );
+      });
+    }
+  }
+];
+function tsconfigStrict(rootDir) {
+  const visited = /* @__PURE__ */ new Set();
+  return readStrictFromTsconfig(join6(rootDir, "tsconfig.json"), visited) === true;
+}
+function readStrictFromTsconfig(path, visited) {
+  if (visited.has(path) || !existsSync3(path)) {
+    return null;
+  }
+  visited.add(path);
+  const parsed = JSON.parse(stripJsonComments(readFileSync2(path, "utf8")));
+  if (parsed.compilerOptions?.strict !== void 0) {
+    return parsed.compilerOptions.strict;
+  }
+  if (!parsed.extends) {
+    return null;
+  }
+  if (parsed.extends.startsWith(".")) {
+    return readStrictFromTsconfig(resolve(dirname3(path), parsed.extends), visited);
+  }
+  return null;
+}
+function stripJsonComments(value) {
+  return value.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+
+// src/audit/rules/secure-by-default.ts
+var secureByDefaultRules = [
+  {
+    id: "NB-ARCH-011",
+    code: "unsanitized-html",
+    architecture: "secure-by-default",
+    defaultSeverity: "err",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      return context.files.flatMap(
+        (file) => file.lines.flatMap((line, index) => {
+          const match = line.match(/dangerouslySetInnerHTML=\{\{\s*__html:\s*([^}]+)\s*\}\}/);
+          if (!match) {
+            return [];
+          }
+          const value = match[1]?.trim() ?? "";
+          const safe = /sanitize\s*\(/i.test(value) || /^["'`]/.test(value);
+          return safe ? [] : [finding(file, "NB-ARCH-011", "unsanitized-html", index + 1)];
+        })
+      );
+    }
+  },
+  {
+    id: "NB-ARCH-012",
+    code: "public-env-secret-name",
+    architecture: "secure-by-default",
+    defaultSeverity: "warn",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      return context.files.flatMap(
+        (file) => file.lines.flatMap((line, index) => {
+          const names = [...line.matchAll(/\b((?:NEXT_PUBLIC|VITE)_[A-Z0-9_]+)/g)].map((match) => match[1] ?? "");
+          return names.filter((name) => /(SECRET|TOKEN|PRIVATE|PASSWORD|_KEY$)/.test(name)).map((name) => finding(file, "NB-ARCH-012", "public-env-secret-name", index + 1, name));
+        })
+      );
+    }
+  }
+];
+
+// src/audit/rules/server-first-components.ts
+var serverFirstComponentRules = [
+  {
+    id: "NB-ARCH-003",
+    code: "use-client-in-entry",
+    architecture: "server-first-components",
+    defaultSeverity: "err",
+    stacks: ["next"],
+    kind: "line",
+    check(context) {
+      return context.files.flatMap((file) => {
+        if (!hasUseClientDirective(file) || !/(^|\/)(page|layout)\.tsx?$/.test(file.path)) {
+          return [];
+        }
+        return [finding(file, "NB-ARCH-003", "use-client-in-entry", lineOf(file.content, /['"]use client['"]/))];
+      });
+    }
+  },
+  {
+    id: "NB-ARCH-004",
+    code: "needless-use-client",
+    architecture: "server-first-components",
+    defaultSeverity: "warn",
+    stacks: ["next"],
+    kind: "line",
+    check(context) {
+      return context.files.flatMap((file) => {
+        if (!hasUseClientDirective(file)) {
+          return [];
+        }
+        const withoutDirective = file.lines.filter((line) => !line.includes("use client")).join("\n");
+        const needsClient = /\buse[A-Z]\w*\s*\(/.test(withoutDirective) || /\bon[A-Z]\w*\s*=/.test(withoutDirective) || /\b(window|document)\./.test(withoutDirective);
+        return needsClient ? [] : [finding(file, "NB-ARCH-004", "needless-use-client", lineOf(file.content, /['"]use client['"]/))];
+      });
+    }
+  }
+];
+
+// src/audit/rules/state-management.ts
+var stateManagementRules = [
+  {
+    id: "NB-ARCH-009",
+    code: "server-state-in-store",
+    architecture: "state-management",
+    defaultSeverity: "warn",
+    stacks: ["next", "vite-react"],
+    kind: "ast",
+    check(context) {
+      const globs = dataLayerGlobs(context.ruleOptions);
+      return context.files.flatMap((file) => {
+        if (isDataLayerFile(file, globs)) {
+          return [];
+        }
+        const hasServerRead = /\bawait\s+(?:fetch\s*\(|\w+\.(?:get|post|list|fetch|load)\s*\()/.test(file.content);
+        if (!hasServerRead) {
+          return [];
+        }
+        return file.lines.flatMap(
+          (line, index) => /\b(use[A-Z]\w*Store\.setState|dispatch|set)\s*\(/.test(line) ? [finding(file, "NB-ARCH-009", "server-state-in-store", index + 1)] : []
+        );
+      });
+    }
+  }
+];
+
+// src/audit/rules/typed-contracts.ts
+var typedContractRules = [
+  {
+    id: "NB-ARCH-007",
+    code: "unvalidated-boundary",
+    architecture: "typed-contracts",
+    defaultSeverity: "warn",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      if (hasGeneratedClientDependency(context.rootDir)) {
+        return [];
+      }
+      const globs = dataLayerGlobs(context.ruleOptions);
+      return context.files.flatMap((file) => {
+        if (!isDataLayerFile(file, globs) || /\.s(afe)?parse\s*\(/.test(file.content)) {
+          return [];
+        }
+        return file.lines.flatMap(
+          (line, index) => /(=\s*await\s+\w+\.json\s*\(|=\s*JSON\.parse\s*\(|as\s+\w+.*await\s+\w+\.json\s*\()/.test(line) ? [finding(file, "NB-ARCH-007", "unvalidated-boundary", index + 1)] : []
+        );
+      });
+    }
+  },
+  {
+    id: "NB-ARCH-008",
+    code: "env-outside-env-file",
+    architecture: "typed-contracts",
+    defaultSeverity: "warn",
+    stacks: ["next", "vite-react"],
+    kind: "line",
+    check(context) {
+      const envFiles = envFileGlobs(context.ruleOptions);
+      return context.files.flatMap((file) => {
+        if (isConfigFile(file.path) || envFiles.some((envFile) => file.path.endsWith(envFile))) {
+          return [];
+        }
+        return file.lines.flatMap((line, index) => {
+          const names = [...line.matchAll(/(?:process\.env|import\.meta\.env)\.([A-Z0-9_]+)/g)].map((match) => match[1] ?? "");
+          return names.filter((name) => name !== "NODE_ENV").map((name) => finding(file, "NB-ARCH-008", "env-outside-env-file", index + 1, name));
+        });
+      });
+    }
+  }
+];
+function envFileGlobs(options) {
+  const configured = options.envFiles;
+  return Array.isArray(configured) && configured.every((item) => typeof item === "string") ? configured : ["env.ts", "env.mjs"];
+}
+
+// src/audit/registry.ts
+var auditRules = [
+  ...featureModuleRules,
+  ...serverFirstComponentRules,
+  ...dataAccessLayerRules,
+  ...typedContractRules,
+  ...stateManagementRules,
+  ...errorLoadingBoundaryRules,
+  ...secureByDefaultRules,
+  ...modernTypeScriptRules
+];
+var guidelineByArchitecture = {
+  "feature-modules": ".ai/guidelines/architectures/feature-modules.md",
+  "server-first-components": ".ai/guidelines/architectures/server-first-components.md",
+  "data-access-layer": ".ai/guidelines/architectures/data-access-layer.md",
+  "typed-contracts": ".ai/guidelines/architectures/typed-contracts.md",
+  "state-management": ".ai/guidelines/architectures/state-management.md",
+  "custom-hooks": ".ai/guidelines/architectures/custom-hooks.md",
+  "component-composition": ".ai/guidelines/architectures/component-composition.md",
+  "styling-tailwind": ".ai/guidelines/architectures/styling-tailwind.md",
+  "testing-strategy": ".ai/guidelines/architectures/testing-strategy.md",
+  "error-loading-boundaries": ".ai/guidelines/architectures/error-loading-boundaries.md",
+  "secure-by-default": ".ai/guidelines/architectures/secure-by-default.md",
+  "modern-typescript": ".ai/guidelines/architectures/modern-typescript.md",
+  "ui-states": ".ai/guidelines/architectures/ui-states.md"
+};
+var explainEntries = new Map(
+  auditRules.map((rule) => [
+    rule.id,
+    {
+      rule: rule.id,
+      code: rule.code,
+      severity: rule.defaultSeverity,
+      architecture: rule.architecture,
+      description: describeRule(rule.id),
+      rationale: "This check enforces the selected node-boost architecture guideline and keeps generated agent feedback actionable.",
+      fix: fixRule(rule.id),
+      guideline: guidelineByArchitecture[rule.architecture]
+    }
+  ])
+);
+function explainFinding(ruleId) {
+  return explainEntries.get(ruleId) ?? null;
+}
+function describeRule(ruleId) {
+  const descriptions = {
+    "NB-ARCH-001": "Feature modules must not deep-import internals from other features.",
+    "NB-ARCH-002": "Feature modules must not depend on app/router entry layers.",
+    "NB-ARCH-003": "Next page and layout entries should stay server-first.",
+    "NB-ARCH-004": "Client directives should be present only when the file needs client-only behavior.",
+    "NB-ARCH-005": "Client components should call a data layer or query hook instead of raw network clients.",
+    "NB-ARCH-006": "Server Components should keep raw fetch calls in a data layer.",
+    "NB-ARCH-007": "Untrusted JSON at data boundaries should be validated.",
+    "NB-ARCH-008": "Environment access should be centralized in env files.",
+    "NB-ARCH-009": "Server data should not be pushed directly into client stores.",
+    "NB-ARCH-010": "Async Next app segments need loading or error boundaries.",
+    "NB-ARCH-011": "Raw HTML injection must be sanitized or static.",
+    "NB-ARCH-012": "Public env names must not look like secrets.",
+    "NB-ARCH-013": "TypeScript projects should run with strict mode.",
+    "NB-ARCH-014": "Source code should avoid explicit any outside tests and declarations."
+  };
+  return descriptions[ruleId] ?? "Unknown node-boost audit rule.";
+}
+function fixRule(ruleId) {
+  const fixes = {
+    "NB-ARCH-001": "Import from the feature public index or move shared code to a shared module.",
+    "NB-ARCH-002": "Invert the dependency: app imports features, features do not import app.",
+    "NB-ARCH-003": "Move interactive code to a child client component.",
+    "NB-ARCH-004": "Remove the directive or add a real client-only boundary around interactive code.",
+    "NB-ARCH-005": "Move the request to an API/data module or wrap it in a query hook.",
+    "NB-ARCH-006": "Move raw fetch usage to the configured data layer.",
+    "NB-ARCH-007": "Parse the response with a schema, or rely on a generated typed client.",
+    "NB-ARCH-008": "Read the env var in env.ts/env.mjs and import the typed value.",
+    "NB-ARCH-009": "Keep server state in a query/cache layer and store only UI state.",
+    "NB-ARCH-010": "Add loading.tsx or error.tsx in the segment branch.",
+    "NB-ARCH-011": "Sanitize the HTML value before passing it to dangerouslySetInnerHTML.",
+    "NB-ARCH-012": "Rename the public env var so it does not imply secret material.",
+    "NB-ARCH-013": "Set compilerOptions.strict to true, directly or through an extends chain.",
+    "NB-ARCH-014": "Replace any with a concrete, unknown, or generic type."
+  };
+  return fixes[ruleId] ?? "Open the linked guideline and apply the recommended architecture boundary.";
+}
+
+// src/audit/scope.ts
+import { execFile } from "child_process";
+import { realpath, readdir } from "fs/promises";
+import { join as join7, relative } from "path";
+import { promisify } from "util";
+import picomatch2 from "picomatch";
+var execFileAsync = promisify(execFile);
+var sourceFilePattern = /\.(tsx?|jsx?)$/;
+var defaultExcludes = ["node_modules/**", "dist/**", ".next/**", "coverage/**"];
+async function resolveAuditScope(options) {
+  const warnings = [];
+  const rawFiles = await resolveRawFiles(options, warnings);
+  const files = filterSourceFiles(rawFiles, options.config.audit.exclude);
+  return {
+    mode: options.mode,
+    files,
+    warnings
+  };
+}
+async function resolveRawFiles(options, warnings) {
+  if (options.mode === "paths") {
+    return options.paths ?? [];
+  }
+  if (options.mode === "all") {
+    return walkFiles(options.rootDir);
+  }
+  if (options.mode === "base") {
+    try {
+      const gitRoot = await findGitRoot(options.rootDir);
+      const mergeBase = (await execGit(gitRoot, ["merge-base", options.base ?? "main", "HEAD"])).trim();
+      const diff = await execGit(gitRoot, ["diff", "--name-only", mergeBase, "HEAD"]);
+      return gitPathsToProjectRelative(gitRoot, options.rootDir, splitLines(diff));
+    } catch {
+      warnings.push(metaWarning("NB-META-004", "git-base-fallback-all"));
+      return walkFiles(options.rootDir);
+    }
+  }
+  try {
+    const gitRoot = await findGitRoot(options.rootDir);
+    const tracked = await execGit(gitRoot, ["diff", "--name-only", "HEAD"]);
+    const untracked = await execGit(gitRoot, ["ls-files", "--others", "--exclude-standard"]);
+    return gitPathsToProjectRelative(gitRoot, options.rootDir, [...splitLines(tracked), ...splitLines(untracked)]);
+  } catch {
+    warnings.push(metaWarning("NB-META-004", "git-changed-fallback-all"));
+    return walkFiles(options.rootDir);
+  }
+}
+function filterSourceFiles(files, configuredExcludes) {
+  const excludes = picomatch2([...defaultExcludes, ...configuredExcludes]);
+  return [...new Set(files.map(toPosix2))].filter((file) => sourceFilePattern.test(file)).filter((file) => !excludes(file)).sort((a, b) => a.localeCompare(b));
+}
+async function walkFiles(rootDir, dir = rootDir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = join7(dir, entry.name);
+      const rel = toPosix2(relative(rootDir, absolutePath));
+      if (entry.isDirectory()) {
+        if (defaultExcludes.some((pattern) => picomatch2.isMatch(`${rel}/`, pattern))) {
+          return [];
+        }
+        return walkFiles(rootDir, absolutePath);
+      }
+      return entry.isFile() ? [rel] : [];
+    })
+  );
+  return files.flat();
+}
+async function execGit(cwd, args) {
+  const { stdout } = await execFileAsync("git", args, { cwd });
+  return stdout;
+}
+async function findGitRoot(rootDir) {
+  return realpath((await execGit(rootDir, ["rev-parse", "--show-toplevel"])).trim());
+}
+async function gitPathsToProjectRelative(gitRootInput, rootDir, files) {
+  const gitRoot = await realpath(gitRootInput);
+  const projectRoot = await realpath(rootDir);
+  const projectPrefix = toPosix2(relative(gitRoot, projectRoot));
+  if (!projectPrefix) {
+    return files;
+  }
+  return files.map(toPosix2).filter((file) => file === projectPrefix || file.startsWith(`${projectPrefix}/`)).map((file) => file.slice(projectPrefix.length).replace(/^\//, ""));
+}
+function splitLines(value) {
+  return value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function toPosix2(path) {
+  return path.replaceAll("\\", "/");
+}
+function metaWarning(rule, code) {
+  return {
+    rule,
+    sev: "warn",
+    file: "<project>",
+    line: 1,
+    code
+  };
+}
+
+// src/audit/suppression.ts
+var suppressionPattern = /nb-disable\s+(NB-[A-Z]+-\d{3})\s*(?:--\s*(.+))?/;
+function buildSuppressionIndex(files) {
+  const lineSuppressions = /* @__PURE__ */ new Map();
+  const fileSuppressions = /* @__PURE__ */ new Map();
+  const metaFindings = [];
+  for (const file of files) {
+    let beforeImports = true;
+    file.lines.forEach((line, index) => {
+      const lineNo = index + 1;
+      const trimmed = line.trim();
+      const match = trimmed.match(suppressionPattern);
+      if (match) {
+        const [, rule = "", reason = ""] = match;
+        if (!reason.trim()) {
+          metaFindings.push({
+            rule: "NB-META-001",
+            sev: "warn",
+            file: file.path,
+            line: lineNo,
+            code: "suppression-without-reason"
+          });
+        }
+        if (beforeImports) {
+          addSuppression(fileSuppressions, file.path, rule);
+        }
+        addSuppression(lineSuppressions, lineKey(file.path, lineNo), rule);
+        addSuppression(lineSuppressions, lineKey(file.path, lineNo + 1), rule);
+      }
+      if (trimmed && !trimmed.startsWith("//") && !trimmed.startsWith("/*") && !trimmed.startsWith("*")) {
+        beforeImports = !trimmed.startsWith("import ");
+      }
+    });
+  }
+  return {
+    metaFindings,
+    suppresses(file, line, rule) {
+      return Boolean(fileSuppressions.get(file)?.has(rule) || lineSuppressions.get(lineKey(file, line))?.has(rule));
+    }
+  };
+}
+function addSuppression(map, key, rule) {
+  const current = map.get(key) ?? /* @__PURE__ */ new Set();
+  current.add(rule);
+  map.set(key, current);
+}
+function lineKey(file, line) {
+  return `${file}:${line}`;
+}
+
+// src/audit/engine.ts
+var NodeBoostConfigMissingError = class extends Error {
+  constructor() {
+    super("No node-boost.json found \u2014 run node-boost install first.");
+    this.name = "NodeBoostConfigMissingError";
+  }
+};
+function isNodeBoostConfigMissingError(error) {
+  return error instanceof NodeBoostConfigMissingError;
+}
+async function runAudit(options = {}) {
+  const started = performance.now();
+  const rootDir = options.rootDir ?? process.cwd();
+  const config = await readConfig(rootDir);
+  const stack = await detectStack(rootDir);
+  const scope = await resolveAuditScope({
+    rootDir,
+    config,
+    mode: options.mode ?? "all",
+    base: options.base,
+    paths: options.paths
+  });
+  const parseWarnings = [];
+  const files = await readAuditFiles(rootDir, scope.files, parseWarnings);
+  const suppressionIndex = buildSuppressionIndex(files);
+  const enabledArchitectures = new Map(normalizeArchitectures(config).map((architecture) => [architecture.name, architecture.options]));
+  const findings = [...scope.warnings, ...parseWarnings, ...suppressionIndex.metaFindings];
+  let suppressed = 0;
+  for (const rule of auditRules) {
+    const severity = config.audit.rules[rule.id] ?? rule.defaultSeverity;
+    if (severity === "off" || !enabledArchitectures.has(rule.architecture) || !rule.stacks.includes(stack.name)) {
+      continue;
+    }
+    const rawFindings = rule.check({
+      rootDir,
+      stack,
+      config,
+      files,
+      allPaths: new Set(scope.files),
+      rule,
+      severity,
+      architectureOptions: enabledArchitectures.get(rule.architecture) ?? {},
+      ruleOptions: config.audit.ruleOptions[rule.id] ?? {}
+    });
+    for (const finding2 of rawFindings) {
+      const normalized = { ...finding2, sev: severity };
+      if (suppressionIndex.suppresses(normalized.file, normalized.line, normalized.rule)) {
+        suppressed += 1;
+      } else {
+        findings.push(normalized);
+      }
+    }
+  }
+  const err = findings.filter((finding2) => finding2.sev === "err").length;
+  const warn = findings.filter((finding2) => finding2.sev === "warn").length;
+  return {
+    v: 1,
+    ok: err === 0,
+    cmd: "audit",
+    scope: scope.mode,
+    err,
+    warn,
+    scanned: files.filter((file) => !file.skipped).length,
+    skipped: files.filter((file) => file.skipped).length,
+    suppressed,
+    elapsedMs: Math.round(performance.now() - started),
+    findings: findings.sort(compareFindings)
+  };
+}
+async function readConfig(rootDir) {
+  const configPath = join8(rootDir, "node-boost.json");
+  const raw = await readFile3(configPath, "utf8").catch((error) => {
+    if (isFileNotFoundError(error)) {
+      throw new NodeBoostConfigMissingError();
+    }
+    throw error;
+  });
+  return parseNodeBoostConfig(JSON.parse(raw));
+}
+function isFileNotFoundError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+async function readAuditFiles(rootDir, files, parseWarnings) {
+  const project = new Project({
+    compilerOptions: {
+      allowJs: true,
+      checkJs: false,
+      jsx: 4,
+      skipLibCheck: true
+    },
+    skipAddingFilesFromTsConfig: true
+  });
+  return Promise.all(
+    files.map(async (file) => {
+      const absolutePath = join8(rootDir, file);
+      const content = await readFile3(absolutePath, "utf8");
+      const started = performance.now();
+      const sourceFile = project.addSourceFileAtPath(absolutePath);
+      const diagnostics = sourceFile.getPreEmitDiagnostics().filter((diagnostic) => diagnostic.getCategory() === DiagnosticCategory.Error && diagnostic.getCode() < 2e3);
+      const elapsed = performance.now() - started;
+      const skipped = diagnostics.length > 0 || elapsed > 5e3;
+      if (diagnostics.length > 0) {
+        parseWarnings.push({
+          rule: "NB-META-002",
+          sev: "warn",
+          file,
+          line: diagnostics[0]?.getLineNumber() ?? 1,
+          code: "parse-error"
+        });
+      } else if (elapsed > 5e3) {
+        parseWarnings.push({
+          rule: "NB-META-003",
+          sev: "warn",
+          file,
+          line: 1,
+          code: "parse-timeout"
+        });
+      }
+      return {
+        path: file,
+        absolutePath,
+        content,
+        lines: content.split(/\r?\n/),
+        sourceFile: skipped ? null : sourceFile,
+        skipped
+      };
+    })
+  );
+}
+function compareFindings(a, b) {
+  return a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule);
+}
+
+// src/audit/reporters/agent.ts
+function renderAgentReport(result) {
+  return `${JSON.stringify({
+    v: result.v,
+    ok: result.ok,
+    cmd: result.cmd,
+    scope: result.scope,
+    err: result.err,
+    warn: result.warn,
+    scanned: result.scanned,
+    skipped: result.skipped,
+    findings: result.findings
+  })}
+`;
+}
+
+// src/audit/reporters/human.ts
+function renderHumanReport(result) {
+  const lines = result.findings.map((finding2) => {
+    const ref = finding2.ref ? ` -> ${finding2.ref}` : "";
+    return `${finding2.file}:${finding2.line} | ${finding2.rule} | ${finding2.sev} | ${finding2.code}${ref}`;
+  });
+  lines.push(
+    `summary | scanned=${result.scanned} skipped=${result.skipped} suppressed=${result.suppressed} err=${result.err} warn=${result.warn} time=${result.elapsedMs}ms`
+  );
+  return `${lines.join("\n")}
+`;
+}
+
+// src/cli/errors.ts
+function handleCliError(error) {
+  if (!isNodeBoostConfigMissingError(error)) {
+    return false;
+  }
+  process.stderr.write(`${error.message}
+`);
+  process.exitCode = 1;
+  return true;
+}
+
+// src/cli/commands/audit.ts
+var auditCommand = defineCommand({
+  meta: {
+    name: "audit",
+    description: "Audit the project against enabled node-boost architecture rules."
+  },
+  args: {
+    all: { type: "boolean", description: "Audit all source files.", default: false },
+    changed: { type: "boolean", description: "Audit changed and untracked source files.", default: false },
+    base: { type: "string", description: "Audit files changed since merge-base with this ref.", required: false },
+    agent: { type: "boolean", description: "Print compact machine-readable JSON.", default: false }
+  },
+  async run({ args }) {
+    try {
+      const paths = Array.isArray(args._) ? args._.map(String) : [];
+      const result = await runAudit({
+        mode: paths.length > 0 ? "paths" : args.base ? "base" : args.changed ? "changed" : "all",
+        base: args.base,
+        paths
+      });
+      process.stdout.write(args.agent ? renderAgentReport(result) : renderHumanReport(result));
+      process.exitCode = result.err > 0 ? 1 : 0;
+    } catch (error) {
+      if (handleCliError(error)) {
+        return;
+      }
+      throw error;
+    }
+  }
+});
+
+// src/cli/commands/doctor.ts
+import { defineCommand as defineCommand2 } from "citty";
+
+// package.json
+var package_default = {
+  name: "@node-boost/node-boost",
+  version: "0.1.0",
+  description: "CLI and MCP guidance layer for Node/React projects.",
+  type: "module",
+  license: "MIT",
+  author: "Gracjan Kubicki",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/gracjankubicki/node-boost.git"
+  },
+  bugs: {
+    url: "https://github.com/gracjankubicki/node-boost/issues"
+  },
+  homepage: "https://github.com/gracjankubicki/node-boost#readme",
+  publishConfig: {
+    access: "public"
+  },
+  keywords: [
+    "node",
+    "react",
+    "nextjs",
+    "vite",
+    "codex",
+    "claude-code",
+    "cursor",
+    "mcp",
+    "architecture",
+    "audit",
+    "agent-skills"
+  ],
+  main: "./dist/index.js",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    }
+  },
+  bin: {
+    "node-boost": "dist/cli.js"
+  },
+  types: "./dist/index.d.ts",
+  files: [
+    "dist",
+    "resources",
+    "schema.json",
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "README.md"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  scripts: {
+    build: "npm run build:schema && tsup",
+    "build:schema": "tsx scripts/generate-schema.ts",
+    typecheck: "tsc --noEmit",
+    lint: "eslint .",
+    test: "vitest run",
+    check: "npm run typecheck && npm run lint && npm test && npm run build"
+  },
+  dependencies: {
+    "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    citty: "^0.2.2",
+    picomatch: "^4.0.5",
+    "smol-toml": "^1.7.0",
+    "ts-morph": "^28.0.0",
+    zod: "^4.4.3"
+  },
+  devDependencies: {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "@types/picomatch": "^4.0.3",
+    eslint: "^10.6.0",
+    tsup: "^8.5.1",
+    tsx: "^4.23.0",
+    typescript: "^6.0.3",
+    "typescript-eslint": "^8.63.0",
+    vitest: "^4.1.10"
+  }
+};
+
+// src/mcp/tools/doctor.ts
+import { readdir as readdir3, readFile as readFile7 } from "fs/promises";
+import { join as join16, relative as relative4 } from "path";
+
+// src/install/orchestrator.ts
+import { cancel, confirm, intro, isCancel, multiselect, outro, select } from "@clack/prompts";
+import { mkdir, readFile as readFile5, writeFile } from "fs/promises";
+import { dirname as dirname5, isAbsolute, join as join14 } from "path";
+import { ZodError } from "zod";
+
+// src/agents/agent.ts
+function createMcpCommand(packageManager) {
+  return createPackageCommand(packageManager, ["mcp"]);
+}
+function createHookCommand(packageManager, agent) {
+  return createPackageCommand(packageManager, ["guard", "--hook", agent]);
+}
+function createPackageCommand(packageManager, nodeBoostArgs) {
+  if (packageManager === "yarn") {
+    return { command: "yarn", args: ["node-boost", ...nodeBoostArgs] };
+  }
+  if (packageManager === "bun") {
+    return { command: "bunx", args: ["node-boost", ...nodeBoostArgs] };
+  }
+  return { command: packageManager, args: ["exec", "node-boost", ...nodeBoostArgs] };
+}
+function formatMcpCommand(command) {
+  return [command.command, ...command.args].join(" ");
+}
+
+// src/agents/merge-hooks.ts
+function mergeClaudeCodeHooks(existingContent, command) {
+  const root = parseObject(existingContent);
+  const hooks = asObject(root.hooks);
+  const stop = asArray(hooks.Stop);
+  hooks.Stop = appendCommandHook(stop, commandString(command), true);
+  root.hooks = hooks;
+  return `${JSON.stringify(sortJson(root), null, 2)}
+`;
+}
+function mergeCodexHooks(existingContent, command) {
+  const root = parseObject(existingContent);
+  const hooks = asObject(root.hooks);
+  const stop = asArray(hooks.Stop);
+  hooks.Stop = appendCommandHook(stop, commandString(command), true);
+  root.hooks = hooks;
+  return `${JSON.stringify(sortJson(root), null, 2)}
+`;
+}
+function mergeCursorHooks(existingContent, command) {
+  const root = parseObject(existingContent);
+  const hooks = asObject(root.hooks);
+  const stop = asArray(hooks.stop);
+  const commandValue = commandString(command);
+  hooks.stop = stop.some((entry) => isObject3(entry) && entry.command === commandValue) ? stop : [...stop, { command: commandValue }];
+  root.version = typeof root.version === "number" ? root.version : 1;
+  root.hooks = hooks;
+  return `${JSON.stringify(sortJson(root), null, 2)}
+`;
+}
+function appendCommandHook(entries, command, includeType) {
+  if (entries.some((entry) => hookGroupHasCommand(entry, command))) {
+    return entries;
+  }
+  const hook = includeType ? { type: "command", command, timeout: 30 } : { command };
+  return [...entries, { hooks: [hook] }];
+}
+function hookGroupHasCommand(entry, command) {
+  return isObject3(entry) && Array.isArray(entry.hooks) && entry.hooks.some((hook) => isObject3(hook) && hook.command === command);
+}
+function commandString(command) {
+  return [command.command, ...command.args].join(" ");
+}
+function parseObject(content) {
+  const parsed = content?.trim() ? JSON.parse(content) : {};
+  return isObject3(parsed) ? parsed : {};
+}
+function asObject(value) {
+  return isObject3(value) ? value : {};
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (!isObject3(value)) {
+    return value;
+  }
+  return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, sortJson(item)]));
+}
+function isObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/agents/merge-json.ts
+function mergeMcpJson(existingContent, command) {
+  const parsed = existingContent?.trim() ? JSON.parse(existingContent) : {};
+  const root = isObject4(parsed) ? parsed : {};
+  const mcpServers = isObject4(root.mcpServers) ? root.mcpServers : {};
+  root.mcpServers = {
+    ...mcpServers,
+    "node-boost": {
+      command: command.command,
+      args: command.args
+    }
+  };
+  return `${JSON.stringify(sortJson2(root), null, 2)}
+`;
+}
+function sortJson2(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson2);
+  }
+  if (!isObject4(value)) {
+    return value;
+  }
+  return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, sortJson2(item)]));
+}
+function isObject4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/agents/managed-block.ts
+var managedBlockStart = "<!-- node-boost:start -->";
+var managedBlockEnd = "<!-- node-boost:end -->";
+function renderManagedBlock(body) {
+  return `${managedBlockStart}
+${body.trim()}
+${managedBlockEnd}
+`;
+}
+function upsertManagedBlock(existingContent, body) {
+  const block = renderManagedBlock(body);
+  if (!existingContent) {
+    return block;
+  }
+  const pattern = new RegExp(`${escapeRegExp(managedBlockStart)}[\\s\\S]*?${escapeRegExp(managedBlockEnd)}\\n?`);
+  if (pattern.test(existingContent)) {
+    return existingContent.replace(pattern, block);
+  }
+  const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+  return `${existingContent}${separator}${block}`;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/agents/claude-code.ts
+var claudeCodeAgent = {
+  name: "claude-code",
+  capabilities: {
+    supportsGuidelines: true,
+    supportsSkills: true,
+    supportsMcp: true,
+    supportsHooks: true
+  },
+  render(context) {
+    const body = [
+      "# node-boost",
+      "",
+      `Use ${context.guidelinesIndexPath} as the generated guidance index.`,
+      `Repo skills are available in ${context.skillsIndexPath} and mirrored to .claude/skills.`,
+      `MCP command: ${formatMcpCommand(context.mcpCommand)}.`
+    ].join("\n");
+    return [
+      {
+        path: "CLAUDE.md",
+        content: upsertManagedBlock(context.existingContent("CLAUDE.md"), body)
+      },
+      {
+        path: ".mcp.json",
+        content: mergeMcpJson(context.existingContent(".mcp.json"), context.mcpCommand)
+      },
+      {
+        path: ".claude/settings.json",
+        content: mergeClaudeCodeHooks(context.existingContent(".claude/settings.json"), context.hookCommands["claude-code"])
+      },
+      ...context.selectedSkills.map((skill) => ({
+        path: skill.outputPath.replace(/^\.ai\/skills\//, ".claude/skills/"),
+        content: context.skillContentByOutputPath.get(skill.outputPath) ?? ""
+      }))
+    ];
+  }
+};
+
+// src/agents/merge-toml.ts
+import { parse, stringify } from "smol-toml";
+function mergeCodexMcpToml(existingContent, command) {
+  const parsed = existingContent?.trim() ? parse(existingContent) : {};
+  const root = isObject5(parsed) ? parsed : {};
+  const mcpServers = isObject5(root.mcp_servers) ? root.mcp_servers : {};
+  root.mcp_servers = {
+    ...mcpServers,
+    "node-boost": {
+      command: command.command,
+      args: command.args
+    }
+  };
+  return `${stringify(sortToml(root)).trim()}
+`;
+}
+function sortToml(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortToml);
+  }
+  if (!isObject5(value)) {
+    return value;
+  }
+  return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, sortToml(item)]));
+}
+function isObject5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/agents/codex.ts
+var codexAgent = {
+  name: "codex",
+  capabilities: {
+    supportsGuidelines: true,
+    supportsSkills: true,
+    supportsMcp: true,
+    supportsHooks: true
+  },
+  render(context) {
+    const body = [
+      "# node-boost",
+      "",
+      `Use ${context.guidelinesIndexPath} as the generated guidance index.`,
+      `Repo skills are installed in .agents/skills and source skills are indexed in ${context.skillsIndexPath}.`,
+      `MCP command: ${formatMcpCommand(context.mcpCommand)}.`
+    ].join("\n");
+    return [
+      {
+        path: "AGENTS.md",
+        content: upsertManagedBlock(context.existingContent("AGENTS.md"), body)
+      },
+      {
+        path: ".codex/config.toml",
+        content: mergeCodexMcpToml(context.existingContent(".codex/config.toml"), context.mcpCommand)
+      },
+      {
+        path: ".codex/hooks.json",
+        content: mergeCodexHooks(context.existingContent(".codex/hooks.json"), context.hookCommands.codex)
+      },
+      ...context.selectedSkills.map((skill) => ({
+        path: skill.outputPath.replace(/^\.ai\/skills\//, ".agents/skills/"),
+        content: context.skillContentByOutputPath.get(skill.outputPath) ?? ""
+      }))
+    ];
+  }
+};
+
+// src/agents/cursor.ts
+var cursorAgent = {
+  name: "cursor",
+  capabilities: {
+    supportsGuidelines: true,
+    supportsSkills: true,
+    supportsMcp: true,
+    supportsHooks: true
+  },
+  render(context) {
+    return [
+      {
+        path: ".cursor/rules/node-boost.mdc",
+        content: [
+          "---",
+          "alwaysApply: true",
+          "---",
+          "",
+          "# node-boost",
+          "",
+          `Use ${context.guidelinesIndexPath} as the generated guidance index.`,
+          `Skills are indexed in ${context.skillsIndexPath}.`,
+          `MCP command: ${formatMcpCommand(context.mcpCommand)}.`,
+          ""
+        ].join("\n")
+      },
+      {
+        path: ".cursor/mcp.json",
+        content: mergeMcpJson(context.existingContent(".cursor/mcp.json"), context.mcpCommand)
+      },
+      {
+        path: ".cursor/hooks.json",
+        content: mergeCursorHooks(context.existingContent(".cursor/hooks.json"), context.hookCommands.cursor)
+      }
+    ];
+  }
+};
+
+// src/agents/index.ts
+var agentInstallers = {
+  "claude-code": claudeCodeAgent,
+  codex: codexAgent,
+  cursor: cursorAgent
+};
+
+// src/compose/overrides.ts
+import { access as access3 } from "fs/promises";
+import { join as join9, relative as relative2 } from "path";
+async function applyResourceOverrides(projectRoot, resources) {
+  return Promise.all(resources.map((resource) => applyResourceOverride(projectRoot, resource)));
+}
+async function applyResourceOverride(projectRoot, resource) {
+  const outputRelative = normalize2(relative2(join9(".ai", resource.kind === "guideline" ? "guidelines" : "skills"), resource.outputPath));
+  const overridePath = join9(projectRoot, ".node-boost", resource.kind === "guideline" ? "guidelines" : "skills", outputRelative);
+  try {
+    await access3(overridePath);
+    return {
+      ...resource,
+      sourcePath: overridePath
+    };
+  } catch {
+    return resource;
+  }
+}
+function normalize2(path) {
+  return path.split("\\").join("/");
+}
+
+// src/compose/guidelines.ts
+import { join as join11 } from "path";
+
+// src/compose/resources.ts
+import { readdir as readdir2 } from "fs/promises";
+import { join as join10, relative as relative3 } from "path";
+async function listResourceFiles(rootDir, kind) {
+  const baseDir = join10(rootDir, "resources", "react", kind);
+  const files = await walkMarkdownFiles(baseDir);
+  return files.map((file) => relative3(baseDir, file)).sort((a, b) => a.localeCompare(b));
+}
+async function walkMarkdownFiles(dir) {
+  let entries;
+  try {
+    entries = await readdir2(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const fullPath = join10(dir, entry.name);
+      if (entry.isDirectory()) {
+        return walkMarkdownFiles(fullPath);
+      }
+      if (entry.isFile() && (entry.name.endsWith(".md") || entry.name === "SKILL.md")) {
+        return [fullPath];
+      }
+      return [];
+    })
+  );
+  return files.flat();
+}
+
+// src/compose/guidelines.ts
+var packageResourceMap = {
+  react: "react",
+  next: "next",
+  vite: "vite",
+  "react-router": "react-router",
+  zod: "zod",
+  "@tanstack/react-query": "react-query",
+  zustand: "zustand",
+  typescript: "typescript",
+  tailwindcss: "tailwindcss",
+  vitest: "testing",
+  playwright: "testing"
+};
+async function composeGuidelines(rootDir, stack, architectures = []) {
+  const availableFiles = await listResourceFiles(rootDir, "guidelines");
+  const selected = /* @__PURE__ */ new Set(["core.md"]);
+  for (const [packageName, resourceName] of Object.entries(packageResourceMap)) {
+    const packageInfo = stack.packages[packageName];
+    if (!packageInfo?.version) {
+      continue;
+    }
+    addIfAvailable(selected, availableFiles, `${resourceName}/core.md`);
+    if (packageInfo.major !== null) {
+      addIfAvailable(selected, availableFiles, `${resourceName}/${packageInfo.major}.md`);
+    }
+  }
+  if (stack.packages.vitest?.version) {
+    addIfAvailable(selected, availableFiles, "testing/vitest.md");
+  }
+  if (stack.packages.playwright?.version) {
+    addIfAvailable(selected, availableFiles, "testing/playwright.md");
+  }
+  const packageGuidelines = [...selected].sort((a, b) => a.localeCompare(b)).map((file) => ({
+    kind: "guideline",
+    sourcePath: join11("resources", "react", "guidelines", file),
+    outputPath: join11(".ai", "guidelines", file)
+  }));
+  const architectureGuidelines = architectures.map((architecture) => ({
+    kind: "guideline",
+    sourcePath: join11("resources", "react", "architectures", architecture.name, architectureVariantPath(architecture)),
+    outputPath: join11(".ai", "guidelines", "architectures", `${architecture.name}.md`)
+  }));
+  return [...packageGuidelines, ...architectureGuidelines].sort((a, b) => a.outputPath.localeCompare(b.outputPath));
+}
+function addIfAvailable(selected, availableFiles, file) {
+  if (availableFiles.includes(file)) {
+    selected.add(file);
+  }
+}
+function architectureVariantPath(architecture) {
+  if (architecture.name === "feature-modules" && typeof architecture.options.boundary === "string") {
+    return join11("variants", `${architecture.options.boundary}.md`);
+  }
+  return "guideline.md";
+}
+
+// src/compose/skills.ts
+import { join as join12 } from "path";
+async function composeSkills(rootDir, stack, architectures = []) {
+  const availableFiles = await listResourceFiles(rootDir, "skills");
+  const selected = /* @__PURE__ */ new Set();
+  if (stack.packages.react?.version) {
+    selected.add("react-development/SKILL.md");
+  }
+  if (stack.name === "next") {
+    selected.add("next-development/SKILL.md");
+  }
+  if (stack.name === "vite-react") {
+    selected.add("spa-routing/SKILL.md");
+  }
+  if (stack.packages.tailwindcss?.version) {
+    selected.add("tailwindcss-development/SKILL.md");
+  }
+  if (stack.packages.vitest?.version || stack.packages.playwright?.version) {
+    selected.add("testing-frontend/SKILL.md");
+  }
+  const packageSkills = [...selected].filter((file) => availableFiles.includes(file)).sort((a, b) => a.localeCompare(b)).map((file) => ({
+    kind: "skill",
+    sourcePath: join12("resources", "react", "skills", file),
+    outputPath: join12(".ai", "skills", file)
+  }));
+  const architectureSkills = architectures.map((architecture) => ({
+    kind: "skill",
+    sourcePath: join12("resources", "react", "architectures", architecture.name, "skill", "SKILL.md"),
+    outputPath: join12(".ai", "skills", architecture.name, "SKILL.md")
+  }));
+  return [...packageSkills, ...architectureSkills].sort((a, b) => a.outputPath.localeCompare(b.outputPath));
+}
+
+// src/compose/index-file.ts
+function renderGuidelinesIndex(stack, architectures, guidelines) {
+  const packages = Object.values(stack.packages).filter((pkg) => pkg.version).sort((a, b) => a.name.localeCompare(b.name)).map((pkg) => `- ${pkg.name}: ${pkg.version} (${pkg.source})`);
+  const architectureLines = architectures.map((architecture) => {
+    const suffix = architecture.name === "feature-modules" ? ` (${featureModulesBoundary(architecture)})` : "";
+    return `- ${architecture.name}${suffix}`;
+  });
+  const fileLines = guidelines.map((guideline) => `- ${guideline.outputPath}: ${sourceLabel(guideline.sourcePath)}`).sort((a, b) => a.localeCompare(b));
+  return [
+    "# node-boost guidelines",
+    "",
+    "## Stack",
+    "",
+    `- name: ${stack.name}`,
+    `- router: ${stack.router}`,
+    `- package manager: ${stack.packageManager.name}`,
+    `- linting: ${stack.linting}`,
+    "",
+    "## Packages",
+    "",
+    ...packages.length ? packages : ["- none detected"],
+    "",
+    "## Architectures",
+    "",
+    ...architectureLines.length ? architectureLines : ["- none selected"],
+    "",
+    "## Files",
+    "",
+    ...fileLines,
+    ""
+  ].join("\n");
+}
+function sourceLabel(sourcePath) {
+  return sourcePath.includes(".node-boost") ? "project override" : "node-boost built-in";
+}
+function featureModulesBoundary(architecture) {
+  return typeof architecture.options.boundary === "string" ? architecture.options.boundary : "public-api";
+}
+
+// src/stacks/architectures.ts
+var commonArchitectures = [
+  "feature-modules",
+  "data-access-layer",
+  "typed-contracts",
+  "state-management",
+  "custom-hooks",
+  "component-composition",
+  "testing-strategy",
+  "secure-by-default",
+  "modern-typescript",
+  "ui-states"
+];
+var nextOnlyArchitectures = [
+  "server-first-components",
+  "error-loading-boundaries"
+];
+var tailwindArchitecture = "styling-tailwind";
+function sortArchitectures(architectures) {
+  return [...architectures].sort((a, b) => a.localeCompare(b));
+}
+
+// src/stacks/next.ts
+var nextStackAdapter = {
+  name: "next",
+  label: "Next.js",
+  supports(stack) {
+    return stack.name === "next";
+  },
+  applicableArchitectures(stack) {
+    const architectures = [...commonArchitectures, ...nextOnlyArchitectures];
+    if (hasPackage(stack, "tailwindcss")) {
+      architectures.push(tailwindArchitecture);
+    }
+    return sortArchitectures(architectures);
+  },
+  recommendedArchitectures(stack) {
+    return this.applicableArchitectures(stack);
+  }
+};
+
+// src/stacks/vite-react.ts
+var viteReactStackAdapter = {
+  name: "vite-react",
+  label: "Vite React",
+  supports(stack) {
+    return stack.name === "vite-react";
+  },
+  applicableArchitectures(stack) {
+    const architectures = [...commonArchitectures];
+    if (hasPackage(stack, "tailwindcss")) {
+      architectures.push(tailwindArchitecture);
+    }
+    return sortArchitectures(architectures);
+  },
+  recommendedArchitectures(stack) {
+    return this.applicableArchitectures(stack);
+  }
+};
+
+// src/stacks/adapter.ts
+var stackAdapters = [nextStackAdapter, viteReactStackAdapter];
+function getStackAdapter(stack) {
+  return stackAdapters.find((adapter) => adapter.supports(stack)) ?? null;
+}
+function hasPackage(stack, packageName) {
+  return Boolean(stack.packages[packageName]?.version);
+}
+
+// src/install/project.ts
+import { access as access4, readFile as readFile4 } from "fs/promises";
+import { dirname as dirname4, join as join13 } from "path";
+import { fileURLToPath } from "url";
+async function findNearestPackageRoot(cwd) {
+  let current = cwd;
+  while (true) {
+    if (await pathExists(join13(current, "package.json"))) {
+      return current;
+    }
+    const parent = dirname4(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+async function readPackageJson2(rootDir) {
+  const raw = await readFile4(join13(rootDir, "package.json"), "utf8");
+  const parsed = JSON.parse(raw);
+  if (!isObject6(parsed)) {
+    throw new Error("package.json must contain an object.");
+  }
+  return parsed;
+}
+async function isWorkspaceRoot(rootDir) {
+  const packageJson = await readPackageJson2(rootDir);
+  return Boolean(packageJson.workspaces) || await pathExists(join13(rootDir, "pnpm-workspace.yaml"));
+}
+async function resolveDefaultPackageRoot(importMetaUrl) {
+  let current = dirname4(fileURLToPath(importMetaUrl));
+  while (true) {
+    if (await pathExists(join13(current, "resources", "react"))) {
+      return current;
+    }
+    const parent = dirname4(current);
+    if (parent === current) {
+      return process.cwd();
+    }
+    current = parent;
+  }
+}
+async function pathExists(path) {
+  try {
+    await access4(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isObject6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/install/orchestrator.ts
+var allAgents = ["claude-code", "codex", "cursor"];
+var defaultFeatures2 = {
+  guidelines: true,
+  skills: true,
+  mcp: true,
+  architecture: true,
+  hooks: false
+};
+async function runInstall(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const packageRoot = options.packageRoot ?? await resolveDefaultPackageRoot(import.meta.url);
+  const projectRoot = await resolveProjectRoot(cwd);
+  const stack = await detectStack(projectRoot);
+  const config = options.noInteraction ? await createDefaultConfig(packageRoot, projectRoot, stack) : await promptForConfig(packageRoot, projectRoot, stack);
+  const operations = await buildInstallOperations({ packageRoot, projectRoot, stack, config });
+  const applied = await applyFileOperations(projectRoot, operations);
+  if (!options.noInteraction) {
+    outro(renderSummary(applied));
+  }
+  return {
+    projectRoot,
+    stack,
+    config,
+    operations: applied
+  };
+}
+async function runUpdate(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const packageRoot = options.packageRoot ?? await resolveDefaultPackageRoot(import.meta.url);
+  const projectRoot = await resolveProjectRoot(cwd);
+  const stack = await detectStack(projectRoot);
+  const configPath = join14(projectRoot, "node-boost.json");
+  const rawConfig = await readFile5(configPath, "utf8");
+  const config = parseConfigWithReadableErrors(JSON.parse(rawConfig));
+  const operations = await buildInstallOperations({ packageRoot, projectRoot, stack, config });
+  return {
+    projectRoot,
+    stack,
+    config,
+    operations: await applyFileOperations(projectRoot, operations)
+  };
+}
+async function buildInstallOperations(input) {
+  const architectures = input.config.features.architecture ? normalizeArchitectures(input.config) : [];
+  const selectedGuidelines = input.config.features.guidelines ? await applyResourceOverrides(input.projectRoot, await composeGuidelines(input.packageRoot, input.stack, architectures)) : [];
+  const selectedSkills = input.config.features.skills ? await applyResourceOverrides(input.projectRoot, await composeSkills(input.packageRoot, input.stack, architectures)) : [];
+  const guidelineOperations = await readResourceOperations(input.packageRoot, selectedGuidelines);
+  const skillOperations = await readResourceOperations(input.packageRoot, selectedSkills);
+  const skillContentByOutputPath = new Map(skillOperations.map((operation) => [operation.path, operation.content]));
+  const existingContent = await preloadExisting(input.projectRoot, [
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".mcp.json",
+    ".claude/settings.json",
+    ".codex/hooks.json",
+    ".codex/config.toml",
+    ".cursor/hooks.json",
+    ".cursor/mcp.json"
+  ]);
+  const mcpCommand2 = createMcpCommand(input.stack.packageManager.name);
+  const hookCommands = {
+    "claude-code": createHookCommand(input.stack.packageManager.name, "claude-code"),
+    codex: createHookCommand(input.stack.packageManager.name, "codex"),
+    cursor: createHookCommand(input.stack.packageManager.name, "cursor")
+  };
+  const agentOperations = input.config.agents.flatMap(
+    (agentName) => agentInstallers[agentName].render({
+      guidelinesIndexPath: ".ai/guidelines/node-boost.md",
+      skillsIndexPath: ".ai/skills",
+      selectedSkills,
+      existingContent: (path) => existingContent.get(path) ?? null,
+      skillContentByOutputPath,
+      mcpCommand: mcpCommand2,
+      hookCommands
+    }).filter((operation) => keepOperationForFeatures(operation.path, input.config.features))
+  );
+  return dedupeOperations([
+    ...guidelineOperations,
+    {
+      path: ".ai/guidelines/node-boost.md",
+      content: renderGuidelinesIndex(input.stack, architectures, selectedGuidelines)
+    },
+    ...skillOperations,
+    ...agentOperations,
+    {
+      path: "node-boost.json",
+      content: `${JSON.stringify(input.config, null, 2)}
+`
+    }
+  ]);
+}
+async function applyFileOperations(projectRoot, operations) {
+  const results = [];
+  for (const operation of operations) {
+    const target = join14(projectRoot, operation.path);
+    const previous = await readOptional(target);
+    const status = previous === null ? "created" : previous === operation.content ? "skipped" : "updated";
+    if (status !== "skipped") {
+      await mkdir(dirname5(target), { recursive: true });
+      await writeFile(target, operation.content, "utf8");
+    }
+    results.push({ ...operation, status });
+  }
+  return results;
+}
+async function resolveProjectRoot(cwd) {
+  const projectRoot = await findNearestPackageRoot(cwd);
+  if (!projectRoot) {
+    throw new Error("No package.json found. Run node-boost inside a Node project.");
+  }
+  const stack = await detectStack(projectRoot);
+  if (stack.name === "unknown" && await isWorkspaceRoot(projectRoot)) {
+    throw new Error("Workspace root has no detectable React stack. Run node-boost in an app directory, for example apps/web.");
+  }
+  return projectRoot;
+}
+async function createDefaultConfig(packageRoot, projectRoot, stack) {
+  return nodeBoostConfigSchema.parse({
+    $schema: "./schema.json",
+    version: 1,
+    generatedWith: await readPackageVersion(packageRoot),
+    stack: stack.name,
+    agents: allAgents,
+    features: defaultFeatures2,
+    architectures: await defaultArchitectures(projectRoot, stack),
+    audit: {
+      exclude: [],
+      rules: {},
+      ruleOptions: {}
+    }
+  });
+}
+async function promptForConfig(packageRoot, projectRoot, stack) {
+  intro(`node-boost install: ${stack.name} / ${stack.packageManager.name}`);
+  const agents = await multiselect({
+    message: "Select agents",
+    options: allAgents.map((agent) => ({ label: agent, value: agent })),
+    initialValues: [...allAgents],
+    required: true
+  });
+  abortIfCancelled(agents);
+  const features = await multiselect({
+    message: "Select features",
+    options: [
+      { label: "Guidelines", value: "guidelines" },
+      { label: "Skills", value: "skills" },
+      { label: "MCP config", value: "mcp" },
+      { label: "Architecture guidance", value: "architecture" },
+      { label: "Hooks config flag", value: "hooks" }
+    ],
+    initialValues: ["guidelines", "skills", "mcp", "architecture"],
+    required: true
+  });
+  abortIfCancelled(features);
+  const featureConfig = {
+    guidelines: features.includes("guidelines"),
+    skills: features.includes("skills"),
+    mcp: features.includes("mcp"),
+    architecture: features.includes("architecture"),
+    hooks: features.includes("hooks")
+  };
+  const architectures = featureConfig.architecture ? await promptArchitectures(projectRoot, stack) : [];
+  const confirmed = await confirm({
+    message: "Write node-boost files?",
+    initialValue: true
+  });
+  abortIfCancelled(confirmed);
+  if (!confirmed) {
+    cancel("Install cancelled.");
+    process.exitCode = 1;
+    throw new Error("Install cancelled.");
+  }
+  return nodeBoostConfigSchema.parse({
+    $schema: "./schema.json",
+    version: 1,
+    generatedWith: await readPackageVersion(packageRoot),
+    stack: stack.name,
+    agents,
+    features: featureConfig,
+    architectures,
+    audit: {
+      exclude: [],
+      rules: {},
+      ruleOptions: {}
+    }
+  });
+}
+async function promptArchitectures(projectRoot, stack) {
+  const adapter = getStackAdapter(stack);
+  const recommended = adapter?.recommendedArchitectures(stack) ?? [];
+  const selected = await multiselect({
+    message: "Select architecture guidance",
+    options: recommended.map((architecture) => ({ label: architecture, value: architecture })),
+    initialValues: recommended,
+    required: false
+  });
+  abortIfCancelled(selected);
+  if (!selected.includes("feature-modules")) {
+    return selected;
+  }
+  const suggestedBoundary = await suggestFeatureModulesBoundary(projectRoot);
+  const boundary = await select({
+    message: "Feature modules boundary",
+    options: [
+      { label: "Public API imports", value: "public-api", hint: "Use when features already import from each other." },
+      { label: "Forbid cross-feature imports", value: "forbid", hint: "Use for greenfield or clean module boundaries." }
+    ],
+    initialValue: suggestedBoundary
+  });
+  abortIfCancelled(boundary);
+  return selected.map(
+    (architecture) => architecture === "feature-modules" ? { name: "feature-modules", boundary } : architecture
+  );
+}
+async function defaultArchitectures(projectRoot, stack) {
+  const adapter = getStackAdapter(stack);
+  const architectures = adapter?.recommendedArchitectures(stack) ?? [];
+  const featureModulesBoundary2 = await suggestFeatureModulesBoundary(projectRoot);
+  return architectures.map(
+    (architecture) => architecture === "feature-modules" ? { name: "feature-modules", boundary: featureModulesBoundary2 } : architecture
+  );
+}
+async function suggestFeatureModulesBoundary(projectRoot) {
+  return await pathExists(join14(projectRoot, "features")) || await pathExists(join14(projectRoot, "src", "features")) ? "public-api" : "forbid";
+}
+async function readResourceOperations(packageRoot, resources) {
+  return Promise.all(
+    resources.map(async (resource) => ({
+      path: resource.outputPath,
+      content: await readSource(packageRoot, resource.sourcePath)
+    }))
+  );
+}
+async function readSource(packageRoot, sourcePath) {
+  const raw = await readFile5(isAbsolute(sourcePath) ? sourcePath : join14(packageRoot, sourcePath), "utf8");
+  return raw.endsWith("\n") ? raw : `${raw}
+`;
+}
+async function preloadExisting(projectRoot, paths) {
+  const entries = await Promise.all(paths.map(async (path) => [path, await readOptional(join14(projectRoot, path))]));
+  return new Map(entries);
+}
+async function readOptional(path) {
+  try {
+    return await readFile5(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function readPackageVersion(packageRoot) {
+  const packageJson = await readPackageJson2(packageRoot);
+  return packageJson.version ?? "0.0.0";
+}
+function keepOperationForFeatures(path, features) {
+  if ((path === ".mcp.json" || path === ".codex/config.toml" || path === ".cursor/mcp.json") && !features.mcp) {
+    return false;
+  }
+  if ((path === ".claude/settings.json" || path === ".codex/hooks.json" || path === ".cursor/hooks.json") && !features.hooks) {
+    return false;
+  }
+  if ((path.startsWith(".claude/skills/") || path.startsWith(".agents/skills/")) && !features.skills) {
+    return false;
+  }
+  if ((path === "CLAUDE.md" || path === "AGENTS.md" || path === ".cursor/rules/node-boost.mdc") && !features.guidelines && !features.skills) {
+    return false;
+  }
+  return true;
+}
+function dedupeOperations(operations) {
+  return [...new Map(operations.map((operation) => [operation.path, operation])).values()].sort(
+    (a, b) => a.path.localeCompare(b.path)
+  );
+}
+function parseConfigWithReadableErrors(input) {
+  try {
+    return parseNodeBoostConfig(input);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const issues = error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("\n");
+      throw new Error(`Invalid node-boost.json:
+${issues}`, { cause: error });
+    }
+    throw error;
+  }
+}
+function abortIfCancelled(value) {
+  if (isCancel(value)) {
+    cancel("Install cancelled.");
+    process.exitCode = 1;
+    throw new Error("Install cancelled.");
+  }
+}
+function renderSummary(results) {
+  const counts = results.reduce(
+    (summary, result) => {
+      summary[result.status] += 1;
+      return summary;
+    },
+    { created: 0, updated: 0, skipped: 0 }
+  );
+  return `created ${counts.created}, updated ${counts.updated}, skipped ${counts.skipped}`;
+}
+
+// src/mcp/project.ts
+import { readFile as readFile6 } from "fs/promises";
+import { join as join15 } from "path";
+import { ZodError as ZodError2 } from "zod";
+async function readBoostConfig(rootDir) {
+  try {
+    const raw = await readFile6(join15(rootDir, "node-boost.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const config = parseNodeBoostConfig(parsed);
+    return {
+      config,
+      architectures: normalizeArchitectures(config),
+      error: null
+    };
+  } catch (error) {
+    return {
+      config: null,
+      architectures: [],
+      error: normalizeConfigError(error)
+    };
+  }
+}
+async function readTypescriptStrict(rootDir) {
+  try {
+    const raw = await readFile6(join15(rootDir, "tsconfig.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (isObject7(parsed) && isObject7(parsed.compilerOptions) && typeof parsed.compilerOptions.strict === "boolean") {
+      return parsed.compilerOptions.strict;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function normalizeConfigError(error) {
+  if (error instanceof SyntaxError) {
+    return new Error(`Invalid JSON: ${error.message}`, { cause: error });
+  }
+  if (error instanceof ZodError2) {
+    const message = error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    return new Error(message, { cause: error });
+  }
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error("Unknown config error.");
+}
+function isObject7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/mcp/tools/doctor.ts
+async function doctorTool(rootDir, boostVersion) {
+  const checks = [];
+  const configRaw = await readOptional2(join16(rootDir, "node-boost.json"));
+  const boostConfig = await readBoostConfig(rootDir);
+  const stack = await detectStack(rootDir);
+  checks.push({
+    id: "config-present",
+    status: configRaw === null ? "fail" : "pass",
+    message: configRaw === null ? "node-boost.json is missing. Run node-boost install." : "node-boost.json is present."
+  });
+  checks.push({
+    id: "config-valid",
+    status: boostConfig.config ? "pass" : "fail",
+    message: boostConfig.config ? "node-boost.json is valid." : `node-boost.json is invalid: ${boostConfig.error?.message ?? "unknown error"}`
+  });
+  checks.push({
+    id: "generated-with-drift",
+    status: !boostConfig.config || boostConfig.config.generatedWith === boostVersion ? "pass" : "warn",
+    message: !boostConfig.config ? "No generatedWith drift can be checked without a valid config." : boostConfig.config.generatedWith === boostVersion ? "generatedWith matches the installed package version." : `generatedWith is ${boostConfig.config.generatedWith}, package is ${boostVersion}. Run node-boost update.`
+  });
+  checks.push({
+    id: "stack-detected",
+    status: stack.name === "unknown" ? "fail" : "pass",
+    message: stack.name === "unknown" ? "No supported React stack detected." : `Detected ${stack.name}.`
+  });
+  if (!boostConfig.config) {
+    checks.push(skipCheck("resources-fresh", "Requires a valid node-boost.json."));
+    checks.push(skipCheck("agent-files-present", "Requires a valid node-boost.json."));
+    checks.push(await overridesCheck(rootDir));
+    checks.push(skipCheck("hooks-wired", "Requires a valid node-boost.json."));
+    checks.push(await lintStrictCheck(rootDir));
+    return withOk(checks);
+  }
+  const packageRoot = await resolveDefaultPackageRoot(import.meta.url);
+  const expectedOperations = await buildInstallOperations({
+    packageRoot,
+    projectRoot: rootDir,
+    stack,
+    config: boostConfig.config
+  });
+  checks.push(await resourcesFreshCheck(rootDir, expectedOperations));
+  checks.push(await agentFilesPresentCheck(rootDir, expectedOperations));
+  checks.push(await overridesCheck(rootDir));
+  checks.push(await hooksWiredCheck(rootDir, boostConfig.config.features.hooks, expectedOperations));
+  checks.push(await lintStrictCheck(rootDir));
+  return withOk(checks);
+}
+async function resourcesFreshCheck(rootDir, expectedOperations) {
+  const stale = await changedExpectedFiles(rootDir, expectedOperations.filter((operation) => operation.path.startsWith(".ai/")));
+  return {
+    id: "resources-fresh",
+    status: stale.length === 0 ? "pass" : "warn",
+    message: stale.length === 0 ? "Generated .ai resources match current node-boost output." : `${stale.length} generated .ai resource(s) differ. Run node-boost update.`,
+    details: stale
+  };
+}
+async function agentFilesPresentCheck(rootDir, expectedOperations) {
+  const expected = expectedOperations.filter((operation) => !operation.path.startsWith(".ai/") && operation.path !== "node-boost.json").map((operation) => operation.path);
+  const missing = await missingFiles(rootDir, expected);
+  return {
+    id: "agent-files-present",
+    status: missing.length === 0 ? "pass" : "fail",
+    message: missing.length === 0 ? "Configured agent files are present." : `${missing.length} configured agent file(s) missing. Run node-boost update.`,
+    details: missing
+  };
+}
+async function hooksWiredCheck(rootDir, hooksEnabled, expectedOperations) {
+  if (!hooksEnabled) {
+    return {
+      id: "hooks-wired",
+      status: "pass",
+      message: "Hooks feature is disabled."
+    };
+  }
+  const hookOperations = expectedOperations.filter(
+    (operation) => operation.path === ".claude/settings.json" || operation.path === ".codex/hooks.json" || operation.path === ".cursor/hooks.json"
+  );
+  const stale = await changedExpectedFiles(rootDir, hookOperations);
+  return {
+    id: "hooks-wired",
+    status: stale.length === 0 ? "pass" : "fail",
+    message: stale.length === 0 ? "Configured hook entries are wired." : `${stale.length} hook config file(s) missing or stale. Run node-boost update.`,
+    details: stale
+  };
+}
+async function overridesCheck(rootDir) {
+  const overrides = await listFiles(join16(rootDir, ".node-boost"));
+  return {
+    id: "overrides-detected",
+    status: "pass",
+    message: overrides.length === 0 ? "No .node-boost overrides detected." : `${overrides.length} .node-boost override(s) active.`,
+    details: overrides.map((file) => relative4(join16(rootDir, ".node-boost"), file).replaceAll("\\", "/"))
+  };
+}
+async function lintStrictCheck(rootDir) {
+  const strict = await tsconfigStrict2(rootDir);
+  return {
+    id: "lint-strict",
+    status: strict === true ? "pass" : "warn",
+    message: strict === true ? "TypeScript strict mode is enabled." : "TypeScript strict mode is not enabled. Enable compilerOptions.strict."
+  };
+}
+async function changedExpectedFiles(rootDir, expectedOperations) {
+  const changed = await Promise.all(
+    expectedOperations.map(async (operation) => {
+      const current = await readOptional2(join16(rootDir, operation.path));
+      return current === operation.content ? null : operation.path;
+    })
+  );
+  return changed.filter((path) => path !== null).sort((a, b) => a.localeCompare(b));
+}
+async function missingFiles(rootDir, paths) {
+  const missing = await Promise.all(paths.map(async (path) => await readOptional2(join16(rootDir, path)) === null ? path : null));
+  return missing.filter((path) => path !== null).sort((a, b) => a.localeCompare(b));
+}
+async function listFiles(dir) {
+  try {
+    const entries = await readdir3(dir, { withFileTypes: true });
+    const nested = await Promise.all(
+      entries.map(async (entry) => {
+        const path = join16(dir, entry.name);
+        if (entry.isDirectory()) {
+          return listFiles(path);
+        }
+        return entry.isFile() ? [path] : [];
+      })
+    );
+    return nested.flat().sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+async function tsconfigStrict2(rootDir) {
+  const visited = /* @__PURE__ */ new Set();
+  return readStrictFromTsconfig2(join16(rootDir, "tsconfig.json"), visited);
+}
+async function readStrictFromTsconfig2(path, visited) {
+  if (visited.has(path)) {
+    return null;
+  }
+  visited.add(path);
+  const raw = await readOptional2(path);
+  if (!raw) {
+    return null;
+  }
+  const parsed = JSON.parse(stripJsonComments2(raw));
+  if (typeof parsed.compilerOptions?.strict === "boolean") {
+    return parsed.compilerOptions.strict;
+  }
+  if (parsed.extends?.startsWith(".")) {
+    return readStrictFromTsconfig2(join16(path, "..", parsed.extends), visited);
+  }
+  return null;
+}
+async function readOptional2(path) {
+  try {
+    return await readFile7(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function stripJsonComments2(value) {
+  return value.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+function skipCheck(id, message) {
+  return { id, status: "warn", message };
+}
+function withOk(checks) {
+  return {
+    ok: checks.every((check) => check.status !== "fail"),
+    checks
+  };
+}
+
+// src/cli/commands/doctor.ts
+var doctorCommand = defineCommand2({
+  meta: {
+    name: "doctor",
+    description: "Check node-boost config, generated files, hooks, and project strictness."
+  },
+  args: {
+    agent: { type: "boolean", description: "Print machine-readable JSON.", default: false }
+  },
+  async run({ args }) {
+    const result = await doctorTool(process.cwd(), package_default.version);
+    process.stdout.write(args.agent ? `${JSON.stringify(result)}
+` : renderDoctor(result));
+    process.exitCode = result.ok ? 0 : 1;
+  }
+});
+function renderDoctor(result) {
+  return `${result.checks.map(renderCheck).join("\n")}
+`;
+}
+function renderCheck(check) {
+  const icon = check.status === "pass" ? "\u2714" : check.status === "warn" ? "\u26A0" : "\u2716";
+  const details = check.details?.length ? `
+${check.details.map((detail) => `  - ${detail}`).join("\n")}` : "";
+  return `${icon} ${check.id}: ${check.message}${details}`;
+}
+
+// src/cli/commands/explain.ts
+import { defineCommand as defineCommand3 } from "citty";
+var explainCommand = defineCommand3({
+  meta: {
+    name: "explain",
+    description: "Explain a node-boost audit finding."
+  },
+  args: {
+    agent: { type: "boolean", description: "Print machine-readable JSON.", default: false }
+  },
+  run({ args }) {
+    const ruleId = Array.isArray(args._) ? String(args._[0] ?? "") : "";
+    const entry = explainFinding(ruleId);
+    if (!entry) {
+      const message = `Unknown node-boost rule "${ruleId}".
+`;
+      if (args.agent) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: message.trim() })}
+`);
+      } else {
+        process.stderr.write(message);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    if (args.agent) {
+      process.stdout.write(`${JSON.stringify({ ok: true, finding: entry })}
+`);
+      return;
+    }
+    process.stdout.write([
+      `${entry.rule} ${entry.code}`,
+      `Severity: ${entry.severity}`,
+      `Architecture: ${entry.architecture}`,
+      entry.description,
+      entry.rationale,
+      `Fix: ${entry.fix}`,
+      `Guideline: ${entry.guideline}`,
+      ""
+    ].join("\n"));
+  }
+});
+
+// src/cli/commands/guard.ts
+import { defineCommand as defineCommand4 } from "citty";
+
+// src/hooks/report.ts
+function renderBlockingReason(result) {
+  return `node-boost guard found ${result.err} error finding(s).
+
+${renderHumanReport(result)}`;
+}
+
+// src/hooks/claude-code.ts
+function formatClaudeCodeHook(result) {
+  if (result.err > 0) {
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: renderBlockingReason(result)
+    };
+  }
+  return { exitCode: 0, stdout: "", stderr: "" };
+}
+
+// src/hooks/codex.ts
+function formatCodexHook(result) {
+  if (result.err > 0) {
+    return {
+      exitCode: 0,
+      stdout: `${JSON.stringify({ decision: "block", reason: renderBlockingReason(result) })}
+`,
+      stderr: ""
+    };
+  }
+  return {
+    exitCode: 0,
+    stdout: `${JSON.stringify({ continue: true })}
+`,
+    stderr: ""
+  };
+}
+
+// src/hooks/cursor.ts
+function formatCursorHook(result) {
+  if (result.err > 0) {
+    return {
+      exitCode: 0,
+      stdout: `${JSON.stringify({ followup_message: renderBlockingReason(result) })}
+`,
+      stderr: ""
+    };
+  }
+  return {
+    exitCode: 0,
+    stdout: "{}\n",
+    stderr: ""
+  };
+}
+
+// src/hooks/adapter.ts
+async function runGuardHook(agent, rootDir = process.cwd()) {
+  const result = await runAudit({ rootDir, mode: "changed" });
+  if (agent === "claude-code") {
+    return formatClaudeCodeHook(result);
+  }
+  if (agent === "codex") {
+    return formatCodexHook(result);
+  }
+  if (agent === "cursor") {
+    return formatCursorHook(result);
+  }
+  return unsupportedHookAgent(agent);
+}
+function unsupportedHookAgent(agent) {
+  return {
+    exitCode: 1,
+    stdout: "",
+    stderr: `Unsupported hook agent "${agent}". Supported agents: claude-code, codex, cursor.
+`
+  };
+}
+
+// src/cli/commands/guard.ts
+var hookAgents = /* @__PURE__ */ new Set(["claude-code", "codex", "cursor"]);
+var guardCommand = defineCommand4({
+  meta: {
+    name: "guard",
+    description: "Run audit as a hard gate for CI or agent hooks."
+  },
+  args: {
+    hook: { type: "string", description: "Respond using a hook protocol: claude-code, codex, cursor.", required: false }
+  },
+  async run({ args }) {
+    try {
+      if (args.hook) {
+        if (!hookAgents.has(args.hook)) {
+          const response2 = unsupportedHookAgent(args.hook);
+          process.stdout.write(response2.stdout);
+          process.stderr.write(response2.stderr);
+          process.exitCode = response2.exitCode;
+          return;
+        }
+        await readStdin();
+        const response = await runGuardHook(args.hook);
+        process.stdout.write(response.stdout);
+        process.stderr.write(response.stderr);
+        process.exitCode = response.exitCode;
+        return;
+      }
+      const result = await runAudit({ mode: "changed" });
+      process.stdout.write(renderAgentReport(result));
+      process.exitCode = result.err > 0 ? 1 : 0;
+    } catch (error) {
+      if (handleCliError(error)) {
+        return;
+      }
+      throw error;
+    }
+  }
+});
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// src/cli/commands/install.ts
+import { defineCommand as defineCommand5 } from "citty";
+var installCommand = defineCommand5({
+  meta: {
+    name: "install",
+    description: "Generate node-boost guidelines, skills, config, and agent files."
+  },
+  args: {
+    interaction: {
+      type: "boolean",
+      description: "Prompt before writing files. Use --no-interaction for detected defaults.",
+      default: true
+    }
+  },
+  async run({ args }) {
+    const result = await runInstall({ noInteraction: args.interaction === false });
+    const counts = countStatuses(result.operations);
+    console.log(`node-boost install: created ${counts.created}, updated ${counts.updated}, skipped ${counts.skipped}`);
+  }
+});
+function countStatuses(operations) {
+  return operations.reduce(
+    (summary, operation) => {
+      summary[operation.status] += 1;
+      return summary;
+    },
+    { created: 0, updated: 0, skipped: 0 }
+  );
+}
+
+// src/cli/commands/mcp.ts
+import { defineCommand as defineCommand6 } from "citty";
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+
+// src/mcp/errors.ts
+var NodeBoostMcpError = class extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "NodeBoostMcpError";
+  }
+  code;
+};
+function formatMcpError(error) {
+  if (error instanceof NodeBoostMcpError) {
+    return `${error.code}: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `NB-E500: ${error.message}`;
+  }
+  return "NB-E500: Unknown MCP tool error.";
+}
+function isDebugEnabled() {
+  return process.env.NODE_BOOST_DEBUG === "1";
+}
+function debugLog(message) {
+  if (isDebugEnabled()) {
+    process.stderr.write(`${message}
+`);
+  }
+}
+
+// src/mcp/tools/application-info.ts
+import { version as nodeVersion } from "process";
+async function applicationInfoTool(rootDir, boostVersion) {
+  const stack = await detectStack(rootDir);
+  const boostConfig = await readBoostConfig(rootDir);
+  return {
+    node: nodeVersion.replace(/^v/, ""),
+    packageManager: `${stack.packageManager.name}${stack.packageManager.version ? `@${stack.packageManager.version}` : ""}`,
+    typescript: {
+      version: stack.packages.typescript?.version ?? null,
+      strict: await readTypescriptStrict(rootDir)
+    },
+    stack: {
+      name: stack.name,
+      version: stackVersion(stack.packages),
+      router: stack.router,
+      srcDir: stack.srcDir
+    },
+    linting: stack.linting,
+    packages: detectedPackages(stack.packages),
+    boost: boostConfig.config ? {
+      version: boostVersion,
+      generatedWith: boostConfig.config.generatedWith,
+      architectures: boostConfig.architectures.map((architecture) => ({
+        name: architecture.name,
+        options: architecture.options
+      }))
+    } : null,
+    ...boostConfig.config ? {} : { hint: "run node-boost install" }
+  };
+}
+function detectedPackages(packages) {
+  return Object.fromEntries(
+    Object.values(packages).filter((pkg) => pkg.source !== "missing" && pkg.version).sort((a, b) => a.name.localeCompare(b.name)).map((pkg) => [pkg.name, pkg.version])
+  );
+}
+function stackVersion(packages) {
+  return packages.next?.version ?? packages.vite?.version ?? packages.react?.version ?? null;
+}
+
+// src/mcp/tools/audit.ts
+async function auditTool(rootDir) {
+  return runAudit({ rootDir, mode: "all" });
+}
+
+// src/mcp/tools/explain-finding.ts
+function explainFindingTool(rule) {
+  const finding2 = explainFinding(rule);
+  if (!finding2) {
+    return { ok: false, error: `Unknown node-boost rule "${rule}".` };
+  }
+  return { ok: true, finding: finding2 };
+}
+
+// src/mcp/tools/list-routes.ts
+import { readdir as readdir4 } from "fs/promises";
+import { join as join17, relative as relative5, sep } from "path";
+var appRouteFiles = {
+  page: "page",
+  layout: "layout",
+  route: "route-handler",
+  error: "error",
+  loading: "loading",
+  "not-found": "not-found",
+  middleware: "middleware"
+};
+var supportedExtensions = /* @__PURE__ */ new Set(["js", "jsx", "ts", "tsx", "mdx"]);
+async function listRoutesTool(rootDir) {
+  const stack = await detectStack(rootDir);
+  if (stack.name === "vite-react") {
+    return {
+      supported: false,
+      reason: "react-router route map is on the roadmap"
+    };
+  }
+  if (stack.name !== "next") {
+    return [];
+  }
+  if (stack.router === "app") {
+    return sortRoutes([
+      ...await scanAppRouter(rootDir, join17(rootDir, "app")),
+      ...await scanAppRouter(rootDir, join17(rootDir, "src", "app"))
+    ]);
+  }
+  if (stack.router === "pages") {
+    return sortRoutes([
+      ...await scanPagesRouter(rootDir, join17(rootDir, "pages")),
+      ...await scanPagesRouter(rootDir, join17(rootDir, "src", "pages"))
+    ]);
+  }
+  return [];
+}
+async function scanAppRouter(rootDir, dir) {
+  const files = await walkFiles2(dir);
+  return files.flatMap((file) => {
+    const parsed = parseRouteFile(file);
+    if (!parsed || !appRouteFiles[parsed.basename]) {
+      return [];
+    }
+    const appRelative = relative5(dir, file);
+    const routeSegments = appRelative.split(sep).slice(0, -1);
+    const slot = routeSegments.find((segment) => segment.startsWith("@"))?.slice(1);
+    const path = segmentsToPath(routeSegments);
+    return [
+      {
+        path,
+        type: appRouteFiles[parsed.basename],
+        file: normalizePath(relative5(rootDir, file)),
+        dynamic: extractDynamicSegments(routeSegments),
+        ...slot ? { slot } : {}
+      }
+    ];
+  });
+}
+async function scanPagesRouter(rootDir, dir) {
+  const files = await walkFiles2(dir);
+  return files.flatMap((file) => {
+    const parsed = parseRouteFile(file);
+    if (!parsed || parsed.basename.startsWith("_") || parsed.basename === "middleware") {
+      return [];
+    }
+    const pagesRelative = relative5(dir, file);
+    const pathWithoutExtension = pagesRelative.slice(0, -parsed.extension.length - 1);
+    const segments = pathWithoutExtension.split(sep);
+    const isApi = segments[0] === "api";
+    const routeSegments = isApi ? segments.slice(1) : segments;
+    if (routeSegments[routeSegments.length - 1] === "index") {
+      routeSegments.pop();
+    }
+    return [
+      {
+        path: isApi ? `/api${segmentsToPath(routeSegments) === "/" ? "" : segmentsToPath(routeSegments)}` : segmentsToPath(routeSegments),
+        type: isApi ? "api-route" : "page",
+        file: normalizePath(relative5(rootDir, file)),
+        dynamic: extractDynamicSegments(routeSegments)
+      }
+    ];
+  });
+}
+async function walkFiles2(dir) {
+  let entries;
+  try {
+    entries = await readdir4(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join17(dir, entry.name);
+      if (entry.isDirectory()) {
+        return walkFiles2(path);
+      }
+      return entry.isFile() ? [path] : [];
+    })
+  );
+  return files.flat();
+}
+function parseRouteFile(file) {
+  const filename = file.split(sep).at(-1) ?? "";
+  const parts = filename.split(".");
+  if (parts.length < 2) {
+    return null;
+  }
+  const extension = parts.at(-1) ?? "";
+  const basename = parts.slice(0, -1).join(".");
+  if (!supportedExtensions.has(extension)) {
+    return null;
+  }
+  return { basename, extension };
+}
+function segmentsToPath(segments) {
+  const routeSegments = segments.filter((segment) => !segment.startsWith("(") && !segment.startsWith("@"));
+  return `/${routeSegments.join("/")}`.replace(/\/+/g, "/");
+}
+function extractDynamicSegments(segments) {
+  return segments.map((segment) => segment.match(/^\[\[?\.{0,3}([^\]]+)\]?\]$/)?.[1] ?? null).filter((segment) => Boolean(segment));
+}
+function sortRoutes(routes) {
+  return routes.sort((a, b) => a.path.localeCompare(b.path) || a.type.localeCompare(b.type) || a.file.localeCompare(b.file));
+}
+function normalizePath(path) {
+  return path.split(sep).join("/");
+}
+
+// src/mcp/server.ts
+function createNodeBoostMcpServer(options = {}) {
+  const rootDir = options.rootDir ?? process.cwd();
+  const packageVersion = options.packageVersion ?? package_default.version;
+  const server = new McpServer({
+    name: "node-boost",
+    version: packageVersion
+  });
+  registerJsonTool(
+    server,
+    "application_info",
+    "Return detected Node/React project information.",
+    async () => applicationInfoTool(rootDir, packageVersion)
+  );
+  registerJsonTool(server, "list_routes", "List detected application routes.", async () => listRoutesTool(rootDir));
+  registerJsonTool(server, "doctor", "Run minimal node-boost project diagnostics.", async () => doctorTool(rootDir, packageVersion));
+  registerJsonTool(server, "audit", "Run node-boost audit on all source files.", async () => auditTool(rootDir));
+  registerJsonTool(
+    server,
+    "explain_finding",
+    'Explain a node-boost audit finding. Pass {"rule":"NB-ARCH-005"}.',
+    (args) => explainFindingTool(readRuleArg(args)),
+    { rule: z2.string() }
+  );
+  if (options.includeThrowingTestTool) {
+    registerJsonTool(server, "__throw_for_test", "Internal test-only failing tool.", () => {
+      throw new Error("forced test error");
+    });
+  }
+  return server;
+}
+async function startNodeBoostMcpServer(options = {}) {
+  const server = createNodeBoostMcpServer(options);
+  await server.connect(new StdioServerTransport());
+}
+function registerJsonTool(server, name, description, handler, inputSchema = {}) {
+  server.registerTool(
+    name,
+    {
+      title: name,
+      description,
+      inputSchema
+    },
+    async (args) => {
+      const start = performance.now();
+      try {
+        const output = await handler(args);
+        debugLog(`[node-boost:mcp] ${name} ok ${Math.round(performance.now() - start)}ms`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output) }]
+        };
+      } catch (error) {
+        const message = formatMcpError(error);
+        debugLog(`[node-boost:mcp] ${name} err ${Math.round(performance.now() - start)}ms ${message}`);
+        return {
+          content: [{ type: "text", text: message }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function readRuleArg(args) {
+  return typeof args.rule === "string" ? args.rule : "";
+}
+
+// src/cli/commands/mcp.ts
+var mcpCommand = defineCommand6({
+  meta: {
+    name: "mcp",
+    description: "Start the node-boost MCP server over stdio."
+  },
+  async run() {
+    await startNodeBoostMcpServer();
+  }
+});
+
+// src/cli/commands/update.ts
+import { defineCommand as defineCommand7 } from "citty";
+var updateCommand = defineCommand7({
+  meta: {
+    name: "update",
+    description: "Regenerate node-boost files from node-boost.json without prompts."
+  },
+  async run() {
+    const result = await runUpdate();
+    const counts = result.operations.reduce(
+      (summary, operation) => {
+        summary[operation.status] += 1;
+        return summary;
+      },
+      { created: 0, updated: 0, skipped: 0 }
+    );
+    console.log(`node-boost update: created ${counts.created}, updated ${counts.updated}, skipped ${counts.skipped}`);
+  }
+});
+
+// src/cli/index.ts
+var main = defineCommand8({
+  meta: {
+    name: "node-boost",
+    description: "CLI and MCP guidance layer for Node/React projects."
+  },
+  subCommands: {
+    audit: auditCommand,
+    doctor: doctorCommand,
+    explain: explainCommand,
+    guard: guardCommand,
+    install: installCommand,
+    mcp: mcpCommand,
+    update: updateCommand
+  }
+});
+await runMain(main);
+//# sourceMappingURL=cli.js.map