@a-company/paradigm 1.5.0

package/dist/beacon-B47XSTL7.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+import {
+  aggregateFromDirectory,
+  buildSymbolIndex,
+  getAllSymbols,
+  getSymbolCounts
+} from "./chunk-5C4SGQKH.js";
+import "./chunk-PW2EXJQT.js";
+import "./chunk-IRKUEJVW.js";
+import {
+  log
+} from "./chunk-4NCFWYGG.js";
+import "./chunk-MO4EEYFW.js";
+
+// src/commands/beacon.ts
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import ora from "ora";
+function findLandmarks(rootDir) {
+  const landmarks = [];
+  const importantFiles = [
+    { pattern: "portal.yaml", desc: "Authorization topology" },
+    { pattern: "src/lib/api.ts", desc: "API utilities" },
+    { pattern: "src/lib/api.js", desc: "API utilities" },
+    { pattern: "src/utils/api.ts", desc: "API utilities" },
+    { pattern: "src/hooks/useAuth.ts", desc: "Auth hook" },
+    { pattern: "src/hooks/useAuth.tsx", desc: "Auth hook" },
+    { pattern: "src/context/AuthContext.tsx", desc: "Auth context" },
+    { pattern: "src/store/index.ts", desc: "State store" },
+    { pattern: "src/types/index.ts", desc: "Type definitions" },
+    { pattern: "src/types.ts", desc: "Type definitions" },
+    { pattern: ".paradigm/config.yaml", desc: "Paradigm config" },
+    { pattern: "tsconfig.json", desc: "TypeScript config" },
+    { pattern: "package.json", desc: "Package manifest" }
+  ];
+  for (const { pattern, desc } of importantFiles) {
+    const fullPath = path.join(rootDir, pattern);
+    if (fs.existsSync(fullPath)) {
+      landmarks.push({ path: pattern, description: desc });
+    }
+  }
+  return landmarks.slice(0, 8);
+}
+function findPathways(rootDir) {
+  const promptsDir = path.join(rootDir, ".paradigm", "prompts");
+  const pathways = [];
+  if (fs.existsSync(promptsDir)) {
+    const files = fs.readdirSync(promptsDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const name = file.replace(".md", "").replace(/-/g, " ");
+      pathways.push({
+        name: name.charAt(0).toUpperCase() + name.slice(1),
+        path: `.paradigm/prompts/${file}`
+      });
+    }
+  }
+  return pathways.slice(0, 6);
+}
+function generateBeacon(projectName, symbols, landmarks, pathways, _rootDir) {
+  const lines = [];
+  lines.push(`# Beacon - ${projectName}`);
+  lines.push("");
+  lines.push("> Quick-start orientation for AI agents. Generated by Paradigm.");
+  lines.push("");
+  lines.push("## Constellation (Symbol Map)");
+  lines.push("");
+  lines.push("```");
+  const components = symbols.filter((s) => s.type === "component");
+  const gates = symbols.filter((s) => s.type === "gate");
+  for (const component of components.slice(0, 15)) {
+    const componentGates = component.references.filter((r) => r.startsWith("^"));
+    let line = `${component.symbol.padEnd(20)} \u2192 ${path.dirname(component.filePath).padEnd(25)}`;
+    if (componentGates.length > 0) {
+      line += ` \u2192 ${componentGates.join(", ")}`;
+    }
+    lines.push(line);
+  }
+  if (components.length > 15) {
+    lines.push(`... and ${components.length - 15} more components`);
+  }
+  lines.push("```");
+  lines.push("");
+  if (gates.length > 0) {
+    lines.push("## Gates (Authorization)");
+    lines.push("");
+    for (const gate of gates.slice(0, 6)) {
+      const desc = gate.description ? ` - ${gate.description}` : "";
+      lines.push(`- \`${gate.symbol}\`${desc}`);
+    }
+    if (gates.length > 6) {
+      lines.push(`- ... and ${gates.length - 6} more gates`);
+    }
+    lines.push("");
+  }
+  if (landmarks.length > 0) {
+    lines.push("## Landmarks (Key Files)");
+    lines.push("");
+    for (const landmark of landmarks) {
+      lines.push(`- \`${landmark.path}\` - ${landmark.description}`);
+    }
+    lines.push("");
+  }
+  if (pathways.length > 0) {
+    lines.push("## Pathways (Common Tasks)");
+    lines.push("");
+    for (const pathway of pathways) {
+      lines.push(`- "${pathway.name}" \u2192 \`${pathway.path}\``);
+    }
+    lines.push("");
+  }
+  lines.push("## Symbol Quick Reference");
+  lines.push("");
+  lines.push("| Symbol | Type | Meaning |");
+  lines.push("|--------|------|---------|");
+  lines.push("| `#` | Component | Any documented code unit |");
+  lines.push("| `$` | Flow | Multi-step process |");
+  lines.push("| `^` | Gate | Authorization checkpoint |");
+  lines.push("| `!` | Signal | Event for side effects |");
+  lines.push("| `~` | Aspect | Rule with code anchor |");
+  lines.push("");
+  lines.push("## For More Context");
+  lines.push("");
+  lines.push("- Full symbol graph: `.paradigm/constellation.json`");
+  lines.push("- Detailed context: `.paradigm/specs/` for detailed specifications");
+  lines.push("- Session history: `.paradigm/thread.md` (if available)");
+  lines.push("- Error mapping: `.paradigm/echoes.yaml` (if available)");
+  lines.push("");
+  lines.push("---");
+  lines.push(`*Generated: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}*`);
+  lines.push(`*Run \`paradigm beacon --refresh\` to update*`);
+  return lines.join("\n");
+}
+async function beaconCommand(targetPath, options = {}) {
+  const cwd = process.cwd();
+  const absolutePath = targetPath ? path.resolve(cwd, targetPath) : cwd;
+  const projectName = path.basename(absolutePath);
+  const showUI = !options.json && !options.quiet;
+  if (showUI) {
+    console.log(chalk.blue("\n\u{1F526} Generating Beacon...\n"));
+  }
+  const spinner = options.json ? null : ora("Scanning project...").start();
+  const tracker = log.command("beacon").start("Generating beacon", { project: projectName });
+  try {
+    const paradigmDir = path.join(absolutePath, ".paradigm");
+    const beaconPath = options.output || path.join(paradigmDir, "beacon.md");
+    if (!options.json && fs.existsSync(beaconPath) && !options.refresh) {
+      spinner?.info("Beacon already exists");
+      if (showUI) {
+        console.log(chalk.gray(`  Use --refresh to regenerate
+`));
+        console.log(chalk.gray(`  Path: ${beaconPath}
+`));
+        const content = fs.readFileSync(beaconPath, "utf8");
+        const lines = content.split("\n").slice(0, 15);
+        console.log(chalk.white("Current Beacon (preview):"));
+        console.log(chalk.gray("\u2500".repeat(40)));
+        for (const line of lines) {
+          console.log(chalk.gray(`  ${line}`));
+        }
+        console.log(chalk.gray("  ..."));
+        console.log("");
+      }
+      return;
+    }
+    const result = await aggregateFromDirectory(absolutePath);
+    const index = buildSymbolIndex(result);
+    const symbols = getAllSymbols(index);
+    spinner && (spinner.text = "Finding landmarks...");
+    const landmarks = findLandmarks(absolutePath);
+    spinner && (spinner.text = "Finding pathways...");
+    const pathways = findPathways(absolutePath);
+    if (options.json) {
+      const jsonComponents = symbols.filter((s) => s.type === "component");
+      const jsonGates = symbols.filter((s) => s.type === "gate");
+      const counts = getSymbolCounts(index);
+      const jsonOutput = {
+        project: projectName,
+        generated: (/* @__PURE__ */ new Date()).toISOString(),
+        symbols: {
+          features: jsonComponents.filter((c) => c.tags?.includes("feature")).map((f) => ({
+            symbol: f.symbol,
+            path: path.dirname(f.filePath),
+            portals: f.references.filter((r) => r.startsWith("^")).length > 0 ? f.references.filter((r) => r.startsWith("^")) : void 0
+          })),
+          components: jsonComponents.map((c) => ({
+            symbol: c.symbol,
+            path: path.dirname(c.filePath)
+          })),
+          portals: jsonGates.map((g) => ({
+            symbol: g.symbol,
+            description: g.description
+          }))
+        },
+        landmarks,
+        pathways,
+        stats: {
+          features: jsonComponents.filter((c) => c.tags?.includes("feature")).length,
+          components: counts.component,
+          portals: counts.gate,
+          total: Object.values(counts).reduce((a, b) => a + b, 0)
+        }
+      };
+      console.log(JSON.stringify(jsonOutput, null, 2));
+      return jsonOutput;
+    }
+    spinner && (spinner.text = "Generating beacon...");
+    const beaconContent = generateBeacon(
+      projectName,
+      symbols,
+      landmarks,
+      pathways,
+      absolutePath
+    );
+    if (!fs.existsSync(paradigmDir)) {
+      fs.mkdirSync(paradigmDir, { recursive: true });
+    }
+    fs.writeFileSync(beaconPath, beaconContent, "utf8");
+    log.component("beacon-file").success("Beacon file written", { path: beaconPath });
+    spinner?.succeed("Beacon generated");
+    tracker.success("Beacon generated", { path: beaconPath, symbols: symbols.length });
+    if (!options.quiet) {
+      const counts = getSymbolCounts(index);
+      console.log(chalk.white("\nBeacon Contents"));
+      console.log(chalk.gray("\u2500".repeat(40)));
+      console.log(`  Components:  ${chalk.green(counts.component.toString())}`);
+      console.log(`  Flows:       ${chalk.yellow(counts.flow.toString())}`);
+      console.log(`  Gates:       ${chalk.red(counts.gate.toString())}`);
+      console.log(`  Signals:     ${chalk.cyan(counts.signal.toString())}`);
+      console.log(`  Aspects:     ${chalk.magenta(counts.aspect.toString())}`);
+      console.log(`  Landmarks:   ${chalk.cyan(landmarks.length.toString())}`);
+      console.log(`  Pathways:    ${chalk.yellow(pathways.length.toString())}`);
+      console.log(chalk.gray(`
+  Output: ${beaconPath}
+`));
+      console.log(chalk.white("Tip"));
+      console.log(chalk.gray("\u2500".repeat(40)));
+      console.log(chalk.gray("  AI agents should read beacon.md first for quick orientation."));
+      console.log(chalk.gray("  Then constellation.json for detailed relationships.\n"));
+    }
+  } catch (error) {
+    spinner?.fail("Failed to generate beacon");
+    tracker.error("Beacon generation failed", { error: error.message });
+    console.log(chalk.red(`Error: ${error.message}
+`));
+    process.exit(1);
+  }
+}
+export {
+  beaconCommand
+};