bigpowers 2.87.7 → 2.88.0

package/extensions/omp-hooks.ts

@@ -0,0 +1,406 @@
+// story: e82s03
+// extensions/omp-hooks.ts
+// bigpowers — Single OMP extension entry exposing every source skill as a
+// slash command, a bigpowers_skill LLM tool, and safety policy guards.
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { execSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+// Skills live at skills/<name>/SKILL.md — scan inside that directory, so
+// only truly foreign entries (e.g. a stray node_modules symlink) need exclusion.
+const EXCLUDED_DIRS = new Set([".git", "node_modules"]);
+
+const DANGEROUS_PATTERNS = [
+  /git\s+reset\s+--hard/,
+  /git\s+clean\s+-f/,
+  /git\s+branch\s+-D/,
+  /git\s+checkout\s+\./,
+  /git\s+restore\s+\./,
+  /push\s+--force/,
+  /push\s+-f(?:\s|$)/,
+];
+
+const CONVENTIONAL_RE =
+  /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?:\s.+/;
+
+const PROTECTED_BRANCH_RE = /(?:^|\s|[:])(?:main|master)(?:\s|$)/;
+const PROTECTED_BRANCHES = ["main", "master"] as const;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface SkillMeta {
+  name: string;
+  description: string;
+  /** Filesystem path to the skill's SKILL.md. */
+  path: string;
+  /** Full SKILL.md content (body only, frontmatter stripped). */
+  markdown: string;
+}
+
+// ---------------------------------------------------------------------------
+// YAML frontmatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Conservatively reads the `name` and `description` keys from YAML-style
+ * frontmatter delimited by `---`.  Only single-line values are handled;
+ * a multi-line YAML value silently yields the directory name as fallback.
+ */
+function parseFrontmatter(
+  content: string,
+  dirName: string,
+): { name: string; description: string } {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return { name: dirName, description: "" };
+  }
+
+  const endIdx = lines.indexOf("---", 1);
+  if (endIdx === -1) {
+    return { name: dirName, description: "" };
+  }
+
+  let name = dirName;
+  let description = "";
+
+  for (let i = 1; i < endIdx; i++) {
+    const line = lines[i];
+    const nameMatch = line.match(/^name:\s*(.+)$/);
+    if (nameMatch) {
+      name = nameMatch[1].trim();
+      continue;
+    }
+    const descMatch = line.match(/^description:\s*(.+)$/);
+    if (descMatch) {
+      description = descMatch[1].trim();
+      continue;
+    }
+  }
+
+  return { name, description };
+}
+
+/** Returns the SKILL.md body below the closing `---` frontmatter line. */
+function stripFrontmatter(content: string): string {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return content;
+  const endIdx = lines.indexOf("---", 1);
+  if (endIdx === -1) return content;
+  // Skip both `---` lines and one blank line if present.
+  let start = endIdx + 1;
+  if (lines[start]?.trim() === "") start++;
+  return lines.slice(start).join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Skill discovery
+// ---------------------------------------------------------------------------
+
+function collectSkillMd(dirPath: string): string | null {
+  const mdPath = join(dirPath, "SKILL.md");
+  try {
+    const st = statSync(mdPath);
+    if (!st.isFile()) return null;
+    return readFileSync(mdPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scans `skillsRoot` (expected: `<package-root>/skills/`) for immediate
+ * subdirectories that contain a SKILL.md file.
+ */
+function discoverSkills(skillsRoot: string): SkillMeta[] {
+  const entries = readdirSync(skillsRoot);
+  const result: SkillMeta[] = [];
+
+  for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry)) continue;
+
+    const absPath = join(skillsRoot, entry);
+    let st;
+    try {
+      st = statSync(absPath);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+
+    const content = collectSkillMd(absPath);
+    if (content === null) continue;
+
+    const { name, description } = parseFrontmatter(content, entry);
+    const markdown = stripFrontmatter(content);
+
+    result.push({ name, description, path: join(absPath, "SKILL.md"), markdown });
+  }
+
+  return result;
+}
+
+function pluginRoot(): string {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+// ---------------------------------------------------------------------------
+// Git safety helpers
+// ---------------------------------------------------------------------------
+
+function currentBranch(): string {
+  try {
+    return execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf-8",
+      timeout: 3000,
+    }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+function protectedPushTarget(command: string, branch: string): boolean {
+  if (PROTECTED_BRANCH_RE.test(command)) return true;
+  const trimmed = command.trim();
+  return (
+    branch === "main" &&
+    (trimmed === "git push" || trimmed === "git push origin")
+  );
+}
+
+function extractCommitMessage(command: string): string | null {
+  const dq = command.match(/-m\s+"([^"]+)"/);
+  if (dq) return dq[1];
+  const sq = command.match(/-m\s+'([^']+)'/);
+  return sq ? sq[1] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+function buildSkillPrompt(skill: SkillMeta, args: string): string {
+  const header = [
+    `Activate skill: ${skill.name}`,
+    `Description: ${skill.description}`,
+    "",
+    "--- SKILL.md ---",
+  ].join("\n");
+
+  const body = skill.markdown;
+
+  let footer = "";
+  if (args.trim()) {
+    footer = `\n\n--- USER ARGUMENTS ---\n${args.trim()}`;
+  }
+
+  return `${header}\n${body}${footer}`;
+}
+
+// ---------------------------------------------------------------------------
+
+async function injectSkillPrompt(
+  pi: ExtensionAPI,
+  prompt: string,
+): Promise<{ injected: boolean; via: "sendUserMessage" | "sendMessage" | "none" }> {
+  try {
+    await pi.sendUserMessage(prompt);
+    return { injected: true, via: "sendUserMessage" };
+  } catch {
+    try {
+      await pi.sendMessage(
+        {
+          customType: "bigpowers.skill",
+          content: prompt,
+          display: true,
+          attribution: "user",
+        },
+        { deliverAs: "nextTurn", triggerTurn: true },
+      );
+      return { injected: true, via: "sendMessage" };
+    } catch {
+      return { injected: false, via: "none" };
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Extension factory
+// ---------------------------------------------------------------------------
+
+export default function bigpowers(pi: ExtensionAPI) {
+  const z = pi.zod;
+
+  pi.setLabel("bigpowers");
+
+  // Discover skills from skills/ in the installed plugin package root.
+  const skills = discoverSkills(join(pluginRoot(), "skills"));
+
+  // ----- Slash commands --------------------------------------------------
+
+  for (const skill of skills) {
+    pi.registerCommand(skill.name, {
+      description: skill.description,
+      handler: async (args, _ctx) => {
+        const prompt = buildSkillPrompt(skill, args);
+        await injectSkillPrompt(pi, prompt);
+      },
+    });
+  }
+
+  // ----- bigpowers_skill tool --------------------------------------------
+
+  pi.registerTool({
+    name: "bigpowers_skill",
+    label: "Bigpowers Skill",
+    description:
+      "Interact with bigpowers source skills. Use 'list' to enumerate available skills, 'get' to retrieve a skill's full markdown, and 'run' to activate a skill with arguments.",
+    parameters: z.object({
+      action: z
+        .enum(["list", "get", "run"])
+        .describe("Operation: list all skills, get one skill, or run a skill with arguments"),
+      skill: z
+        .string()
+        .optional()
+        .describe("Skill name — required for 'get' and 'run' actions"),
+      args: z
+        .string()
+        .optional()
+        .describe("User arguments passed to the skill — only used with 'run'"),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const { action, skill: skillName, args } = params;
+
+      switch (action) {
+        case "list": {
+          const listing = skills.map((s) => ({
+            name: s.name,
+            description: s.description,
+          }));
+          return {
+            content: [{ type: "text", text: JSON.stringify(listing, null, 2) }],
+            details: { skills: listing },
+          };
+        }
+
+        case "get": {
+          if (!skillName) {
+            return {
+              content: [{ type: "text", text: "Error: 'skill' parameter is required for 'get' action." }],
+              details: { error: "missing_skill_param" },
+            };
+          }
+          const found = skills.find((s) => s.name === skillName);
+          if (!found) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Error: skill '${skillName}' not found. Use 'list' to see available skills.`,
+                },
+              ],
+              details: { error: "skill_not_found", skill: skillName },
+            };
+          }
+          return {
+            content: [
+              { type: "text", text: `# ${found.name}\n\n${found.description}\n\n---\n\n${found.markdown}` },
+            ],
+            details: { name: found.name, description: found.description },
+          };
+        }
+
+        case "run": {
+          if (!skillName) {
+            return {
+              content: [{ type: "text", text: "Error: 'skill' parameter is required for 'run' action." }],
+              details: { error: "missing_skill_param" },
+            };
+          }
+          const found = skills.find((s) => s.name === skillName);
+          if (!found) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Error: skill '${skillName}' not found. Use 'list' to see available skills.`,
+                },
+              ],
+              details: { error: "skill_not_found", skill: skillName },
+            };
+          }
+          const prompt = buildSkillPrompt(found, args ?? "");
+          const { injected, via } = await injectSkillPrompt(pi, prompt);
+          return {
+            content: [{ type: "text", text: prompt }],
+            details: { skill: found.name, injected, via },
+          };
+        }
+      }
+    },
+  });
+
+  // ----- Event handlers --------------------------------------------------
+
+  pi.on("session_start", async (_event, ctx) => {
+    const count = skills.length;
+    ctx.ui.notify(`bigpowers: ${count} skills loaded`, "info");
+  });
+
+  pi.on("tool_call", (event) => {
+    if (event.toolName !== "bash") return;
+    const { command } = event.input as { command?: string };
+    if (!command) return;
+
+    for (const pat of DANGEROUS_PATTERNS) {
+      if (pat.test(command)) {
+        return {
+          block: true,
+          reason: `BLOCKED: '${command}' matches dangerous pattern '${pat}'.`,
+        };
+      }
+    }
+
+    const branch = currentBranch();
+
+    if (/git\s+push/.test(command) && protectedPushTarget(command, branch)) {
+      return {
+        block: true,
+        reason:
+          "BLOCKED: Direct push to protected branch. Use kickoff-branch + release-branch.",
+      };
+    }
+
+    if (/git\s+commit/.test(command)) {
+      if ((PROTECTED_BRANCHES as readonly string[]).includes(branch)) {
+        return {
+          block: true,
+          reason: `BLOCKED: Direct commits to '${branch}' are forbidden. Use a feature branch.`,
+        };
+      }
+      const msg = extractCommitMessage(command);
+      if (msg) {
+        if (!CONVENTIONAL_RE.test(msg)) {
+          return {
+            block: true,
+            reason:
+              "BLOCKED: Commit message must follow Conventional Commits: <type>(<scope>): <subject>.",
+          };
+        }
+        if (msg.split("\n")[0].length > 72) {
+          return {
+            block: true,
+            reason: "BLOCKED: Commit subject line must be ≤72 characters.",
+          };
+        }
+      }
+    }
+  });
+}

package/hooks/pre/bash.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# story: e82s03
+# bigpowers — pre-tool-use hook for OMP bash tool
+# Shell fallback for runtimes that invoke hooks as processes rather than
+# calling the TypeScript extension directly. Blocks dangerous git commands
+# and enforces Conventional Commits. Primary implementation lives in
+# extensions/omp-hooks.ts (ExtensionAPI tool_call handler).
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.command // .tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+DANGEROUS_PATTERNS=(
+  "git reset --hard"
+  "git clean -f"
+  "git branch -D"
+  "push --force"
+  "push -f"
+)
+PROTECTED_BRANCHES=("main" "master")
+CONVENTIONAL_RE='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?:[[:space:]].+'
+
+for p in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qE "$p"; then
+    printf '{"decision":"block","reason":"BLOCKED: dangerous pattern %q"}\n' "$p"
+    exit 0
+  fi
+done
+
+if [[ "$COMMAND" =~ git[[:space:]]+commit ]]; then
+  MSG=""
+  if [[ "$COMMAND" =~ -m[[:space:]]+"([^"]+)" ]]; then MSG="${BASH_REMATCH[1]}"; fi
+  if [ -n "$MSG" ] && [[ ! "$MSG" =~ $CONVENTIONAL_RE ]]; then
+    echo '{"decision":"block","reason":"BLOCKED: Conventional Commits required"}'
+    exit 0
+  fi
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+  for b in "${PROTECTED_BRANCHES[@]}"; do
+    if [[ "$BRANCH" == "$b" ]]; then
+      printf '{"decision":"block","reason":"BLOCKED: direct commit to %q"}\n' "$b"
+      exit 0
+    fi
+  done
+fi
+
+exit 0

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "bigpowers",
-  "version": "2.87.7",
+  "version": "2.88.0",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
+  "omp": {
+    "extensions": [
+      "extensions/omp-hooks.ts"
+    ]
+  },
   "scripts": {
     "setup": "node bin/setup.js",
     "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh && python3 scripts/check-skill-links.py",

package/scripts/lib/golden-suite-gates.sh

@@ -64,6 +64,8 @@ GOLDEN_GATES=(
   "epics-wiki-zero-stories:bash scripts/test-generate-epics-wiki-zero-stories.sh:false"
   "golden-g11-worktree-venv:bash scripts/test-golden-g11-worktree-venv.sh:false"
   "install-helpers:bash scripts/test-install-helpers.sh:false"
+  "project-runtime:bash scripts/test-project-runtime.sh:false"
+  "omp-extension:bash scripts/validate-omp-extension.sh:false"
   "import-boundaries:bash scripts/check-import-boundaries.sh:false"
   "skill-catalog:bash scripts/validate-skill-catalog.sh:false"
   "specs-parse:bash scripts/validate-specs-yaml.sh:false"

package/scripts/lib/install-helpers.js

@@ -36,7 +36,11 @@ function assertReplaceable(dst) {
   }
   if (st.isSymbolicLink()) {
     const target = fs.readlinkSync(dst);
-    if (target.startsWith(REPO_ROOT)) return; // managed by bigpowers — safe to re-link
+    // Path-separator boundary: a string-prefix sibling of the package root
+    // (e.g. <ROOT>-evil) is NOT managed by this package.
+    if (target === REPO_ROOT || target.startsWith(REPO_ROOT + path.sep)) {
+      return; // managed by bigpowers — safe to re-link
+    }
   }
   throw new Error(
     `Refusing to replace ${dst}: it exists and is not a bigpowers-managed symlink. ` +
@@ -416,6 +420,52 @@ function installLocal(tool, repoRoot) {
   }
 }
 
+// ── Project provisioning (bigpowers init) ────────────────────────────────────
+
+// Provision the CURRENT project (cwd) with the package's scripts/ tree and the
+// specs/ scaffolding skill bodies assume. Package installs (pi, npm -g, npx)
+// register skills but pi's package contract has no resource type for project
+// files and no lifecycle script runs — so `bash scripts/*.sh` invocations and
+// `→ verify:` gates in SKILL.md files fail outside a bigpowers checkout. (#116)
+function initProject(repoRoot) {
+  const cwd = process.cwd();
+  if (path.resolve(cwd) === path.resolve(repoRoot)) {
+    return { skipped: 'cwd-is-package' };
+  }
+  linkDir(path.join(repoRoot, 'scripts'), path.join(cwd, 'scripts'));
+  const created = [];
+  for (const rel of [path.join('specs', 'bugs'), path.join('specs', 'verifications')]) {
+    const dir = path.join(cwd, rel);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      created.push(rel);
+    }
+  }
+  return { skipped: null, scriptsLinked: true, created };
+}
+
+// Inverse of initProject: remove ONLY the managed scripts symlink and specs/
+// scaffolding dirs we created (and only while untouched — user content survives).
+function initProjectRemove(repoRoot) {
+  const cwd = process.cwd();
+  const scriptsLink = path.join(cwd, 'scripts');
+  try {
+    if (fs.lstatSync(scriptsLink).isSymbolicLink()
+      && fs.readlinkSync(scriptsLink) === path.join(repoRoot, 'scripts')) {
+      fs.unlinkSync(scriptsLink);
+    }
+  } catch {}
+  for (const rel of [path.join('specs', 'bugs'), path.join('specs', 'verifications'), 'specs']) {
+    const dir = path.join(cwd, rel);
+    try {
+      if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()
+        && fs.readdirSync(dir).length === 0) {
+        fs.rmdirSync(dir);
+      }
+    } catch {}
+  }
+}
+
 // ── Uninstall per tool ───────────────────────────────────────────────────────
 
 function uninstallTool(toolId, repoRoot) {
@@ -694,6 +744,8 @@ module.exports = {
   linkHook,
   installGlobal,
   installLocal,
+  initProject,
+  initProjectRemove,
   uninstallTool,
   removeSymlink,
   detectExistingInstall,

package/scripts/lib/project-runtime.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# story: e82s01
+# Resolve consumer-project runtime settings without external YAML dependencies.
+
+if [[ -n "${BIGPOWERS_PROJECT_RUNTIME_LOADED:-}" ]]; then
+  return 0
+fi
+BIGPOWERS_PROJECT_RUNTIME_LOADED=1
+
+_bp_config_value() {
+  local project_root="$1" key="$2"
+  local config_file="$project_root/.bigpowers/config.yaml"
+  [[ -f "$config_file" ]] || return 1
+
+  awk -v key="$key" '
+    /^[[:space:]]*#/ { next }
+    {
+      separator = index($0, ":")
+      if (!separator) next
+      candidate = substr($0, 1, separator - 1)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", candidate)
+      if (candidate != key) next
+      value = substr($0, separator + 1)
+      sub(/[[:space:]]+#.*$/, "", value)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+      if ((substr(value, 1, 1) == "\"" && substr(value, length(value), 1) == "\"") ||
+          (substr(value, 1, 1) == "\047" && substr(value, length(value), 1) == "\047")) {
+        value = substr(value, 2, length(value) - 2)
+      }
+      print value
+      found = 1
+      exit
+    }
+    END { if (!found) exit 1 }
+  ' "$config_file"
+}
+
+_bp_specs_dir_value() {
+  local project_root="$1"
+  if [[ -n "${BIGPOWERS_SPECS_DIR+x}" ]]; then
+    printf '%s\n' "$BIGPOWERS_SPECS_DIR"
+  elif _bp_config_value "$project_root" specs_dir; then
+    return 0
+  else
+    printf '%s\n' specs
+  fi
+}
+
+bp_specs_dir() {
+  local project_root="${1:-$PWD}"
+  local specs_dir
+  specs_dir="$(_bp_specs_dir_value "$project_root")"
+  if [[ -z "$specs_dir" ]]; then
+    echo "bigpowers config: specs_dir must not be empty; set it to specs, .specs, or another directory" >&2
+    return 2
+  fi
+  printf '%s\n' "$specs_dir"
+}
+
+bp_specs_path() {
+  local project_root="${1:-$PWD}" relative_path="${2:-}"
+  local specs_dir
+  specs_dir="$(bp_specs_dir "$project_root")" || return
+
+  if [[ "$specs_dir" == /* ]]; then
+    if [[ -n "$relative_path" ]]; then
+      printf '%s/%s\n' "${specs_dir%/}" "${relative_path#/}"
+    else
+      printf '%s\n' "${specs_dir%/}"
+    fi
+  elif [[ -n "$relative_path" ]]; then
+    printf '%s/%s/%s\n' "${project_root%/}" "${specs_dir%/}" "${relative_path#/}"
+  else
+    printf '%s/%s\n' "${project_root%/}" "${specs_dir%/}"
+  fi
+}
+
+_bp_vcs_value() {
+  local project_root="$1"
+  if [[ -n "${BIGPOWERS_VCS+x}" ]]; then
+    printf '%s\n' "$BIGPOWERS_VCS"
+  elif _bp_config_value "$project_root" vcs; then
+    return 0
+  else
+    printf '%s\n' auto
+  fi
+}
+
+bp_vcs_kind() {
+  local project_root="${1:-$PWD}"
+  local configured_vcs
+  configured_vcs="$(_bp_vcs_value "$project_root")"
+
+  case "$configured_vcs" in
+    git|jj) printf '%s\n' "$configured_vcs" ;;
+    auto)
+      if [[ -d "$project_root/.jj" ]]; then
+        printf '%s\n' jj
+      elif [[ -e "$project_root/.git" ]]; then
+        printf '%s\n' git
+      else
+        printf '%s\n' none
+      fi
+      ;;
+    *)
+      echo "bigpowers config: invalid vcs '$configured_vcs'. Expected one of: auto, git, jj" >&2
+      return 2
+      ;;
+  esac
+}