@supersoniks/concorde 4.9.2 → 4.9.4

package/scripts/ai-init.mjs

@@ -1,26 +1,47 @@
 #!/usr/bin/env node
 /**
- * Installe les fichiers agent IA Concorde dans un projet.
+ * Install Concorde AI agent files into a project.
  *
  * Usage:
  *   node node_modules/@supersoniks/concorde/scripts/ai-init.mjs [options]
- *   yarn concorde ai-init
+ *   yarn ai-init
  *
  * Options:
- *   --project-root <dir>   Racine du projet (défaut: cwd)
- *   --concorde-ai <dir>    Dossier ai/ Concorde (défaut: auto-detect)
- *   --overlay <dir>        Couche additionnelle (ex. starter kit)
- *   --cursor-only          N'installe que Cursor (.cursor/)
- *   --jetbrains-only       N'installe que JetBrains (.aiassistant/rules/)
- *   --merge-agents         Fusionne AGENTS.md au lieu d'écraser si existant
+ *   --project-root <dir>   Project root (default: cwd)
+ *   --concorde-ai <dir>    Concorde ai/ folder (default: auto-detect)
+ *   --overlay <dir>        Extra layer (e.g. starter kit) — uses AGENTS.starter.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)
+ *
+ * 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
+ *
+ * Layout when writing:
+ *
+ *   [optional project preamble — short, project-only]
+ *   <!-- concorde-ai -->
+ *   <package ai/AGENTS.md>
+ *   [--- + overlay AGENTS.starter.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.starter.md
+ * for project-specific agent notes (endpoints, dpKeys, …).
  */
 
 import fs from "node:fs";
 import path from "node:path";
-import {fileURLToPath} from "node:url";
+import {fileURLToPath, pathToFileURL} from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const AGENTS_MARKER = "<!-- concorde-ai -->";
+
 const args = process.argv.slice(2);
 
 function readArg(name) {
@@ -38,10 +59,34 @@ const overlayDir = readArg("--overlay")
 
 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";
+}
+
 function detectConcordeAi() {
   const explicit = readArg("--concorde-ai");
   if (explicit) return path.resolve(explicit);
@@ -72,96 +117,337 @@ function copyDir(src, dest) {
   }
 }
 
-function mergeAgentsFile(targetPath, baseContent, overlayContent) {
-  const marker = "<!-- concorde-ai -->";
-  let existing = "";
-  if (fs.existsSync(targetPath)) {
-    existing = fs.readFileSync(targetPath, "utf8");
+function normalizeHeading(title) {
+  return title
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function isStockConcordeH1(title) {
+  // "# Agents — Concorde" with optional project suffix in parentheses
+  return /^agents\s+concorde(\s|$)/i.test(normalizeHeading(title));
+}
+
+/**
+ * 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});
+    }
+  }
+
+  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;
+  }
+  return false;
+}
+
+/**
+ * True when preamble looks like a full (or near-full) copy of package AGENTS.md.
+ */
+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;
+  }
+
+  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;
+    }
   }
 
+  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");
+}
 
-  const combined = parts.join("\n\n---\n\n");
+/**
+ * Build final AGENTS.md. Never stacks managed (post-marker) content.
+ * @returns {{ markdown: string, warnings: string[] }}
+ */
+export function buildAgentsFile({
+  existing = "",
+  baseContent,
+  overlayContent = "",
+  mergeAgents: merge = false,
+  forceAgents: force = false,
+}) {
+  const warnings = [];
+  const combined = buildManagedAgents(baseContent, overlayContent);
 
-  if (!existing) {
-    fs.mkdirSync(path.dirname(targetPath), {recursive: true});
-    fs.writeFileSync(targetPath, combined + "\n");
-    return;
+  // Destructive replace: ignore any existing project content
+  if (force && !existing.replace(/\r\n/g, "\n").includes(AGENTS_MARKER)) {
+    return {markdown: `${combined}\n`, warnings};
   }
 
-  if (existing.includes(marker)) {
-    const before = existing.split(marker)[0].trimEnd();
-    fs.writeFileSync(targetPath, `${before}\n\n${marker}\n\n${combined}\n`);
-    return;
+  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();
   }
 
-  if (mergeAgents) {
-    fs.writeFileSync(
-      targetPath,
-      `${existing.trimEnd()}\n\n---\n\n${marker}\n\n${combined}\n`,
-    );
-    return;
+  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.starter.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.",
+      );
+    }
   }
 
-  fs.writeFileSync(targetPath, combined + "\n");
+  // 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};
 }
 
-const concordeAi = detectConcordeAi();
+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");
+  }
 
-console.log(`Concorde ai-init → ${projectRoot}`);
-console.log(`  source: ${concordeAi}`);
-if (overlayDir) console.log(`  overlay: ${overlayDir}`);
+  const {markdown, warnings} = buildAgentsFile({
+    existing,
+    baseContent,
+    overlayContent,
+    mergeAgents: merge,
+    forceAgents: force,
+  });
 
-if (installCursor) {
-  copyDir(
-    path.join(concordeAi, "cursor", "rules"),
-    path.join(projectRoot, ".cursor", "rules"),
-  );
-  copyDir(
-    path.join(concordeAi, "skills"),
-    path.join(projectRoot, ".cursor", "skills"),
-  );
+  fs.mkdirSync(path.dirname(targetPath), {recursive: true});
+  fs.writeFileSync(targetPath, markdown);
+  return warnings;
+}
+
+function main() {
+  const concordeAi = detectConcordeAi();
+
+  console.log(`Concorde ai-init → ${projectRoot}`);
+  console.log(`  source: ${concordeAi}`);
+  if (overlayDir) console.log(`  overlay: ${overlayDir}`);
 
-  if (overlayDir) {
+  if (installCursor) {
     copyDir(
-      path.join(overlayDir, "cursor", "rules"),
+      path.join(concordeAi, "cursor", "rules"),
       path.join(projectRoot, ".cursor", "rules"),
     );
     copyDir(
-      path.join(overlayDir, "skills"),
+      path.join(concordeAi, "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, "cursor", "rules"),
+        path.join(projectRoot, ".cursor", "rules"),
+      );
+      copyDir(
+        path.join(overlayDir, "skills"),
+        path.join(projectRoot, ".cursor", "skills"),
+      );
+    }
+  }
 
-  if (overlayDir) {
+  if (installJetbrains) {
     copyDir(
-      path.join(overlayDir, "jetbrains", "rules"),
+      path.join(concordeAi, "jetbrains", "rules"),
       path.join(projectRoot, ".aiassistant", "rules"),
     );
+
+    if (overlayDir) {
+      copyDir(
+        path.join(overlayDir, "jetbrains", "rules"),
+        path.join(projectRoot, ".aiassistant", "rules"),
+      );
+    }
   }
-}
 
-const baseAgents = fs.readFileSync(path.join(concordeAi, "AGENTS.md"), "utf8");
-let overlayAgents = "";
-if (overlayDir) {
-  const overlayPath = path.join(overlayDir, "AGENTS.starter.md");
-  if (fs.existsSync(overlayPath)) {
-    overlayAgents = fs.readFileSync(overlayPath, "utf8");
+  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");
+    let overlayAgents = "";
+    if (overlayDir) {
+      const overlayPath = path.join(overlayDir, "AGENTS.starter.md");
+      if (fs.existsSync(overlayPath)) {
+        overlayAgents = fs.readFileSync(overlayPath, "utf8");
+      }
+    }
+
+    const warnings = mergeAgentsFile(agentsPath, baseAgents, overlayAgents, {
+      mergeAgents: action === "merge" || action === "refresh",
+      forceAgents: action === "force",
+    });
+    for (const w of warnings) {
+      console.warn(`  ⚠ ${w}`);
+    }
+    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.");
 }
-mergeAgentsFile(path.join(projectRoot, "AGENTS.md"), baseAgents, overlayAgents);
 
-console.log("  ✓ AGENTS.md");
-if (installCursor) console.log("  ✓ .cursor/skills + .cursor/rules");
-if (installJetbrains) console.log("  ✓ .aiassistant/rules");
-console.log("Done.");
+const isDirectRun =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isDirectRun) {
+  main();
+}

package/scripts/ai-init.test.mjs

@@ -0,0 +1,206 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  buildAgentsFile,
+  decideAgentsAction,
+  preambleDuplicatesBase,
+  slimPreamble,
+} from "./ai-init.mjs";
+
+const base = `# Agents — Concorde
+
+Guide for Concorde.
+
+## Skills / rules
+
+| File | Role |
+|------|------|
+| \`.cursor/skills/concorde/SKILL.md\` | Patterns |
+
+## Conventions impératives
+
+- Always **DataProvider**
+- No **sonic-fetch**, no **PublisherManager**
+- Forms: **formDataProvider**
+- Skill **concorde-get-set-dp**
+`;
+
+const overlay = `## Conventions (project)
+
+- HTTP routes: \`endpoints.*\`
+`;
+
+test("decideAgentsAction: missing file → create", () => {
+  assert.equal(decideAgentsAction({existingText: ""}), "create");
+});
+
+test("decideAgentsAction: project-owned AGENTS.md → skip by default", () => {
+  assert.equal(
+    decideAgentsAction({existingText: "# Billetterie\n\nProject notes.\n"}),
+    "skip",
+  );
+});
+
+test("decideAgentsAction: --skip-agents always skips", () => {
+  assert.equal(
+    decideAgentsAction({existingText: "", skipAgents: true}),
+    "skip",
+  );
+});
+
+test("decideAgentsAction: --merge-agents on project-owned → merge", () => {
+  assert.equal(
+    decideAgentsAction({
+      existingText: "# Billetterie\n\nNotes.\n",
+      mergeAgents: true,
+    }),
+    "merge",
+  );
+});
+
+test("decideAgentsAction: --force-agents on project-owned → force", () => {
+  assert.equal(
+    decideAgentsAction({
+      existingText: "# Billetterie\n\nNotes.\n",
+      forceAgents: true,
+    }),
+    "force",
+  );
+});
+
+test("decideAgentsAction: marked file → refresh", () => {
+  assert.equal(
+    decideAgentsAction({
+      existingText: "# App\n\n<!-- concorde-ai -->\n\nold\n",
+    }),
+    "refresh",
+  );
+});
+
+test("forceAgents replaces project-owned content", () => {
+  const {markdown} = buildAgentsFile({
+    existing: "# Old project notes\n\nkeep me",
+    baseContent: base,
+    overlayContent: "",
+    forceAgents: true,
+  });
+  assert.equal(markdown.includes("keep me"), false);
+  assert.equal(markdown.includes("<!-- concorde-ai -->"), false);
+  assert.match(markdown, /^# Agents — Concorde/m);
+});
+
+test("without force/merge, buildAgentsFile still builds content (caller decides skip)", () => {
+  const {markdown} = buildAgentsFile({
+    existing: "",
+    baseContent: base,
+    overlayContent: "",
+  });
+  assert.match(markdown, /^# Agents — Concorde/m);
+});
+
+test("merge without marker keeps short unique preamble", () => {
+  const {markdown, warnings} = buildAgentsFile({
+    existing: "# My app\n\nOnly project notes here.\n",
+    baseContent: base,
+    overlayContent: "",
+    mergeAgents: true,
+  });
+  assert.match(markdown, /# My app/);
+  assert.match(markdown, /<!-- concorde-ai -->/);
+  assert.match(markdown, /# Agents — Concorde/);
+  assert.equal(warnings.length, 0);
+});
+
+test("re-run with marker replaces managed zone only (idempotent)", () => {
+  const first = buildAgentsFile({
+    existing: "# My app\n\nNote.\n",
+    baseContent: base,
+    overlayContent: "v1 overlay",
+    mergeAgents: true,
+  }).markdown;
+
+  const second = buildAgentsFile({
+    existing: first.replace("v1 overlay", "STALE"),
+    baseContent: base,
+    overlayContent: "v2 overlay",
+    mergeAgents: true,
+  }).markdown;
+
+  assert.equal(second.includes("STALE"), false);
+  assert.match(second, /v2 overlay/);
+  assert.equal(second.split("<!-- concorde-ai -->").length, 2);
+});
+
+test("duplicate Concorde preamble is dropped", () => {
+  const fork = `${base}\n\nExtra copy of the same guide.\n`;
+  assert.equal(preambleDuplicatesBase(fork, base), true);
+
+  const {markdown, warnings} = buildAgentsFile({
+    existing: `${fork}\n\n<!-- concorde-ai -->\n\nold managed\n`,
+    baseContent: base,
+    overlayContent: overlay,
+    mergeAgents: true,
+  });
+
+  assert.equal(markdown.split("<!-- concorde-ai -->").length, 2);
+  assert.equal(
+    markdown.indexOf("# Agents — Concorde"),
+    markdown.lastIndexOf("# Agents — Concorde"),
+  );
+  assert.match(markdown, /Conventions \(project\)/);
+  assert.ok(warnings.some((w) => /duplicated|slimmed/i.test(w)));
+});
+
+test("slimPreamble keeps unique ## sections", () => {
+  const preamble = `# Agents — Concorde (my-app)
+
+Guide.
+
+## Skills / rules
+
+dup
+
+## Project only
+
+- use endpoints.ts
+`;
+  const slim = slimPreamble(preamble, base);
+  assert.match(slim, /Project only/);
+  assert.equal(slim.includes("## Skills / rules"), false);
+  assert.match(slim, /Concorde \(my-app\)/);
+});
+
+test("slimPreamble drops Skills even when package title has suffix", () => {
+  const packageBase = `# Agents — Concorde
+
+## Skills / rules (après installation)
+
+table
+
+## Conventions impératives
+
+- sonic-fetch
+- PublisherManager
+- formDataProvider
+- concorde-get-set-dp
+`;
+  const preamble = `# Agents — Concorde (app)
+
+## Skills / rules
+
+dup table
+
+## Installation / réinstallation
+
+custom install cmd
+
+## Project endpoints
+
+- endpoints.ts
+`;
+  const slim = slimPreamble(preamble, packageBase);
+  assert.equal(slim.includes("## Skills / rules"), false);
+  assert.match(slim, /Project endpoints/);
+  // Installation may stay if not in package — package has no Installation ##
+  assert.match(slim, /Installation \/ réinstallation|Project endpoints/);
+});