@artefact-ci/sdd 0.0.1-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artefact CI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @artefact-ci/sdd
+
+L'installeur de la méthode Artefact CI. Il installe Spec Kit 1.3.2 (via `uvx`), l'extension git, l'extension `artefact-product` et le preset `artefact-sdd`, réapplique les hooks git, génère les fichiers d'agent de l'outil du projet, puis déduit `stack.yml` et écrit la constitution de base. Il ne pose aucune question : il fait, puis affiche un rapport.
+
+## Usage
+
+```sh
+npx @artefact-ci/sdd@X.Y.Z init   [--integration <outil>]
+npx @artefact-ci/sdd@X.Y.Z update
+```
+
+Sans `--source`, l'installeur installe la release GitHub de sa propre version : le preset `artefact-sdd` et l'extension `artefact-product` du tag `vX.Y.Z`. Fixer la version dans la commande (`@X.Y.Z`) fixe donc celle de la méthode.
+
+Pour développer la méthode, `--source` installe en `--dev` depuis un clone :
+
+```sh
+artefact-sdd init   --source <clone de speckit-artefact> [--integration <outil>]
+artefact-sdd update --source <clone de speckit-artefact>
+```
+
+| Option | Rôle |
+| --- | --- |
+| `--source <dir>` | clone de `speckit-artefact` d'où l'extension (`extension/`) et le preset (`preset/`) sont installés en `--dev`, pour développer la méthode. Sans cette option, la release GitHub de la version de l'installeur est installée. |
+| `--integration <outil>` | outil du projet pour `specify init` (`claude` par défaut). Ignoré quand `.specify/` existe : l'intégration du projet est gardée. Ignoré par `update`. |
+| `--help` | affiche l'usage |
+
+Il faut [uv](https://docs.astral.sh/uv/) et Node 24.11 ou plus. Depuis ce dépôt : `pnpm --filter @artefact-ci/sdd build`, puis `node packages/sdd/dist/cli.mjs init --source .` dans le projet.
+
+## Ce que `init` touche
+
+| Étape | Effet |
+| --- | --- |
+| Spec Kit | `specify init --here` si `.specify/` est absent, avec `--force` dès que le dossier n'est pas vide (`.git` compris) |
+| Migration | si le preset `boilerplate` est installé, il est retiré (`specify preset remove boilerplate`) |
+| Composants | extension git, `artefact-product`, `artefact-sdd` ; déjà installés, ils ne sont pas réinstallés (c'est le rôle d'`update`) |
+| Hooks | clé `hooks:` de `.specify/extensions.yml` : les 10 hooks git du boilerplate ; le reste du fichier est gardé |
+| Agents | `.claude/agents/<nom>.md` (Claude Code) et `.agents/agents/<nom>/agent.md` (Antigravity, relecteurs seulement) ; ces fichiers lisent les consignes de `.specify/extensions/artefact-product/agents/` |
+| `stack.yml` | écrit seulement s'il est absent ; déduit de `nx.json`, `next.config.*`, `bun.lock` et du gestionnaire de paquets ; une clé non déduite reste vide avec `# à compléter` |
+| Constitution | `.specify/memory/constitution.md` écrite seulement si elle est absente ou encore le gabarit vierge |
+| Version | `.specify/artefact.json` (voir plus bas) |
+
+Un dossier `docs/agents/` hérité du boilerplate n'est jamais supprimé : le rapport le liste comme obsolète et dit si chaque consigne est identique à celle du boilerplate ou modifiée sur place (à reporter alors dans les docs du projet).
+
+`init` lancé deux fois de suite laisse `git status` vide la deuxième fois.
+
+## La version installée : `.specify/artefact.json`
+
+L'installeur enregistre la version de la méthode installée et sa source dans `.specify/artefact.json`, en JSON indenté de 2 espaces :
+
+```json
+{
+  "version": "0.2.1",
+  "source": "release"
+}
+```
+
+`source` vaut `release` (zips de la release GitHub) ou `dev` (`--source`, la version est alors celle de `preset/preset.yml` du clone). Le fichier ne contient ni date ni chemin. Un fichier illisible ou incomplet arrête `init` et `update` avant toute commande Spec Kit, sans être réécrit.
+
+`init` écrit ce fichier sur un projet neuf (aucun des deux composants installé) et le laisse tel quel quand il donne déjà la même version. Si `.specify/artefact.json` donne une autre version que celle de l'installeur, `init` refuse sans rien installer et renvoie vers `update`, seul à changer de version.
+
+Un projet installé avant ce fichier (phase 4, avec `--source`) a déjà les composants mais pas `.specify/artefact.json` : `init` n'en écrit pas, et son rapport affiche « Version installée inconnue : lance update pour aligner tous les composants ». Lancer `update`, qui réinstalle tout et écrit le fichier.
+
+`update` écrit toujours le fichier, et son rapport donne la version précédente. S'il installe une version plus ancienne que celle enregistrée, il prévient et continue.
+
+## Ce que `update` touche
+
+Il réinstalle l'extension et le preset, puis régénère les fichiers d'agent et réapplique les hooks. Quand `.specify/integration.json` liste plusieurs outils, il lance `specify integration use` pour chaque outil autre que celui par défaut, puis pour l'outil par défaut : Spec Kit n'enregistre les commandes de l'extension et du preset que pour l'outil sélectionné. L'outil par défaut ne change pas, même si un `use` échoue, et les scripts de `.specify/scripts/` gardent leurs droits. Sans `--source`, il les prend dans les zips de la release de sa version : `extension add --from <url du zip> --force` et `preset update artefact-sdd --from <url du zip>`. Avec `--source`, il les prend dans le clone en `--dev` : `extension add --dev … --force` et `preset update artefact-sdd --dev …` (soit un retrait puis un ajout). Si un téléchargement échoue (réseau coupé, version sans release), l'installeur s'arrête en citant l'URL du zip : relancer la même commande une fois le réseau rétabli. `installed_at` change dans les registres de `.specify/` : c'est attendu. Il ne touche jamais `stack.yml` ni la constitution, et s'arrête si `.specify/` est absent.

package/dist/agents.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse, stringify } from 'yaml';
+/** Dossier où Spec Kit installe les consignes des sous-agents (relatif à la racine du projet). */
+export const INSTRUCTIONS_DIR = '.specify/extensions/artefact-product/agents';
+export function readAgentSpecs(root) {
+    const file = join(root, INSTRUCTIONS_DIR, 'agents.yml');
+    if (!existsSync(file)) {
+        throw new Error(`${INSTRUCTIONS_DIR}/agents.yml introuvable dans ${root} : l'extension artefact-product est-elle installée ?`);
+    }
+    const doc = parse(readFileSync(file, 'utf8'));
+    if (!doc || !Array.isArray(doc.agents)) {
+        throw new Error(`${INSTRUCTIONS_DIR}/agents.yml invalide : clé « agents » absente`);
+    }
+    return doc.agents.map((a) => ({ name: a.name, access: a.access, description: a.description }));
+}
+/** Intégrations Spec Kit installées (`.specify/integration.json`) ; [] si le fichier manque. */
+export function readIntegrations(root) {
+    const file = join(root, '.specify', 'integration.json');
+    if (!existsSync(file))
+        return [];
+    const json = JSON.parse(readFileSync(file, 'utf8'));
+    if (Array.isArray(json.installed_integrations))
+        return json.installed_integrations;
+    return json.integration ? [json.integration] : [];
+}
+/** Intégration par défaut de `.specify/integration.json` (`default_integration`, sinon `integration`) ; null si aucune. */
+export function readDefaultIntegration(root) {
+    const file = join(root, '.specify', 'integration.json');
+    if (!existsSync(file))
+        return null;
+    const json = JSON.parse(readFileSync(file, 'utf8'));
+    return json.default_integration ?? json.integration ?? null;
+}
+function body(spec) {
+    const lines = [
+        `Lis \`${INSTRUCTIONS_DIR}/${spec.name}.md\` et applique-le à la lettre : méthode, grille et format du rapport.`,
+    ];
+    lines.push(spec.access === 'read-only'
+        ? "Tu n'as pas écrit ce travail. Ne modifie aucun fichier, ne commite rien. Rends uniquement le rapport."
+        : "Ne commite rien : la commande qui t'a lancé s'en charge après l'accord de l'utilisateur.");
+    return lines.join('\n\n');
+}
+function document(front, spec) {
+    return `---\n${stringify(front, { lineWidth: 0 })}---\n\n${body(spec)}\n`;
+}
+const CLAUDE_TOOLS = {
+    'read-only': 'Read, Grep, Glob, Bash',
+    writes: 'Read, Grep, Glob, Bash, Write, Edit',
+};
+// Antigravity : noms d'outils pris verbatim sur https://antigravity.google/docs/subagents
+// (consulté le 2026-11-10) : view_file, grep_search, run_command (exemple de frontmatter).
+// La doc ne nomme aucun outil pour créer un fichier ni pour lister un dossier (le listing
+// passe par run_command) : les agents `writes` sont donc ignorés sur agy jusqu'à une
+// vérification manuelle. Un nom faux ferait se bloquer le sous-agent.
+const AGY_TOOLS = ['view_file', 'grep_search', 'run_command'];
+const GENERATORS = {
+    claude: {
+        supports: () => true,
+        file: (spec) => ({
+            path: `.claude/agents/${spec.name}.md`,
+            content: document({ name: spec.name, description: spec.description, tools: CLAUDE_TOOLS[spec.access] }, spec),
+        }),
+    },
+    agy: {
+        supports: (spec) => spec.access === 'read-only',
+        file: (spec) => ({
+            path: `.agents/agents/${spec.name}/agent.md`,
+            content: document({
+                name: spec.name,
+                description: spec.description,
+                tools: AGY_TOOLS,
+                commandExecutionPolicy: 'sandbox',
+            }, spec),
+        }),
+    },
+};
+/** Fichiers d'agent d'une intégration ; null si l'outil n'a pas de générateur. Pure. */
+export function agentFiles(integration, specs) {
+    const gen = GENERATORS[integration];
+    if (!gen)
+        return null;
+    return specs.filter(gen.supports).map(gen.file);
+}
+/** Noms des agents sans fichier généré pour cette intégration ([] si inconnue ou complète). */
+export function skippedAgents(integration, specs) {
+    const gen = GENERATORS[integration];
+    if (!gen)
+        return [];
+    return specs.filter((s) => !gen.supports(s)).map((s) => s.name);
+}

package/dist/artefact.mjs

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SetupError } from "./errors.mjs";
+import { writeIfChanged } from "./fs.mjs";
+export const ARTEFACT_JSON = '.specify/artefact.json';
+/** Lit `.specify/artefact.json` ; null si absent, SetupError s'il est illisible ou incomplet. */
+export function readInstalled(root) {
+    const file = join(root, ARTEFACT_JSON);
+    if (!existsSync(file))
+        return null;
+    let json;
+    try {
+        json = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new SetupError(`${ARTEFACT_JSON} illisible : ${e.message}`);
+    }
+    const o = (typeof json === 'object' && json !== null ? json : {});
+    if (typeof o['version'] !== 'string' || o['version'] === '') {
+        throw new SetupError(`${ARTEFACT_JSON} : version manque ou n'est pas une chaîne`);
+    }
+    if (o['source'] !== 'release' && o['source'] !== 'dev') {
+        throw new SetupError(`${ARTEFACT_JSON} : source doit valoir release ou dev`);
+    }
+    return { version: o['version'], source: o['source'] };
+}
+/** Écrit `.specify/artefact.json` ; vrai si le contenu a changé. */
+export function writeInstalled(root, i) {
+    return writeIfChanged(join(root, ARTEFACT_JSON), `${JSON.stringify(i, null, 2)}\n`);
+}
+/** Compare deux versions `X.Y.Z` numériquement : négatif, nul ou positif. */
+export function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}

package/dist/cli.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Installe la méthode Artefact CI dans le dépôt courant (Spec Kit, preset artefact-sdd,
+ * extension artefact-product, agents de relecture, stack.yml, constitution).
+ *   artefact-sdd init [--integration <outil>]
+ *   artefact-sdd update
+ * Sans --source, l'installeur installe la release GitHub de sa propre version.
+ *   artefact-sdd init|update --source <clone de speckit-artefact>
+ * Avec --source, il installe en --dev depuis ce clone (développement de la méthode).
+ * init est idempotent ; update réinstalle les composants sans toucher stack.yml ni la constitution.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { init, SetupError, update } from "./install.mjs";
+import { formatReport } from "./report.mjs";
+import { devSource, releaseSource } from "./source.mjs";
+import { run, SpecifyError } from "./specify.mjs";
+const USAGE = 'Usage : artefact-sdd init|update [--source <dir>] [--integration <outil>] [--help]';
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+let parsed;
+try {
+    parsed = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            source: { type: 'string' },
+            integration: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+}
+catch (error) {
+    fail(`${error.message}\n${USAGE}`);
+}
+const { values, positionals } = parsed;
+if (values.help) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const [command, ...extra] = positionals;
+if (command === undefined)
+    fail(USAGE);
+if (command !== 'init' && command !== 'update')
+    fail(`Commande inconnue : ${command}\n${USAGE}`);
+if (extra.length > 0)
+    fail(`Argument en trop : ${extra.join(' ')}\n${USAGE}`);
+if (command === 'update' && values.integration !== undefined) {
+    console.error("Avertissement : --integration est ignoré par update, l'intégration du projet est gardée.");
+}
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+try {
+    const options = {
+        root: process.cwd(),
+        source: values.source ? devSource(resolve(values.source)) : releaseSource(pkg.version),
+        toolsVersion: pkg.version,
+        runner: run,
+        ...(command === 'init' && values.integration !== undefined ? { integration: values.integration } : {}),
+    };
+    const report = command === 'init' ? await init(options) : await update(options);
+    process.stdout.write(formatReport(report));
+}
+catch (error) {
+    if (error instanceof SetupError || error instanceof SpecifyError)
+        fail(error.message);
+    throw error;
+}

package/dist/constitution.mjs

@@ -0,0 +1,8 @@
+/** Vrai si le texte est encore la constitution vierge du cœur Spec Kit (aucun installeur passé). */
+export function isBlankConstitution(text) {
+    return text.includes('[PROJECT_NAME]') && text.includes('[PRINCIPLE_1_NAME]');
+}
+/** Renseigne le nom du projet ; les autres marqueurs restent à remplir. */
+export function baseConstitution(template, projectName) {
+    return template.replaceAll('[PROJECT_NAME]', () => projectName);
+}

package/dist/errors.mjs

@@ -0,0 +1,6 @@
+export class SetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SetupError';
+    }
+}

package/dist/examples/bun-hono.yml

@@ -0,0 +1,17 @@
+# .specify/stack.yml : API Bun + Hono sans front (exemple : avia-agent, à valider en phase 6b)
+version: 1
+branches:
+  base: dev
+  production: main
+docs:
+  - AGENTS.md
+commands:
+  test: bun test {file}
+  affected: bun run lint && bun run typecheck && bun test
+  check: bun run check
+  trace: bunx @artefact-ci/spec-trace
+tests:
+  globs: ['src/**/*.test.ts']
+flags: false
+ui: null # pas de front : /speckit-design n'écrit que la partie non visuelle, /speckit-prototype s'arrête
+e2e: null

package/dist/examples/nextjs.yml

@@ -0,0 +1,25 @@
+# .specify/stack.yml : application Next.js (exemple : avia-client, à valider en phase 6b)
+version: 1
+branches:
+  base: dev
+  production: main
+docs:
+  - AGENTS.md
+commands:
+  test: pnpm vitest run {file}
+  affected: pnpm lint && pnpm typecheck && pnpm vitest run
+  check: pnpm check
+  trace: pnpm dlx @artefact-ci/spec-trace
+tests:
+  globs: ['src/**/*.test.ts', 'src/**/*.test.tsx', 'e2e/**/*.spec.ts']
+  needs: []
+flags: false
+ui:
+  components: src/components/ui
+  storybook: false
+  theme: src/app/globals.css
+  prototype: pnpm dlx @artefact-ci/prototype # paquet de la phase 3
+e2e:
+  dir: e2e
+  command: pnpm exec playwright test
+  setup: pnpm exec playwright install chromium

package/dist/examples/nx.yml

@@ -0,0 +1,35 @@
+# .specify/stack.yml : nx-react-nestjs (Nx, NestJS, React)
+version: 1
+branches:
+  base: dev
+  production: main
+docs:
+  - AGENTS.md
+  - apps/web/AGENTS.md
+  - libs/web/AGENTS.md
+commands:
+  test: pnpm nx test {project}
+  affected: pnpm nx affected -t lint typecheck test
+  fresh: pnpm nx affected -t lint typecheck test --skip-nx-cache
+  check: pnpm check
+  trace: pnpm -s spec:trace
+tests:
+  globs: ['**/*.spec.ts', '**/*.spec.tsx']
+  needs: [docker] # Testcontainers
+shared:
+  - libs/api/core
+  - libs/shared/contracts
+  - libs/web/data-access
+  - apps/auth
+flags: true # feature flags : catalogue FEATURE_FLAGS, @RequireFeature, requireFeature (AGENTS.md)
+ui:
+  components: libs/web/ui
+  storybook: true
+  theme: libs/web/ui/src/lib/styles/theme.css
+  preview: pnpm nx run web-ui:storybook # http://localhost:6006
+  prototype: pnpm prototype
+e2e:
+  dir: apps/web-e2e
+  command: pnpm nx affected -t e2e
+  fresh: pnpm nx affected -t e2e --skip-nx-cache
+  setup: pnpm exec playwright install chromium

package/dist/fs.mjs

@@ -0,0 +1,10 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Écrit `content` seulement s'il diffère du fichier (crée les dossiers) ; vrai si écrit. */
+export function writeIfChanged(path, content) {
+    if (existsSync(path) && readFileSync(path, 'utf8') === content)
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return true;
+}

package/dist/hooks.mjs

@@ -0,0 +1,70 @@
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+const hook = (command, prompt, description) => ({
+    extension: 'git',
+    command: `speckit.git.${command}`,
+    enabled: true,
+    optional: false,
+    priority: 10,
+    prompt,
+    description,
+    condition: null,
+});
+/** Les 10 hooks git du boilerplate, dans l'ordre de ses événements. */
+const rows = [
+    ['before_specify', 'feature', 'Execute speckit.git.feature?', 'Create feature branch before specification'],
+    ['after_specify', 'commit', 'Commit specify changes?', 'Auto-commit after specification'],
+    ['after_clarify', 'commit', 'Commit clarify changes?', 'Auto-commit after spec clarification'],
+    ['after_plan', 'commit', 'Commit plan changes?', 'Auto-commit after implementation planning'],
+    ['after_tasks', 'commit', 'Commit tasks changes?', 'Auto-commit after task generation'],
+    ['after_checklist', 'commit', 'Commit checklist changes?', 'Auto-commit after checklist generation'],
+    ['after_analyze', 'commit', 'Commit analysis corrections?', 'Auto-commit the corrections made after the analysis'],
+    ['after_implement', 'commit', 'Commit implement changes?', 'Auto-commit after implementation'],
+    ['after_converge', 'commit', 'Commit converge changes?', 'Auto-commit after convergence'],
+    ['after_constitution', 'commit', 'Commit constitution changes?', 'Auto-commit after constitution update'],
+];
+export const GIT_HOOKS = rows.map(([event, command, prompt, description]) => [event, hook(command, prompt, description)]);
+const HEADER = ` Wired on purpose: branch creation before specify, and a commit after each command that writes files
+ (after analyze too: it reports only, but the corrections applied right after it get committed; with
+ nothing changed the hook does nothing). The extension's other hooks (repository initialization,
+ commits before each command, taskstoissues) are left out. \`specify extension update git\` re-adds them:
+ \`npx @artefact-ci/sdd update\` reapplies them.`;
+const isGit = (item) => isMap(item) && item.get('extension') === 'git';
+/**
+ * Ramène les hooks git d'un `.specify/extensions.yml` aux 10 du boilerplate : retire toutes les entrées
+ * `extension: git`, supprime les événements devenus vides, ajoute les 10 hooks (après les entrées des
+ * autres extensions d'un même événement). Conserve `installed`, les autres extensions et les commentaires.
+ */
+export function applyGitHooks(extensionsYml) {
+    const doc = parseDocument(extensionsYml);
+    if (doc.errors.length > 0)
+        throw new Error(`extensions.yml invalide : ${doc.errors[0]?.message}`);
+    if (doc.contents === null)
+        doc.contents = doc.createNode({});
+    if (!isMap(doc.contents))
+        throw new Error('extensions.yml invalide : un mapping est attendu à la racine');
+    doc.setIn(['settings', 'auto_execute_hooks'], true);
+    if (!isMap(doc.get('hooks')))
+        doc.set(doc.createNode('hooks'), doc.createNode({}));
+    const hooks = doc.get('hooks');
+    for (const pair of [...hooks.items]) {
+        const seq = pair.value;
+        if (!isSeq(seq))
+            continue;
+        seq.items = seq.items.filter((item) => !isGit(item));
+        if (seq.items.length === 0)
+            hooks.items = hooks.items.filter((p) => p !== pair);
+    }
+    for (const [event, entry] of GIT_HOOKS) {
+        let seq = hooks.get(event);
+        if (!isSeq(seq)) {
+            seq = doc.createNode([]);
+            hooks.set(event, seq);
+        }
+        seq.add(doc.createNode(entry));
+    }
+    const key = doc.contents.items.find((p) => isScalar(p.key) && p.key.value === 'hooks')?.key;
+    if (isScalar(key) && !(key.commentBefore ?? '').includes('Wired on purpose')) {
+        key.commentBefore = key.commentBefore ? `${key.commentBefore}\n${HEADER}` : HEADER;
+    }
+    return doc.toString({ indentSeq: false });
+}

package/dist/install.mjs

@@ -0,0 +1,261 @@
+import { chmodSync, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { agentFiles, readAgentSpecs, readDefaultIntegration, readIntegrations, skippedAgents } from "./agents.mjs";
+import { compareVersions, readInstalled, writeInstalled } from "./artefact.mjs";
+import { baseConstitution, isBlankConstitution } from "./constitution.mjs";
+import { applyGitHooks } from "./hooks.mjs";
+import { legacyAgents } from "./legacy.mjs";
+import { SetupError } from "./errors.mjs";
+import { writeIfChanged } from "./fs.mjs";
+import { componentArgs, zipUrl } from "./source.mjs";
+import { hasUv, specify, SpecifyError } from "./specify.mjs";
+import { deduceStack, defaultExamplesDir } from "./stack.mjs";
+export { SetupError, writeIfChanged };
+const UV_MISSING = 'uv manque : https://docs.astral.sh/uv/getting-started/installation/';
+const CONSTITUTION = '.specify/memory/constitution.md';
+const STACK = '.specify/stack.yml';
+const EXTENSIONS_YML = '.specify/extensions.yml';
+const PRESET_TEMPLATE = '.specify/presets/artefact-sdd/templates/constitution-template.md';
+/** Vrai si `id` est une clé du `.registry` de `kind` ; registre absent → faux. */
+function registered(root, kind, id) {
+    const rel = `.specify/${kind}/.registry`;
+    const file = join(root, rel);
+    if (!existsSync(file))
+        return false;
+    let json;
+    try {
+        json = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new SetupError(`${rel} illisible : ${e.message}`);
+    }
+    const map = json?.[kind];
+    return typeof map === 'object' && map !== null && id in map;
+}
+const COMPONENTS = [
+    {
+        id: 'git',
+        kind: 'extensions',
+        install: (_s, present) => ({ args: ['extension', 'add', 'git', ...(present ? ['--force'] : [])] }),
+    },
+    { id: 'artefact-product', kind: 'extensions', install: (s, present) => componentArgs(s, 'artefact-product', present) },
+    { id: 'artefact-sdd', kind: 'presets', install: (s, present) => componentArgs(s, 'artefact-sdd', present) },
+];
+/** stdout d'une commande git, ou null si elle échoue (pas un dépôt, pas de commit…). */
+async function git(o, args) {
+    try {
+        const r = await o.runner('git', args, { cwd: o.root });
+        return r.code === 0 ? r.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Branches locales et de `origin` (préfixe retiré, dédupliquées) et cible de `origin/HEAD` ; vide hors dépôt. */
+async function branches(o) {
+    const refs = ((await git(o, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes/origin'])) ?? '')
+        .split('\n')
+        .map((r) => r.trim())
+        .filter((r) => r !== '' && r !== 'refs/remotes/origin/HEAD')
+        .map((r) => r.replace(/^refs\/heads\//, '').replace(/^refs\/remotes\/origin\//, ''));
+    const head = (await git(o, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']))?.trim();
+    const defaultBranch = head?.startsWith('refs/remotes/origin/') ? head.slice('refs/remotes/origin/'.length) : undefined;
+    return { names: [...new Set(refs)], ...(defaultBranch ? { defaultBranch } : {}) };
+}
+const SCRIPTS = '.specify/scripts';
+/** Droits de chaque fichier sous `.specify/scripts/` (chemin absolu → mode). */
+function scriptModes(root) {
+    const modes = new Map();
+    const walk = (dir) => {
+        if (!existsSync(dir))
+            return;
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile())
+                modes.set(p, statSync(p).mode & 0o777);
+        }
+    };
+    walk(join(root, SCRIPTS));
+    return modes;
+}
+/**
+ * Spec Kit 1.3.2 n'enregistre les commandes d'une extension ou d'un preset que pour l'intégration
+ * par défaut ; une autre ne les reçoit qu'à `specify integration use`. On sélectionne donc chaque
+ * intégration secondaire, puis on revient toujours à celle par défaut, même après un échec.
+ * `use` réécrit les scripts partagés sans leur droit d'exécution : on remet les droits d'avant.
+ */
+async function registerSecondary(o, integrations) {
+    const fallback = readDefaultIntegration(o.root);
+    if (fallback === null || !integrations.includes(fallback))
+        return [];
+    const others = integrations.filter((i) => i !== fallback);
+    if (others.length === 0)
+        return [];
+    const modes = scriptModes(o.root);
+    let failed;
+    for (const integration of others) {
+        try {
+            await specify(o.runner, o.root, ['integration', 'use', integration]);
+        }
+        catch (e) {
+            failed = { integration, error: e };
+            break;
+        }
+    }
+    try {
+        await specify(o.runner, o.root, ['integration', 'use', fallback]);
+    }
+    finally {
+        for (const [file, mode] of modes) {
+            if (existsSync(file) && (statSync(file).mode & 0o777) !== mode)
+                chmodSync(file, mode);
+        }
+    }
+    if (failed) {
+        throw new SetupError(`impossible d'enregistrer les commandes de la méthode pour ${failed.integration} : ${failed.error.message} ; ${fallback} reste l'outil par défaut, relance update`);
+    }
+    return others;
+}
+async function isDirty(o) {
+    return ((await git(o, ['status', '--porcelain'])) ?? '').trim() !== '';
+}
+/** Étapes 3 à 6 communes à init et update, puis le relevé des anciens agents. */
+async function common(o, mode) {
+    const { root } = o;
+    const migrated = registered(root, 'presets', 'boilerplate');
+    if (migrated)
+        await specify(o.runner, root, ['preset', 'remove', 'boilerplate']);
+    const installed = [];
+    const skipped = [];
+    for (const c of COMPONENTS) {
+        const present = registered(root, c.kind, c.id);
+        if (mode === 'init' && present) {
+            skipped.push(c.id);
+            continue;
+        }
+        const { args, input } = c.install(o.source, present);
+        try {
+            await specify(o.runner, root, args, input);
+        }
+        catch (e) {
+            if (o.source.kind === 'release' && c.id !== 'git' && e instanceof SpecifyError) {
+                const url = zipUrl(o.source, c.id);
+                throw new SetupError(`impossible d'installer ${c.id} ${o.source.version} depuis ${url} : ${e.message} ; relance la même commande une fois le réseau rétabli`);
+            }
+            throw e;
+        }
+        installed.push(c.id);
+    }
+    const extYml = join(root, EXTENSIONS_YML);
+    writeIfChanged(extYml, applyGitHooks(existsSync(extYml) ? readFileSync(extYml, 'utf8') : ''));
+    let integrations;
+    try {
+        integrations = readIntegrations(root);
+    }
+    catch (e) {
+        throw new SetupError(`.specify/integration.json illisible : ${e.message}`);
+    }
+    // Seulement quand un composant vient d'être (ré)installé : un second init ne lance rien.
+    const registeredFor = installed.length > 0 ? await registerSecondary(o, integrations) : [];
+    const specs = readAgentSpecs(root);
+    const agents = [];
+    const agentsSkipped = [];
+    const noAgentGenerator = [];
+    for (const integration of integrations) {
+        const files = agentFiles(integration, specs);
+        if (files === null) {
+            noAgentGenerator.push(integration);
+            continue;
+        }
+        for (const f of files) {
+            writeIfChanged(join(root, f.path), f.content);
+            agents.push(f.path);
+        }
+        const names = skippedAgents(integration, specs);
+        if (names.length > 0)
+            agentsSkipped.push({ integration, names });
+    }
+    return {
+        migrated,
+        noIntegration: integrations.length === 0,
+        installed,
+        skipped,
+        agents,
+        agentsSkipped,
+        noAgentGenerator,
+        registeredFor,
+        legacy: legacyAgents(root),
+    };
+}
+export async function init(o) {
+    const { root } = o;
+    if (!(await hasUv(o.runner)))
+        throw new SetupError(UV_MISSING);
+    // Le garde passe avant toute commande Spec Kit, migration du boilerplate comprise.
+    const previous = readInstalled(root);
+    if (previous && previous.version !== o.source.version) {
+        throw new SetupError(`Spec Kit a déjà la méthode en ${previous.version} (.specify/artefact.json) ; cet installeur installe ${o.source.version} : lance update pour changer de version`);
+    }
+    const noneInstalled = !registered(root, 'presets', 'artefact-sdd') && !registered(root, 'extensions', 'artefact-product');
+    const dirty = await isDirty(o);
+    const hadSpecify = existsSync(join(root, '.specify'));
+    if (!hadSpecify) {
+        const args = ['init', '--here', '--script', 'sh', '--non-interactive', '--ignore-agent-tools'];
+        args.push('--integration', o.integration ?? 'claude');
+        // Spec Kit 1.3.2 compte `.git` comme contenu : sans --force, il refuse un dossier non vide.
+        if (readdirSync(root).length > 0)
+            args.push('--force');
+        await specify(o.runner, root, args);
+    }
+    const done = await common(o, 'init');
+    const current = { version: o.source.version, source: o.source.kind };
+    const record = previous !== null || noneInstalled;
+    if (record)
+        writeInstalled(root, current);
+    let stack;
+    if (!existsSync(join(root, STACK))) {
+        stack = deduceStack(root, { examplesDir: defaultExamplesDir(), toolsVersion: o.toolsVersion, branches: await branches(o) });
+        writeIfChanged(join(root, STACK), stack.yaml);
+    }
+    let constitution = 'kept';
+    const constFile = join(root, CONSTITUTION);
+    if (!existsSync(constFile) || isBlankConstitution(readFileSync(constFile, 'utf8'))) {
+        const template = join(root, PRESET_TEMPLATE);
+        if (!existsSync(template)) {
+            throw new SetupError(`${PRESET_TEMPLATE} introuvable alors que le preset artefact-sdd est enregistré : lance update`);
+        }
+        writeIfChanged(constFile, baseConstitution(readFileSync(template, 'utf8'), basename(root)));
+        constitution = 'written';
+    }
+    // Spec Kit n'installe une intégration qu'à son init : sur un projet déjà initialisé, --integration ne fait rien.
+    let integrationIgnored;
+    if (hadSpecify && o.integration !== undefined) {
+        const installed = readIntegrations(root);
+        if (!installed.includes(o.integration))
+            integrationIgnored = { requested: o.integration, installed };
+    }
+    return {
+        mode: 'init',
+        ...done,
+        stack,
+        constitution,
+        dirty,
+        ...(integrationIgnored ? { integrationIgnored } : {}),
+        version: { installed: record ? current : null, previous, downgrade: false }
+    };
+}
+export async function update(o) {
+    if (!(await hasUv(o.runner)))
+        throw new SetupError(UV_MISSING);
+    if (!existsSync(join(o.root, '.specify')))
+        throw new SetupError('.specify/ absent : lance init');
+    const previous = readInstalled(o.root);
+    const dirty = await isDirty(o);
+    const done = await common(o, 'update');
+    const current = { version: o.source.version, source: o.source.kind };
+    writeInstalled(o.root, current);
+    const downgrade = previous !== null && compareVersions(previous.version, current.version) > 0;
+    return { mode: 'update', ...done, constitution: 'kept', dirty, version: { installed: current, previous, downgrade } };
+}

package/dist/legacy.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const LEGACY_DIR = 'docs/agents';
+/** SHA-256 des fichiers du boilerplate (commit b30bb7b). */
+const BOILERPLATE = {
+    'designer.md': '01be6c6e3f1f86452bde42fb5117d288604f9757e0cf56c58a645fccc940bb4d',
+    'po.md': '2a78f6d5509157d26b866ad76de37abd3d075bb11dad63cc3eaae22188858696',
+    'relecteur-design.md': '3580a65a90e7fa3d8930213c304c18e74217a22e2b72efcb224902ddd3db95c2',
+    'relecteur-produit.md': '6907b77ab2d049462e9f06c5fbd4c64b901ccf9ba6d77f43a0a6150063c33b28',
+    'relecteur.md': '39825229e09467c002a60ac73f034a1ca440fbba7e53a9b6413d126e3618038d',
+};
+/** Dossiers de build, de cache ou de dépendances, sautés partout. */
+const SKIPPED = new Set(['.git', 'node_modules', 'dist', '.next', '.nx', 'coverage', '.turbo', 'build', 'vendor']);
+/**
+ * Chemins sautés : fichiers d'agent générés, l'ancien dossier lui-même, et ce que Spec Kit et l'installeur
+ * écrivent sous `.specify/`. `.specify/memory/` (la constitution du projet) est lu.
+ */
+const GENERATED = new Set([
+    '.claude/agents',
+    '.agents/agents',
+    LEGACY_DIR,
+    ...['extensions', 'presets', 'templates', 'scripts', 'integrations', 'workflows'].map((d) => `.specify/${d}`),
+]);
+function findMentions(root, rel, out) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, rel), { withFileTypes: true });
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'EACCES' || code === 'EPERM')
+            return;
+        throw e;
+    }
+    for (const e of entries) {
+        const path = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isSymbolicLink())
+            continue;
+        if (e.isDirectory()) {
+            if (!SKIPPED.has(e.name) && !GENERATED.has(path))
+                findMentions(root, path, out);
+        }
+        else if (e.isFile() && e.name.endsWith('.md')) {
+            let text;
+            try {
+                text = readFileSync(join(root, path), 'utf8');
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === 'EACCES' || code === 'EPERM')
+                    continue;
+                throw err;
+            }
+            if (text.includes(`${LEGACY_DIR}/`))
+                out.push(path);
+        }
+    }
+}
+/** Lit seulement : `docs/agents/` du projet n'est jamais modifié ni supprimé. */
+export function legacyAgents(root) {
+    const dir = join(root, LEGACY_DIR);
+    const files = [];
+    if (existsSync(dir)) {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (!e.isFile() || !e.name.endsWith('.md'))
+                continue;
+            const expected = BOILERPLATE[e.name];
+            const sha = createHash('sha256').update(readFileSync(join(dir, e.name))).digest('hex');
+            files.push({
+                path: `${LEGACY_DIR}/${e.name}`,
+                state: expected === undefined ? 'unknown' : expected === sha ? 'unchanged' : 'modified',
+            });
+        }
+        files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    }
+    const mentions = [];
+    findMentions(root, '', mentions);
+    mentions.sort();
+    return { files, mentions };
+}

package/dist/report.mjs

@@ -0,0 +1,91 @@
+import { SPECIFY_VERSION } from "./specify.mjs";
+const LEGACY_STATE = {
+    unchanged: 'identique au boilerplate, tu peux le supprimer',
+    /** Variante quand des fichiers citent encore docs/agents/. */
+    unchangedCited: 'identique au boilerplate : supprimable une fois les mentions ci-dessous mises à jour',
+    modified: 'modifié, à reporter dans les docs avant de supprimer le dossier',
+    unknown: 'inconnu du boilerplate, à reporter dans les docs avant de supprimer le dossier',
+};
+/** Dossier d'agents d'un fichier généré : `.claude/agents/x.md` → `.claude/agents`. */
+const agentDir = (path) => path.split('/').slice(0, 2).join('/');
+/** Le rapport d'init ou d'update, en français, pour la sortie standard. */
+export function formatReport(r) {
+    const out = [];
+    const list = (items) => items.join(', ');
+    out.push('Spec Kit');
+    if (r.installed.length > 0) {
+        out.push(`  ${r.mode === 'update' ? 'Réinstallé / mis à jour' : 'Installé'} : ${list(r.installed)}`);
+    }
+    if (r.skipped.length > 0)
+        out.push(`  Déjà installé : ${list(r.skipped)}`);
+    if (r.registeredFor.length > 0) {
+        out.push(`  Commandes de la méthode enregistrées aussi pour : ${list(r.registeredFor)} (outil par défaut inchangé)`);
+    }
+    const { installed, previous, downgrade } = r.version;
+    if (installed === null) {
+        out.push('  Version installée inconnue : lance update pour aligner tous les composants');
+    }
+    else {
+        const now = `${installed.version} (${installed.source})`;
+        if (r.mode === 'init')
+            out.push(`  Version : ${now}`);
+        else if (previous)
+            out.push(`  Version : ${previous.version} → ${now}`);
+        else
+            out.push(`  Version : ${now}, version précédente inconnue`);
+        if (downgrade && previous) {
+            out.push(`  Attention : ${previous.version} était plus récente que ${installed.version}, l'installeur a remis ${installed.version}`);
+        }
+    }
+    if (r.migrated) {
+        out.push('', 'Migration du boilerplate', '  preset `boilerplate` retiré ;', '  pour garder les templates de plan et de tâches propres à la stack, ajouter un preset local au-dessus', '  (`specify preset add --dev <chemin> --priority 5`, voir `examples/nx-preset/` de speckit-artefact) ;', '  remplacer `preset update boilerplate` dans `AGENTS.md` et les guides par `npx @artefact-ci/sdd update`.');
+    }
+    if (r.noIntegration || r.agents.length > 0 || r.noAgentGenerator.length > 0 || r.agentsSkipped.length > 0) {
+        out.push('', "Agents de relecture");
+        if (r.noIntegration) {
+            out.push("  aucune intégration trouvée dans .specify/integration.json : aucun fichier d'agent généré");
+        }
+        const byDir = new Map();
+        for (const path of r.agents)
+            byDir.set(agentDir(path), [...(byDir.get(agentDir(path)) ?? []), path]);
+        for (const [dir, paths] of byDir)
+            out.push(`  ${dir} : ${paths.length} fichier(s) à jour`);
+        for (const name of r.noAgentGenerator) {
+            out.push(`  ${name} : pas de générateur de fichiers d'agent, la relecture se fait en contexte neuf`);
+        }
+        for (const { integration, names } of r.agentsSkipped) {
+            out.push(`  ${integration} : pas de fichier d'agent ${list(names)} pour cet outil : la commande fera ce travail en nouvelle session`);
+        }
+    }
+    if (r.stack) {
+        out.push('', ".specify/stack.yml déduit du dépôt : relis-le et corrige-le avant de t'en servir.");
+        out.push(`  Stack détectée : ${r.stack.kind === 'unknown' ? 'aucune reconnue' : r.stack.kind}`);
+        if (r.stack.guessed.length > 0)
+            out.push(`  Devinées : ${list(r.stack.guessed)}`);
+        if (r.stack.empty.length > 0)
+            out.push(`  À compléter : ${list(r.stack.empty)}`);
+    }
+    out.push('', r.constitution === 'written'
+        ? '.specify/memory/constitution.md écrit avec la base Artefact CI : ajoute les principes du projet.'
+        : '.specify/memory/constitution.md gardé tel quel.');
+    if (r.legacy.files.length > 0 || r.legacy.mentions.length > 0) {
+        out.push('', "Anciens agents (docs/agents/, jamais modifiés par l'installeur)");
+        const cited = r.legacy.mentions.length > 0;
+        for (const f of r.legacy.files) {
+            out.push(`  ${f.path} : ${LEGACY_STATE[f.state === 'unchanged' && cited ? 'unchangedCited' : f.state]}`);
+        }
+        if (r.legacy.mentions.length > 0) {
+            out.push(`  Citent encore docs/agents/ : ${list(r.legacy.mentions)}`);
+        }
+    }
+    if (r.integrationIgnored) {
+        const { requested, installed } = r.integrationIgnored;
+        const current = installed.length > 0 ? list(installed) : 'aucune intégration';
+        const specify = `uvx --from specify-cli==${SPECIFY_VERSION} specify integration`;
+        out.push('', `Attention : --integration ${requested} ignoré : Spec Kit était déjà installé ici avec ${current}.`, `  pour garder ${current} et ajouter ${requested} : ${specify} install ${requested} --script sh --force`, `  pour remplacer ${current} par ${requested} : ${specify} switch ${requested}`, "  puis : npx @artefact-ci/sdd update (voir « Changer ou ajouter un outil » dans le README de speckit-artefact)");
+    }
+    if (r.dirty) {
+        out.push('', "Attention : le dépôt avait des changements non commités avant l'installation ; relis le diff avant de commiter.");
+    }
+    return `${out.join('\n')}\n`;
+}

package/dist/source.mjs

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { SetupError } from "./errors.mjs";
+export const RELEASE_BASE = 'https://github.com/artefact-ci/speckit-artefact/releases/download';
+/** Release GitHub de `version` ; SDD_RELEASE_BASE_URL (réservée aux tests) remplace le préfixe de l'URL. */
+export function releaseSource(version, env = process.env) {
+    const override = env['SDD_RELEASE_BASE_URL'];
+    const baseUrl = override ? override.replace(/\/+$/, '') : `${RELEASE_BASE}/v${version}`;
+    return { kind: 'release', version, baseUrl };
+}
+/** Clone de speckit-artefact : la version est `preset.version` du preset. */
+export function devSource(dir) {
+    for (const file of ['extension/extension.yml', 'preset/preset.yml']) {
+        if (!existsSync(join(dir, file))) {
+            throw new SetupError(`${dir} n'est pas un clone de speckit-artefact : ${file} introuvable (passe --source <clone de speckit-artefact>)`);
+        }
+    }
+    const file = join(dir, 'preset/preset.yml');
+    const version = parse(readFileSync(file, 'utf8'))?.preset?.version;
+    if (typeof version !== 'string' || version === '') {
+        throw new SetupError(`${file} : preset.version manque`);
+    }
+    return { kind: 'dev', version, dir };
+}
+export function zipUrl(s, id) {
+    return `${s.baseUrl}/${id}-${s.version}.zip`;
+}
+/** Arguments `specify` d'installation de `id` ; `input` est envoyé sur stdin. */
+export function componentArgs(s, id, present) {
+    if (s.kind === 'release') {
+        const url = zipUrl(s, id);
+        if (id === 'artefact-product') {
+            // `extension add --from` demande « Continue with installation? [y/N] ».
+            return { args: ['extension', 'add', '--from', url, ...(present ? ['--force'] : [])], input: 'y\n' };
+        }
+        return { args: present ? ['preset', 'update', 'artefact-sdd', '--from', url] : ['preset', 'add', '--from', url] };
+    }
+    if (id === 'artefact-product') {
+        const dir = join(s.dir, 'extension');
+        return { args: ['extension', 'add', '--dev', dir, ...(present ? ['--force'] : [])] };
+    }
+    const dir = join(s.dir, 'preset');
+    return { args: present ? ['preset', 'update', 'artefact-sdd', '--dev', dir] : ['preset', 'add', '--dev', dir] };
+}

package/dist/specify.mjs

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+/** Version de Spec Kit (specify-cli) épinglée par l'installeur. */
+export const SPECIFY_VERSION = '1.3.2';
+/** Lance une commande sans shell. Ne rejette que si le processus ne peut pas démarrer. */
+export const run = (cmd, args, opts) => new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8').on('data', (d) => (stdout += d));
+    child.stderr.setEncoding('utf8').on('data', (d) => (stderr += d));
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    // Un EPIPE sur stdin (processus déjà terminé) ne doit pas faire tomber l'installeur.
+    child.stdin.on('error', () => { });
+    if (opts.input !== undefined)
+        child.stdin.write(opts.input);
+    child.stdin.end();
+});
+/** Spec Kit écrit ses erreurs sur stdout : le message en garde la fin, puis stderr. */
+const TAIL_LINES = 20;
+export class SpecifyError extends Error {
+    code;
+    stdout;
+    stderr;
+    constructor(code, stderr, stdout = '') {
+        const tail = stdout.trimEnd().split('\n').slice(-TAIL_LINES).join('\n').trim();
+        const detail = [tail, stderr.trim()].filter(Boolean).join('\n');
+        super(`specify a échoué (code ${code})${detail ? ` :\n${detail}` : ''}`);
+        this.name = 'SpecifyError';
+        this.code = code;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+/** Exécute `specify …args` via uvx, à la version épinglée ; renvoie stdout. */
+export async function specify(runner, cwd, args, input) {
+    const { code, stdout, stderr } = await runner('uvx', ['--from', `specify-cli==${SPECIFY_VERSION}`, 'specify', ...args], { cwd, ...(input !== undefined ? { input } : {}) });
+    if (code !== 0)
+        throw new SpecifyError(code, stderr, stdout);
+    return stdout;
+}
+export async function hasUv(runner) {
+    try {
+        return (await runner('uvx', ['--version'], { cwd: process.cwd() })).code === 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/stack.mjs

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse, stringify } from 'yaml';
+const TODO = '# à compléter';
+/** Les exemples sont copiés dans `dist/examples/` au build ; depuis `src/` (dev, tests), on lit ceux du dépôt. */
+export function defaultExamplesDir() {
+    const built = new URL('./examples/', import.meta.url);
+    return fileURLToPath(existsSync(built) ? built : new URL('../../../examples/stack/', import.meta.url));
+}
+const RUNNERS = {
+    bun: { run: 'bun run', dlx: 'bunx' },
+    pnpm: { run: 'pnpm', dlx: 'pnpm dlx' },
+    // yarn 1 n'a pas de dlx : npx marche partout où yarn tourne.
+    yarn: { run: 'yarn', dlx: 'npx -y' },
+    npm: { run: 'npm run', dlx: 'npx -y' },
+};
+const EXEC = { bun: 'bunx ', pnpm: 'pnpm ', yarn: 'yarn ', npm: 'npx ' };
+const detectRunner = (has) => has('bun.lock') || has('bun.lockb') ? 'bun'
+    : has('pnpm-lock.yaml') ? 'pnpm'
+        : has('yarn.lock') ? 'yarn'
+            : 'npm';
+const detectKind = (root, has) => {
+    if (has('nx.json'))
+        return 'nx';
+    if (['js', 'mjs', 'cjs', 'ts', 'mts'].some((e) => has(`next.config.${e}`)))
+        return 'nextjs';
+    if (has('bun.lock') || has('bun.lockb'))
+        return 'bun-hono';
+    return 'unknown';
+};
+const readScripts = (root) => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        return pkg.scripts ?? {};
+    }
+    catch {
+        return {};
+    }
+};
+const scalar = (v) => stringify(v, { lineWidth: 0, singleQuote: true }).trimEnd();
+const flow = (v) => stringify(v, { collectionStyle: 'flow', flowCollectionPadding: false, singleQuote: true, lineWidth: 0 }).trimEnd();
+/**
+ * Déduit le texte de `.specify/stack.yml` d'un dépôt, sans rien écrire. Part de l'exemple le plus proche
+ * (`examples/stack/`), garde ce que le dépôt confirme, laisse le reste vide avec `# à compléter`.
+ */
+export function deduceStack(root, opts) {
+    const has = (p) => existsSync(join(root, p));
+    const kind = detectKind(root, has);
+    const runner = detectRunner(has);
+    const scripts = readScripts(root);
+    const run = RUNNERS[runner].run;
+    const dlx = RUNNERS[runner].dlx;
+    const ex = kind === 'unknown' ? {} : parse(readFileSync(join(opts.examplesDir, `${kind}.yml`), 'utf8'));
+    /** `pnpm exec x` / `pnpm x` de l'exemple, réécrits pour le runner du projet. */
+    const swap = (cmd) => {
+        if (runner === 'pnpm')
+            return cmd;
+        if (cmd.startsWith('pnpm exec '))
+            return EXEC[runner] + cmd.slice('pnpm exec '.length);
+        if (cmd.startsWith('pnpm '))
+            return EXEC[runner] + cmd.slice('pnpm '.length);
+        return cmd;
+    };
+    const guessed = new Set();
+    const empty = new Set();
+    const lines = [`# Déduit par @artefact-ci/sdd ${opts.toolsVersion} : relis chaque clé (voir docs/stack.md).`, 'version: 1'];
+    /** Une clé : valeur, ou vide + `# à compléter`. */
+    const put = (indent, path, value, comment) => {
+        const key = path.split('.').at(-1);
+        const pad = ' '.repeat(indent);
+        if (value === undefined || value === '') {
+            empty.add(path);
+            lines.push(`${pad}${key}: ${TODO}`);
+        }
+        else {
+            lines.push(`${pad}${key}: ${value}${comment ? ` ${comment}` : ''}`);
+        }
+    };
+    const putList = (path, values) => {
+        if (values.length === 0)
+            return void put(0, path, undefined);
+        lines.push(`${path}:`, ...values.map((v) => `  - ${scalar(v)}`));
+    };
+    // branches : base = dev, sinon la branche par défaut (origin/HEAD, puis main, puis master), jamais la
+    // branche courante ; production = main si présente et différente de base. Sinon vide, à compléter.
+    const names = new Set(opts.branches.names);
+    const def = opts.branches.defaultBranch;
+    const base = names.has('dev') ? 'dev' : [def, 'main', 'master'].find((b) => b !== undefined && names.has(b));
+    const production = names.has('main') && base !== 'main' ? 'main' : undefined;
+    lines.push('branches:');
+    put(2, 'branches.base', base === undefined ? undefined : scalar(base));
+    put(2, 'branches.production', production);
+    if (base !== undefined)
+        guessed.add('branches.base');
+    if (production !== undefined)
+        guessed.add('branches.production');
+    const docs = (ex.docs ?? ['AGENTS.md']).filter(has);
+    putList('docs', docs);
+    if (docs.length > 0)
+        guessed.add('docs');
+    // commandes
+    lines.push('commands:');
+    const exampleCmd = (name) => {
+        const c = ex.commands?.[name];
+        return c === undefined ? undefined : swap(c);
+    };
+    const cmds = [];
+    if (kind === 'nx') {
+        cmds.push(['test', exampleCmd('test')], ['affected', exampleCmd('affected')], ['fresh', exampleCmd('fresh')]);
+    }
+    else {
+        const t = scripts['test'];
+        const test = t === undefined ? undefined : t === 'bun test' ? 'bun test {file}' : runner === 'npm' ? 'npm run test -- {file}' : `${run} test {file}`;
+        const parts = ['lint', 'typecheck', 'test'].filter((s) => scripts[s] !== undefined).map((s) => `${run} ${s}`);
+        cmds.push(['test', test], ['affected', t === undefined ? undefined : parts.join(' && ')]);
+    }
+    cmds.push(['check', scripts['check'] === undefined ? undefined : `${run} check`]);
+    cmds.push(['trace', `${dlx} @artefact-ci/spec-trace@${opts.toolsVersion}`]);
+    for (const [name, value] of cmds) {
+        put(2, `commands.${name}`, value === undefined ? undefined : scalar(value));
+        if (value !== undefined)
+            guessed.add(`commands.${name}`);
+    }
+    // tests, shared
+    if (ex.tests) {
+        lines.push('tests:');
+        if (ex.tests.globs)
+            (put(2, 'tests.globs', flow(ex.tests.globs)), guessed.add('tests.globs'));
+        if (ex.tests.needs)
+            (put(2, 'tests.needs', flow(ex.tests.needs)), guessed.add('tests.needs'));
+    }
+    if (ex.shared) {
+        const shared = ex.shared.filter(has);
+        putList('shared', shared);
+        if (shared.length > 0)
+            guessed.add('shared');
+    }
+    // flags : livrer derrière un feature flag est une décision de l'équipe, jamais devinée.
+    put(0, 'flags', undefined);
+    // ui : objet dès qu'un front est détecté
+    guessed.add('ui');
+    if (kind === 'nx' || kind === 'nextjs') {
+        const ui = ex.ui ?? {};
+        lines.push('ui:');
+        put(2, 'ui.components', ui.components && has(ui.components) ? scalar(ui.components) : undefined);
+        if (ui.storybook !== undefined)
+            put(2, 'ui.storybook', String(ui.storybook));
+        put(2, 'ui.theme', ui.theme && has(ui.theme) ? scalar(ui.theme) : undefined);
+        if (ui.preview)
+            put(2, 'ui.preview', scalar(swap(ui.preview)), '# http://localhost:6006');
+        put(2, 'ui.prototype', scalar(scripts['prototype'] !== undefined ? `${run} prototype` : `${dlx} @artefact-ci/prototype@${opts.toolsVersion}`));
+    }
+    else {
+        lines.push('ui: null # pas de front : /speckit-design n\'écrit que la partie non visuelle, /speckit-prototype s\'arrête');
+    }
+    // e2e : seulement si le dossier des parcours existe
+    guessed.add('e2e');
+    if (ex.e2e && has(ex.e2e.dir)) {
+        lines.push('e2e:');
+        put(2, 'e2e.dir', scalar(ex.e2e.dir));
+        if (ex.e2e.command)
+            put(2, 'e2e.command', scalar(swap(ex.e2e.command)));
+        if (ex.e2e.fresh)
+            put(2, 'e2e.fresh', scalar(swap(ex.e2e.fresh)));
+        if (ex.e2e.setup)
+            put(2, 'e2e.setup', scalar(swap(ex.e2e.setup)));
+    }
+    else {
+        lines.push('e2e: null');
+    }
+    return { yaml: `${lines.join('\n')}\n`, kind, guessed: [...guessed].sort(), empty: [...empty].sort() };
+}

package/package.json

@@ -1 +1,34 @@
-{"name":"@artefact-ci/sdd","version":"0.0.1-stage"}
+{
+  "name": "@artefact-ci/sdd",
+  "version": "0.2.1",
+  "description": "Installeur de la méthode Artefact CI pour Spec Kit (preset artefact-sdd, extension artefact-product)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artefact-ci/speckit-artefact.git",
+    "directory": "packages/sdd"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "bin": {
+    "artefact-sdd": "dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.11"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/examples && cp ../../examples/stack/*.yml dist/examples/",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test 'src/*.test.mts'",
+    "test:e2e": "pnpm build && node --test test/e2e.test.mts"
+  }
+}