bigpowers 2.60.0 → 2.61.1

package/bigpowers-mcp/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "bigpowers-mcp",
+  "version": "0.1.0",
+  "description": "MCP semantic context server for bigpowers skills catalog",
+  "type": "module",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.1.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/bigpowers-mcp/src/config.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Repo root: cwd when launched from workspace, else parent of bigpowers-mcp. */
+export function getRepoRoot(): string {
+  const fromEnv = process.env.BIGPOWERS_ROOT;
+  if (fromEnv) return path.resolve(fromEnv);
+
+  const cwd = process.cwd();
+  if (isRepoRoot(cwd)) return cwd;
+
+  const parentOfPackage = path.resolve(packageDir, "../..");
+  if (isRepoRoot(parentOfPackage)) return parentOfPackage;
+
+  return cwd;
+}
+
+function isRepoRoot(dir: string): boolean {
+  return (
+    fs.existsSync(path.join(dir, "skills")) && fs.existsSync(path.join(dir, "specs"))
+  );
+}
+
+export function getSkillsDir(repoRoot: string): string {
+  return path.join(repoRoot, "skills");
+}
+
+export function getGraphPath(repoRoot: string): string {
+  return path.join(repoRoot, "bigpowers-mcp", "graph.jsonl");
+}
+
+export const MAX_READ_SKILL_BYTES = 512 * 1024;
+
+export const SECRET_DENYLIST = [
+  /\.env/i,
+  /\.pem$/i,
+  /secret/i,
+  /credentials/i,
+];
+
+export const GIT_SCOPE_DIRS = ["skills", "specs"];

package/bigpowers-mcp/src/index.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createContext, registerTools } from "./tools/index.js";
+
+async function main(): Promise<void> {
+  const ctx = createContext();
+  const server = new McpServer({
+    name: "bigpowers-mcp",
+    version: "0.1.0",
+  });
+
+  registerTools(server, ctx);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("bigpowers-mcp started");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/bigpowers-mcp/src/lib/git-context.ts

@@ -0,0 +1,99 @@
+// story: e32s04
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { GIT_SCOPE_DIRS, SECRET_DENYLIST } from "../config.js";
+import { isSecretPath } from "./paths.js";
+
+export interface GitContextResult {
+  action: string;
+  changed_files: Record<string, string[]>;
+  commits?: Array<{ hash: string; subject: string; files: string[] }>;
+  diffs?: Record<string, string>;
+}
+
+function inScope(filePath: string): boolean {
+  const norm = filePath.replace(/\\/g, "/");
+  if (isSecretPath(norm)) return false;
+  return GIT_SCOPE_DIRS.some((d) => norm === d || norm.startsWith(`${d}/`));
+}
+
+function groupByDir(files: string[]): Record<string, string[]> {
+  const grouped: Record<string, string[]> = {};
+  for (const f of files) {
+    const parts = f.split("/");
+    const dir = parts.length > 1 ? parts[0] : ".";
+    if (!grouped[dir]) grouped[dir] = [];
+    grouped[dir].push(f);
+  }
+  return grouped;
+}
+
+function git(repoRoot: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+  }).trim();
+}
+
+export function getGitContext(repoRoot: string, action: "status" | "log" | "diff"): GitContextResult {
+  if (action === "status") {
+    const out = git(repoRoot, ["status", "--porcelain"]);
+    const files = out
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim())
+      .filter(inScope);
+    return { action, changed_files: groupByDir(files) };
+  }
+
+  if (action === "log") {
+    const out = git(repoRoot, [
+      "log",
+      "-10",
+      "--pretty=format:%H|%s",
+      "--name-only",
+      "--",
+      ...GIT_SCOPE_DIRS,
+    ]);
+    const commits: GitContextResult["commits"] = [];
+    let current: { hash: string; subject: string; files: string[] } | null = null;
+    for (const line of out.split("\n")) {
+      if (line.includes("|")) {
+        if (current) commits.push(current);
+        const [hash, subject] = line.split("|");
+        current = { hash, subject, files: [] };
+      } else if (line.trim() && current && inScope(line.trim())) {
+        current.files.push(line.trim());
+      }
+    }
+    if (current) commits.push(current);
+    return { action, changed_files: {}, commits };
+  }
+
+  const diffOut = git(repoRoot, ["diff", "--", ...GIT_SCOPE_DIRS]);
+  const diffs: Record<string, string> = {};
+  let currentFile = "";
+  let buf: string[] = [];
+  for (const line of diffOut.split("\n")) {
+    if (line.startsWith("diff --git")) {
+      if (currentFile && buf.length) diffs[currentFile] = buf.join("\n");
+      const match = / b\/(.+)$/.exec(line);
+      currentFile = match?.[1] ?? "";
+      buf = [line];
+    } else {
+      buf.push(line);
+    }
+  }
+  if (currentFile && buf.length && inScope(currentFile) && !isSecretPath(currentFile)) {
+    diffs[currentFile] = buf.join("\n");
+  }
+
+  const changed = Object.keys(diffs);
+  return { action, changed_files: groupByDir(changed), diffs };
+}
+
+export function isGitRepo(repoRoot: string): boolean {
+  return fs.existsSync(path.join(repoRoot, ".git"));
+}

package/bigpowers-mcp/src/lib/graph/builder.ts

@@ -0,0 +1,95 @@
+import type { ParsedSkill } from "../skill-parser.js";
+import type { GraphEntity, GraphRelation, SkillGraph } from "./types.js";
+
+const HANDOFF_AFTER = /run\s+(\S+)\s+after\s+(\S+)/gi;
+const HARD_GATE = /HARD GATE:\s*(.+)/i;
+const SKILL_REF = /see\s+skills\/(\S+)\/SKILL\.md/gi;
+const CONVENTIONS_REF = /CONVENTIONS\.md(?:\s*[§#]\s*(\S+))?/gi;
+
+export function buildGraphFromSkills(parsedSkills: ParsedSkill[]): SkillGraph {
+  const graph: SkillGraph = { entities: new Map(), relations: [] };
+
+  for (const skill of parsedSkills) {
+    const fm = skill.frontmatter;
+    const observations: string[] = [];
+    if (fm.model) observations.push(`model: ${String(fm.model)}`);
+    if (fm.effort) observations.push(`effort: ${String(fm.effort)}`);
+    if (fm.description) observations.push(`description: ${String(fm.description)}`);
+
+    const entity: GraphEntity = {
+      type: "entity",
+      name: skill.name,
+      entityType: "Skill",
+      observations,
+    };
+    graph.entities.set(skill.name, entity);
+
+    const prose = skill.rawProse + "\n" + skill.sections.map((s) => s.prose).join("\n");
+
+    let m: RegExpExecArray | null;
+    HANDOFF_AFTER.lastIndex = 0;
+    while ((m = HANDOFF_AFTER.exec(prose)) !== null) {
+      graph.relations.push({
+        type: "relation",
+        from: m[1],
+        to: m[2],
+        relationType: "depends_on",
+      });
+    }
+
+    const gateMatch = HARD_GATE.exec(prose);
+    if (gateMatch) {
+      const gateText = gateMatch[1].trim();
+      const targetMatch = /(\S+-?\S+)/.exec(gateText);
+      if (targetMatch) {
+        graph.relations.push({
+          type: "relation",
+          from: skill.name,
+          to: targetMatch[1].replace(/[`'"]/g, ""),
+          relationType: "gates",
+        });
+      }
+    }
+
+    SKILL_REF.lastIndex = 0;
+    while ((m = SKILL_REF.exec(prose)) !== null) {
+      graph.relations.push({
+        type: "relation",
+        from: skill.name,
+        to: m[1],
+        relationType: "references",
+      });
+    }
+
+    CONVENTIONS_REF.lastIndex = 0;
+    while ((m = CONVENTIONS_REF.exec(prose)) !== null) {
+      graph.relations.push({
+        type: "relation",
+        from: skill.name,
+        to: m[1] ? `CONVENTIONS.md §${m[1]}` : "CONVENTIONS.md",
+        relationType: "enforces",
+      });
+    }
+
+    const desc = String(fm.description ?? "");
+    const handoffMatch = /handoff.*?(\S+-?\S+)/i.exec(desc);
+    if (handoffMatch) {
+      graph.relations.push({
+        type: "relation",
+        from: skill.name,
+        to: handoffMatch[1],
+        relationType: "handoff_to",
+      });
+    }
+  }
+
+  return graph;
+}
+
+export function mergeGraphs(base: SkillGraph, incoming: SkillGraph): SkillGraph {
+  for (const [name, entity] of incoming.entities) {
+    base.entities.set(name, entity);
+  }
+  base.relations.push(...incoming.relations);
+  return base;
+}

package/bigpowers-mcp/src/lib/graph/store.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { GraphEntity, GraphLine, GraphRelation, SkillGraph } from "./types.js";
+
+export function emptyGraph(): SkillGraph {
+  return { entities: new Map(), relations: [] };
+}
+
+export function loadGraph(graphPath: string): SkillGraph {
+  const graph = emptyGraph();
+  if (!fs.existsSync(graphPath)) return graph;
+
+  const lines = fs.readFileSync(graphPath, "utf8").split("\n").filter(Boolean);
+  for (const line of lines) {
+    const parsed = JSON.parse(line) as GraphLine;
+    if (parsed.type === "entity") {
+      graph.entities.set(parsed.name, parsed);
+    } else if (parsed.type === "relation") {
+      graph.relations.push(parsed);
+    }
+  }
+  return graph;
+}
+
+export function saveGraph(graphPath: string, graph: SkillGraph): void {
+  fs.mkdirSync(path.dirname(graphPath), { recursive: true });
+  const lines: string[] = [];
+  for (const entity of graph.entities.values()) {
+    lines.push(JSON.stringify(entity));
+  }
+  for (const rel of graph.relations) {
+    lines.push(JSON.stringify(rel));
+  }
+  fs.writeFileSync(graphPath, lines.join("\n") + (lines.length ? "\n" : ""));
+}
+
+export function searchNodes(graph: SkillGraph, query: string): GraphEntity[] {
+  const q = query.toLowerCase();
+  return [...graph.entities.values()].filter((e) => {
+    const hay = [e.name, e.entityType, ...e.observations].join(" ").toLowerCase();
+    return hay.includes(q);
+  });
+}
+
+export function openNodes(graph: SkillGraph, names: string[]): GraphEntity[] {
+  return names
+    .map((n) => graph.entities.get(n))
+    .filter((e): e is GraphEntity => e !== undefined);
+}
+
+export function getRelationsFor(graph: SkillGraph, skillName: string): GraphRelation[] {
+  return graph.relations.filter((r) => r.from === skillName || r.to === skillName);
+}
+
+export function getForwardDeps(graph: SkillGraph, skillName: string): string[] {
+  return graph.relations
+    .filter((r) => r.from === skillName && r.relationType === "depends_on")
+    .map((r) => r.to);
+}
+
+export function getReverseDeps(graph: SkillGraph, skillName: string): string[] {
+  return graph.relations
+    .filter((r) => r.to === skillName && r.relationType === "depends_on")
+    .map((r) => r.from);
+}
+
+export function getHandoffChain(graph: SkillGraph, skillName: string): string[] {
+  const chain: string[] = [skillName];
+  let current = skillName;
+  const seen = new Set<string>([skillName]);
+  for (let i = 0; i < 20; i++) {
+    const next = graph.relations.find(
+      (r) => r.from === current && r.relationType === "handoff_to",
+    );
+    if (!next || seen.has(next.to)) break;
+    chain.push(next.to);
+    seen.add(next.to);
+    current = next.to;
+  }
+  return chain;
+}
+
+export function getConventions(graph: SkillGraph, skillName: string): string[] {
+  return graph.relations
+    .filter((r) => r.from === skillName && r.relationType === "enforces")
+    .map((r) => r.to);
+}

package/bigpowers-mcp/src/lib/graph/types.ts

@@ -0,0 +1,28 @@
+export interface GraphEntity {
+  type: "entity";
+  name: string;
+  entityType: string;
+  observations: string[];
+}
+
+export interface GraphRelation {
+  type: "relation";
+  from: string;
+  to: string;
+  relationType: string;
+}
+
+export type GraphLine = GraphEntity | GraphRelation;
+
+export interface SkillGraph {
+  entities: Map<string, GraphEntity>;
+  relations: GraphRelation[];
+}
+
+export interface DependencyReport {
+  skill: string;
+  depends_on: string[];
+  depended_by: string[];
+  handoff_chain: string[];
+  conventions: string[];
+}

package/bigpowers-mcp/src/lib/paths.ts

@@ -0,0 +1,47 @@
+import path from "node:path";
+
+export class PathGuardError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PathGuardError";
+  }
+}
+
+/** Resolve userPath strictly within allowedRoot; reject traversal. */
+export function resolveWithin(allowedRoot: string, userPath: string): string {
+  const normalized = userPath.replace(/\\/g, "/").trim();
+  if (!normalized || normalized.startsWith("/") || normalized.includes("..")) {
+    throw new PathGuardError(`Invalid path: ${userPath}`);
+  }
+
+  const resolved = path.resolve(allowedRoot, normalized);
+  const rootWithSep = allowedRoot.endsWith(path.sep)
+    ? allowedRoot
+    : allowedRoot + path.sep;
+
+  if (!resolved.startsWith(rootWithSep) && resolved !== allowedRoot) {
+    throw new PathGuardError(`Path escapes allowed root: ${userPath}`);
+  }
+  return resolved;
+}
+
+/** Resolve a skill name to skills/<name>/SKILL.md under repo root. */
+export function resolveSkillPath(repoRoot: string, skillName: string): string {
+  const name = skillName.trim();
+  if (!name || name.includes("/") || name.includes("\\") || name.includes("..")) {
+    throw new PathGuardError(`Invalid skill name: ${skillName}`);
+  }
+  const skillsDir = path.join(repoRoot, "skills");
+  const skillDir = resolveWithin(skillsDir, name);
+  return path.join(skillDir, "SKILL.md");
+}
+
+export function isSecretPath(filePath: string): boolean {
+  const base = path.basename(filePath);
+  return (
+    base.startsWith(".env") ||
+    /\.pem$/i.test(base) ||
+    /secret/i.test(base) ||
+    /credentials/i.test(base)
+  );
+}

package/bigpowers-mcp/src/lib/phase-map.ts

@@ -0,0 +1,77 @@
+/** Lifecycle phase map — mirrors scripts/mcp-server.js PHASE_MAP. */
+export const PHASE_MAP: Record<string, string> = {
+  "survey-context": "Discover",
+  "research-first": "Discover",
+  "search-skills": "Discover",
+  "using-bigpowers": "Discover",
+  "map-codebase": "Discover",
+  "elaborate-spec": "Discover",
+  "model-domain": "Design",
+  "define-language": "Design",
+  "grill-me": "Design",
+  "grill-with-docs": "Design",
+  "deepen-architecture": "Design",
+  "design-interface": "Design",
+  "define-success": "Design",
+  "scope-work": "Plan",
+  "slice-tasks": "Plan",
+  "plan-work": "Plan",
+  "plan-release": "Plan",
+  "plan-refactor": "Plan",
+  "assess-impact": "Plan",
+  "change-request": "Plan",
+  "run-planning": "Plan",
+  "seed-conventions": "Plan",
+  "develop-tdd": "Build",
+  "kickoff-branch": "Build",
+  "execute-plan": "Build",
+  "build-epic": "Build",
+  "spike-prototype": "Build",
+  "craft-skill": "Build",
+  "quick-fix": "Build",
+  "setup-environment": "Build",
+  "wire-observability": "Build",
+  "wire-ci": "Build",
+  "publish-package": "Build",
+  "align-grid": "Build",
+  "orchestrate-project": "Build",
+  "guard-git": "Build",
+  "hook-commits": "Build",
+  "deploy": "Build",
+  "smoke-test": "Build",
+  "validate-contracts": "Build",
+  "verify-work": "Verify",
+  "validate-fix": "Verify",
+  "audit-code": "Verify",
+  "enforce-first": "Verify",
+  "run-evals": "Verify",
+  "investigate-bug": "Verify",
+  "diagnose-root": "Verify",
+  "fix-bug": "Verify",
+  "inspect-quality": "Verify",
+  "request-review": "Verify",
+  "respond-review": "Verify",
+  "trace-requirement": "Verify",
+  "release-branch": "Release",
+  "commit-message": "Release",
+  "session-state": "Sustain",
+  "terse-mode": "Sustain",
+  "compose-workflow": "Sustain",
+  "delegate-task": "Sustain",
+  "dispatch-agents": "Sustain",
+  "edit-document": "Sustain",
+  "evolve-skill": "Sustain",
+  "migrate-spec": "Sustain",
+  "organize-workspace": "Sustain",
+  "reset-baseline": "Sustain",
+  "simulate-agents": "Sustain",
+  "stocktake-skills": "Sustain",
+  "write-document": "Sustain",
+  "plan-tests": "Plan",
+  "gate-trace": "Verify",
+  "security-review": "Verify",
+};
+
+export function phaseForSkill(name: string): string {
+  return PHASE_MAP[name] ?? "Other";
+}