@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/scripts/ai-init.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Install Concorde AI agent files into a project.
+ * Install the Concorde agent skill into a project.
  *
  * Usage:
  *   node node_modules/@supersoniks/concorde/scripts/ai-init.mjs [options]
@@ -9,31 +9,17 @@
  * Options:
  *   --project-root <dir>   Project root (default: cwd)
  *   --concorde-ai <dir>    Concorde ai/ folder (default: auto-detect)
- *   --overlay <dir>        Extra layer (project kit) — uses AGENTS.concorde.md
- *   --cursor-only          Install only Cursor (.cursor/)
- *   --jetbrains-only       Install only JetBrains (.aiassistant/rules/)
- *   --skip-agents          Never write AGENTS.md (skills/rules only)
- *   --merge-agents         Opt-in: keep project preamble, append/refresh Concorde block
- *   --force-agents         Opt-in: replace AGENTS.md entirely (destructive)
+ *   --overlay <dir>        Extra skills from a project kit (<dir>/skills/<name>/)
+ *   --no-links             Do not link skills into .claude/ and .junie/
  *
- * AGENTS.md policy (non-invasive by default):
- *   - Missing file → create Concorde guide
- *   - Existing with <!-- concorde-ai --> → refresh managed zone only
- *   - Existing without marker → leave untouched (project-owned, e.g. billetterie)
- *     unless --merge-agents or --force-agents
+ * Skills:
+ *   - Copied to .agents/skills/<name>/ (read natively by Cursor and other
+ *     agents following the Agent Skills convention)
+ *   - Linked per skill from .claude/skills/ (Claude Code) and .junie/skills/
+ *     (JetBrains Junie); copied instead where symlinks are not allowed
+ *   - Project skills with the same folder name are never overwritten
  *
- * Layout when writing:
- *
- *   [optional project preamble — short, project-only]
- *   <!-- concorde-ai -->
- *   <package ai/AGENTS.md>
- *   [--- + overlay AGENTS.concorde.md]
- *
- * Everything AFTER the marker is owned by Concorde and replaced on every run.
- * Do not copy the full Concorde guide into the preamble — use overlay/AGENTS.concorde.md
- * for project-specific agent notes (endpoints, dpKeys, …).
- *
- * Legacy: AGENTS.starter.md / AGENTS.overlay.md still read if AGENTS.concorde.md is missing.
+ * AGENTS.md belongs to the project: ai-init never reads nor writes it.
  */
 
 import fs from "node:fs";
@@ -42,15 +28,6 @@ import {fileURLToPath, pathToFileURL} from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const AGENTS_MARKER = "<!-- concorde-ai -->";
-/** Project Concorde notes for `--overlay` (preferred). */
-const OVERLAY_AGENTS_FILE = "AGENTS.concorde.md";
-/** @deprecated Prefer AGENTS.concorde.md */
-const OVERLAY_AGENTS_FILE_LEGACY = [
-  "AGENTS.overlay.md",
-  "AGENTS.starter.md",
-];
-
 const args = process.argv.slice(2);
 
 function readArg(name) {
@@ -66,36 +43,11 @@ const overlayDir = readArg("--overlay")
   ? path.resolve(readArg("--overlay"))
   : undefined;
 
-const cursorOnly = flags.has("--cursor-only");
-const jetbrainsOnly = flags.has("--jetbrains-only");
-const skipAgents = flags.has("--skip-agents");
-const mergeAgents = flags.has("--merge-agents");
-const forceAgents = flags.has("--force-agents");
-const installCursor = !jetbrainsOnly;
-const installJetbrains = !cursorOnly;
-
-/**
- * Decide whether / how to write AGENTS.md.
- * @returns {"skip" | "create" | "refresh" | "merge" | "force"}
- */
-export function decideAgentsAction({
-  existingText = "",
-  skipAgents: skip = false,
-  mergeAgents: merge = false,
-  forceAgents: force = false,
-} = {}) {
-  if (skip) return "skip";
-  const text = existingText.replace(/\r\n/g, "\n");
-  const exists = text.trim().length > 0;
-  const hasMarker = text.includes(AGENTS_MARKER);
-
-  if (!exists) return "create";
-  if (hasMarker) return "refresh";
-  if (force) return "force";
-  if (merge) return "merge";
-  return "skip";
-}
-
+const noLinks = flags.has("--no-links");
+/** Canonical skills folder, relative to the project root. */
+export const SKILLS_DIR = ".agents/skills";
+/** Agent-specific skills folders that get one symlink per skill. */
+export const SKILL_LINK_DIRS = [".claude/skills", ".junie/skills"];
 function detectConcordeAi() {
   const explicit = readArg("--concorde-ai");
   if (explicit) return path.resolve(explicit);
@@ -111,33 +63,6 @@ function detectConcordeAi() {
   );
 }
 
-/**
- * Read project Concorde AGENTS notes from `--overlay` dir.
- * Prefers AGENTS.concorde.md; falls back to deprecated legacy names.
- * @returns {{ content: string, warnings: string[] }}
- */
-export function readOverlayAgents(overlayDir) {
-  const warnings = [];
-  if (!overlayDir) return {content: "", warnings};
-
-  const preferred = path.join(overlayDir, OVERLAY_AGENTS_FILE);
-  if (fs.existsSync(preferred)) {
-    return {content: fs.readFileSync(preferred, "utf8"), warnings};
-  }
-
-  for (const legacyName of OVERLAY_AGENTS_FILE_LEGACY) {
-    const legacy = path.join(overlayDir, legacyName);
-    if (fs.existsSync(legacy)) {
-      warnings.push(
-        `Overlay uses deprecated ${legacyName} — rename to ${OVERLAY_AGENTS_FILE}.`,
-      );
-      return {content: fs.readFileSync(legacy, "utf8"), warnings};
-    }
-  }
-
-  return {content: "", warnings};
-}
-
 function copyDir(src, dest) {
   if (!fs.existsSync(src)) return;
   fs.mkdirSync(dest, {recursive: true});
@@ -153,229 +78,98 @@ function copyDir(src, dest) {
   }
 }
 
-function normalizeHeading(title) {
-  return title
-    .normalize("NFKD")
-    .replace(/\p{M}/gu, "")
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, " ")
-    .trim();
+function listSkillNames(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, {withFileTypes: true})
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "SKILL.md")))
+    .map((e) => e.name)
+    .sort();
 }
 
-function isStockConcordeH1(title) {
-  // "# Agents — Concorde" with optional project suffix in parentheses
-  return /^agents\s+concorde(\s|$)/i.test(normalizeHeading(title));
+function removePath(p) {
+  fs.rmSync(p, {recursive: true, force: true});
 }
 
-/**
- * Split markdown into a leading H1 block + ## sections (## title → body).
- * @returns {{ h1: string | null, sections: Array<{ title: string, body: string }> }}
- */
-function splitAgentsSections(markdown) {
-  const text = markdown.replace(/\r\n/g, "\n").trim();
-  if (!text) return {h1: null, sections: []};
-
-  const parts = text.split(/\n(?=##\s+)/);
-  let h1 = null;
-  const sections = [];
-
-  for (const part of parts) {
-    const trimmed = part.trim();
-    if (!trimmed) continue;
-    if (trimmed.startsWith("## ")) {
-      const nl = trimmed.indexOf("\n");
-      const titleLine = nl === -1 ? trimmed : trimmed.slice(0, nl);
-      const title = titleLine.replace(/^##\s+/, "").trim();
-      const body = nl === -1 ? "" : trimmed.slice(nl + 1).trim();
-      sections.push({title, body});
-    } else if (h1 === null) {
-      h1 = trimmed;
-    } else {
-      // Orphan content without ## — keep as synthetic section
-      sections.push({title: "", body: trimmed});
-    }
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
   }
-
-  return {h1, sections};
 }
 
-function baseHeadingSet(baseContent) {
-  const {sections} = splitAgentsSections(baseContent);
-  return new Set(sections.map((s) => normalizeHeading(s.title)).filter(Boolean));
-}
-
-/** Match "## Skills / rules" with "## Skills / rules (après installation)". */
-function isSameAgentsHeading(a, b) {
-  if (!a || !b) return false;
-  if (a === b) return true;
-  const stripParen = (s) => s.replace(/\s*\(.*\)$/, "").trim();
-  const aa = stripParen(a);
-  const bb = stripParen(b);
-  if (aa === bb) return true;
-  return aa.startsWith(bb) || bb.startsWith(aa);
-}
-
-function isPackageHeading(titleKey, baseHeads) {
-  for (const bh of baseHeads) {
-    if (isSameAgentsHeading(titleKey, bh)) return true;
+function pathExists(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
   }
-  return false;
 }
 
 /**
- * True when preamble looks like a full (or near-full) copy of package AGENTS.md.
+ * Copy skills into `<projectRoot>/.agents/skills`, replacing previous copies.
+ * @param {string[]} sourceDirs skills folders (package first, then overlay)
+ * @returns {string[]} installed skill names
  */
-export function preambleDuplicatesBase(preamble, baseContent) {
-  const p = preamble.trim();
-  const b = baseContent.trim();
-  if (!p || !b) return false;
-
-  const fingerprints = [
-    "sonic-fetch",
-    "publishermanager",
-    "formdataprovider",
-    "dataprovide",
-    "concorde-get-set-dp",
-  ];
-  const pNorm = p.toLowerCase();
-  const hits = fingerprints.filter((fp) => pNorm.includes(fp)).length;
-  const longEnough = p.length >= b.length * 0.45;
-  const stockTitle = /^#\s*agents\s*[—–-]\s*concorde\b/im.test(p);
-
-  return stockTitle && longEnough && hits >= 3;
-}
-
-/**
- * Keep only project-specific preamble bits (unique ## vs package, short custom H1).
- * Drops sections that duplicate Concorde ai/AGENTS.md so re-runs heal stacked copies.
- */
-export function slimPreamble(preamble, baseContent) {
-  const raw = preamble.trim();
-  if (!raw) return "";
-
-  const {h1, sections} = splitAgentsSections(raw);
-  const h1Title = h1?.split("\n")[0]?.replace(/^#\s+/, "").trim() ?? "";
-  // Full forks OR any preamble titled like Concorde AGENTS → strip package ## sections
-  const shouldDedup =
-    preambleDuplicatesBase(raw, baseContent) || isStockConcordeH1(h1Title);
-
-  if (!shouldDedup) {
-    return raw;
+export function syncSkills(projectRoot, sourceDirs) {
+  const dest = path.join(projectRoot, SKILLS_DIR);
+  const installed = new Map();
+  for (const dir of sourceDirs) {
+    for (const name of listSkillNames(dir)) installed.set(name, path.join(dir, name));
   }
 
-  const baseHeads = baseHeadingSet(baseContent);
-  const kept = [];
-
-  for (const section of sections) {
-    const key = normalizeHeading(section.title);
-    if (!key) {
-      if (!preambleDuplicatesBase(section.body, baseContent)) {
-        kept.push(section.body);
-      }
-      continue;
-    }
-    if (!isPackageHeading(key, baseHeads)) {
-      kept.push(`## ${section.title}\n\n${section.body}`.trim());
-    }
-  }
-
-  let intro = "";
-  if (h1) {
-    const firstLine = h1.split("\n")[0].trim();
-    const title = firstLine.replace(/^#\s+/, "");
-    if (isStockConcordeH1(title) && /[()]/.test(title)) {
-      intro = firstLine;
-    } else if (!isStockConcordeH1(title)) {
-      intro = firstLine;
-    }
+  for (const [name, from] of installed) {
+    const to = path.join(dest, name);
+    removePath(to);
+    copyDir(from, to);
   }
-
-  return [intro, ...kept].filter(Boolean).join("\n\n").trim();
-}
-
-export function buildManagedAgents(baseContent, overlayContent) {
-  const parts = [baseContent.trim()];
-  if (overlayContent?.trim()) {
-    parts.push(overlayContent.trim());
-  }
-  return parts.join("\n\n---\n\n");
+  return [...installed.keys()].sort();
 }
 
 /**
- * Build final AGENTS.md. Never stacks managed (post-marker) content.
- * @returns {{ markdown: string, warnings: string[] }}
+ * Link each skill from the agent-specific folders to `.agents/skills/<name>`.
+ * Skips a folder that already resolves to `.agents/skills` (whole-dir symlink).
+ * Replaces earlier links, and copies of package skills (`packageNames`); never
+ * overwrites a project's own skill of the same name. Falls back to a copy when
+ * symlinks are not allowed.
+ * @returns {Array<{ dir: string, mode: "linked" | "copied" | "shared" }>}
  */
-export function buildAgentsFile({
-  existing = "",
-  baseContent,
-  overlayContent = "",
-  mergeAgents: merge = false,
-  forceAgents: force = false,
-}) {
-  const warnings = [];
-  const combined = buildManagedAgents(baseContent, overlayContent);
-
-  // Destructive replace: ignore any existing project content
-  if (force && !existing.replace(/\r\n/g, "\n").includes(AGENTS_MARKER)) {
-    return {markdown: `${combined}\n`, warnings};
-  }
-
-  let preamble = "";
-  const existingText = existing.replace(/\r\n/g, "\n");
-
-  if (existingText.includes(AGENTS_MARKER)) {
-    preamble = existingText.split(AGENTS_MARKER)[0].trimEnd();
-  } else if (merge && existingText.trim()) {
-    preamble = existingText.trimEnd();
-  }
-
-  const hadMarker = existingText.includes(AGENTS_MARKER);
-
-  if (preamble) {
-    const before = preamble;
-    preamble = slimPreamble(preamble, baseContent);
-    if (before.trim() && !preamble) {
-      warnings.push(
-        "AGENTS.md preamble duplicated Concorde ai/AGENTS.md — dropped. Put project-only notes in overlay AGENTS.concorde.md (or a short preamble before <!-- concorde-ai -->).",
-      );
-    } else if (before.trim() && preamble !== before.trim()) {
-      warnings.push(
-        "AGENTS.md preamble slimmed: removed sections that duplicate package AGENTS.md.",
-      );
+export function linkSkills(
+  projectRoot,
+  names,
+  {packageNames = [], linkDirs = SKILL_LINK_DIRS} = {},
+) {
+  const source = path.join(projectRoot, SKILLS_DIR);
+  const sourceReal = fs.realpathSync(source);
+  const results = [];
+
+  for (const linkDir of linkDirs) {
+    const dir = path.join(projectRoot, linkDir);
+    if (fs.existsSync(dir) && fs.realpathSync(dir) === sourceReal) {
+      results.push({dir: linkDir, mode: "shared"});
+      continue;
     }
+    fs.mkdirSync(dir, {recursive: true});
+    let mode = "linked";
+    for (const name of names) {
+      const target = path.join(dir, name);
+      if (pathExists(target)) {
+        const owned = isSymlink(target) || packageNames.includes(name);
+        if (!owned) continue;
+        removePath(target);
+      }
+      try {
+        fs.symlinkSync(path.relative(dir, path.join(source, name)), target, "dir");
+      } catch {
+        copyDir(path.join(source, name), target);
+        mode = "copied";
+      }
+    }
+    results.push({dir: linkDir, mode});
   }
-
-  // Always emit the marker when refreshing a marked file or merging a preamble,
-  // so re-runs stay idempotent even if the preamble was fully dropped.
-  const emitMarker = hadMarker || Boolean(preamble) || merge;
-  const markdown = emitMarker
-    ? preamble
-      ? `${preamble.trimEnd()}\n\n${AGENTS_MARKER}\n\n${combined}\n`
-      : `${AGENTS_MARKER}\n\n${combined}\n`
-    : `${combined}\n`;
-
-  return {markdown, warnings};
-}
-
-export function mergeAgentsFile(targetPath, baseContent, overlayContent, options = {}) {
-  const merge = options.mergeAgents ?? false;
-  const force = options.forceAgents ?? false;
-  let existing = "";
-  if (fs.existsSync(targetPath)) {
-    existing = fs.readFileSync(targetPath, "utf8");
-  }
-
-  const {markdown, warnings} = buildAgentsFile({
-    existing,
-    baseContent,
-    overlayContent,
-    mergeAgents: merge,
-    forceAgents: force,
-  });
-
-  fs.mkdirSync(path.dirname(targetPath), {recursive: true});
-  fs.writeFileSync(targetPath, markdown);
-  return warnings;
+  return results;
 }
 
 function main() {
@@ -385,96 +179,27 @@ function main() {
   console.log(`  source: ${concordeAi}`);
   if (overlayDir) console.log(`  overlay: ${overlayDir}`);
 
-  if (installCursor) {
-    copyDir(
-      path.join(concordeAi, "cursor", "rules"),
-      path.join(projectRoot, ".cursor", "rules"),
-    );
-    copyDir(
-      path.join(concordeAi, "skills"),
-      path.join(projectRoot, ".cursor", "skills"),
-    );
-
-    if (overlayDir) {
-      copyDir(
-        path.join(overlayDir, "cursor", "rules"),
-        path.join(projectRoot, ".cursor", "rules"),
-      );
-      copyDir(
-        path.join(overlayDir, "skills"),
-        path.join(projectRoot, ".cursor", "skills"),
-      );
-    }
-  }
-
-  if (installJetbrains) {
-    copyDir(
-      path.join(concordeAi, "jetbrains", "rules"),
-      path.join(projectRoot, ".aiassistant", "rules"),
-    );
-
-    if (overlayDir) {
-      copyDir(
-        path.join(overlayDir, "jetbrains", "rules"),
-        path.join(projectRoot, ".aiassistant", "rules"),
-      );
-    }
-  }
-
-  const agentsPath = path.join(projectRoot, "AGENTS.md");
-  let existingAgents = "";
-  if (fs.existsSync(agentsPath)) {
-    existingAgents = fs.readFileSync(agentsPath, "utf8");
-  }
-
-  const action = decideAgentsAction({
-    existingText: existingAgents,
-    skipAgents,
-    mergeAgents,
-    forceAgents,
-  });
-
-  if (action === "skip") {
-    if (skipAgents) {
-      console.log("  ⊘ AGENTS.md skipped (--skip-agents)");
-    } else if (existingAgents.trim()) {
-      console.log(
-        "  ⊘ AGENTS.md left untouched (project-owned, no <!-- concorde-ai --> marker).",
-      );
-      console.log(
-        "    Use --merge-agents to append a Concorde block, or --force-agents to replace.",
-      );
-    } else {
-      console.log("  ⊘ AGENTS.md skipped");
-    }
-  } else {
-    const baseAgents = fs.readFileSync(path.join(concordeAi, "AGENTS.md"), "utf8");
-    const {content: overlayAgents, warnings: overlayWarnings} =
-      readOverlayAgents(overlayDir);
-
-    const warnings = [
-      ...overlayWarnings,
-      ...mergeAgentsFile(agentsPath, baseAgents, overlayAgents, {
-        mergeAgents: action === "merge" || action === "refresh",
-        forceAgents: action === "force",
-      }),
-    ];
-    for (const w of warnings) {
-      console.warn(`  ⚠ ${w}`);
+  const packageSkills = path.join(concordeAi, "skills");
+  const skillNames = syncSkills(projectRoot, [
+    packageSkills,
+    ...(overlayDir ? [path.join(overlayDir, "skills")] : []),
+  ]);
+  console.log(`  ✓ ${SKILLS_DIR} (${skillNames.join(", ")})`);
+
+  if (!noLinks) {
+    for (const {dir, mode} of linkSkills(projectRoot, skillNames, {
+      packageNames: listSkillNames(packageSkills),
+    })) {
+      const label =
+        mode === "shared"
+          ? `already points to ${SKILLS_DIR}`
+          : mode === "copied"
+            ? "copied (symlinks not allowed here)"
+            : "linked";
+      console.log(`  ✓ ${dir} (${label})`);
     }
-    const label =
-      action === "create"
-        ? "created"
-        : action === "merge"
-          ? "merged"
-          : action === "force"
-            ? "replaced (--force-agents)"
-            : "refreshed";
-    console.log(`  ✓ AGENTS.md (${label})`);
   }
 
-  if (installCursor) console.log("  ✓ .cursor/skills + .cursor/rules");
-  if (installJetbrains) console.log("  ✓ .aiassistant/rules");
   console.log("Done.");
 }