@misterhuydo/sentinel 1.2.8 → 1.3.0

package/lib/add.js

@@ -1,415 +1,470 @@
-'use strict';
-
-const fs = require('fs-extra');
-const path = require('path');
-const os = require('os');
-const { execSync, spawnSync } = require('child_process');
-const prompts = require('prompts');
-const chalk = require('chalk');
-const { writeExampleProject, generateWorkspaceScripts, generateProjectScripts } = require('./generate');
-
-const ok   = msg => console.log(chalk.green('  ✔'), msg);
-const info = msg => console.log(chalk.cyan('  →'), msg);
-const warn = msg => console.log(chalk.yellow('  ⚠'), msg);
-const step = msg => console.log('\n' + chalk.bold.white(msg));
-
-// ── Input type detection ───────────────────────────────────────────────────
-
-function detectInputType(arg) {
-  if (!arg) return 'name';
-  if (/^git@/.test(arg) || (/^https?:\/\/github\.com\//.test(arg) && arg.endsWith('.git'))) return 'git';
-  if (/^https?:\/\//.test(arg)) return 'url';
-  if (arg.toLowerCase().endsWith('.json') || arg.includes('/') || arg.includes('\\')) return 'json';
-  return 'name';
-}
-
-// ── Workspace resolver ─────────────────────────────────────────────────────
-
-async function resolveWorkspace(initial) {
-  const ans = await prompts([{
-    type: 'text',
-    name: 'workspace',
-    message: 'Workspace directory',
-    initial: initial || path.join(os.homedir(), 'sentinel'),
-    format: v => v.replace(/^~/, os.homedir()),
-  }], { onCancel: () => process.exit(0) });
-  return ans.workspace;
-}
-
-function requireCodeDir(workspace) {
-  const codeDir = path.join(workspace, 'code');
-  if (!fs.existsSync(codeDir)) {
-    console.error(chalk.red(`Sentinel code not found at ${codeDir}`));
-    console.error(chalk.red('Run "sentinel init" first.'));
-    process.exit(1);
-  }
-  return codeDir;
-}
-
-// ── Validation ─────────────────────────────────────────────────────────────
-
-const VALID_NAME = /^[a-z0-9_-]+$/i;
-const GITHUB_URL = /^(git@github\.com:|https:\/\/github\.com\/).+\.git$/;
-
-function validateProjectJson(obj) {
-  const errors = [];
-  if (!obj.name || !VALID_NAME.test(obj.name)) {
-    errors.push('name must be letters, numbers, hyphens only');
-  }
-  if (!Array.isArray(obj.repos) || obj.repos.length === 0) {
-    errors.push('repos array is required and must be non-empty');
-  } else {
-    obj.repos.forEach((r, i) => {
-      if (!r.REPO_URL || !GITHUB_URL.test(r.REPO_URL)) {
-        errors.push(`repos[${i}].REPO_URL must be a valid GitHub URL`);
-      }
-      if (!r.name) errors.push(`repos[${i}].name is required`);
-    });
-  }
-  return errors;
-}
-
-// ── Properties file writer ─────────────────────────────────────────────────
-
-function writePropertiesFile(filePath, obj) {
-  const lines = Object.entries(obj).map(([k, v]) => `${k}=${v}`);
-  fs.writeFileSync(filePath, lines.join('\n') + '\n');
-}
-
-// ── Apply JSON config to a project directory ───────────────────────────────
-
-function applyJsonToProject(projectDir, obj) {
-  const configDir  = path.join(projectDir, 'config');
-  const repoDir    = path.join(projectDir, 'config', 'repo-configs');
-  const logDir     = path.join(projectDir, 'config', 'log-configs');
-  fs.ensureDirSync(repoDir);
-  fs.ensureDirSync(logDir);
-
-  // sentinel.properties overrides
-  if (obj.sentinel) {
-    const propsPath = path.join(configDir, 'sentinel.properties');
-    const existing = fs.existsSync(propsPath) ? fs.readFileSync(propsPath, 'utf8') : '';
-    let updated = existing;
-    Object.entries(obj.sentinel).forEach(([k, v]) => {
-      const re = new RegExp(`^#?\\s*${k}\\s*=.*$`, 'm');
-      if (re.test(updated)) {
-        updated = updated.replace(re, `${k}=${v}`);
-      } else {
-        updated += `\n${k}=${v}`;
-      }
-    });
-    fs.writeFileSync(propsPath, updated);
-    ok('Updated sentinel.properties');
-  }
-
-  // repo-configs
-  if (Array.isArray(obj.repos)) {
-    obj.repos.forEach(repo => {
-      const { name, ...props } = repo;
-      writePropertiesFile(path.join(repoDir, `${name}.properties`), props);
-      ok(`Created repo-configs/${name}.properties`);
-    });
-  }
-
-  // log-configs (optional)
-  if (Array.isArray(obj.log_sources)) {
-    obj.log_sources.forEach(src => {
-      const { name, ...props } = src;
-      writePropertiesFile(path.join(logDir, `${name}.properties`), props);
-      ok(`Created log-configs/${name}.properties`);
-    });
-  }
-}
-
-// ── URL fetcher ────────────────────────────────────────────────────────────
-
-function fetchUrl(url) {
-  try {
-    const result = spawnSync('curl', ['-fsSL', '--max-time', '10', url], { encoding: 'utf8' });
-    if (result.status !== 0) throw new Error(result.stderr || 'curl failed');
-    return result.stdout;
-  } catch (_) {
-    // fallback: node https
-    const https = require('https');
-    const http  = require('http');
-    const lib   = url.startsWith('https') ? https : http;
-    return new Promise((resolve, reject) => {
-      lib.get(url, res => {
-        let data = '';
-        res.on('data', c => (data += c));
-        res.on('end', () => resolve(data));
-      }).on('error', reject);
-    });
-  }
-}
-
-// ── Mode: name (template) ──────────────────────────────────────────────────
-
-async function addFromName(nameArg, workspace) {
-  const answers = await prompts([{
-    type: 'text',
-    name: 'name',
-    message: 'Project name',
-    initial: nameArg || 'my-project',
-    validate: v => VALID_NAME.test(v) || 'Use letters, numbers, hyphens only',
-  }], { onCancel: () => process.exit(0) });
-
-  const { name } = answers;
-  const projectDir = path.join(workspace, name);
-
-  step('Dry-run preview');
-  info(`Will create: ${projectDir}/`);
-  info('  config/sentinel.properties');
-  info('  config/repo-configs/_example.properties');
-  info('  config/log-configs/_example.properties');
-  info('  init.sh, start.sh, stop.sh');
-
-  const { confirm } = await prompts({
-    type: 'confirm', name: 'confirm',
-    message: `Create project "${name}"?`, initial: true,
-  }, { onCancel: () => process.exit(0) });
-  if (!confirm) { info('Aborted.'); return; }
-
-  if (fs.existsSync(projectDir)) {
-    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
-    process.exit(1);
-  }
-
-  const codeDir  = requireCodeDir(workspace);
-  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
-  writeExampleProject(projectDir, codeDir, pythonBin);
-  generateWorkspaceScripts(workspace);
-
-  ok(`Project "${name}" created at ${projectDir}`);
-  printNextSteps(projectDir);
-}
-
-// ── Mode: git URL ──────────────────────────────────────────────────────────
-
-async function addFromGit(gitUrl, workspace) {
-  // Derive project name from repo name
-  const repoSlug  = gitUrl.replace(/\.git$/, '').split(/[:/]/).pop();
-  const answers = await prompts([{
-    type: 'text',
-    name: 'name',
-    message: 'Project name',
-    initial: repoSlug,
-    validate: v => VALID_NAME.test(v) || 'Use letters, numbers, hyphens only',
-  }], { onCancel: () => process.exit(0) });
-
-  const { name } = answers;
-  const projectDir = path.join(workspace, name);
-  const localPath  = path.join(workspace, 'repos', repoSlug);
-
-  step('Dry-run: validating git URL');
-  info(`Running: git ls-remote ${gitUrl}`);
-  const result = spawnSync('git', ['ls-remote', '--heads', gitUrl], { encoding: 'utf8', timeout: 15000 });
-  if (result.status !== 0) {
-    console.error(chalk.red(`  ✖ Cannot reach repository: ${gitUrl}`));
-    console.error(chalk.red(`    ${result.stderr || 'git ls-remote failed'}`));
-    process.exit(1);
-  }
-  ok('Repository is reachable');
-
-  const branches = (result.stdout || '').split('\n')
-    .filter(Boolean).map(l => l.split('\t')[1].replace('refs/heads/', ''));
-  const defaultBranch = branches.includes('main') ? 'main' : (branches[0] || 'main');
-  info(`Detected default branch: ${defaultBranch}`);
-
-  step('Dry-run preview');
-  info(`Will create: ${projectDir}/`);
-  info(`  config/repo-configs/${repoSlug}.properties`);
-  info(`    REPO_URL=${gitUrl}`);
-  info(`    LOCAL_PATH=${localPath}`);
-  info(`    BRANCH=${defaultBranch}`);
-  info('  init.sh, start.sh, stop.sh');
-
-  const { confirm } = await prompts({
-    type: 'confirm', name: 'confirm',
-    message: `Create project "${name}" for ${gitUrl}?`, initial: true,
-  }, { onCancel: () => process.exit(0) });
-  if (!confirm) { info('Aborted.'); return; }
-
-  if (fs.existsSync(projectDir)) {
-    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
-    process.exit(1);
-  }
-
-  const codeDir   = requireCodeDir(workspace);
-  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
-
-  writeExampleProject(projectDir, codeDir, pythonBin);
-
-  // Write the actual repo config (overwrite the example)
-  const repoDir = path.join(projectDir, 'config', 'repo-configs');
-  writePropertiesFile(path.join(repoDir, `${repoSlug}.properties`), {
-    REPO_NAME: repoSlug,
-    REPO_URL: gitUrl,
-    LOCAL_PATH: localPath,
-    BRANCH: defaultBranch,
-    AUTO_PUBLISH: 'false',
-    CAIRN_MCP_ENABLED: 'true',
-  });
-  // Remove the _example placeholder
-  const example = path.join(repoDir, '_example.properties');
-  if (fs.existsSync(example)) fs.removeSync(example);
-
-  generateWorkspaceScripts(workspace);
-  ok(`Project "${name}" created at ${projectDir}`);
-  printNextSteps(projectDir);
-}
-
-// ── Mode: local JSON ───────────────────────────────────────────────────────
-
-async function addFromJson(jsonPath, workspace) {
-  step(`Reading ${jsonPath}`);
-  let obj;
-  try {
-    obj = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
-  } catch (e) {
-    console.error(chalk.red(`  ✖ Cannot parse ${jsonPath}: ${e.message}`));
-    process.exit(1);
-  }
-
-  const errors = validateProjectJson(obj);
-  if (errors.length) {
-    console.error(chalk.red('  ✖ Invalid project JSON:'));
-    errors.forEach(e => console.error(chalk.red(`    - ${e}`)));
-    process.exit(1);
-  }
-  ok('JSON is valid');
-
-  const { name } = obj;
-  const projectDir = path.join(workspace, name);
-
-  step('Dry-run preview');
-  info(`Will create: ${projectDir}/`);
-  (obj.repos || []).forEach(r => info(`  config/repo-configs/${r.name}.properties  (${r.REPO_URL})`));
-  (obj.log_sources || []).forEach(s => info(`  config/log-configs/${s.name}.properties  (${s.SOURCE_TYPE})`));
-  if (obj.sentinel) {
-    Object.entries(obj.sentinel).forEach(([k, v]) => info(`  sentinel.properties: ${k}=${v}`));
-  }
-
-  const { confirm } = await prompts({
-    type: 'confirm', name: 'confirm',
-    message: `Create project "${name}" from ${path.basename(jsonPath)}?`, initial: true,
-  }, { onCancel: () => process.exit(0) });
-  if (!confirm) { info('Aborted.'); return; }
-
-  if (fs.existsSync(projectDir)) {
-    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
-    process.exit(1);
-  }
-
-  const codeDir   = requireCodeDir(workspace);
-  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
-
-  writeExampleProject(projectDir, codeDir, pythonBin);
-
-  // Remove example placeholders before writing real configs
-  const repoDir = path.join(projectDir, 'config', 'repo-configs');
-  const logDir  = path.join(projectDir, 'config', 'log-configs');
-  const exampleRepo = path.join(repoDir, '_example.properties');
-  const exampleLog  = path.join(logDir,  '_example.properties');
-  if (fs.existsSync(exampleRepo)) fs.removeSync(exampleRepo);
-  if (fs.existsSync(exampleLog))  fs.removeSync(exampleLog);
-
-  applyJsonToProject(projectDir, obj);
-  generateWorkspaceScripts(workspace);
-  ok(`Project "${name}" created at ${projectDir}`);
-  printNextSteps(projectDir);
-}
-
-// ── Mode: remote URL ───────────────────────────────────────────────────────
-
-async function addFromUrl(url, workspace) {
-  step(`Fetching ${url}`);
-  let raw;
-  try {
-    raw = fetchUrl(url);
-    if (raw && typeof raw.then === 'function') raw = await raw;
-  } catch (e) {
-    console.error(chalk.red(`  ✖ Cannot fetch ${url}: ${e.message}`));
-    process.exit(1);
-  }
-
-  let obj;
-  try {
-    obj = JSON.parse(raw);
-  } catch (e) {
-    console.error(chalk.red(`  ✖ Response is not valid JSON: ${e.message}`));
-    process.exit(1);
-  }
-
-  const errors = validateProjectJson(obj);
-  if (errors.length) {
-    console.error(chalk.red('  ✖ Invalid project JSON at URL:'));
-    errors.forEach(e => console.error(chalk.red(`    - ${e}`)));
-    process.exit(1);
-  }
-  ok('JSON is valid');
-
-  const { name } = obj;
-  const projectDir = path.join(workspace, name);
-
-  step('Dry-run preview');
-  info(`Will create: ${projectDir}/`);
-  (obj.repos || []).forEach(r => info(`  config/repo-configs/${r.name}.properties  (${r.REPO_URL})`));
-  (obj.log_sources || []).forEach(s => info(`  config/log-configs/${s.name}.properties  (${s.SOURCE_TYPE})`));
-  if (obj.sentinel) {
-    Object.entries(obj.sentinel).forEach(([k, v]) => info(`  sentinel.properties: ${k}=${v}`));
-  }
-
-  const { confirm } = await prompts({
-    type: 'confirm', name: 'confirm',
-    message: `Create project "${name}" from ${url}?`, initial: true,
-  }, { onCancel: () => process.exit(0) });
-  if (!confirm) { info('Aborted.'); return; }
-
-  if (fs.existsSync(projectDir)) {
-    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
-    process.exit(1);
-  }
-
-  const codeDir   = requireCodeDir(workspace);
-  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
-
-  writeExampleProject(projectDir, codeDir, pythonBin);
-
-  const repoDir = path.join(projectDir, 'config', 'repo-configs');
-  const logDir  = path.join(projectDir, 'config', 'log-configs');
-  const exampleRepo = path.join(repoDir, '_example.properties');
-  const exampleLog  = path.join(logDir,  '_example.properties');
-  if (fs.existsSync(exampleRepo)) fs.removeSync(exampleRepo);
-  if (fs.existsSync(exampleLog))  fs.removeSync(exampleLog);
-
-  applyJsonToProject(projectDir, obj);
-  generateWorkspaceScripts(workspace);
-  ok(`Project "${name}" created at ${projectDir}`);
-  printNextSteps(projectDir);
-}
-
-// ── Helper ─────────────────────────────────────────────────────────────────
-
-function printNextSteps(projectDir) {
-  console.log(`
-  Next steps:
-    1. Edit config files in:
-       ${chalk.cyan(`${projectDir}/config/`)}
-    2. Start (Sentinel clones, indexes, and monitors automatically):
-       ${chalk.cyan(`${projectDir}/start.sh`)}
-`);
-}
-
-// ── Entry point ────────────────────────────────────────────────────────────
-
-module.exports = async function add(arg) {
-  const type = detectInputType(arg);
-
-  const workspace = await resolveWorkspace();
-
-  if (type === 'git')  return addFromGit(arg, workspace);
-  if (type === 'url')  return addFromUrl(arg, workspace);
-  if (type === 'json') return addFromJson(arg, workspace);
-  return addFromName(arg, workspace);
-};
+'use strict';
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const { execSync, spawnSync } = require('child_process');
+const prompts = require('prompts');
+const chalk = require('chalk');
+const { writeExampleProject, generateWorkspaceScripts, generateProjectScripts } = require('./generate');
+const ok   = msg => console.log(chalk.green('  ✔'), msg);
+const info = msg => console.log(chalk.cyan('  →'), msg);
+const warn = msg => console.log(chalk.yellow('  ⚠'), msg);
+const step = msg => console.log('\n' + chalk.bold.white(msg));
+
+function detectInputType(arg) {
+  if (!arg) return 'name';
+  if (/^git@/.test(arg) || (/^https?:\/\/github\.com\//.test(arg) && arg.endsWith('.git'))) return 'git';
+  if (/^https?:\/\//.test(arg)) return 'url';
+  if (arg.toLowerCase().endsWith('.json') || arg.includes('/') || arg.includes('\\')) return 'json';
+  return 'name';
+}
+
+async function resolveWorkspace(initial) {
+  const ans = await prompts([{
+    type: 'text',
+    name: 'workspace',
+    message: 'Workspace directory',
+    initial: initial || path.join(os.homedir(), 'sentinel'),
+    format: v => v.replace(/^~/, os.homedir()),
+  }], { onCancel: () => process.exit(0) });
+  return ans.workspace;
+}
+
+function requireCodeDir(workspace) {
+  const codeDir = path.join(workspace, 'code');
+  if (!fs.existsSync(codeDir)) {
+    console.error(chalk.red(`Sentinel code not found at ${codeDir}`));
+    console.error(chalk.red('Run "sentinel init" first.'));
+    process.exit(1);
+  }
+  return codeDir;
+}
+
+const VALID_NAME = /^[a-z0-9_-]+$/i;
+const GITHUB_URL = /^(git@github\.com:|https:\/\/github\.com\/).+\.git$/;
+
+function validateProjectJson(obj) {
+  const errors = [];
+  if (!obj.name || !VALID_NAME.test(obj.name)) {
+    errors.push('name must be letters, numbers, hyphens only');
+  }
+  if (!Array.isArray(obj.repos) || obj.repos.length === 0) {
+    errors.push('repos array is required and must be non-empty');
+  } else {
+    obj.repos.forEach((r, i) => {
+      if (!r.REPO_URL || !GITHUB_URL.test(r.REPO_URL)) {
+        errors.push(`repos[${i}].REPO_URL must be a valid GitHub URL`);
+      }
+      if (!r.name) errors.push(`repos[${i}].name is required`);
+    });
+  }
+  return errors;
+}
+
+function writePropertiesFile(filePath, obj) {
+  const lines = Object.entries(obj).map(([k, v]) => `${k}=${v}`);
+  fs.writeFileSync(filePath, lines.join('\n') + '\n');
+}
+
+function applyJsonToProject(projectDir, obj) {
+  const configDir  = path.join(projectDir, 'config');
+  const repoDir    = path.join(projectDir, 'config', 'repo-configs');
+  const logDir     = path.join(projectDir, 'config', 'log-configs');
+  fs.ensureDirSync(repoDir);
+  fs.ensureDirSync(logDir);
+  if (obj.sentinel) {
+    const propsPath = path.join(configDir, 'sentinel.properties');
+    const existing = fs.existsSync(propsPath) ? fs.readFileSync(propsPath, 'utf8') : '';
+    let updated = existing;
+    Object.entries(obj.sentinel).forEach(([k, v]) => {
+      const re = new RegExp(`^#?\\s*${k}\\s*=.*$`, 'm');
+      if (re.test(updated)) {
+        updated = updated.replace(re, `${k}=${v}`);
+      } else {
+        updated += `\n${k}=${v}`;
+      }
+    });
+    fs.writeFileSync(propsPath, updated);
+    ok('Updated sentinel.properties');
+  }
+  if (Array.isArray(obj.repos)) {
+    obj.repos.forEach(repo => {
+      const { name, ...props } = repo;
+      writePropertiesFile(path.join(repoDir, `${name}.properties`), props);
+      ok(`Created repo-configs/${name}.properties`);
+    });
+  }
+  if (Array.isArray(obj.log_sources)) {
+    obj.log_sources.forEach(src => {
+      const { name, ...props } = src;
+      writePropertiesFile(path.join(logDir, `${name}.properties`), props);
+      ok(`Created log-configs/${name}.properties`);
+    });
+  }
+}
+
+function fetchUrl(url) {
+  try {
+    const result = spawnSync('curl', ['-fsSL', '--max-time', '10', url], { encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(result.stderr || 'curl failed');
+    return result.stdout;
+  } catch (_) {
+    const https = require('https');
+    const http  = require('http');
+    const lib   = url.startsWith('https') ? https : http;
+    return new Promise((resolve, reject) => {
+      lib.get(url, res => {
+        let data = '';
+        res.on('data', c => (data += c));
+        res.on('end', () => resolve(data));
+      }).on('error', reject);
+    });
+  }
+}
+
+// ── SSH deploy key helpers ────────────────────────────────────────────────────
+
+function ensureKnownHosts() {
+  const knownHosts = path.join(os.homedir(), '.ssh', 'known_hosts');
+  const content = fs.existsSync(knownHosts) ? fs.readFileSync(knownHosts, 'utf8') : '';
+  if (content.includes('github.com')) return;
+  info('Adding GitHub to known_hosts…');
+  const r = spawnSync('ssh-keyscan', ['github.com'], { encoding: 'utf8', timeout: 10000 });
+  if (r.stdout) fs.appendFileSync(knownHosts, r.stdout);
+}
+
+function generateDeployKey(repoSlug) {
+  const sshDir  = path.join(os.homedir(), '.ssh');
+  const keyFile = path.join(sshDir, `${repoSlug}.key`);
+  fs.ensureDirSync(sshDir);
+  fs.chmodSync(sshDir, 0o700);
+
+  if (fs.existsSync(keyFile)) {
+    info(`Using existing key: ${keyFile}`);
+  } else {
+    spawnSync('ssh-keygen', ['-t', 'ed25519', '-C', `sentinel@${repoSlug}`, '-f', keyFile, '-N', ''],
+      { stdio: 'inherit' });
+    ok(`Deploy key generated: ${keyFile}`);
+  }
+
+  const configFile = path.join(sshDir, 'config');
+  const sshHost    = `github-${repoSlug}`;
+  const existing   = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : '';
+  if (!existing.includes(`Host ${sshHost}`)) {
+    fs.appendFileSync(configFile,
+      `\nHost ${sshHost}\n    HostName github.com\n    User git\n    IdentityFile ${keyFile}\n    IdentitiesOnly yes\n`);
+    fs.chmodSync(configFile, 0o600);
+    ok('SSH config updated');
+  }
+
+  return { keyFile, sshHost };
+}
+
+function printDeployKeyInstructions(orgRepo, keyFile) {
+  const pubKey = fs.readFileSync(`${keyFile}.pub`, 'utf8').trim();
+  const bar    = '─'.repeat(70);
+  console.log('');
+  console.log(chalk.bold.yellow(`  ┌${bar}┐`));
+  console.log(chalk.bold.yellow(`  │`) + chalk.bold(`  Add this deploy key to GitHub`) + chalk.bold.yellow(' '.repeat(40) + '│'));
+  console.log(chalk.bold.yellow(`  │`) + chalk.cyan(`  github.com/${orgRepo}`) + chalk.bold.yellow(' '.repeat(Math.max(0, 70 - 14 - orgRepo.length)) + '│'));
+  console.log(chalk.bold.yellow(`  │`) + `  Settings → Deploy keys → Add deploy key` + chalk.bold.yellow(' '.repeat(29) + '│'));
+  console.log(chalk.bold.yellow(`  │`) + `  Allow write access: ✓` + chalk.bold.yellow(' '.repeat(47) + '│'));
+  console.log(chalk.bold.yellow(`  └${bar}┘`));
+  console.log('');
+  console.log(chalk.green(pubKey));
+  console.log('');
+}
+
+// ── addFromGit ────────────────────────────────────────────────────────────────
+
+async function addFromGit(gitUrl, workspace) {
+  const repoSlug = gitUrl.replace(/\.git$/, '').split(/[:/]/).pop();
+  const orgRepo  = gitUrl
+    .replace(/^git@github\.com:/, '')
+    .replace(/^https:\/\/github\.com\//, '')
+    .replace(/\.git$/, '');
+
+  const { name } = await prompts([{
+    type: 'text',
+    name: 'name',
+    message: 'Project name',
+    initial: repoSlug,
+    validate: v => VALID_NAME.test(v) || 'Use letters, numbers, hyphens only',
+  }], { onCancel: () => process.exit(0) });
+
+  // ── 1. Generate SSH deploy key ──────────────────────────────────────────────
+  step('Setting up SSH deploy key');
+  ensureKnownHosts();
+  const { keyFile, sshHost } = generateDeployKey(repoSlug);
+  const sshUrl = `git@${sshHost}:${orgRepo}.git`;
+  printDeployKeyInstructions(orgRepo, keyFile);
+
+  // ── 2. Fix deployment mode ──────────────────────────────────────────────────
+  const { autoPublish } = await prompts({
+    type: 'select',
+    name: 'autoPublish',
+    message: 'How should Sentinel deploy fixes?',
+    hint: 'You can change this later in config/repo-configs/',
+    choices: [
+      {
+        title: 'Open a PR for each fix  (AUTO_PUBLISH=false)  — recommended',
+        description: 'Sentinel pushes to a branch and opens a GitHub PR. You review and merge.',
+        value: false,
+      },
+      {
+        title: 'Push directly to main  (AUTO_PUBLISH=true)  — fully autonomous',
+        description: 'Sentinel commits and pushes fixes straight to your main branch.',
+        value: true,
+      },
+    ],
+  }, { onCancel: () => process.exit(0) });
+
+  if (autoPublish) {
+    warn('AUTO_PUBLISH=true: Sentinel will push fixes directly to main without review.');
+    warn('Make sure your repo has branch protection rules and CI that blocks bad pushes.');
+  }
+
+  // ── 3. Wait for user to add the key ────────────────────────────────────────
+  await prompts({
+    type: 'text',
+    name: '_',
+    message: chalk.bold('Press Enter once you\'ve added the deploy key to GitHub…'),
+    format: () => '',
+  }, { onCancel: () => process.exit(0) });
+
+  // ── 4. Validate access ──────────────────────────────────────────────────────
+  step('Validating repository access…');
+  info(`Testing SSH: ${sshUrl}`);
+  const result = spawnSync('git', ['ls-remote', '--heads', sshUrl],
+    {
+      encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+
+  if (result.status !== 0) {
+    const errText = (result.stderr || result.error?.message || '').trim();
+    console.error(chalk.red('  ✖ Cannot reach repository'));
+    if (errText) console.error(chalk.red(`    ${errText}`));
+    console.error('');
+    console.error(chalk.yellow('  Check that the deploy key was added to the correct repo with write access.'));
+    console.error(chalk.yellow('  Then re-run: sentinel add ' + gitUrl));
+    process.exit(1);
+  }
+
+  const branches = (result.stdout || '').split('\n')
+    .filter(Boolean).map(l => l.split('\t')[1].replace('refs/heads/', ''));
+  const defaultBranch = branches.includes('main') ? 'main' : (branches[0] || 'main');
+  ok(`Repository is reachable  (default branch: ${defaultBranch})`);
+
+  // ── 5. Preview + confirm ────────────────────────────────────────────────────
+  const projectDir = path.join(workspace, name);
+  const localPath  = path.join(workspace, 'repos', repoSlug);
+
+  step('Dry-run preview');
+  info(`Will create: ${projectDir}/`);
+  info(`  config/repo-configs/${repoSlug}.properties`);
+  info(`    REPO_URL=${sshUrl}`);
+  info(`    BRANCH=${defaultBranch}`);
+  info(`    AUTO_PUBLISH=${autoPublish}`);
+  info('  init.sh, start.sh, stop.sh');
+
+  const { confirm } = await prompts({
+    type: 'confirm', name: 'confirm',
+    message: `Create project "${name}"?`, initial: true,
+  }, { onCancel: () => process.exit(0) });
+  if (!confirm) { info('Aborted.'); return; }
+
+  if (fs.existsSync(projectDir)) {
+    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
+    process.exit(1);
+  }
+
+  // ── 6. Write files ──────────────────────────────────────────────────────────
+  const codeDir   = requireCodeDir(workspace);
+  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
+  writeExampleProject(projectDir, codeDir, pythonBin);
+  const repoDir = path.join(projectDir, 'config', 'repo-configs');
+  writePropertiesFile(path.join(repoDir, `${repoSlug}.properties`), {
+    REPO_NAME:         repoSlug,
+    REPO_URL:          sshUrl,
+    LOCAL_PATH:        localPath,
+    BRANCH:            defaultBranch,
+    AUTO_PUBLISH:      autoPublish ? 'true' : 'false',
+    CAIRN_MCP_ENABLED: 'true',
+  });
+  const example = path.join(repoDir, '_example.properties');
+  if (fs.existsSync(example)) fs.removeSync(example);
+  generateWorkspaceScripts(workspace);
+  ok(`Project "${name}" created at ${projectDir}`);
+  printNextSteps(projectDir, autoPublish);
+}
+
+// ── addFromName ───────────────────────────────────────────────────────────────
+
+async function addFromName(nameArg, workspace) {
+  const answers = await prompts([{
+    type: 'text',
+    name: 'name',
+    message: 'Project name',
+    initial: nameArg || 'my-project',
+    validate: v => VALID_NAME.test(v) || 'Use letters, numbers, hyphens only',
+  }], { onCancel: () => process.exit(0) });
+  const { name } = answers;
+  const projectDir = path.join(workspace, name);
+  step('Dry-run preview');
+  info(`Will create: ${projectDir}/`);
+  info('  config/sentinel.properties');
+  info('  config/repo-configs/_example.properties');
+  info('  config/log-configs/_example.properties');
+  info('  init.sh, start.sh, stop.sh');
+  const { confirm } = await prompts({
+    type: 'confirm', name: 'confirm',
+    message: `Create project "${name}"?`, initial: true,
+  }, { onCancel: () => process.exit(0) });
+  if (!confirm) { info('Aborted.'); return; }
+  if (fs.existsSync(projectDir)) {
+    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
+    process.exit(1);
+  }
+  const codeDir  = requireCodeDir(workspace);
+  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
+  writeExampleProject(projectDir, codeDir, pythonBin);
+  generateWorkspaceScripts(workspace);
+  ok(`Project "${name}" created at ${projectDir}`);
+  printNextSteps(projectDir);
+}
+
+// ── addFromJson ───────────────────────────────────────────────────────────────
+
+async function addFromJson(jsonPath, workspace) {
+  step(`Reading ${jsonPath}`);
+  let obj;
+  try {
+    obj = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (e) {
+    console.error(chalk.red(`  ✖ Cannot parse ${jsonPath}: ${e.message}`));
+    process.exit(1);
+  }
+  const errors = validateProjectJson(obj);
+  if (errors.length) {
+    console.error(chalk.red('  ✖ Invalid project JSON:'));
+    errors.forEach(e => console.error(chalk.red(`    - ${e}`)));
+    process.exit(1);
+  }
+  ok('JSON is valid');
+  const { name } = obj;
+  const projectDir = path.join(workspace, name);
+  step('Dry-run preview');
+  info(`Will create: ${projectDir}/`);
+  (obj.repos || []).forEach(r => info(`  config/repo-configs/${r.name}.properties  (${r.REPO_URL})`));
+  (obj.log_sources || []).forEach(s => info(`  config/log-configs/${s.name}.properties  (${s.SOURCE_TYPE})`));
+  if (obj.sentinel) {
+    Object.entries(obj.sentinel).forEach(([k, v]) => info(`  sentinel.properties: ${k}=${v}`));
+  }
+  const { confirm } = await prompts({
+    type: 'confirm', name: 'confirm',
+    message: `Create project "${name}" from ${path.basename(jsonPath)}?`, initial: true,
+  }, { onCancel: () => process.exit(0) });
+  if (!confirm) { info('Aborted.'); return; }
+  if (fs.existsSync(projectDir)) {
+    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
+    process.exit(1);
+  }
+  const codeDir   = requireCodeDir(workspace);
+  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
+  writeExampleProject(projectDir, codeDir, pythonBin);
+  const repoDir = path.join(projectDir, 'config', 'repo-configs');
+  const logDir  = path.join(projectDir, 'config', 'log-configs');
+  if (fs.existsSync(path.join(repoDir, '_example.properties'))) fs.removeSync(path.join(repoDir, '_example.properties'));
+  if (fs.existsSync(path.join(logDir,  '_example.properties'))) fs.removeSync(path.join(logDir,  '_example.properties'));
+  applyJsonToProject(projectDir, obj);
+  generateWorkspaceScripts(workspace);
+  ok(`Project "${name}" created at ${projectDir}`);
+  printNextSteps(projectDir);
+}
+
+// ── addFromUrl ────────────────────────────────────────────────────────────────
+
+async function addFromUrl(url, workspace) {
+  step(`Fetching ${url}`);
+  let raw;
+  try {
+    raw = fetchUrl(url);
+    if (raw && typeof raw.then === 'function') raw = await raw;
+  } catch (e) {
+    console.error(chalk.red(`  ✖ Cannot fetch ${url}: ${e.message}`));
+    process.exit(1);
+  }
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch (e) {
+    console.error(chalk.red(`  ✖ Response is not valid JSON: ${e.message}`));
+    process.exit(1);
+  }
+  const errors = validateProjectJson(obj);
+  if (errors.length) {
+    console.error(chalk.red('  ✖ Invalid project JSON at URL:'));
+    errors.forEach(e => console.error(chalk.red(`    - ${e}`)));
+    process.exit(1);
+  }
+  ok('JSON is valid');
+  const { name } = obj;
+  const projectDir = path.join(workspace, name);
+  step('Dry-run preview');
+  info(`Will create: ${projectDir}/`);
+  (obj.repos || []).forEach(r => info(`  config/repo-configs/${r.name}.properties  (${r.REPO_URL})`));
+  (obj.log_sources || []).forEach(s => info(`  config/log-configs/${s.name}.properties  (${s.SOURCE_TYPE})`));
+  if (obj.sentinel) {
+    Object.entries(obj.sentinel).forEach(([k, v]) => info(`  sentinel.properties: ${k}=${v}`));
+  }
+  const { confirm } = await prompts({
+    type: 'confirm', name: 'confirm',
+    message: `Create project "${name}" from ${url}?`, initial: true,
+  }, { onCancel: () => process.exit(0) });
+  if (!confirm) { info('Aborted.'); return; }
+  if (fs.existsSync(projectDir)) {
+    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
+    process.exit(1);
+  }
+  const codeDir   = requireCodeDir(workspace);
+  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
+  writeExampleProject(projectDir, codeDir, pythonBin);
+  const repoDir = path.join(projectDir, 'config', 'repo-configs');
+  const logDir  = path.join(projectDir, 'config', 'log-configs');
+  if (fs.existsSync(path.join(repoDir, '_example.properties'))) fs.removeSync(path.join(repoDir, '_example.properties'));
+  if (fs.existsSync(path.join(logDir,  '_example.properties'))) fs.removeSync(path.join(logDir,  '_example.properties'));
+  applyJsonToProject(projectDir, obj);
+  generateWorkspaceScripts(workspace);
+  ok(`Project "${name}" created at ${projectDir}`);
+  printNextSteps(projectDir);
+}
+
+// ── printNextSteps ────────────────────────────────────────────────────────────
+
+function printNextSteps(projectDir, autoPublish) {
+  const mode = autoPublish === true
+    ? chalk.yellow('  ⚠  Fixes push directly to main — ensure CI blocks bad pushes')
+    : autoPublish === false
+    ? chalk.cyan('  →  Sentinel will open a GitHub PR for each fix — review and merge at github.com')
+    : '';
+  console.log(`
+  Next steps:
+    1. Edit config/log-configs/ to add your log sources
+       ${chalk.cyan(`${projectDir}/config/`)}
+    2. Start Sentinel:
+       ${chalk.cyan(`${projectDir}/start.sh`)}
+${mode ? '     ' + mode : ''}
+`);
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+module.exports = async function add(arg) {
+  const type = detectInputType(arg);
+  const workspace = await resolveWorkspace();
+  if (type === 'git')  return addFromGit(arg, workspace);
+  if (type === 'url')  return addFromUrl(arg, workspace);
+  if (type === 'json') return addFromJson(arg, workspace);
+  return addFromName(arg, workspace);
+};