getprismo 0.1.6 → 0.1.7

package/README.md

@@ -68,8 +68,8 @@ Fixed:
 - Created .cursorignore
 - Generated prismo-dev-report.md
 - Generated .prismo/architecture-summary.md
-- Generated .prismo/recommended-CLAUDE.md
-- Generated .prismo/recommended-AGENTS.md
+- Generated .prismo/recommended-CLAUDE.boilerplate.md
+- Generated .prismo/recommended-AGENTS.boilerplate.md
 - Generated .prismo/recommended-.claudeignore
 - Generated .prismo/recommended-.cursorignore
 - Generated .prismo/recommended-.gitignore-additions
@@ -384,8 +384,8 @@ what doctor creates:
 .prismo/architecture-summary.md            compact project overview for agents
 .prismo/backend-summary.md                 backend-specific context
 .prismo/frontend-summary.md                frontend-specific context
-.prismo/recommended-CLAUDE.md              optimized CLAUDE.md template
-.prismo/recommended-AGENTS.md              optimized AGENTS.md template
+.prismo/recommended-CLAUDE.boilerplate.md              CLAUDE.md boilerplate reference; do not overwrite curated files
+.prismo/recommended-AGENTS.boilerplate.md              AGENTS.md boilerplate reference; do not overwrite curated files
 .prismo/recommended-.claudeignore          full recommended ignore list
 .prismo/recommended-.cursorignore          full recommended ignore list
 .prismo/recommended-.gitignore-additions   things your gitignore might be missing
@@ -600,8 +600,8 @@ no api keys. no intercepted prompts. no data uploaded.
 ├── frontend-summary.md
 ├── frontend-context.md
 ├── backend-context.md
-├── recommended-CLAUDE.md
-├── recommended-AGENTS.md
+├── recommended-CLAUDE.boilerplate.md
+├── recommended-AGENTS.boilerplate.md
 ├── recommended-.claudeignore
 ├── recommended-.cursorignore
 ├── recommended-.gitignore-additions

package/lib/prismo-dev/context-optimize.js

@@ -122,18 +122,49 @@ function isNonSourcePath(rel) {
 }
 
 function detectBackendPaths(result) {
-  const api = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/(backend|app|src)\/.*(router|routes|api)\//.test(rel) || /(backend|app|src)\/.*(router|routes).*\.py$/.test(rel) || /\/(routing|routers?)\.py$/.test(rel)), 20).map((f) => f.path);
-  const services = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/(backend|app|src)\/.*(service|services|application)/.test(rel) || /\/applications?\.py$/.test(rel)), 20).map((f) => f.path);
-  const models = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/(backend|app|src)\/.*models\.py$/.test(rel) || /(backend|app|src)\/.*schema/.test(rel) || /\/models\.py$/.test(rel)), 20).map((f) => f.path);
-  const db = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && /(backend|app|src)\/.*\/(db|database|alembic|migrations)[/.]/.test(rel), 20).map((f) => f.path);
-  const config = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/(backend|app|src)\/.*(config|settings|env).*\.py$/.test(rel) || rel.endsWith("requirements.txt") || rel === "pyproject.toml"), 20).map((f) => f.path);
-  const auth = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/(backend|app|src)\/.*auth/.test(rel) || /\/security\.py$/.test(rel)), 20).map((f) => f.path);
+  const pythonText = (file) => readIfText(path.join(result.root, file.path), 256 * 1024) || "";
+  const isRootPython = (rel) => /^[^/]+\.py$/.test(rel);
+  const isPython = (rel) => rel.endsWith(".py");
+  const hasFastApiSignal = (file) => /FastAPI\s*\(|APIRouter\s*\(|@app\.(get|post|put|patch|delete)|@router\.(get|post|put|patch|delete)/.test(pythonText(file));
+  const api = findRepoFiles(result, (rel, file) => !isNonSourcePath(rel) && (
+    /(backend|app|src)\/.*(router|routes|api)\//.test(rel) ||
+    /(backend|app|src)\/.*(router|routes).*\.py$/.test(rel) ||
+    /\/(routing|routers?)\.py$/.test(rel) ||
+    (isRootPython(rel) && hasFastApiSignal(file))
+  ), 30).map((f) => f.path);
+  const services = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (
+    /(backend|app|src)\/.*(service|services|application)/.test(rel) ||
+    /\/applications?\.py$/.test(rel) ||
+    (isRootPython(rel) && /(service|worker|manager|client|heartbeat|memory|chat|tool|orchestrator|pipeline)/i.test(rel))
+  ), 40).map((f) => f.path);
+  const models = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (
+    /(backend|app|src)\/.*models\.py$/.test(rel) ||
+    /(backend|app|src)\/.*schema/.test(rel) ||
+    /\/models\.py$/.test(rel) ||
+    (isRootPython(rel) && /(model|schema|entity|types?)/i.test(rel))
+  ), 30).map((f) => f.path);
+  const db = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (
+    /(backend|app|src)\/.*\/(db|database|alembic|migrations)[/.]/.test(rel) ||
+    (isPython(rel) && /(sqlite|qdrant|neo4j|database|storage|repository|vector|graph|migration)/i.test(rel))
+  ), 30).map((f) => f.path);
+  const config = findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (
+    /(backend|app|src)\/.*(config|settings|env).*\.py$/.test(rel) ||
+    (isRootPython(rel) && /(config|settings|env)/i.test(rel)) ||
+    rel.endsWith("requirements.txt") ||
+    rel === "pyproject.toml"
+  ), 20).map((f) => f.path);
+  const auth = findRepoFiles(result, (rel, file) => !isNonSourcePath(rel) && (
+    /(backend|app|src)\/.*auth/.test(rel) ||
+    /\/security\.py$/.test(rel) ||
+    (isPython(rel) && /(auth|security|permission|token|session|oauth|jwt|middleware)/i.test(rel)) ||
+    (isRootPython(rel) && /(Depends|HTTPBearer|OAuth2|JWT|Authorization)/.test(pythonText(file)))
+  ), 30).map((f) => f.path);
   return { api, services, models, db, config, auth };
 }
 
 function detectFrontendPaths(result) {
   return {
-    app: findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/frontend\/src\/app\//.test(rel) || /src\/app\//.test(rel) || /apps\/[^/]+\/app\//.test(rel) || /apps\/[^/]+\/src\/app\//.test(rel)), 24).map((f) => f.path),
+    app: findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/frontend\/src\/app\//.test(rel) || /frontend\/src\/App\.[jt]sx?$/.test(rel) || /src\/App\.[jt]sx?$/.test(rel) || /src\/app\//.test(rel) || /apps\/[^/]+\/app\//.test(rel) || /apps\/[^/]+\/src\/app\//.test(rel)), 24).map((f) => f.path),
     components: findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/frontend\/src\/components\//.test(rel) || /src\/components\//.test(rel) || /apps\/[^/]+\/.*components\//.test(rel) || /packages\/[^/]+\/.*components\//.test(rel)), 20).map((f) => f.path),
     apiClient: findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/frontend\/src\/(lib|hooks)\/.*(api|client|query|finops)/.test(rel) || /src\/(lib|hooks)\/.*(api|client|query)/.test(rel)), 20).map((f) => f.path),
     styling: findRepoFiles(result, (rel) => !isNonSourcePath(rel) && (/tailwind\.config|globals\.css|\.module\.css|frontend\/src\/app\/globals/.test(rel)), 20).map((f) => f.path),
@@ -186,6 +217,60 @@ function mdList(items, empty = "None detected.") {
   return items.map((item) => `- \`${item}\``).join("\n");
 }
 
+function topBySize(files, limit = 8) {
+  return [...(files || [])]
+    .filter((file) => !file.ignored && file.kind !== "binary")
+    .sort((a, b) => b.size - a.size)
+    .slice(0, limit)
+    .map((file) => `${file.path} (${formatBytes(file.size)})`);
+}
+
+function inferGaps(ctx) {
+  const gaps = [];
+  if (ctx.backendDetected && !ctx.backend.api.length) {
+    gaps.push("No conventional backend API layout detected; review root-level Python files or custom service modules for FastAPI/APIRouter usage.");
+  }
+  if (ctx.backendDetected && !ctx.backend.services.length) {
+    gaps.push("No conventional service directory detected; backend services may use flat files or project-specific naming.");
+  }
+  if (ctx.frontendDetected && !ctx.frontend.app.length) {
+    gaps.push("No conventional frontend routing surface detected; Vite/React routes may live in App.tsx or custom tab components.");
+  }
+  return gaps;
+}
+
+function summarizeRiskyDirectories(dirs) {
+  const groups = new Map();
+  for (const dir of dirs || []) {
+    const normalized = dir.path.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    let key = `${normalized}/`;
+    if (parts.includes("__pycache__")) {
+      const before = parts.slice(0, parts.indexOf("__pycache__"));
+      const prefix = before.length ? `${before[0]}/**` : "**";
+      key = `${prefix}/__pycache__/`;
+    } else if (parts.includes("node_modules")) {
+      key = `${parts.slice(0, parts.indexOf("node_modules") + 1).join("/")}/**`;
+    } else if (parts.length > 2) {
+      key = `${parts.slice(0, 2).join("/")}/**/${parts[parts.length - 1]}/`;
+    }
+    const existing = groups.get(key) || { key, count: 0, exposed: 0, ignored: 0, examples: [] };
+    existing.count += 1;
+    if (dir.exposed) existing.exposed += 1;
+    else existing.ignored += 1;
+    if (existing.examples.length < 2) existing.examples.push(`${normalized}/`);
+    groups.set(key, existing);
+  }
+  return Array.from(groups.values())
+    .sort((a, b) => b.exposed - a.exposed || b.count - a.count)
+    .slice(0, 25)
+    .map((group) => {
+      const state = group.exposed ? `${group.exposed} exposed` : `${group.ignored} ignored`;
+      const example = group.examples[0] && group.examples[0] !== group.key ? `; e.g. ${group.examples[0]}` : "";
+      return `${group.key} (${group.count} director${group.count === 1 ? "y" : "ies"}, ${state}${example})`;
+    });
+}
+
 function proseList(items, empty = "none detected") {
   return items && items.length ? items.join(", ") : empty;
 }
@@ -194,6 +279,7 @@ function renderArchitectureSummary(ctx) {
   const apiLayer = ctx.backend.api.slice(0, 6);
   const dbLayer = ctx.backend.db.slice(0, 6);
   const frontendLayer = ctx.frontend.app.slice(0, 6);
+  const gaps = inferGaps(ctx);
   const readOrder = [
     "- Start here.",
     ctx.backendDetected ? "- For backend work, read `.prismo/backend-summary.md` next." : null,
@@ -234,6 +320,10 @@ function renderArchitectureSummary(ctx) {
     "",
     ctx.warnings.length ? ctx.warnings.map((warning) => `- ${warning}`).join("\n") : "- No major local context risks detected.",
     "",
+    "## Detection Gaps",
+    "",
+    gaps.length ? gaps.map((gap) => `- ${gap}`).join("\n") : "- No major architecture-detection gaps surfaced.",
+    "",
     "## AI Workflow Notes",
     "",
     "- Prefer this summary before broad repo reads.",
@@ -244,6 +334,7 @@ function renderArchitectureSummary(ctx) {
 }
 
 function renderBackendSummary(ctx) {
+  const backendCandidates = topBySize(ctx.scan.files.filter((file) => file.path.endsWith(".py") && !isNonSourcePath(file.path)), 8);
   return [
     "# Backend Summary",
     "",
@@ -273,10 +364,21 @@ function renderBackendSummary(ctx) {
     "",
     mdList(ctx.backend.config),
     "",
+    "## Load-Bearing Candidates",
+    "",
+    mdList(backendCandidates, "No Python source candidates detected."),
+    "",
+    "## Detection Notes",
+    "",
+    ctx.backend.api.length || ctx.backend.services.length
+      ? "- Backend paths were inferred from conventional directories plus root-level Python/FastAPI/service filename signals."
+      : "- No conventional backend paths were detected; inspect root-level Python modules and custom service naming manually.",
+    "",
   ].join("\n");
 }
 
 function renderFrontendSummary(ctx) {
+  const frontendCandidates = topBySize(ctx.scan.files.filter((file) => /\.(tsx?|jsx?)$/.test(file.path) && /(^|\/)(frontend|src|app|components|hooks)\//.test(file.path)), 8);
   return [
     "# Frontend Summary",
     "",
@@ -302,6 +404,10 @@ function renderFrontendSummary(ctx) {
     "",
     mdList(ctx.frontend.styling),
     "",
+    "## Load-Bearing Candidates",
+    "",
+    mdList(frontendCandidates, "No frontend source candidates detected."),
+    "",
   ].join("\n");
 }
 
@@ -319,7 +425,9 @@ function renderRecommendedClaude(ctx) {
   if (hasPath(ctx.scan, (rel) => rel === "frontend/package.json")) commands.push("cd frontend && npm run test");
   if (hasPath(ctx.scan, (rel) => rel === "backend/pytest.ini" || rel.startsWith("backend/tests/"))) commands.push("cd backend && pytest");
   return [
-    "# CLAUDE.md",
+    "# CLAUDE.md Boilerplate",
+    "",
+    "Do not overwrite an existing curated CLAUDE.md with this file. Use it as a diff/reference for missing compact-context guidance only.",
     "",
     "Keep context small. Start with `.prismo/architecture-summary.md`; use scoped `.prismo/*-summary.md` files only when relevant.",
     "",
@@ -351,7 +459,9 @@ function renderRecommendedClaude(ctx) {
 
 function renderRecommendedAgents(ctx) {
   return [
-    "# AGENTS.md",
+    "# AGENTS.md Boilerplate",
+    "",
+    "Do not overwrite an existing curated AGENTS.md with this file. Use it as a diff/reference for missing compact-context guidance only.",
     "",
     "Use `.prismo/architecture-summary.md` first to avoid repeated broad repo exploration. Keep this file durable and short; task-specific details belong in the prompt or scoped context files.",
     "",
@@ -413,7 +523,7 @@ function renderOptimizeReport(ctx, generatedFiles) {
     "",
     "## Token-Heavy Directories",
     "",
-    mdList(ctx.scan.highRiskDirs.map((dir) => `${dir.path}/${dir.exposed ? " (exposed)" : " (ignored)"}`)),
+    mdList(summarizeRiskyDirectories(ctx.scan.highRiskDirs)),
     "",
     "## Optimization Suggestions",
     "",
@@ -530,8 +640,8 @@ function renderContextCommand(ctx, scope = null) {
 function getOptimizePendingFiles(ctx) {
   const pending = [
     ["architecture-summary.md", renderArchitectureSummary(ctx)],
-    ["recommended-CLAUDE.md", renderRecommendedClaude(ctx)],
-    ["recommended-AGENTS.md", renderRecommendedAgents(ctx)],
+    ["recommended-CLAUDE.boilerplate.md", renderRecommendedClaude(ctx)],
+    ["recommended-AGENTS.boilerplate.md", renderRecommendedAgents(ctx)],
     ["recommended-.claudeignore", `${ctx.scan.recommendedClaudeIgnore.join("\n")}\n`],
     ["recommended-.cursorignore", `${ctx.scan.recommendedCursorIgnore.join("\n")}\n`],
     ["recommended-.gitignore-additions", renderGitignoreAdditions(ctx)],

package/lib/prismo-dev/fixes.js

@@ -77,8 +77,8 @@ function applyFixes(result, options = {}) {
   }
   if (ignoresOnly) return actions;
 
-  const report = options.dryRun ? { reportPath: path.join(result.root, "prismo-dev-report.md"), backupPath: null } : writeReport(result);
-  actions.push(`${options.dryRun ? "Would generate" : "Generated"} ${path.basename(report.reportPath)}`);
+  const report = options.dryRun ? { reportPath: path.join(result.root, ".prismo", "prismo-dev-report.md"), backupPath: null } : writeReport(result);
+  actions.push(`${options.dryRun ? "Would generate" : "Generated"} .prismo/${path.basename(report.reportPath)}`);
   if (report.backupPath) actions.push(`Backed up existing report to ${path.basename(report.backupPath)}`);
 
   const claudeFile = result.instructionFiles.find((file) => file.isClaude);
@@ -92,10 +92,12 @@ function applyFixes(result, options = {}) {
 
   const hasCodexRisk = result.issues.some((issue) => issue.category === "codex_config");
   if (hasCodexRisk || result.instructionFiles.some((file) => file.path === "AGENTS.md" || file.path.startsWith(".codex/"))) {
-    const codexPath = path.join(result.root, "prismo-AGENTS-recommendations.md");
+    const prismoDir = path.join(result.root, ".prismo");
+    if (!options.dryRun) fs.mkdirSync(prismoDir, { recursive: true });
+    const codexPath = path.join(prismoDir, "prismo-AGENTS-recommendations.md");
     const backupPath = options.dryRun ? null : backupIfExists(codexPath);
     if (!options.dryRun) fs.writeFileSync(codexPath, renderAgentsRecommendations(result), "utf8");
-    actions.push(`${options.dryRun ? "Would generate" : "Generated"} prismo-AGENTS-recommendations.md`);
+    actions.push(`${options.dryRun ? "Would generate" : "Generated"} .prismo/prismo-AGENTS-recommendations.md`);
     if (backupPath) actions.push(`Backed up existing AGENTS recommendations to ${path.basename(backupPath)}`);
   }
   return actions;

package/lib/prismo-dev/report.js

@@ -94,7 +94,7 @@ function renderTerminalReport(result, options = {}) {
       ? "No matching local usage sessions were found; repo-risk estimates remain heuristic."
     : "Potential savings estimates are heuristic and local-only, not provider billing data.");
   lines.push("");
-  lines.push(reportEnabled ? "Report: prismo-dev-report.md" : "Report: skipped (--no-report)");
+  lines.push(reportEnabled ? "Report: .prismo/prismo-dev-report.md" : "Report: skipped (--no-report)");
   return lines.join("\n");
 }
 
@@ -342,7 +342,9 @@ function backupIfExists(filePath) {
 }
 
 function writeReport(result) {
-  const reportPath = path.join(result.root, "prismo-dev-report.md");
+  const prismoDir = path.join(result.root, ".prismo");
+  fs.mkdirSync(prismoDir, { recursive: true });
+  const reportPath = path.join(prismoDir, "prismo-dev-report.md");
   const backupPath = backupIfExists(reportPath);
   fs.writeFileSync(reportPath, renderMarkdownReport(result), "utf8");
   return { reportPath, backupPath };

package/lib/prismo-dev/scan.js

@@ -1060,9 +1060,7 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
   const recommendedCursorIgnore = Array.from(new Set([
     ...recommendedClaudeIgnore,
     ".prismo/",
-    "prismo-dev-report.md",
     "prismo-optimized-CLAUDE.template.md",
-    "prismo-AGENTS-recommendations.md",
   ]));
   const recommendations = buildRecommendations({
     hasClaudeIgnore,

package/lib/prismo-dev-scan.js

@@ -304,7 +304,7 @@ Options:
   --json      Output valid JSON only for CI or future dashboard ingestion.
   --usage     Include real local Codex/Claude Code session usage in scan diagnostics.
   --simple    Print a plain-English scan summary for first-time or non-technical users.
-  --no-report Do not write prismo-dev-report.md.
+  --no-report Do not write .prismo/prismo-dev-report.md.
   --limit N   Number of recent local sessions to show.
   --interval N Refresh interval in seconds for watch mode.
   --dry-run  Preview doctor/fix actions without writing files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",