@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/scripts/ai-init.test.mjs

@@ -3,257 +3,99 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
-import {
-  buildAgentsFile,
-  decideAgentsAction,
-  preambleDuplicatesBase,
-  readOverlayAgents,
-  slimPreamble,
-} from "./ai-init.mjs";
+import {SKILLS_DIR, linkSkills, syncSkills} from "./ai-init.mjs";
 
-const base = `# Agents — Concorde
+async function makeSkill(dir, name, body = "x") {
+  await fs.mkdir(path.join(dir, name), {recursive: true});
+  await fs.writeFile(path.join(dir, name, "SKILL.md"), `---\nname: ${name}\n---\n${body}\n`);
+}
 
-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,
+async function withProject(fn) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "concorde-skills-"));
+  try {
+    await fn(root);
+  } finally {
+    await fs.rm(root, {recursive: true, force: true});
+  }
+}
+
+test("syncSkills copies a skill with its rules/ folder into .agents/skills", async () => {
+  await withProject(async (root) => {
+    const pkg = path.join(root, "pkg");
+    await makeSkill(pkg, "concorde");
+    await fs.mkdir(path.join(pkg, "concorde", "rules"));
+    await fs.writeFile(path.join(pkg, "concorde", "rules", "data.md"), "# Data\n");
+    assert.deepEqual(syncSkills(path.join(root, "app"), [pkg]), ["concorde"]);
+    const rule = path.join(root, "app", SKILLS_DIR, "concorde", "rules", "data.md");
+    assert.equal(await fs.readFile(rule, "utf8"), "# Data\n");
   });
-  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: "",
+test("syncSkills replaces its own skill and keeps project skills", async () => {
+  await withProject(async (root) => {
+    const pkg = path.join(root, "pkg");
+    const app = path.join(root, "app");
+    const installed = path.join(app, SKILLS_DIR);
+    await makeSkill(pkg, "concorde");
+    await makeSkill(installed, "concorde", "old copy");
+    await makeSkill(installed, "concorde-docs", "project");
+    syncSkills(app, [pkg]);
+    assert.deepEqual((await fs.readdir(installed)).sort(), ["concorde", "concorde-docs"]);
+    assert.doesNotMatch(
+      await fs.readFile(path.join(installed, "concorde", "SKILL.md"), "utf8"),
+      /old copy/,
+    );
+    assert.match(
+      await fs.readFile(path.join(installed, "concorde-docs", "SKILL.md"), "utf8"),
+      /project/,
+    );
   });
-  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,
+test("linkSkills links each skill from .claude and .junie", async () => {
+  await withProject(async (root) => {
+    await makeSkill(path.join(root, SKILLS_DIR), "concorde");
+    const results = linkSkills(root, ["concorde"]);
+    assert.deepEqual(
+      results.map((r) => r.mode),
+      ["linked", "linked"],
+    );
+    for (const dir of [".claude/skills", ".junie/skills"]) {
+      const link = path.join(root, dir, "concorde");
+      assert.ok((await fs.lstat(link)).isSymbolicLink(), `${dir} not a symlink`);
+      assert.equal(await fs.readlink(link), path.join("..", "..", SKILLS_DIR, "concorde"));
+      assert.match(await fs.readFile(path.join(link, "SKILL.md"), "utf8"), /concorde/);
+    }
   });
-  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,
+test("linkSkills keeps project skills and whole-folder links", async () => {
+  await withProject(async (root) => {
+    await makeSkill(path.join(root, SKILLS_DIR), "concorde");
+    await makeSkill(path.join(root, SKILLS_DIR), "my-skill");
+    // .claude/skills is already a symlink to .agents/skills (this repo's layout)
+    await fs.mkdir(path.join(root, ".claude"), {recursive: true});
+    await fs.symlink(path.join("..", SKILLS_DIR), path.join(root, ".claude/skills"));
+    // .junie has its own skill with the same name as an overlay skill
+    await makeSkill(path.join(root, ".junie/skills"), "my-skill", "junie own");
+
+    const results = linkSkills(root, ["concorde", "my-skill"], {packageNames: ["concorde"]});
+    assert.equal(results.find((r) => r.dir === ".claude/skills").mode, "shared");
+    assert.ok((await fs.lstat(path.join(root, ".claude/skills"))).isSymbolicLink());
+    const own = path.join(root, ".junie/skills/my-skill");
+    assert.ok(!(await fs.lstat(own)).isSymbolicLink());
+    assert.match(await fs.readFile(path.join(own, "SKILL.md"), "utf8"), /junie own/);
+    assert.ok((await fs.lstat(path.join(root, ".junie/skills/concorde"))).isSymbolicLink());
   });
-
-  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/);
-});
-
-test("readOverlayAgents: prefers AGENTS.concorde.md", async () => {
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "concorde-overlay-"));
-  try {
-    await fs.writeFile(
-      path.join(dir, "AGENTS.concorde.md"),
-      "# overlay preferred\n",
-    );
-    await fs.writeFile(
-      path.join(dir, "AGENTS.starter.md"),
-      "# overlay legacy\n",
-    );
-    const {content, warnings} = readOverlayAgents(dir);
-    assert.match(content, /overlay preferred/);
-    assert.equal(warnings.length, 0);
-  } finally {
-    await fs.rm(dir, {recursive: true, force: true});
-  }
 });
 
-test("readOverlayAgents: falls back to AGENTS.starter.md with warning", async () => {
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "concorde-overlay-"));
-  try {
-    await fs.writeFile(
-      path.join(dir, "AGENTS.starter.md"),
-      "# overlay legacy\n",
-    );
-    const {content, warnings} = readOverlayAgents(dir);
-    assert.match(content, /overlay legacy/);
-    assert.match(warnings[0] ?? "", /deprecated AGENTS\.starter\.md/);
-  } finally {
-    await fs.rm(dir, {recursive: true, force: true});
-  }
-});
-
-test("readOverlayAgents: falls back to AGENTS.overlay.md with warning", async () => {
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "concorde-overlay-"));
-  try {
-    await fs.writeFile(
-      path.join(dir, "AGENTS.overlay.md"),
-      "# overlay mid legacy\n",
-    );
-    const {content, warnings} = readOverlayAgents(dir);
-    assert.match(content, /overlay mid legacy/);
-    assert.match(warnings[0] ?? "", /deprecated AGENTS\.overlay\.md/);
-  } finally {
-    await fs.rm(dir, {recursive: true, force: true});
-  }
+test("linkSkills replaces an earlier copy of a package skill", async () => {
+  await withProject(async (root) => {
+    await makeSkill(path.join(root, SKILLS_DIR), "concorde", "new");
+    await makeSkill(path.join(root, ".junie/skills"), "concorde", "copied before");
+    linkSkills(root, ["concorde"], {packageNames: ["concorde"]});
+    const link = path.join(root, ".junie/skills/concorde");
+    assert.ok((await fs.lstat(link)).isSymbolicLink());
+    assert.match(await fs.readFile(path.join(link, "SKILL.md"), "utf8"), /new/);
+  });
 });

package/scripts/docs-markdown-vite-plugin.ts

@@ -0,0 +1,43 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import type { Connect, Plugin } from "vite";
+import { SITE_PAGE_SLUGS, toSourceId } from "./docs-public-url.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MD_PATH_RE = /^\/((?:docs|core)\/.+\.mdx?)(?:\?|$)/i;
+const SITE_PAGE_MD_RE = new RegExp(
+  `^/(${SITE_PAGE_SLUGS.join("|")})\\.md(?:\\?|$)`,
+);
+
+/**
+ * Dev: serve public `/docs|core/…/*.md` from `src/…` (including underscore
+ * sections and `name/name.md` component pages), and `/about.md` & co. from
+ * `site-pages/`.
+ */
+export function docsMarkdownVitePlugin(): Plugin {
+  return {
+    name: "concorde-docs-markdown",
+    configureServer(server) {
+      server.middlewares.use(((req, res, next) => {
+        const raw = req.url || "";
+        const sitePage = SITE_PAGE_MD_RE.exec(raw);
+        const match = MD_PATH_RE.exec(raw);
+        if (!match && !sitePage) {
+          next();
+          return;
+        }
+        const filePath = sitePage
+          ? path.join(root, "site-pages", `${sitePage[1]}.md`)
+          : path.join(root, "src", `${toSourceId(match![1])}.md`);
+        if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+          next();
+          return;
+        }
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+        fs.createReadStream(filePath).pipe(res);
+      }) as Connect.NextHandleFunction);
+    },
+  };
+}

package/scripts/docs-public-url.mjs

@@ -0,0 +1,56 @@
+/**
+ * Public doc URL ↔ source markdown path (under src/).
+ *
+ * Docs sections are 1:1 with the public path:
+ *   /docs/getting-started/start ↔ docs/getting-started/start.md
+ *
+ * Components collapse the trailing duplicate folder/file name:
+ *   /core/components/ui/button ↔ core/components/ui/button/button.md
+ */
+
+/**
+ * Component markdown whose basename ≠ parent folder (not collapsed in public URLs).
+ * Keep in sync with `find src/core/components -name '*.md'` where dirname ≠ basename.
+ */
+export const COMPONENT_MD_EXCEPTIONS = new Set([
+  "core/components/functional/sdui/sdui-extension-points",
+]);
+
+/**
+ * Root-level site pages (`/about` ↔ `site-pages/about.md`, published as
+ * `/about.md`). Kept outside src/ so they stay out of doc nav and search.
+ */
+export const SITE_PAGE_SLUGS = ["about", "privacy"];
+
+/** Strip leading slash and optional .md/.mdx */
+export function stripMd(rel) {
+  return rel.replace(/^\//, "").replace(/\.mdx?$/i, "");
+}
+
+/** Source-relative id (may include …/name/name for components). */
+export function toSourceId(relOrPublic) {
+  let p = stripMd(relOrPublic);
+
+  if (p.startsWith("core/components/") && !COMPONENT_MD_EXCEPTIONS.has(p)) {
+    const parts = p.split("/");
+    const last = parts[parts.length - 1];
+    if (parts.length >= 2 && parts[parts.length - 2] !== last) {
+      p = `${p}/${last}`;
+    }
+  }
+
+  return p;
+}
+
+/** Public pathname (leading slash, no .md). */
+export function toPublicPath(mdRel) {
+  let p = stripMd(mdRel);
+  // …/name/name → …/name (component index pages)
+  p = p.replace(/\/([^/]+)\/\1$/, "/$1");
+  return `/${p}`;
+}
+
+/** Public path + .md for agent / SPA fetch URL path (no leading slash). */
+export function toPublicMdRel(mdRel) {
+  return `${toPublicPath(mdRel).slice(1)}.md`;
+}

package/scripts/docs.htaccess

@@ -0,0 +1,82 @@
+# Concorde docs — pathname SPA + agent Markdown/HTML
+# Public paths match on-disk docs/… ; components collapse …/name → …/name/name.(md|html)
+# See https://acceptmarkdown.com/recipes/apache (Option A, pragmatic)
+
+DirectoryIndex index.html
+# Component folders exist on disk (…/button/button.md); do not force a trailing
+# slash on the pretty URL /…/button (that would break SPA + Accept negotiation).
+DirectorySlash Off
+
+RewriteEngine On
+
+# Pretty component URLs: drop a trailing slash if the client added one
+RewriteRule ^(core/components/.+)/$ /$1 [R=301,L]
+
+# Homepage: Accept: text/markdown → index.md
+RewriteCond %{HTTP:Accept} "text/markdown" [NC]
+RewriteCond %{HTTP:Accept} !"text/markdown\s*;\s*q\s*=\s*0(\.0+)?(\s*,|$)" [NC]
+RewriteRule ^/?$ index.md [END]
+
+# --- Site pages: /about, /privacy (SPA shell with inline content + .md) ---
+RewriteRule ^(about|privacy)/$ /$1 [R=301,L]
+RewriteCond %{HTTP:Accept} "text/markdown" [NC]
+RewriteCond %{HTTP:Accept} !"text/markdown\s*;\s*q\s*=\s*0(\.0+)?(\s*,|$)" [NC]
+RewriteRule ^(about|privacy)$ /$1.md [END]
+RewriteRule ^(about|privacy)$ /$1.html [END]
+
+# --- Components: /…/button(.md|.html) → /…/button/button.(md|html) ---
+RewriteCond %{DOCUMENT_ROOT}/$1/$2/$2.md -f
+RewriteRule ^(core/components/.+)/([^/]+)\.md$ /$1/$2/$2.md [END]
+RewriteCond %{DOCUMENT_ROOT}/$1/$2/$2.html -f
+RewriteRule ^(core/components/.+)/([^/]+)\.html$ /$1/$2/$2.html [END]
+
+# --- Accept: text/markdown → sibling .md (docs paths are 1:1; components collapse) ---
+RewriteCond %{REQUEST_URI} !\.(mdx?|html)$ [NC]
+RewriteCond %{HTTP:Accept} "text/markdown" [NC]
+RewriteCond %{HTTP:Accept} !"text/markdown\s*;\s*q\s*=\s*0(\.0+)?(\s*,|$)" [NC]
+RewriteCond %{DOCUMENT_ROOT}/$1/$2/$2.md -f
+RewriteRule ^(core/components/.+)/([^/]+)$ /$1/$2/$2.md [END]
+
+RewriteCond %{REQUEST_URI} !\.(mdx?|html)$ [NC]
+RewriteCond %{HTTP:Accept} "text/markdown" [NC]
+RewriteCond %{HTTP:Accept} !"text/markdown\s*;\s*q\s*=\s*0(\.0+)?(\s*,|$)" [NC]
+RewriteCond %{DOCUMENT_ROOT}/$1.md -f
+RewriteRule ^((?:docs|core)/.+)$ /$1.md [END]
+
+# --- Known crawlers → static HTML ---
+RewriteCond %{REQUEST_URI} !\.(mdx?|html)$ [NC]
+RewriteCond %{HTTP_USER_AGENT} (bot|crawler|spider|slurp|GPTBot|Claude|anthropic|Bytespider|Applebot|bingbot|Googlebot|DuckDuckBot|YandexBot|Baiduspider|facebookexternalhit|LinkedInBot|Twitterbot|SemrushBot|AhrefsBot|PetalBot|CCBot|meta-externalagent|OAI-SearchBot|Perplexity|Diffbot|ia_archiver) [NC]
+RewriteCond %{DOCUMENT_ROOT}/$1/$2/$2.html -f
+RewriteRule ^(core/components/.+)/([^/]+)$ /$1/$2/$2.html [END]
+
+RewriteCond %{REQUEST_URI} !\.(mdx?|html)$ [NC]
+RewriteCond %{HTTP_USER_AGENT} (bot|crawler|spider|slurp|GPTBot|Claude|anthropic|Bytespider|Applebot|bingbot|Googlebot|DuckDuckBot|YandexBot|Baiduspider|facebookexternalhit|LinkedInBot|Twitterbot|SemrushBot|AhrefsBot|PetalBot|CCBot|meta-externalagent|OAI-SearchBot|Perplexity|Diffbot|ia_archiver) [NC]
+RewriteCond %{DOCUMENT_ROOT}/$1.html -f
+RewriteRule ^((?:docs|core)/.+)$ /$1.html [END]
+
+# Hubs are static files only
+RewriteCond %{DOCUMENT_ROOT}/hubs/$1.html -f
+RewriteRule ^hubs/([^/]+)/?$ /hubs/$1.html [END]
+
+# SPA pushState (allow when path matches an on-disk dir such as …/button/)
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteRule ^(?:docs|core)/ index.html [END]
+
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{HTTP:Accept} "text/markdown" [NC]
+RewriteCond %{HTTP:Accept} !"text/markdown\s*;\s*q\s*=\s*0(\.0+)?(\s*,|$)" [NC]
+RewriteRule ^ - [R=404,L]
+
+ErrorDocument 404 /404.md
+
+<IfModule mod_headers.c>
+  Header merge Vary Accept
+</IfModule>
+
+<FilesMatch "\.md$">
+  ForceType text/markdown
+  <IfModule mod_headers.c>
+    Header set Content-Type "text/markdown; charset=utf-8"
+    Header merge Vary Accept
+  </IfModule>
+</FilesMatch>