@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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

@@ -2,14 +2,18 @@ import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import type { Connect, Plugin } from "vite";
-import { toSourceId } from "./docs-public-url.mjs";
+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).
+ * sections and `name/name.md` component pages), and `/about.md` & co. from
+ * `site-pages/`.
  */
 export function docsMarkdownVitePlugin(): Plugin {
   return {
@@ -17,13 +21,15 @@ export function docsMarkdownVitePlugin(): Plugin {
     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) {
+        if (!match && !sitePage) {
           next();
           return;
         }
-        const sourceRel = `${toSourceId(match[1])}.md`;
-        const filePath = path.join(root, "src", sourceRel);
+        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;

package/scripts/docs-public-url.mjs

@@ -16,6 +16,12 @@ 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, "");

package/scripts/docs.htaccess

@@ -17,6 +17,13 @@ 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]

package/scripts/generate-cem.mjs

@@ -0,0 +1,244 @@
+/**
+ * Publishes the Custom Elements Manifest (custom-elements.json) at the package
+ * root: the standard machine-readable API of every sonic-* element, for IDEs
+ * and coding agents.
+ *
+ * Starts from the raw analyzer output and:
+ * - fills `tagName` (components use `@customElement(tagName)` with a constant
+ *   the analyzer does not resolve);
+ * - expands string-literal union aliases (`ButtonType` → `"default" | …`) so
+ *   allowed values are visible;
+ * - keeps custom elements and their public API only.
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { extractTagNameFromSource, runCem } from "./generate-sdui-catalog.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+export const CEM_OUT = path.join(ROOT, "custom-elements.json");
+const CEM_CONFIG = path.join(ROOT, "custom-elements-manifest.public.config.mjs");
+const CEM_RAW = path.join(ROOT, ".tmp-cem-public", "custom-elements.json");
+
+const LIFECYCLE = new Set([
+  "render",
+  "connectedCallback",
+  "disconnectedCallback",
+  "attributeChangedCallback",
+  "createRenderRoot",
+  "firstUpdated",
+  "updated",
+  "willUpdate",
+  "shouldUpdate",
+  "update",
+  "getUpdateComplete",
+]);
+
+/**
+ * `export type X = "a" | "b"` aliases made only of string literals.
+ * A name defined twice with different values is left out.
+ * @param {string[]} sources TypeScript source texts
+ * @returns {Map<string, string>} alias name → `"a" | "b"`
+ */
+export function collectLiteralUnions(sources) {
+  const unions = new Map();
+  const conflicts = new Set();
+  const re = /export\s+type\s+([A-Z]\w*)\s*=\s*([^;]+);/g;
+  for (const src of sources) {
+    for (const [, name, body] of src.matchAll(re)) {
+      const parts = body
+        .split("|")
+        .map((p) => p.trim())
+        .filter(Boolean);
+      if (!parts.length || !parts.every((p) => /^(["'])[^"']*\1$/.test(p))) continue;
+      const text = parts.map((p) => `"${p.slice(1, -1)}"`).join(" | ");
+      if (unions.has(name) && unions.get(name) !== text) conflicts.add(name);
+      unions.set(name, text);
+    }
+  }
+  for (const name of conflicts) unions.delete(name);
+  return unions;
+}
+
+/** Replace alias identifiers in a type text by their literal union. */
+export function expandType(text, unions) {
+  if (!text) return text;
+  return text
+    .replace(/\b[A-Z]\w*\b/g, (id) => unions.get(id) ?? id)
+    .replace(/\s+/g, " ")
+    .replace(/^\|\s*/, "")
+    .trim();
+}
+
+/** Names declared with Lit `@property(…)` (fields and accessors) in a source. */
+export function collectLitProperties(source) {
+  const names = new Set();
+  const re =
+    /@property\((?:[^()]|\([^()]*\))*\)\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*(?:(?:declare|readonly|public|override|accessor)\s+)*(?:(?:get|set)\s+)?(\w+)/g;
+  for (const [, name] of source.matchAll(re)) names.add(name);
+  return names;
+}
+
+function withType(entry, unions) {
+  if (!entry?.type?.text) return entry;
+  return { ...entry, type: { ...entry.type, text: expandType(entry.type.text, unions) } };
+}
+
+/**
+ * Public API: Lit properties (with or without attribute) and documented
+ * public methods. Undocumented helpers that merely lack `private` are dropped.
+ */
+function isPublicMember(member, isLitProperty) {
+  if (member.static) return false;
+  if (member.privacy === "private" || member.privacy === "protected") return false;
+  if (member.name.startsWith("_") || member.name.startsWith("#")) return false;
+  if (member.kind === "field") return Boolean(member.attribute) || isLitProperty(member);
+  if (member.kind === "method") return !LIFECYCLE.has(member.name) && Boolean(member.description);
+  return false;
+}
+
+/**
+ * @param {object} raw analyzer manifest
+ * @param {{
+ *   resolveTagName: (modulePath: string) => string | undefined,
+ *   unions: Map<string, string>,
+ *   litProperties: (modulePath: string) => Set<string>,
+ *   exclude?: (modulePath: string) => boolean,
+ * }} options
+ */
+export function buildManifest(raw, { resolveTagName, unions, litProperties, exclude = () => false }) {
+  const byModule = new Map((raw.modules || []).map((m) => [m.path, m]));
+  /** Mixin declaration for `{ name, module | package }` (package paths map to src/). */
+  const resolveMixin = (ref) => {
+    const modulePath =
+      ref.module ??
+      (ref.package?.startsWith("@supersoniks/concorde/")
+        ? `src/${ref.package.slice("@supersoniks/concorde/".length)}.ts`
+        : undefined);
+    const mod = modulePath && byModule.get(modulePath);
+    const decl = mod?.declarations?.find((d) => d.kind === "mixin");
+    return decl ? { decl, modulePath, name: ref.name } : undefined;
+  };
+  /** Own entries first, then each mixin's, skipping names already present. */
+  const withMixins = (d, field) => {
+    const out = [...(d[field] || [])];
+    const seen = new Set(out.map((e) => e.name));
+    for (const ref of d.mixins || []) {
+      const mixin = resolveMixin(ref);
+      for (const entry of mixin?.decl[field] || []) {
+        if (seen.has(entry.name)) continue;
+        seen.add(entry.name);
+        out.push({ ...entry, inheritedFrom: { name: mixin.name, module: mixin.modulePath } });
+      }
+    }
+    return out;
+  };
+  const modules = [];
+  for (const mod of raw.modules || []) {
+    if (exclude(mod.path)) continue;
+    const defined = new Set(
+      (mod.exports || [])
+        .filter((e) => e.kind === "custom-element-definition")
+        .map((e) => e.declaration?.name),
+    );
+    const elements = (mod.declarations || []).filter(
+      (d) => d.kind === "class" && (d.customElement || defined.has(d.name)),
+    );
+    const declarations = [];
+    for (const element of elements) {
+      const tagName = element.tagName || resolveTagName(mod.path);
+      if (!tagName) continue;
+      const d = {
+        ...element,
+        attributes: withMixins(element, "attributes"),
+        members: withMixins(element, "members"),
+      };
+      declarations.push({
+        kind: "class",
+        name: d.name,
+        tagName,
+        customElement: true,
+        ...(d.summary && { summary: d.summary }),
+        ...(d.description && { description: d.description }),
+        ...(d.attributes?.length && {
+          attributes: d.attributes.map((a) => withType(a, unions)),
+        }),
+        ...(d.members?.length && {
+          members: d.members
+            .filter((m) =>
+              isPublicMember(m, (member) =>
+                litProperties(member.inheritedFrom?.module ?? mod.path).has(member.name),
+              ),
+            )
+            .map((m) => withType(m, unions)),
+        }),
+        ...(d.events?.length && { events: d.events }),
+        ...(d.slots?.length && { slots: d.slots }),
+        ...(d.cssProperties?.length && { cssProperties: d.cssProperties }),
+        ...(d.cssParts?.length && { cssParts: d.cssParts }),
+      });
+    }
+    if (!declarations.length) continue;
+    modules.push({
+      kind: "javascript-module",
+      path: mod.path,
+      declarations,
+      exports: declarations.flatMap((d) => [
+        { kind: "js", name: d.name, declaration: { name: d.name, module: mod.path } },
+        {
+          kind: "custom-element-definition",
+          name: d.tagName,
+          declaration: { name: d.name, module: mod.path },
+        },
+      ]),
+    });
+  }
+  modules.sort((a, b) => a.path.localeCompare(b.path));
+  return { schemaVersion: raw.schemaVersion || "1.0.0", readme: "", modules };
+}
+
+function listTsFiles(dir, files = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) listTsFiles(p, files);
+    else if (entry.name.endsWith(".ts") && !/\.(spec|test|demo)\.ts$/.test(entry.name)) {
+      files.push(p);
+    }
+  }
+  return files;
+}
+
+/** Writes custom-elements.json at the package root and returns its path. */
+export function generateCem() {
+  runCem(CEM_CONFIG);
+  const raw = JSON.parse(fs.readFileSync(CEM_RAW, "utf8"));
+  const unions = collectLiteralUnions(
+    listTsFiles(path.join(ROOT, "src/core")).map((f) => fs.readFileSync(f, "utf8")),
+  );
+  const propertyCache = new Map();
+  const manifest = buildManifest(raw, {
+    unions,
+    resolveTagName: (modulePath) => extractTagNameFromSource(path.join(ROOT, modulePath)),
+    litProperties: (modulePath) => {
+      if (!propertyCache.has(modulePath)) {
+        const file = path.join(ROOT, modulePath);
+        propertyCache.set(
+          modulePath,
+          fs.existsSync(file) ? collectLitProperties(fs.readFileSync(file, "utf8")) : new Set(),
+        );
+      }
+      return propertyCache.get(modulePath);
+    },
+    // Copy-paste starter, not a library element
+    exclude: (modulePath) => modulePath.includes("/functional/example/"),
+  });
+  fs.writeFileSync(CEM_OUT, JSON.stringify(manifest, null, 2) + "\n");
+  const count = manifest.modules.reduce((n, m) => n + m.declarations.length, 0);
+  console.log(`✅ custom-elements.json: ${count} elements`);
+  return CEM_OUT;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  generateCem();
+}