@dev-kosaly/kagents 0.1.1 → 0.2.0

package/README.md

@@ -50,16 +50,29 @@ Prérequis : Node 18 ou plus. Depuis la racine du projet :
 
 ```bash
 npx @dev-kosaly/kagents            # ou : pnpm dlx @dev-kosaly/kagents
-npx @dev-kosaly/kagents --tools claude,cursor,agents
+npx @dev-kosaly/kagents --tools claude,cursor,agents   # sans question
+npx @dev-kosaly/kagents --configure                    # rechoisir les outils
 npx @dev-kosaly/kagents --copy     # copies au lieu de liens (utile sous Windows)
 npx @dev-kosaly/kagents uninstall
 ```
 
-Par défaut, le kit détecte les outils présents (`.claude/`, `.cursor/`) et branche aussi `.agents/skills/`.
+Ajouter le paquet comme dépendance (`npm add @dev-kosaly/kagents` ou `pnpm add @dev-kosaly/kagents`) lance aussi l'installation automatiquement. Avec **pnpm**, les scripts des dépendances sont bloqués tant qu'ils ne sont pas approuvés : lancez `pnpm approve-builds` une fois (ou `pnpm exec kagents` à la main). `KAGENTS_SKIP_POSTINSTALL=1` désactive l'installation automatique.
+
+Dans un terminal, l'installation pose la question :
+
+```text
+? Pour quels outils installer KAgents ?  (↑↓ espace a entrée)
+ ❯ ◉ Claude Code  (.claude/commands, .claude/agents)
+   ◯ Cursor  (.cursor/commands, .cursor/agents, .cursor/rules)
+   ◉ Codex et autres outils AGENTS.md  (.agents/skills)
+```
+
+Le choix est mémorisé dans `.kagents/config.json` et rejoué aux mises à jour. Sans terminal (CI) ou avec `--yes`, les outils sont détectés automatiquement (`.claude/`, `.cursor/`) et `.agents/skills/` est ajouté.
 
 Ce que fait l'installation :
-- Le kit est copié dans `.kagents/`. `.claude/`, `.cursor/` et `.agents/` ne contiennent que des liens relatifs.
+- Le kit est copié dans `.kagents/`. `.claude/` et `.cursor/` reçoivent des liens relatifs vers les commandes et les agents (les skills restent dans `.kagents/skills/` pour ne pas polluer le menu `/`) ; `.agents/skills/` expose les skills aux outils qui le lisent.
 - Le bloc `<!-- kagents:start/end -->` de `AGENTS.md` est régénéré (mode d'emploi, agents, routage). Le reste du fichier n'est jamais modifié.
+- `.gitignore` reçoit un bloc `# kagents:start/end` qui ignore le kit dans `.kagents/` mais pas `.kagents/docs/` (livrables et contexte, à versionner).
 - Un fichier existant qui n'est pas géré par KAgents n'est jamais écrasé.
 
 **Mise à jour** : relancer avec `@latest`. Les fichiers du kit dans `.kagents/` sont régénérés (ne pas les éditer). `.kagents/docs/`, qui contient les livrables des agents et `knowledge/context.md`, n'est jamais touché.

package/agents/architect.md

@@ -116,7 +116,7 @@ Handoff Developer : perimetre implementation **apres** validations ; ne pas defi
 | `agents/architect.md` | Qui, limites, modes, principes |
 | `rules/domains/architect-invariants.md` | Invariants non negociables |
 | `rules/domains/architect-chat.md` | Contrat de sortie conversationnelle |
-| `skills/architect-*` | Procedures |
+| `skills/architect-*` | Procedures (installées dans `.kagents/skills/<nom>/SKILL.md` : les charger par ce chemin) |
 | `workflows/architect-*.md` | Enchainement |
 | `templates/architect-output/` | Structure livrable |
 | `commands/architect*.md` | Entrees explicites |

package/bin/kagents.js

@@ -5,25 +5,29 @@
 
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
+const tty = require('tty');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const PKG = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
 const KIT_DIRS = ['agents', 'skills', 'commands', 'rules', 'templates', 'checklists', 'workflows', 'governance', 'docs'];
 const SKIP = new Set(['README.md', '.gitkeep']);
 const BLOCK_RE = /<!-- kagents:start -->[\s\S]*?<!-- kagents:end -->/;
+const GITIGNORE_RE = /# kagents:start\n[\s\S]*?# kagents:end\n?/;
+// On ignore le kit (régénérable) mais pas docs/ : livrables et contexte sont à versionner.
 
 // Adaptateurs : un outil = une liste [dossier du kit, destination, type].
 // type : files (fichiers), dirs (dossiers), agents (fichiers .md avec `name:`).
+// Les skills ne sont volontairement PAS liées dans .claude/ ni .cursor/ : ces outils les listeraient
+// comme commandes `/`. Les agents et commandes les chargent par chemin depuis .kagents/skills/.
 const ADAPTERS = {
   agents: [['skills', '.agents/skills', 'dirs']],
   claude: [
     ['commands', '.claude/commands', 'files'],
-    ['skills', '.claude/skills', 'dirs'],
     ['agents', '.claude/agents', 'agents'],
   ],
   cursor: [
     ['commands', '.cursor/commands', 'files'],
-    ['skills', '.cursor/skills', 'dirs'],
     ['agents', '.cursor/agents', 'agents'],
     ['rules/global', '.cursor/rules', 'files'],
     ['rules/domains', '.cursor/rules', 'files'],
@@ -32,14 +36,18 @@ const ADAPTERS = {
 
 const HELP = `kagents ${PKG.version}
 
-Usage : kagents [install] [--tools claude,cursor,agents|auto] [--copy]
+Usage : kagents [install] [--tools claude,cursor,agents|auto|none] [--yes] [--copy]
+        kagents --configure          (rechoisir les outils)
         kagents uninstall
         kagents --help | --version
 
-À lancer depuis la racine du projet.
-  --tools   outils à brancher (défaut : auto = agents + claude/cursor s'ils sont détectés)
-  --copy    copies au lieu de liens symboliques (aussi la variable KAGENTS_MODE=copy)
-  uninstall retire ce que KAgents a installé (docs/ est conservé)
+À lancer depuis la racine du projet. Dans un terminal, une liste permet de choisir
+les outils à brancher ; le choix est mémorisé dans .kagents/config.json.
+  --tools      outils à brancher, sans question
+  --yes, -y    ne pose pas de question (détection automatique)
+  --configure  pose à nouveau la question
+  --copy       copies au lieu de liens symboliques (aussi KAGENTS_MODE=copy)
+  uninstall    retire ce que KAgents a installé (docs/ est conservé)
 `;
 
 const log = (m) => console.log(`kagents: ${m}`);
@@ -51,12 +59,14 @@ const die = (m) => {
 
 // --- Arguments ----------------------------------------------------------------
 function parseArgs(argv) {
-  const o = { cmd: 'install', tools: 'auto', copy: process.env.KAGENTS_MODE === 'copy' };
+  const o = { cmd: 'install', tools: null, yes: false, configure: false, copy: process.env.KAGENTS_MODE === 'copy' };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '-h' || a === '--help') o.cmd = 'help';
     else if (a === '-v' || a === '--version') o.cmd = 'version';
     else if (a === '--copy') o.copy = true;
+    else if (a === '-y' || a === '--yes') o.yes = true;
+    else if (a === '--configure') o.configure = true;
     else if (a === '--tools') o.tools = argv[++i] || die('--tools attend une valeur');
     else if (a.startsWith('--tools=')) o.tools = a.slice(8);
     else if (a === 'install' || a === 'uninstall') o.cmd = a;
@@ -102,6 +112,7 @@ class Installer {
     this.copy = copy;
     this.kagents = path.join(target, '.kagents');
     this.manifest = path.join(this.kagents, '.installed');
+    this.config = path.join(this.kagents, 'config.json');
     this.entries = [];
   }
 
@@ -266,15 +277,49 @@ Document partagé, écrit par l'utilisateur. Les agents le lisent, ne l'écriven
     fs.writeFileSync(file, out);
   }
 
-  resolveTools(tools) {
-    if (tools !== 'auto') return tools.split(',').filter(Boolean);
-    const t = ['agents'];
+  // Bloc .gitignore : le kit et les liens que l'on a posés, jamais docs/ (sauf les fichiers du kit qui s'y trouvent).
+  gitignoreBlock() {
+    const extra = this.entries.filter((e) => !e.startsWith('.kagents/') || e.startsWith('.kagents/docs/')).sort();
+    return ['# kagents:start', '.kagents/*', '!.kagents/docs/', ...extra, '# kagents:end'].join('\n') + '\n';
+  }
+
+  writeGitignore() {
+    const file = path.join(this.target, '.gitignore');
+    if (!fs.existsSync(file) && !fs.existsSync(path.join(this.target, '.git'))) return;
+    const cur = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const block = this.gitignoreBlock();
+    const out = GITIGNORE_RE.test(cur)
+      ? cur.replace(GITIGNORE_RE, () => block)
+      : (cur && !cur.endsWith('\n') ? cur + '\n' : cur) + (cur ? '\n' : '') + block;
+    fs.writeFileSync(file, out);
+  }
+
+  detectTools() {
     const has = (p) => fs.existsSync(path.join(this.target, p));
+    const t = [];
     if (has('.claude') || has('CLAUDE.md')) t.push('claude');
     if (has('.cursor')) t.push('cursor');
     return t;
   }
 
+  resolveTools(tools) {
+    return tools === 'auto' ? ['agents', ...this.detectTools()] : tools;
+  }
+
+  loadConfig() {
+    try {
+      const c = JSON.parse(fs.readFileSync(this.config, 'utf8'));
+      return Array.isArray(c.tools) ? c.tools : null;
+    } catch {
+      return null;
+    }
+  }
+
+  saveConfig(tools) {
+    fs.mkdirSync(this.kagents, { recursive: true });
+    fs.writeFileSync(this.config, JSON.stringify({ tools }, null, 2) + '\n');
+  }
+
   runAdapters(tools) {
     for (const tool of this.resolveTools(tools)) {
       if (!ADAPTERS[tool]) {
@@ -326,6 +371,7 @@ Document partagé, écrit par l'utilisateur. Les agents le lisent, ne l'écriven
     this.createDocs();
     this.writeAgentsMd();
     this.runAdapters(tools);
+    this.writeGitignore();
     this.saveManifest();
     log(`installé dans ${this.kagents} (${this.copy ? 'copies' : 'liens'})`);
   }
@@ -341,22 +387,125 @@ Document partagé, écrit par l'utilisateur. Les agents le lisent, ne l'écriven
         else fs.rmSync(file);
       }
     }
+    const gi = path.join(this.target, '.gitignore');
+    if (fs.existsSync(gi) && GITIGNORE_RE.test(fs.readFileSync(gi, 'utf8'))) {
+      const out = fs.readFileSync(gi, 'utf8').replace(GITIGNORE_RE, '').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '');
+      if (out) fs.writeFileSync(gi, out + '\n');
+      else fs.rmSync(gi);
+    }
     fs.rmSync(this.manifest, { force: true });
+    fs.rmSync(this.config, { force: true });
     this.prune(removed);
     log('désinstallé (.kagents/docs/ conservé : ce sont vos livrables)');
   }
 }
 
+// --- Question interactive -----------------------------------------------------
+// Terminal utilisable : le nôtre, ou /dev/tty quand on est lancé par un postinstall (stdin/stdout détournés).
+function openTTY() {
+  if (process.stdin.isTTY && process.stdout.isTTY) return { input: process.stdin, output: process.stdout, close() {} };
+  if (process.env.KAGENTS_FROM_POSTINSTALL && process.platform !== 'win32') {
+    try {
+      const rfd = fs.openSync('/dev/tty', 'r');
+      const wfd = fs.openSync('/dev/tty', 'w');
+      const input = new tty.ReadStream(rfd);
+      const output = new tty.WriteStream(wfd);
+      return { input, output, close: () => { input.destroy(); output.destroy(); } };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// Liste à cocher : ↑↓ déplacer, espace cocher, a tout, entrée valider. Renvoie les ids cochés.
+function multiselect(io, message, items) {
+  return new Promise((resolve) => {
+    const { input, output } = io;
+    const state = items.map((i) => ({ ...i }));
+    let cur = 0;
+    let drawn = false;
+    const draw = () => {
+      if (drawn) output.write(`\x1b[${state.length + 1}A`);
+      drawn = true;
+      output.write(`\x1b[2K\x1b[1m?\x1b[0m ${message}\n`);
+      state.forEach((it, i) => {
+        const box = it.checked ? '\x1b[32m◉\x1b[0m' : '◯';
+        output.write(`\x1b[2K ${i === cur ? '\x1b[36m❯\x1b[0m' : ' '} ${box} ${it.label}\n`);
+      });
+    };
+    const finish = () => {
+      input.removeListener('keypress', onKey);
+      input.setRawMode(false);
+      input.pause();
+      output.write('\x1b[?25h');
+      io.close();
+      resolve(state.filter((i) => i.checked).map((i) => i.id));
+    };
+    const onKey = (str, key = {}) => {
+      if (key.ctrl && key.name === 'c') {
+        output.write('\x1b[?25h\n');
+        process.exit(130);
+      }
+      if (key.name === 'up') cur = (cur + state.length - 1) % state.length;
+      else if (key.name === 'down') cur = (cur + 1) % state.length;
+      else if (key.name === 'space') state[cur].checked = !state[cur].checked;
+      else if (key.name === 'a') {
+        const all = state.every((i) => i.checked);
+        state.forEach((i) => (i.checked = !all));
+      } else if (key.name === 'return') {
+        draw();
+        return finish();
+      }
+      draw();
+    };
+    readline.emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    output.write('\x1b[?25l');
+    input.on('keypress', onKey);
+    draw();
+  });
+}
+
+async function chooseTools(inst, o) {
+  if (o.tools) {
+    const t = o.tools === 'auto' ? 'auto' : o.tools === 'none' ? [] : o.tools.split(',').filter(Boolean);
+    if (t !== 'auto') inst.chosen = t;
+    return t;
+  }
+  if (!o.configure) {
+    const saved = inst.loadConfig();
+    if (saved) return saved;
+  }
+  if (!o.yes && !process.env.KAGENTS_NO_PROMPT && !process.env.CI) {
+    const io = openTTY();
+    if (io) {
+      const detected = inst.detectTools();
+      const picked = await multiselect(io, 'Pour quels outils installer KAgents ?  (↑↓ espace a entrée)', [
+        { id: 'claude', label: 'Claude Code  (.claude/commands, .claude/agents)', checked: detected.includes('claude') },
+        { id: 'cursor', label: 'Cursor  (.cursor/commands, .cursor/agents, .cursor/rules)', checked: detected.includes('cursor') },
+        { id: 'agents', label: 'Codex et autres outils AGENTS.md  (.agents/skills)', checked: true },
+      ]);
+      inst.chosen = picked;
+      return picked;
+    }
+  }
+  return 'auto';
+}
+
 // --- Main ---------------------------------------------------------------------
-function main() {
+async function main() {
   const o = parseArgs(process.argv.slice(2));
   if (o.cmd === 'help') return console.log(HELP);
   if (o.cmd === 'version') return console.log(PKG.version);
   const target = process.cwd();
   if (path.resolve(target) === PKG_ROOT) die("à lancer depuis la racine d'un projet, pas depuis le kit.");
   const inst = new Installer(target, o.copy);
-  if (o.cmd === 'uninstall') inst.uninstall();
-  else inst.install(o.tools);
+  if (o.cmd === 'uninstall') return inst.uninstall();
+  const tools = await chooseTools(inst, o);
+  inst.install(tools);
+  if (inst.chosen) inst.saveConfig(inst.chosen);
 }
 
 main();

package/bin/postinstall.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+'use strict';
+// Lancé par npm/pnpm après `add @dev-kosaly/kagents` : installe le kit dans le projet.
+// Ne doit jamais faire échouer l'installation des dépendances.
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const pkgRoot = path.resolve(__dirname, '..');
+const project = process.env.INIT_CWD;
+
+const skip = (why) => {
+  if (why) console.log(`kagents: installation automatique ignorée (${why}). Lancez : npx kagents`);
+  process.exit(0);
+};
+
+if (process.env.KAGENTS_SKIP_POSTINSTALL) skip();
+if (!project) skip();
+if (process.env.npm_config_global === 'true') skip('installation globale');
+if (!pkgRoot.split(path.sep).includes('node_modules')) skip(); // développement du kit lui-même
+if (path.resolve(project) === pkgRoot) skip();
+
+try {
+  spawnSync(process.execPath, [path.join(__dirname, 'kagents.js')], { cwd: project, stdio: 'inherit', env: { ...process.env, KAGENTS_FROM_POSTINSTALL: '1' } });
+} catch {
+  /* jamais bloquant */
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-kosaly/kagents",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Kit d'agents IA d'ingénierie installable dans un projet (Claude Code, Cursor, AGENTS.md)",
   "bin": {
     "kagents": "bin/kagents.js"
@@ -29,6 +29,7 @@
     "access": "public"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.js",
     "test": "node scripts/smoke-test.js",
     "prepublishOnly": "npm test"
   },