@piecemaker-legal/piecemaker 1.0.0

package/server/piecemaker/vendor/installer/lib/desktop-launcher.mjs

@@ -0,0 +1,305 @@
+/**
+ * Raccourci Bureau et gestionnaire du protocole local `piecemaker:`.
+ *
+ * Le raccourci lance `piecemaker open` : le serveur est donc démarré avant
+ * l'ouverture de l'administration. Le gestionnaire de protocole, lui, lance
+ * seulement `piecemaker start`; la page PWA hors ligne peut ainsi redémarrer
+ * le serveur sans ouvrir une seconde fenêtre.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { HOME_DIR, REPO_ROOT, runCapture } from './platform.mjs';
+
+const MAC_REGISTER = '/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister';
+const DEFAULT_ICNS = path.join(REPO_ROOT, 'installer', 'assets', 'piecemaker.icns');
+const DEFAULT_ICO = path.join(REPO_ROOT, 'installer', 'assets', 'piecemaker.ico');
+const DEFAULT_PNG = path.join(REPO_ROOT, 'admin', 'icons', 'icon-512.png');
+const SWIFT_SOURCE = path.join(REPO_ROOT, 'installer', 'assets', 'PieceMakerApp.swift');
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function powershellQuote(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function desktopEntryQuote(value) {
+  return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('$', '\\$').replaceAll('`', '\\`')}"`;
+}
+
+function commandSucceeded(result) {
+  return !result?.error && result?.code === 0;
+}
+
+function writeFile(file, content, mode = 0o644) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, { encoding: 'utf8', mode });
+  fs.chmodSync(file, mode);
+}
+
+function desktopDirectoryForLinux(homeDir) {
+  const config = path.join(homeDir, '.config', 'user-dirs.dirs');
+  try {
+    const match = fs.readFileSync(config, 'utf8').match(/^XDG_DESKTOP_DIR="([^"]+)"/m);
+    if (match) return match[1].replace('$HOME', homeDir);
+  } catch {}
+  return path.join(homeDir, 'Desktop');
+}
+
+function resolveDesktopDirectory({ platform, homeDir, desktopDir, commandRunner }) {
+  if (desktopDir) return desktopDir;
+  if (platform === 'win32') {
+    const result = commandRunner('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      '[Environment]::GetFolderPath("Desktop")',
+    ]);
+    if (commandSucceeded(result) && result.stdout) return result.stdout.trim();
+  }
+  if (platform === 'linux') return desktopDirectoryForLinux(homeDir);
+  return path.join(homeDir, 'Desktop');
+}
+
+export function desktopLauncherPaths({
+  platform = process.platform,
+  homeDir = os.homedir(),
+  runtimeDir = HOME_DIR,
+  desktopDir,
+  commandRunner = runCapture,
+} = {}) {
+  const desktop = resolveDesktopDirectory({ platform, homeDir, desktopDir, commandRunner });
+  if (platform === 'darwin') {
+    return {
+      shortcut: path.join(desktop, 'PieceMaker.app'),
+      protocol: path.join(runtimeDir, 'launcher', 'PieceMaker Protocol.app'),
+    };
+  }
+  if (platform === 'win32') {
+    return {
+      shortcut: path.join(desktop, 'PieceMaker.lnk'),
+      protocol: 'HKCU\\Software\\Classes\\piecemaker',
+    };
+  }
+  return {
+    shortcut: path.join(desktop, 'PieceMaker.desktop'),
+    protocol: path.join(homeDir, '.local', 'share', 'applications', 'piecemaker-protocol.desktop'),
+  };
+}
+
+function macPlist({ executable, identifier, protocol = false, nativeApp = false }) {
+  const protocolBlock = protocol ? `
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key><string>PieceMaker</string>
+      <key>CFBundleURLSchemes</key><array><string>piecemaker</string></array>
+    </dict>
+  </array>` : '';
+  const uiElement = nativeApp ? '' : '\n  <key>LSUIElement</key><true/>';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDisplayName</key><string>PieceMaker</string>
+  <key>CFBundleExecutable</key><string>${executable}</string>
+  <key>CFBundleIconFile</key><string>piecemaker.icns</string>
+  <key>CFBundleIdentifier</key><string>${identifier}</string>
+  <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>CFBundleVersion</key><string>1</string>${uiElement}${protocolBlock}
+</dict>
+</plist>
+`;
+}
+
+function createMacShellApplication(target, {
+  verb,
+  identifier,
+  protocol = false,
+  nodePath,
+  cliPath,
+  runtimeDir,
+  iconPath,
+}) {
+  const executable = 'PieceMaker';
+  const contents = path.join(target, 'Contents');
+  const executablePath = path.join(contents, 'MacOS', executable);
+  const logPath = path.join(runtimeDir, 'desktop-launcher.log');
+  const script = `#!/bin/sh\n${shellQuote(nodePath)} ${shellQuote(cliPath)} ${verb} >>${shellQuote(logPath)} 2>&1 &\nexit 0\n`;
+  writeFile(executablePath, script, 0o755);
+  writeFile(path.join(contents, 'Info.plist'), macPlist({ executable, identifier, protocol }));
+  fs.mkdirSync(path.join(contents, 'Resources'), { recursive: true });
+  fs.copyFileSync(iconPath, path.join(contents, 'Resources', 'piecemaker.icns'));
+}
+
+function createMacNativeApplication(target, { identifier, nodePath, cliPath, iconPath, commandRunner }) {
+  const executable = 'PieceMaker';
+  const contents = path.join(target, 'Contents');
+  const executablePath = path.join(contents, 'MacOS', executable);
+  fs.mkdirSync(path.dirname(executablePath), { recursive: true });
+  const compile = commandRunner('swiftc', [
+    '-o', executablePath,
+    '-framework', 'Cocoa',
+    '-framework', 'WebKit',
+    '-suppress-warnings',
+    SWIFT_SOURCE,
+  ]);
+  if (!commandSucceeded(compile)) {
+    throw new Error(`Compilation Swift impossible : ${compile.stderr || compile.error?.message || `code ${compile.code}`}`);
+  }
+  fs.chmodSync(executablePath, 0o755);
+  const plist = macPlist({ executable, identifier, nativeApp: true });
+  writeFile(path.join(contents, 'Info.plist'), plist);
+  fs.mkdirSync(path.join(contents, 'Resources'), { recursive: true });
+  fs.copyFileSync(iconPath, path.join(contents, 'Resources', 'piecemaker.icns'));
+  const envPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>PIECEMAKER_NODE</key><string>${nodePath}</string>
+  <key>PIECEMAKER_CLI</key><string>${cliPath}</string>
+</dict>
+</plist>
+`;
+  writeFile(path.join(contents, 'Resources', 'environment.plist'), envPlist);
+}
+
+function installMac({ paths, nodePath, cliPath, runtimeDir, iconPath, commandRunner }) {
+  const swiftAvailable = commandSucceeded(commandRunner('which', ['swiftc']));
+  if (swiftAvailable) {
+    createMacNativeApplication(paths.shortcut, {
+      identifier: 'com.piecemaker.desktop',
+      nodePath,
+      cliPath,
+      iconPath,
+      commandRunner,
+    });
+  } else {
+    createMacShellApplication(paths.shortcut, {
+      verb: 'open',
+      identifier: 'com.piecemaker.desktop',
+      nodePath,
+      cliPath,
+      runtimeDir,
+      iconPath,
+    });
+  }
+  createMacShellApplication(paths.protocol, {
+    verb: 'start',
+    identifier: 'com.piecemaker.protocol',
+    protocol: true,
+    nodePath,
+    cliPath,
+    runtimeDir,
+    iconPath,
+  });
+  const registration = commandRunner(MAC_REGISTER, ['-f', paths.protocol]);
+  return {
+    native: swiftAvailable,
+    protocolReady: commandSucceeded(registration),
+    protocolError: registration.stderr || registration.error?.message || '',
+  };
+}
+
+function installWindows({ paths, nodePath, cliPath, repoRoot, iconPath, commandRunner }) {
+  fs.mkdirSync(path.dirname(paths.shortcut), { recursive: true });
+  const script = [
+    '$shell = New-Object -ComObject WScript.Shell',
+    `$shortcut = $shell.CreateShortcut(${powershellQuote(paths.shortcut)})`,
+    `$shortcut.TargetPath = ${powershellQuote(nodePath)}`,
+    `$shortcut.Arguments = ${powershellQuote(`"${cliPath}" open`)}`,
+    `$shortcut.WorkingDirectory = ${powershellQuote(repoRoot)}`,
+    `$shortcut.IconLocation = ${powershellQuote(`${iconPath},0`)}`,
+    "$shortcut.Description = 'Démarrer et ouvrir PieceMaker'",
+    '$shortcut.Save()',
+  ].join('; ');
+  const shortcut = commandRunner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script]);
+  if (!commandSucceeded(shortcut)) {
+    throw new Error(shortcut.stderr || shortcut.error?.message || 'Création du raccourci Windows impossible.');
+  }
+
+  const key = 'HKCU\\Software\\Classes\\piecemaker';
+  const protocolCommand = `"${nodePath}" "${cliPath}" start`;
+  const commands = [
+    [key, '/ve', '/d', 'URL:PieceMaker'],
+    [key, '/v', 'URL Protocol', '/d', ''],
+    [`${key}\\DefaultIcon`, '/ve', '/d', `"${iconPath}",0`],
+    [`${key}\\shell\\open\\command`, '/ve', '/d', protocolCommand],
+  ];
+  const results = commands.map((args) => commandRunner('reg.exe', ['add', ...args, '/f']));
+  const failure = results.find((result) => !commandSucceeded(result));
+  return { protocolReady: !failure, protocolError: failure?.stderr || failure?.error?.message || '' };
+}
+
+function linuxDesktopEntry({ name, comment, nodePath, cliPath, verb, iconPath, protocol = false }) {
+  return `[Desktop Entry]
+Type=Application
+Name=${name}
+Comment=${comment}
+Exec=${desktopEntryQuote(nodePath)} ${desktopEntryQuote(cliPath)} ${verb}
+Icon=${iconPath}
+Terminal=false
+Categories=Office;Utility;
+${protocol ? 'NoDisplay=true\nMimeType=x-scheme-handler/piecemaker;\n' : ''}`;
+}
+
+function installLinux({ paths, nodePath, cliPath, iconPath, commandRunner }) {
+  writeFile(paths.shortcut, linuxDesktopEntry({
+    name: 'PieceMaker',
+    comment: 'Démarrer et ouvrir PieceMaker',
+    nodePath,
+    cliPath,
+    verb: 'open',
+    iconPath,
+  }), 0o755);
+  writeFile(paths.protocol, linuxDesktopEntry({
+    name: 'PieceMaker Protocol',
+    comment: 'Démarrer le serveur local PieceMaker',
+    nodePath,
+    cliPath,
+    verb: 'start',
+    iconPath,
+    protocol: true,
+  }), 0o755);
+  const registration = commandRunner('xdg-mime', ['default', path.basename(paths.protocol), 'x-scheme-handler/piecemaker']);
+  return { protocolReady: commandSucceeded(registration), protocolError: registration.stderr || registration.error?.message || '' };
+}
+
+export function installDesktopLauncher({
+  platform = process.platform,
+  homeDir = os.homedir(),
+  runtimeDir = HOME_DIR,
+  repoRoot = REPO_ROOT,
+  desktopDir,
+  nodePath = process.execPath,
+  commandRunner = runCapture,
+  iconPath,
+} = {}) {
+  const paths = desktopLauncherPaths({ platform, homeDir, runtimeDir, desktopDir, commandRunner });
+  const cliPath = path.join(repoRoot, 'installer', 'bin', 'piecemaker.mjs');
+  let result;
+  if (platform === 'darwin') {
+    result = installMac({ paths, nodePath, cliPath, runtimeDir, iconPath: iconPath || DEFAULT_ICNS, commandRunner });
+  } else if (platform === 'win32') {
+    result = installWindows({ paths, nodePath, cliPath, repoRoot, iconPath: iconPath || DEFAULT_ICO, commandRunner });
+  } else {
+    result = installLinux({ paths, nodePath, cliPath, iconPath: iconPath || DEFAULT_PNG, commandRunner });
+  }
+  return { ...paths, ...result };
+}
+
+export function desktopLauncherStatus(options = {}) {
+  const paths = desktopLauncherPaths(options);
+  const shortcutReady = fs.existsSync(paths.shortcut);
+  const platform = options.platform || process.platform;
+  const protocolReady = platform === 'win32'
+    ? commandSucceeded((options.commandRunner || runCapture)('reg.exe', ['query', paths.protocol, '/v', 'URL Protocol']))
+    : fs.existsSync(paths.protocol);
+  return { ...paths, shortcutReady, protocolReady };
+}

package/server/piecemaker/vendor/installer/lib/legacy-legifrance.mjs

@@ -0,0 +1,72 @@
+/**
+ * Migration — restes de l'ancien serveur MCP Légifrance local.
+ *
+ * Avant l'extraction du runtime vers PieceMaker-Legal/mcp-legifrance, le
+ * serveur vivait dans ce dépôt et tournait en service launchd HTTP local. Sur
+ * une machine déjà installée, cet agent survit à la mise à jour : `KeepAlive`
+ * le relance toutes les 5 s sur un script désormais absent, ce qui recrée sans
+ * fin le dossier de runtime supprimé et gonfle un journal d'erreurs de
+ * plusieurs mégaoctets.
+ *
+ * Ce nettoyage vit dans son propre module plutôt que dans l'étape 07 : l'étape
+ * ne doit décrire que le plugin autonome, et rien d'autre ne doit laisser
+ * croire que le runtime habite encore le dépôt.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from './ui.mjs';
+import { runCapture } from './platform.mjs';
+
+export const LEGACY_SERVICE_LABEL = 'com.piecemaker.mcp-legifrance-local';
+
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** Dossier de runtime hérité, à l'intérieur du dépôt. */
+export function legacyRuntimeDir(root = REPOSITORY_ROOT) {
+  return path.join(root, 'piecemaker-plugin', 'mcp');
+}
+
+/** Fichier launchd hérité, dans le home de l'utilisateur. */
+export function legacyServicePlist(userHome = os.homedir()) {
+  return path.join(userHome, 'Library', 'LaunchAgents', `${LEGACY_SERVICE_LABEL}.plist`);
+}
+
+/**
+ * Retire l'agent launchd — d'abord, sinon il recrée aussitôt ses journaux —,
+ * puis son .plist et le dossier de runtime. Idempotent : sur une machine
+ * installée après l'extraction, rien n'existe et rien n'est fait. Renvoie la
+ * liste de ce qui a été retiré, vide dans le cas courant.
+ */
+export function removeLegacyLegifranceService({
+  userHome = os.homedir(),
+  repositoryRoot = REPOSITORY_ROOT,
+  capture = runCapture,
+  logger = log,
+  platform = process.platform,
+} = {}) {
+  const removed = [];
+  if (platform === 'darwin') {
+    const domain = `gui/${process.getuid()}`;
+    if (capture('launchctl', ['print', `${domain}/${LEGACY_SERVICE_LABEL}`]).code === 0) {
+      capture('launchctl', ['bootout', `${domain}/${LEGACY_SERVICE_LABEL}`]);
+      removed.push('service launchd');
+    }
+    const plist = legacyServicePlist(userHome);
+    if (fs.existsSync(plist)) {
+      fs.rmSync(plist, { force: true });
+      removed.push('fichier .plist');
+    }
+  }
+  const runtime = legacyRuntimeDir(repositoryRoot);
+  if (fs.existsSync(runtime)) {
+    fs.rmSync(runtime, { recursive: true, force: true });
+    removed.push('dossier de runtime hérité');
+  }
+  if (removed.length) {
+    logger.detail(`Ancien serveur MCP Légifrance local nettoyé : ${removed.join(', ')}.`);
+  }
+  return removed;
+}

package/server/piecemaker/vendor/installer/lib/platform.mjs

@@ -0,0 +1,163 @@
+/**
+ * Cross-platform process and toolchain helpers (macOS + Windows + Linux).
+ *
+ * Everything that shells out goes through here so the Windows quirks live in
+ * one place: `.cmd` shims for npm/npx, `python` vs `python3`, and venv layouts
+ * that put binaries in Scripts/ instead of bin/.
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const IS_WINDOWS = process.platform === 'win32';
+export const IS_MAC = process.platform === 'darwin';
+
+/** Repository root, derived from this file's location. */
+export const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..'
+);
+
+/** Root of the git repository this installer is vendored into (server/piecemaker/vendor/../../..). */
+export const GIT_REPO_ROOT = path.resolve(REPO_ROOT, '..', '..', '..');
+
+/** Per-user PieceMaker directory, replacing Electron's userData path. */
+export const HOME_DIR = process.env.PIECEMAKER_HOME || path.join(os.homedir(), '.piecemaker');
+
+/**
+ * Put the directory of the running Node first. npm's launcher uses
+ * `#!/usr/bin/env node`; without this, an older system Node can execute npm
+ * even though PieceMaker itself was started with a recent NVM installation.
+ */
+export function npmEnv(env = process.env) {
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === 'path') || 'PATH';
+  const runtimeBin = path.dirname(process.execPath);
+  const currentPath = env[pathKey] || '';
+  return {
+    ...env,
+    [pathKey]: [runtimeBin, currentPath].filter(Boolean).join(path.delimiter),
+  };
+}
+
+/** npm and npx need the .cmd shim on Windows when spawned without a shell. */
+export function npmBin(name = 'npm') {
+  const executable = IS_WINDOWS ? `${name}.cmd` : name;
+  const adjacent = path.join(path.dirname(process.execPath), executable);
+  return fs.existsSync(adjacent) ? adjacent : executable;
+}
+
+/**
+ * Run a command to completion, streaming nothing.
+ * Returns { code, stdout, stderr } and never throws on a non-zero exit.
+ */
+export function runCapture(command, args = [], options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+    ...options,
+  });
+  return {
+    code: result.status ?? 1,
+    stdout: (result.stdout || '').trim(),
+    stderr: (result.stderr || '').trim(),
+    error: result.error,
+  };
+}
+
+/**
+ * Run a command, forwarding output line by line to `onLine`.
+ * Resolves with the exit code; rejects only if the process cannot be spawned.
+ */
+export function run(command, args = [], { onLine, ...options } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...options,
+    });
+
+    const forward = (stream) => {
+      let buffer = '';
+      stream.setEncoding('utf8');
+      stream.on('data', (chunk) => {
+        buffer += chunk;
+        let index;
+        while ((index = buffer.indexOf('\n')) >= 0) {
+          const line = buffer.slice(0, index).replace(/\r$/, '');
+          buffer = buffer.slice(index + 1);
+          if (line.trim() && onLine) onLine(line);
+        }
+      });
+      stream.on('end', () => {
+        if (buffer.trim() && onLine) onLine(buffer.trim());
+      });
+    };
+
+    if (child.stdout) forward(child.stdout);
+    if (child.stderr) forward(child.stderr);
+
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}
+
+/** True when `command --version` (or the given probe) succeeds. */
+export function commandExists(command, args = ['--version']) {
+  const result = runCapture(command, args);
+  return result.code === 0 && !result.error;
+}
+
+/** Locate a usable Python 3 interpreter, honouring PYTHON_PATH. */
+export function findPython() {
+  const candidates = [
+    process.env.PYTHON_PATH,
+    IS_WINDOWS ? 'python' : 'python3',
+    IS_WINDOWS ? 'python3' : 'python',
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const result = runCapture(candidate, ['--version']);
+    if (result.code !== 0) continue;
+    const version = `${result.stdout} ${result.stderr}`.match(/Python (\d+)\.(\d+)/);
+    if (!version) continue;
+    const [, major, minor] = version.map(Number);
+    if (major === 3 && minor >= 10) {
+      return { command: candidate, version: `${major}.${minor}` };
+    }
+  }
+  return null;
+}
+
+/** Paths inside a virtualenv, which differ on Windows. */
+export function venvPaths(venvDir) {
+  const binDir = path.join(venvDir, IS_WINDOWS ? 'Scripts' : 'bin');
+  return {
+    dir: venvDir,
+    binDir,
+    python: path.join(binDir, IS_WINDOWS ? 'python.exe' : 'python'),
+    pip: path.join(binDir, IS_WINDOWS ? 'pip.exe' : 'pip'),
+    exists: fs.existsSync(path.join(binDir, IS_WINDOWS ? 'python.exe' : 'python')),
+  };
+}
+
+/** Compare semver-ish strings. Returns 1, 0 or -1. */
+export function compareVersions(a, b) {
+  const pa = String(a).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/server/piecemaker/vendor/installer/lib/prompt.mjs

@@ -0,0 +1,138 @@
+/**
+ * Interactive prompts built on node:readline — no dependencies.
+ *
+ * Every prompt honours PIECEMAKER_YES=1 (accept defaults, never block), which
+ * is what the non-interactive install path and CI use.
+ */
+
+import readline from 'node:readline';
+import { c, write, blank } from './ui.mjs';
+
+const AUTO = process.env.PIECEMAKER_YES === '1' || !process.stdin.isTTY;
+
+export const nonInteractive = AUTO;
+
+function createInterface() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+
+/** Free-text question with an optional default. */
+export async function ask(question, { def = '', required = false } = {}) {
+  if (AUTO) return def;
+  const suffix = def ? c.gray(` [${def}]`) : '';
+  for (;;) {
+    const rl = createInterface();
+    const answer = await new Promise((resolve) =>
+      rl.question(`  ${c.cyan('?')} ${question}${suffix} `, (a) => {
+        rl.close();
+        resolve(a.trim());
+      })
+    );
+    const value = answer || def;
+    if (value || !required) return value;
+    write(`  ${c.yellow('!')} Une valeur est requise.`);
+  }
+}
+
+/** Yes/no question. Default is applied on an empty answer. */
+export async function confirm(question, def = true) {
+  if (AUTO) return def;
+  const hint = def ? 'O/n' : 'o/N';
+  const rl = createInterface();
+  const answer = await new Promise((resolve) =>
+    rl.question(`  ${c.cyan('?')} ${question} ${c.gray(`[${hint}]`)} `, (a) => {
+      rl.close();
+      resolve(a.trim().toLowerCase());
+    })
+  );
+  if (!answer) return def;
+  return answer === 'o' || answer === 'oui' || answer === 'y' || answer === 'yes';
+}
+
+/**
+ * Secret input. Echo is suppressed on a TTY; on a non-TTY the value can only
+ * come from the environment, which is the documented CI path.
+ */
+export async function secret(question) {
+  if (AUTO) return '';
+  return new Promise((resolve) => {
+    const rl = createInterface();
+    const onData = (char) => {
+      const s = String(char);
+      if (s === '\n' || s === '\r' || s === '') {
+        process.stdin.removeListener('data', onData);
+        return;
+      }
+      readline.clearLine(process.stdout, 0);
+      readline.cursorTo(process.stdout, 0);
+      process.stdout.write(`  ${c.cyan('?')} ${question} `);
+    };
+    process.stdin.on('data', onData);
+    rl.question(`  ${c.cyan('?')} ${question} `, (value) => {
+      process.stdin.removeListener('data', onData);
+      rl.close();
+      blank();
+      resolve(value.trim());
+    });
+  });
+}
+
+/**
+ * Single-choice menu.
+ * `choices` is an array of { value, label, hint }. Returns the chosen value.
+ */
+export async function select(question, choices, { def = 0 } = {}) {
+  if (AUTO) return choices[def].value;
+  blank();
+  write(`  ${c.bold(question)}`);
+  blank();
+  choices.forEach((choice, i) => {
+    const num = c.cyan(String(i + 1).padStart(2));
+    const hint = choice.hint ? c.gray(`  ${choice.hint}`) : '';
+    write(`  ${num}. ${choice.label}${hint}`);
+  });
+  blank();
+  for (;;) {
+    const answer = await ask('Votre choix', { def: String(def + 1) });
+    const index = Number.parseInt(answer, 10) - 1;
+    if (Number.isInteger(index) && index >= 0 && index < choices.length) {
+      return choices[index].value;
+    }
+    write(`  ${c.yellow('!')} Choix invalide.`);
+  }
+}
+
+/**
+ * Multi-choice menu. Accepts "1,3,5", "1 3 5", "tout" or "aucun".
+ * Returns an array of values.
+ */
+export async function multiSelect(question, choices, { def = [] } = {}) {
+  if (AUTO) return def;
+  blank();
+  write(`  ${c.bold(question)}`);
+  write(`  ${c.gray('Numéros séparés par des virgules, "tout", ou Entrée pour la sélection par défaut.')}`);
+  blank();
+  choices.forEach((choice, i) => {
+    const mark = def.includes(choice.value) ? c.green('•') : ' ';
+    const num = c.cyan(String(i + 1).padStart(2));
+    const hint = choice.hint ? c.gray(`  ${choice.hint}`) : '';
+    write(`  ${mark} ${num}. ${choice.label}${hint}`);
+  });
+  blank();
+  const answer = await ask('Votre sélection', { def: 'tout' });
+  const normalized = answer.toLowerCase();
+  if (normalized === 'tout' || normalized === 'all') return choices.map((ch) => ch.value);
+  if (normalized === 'aucun' || normalized === 'none') return [];
+  const picked = normalized
+    .split(/[,\s]+/)
+    .map((n) => Number.parseInt(n, 10) - 1)
+    .filter((i) => Number.isInteger(i) && i >= 0 && i < choices.length)
+    .map((i) => choices[i].value);
+  return picked.length ? picked : def;
+}
+
+/** Wait for Enter. No-op when non-interactive. */
+export async function pause(message = 'Appuyez sur Entrée pour continuer') {
+  if (AUTO) return;
+  await ask(message);
+}