@poltergeist-ai/cli 0.1.5 → 0.1.9

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { appendFileSync, existsSync, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
 import path4 from "path";
 import { execFileSync as execFileSync2 } from "child_process";
 import { parseArgs } from "util";
@@ -742,31 +742,115 @@ function sampleMatching(comments, patterns, max) {
   }
   return matches;
 }
-function extractThemes(comments) {
+function extractThemes(comments, commentSeverities) {
   if (comments.length === 0) return [];
   const themes = [];
+  const severities = commentSeverities ?? [];
   for (const def of THEME_DEFS) {
     const matchingComments = [];
-    for (const comment of comments) {
+    const matchingSeverities = [];
+    let totalLength = 0;
+    for (let i = 0; i < comments.length; i++) {
+      const comment = comments[i];
       const lower = comment.toLowerCase();
       if (def.patterns.some((p) => p.test(lower))) {
         matchingComments.push(comment);
+        totalLength += comment.length;
+        if (i < severities.length) {
+          matchingSeverities.push(severities[i]);
+        }
       }
     }
     if (matchingComments.length < 2) continue;
     const ratio = Math.round(matchingComments.length / comments.length * 100) / 100;
     const snippets = matchingComments.filter((c) => c.length > 20 && c.length < 300).slice(0, 3).map((c) => c.length > 150 ? c.slice(0, 150) + "..." : c);
+    const severityBreakdown = {};
+    for (const sev of matchingSeverities) {
+      severityBreakdown[sev] = (severityBreakdown[sev] ?? 0) + 1;
+    }
     themes.push({
       theme: def.theme,
       label: def.label,
       count: matchingComments.length,
       ratio,
-      exampleSnippets: snippets
+      exampleSnippets: snippets,
+      severityBreakdown: matchingSeverities.length > 0 ? severityBreakdown : void 0,
+      avgCommentLength: Math.round(totalLength / matchingComments.length)
     });
   }
   themes.sort((a, b) => b.count - a.count);
   return themes;
 }
+var HIGH_SEVERITY = /* @__PURE__ */ new Set(["blocking", "major"]);
+var MED_SEVERITY = /* @__PURE__ */ new Set(["suggestion", "question", "thought"]);
+var LOW_SEVERITY = /* @__PURE__ */ new Set(["nit", "minor"]);
+function dominantSeverity(breakdown) {
+  if (!breakdown) return "unknown";
+  let bestCategory = "unknown";
+  let bestCount = 0;
+  let highCount = 0;
+  let medCount = 0;
+  let lowCount = 0;
+  for (const [sev, count] of Object.entries(breakdown)) {
+    if (HIGH_SEVERITY.has(sev)) highCount += count;
+    else if (MED_SEVERITY.has(sev)) medCount += count;
+    else if (LOW_SEVERITY.has(sev)) lowCount += count;
+  }
+  if (highCount > bestCount) {
+    bestCategory = "blocking";
+    bestCount = highCount;
+  }
+  if (medCount > bestCount) {
+    bestCategory = "suggestion";
+    bestCount = medCount;
+  }
+  if (lowCount > bestCount) {
+    bestCategory = "nit";
+    bestCount = lowCount;
+  }
+  return bestCategory;
+}
+function computeWeightedDimensions(themes) {
+  if (themes.length === 0) return [];
+  const maxRatio = Math.max(...themes.map((t) => t.ratio));
+  const maxAvgLen = Math.max(
+    ...themes.map((t) => t.avgCommentLength ?? 0),
+    1
+  );
+  return themes.map((theme) => {
+    const frequencyScore = maxRatio > 0 ? theme.ratio / maxRatio : 0;
+    let severityScore = 0.5;
+    if (theme.severityBreakdown) {
+      const total = Object.values(theme.severityBreakdown).reduce(
+        (a, b) => a + b,
+        0
+      );
+      if (total > 0) {
+        let highCount = 0;
+        for (const [sev, count] of Object.entries(theme.severityBreakdown)) {
+          if (HIGH_SEVERITY.has(sev)) highCount += count;
+        }
+        severityScore = highCount / total;
+      }
+    }
+    const avgLen = theme.avgCommentLength ?? 0;
+    const specificityScore = maxAvgLen > 0 ? avgLen / maxAvgLen : 0;
+    const rawWeight = frequencyScore * 0.5 + severityScore * 0.3 + specificityScore * 0.2;
+    const weight = Math.round(Math.min(1, Math.max(0, rawWeight)) * 100) / 100;
+    let confidence;
+    if (theme.count >= 20) confidence = "high";
+    else if (theme.count >= 10) confidence = "moderate";
+    else confidence = "low";
+    return {
+      dimension: theme.theme,
+      label: theme.label,
+      weight,
+      confidence,
+      commentCount: theme.count,
+      defaultSeverity: dominantSeverity(theme.severityBreakdown)
+    };
+  });
+}
 function buildToneProfile(comments) {
   if (comments.length < 5) return void 0;
   const n = comments.length;
@@ -810,10 +894,13 @@ function summariseReview(signals) {
       indices.filter((i) => i >= 0 && i < n).map((i) => sorted[i])
     )
   ];
-  obs.reviewThemes = extractThemes(comments);
+  obs.reviewThemes = extractThemes(comments, signals.commentSeverities);
   obs.toneProfile = buildToneProfile(comments);
   obs.recurringQuestions = extractRecurringQuestions(comments);
   obs.recurringPhrases = extractRecurringPhrases(comments);
+  if (obs.reviewThemes.length > 0) {
+    obs.weightedDimensions = computeWeightedDimensions(obs.reviewThemes);
+  }
   return obs;
 }
 
@@ -823,6 +910,7 @@ function extractGitLabSignals(exportPath, contributor, verbose) {
     reviewComments: [],
     commentLengths: [],
     severityPrefixes: {},
+    commentSeverities: [],
     questionComments: 0,
     totalComments: 0,
     source: "gitlab"
@@ -860,7 +948,11 @@ function extractGitLabSignals(exportPath, contributor, verbose) {
     signals.totalComments += 1;
     const prefixMatch = body.match(prefixRe);
     if (prefixMatch) {
-      increment(signals.severityPrefixes, prefixMatch[1].toLowerCase());
+      const severity = prefixMatch[1].toLowerCase();
+      increment(signals.severityPrefixes, severity);
+      signals.commentSeverities.push(severity);
+    } else {
+      signals.commentSeverities.push("none");
     }
     if (body.endsWith("?") || body.toLowerCase().startsWith("do we") || body.toLowerCase().startsWith("should we")) {
       signals.questionComments += 1;
@@ -953,6 +1045,7 @@ async function extractGitHubSignals(owner, repo, contributor, token, verbose) {
     reviewComments: [],
     commentLengths: [],
     severityPrefixes: {},
+    commentSeverities: [],
     questionComments: 0,
     totalComments: 0,
     source: "github"
@@ -996,7 +1089,11 @@ async function extractGitHubSignals(owner, repo, contributor, token, verbose) {
       signals.totalComments += 1;
       const prefixMatch = body.match(prefixRe);
       if (prefixMatch) {
-        increment(signals.severityPrefixes, prefixMatch[1].toLowerCase());
+        const severity = prefixMatch[1].toLowerCase();
+        increment(signals.severityPrefixes, severity);
+        signals.commentSeverities.push(severity);
+      } else {
+        signals.commentSeverities.push("none");
       }
       if (body.endsWith("?") || body.toLowerCase().startsWith("do we") || body.toLowerCase().startsWith("should we")) {
         signals.questionComments += 1;
@@ -1104,6 +1201,18 @@ function extractDocsSignals(docsDir, contributor, verbose) {
 }
 
 // src/generator.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+function getCliVersion() {
+  try {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync4(join(dir, "..", "package.json"), "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 function formatPairs(pairs, suffix = "") {
   return pairs.map(([name, count]) => `${name}${suffix} (${count})`).join(", ");
 }
@@ -1129,23 +1238,66 @@ function buildGhostMarkdown(input) {
   const { contributor, slug, gitObs, codeStyleObs, reviewObs, slackObs, docsSignals, sourcesUsed } = input;
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const domains = gitObs.inferredDomains?.length ? gitObs.inferredDomains.join(", ") : "_[fill in manually]_";
+  const cliVersion = getCliVersion();
   const lines = [
     `# Contributor Soul: ${contributor}`,
     "",
     "## Identity",
     `- **Slug**: ${slug}`,
+    `- **Version**: 0.1.0`,
+    `- **Status**: draft`,
     "- **Role**: _[fill in manually]_",
     `- **Primary domains**: ${domains}`,
     `- **Soul last updated**: ${today}`,
     `- **Sources used**: ${sourcesUsed.join(", ")}`,
+    `- **Generated by**: @poltergeist-ai/cli@${cliVersion}`,
     "",
+    "---",
+    ""
+  ];
+  const weighted = reviewObs.weightedDimensions;
+  const themes = reviewObs.reviewThemes;
+  if (weighted && weighted.length > 0) {
+    lines.push(
+      "## Review Heuristics",
+      "",
+      `_Inferred from ${reviewObs.totalReviewComments ?? "?"} review comments \u2014 adjust weights as needed_`,
+      "",
+      "| Dimension | Weight | Confidence | Default Severity |",
+      "|---|---|---|---|"
+    );
+    for (const dim of weighted) {
+      lines.push(
+        `| ${dim.label} | ${dim.weight.toFixed(2)} | ${dim.confidence} (${dim.commentCount} comments) | ${dim.defaultSeverity} |`
+      );
+    }
+    lines.push("");
+  }
+  lines.push(
+    "### Tradeoff Preferences",
+    "_How this contributor resolves common engineering tensions. Fill in from review patterns._",
+    "",
+    "- abstraction vs duplication: _[prefer-abstraction | prefer-duplication | balanced]_",
+    "- readability vs performance: _[prefer-readability | prefer-performance | balanced]_",
+    "- speed vs correctness: _[prefer-speed | prefer-correctness | balanced]_",
+    "- local vs system optimization: _[prefer-local | prefer-system | balanced]_",
+    ""
+  );
+  lines.push(
+    "### Scars",
+    "_Historical incidents that make this contributor unusually sensitive to certain patterns._",
+    "_Format: **pattern** (multiplier) \u2014 description. Amplifies: dimension names._",
+    "",
+    "_[Fill in manually \u2014 e.g.: **shared-mutable-state** (\xD71.8) \u2014 production incident. Amplifies: error_handling, readability]_",
+    ""
+  );
+  lines.push(
     "---",
     "",
     "## Review Philosophy",
     "",
     "### What they care about most (ranked)"
-  ];
-  const themes = reviewObs.reviewThemes;
+  );
   if (themes && themes.length > 0) {
     lines.push(
       `_Inferred from ${reviewObs.totalReviewComments ?? "?"} review comments \u2014 verify and re-order as needed_`
@@ -1416,6 +1568,132 @@ function buildGhostMarkdown(input) {
   return lines.join("\n");
 }
 
+// src/setup.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync5, writeFileSync } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { createInterface } from "readline";
+import { installRules, supportedTools } from "@poltergeist-ai/llm-rules";
+function getSkillsDir() {
+  return join2(dirname2(fileURLToPath2(import.meta.url)), "..", "skills");
+}
+function loadSkill(filePath) {
+  const raw = readFileSync5(filePath, "utf-8");
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) {
+    return { name: "", description: "", body: raw, raw };
+  }
+  const frontmatter = fmMatch[1];
+  const body = fmMatch[2].trim();
+  let name = "";
+  let description = "";
+  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+  if (nameMatch) name = nameMatch[1].trim();
+  const descMatch = frontmatter.match(/description:\s*>\s*\n([\s\S]*?)$/);
+  if (descMatch) {
+    description = descMatch[1].replace(/\n\s*/g, " ").trim();
+  } else {
+    const descSimple = frontmatter.match(/^description:\s*(?!>)(.+)$/m);
+    if (descSimple) description = descSimple[1].trim();
+  }
+  return { name, description, body, raw };
+}
+function stripPluginRoot(content) {
+  return content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}\//g, ".poltergeist/");
+}
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+async function runSetup(toolFlag) {
+  console.log("\n  Poltergeist Setup\n");
+  const tools = supportedTools();
+  let selectedToolIds;
+  if (toolFlag) {
+    const ids = toolFlag.split(",").map((s) => s.trim().toLowerCase());
+    const valid = ids.filter((id) => tools.some((t) => t.id === id));
+    if (valid.length === 0) {
+      console.error(
+        `Unknown tool(s): ${toolFlag}
+Available: ${tools.map((t) => t.id).join(", ")}`
+      );
+      return 1;
+    }
+    selectedToolIds = valid;
+  } else {
+    console.log("  Available tools:\n");
+    for (let i = 0; i < tools.length; i++) {
+      console.log(`    ${i + 1}. ${tools[i].name} (${tools[i].id})`);
+    }
+    console.log(`    a. All
+`);
+    const answer = await prompt("  Install for (numbers comma-separated, or 'a' for all): ");
+    if (answer.toLowerCase() === "a") {
+      selectedToolIds = tools.map((t) => t.id);
+    } else {
+      const indices = answer.split(",").map((s) => parseInt(s.trim()) - 1).filter((i) => i >= 0 && i < tools.length);
+      if (indices.length === 0) {
+        console.log("No tools selected.");
+        return 0;
+      }
+      selectedToolIds = indices.map((i) => tools[i].id);
+    }
+  }
+  const skillsDir = getSkillsDir();
+  const reviewSkillPath = join2(skillsDir, "poltergeist", "SKILL.md");
+  const extractSkillPath = join2(skillsDir, "extract", "SKILL.md");
+  const rules = [];
+  if (existsSync(reviewSkillPath)) {
+    const skill = loadSkill(reviewSkillPath);
+    rules.push({
+      name: skill.name || "poltergeist",
+      description: skill.description || "Poltergeist review skill",
+      content: stripPluginRoot(skill.raw)
+    });
+  } else {
+    console.error(`  [error] Review skill not found at ${reviewSkillPath}`);
+    return 1;
+  }
+  if (existsSync(extractSkillPath)) {
+    const skill = loadSkill(extractSkillPath);
+    rules.push({
+      name: skill.name || "extract",
+      description: skill.description || "Poltergeist extract skill",
+      content: stripPluginRoot(skill.raw)
+    });
+  }
+  console.log(`
+  Installing for ${selectedToolIds.join(", ")}...`);
+  const results = installRules(rules, {
+    tools: selectedToolIds,
+    force: true,
+    namespace: "poltergeist"
+  });
+  for (const result of results) {
+    console.log(`    \u2713 ${result.path} (${result.action})`);
+  }
+  const exampleGhostPath = join2(skillsDir, "..", "ghosts", "example-ghost.md");
+  if (existsSync(exampleGhostPath)) {
+    const ghostDest = ".poltergeist/ghosts/example-ghost.md";
+    if (!existsSync(ghostDest)) {
+      mkdirSync(dirname2(ghostDest), { recursive: true });
+      writeFileSync(ghostDest, readFileSync5(exampleGhostPath));
+      console.log(`
+    \u2713 ${ghostDest}`);
+    }
+  }
+  console.log("\n  Done. Next steps:");
+  console.log("    1. Build a ghost: npx @poltergeist-ai/cli extract --contributor <name> --git-repo <url>");
+  console.log('    2. Run a review:  git diff main | claude "review as @<slug>"');
+  console.log("");
+  return 0;
+}
+
 // src/cli.ts
 var POLTERGEIST_DIR = ".poltergeist";
 var CACHE_DIR = `${POLTERGEIST_DIR}/repos`;
@@ -1423,25 +1701,27 @@ var GHOSTS_DIR = `${POLTERGEIST_DIR}/ghosts`;
 function ensureReposGitignored() {
   const gitignorePath = ".gitignore";
   const entry = ".poltergeist/repos/";
-  if (existsSync(gitignorePath)) {
-    const content = readFileSync4(gitignorePath, "utf-8");
+  if (existsSync2(gitignorePath)) {
+    const content = readFileSync6(gitignorePath, "utf-8");
     if (content.includes(entry)) return;
     appendFileSync(gitignorePath, `
 # Poltergeist cached clones
 ${entry}
 `);
   } else {
-    writeFileSync(gitignorePath, `# Poltergeist cached clones
+    writeFileSync2(gitignorePath, `# Poltergeist cached clones
 ${entry}
 `);
   }
 }
 function printUsage() {
-  console.log(`Usage: poltergeist [extract] [options]
+  console.log(`Usage: poltergeist <command> [options]
 
-Build a contributor ghost profile from data sources.
+Commands:
+  extract    Build a contributor ghost profile from data sources
+  setup      Install poltergeist skills for your AI coding tool
 
-Options:
+Extract options:
   --contributor <name>    Contributor name (required; use GitHub username for best results)
   --email <email>         Contributor email (for git log filtering)
   --slug <slug>           Output slug (default: derived from name)
@@ -1452,6 +1732,11 @@ Options:
   --github-token <token>  GitHub personal access token (for higher API rate limits)
   --output <path>         Output path (default: .poltergeist/ghosts/<slug>.md)
   --verbose               Enable verbose logging
+
+Setup options:
+  --tool <id>             Tool to install for (claude-code,codex,cursor,windsurf,cline)
+                          Comma-separated for multiple. Omit to choose interactively.
+
   --help                  Show this help message`);
 }
 function isRemoteUrl(value) {
@@ -1464,7 +1749,7 @@ function resolveGitRepo(value, verbose) {
   if (!isRemoteUrl(value)) return value;
   const slug = repoSlug(value);
   const cloneDir = path4.join(CACHE_DIR, slug);
-  if (existsSync(cloneDir)) {
+  if (existsSync2(cloneDir)) {
     console.log(`[extract] Using cached clone at ${cloneDir}`);
     try {
       execFileSync2("git", ["-C", cloneDir, "fetch", "--quiet"], {
@@ -1478,7 +1763,7 @@ function resolveGitRepo(value, verbose) {
     return cloneDir;
   }
   console.log(`[extract] Cloning ${value} into ${cloneDir}...`);
-  mkdirSync(CACHE_DIR, { recursive: true });
+  mkdirSync2(CACHE_DIR, { recursive: true });
   ensureReposGitignored();
   execFileSync2(
     "git",
@@ -1497,6 +1782,16 @@ async function run() {
     printUsage();
     return 0;
   }
+  if (rawArgs[0] === "setup") {
+    const setupArgs = rawArgs.slice(1);
+    let toolFlag;
+    for (let i = 0; i < setupArgs.length; i++) {
+      if (setupArgs[i] === "--tool" && setupArgs[i + 1]) {
+        toolFlag = setupArgs[i + 1];
+      }
+    }
+    return runSetup(toolFlag);
+  }
   const args = rawArgs[0] === "extract" ? rawArgs.slice(1) : rawArgs;
   const { values } = parseArgs({
     args,
@@ -1529,7 +1824,7 @@ async function run() {
   const slug = values.slug ?? slugify(contributor);
   const outputPath = values.output ?? `${GHOSTS_DIR}/${slug}.md`;
   const verbose = values.verbose ?? false;
-  const githubToken = values["github-token"];
+  const githubToken = values["github-token"] ?? process.env.GITHUB_PERSONAL_ACCESS_TOKEN ?? process.env.GITHUB_TOKEN;
   const sourcesUsed = [];
   let gitObs = {};
   let codeStyleObs = { observations: [], totalLinesAnalyzed: 0 };
@@ -1632,9 +1927,9 @@ async function run() {
   });
   const dir = path4.dirname(outputPath);
   if (dir && dir !== ".") {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync2(dir, { recursive: true });
   }
-  writeFileSync(outputPath, ghostMd);
+  writeFileSync2(outputPath, ghostMd);
   console.log(`
 Ghost draft written to: ${outputPath}`);
   console.log("\nNext steps:");

package/dist/index.d.ts

@@ -34,6 +34,8 @@ interface ReviewSignals {
     reviewComments: string[];
     commentLengths: number[];
     severityPrefixes: Record<string, number>;
+    /** Per-comment severity prefix (parallel array to reviewComments) */
+    commentSeverities?: string[];
     questionComments: number;
     totalComments: number;
     source: "github" | "gitlab";
@@ -46,6 +48,10 @@ interface ReviewTheme {
     ratio: number;
     /** Verbatim snippets that matched this theme */
     exampleSnippets: string[];
+    /** Breakdown of severity prefixes for comments matching this theme */
+    severityBreakdown?: Record<string, number>;
+    /** Average character length of comments matching this theme */
+    avgCommentLength?: number;
 }
 interface CommentToneProfile {
     /** Fraction of comments that include praise / positive reinforcement */
@@ -61,6 +67,16 @@ interface CommentToneProfile {
     /** Sample explanatory comments */
     explanationExamples: string[];
 }
+interface WeightedDimension {
+    dimension: string;
+    label: string;
+    /** Composite weight (0.0–1.0) derived from frequency, severity, and specificity */
+    weight: number;
+    confidence: "high" | "moderate" | "low";
+    commentCount: number;
+    /** Most common severity when this theme appears */
+    defaultSeverity: "blocking" | "suggestion" | "nit" | "unknown";
+}
 interface ReviewObservations {
     totalReviewComments?: number;
     avgCommentLength?: number;
@@ -77,6 +93,8 @@ interface ReviewObservations {
     recurringQuestions?: string[];
     /** Phrases/vocabulary the contributor uses repeatedly */
     recurringPhrases?: string[];
+    /** Weighted dimensions computed from frequency, severity, and specificity */
+    weightedDimensions?: WeightedDimension[];
 }
 /** @deprecated Use ReviewSignals instead */
 type GitLabSignals = ReviewSignals;