@supersoniks/concorde 4.6.0 → 4.7.0

package/scripts/ai-init.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * Installe les fichiers agent IA Concorde dans un projet.
+ *
+ * Usage:
+ *   node node_modules/@supersoniks/concorde/scripts/ai-init.mjs [options]
+ *   yarn concorde 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
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+
+function readArg(name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+const flags = new Set(args.filter((a) => a.startsWith("--") && !a.includes("=")));
+
+const projectRoot = path.resolve(readArg("--project-root") ?? process.cwd());
+const overlayDir = readArg("--overlay")
+  ? path.resolve(readArg("--overlay"))
+  : undefined;
+
+const cursorOnly = flags.has("--cursor-only");
+const jetbrainsOnly = flags.has("--jetbrains-only");
+const mergeAgents = flags.has("--merge-agents");
+const installCursor = !jetbrainsOnly;
+const installJetbrains = !cursorOnly;
+
+function detectConcordeAi() {
+  const explicit = readArg("--concorde-ai");
+  if (explicit) return path.resolve(explicit);
+  const fromScript = path.resolve(__dirname, "../ai");
+  if (fs.existsSync(fromScript)) return fromScript;
+  const fromNodeModules = path.resolve(
+    projectRoot,
+    "node_modules/@supersoniks/concorde/ai",
+  );
+  if (fs.existsSync(fromNodeModules)) return fromNodeModules;
+  throw new Error(
+    "Dossier ai/ Concorde introuvable. Passez --concorde-ai <chemin>.",
+  );
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, {recursive: true});
+  for (const entry of fs.readdirSync(src, {withFileTypes: true})) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(from, to);
+    } else {
+      fs.mkdirSync(path.dirname(to), {recursive: true});
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function mergeAgentsFile(targetPath, baseContent, overlayContent) {
+  const marker = "<!-- concorde-ai -->";
+  let existing = "";
+  if (fs.existsSync(targetPath)) {
+    existing = fs.readFileSync(targetPath, "utf8");
+  }
+
+  const parts = [baseContent.trim()];
+  if (overlayContent?.trim()) {
+    parts.push(overlayContent.trim());
+  }
+
+  const combined = parts.join("\n\n---\n\n");
+
+  if (!existing) {
+    fs.mkdirSync(path.dirname(targetPath), {recursive: true});
+    fs.writeFileSync(targetPath, combined + "\n");
+    return;
+  }
+
+  if (existing.includes(marker)) {
+    const before = existing.split(marker)[0].trimEnd();
+    fs.writeFileSync(targetPath, `${before}\n\n${marker}\n\n${combined}\n`);
+    return;
+  }
+
+  if (mergeAgents) {
+    fs.writeFileSync(
+      targetPath,
+      `${existing.trimEnd()}\n\n---\n\n${marker}\n\n${combined}\n`,
+    );
+    return;
+  }
+
+  fs.writeFileSync(targetPath, combined + "\n");
+}
+
+const concordeAi = detectConcordeAi();
+
+console.log(`Concorde ai-init → ${projectRoot}`);
+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 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");
+  }
+}
+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.");

package/scripts/docs-mock-api-vite-plugin.ts

@@ -0,0 +1,116 @@
+import * as esbuild from "esbuild";
+import fs from "fs";
+import path from "path";
+import {fileURLToPath} from "url";
+import type {IncomingMessage} from "node:http";
+import type {Connect, Plugin} from "vite";
+import {handleDocsMockApiRequest} from "../src/docs/mock-api/router";
+
+function readNodeRequestBody(req: IncomingMessage): Promise<Buffer | undefined> {
+  return new Promise((resolve, reject) => {
+    const method = req.method?.toUpperCase() ?? "GET";
+    if (method === "GET" || method === "HEAD") {
+      resolve(undefined);
+      return;
+    }
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk) => chunks.push(chunk as Buffer));
+    req.on("end", () => resolve(chunks.length ? Buffer.concat(chunks) : undefined));
+    req.on("error", reject);
+  });
+}
+
+/** HTTP/2 pseudo-headers (`:method`, …) and other invalid names must not reach `Headers`. */
+function isValidFetchHeaderName(name: string): boolean {
+  if (!name || name.startsWith(":")) return false;
+  return /^[\^_`a-zA-Z\-0-9!#$%&'*+.|~]+$/.test(name);
+}
+
+function nodeHeadersToFetchHeaders(req: IncomingMessage): Headers {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value == null || !isValidFetchHeaderName(key)) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) headers.append(key, v);
+    } else {
+      headers.set(key, value);
+    }
+  }
+  return headers;
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, "..");
+const swEntry = path.join(root, "src/docs/mock-api/service-worker.ts");
+async function buildDocsMockApiServiceWorker(): Promise<void> {
+  await esbuild.build({
+    entryPoints: [swEntry],
+    outfile: path.join(root, "public/docs-mock-api-sw.js"),
+    bundle: true,
+    format: "iife",
+    platform: "browser",
+    target: "es2020",
+    minify: false,
+    sourcemap: true,
+    logLevel: "silent",
+  });
+}
+
+export function docsMockApiVitePlugin(): Plugin {
+  const middleware: Connect.NextHandleFunction = async (req, res, next) => {
+    const rawUrl = req.url?.split("?")[0] ?? "";
+    if (!rawUrl.startsWith("/docs-mock-api")) {
+      return next();
+    }
+
+    const proto =
+      (req.headers["x-forwarded-proto"] as string | undefined) ?? "http";
+    const host = req.headers.host ?? "localhost";
+    const body = await readNodeRequestBody(req);
+    const init: RequestInit = {
+      method: req.method ?? "GET",
+      headers: nodeHeadersToFetchHeaders(req),
+    };
+    if (body?.length) {
+      init.body = new Uint8Array(body);
+    }
+    const request = new Request(
+      new URL(req.url!, `${proto}://${host}`),
+      init,
+    );
+
+    try {
+      const response = await handleDocsMockApiRequest(request);
+      if (!response) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({error: "Not handled", path: rawUrl}));
+        return;
+      }
+
+      res.statusCode = response.status;
+      response.headers.forEach((value, key) => {
+        if (key.toLowerCase() === "content-length") return;
+        res.setHeader(key, value);
+      });
+      res.end(Buffer.from(await response.arrayBuffer()));
+    } catch (err) {
+      console.error("[docs-mock-api] middleware error", err);
+      next();
+    }
+  };
+
+  return {
+    name: "concorde-docs-mock-api",
+    async buildStart() {
+      await buildDocsMockApiServiceWorker();
+    },
+    configureServer(server) {
+      // Avant le fallback SPA Vite (configureServer synchrone, pas le callback)
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}

package/scripts/docs-open-in-editor-plugin.ts

@@ -0,0 +1,130 @@
+import { execSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Connect, Plugin } from "vite";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, "..");
+
+const OPEN_PREFIX = "/__docs/open";
+
+/** Paths allowed for ↗ source links (demo / mock API sources only). */
+export function isDocsSourcePathAllowed(relPath: string): boolean {
+  const normalized = path.normalize(relPath).replace(/\\/g, "/");
+  if (normalized.startsWith("..") || path.isAbsolute(normalized)) return false;
+
+  if (normalized.startsWith("src/docs/example/")) return true;
+  if (normalized.startsWith("src/docs/mock-api/")) return true;
+  if (/^src\/core\/components\/functional\/[^/]+\/[^/]+\.demo\.ts$/.test(normalized)) {
+    return true;
+  }
+  const functionalImpl = new Set([
+    "src/core/components/functional/queue/queue.ts",
+    "src/core/components/functional/list/list.ts",
+  ]);
+  if (functionalImpl.has(normalized)) return true;
+
+  return false;
+}
+
+export function isEditorAvailable(): boolean {
+  const editor = process.env.DOCS_EDITOR ?? process.env.STARTER_EDITOR ?? "cursor";
+  try {
+    execSync(`${editor} --version`, { stdio: "pipe", timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function openInEditor(absPath: string, line: number, column: number): void {
+  const editor = process.env.DOCS_EDITOR ?? process.env.STARTER_EDITOR ?? "cursor";
+  const goto = `${absPath}:${line}:${column}`;
+  const args = process.env.DOCS_EDITOR_ARGS
+    ? [...process.env.DOCS_EDITOR_ARGS.split(/\s+/), goto, projectRoot]
+    : ["-r", "-g", goto, projectRoot];
+
+  const child = spawn(editor, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+/**
+ * Dev middleware: open doc demo sources in Cursor (`cursor -r -g`).
+ * Only paths under src/docs/example/, src/docs/mock-api/, or *.demo.ts in functional/.
+ */
+export function docsOpenInEditorPlugin(): Plugin {
+  let editorAvailable = false;
+
+  const middleware: Connect.NextHandleFunction = (req, res, next) => {
+    if (!req.url || req.method !== "GET" || !req.url.startsWith(OPEN_PREFIX)) {
+      return next();
+    }
+
+    if (!editorAvailable) {
+      res.statusCode = 503;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Editor not available");
+      return;
+    }
+
+    try {
+      const url = new URL(req.url, "http://localhost");
+      const relPath = url.searchParams.get("path") ?? "";
+      const line = Math.max(1, Number(url.searchParams.get("line") ?? "1") || 1);
+      const column = Math.max(
+        1,
+        Number(url.searchParams.get("column") ?? "1") || 1,
+      );
+
+      if (!relPath || !isDocsSourcePathAllowed(relPath)) {
+        res.statusCode = 403;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Forbidden");
+        return;
+      }
+
+      const absPath = path.resolve(projectRoot, relPath);
+      if (!fs.existsSync(absPath)) {
+        res.statusCode = 404;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("Not found");
+        return;
+      }
+
+      openInEditor(absPath, line, column);
+      res.statusCode = 204;
+      res.end();
+    } catch {
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("Error");
+    }
+  };
+
+  return {
+    name: "concorde-docs-open-in-editor",
+    config() {
+      editorAvailable = isEditorAvailable();
+      if (!editorAvailable) {
+        console.log(
+          "[docs] ↗ source links hidden — Cursor CLI not found (Command Palette → Install 'cursor' command)",
+        );
+      }
+      return {
+        define: {
+          __DOCS_EDITOR_AVAILABLE__: JSON.stringify(editorAvailable),
+        },
+      };
+    },
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}

package/scripts/pre-publish.mjs

@@ -4,7 +4,8 @@ import fs from "fs";
 const requiredFiles = [
   'concorde-core.bundle.js',
   'concorde-core.es.js',
-  // Ajoute ici les autres fichiers que tu veux vérifier
+  'ai/AGENTS.md',
+  'scripts/ai-init.mjs',
 ];
 
 let allFilesExist = true;

package/src/core/components/functional/example/example.ts

@@ -9,7 +9,7 @@ import {
   ApiGetResult,
 } from "@supersoniks/concorde/decorators";
 
-/** Same API as the queue demo: https://geo.api.gouv.fr/ */
+/** Same API as the queue demo: /docs-mock-api/geo/ */
 type City = { nom: string; code: string };
 
 const endpoint = new Endpoint<City[], { limit: number }>(

package/src/core/components/functional/fetch/fetch.md

@@ -1,6 +1,8 @@
 # Fetch
-The **sonic-fetch** component is used to request and store data from an API.
-Fetch extends the mixins Fetcher and [Subscriber](#docs/_core-concept/subscriber.md/subscriber)
+
+> **New apps:** prefer [@get](#docs/_decorators/get.md/get) for a typed GET on a component, or [List](#core/components/functional/list/list.md/list) / [Queue](#core/components/functional/queue/queue.md/queue) with `fetch` for collections. Use [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) (`serviceURL="/docs-mock-api"`) to try examples offline.
+
+The **sonic-fetch** component requests and stores API data. It extends the Fetcher and [Subscriber](#docs/_core-concept/subscriber.md/subscriber) mixins.
 
 
 
@@ -9,7 +11,7 @@ Fetch extends the mixins Fetcher and [Subscriber](#docs/_core-concept/subscriber
 ## Basic usage
 In order to work properly the <b>sonic-fetch</b> component needs at least the following attributes.  
 - **serviceURL** : A base service url. This attribute can be inherited from an ancestor.
-  *ex : https://reqres.in*
+  *ex : /docs-mock-api*
 - **endPoint** : the specific location where requests for information are sent (see the api docs).  
   *ex : api/users | api/users?page=2 | api/users/2*
 - **dataProvider *(Required)*** : An ID that is used as a reference to the object storing the data returned by the API.
@@ -19,7 +21,7 @@ This attribute can be inherited from an ancestor.
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="https://reqres.in" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
     <sonic-button dataProvider="myDataObj" debug>Hover to see the data</sonic-button>
   </template>
 </sonic-code>
@@ -29,7 +31,7 @@ If no **endPoint** is specified it will be filled by the **dataProvider ID** ins
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="https://reqres.in" dataProvider="api/users?page=2" ></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="api/users?page=2" ></sonic-fetch>
     <sonic-button dataProvider="api/users?page=2" debug>Hover to see the data</sonic-button>
   </template>
 </sonic-code>
@@ -46,19 +48,19 @@ For example if the data is `{my:{data:{a:1,b:2}}}` and the key is `key="my.data"
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="https://reqres.in" dataProvider="api/users/2" ></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="api/users/2" ></sonic-fetch>
     <sonic-button dataProvider="api/users/2" debug>dataProvider object</sonic-button>
     <!-- Get the user ID -->
-    <sonic-fetch serviceURL="https://reqres.in" dataProvider="id" endPoint="api/users/2" key="data.id"></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="id" endPoint="api/users/2" key="data.id"></sonic-fetch>
     <sonic-button dataProvider="id" debug>data.id</sonic-button>
     <!-- Get the user First name -->
-    <sonic-fetch serviceURL="https://reqres.in" dataProvider="first_name" endPoint="api/users/2" key="data.first_name"></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="first_name" endPoint="api/users/2" key="data.first_name"></sonic-fetch>
     <sonic-button dataProvider="first_name" debug>data.first_name</sonic-button>
     <!-- Get the user Last name -->
-    <sonic-fetch serviceURL="https://reqres.in" dataProvider="last_name" endPoint="api/users/2" key="data.last_name"></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="last_name" endPoint="api/users/2" key="data.last_name"></sonic-fetch>
     <sonic-button dataProvider="last_name" debug>data.last_name</sonic-button>
     <!-- Get the user email -->
-    <sonic-fetch serviceURL="https://reqres.in" dataProvider="email" endPoint="api/users/2" key="data.email"></sonic-fetch>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="email" endPoint="api/users/2" key="data.email"></sonic-fetch>
     <sonic-button dataProvider="email" debug>data.email</sonic-button>
   </template>
 </sonic-code>
@@ -80,7 +82,7 @@ The noLoader attribute disables display of the default loader
 
 <sonic-code>
   <template>
-    <sonic-fetch noLoader serviceURL="https://reqres.in" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
+    <sonic-fetch noLoader serviceURL="/docs-mock-api" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
     <sonic-button dataProvider="myDataObj" debug>Basic fetch with noLoader attribute</sonic-button>
   </template>
 </sonic-code>

package/src/core/components/functional/if/if.md

@@ -1,16 +1,9 @@
 # if
 
-The **sonic-if** component shows its content based on the value of its reactive property names **condition**
+The **sonic-if** component shows its slot when **`.condition`** is true. In Lit, bind `.condition` from store-driven state (`@subscribe` on a `formDataProvider` field) — live preview and **TypeScript source are the same file** (`docs-lit-demo`):
 
-<sonic-code>
-  <template>
-<div dataProvider="visibilitySettings" formDataProvider="visibilitySettings">
-  <sonic-checkbox label="Show evacuation plan" name="togglePlan" unique checked value="true"></sonic-checkbox>
-  <sonic-if  data-bind ::condition="$togglePlan" class="mt-4 block">
-  <sonic-image src="https://www.thebaron.info/assets/mail/concorde-evacuation.jpg" rounded="md" ratio="654/463"></sonic-image>
-  </sonic-if>
-</div>
-  </template>
-</sonic-code>
+<docs-lit-demo for="docs-toggle-if-demo"></docs-lit-demo>
+
+Plain HTML without Lit: [HTML integration](#docs/_misc/html-integration.md/html-integration).
 
 

package/src/core/components/functional/list/list.demo.ts

@@ -43,13 +43,13 @@ export class ListDemo extends LitElement {
         <h2 class="text-xl font-medium mb-4">Liste des utilisateurs</h2>
         <sonic-list
           fetch
-          serviceurl="https://reqres.in"
+          serviceurl="/docs-mock-api"
           dataprovider="api/users"
           key="data"
           class="grid grid-cols-1 gap-4"
-          items=${this.items}
-          noItems=${this.noItems}
-          skeleton=${this.skeleton}
+          .items=${this.items}
+          .noItems=${this.noItems}
+          .skeleton=${this.skeleton}
           debug
         ></sonic-list>
       </div>