cloud-ide-cide 2.0.34

package/cideShell.js

@@ -0,0 +1,1292 @@
+/**
+ * cide shell — interactive workspace REPL (build, publish, git, server, npm, env).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync, spawn } = require('child_process');
+
+const buildProject = require('./buildProject');
+const buildWorkspace = require('./buildWorkspace');
+const buildAllProjects = require('./buildAllProjects');
+const startProject = require('./startProject');
+const watchLinkProject = require('./watchLinkProject');
+const publishPackage = require('./publishPackage');
+const uploadProject = require('./uploadProject');
+const serverInit = require('./serverInit');
+
+const loadCideConfig = publishPackage.loadCideConfig;
+const discoverPublishablePackages = publishPackage.discoverPublishablePackages;
+const installGlobalPackage = publishPackage.installGlobalPackage;
+
+const PROMPT = 'CloudIDE> ';
+
+/** Shell: `build -p all` / `build --resume-from 2` → options for buildWorkspace */
+function parseBuildShellArgs(tokens) {
+  const out = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const t = String(tokens[i]);
+    if (t === '-p' || t === '--packages') {
+      out.packages = tokens[++i];
+    } else if (t === '--resume-from') {
+      out.resumeFrom = tokens[++i];
+    } else if (t === '--continue-on-error') {
+      out.continueOnError = true;
+    }
+  }
+  return out;
+}
+
+const ENV_KEYS_TO_CHECK = [
+  'MONGODB_URI',
+  'JWT_SECRET',
+  'PORT',
+  'SECRET_KEY',
+  'EMAIL_GATEWAY_URL',
+];
+
+let bgServerPid = null;
+
+function existsSync(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function safeReadJson(p) {
+  try {
+    return readJson(p);
+  } catch {
+    return null;
+  }
+}
+
+function safeReaddir(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/** True if dir contains cide.json marking an Angular workspace (supports templete/template typo). */
+function isAngularCideJsonAt(dir) {
+  const cidePath = path.join(dir, 'cide.json');
+  if (!existsSync(cidePath)) return false;
+  const c = safeReadJson(cidePath);
+  return !!(c && (c.templete === 'angular' || c.template === 'angular'));
+}
+
+/**
+ * Find Angular workspace root (folder with angular cide.json). No hardcoded folder names.
+ *
+ * 1) Walk up from cwd until a matching cide.json is found.
+ * 2) For each ancestor, scan that ancestor’s immediate subfolders (siblings of your current path) for angular cide.json — supports running from monorepo root or from a sibling package (e.g. CLI folder next to the Angular app).
+ * 3) Shallow BFS under cwd (max depth), skipping node_modules / dist — supports nested layouts.
+ */
+function findAngularWorkspaceRoot() {
+  const cwd = path.resolve(process.cwd());
+
+  let d = cwd;
+  for (let i = 0; i < 16; i++) {
+    if (isAngularCideJsonAt(d)) return d;
+    const parent = path.dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+
+  d = cwd;
+  for (let i = 0; i < 16; i++) {
+    const parent = path.dirname(d);
+    if (parent === d) break;
+    for (const e of safeReaddir(parent)) {
+      if (!e.isDirectory() || e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      const sibling = path.resolve(parent, e.name);
+      if (isAngularCideJsonAt(sibling)) return sibling;
+    }
+    d = parent;
+  }
+
+  const maxDepth = 5;
+  const queue = [[cwd, 0]];
+  const seen = new Set([cwd]);
+  while (queue.length > 0) {
+    const [dir, depth] = queue.shift();
+    if (isAngularCideJsonAt(dir)) return dir;
+    if (depth >= maxDepth) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name === 'node_modules' || e.name === 'dist' || e.name.startsWith('.')) continue;
+      const full = path.resolve(dir, e.name);
+      if (seen.has(full)) continue;
+      seen.add(full);
+      queue.push([full, depth + 1]);
+    }
+  }
+
+  return null;
+}
+
+function discoverGitRepos(monorepoRoot) {
+  const repos = [];
+  if (!existsSync(monorepoRoot)) return repos;
+  for (const e of safeReaddir(monorepoRoot)) {
+    if (!e.isDirectory() || e.name === 'node_modules' || e.name.startsWith('.')) continue;
+    const abs = path.join(monorepoRoot, e.name);
+    if (existsSync(path.join(abs, '.git'))) {
+      repos.push({ name: e.name, absPath: abs });
+    }
+  }
+  repos.sort((a, b) => a.name.localeCompare(b.name));
+  return repos;
+}
+
+/** Every folder under projects/ (and projects/@cloudidesys/) that has ng-package.json */
+function discoverAngularLibs(angularRoot) {
+  const seen = new Set();
+  const out = [];
+  function pushLib(projDir, folderName) {
+    const resolved = path.resolve(projDir);
+    if (seen.has(resolved)) return;
+    const ngp = path.join(projDir, 'ng-package.json');
+    if (!existsSync(ngp)) return;
+    seen.add(resolved);
+    const pjPath = path.join(projDir, 'package.json');
+    const pkg = safeReadJson(pjPath) || {};
+    const ng = safeReadJson(ngp) || {};
+    let distDir = null;
+    if (ng.dest) distDir = path.resolve(projDir, ng.dest);
+    const short = folderName.startsWith('cloud-ide-') ? folderName.slice('cloud-ide-'.length) : folderName;
+    out.push({
+      folderName,
+      shortName: short,
+      packageName: pkg.name || folderName,
+      absDir: resolved,
+      distDir,
+      version: pkg.version || '0.0.0',
+    });
+  }
+  const projectsDir = path.join(angularRoot, 'projects');
+  if (!existsSync(projectsDir)) return out;
+  for (const e of safeReaddir(projectsDir)) {
+    if (!e.isDirectory()) continue;
+    if (e.name === '@cloudidesys') {
+      const scoped = path.join(projectsDir, e.name);
+      for (const e2 of safeReaddir(scoped)) {
+        if (!e2.isDirectory()) continue;
+        pushLib(path.join(scoped, e2.name), e2.name);
+      }
+      continue;
+    }
+    pushLib(path.join(projectsDir, e.name), e.name);
+  }
+  out.sort((a, b) => a.folderName.localeCompare(b.folderName));
+  return out;
+}
+
+function discoverSeedScripts(nodeRoot) {
+  const dir = path.join(nodeRoot, 'src', 'scripts');
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.ts')) continue;
+    const base = f.replace(/\.ts$/, '');
+    out.push({ name: base, file: f, absPath: path.join(dir, f) });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+function discoverNodeBackend(monorepoRoot) {
+  if (!existsSync(monorepoRoot)) return null;
+  for (const e of safeReaddir(monorepoRoot)) {
+    if (!e.isDirectory()) continue;
+    const abs = path.join(monorepoRoot, e.name);
+    const cidePath = path.join(abs, 'cide.json');
+    if (!existsSync(cidePath)) continue;
+    const c = safeReadJson(cidePath);
+    if (c && c.templete === 'node') {
+      const pj = path.join(abs, 'package.json');
+      const pkg = safeReadJson(pj) || {};
+      return { name: e.name, absPath: abs, scripts: pkg.scripts || {} };
+    }
+  }
+  return null;
+}
+
+/**
+ * Projects that can be started via `npm run <script>` (shown in `start` picker).
+ */
+function discoverRunnableProjects(ws) {
+  const list = [];
+  if (ws.angularRoot) {
+    const pj = path.join(ws.angularRoot, 'package.json');
+    const pkg = safeReadJson(pj) || {};
+    const scripts = pkg.scripts || {};
+    const angularShortName = path.basename(ws.angularRoot);
+    if (scripts.start) {
+      list.push({
+        kind: 'angular',
+        label: `${angularShortName} — Angular app (npm run start → ng serve)`,
+        cwd: ws.angularRoot,
+        npmScript: 'start',
+      });
+    }
+    if (scripts.tailwindcss) {
+      list.push({
+        kind: 'tailwind',
+        label: `${angularShortName} — Tailwind CSS watch`,
+        cwd: ws.angularRoot,
+        npmScript: 'tailwindcss',
+      });
+    }
+  }
+  if (ws.nodeBackend) {
+    const scripts = ws.nodeBackend.scripts || {};
+    const scriptName = scripts.dev ? 'dev' : scripts.start ? 'start' : null;
+    if (scriptName) {
+      list.push({
+        kind: 'node',
+        label: `${ws.nodeBackend.name} — Node API (npm run ${scriptName})`,
+        cwd: ws.nodeBackend.absPath,
+        npmScript: scriptName,
+      });
+    }
+  }
+  list.forEach((e, i) => {
+    e.index = i + 1;
+  });
+  return list;
+}
+
+function parseNumberSelection(raw, maxN) {
+  const s = String(raw).trim().toLowerCase();
+  if (s === 'q' || s === 'quit') return { ok: true, indices: [], cancelled: true };
+  if (!s) return { ok: false, error: 'Empty selection.' };
+  if (s === 'all') {
+    return { ok: true, indices: Array.from({ length: maxN }, (_, i) => i) };
+  }
+  const set = new Set();
+  const parts = s.split(',').map((p) => p.trim()).filter(Boolean);
+  for (const part of parts) {
+    if (part.includes('-')) {
+      const [a, b] = part.split('-').map((x) => parseInt(x.trim(), 10));
+      if (Number.isFinite(a) && Number.isFinite(b)) {
+        const lo = Math.min(a, b);
+        const hi = Math.max(a, b);
+        for (let i = lo; i <= hi; i++) {
+          if (i >= 1 && i <= maxN) set.add(i - 1);
+        }
+      }
+    } else {
+      const n = parseInt(part, 10);
+      if (n >= 1 && n <= maxN) set.add(n - 1);
+    }
+  }
+  const indices = [...set].sort((a, b) => a - b);
+  if (indices.length === 0) {
+    return { ok: false, error: `No valid numbers. Use 1–${maxN}, ranges like 1-3, or all.` };
+  }
+  return { ok: true, indices };
+}
+
+/** True when stdin is likely VS Code / Cursor integrated terminal (not a standalone OS terminal). */
+function isLikelyIdeIntegratedTerminal() {
+  return (
+    process.env.TERM_PROGRAM === 'vscode' ||
+    process.env.VSCODE_INJECTION === '1' ||
+    process.env.VSCODE_CWD !== undefined ||
+    process.env.CURSOR_TRACE_ID !== undefined
+  );
+}
+
+/** Commands to paste into a new integrated terminal (preferred when running inside Cursor/VS Code). */
+function printIntegratedTerminalInstructions(cwd, script) {
+  const cmdLine =
+    process.platform === 'win32'
+      ? `cd /d "${cwd}" && npm run ${script}`
+      : `cd ${JSON.stringify(cwd)} && npm run ${script}`;
+  console.log('');
+  console.log('  Open a new integrated terminal (Terminal → New Terminal, or Ctrl+Shift+`), then paste:');
+  console.log(`    ${cmdLine}`);
+  console.log('');
+}
+
+/**
+ * When running inside Cursor/VS Code: print paste-ready commands (integrated terminal).
+ * Otherwise: open a new OS terminal window (Windows cmd) or print for macOS/Linux.
+ */
+function launchInNewTerminal(entry) {
+  const cwd = path.resolve(entry.cwd);
+  const script = String(entry.npmScript || '').replace(/[^a-zA-Z0-9:_-]/g, '');
+  if (!script) {
+    throw new Error('Invalid npm script name');
+  }
+
+  if (isLikelyIdeIntegratedTerminal()) {
+    printIntegratedTerminalInstructions(cwd, script);
+    return;
+  }
+
+  if (process.platform === 'win32') {
+    // Avoid: start "title" cmd /k JSON.stringify(...) — cmd misparses JSON escapes and shows
+    // "The filename, directory name, or volume label syntax is incorrect."
+    // Also avoid Unicode/special chars in start's window title (—, →, parentheses, &).
+    const runLine = `cd /d "${cwd}" && npm run ${script}`;
+    const comspec = process.env.ComSpec || 'cmd.exe';
+    const child = spawn(comspec, ['/c', 'start', 'cide', 'cmd', '/k', runLine], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: false,
+    });
+    child.unref();
+  } else {
+    console.log(`\n  Open a new terminal and run:\n    cd ${JSON.stringify(cwd)} && npm run ${script}\n`);
+  }
+}
+
+function questionRl(rl, promptText) {
+  return new Promise((resolve) => {
+    rl.question(promptText, resolve);
+  });
+}
+
+async function handleStartCommand(ws, rl, rest) {
+  const joined = rest.join(' ').trim();
+  if (joined.toLowerCase() === 'legacy') {
+    handleStartLegacyProject(ws);
+    return;
+  }
+
+  const runnable = discoverRunnableProjects(ws);
+  if (!runnable.length) {
+    console.log(
+      'No runnable projects found (need npm scripts: start in Angular workspace, dev/start in Node API, optional tailwindcss).'
+    );
+    return;
+  }
+
+  let spec = joined;
+  if (!spec) {
+    console.log(`
+----------------------------------------------------------------
+ START — dev servers (npm run …)
+----------------------------------------------------------------
+  In Cursor / VS Code: prints commands to paste in a new integrated terminal (recommended).
+  Standalone terminal (outside IDE): opens a new OS window on Windows.
+
+`);
+    runnable.forEach((r) => {
+      console.log(`  [${r.index}]  ${r.kind.padEnd(10)}  ${r.label}`);
+    });
+    console.log(`
+  Pick one line (same rules as publish):
+    1           only [1]
+    1,3         [1] and [3]
+    1-3         [1] through [3]
+    all         every item above
+    q           cancel
+
+  Or re-run non-interactively:  start 1   |   start 1,3   |   start all
+----------------------------------------------------------------
+`);
+    spec = (await questionRl(rl, 'Which to run? ')).trim();
+  }
+
+  if (!spec || spec.toLowerCase() === 'q') {
+    console.log('(cancelled)');
+    return;
+  }
+
+  const parsed = parseNumberSelection(spec, runnable.length);
+  if (parsed.cancelled) {
+    console.log('(cancelled)');
+    return;
+  }
+  if (!parsed.ok) {
+    console.error(parsed.error || 'Invalid selection');
+    return;
+  }
+  if (!parsed.indices.length) {
+    console.log('Nothing selected.');
+    return;
+  }
+
+  const inIde = isLikelyIdeIntegratedTerminal();
+  for (const idx of parsed.indices) {
+    const entry = runnable[idx];
+    if (!entry) continue;
+    console.log(
+      `\n  → ${inIde ? 'Paste in new terminal' : 'New OS window'}: [${entry.index}] ${entry.label}`
+    );
+    try {
+      launchInNewTerminal(entry);
+    } catch (e) {
+      console.error(`  Failed: ${e.message}`);
+    }
+  }
+  console.log(
+    inIde
+      ? '\nDone. Use Terminal → New Terminal, then paste each command above.\n'
+      : '\nDone. Check the new terminal window(s).\n'
+  );
+}
+
+function loadWorkspace() {
+  const angularRoot = findAngularWorkspaceRoot();
+  if (!angularRoot) {
+    return {
+      angularRoot: null,
+      monorepoRoot: null,
+      cide: {},
+      repos: [],
+      angularLibs: [],
+      seedScripts: [],
+      nodeBackend: null,
+      publishList: [],
+    };
+  }
+  const { cide, monorepoRoot } = loadCideConfig(angularRoot);
+  const repos = discoverGitRepos(monorepoRoot);
+  const angularLibs = discoverAngularLibs(angularRoot);
+  const nodeBackend = discoverNodeBackend(monorepoRoot);
+  const seedScripts = nodeBackend ? discoverSeedScripts(nodeBackend.absPath) : [];
+  // Lazy publish list: large monorepo scans run on first `packages` / `versions`, not every shell startup.
+  const ws = {
+    angularRoot,
+    monorepoRoot,
+    cide,
+    repos,
+    angularLibs,
+    seedScripts,
+    nodeBackend,
+    _publishListCache: undefined,
+  };
+  Object.defineProperty(ws, 'publishList', {
+    get() {
+      if (this._publishListCache !== undefined) return this._publishListCache;
+      const { cide: cc, monorepoRoot: mr } = loadCideConfig(this.angularRoot);
+      this._publishListCache = discoverPublishablePackages({ cide: cc, angularRoot: this.angularRoot, monorepoRoot: mr });
+      return this._publishListCache;
+    },
+    enumerable: true,
+  });
+  return ws;
+}
+
+function gitShortStatus(repoPath) {
+  try {
+    return execSync('git status --porcelain', { cwd: repoPath, encoding: 'utf8', shell: true }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function gitAheadCount(repoPath) {
+  try {
+    const o = execSync('git rev-list @{u}..HEAD --count', {
+      cwd: repoPath,
+      encoding: 'utf8',
+      shell: true,
+    }).trim();
+    const n = parseInt(o, 10);
+    return Number.isFinite(n) ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** One git call for startup banner (replaces status + rev-list per repo). */
+function gitRepoStatusSummary(repoPath) {
+  try {
+    const out = execSync('git status -sb', { cwd: repoPath, encoding: 'utf8', shell: true }).trim();
+    if (!out) return { hint: 'clean' };
+    const lines = out.split(/\r?\n/);
+    const first = lines[0];
+    let ahead = 0;
+    const am = first.match(/\[ahead (\d+)\]/);
+    if (am) ahead = parseInt(am[1], 10);
+    const dirtyLines = Math.max(0, lines.length - 1);
+    let hint = 'clean';
+    if (dirtyLines > 0) hint = `${dirtyLines} local change(s)  -> try: commit "message"`;
+    else if (ahead > 0) hint = `${ahead} unpushed commit(s)  -> try: push`;
+    return { hint };
+  } catch {
+    return { hint: '(git failed)' };
+  }
+}
+
+function findRepo(ws, name) {
+  if (!name) return null;
+  const n = name.toLowerCase();
+  return ws.repos.find((r) => r.name.toLowerCase() === n) || null;
+}
+
+function resolveBuildToken(token, ws) {
+  const t = String(token).trim().toLowerCase();
+  if (!t) return null;
+  for (const L of ws.angularLibs) {
+    if (L.shortName === t) return L.folderName;
+    if (L.folderName.toLowerCase() === t) return L.folderName;
+    if (`cloud-ide-${t}` === L.folderName.toLowerCase()) return L.folderName;
+    if (L.packageName && L.packageName.toLowerCase() === t) return L.folderName;
+    const scoped = `@cloudidesys/cloud-ide-${t}`;
+    if (L.packageName && L.packageName.toLowerCase() === scoped) return L.folderName;
+  }
+  return token;
+}
+
+function printStartupScan(ws) {
+  const cliVersion = require('./package.json').version;
+  console.log('');
+  console.log('============================================================');
+  console.log(`  CloudIDE Workspace Shell (v${cliVersion})`);
+  console.log('  Git · build · publish · server · npm  —  type "help" for commands');
+  console.log('============================================================');
+  if (!ws.angularRoot) {
+    console.log(
+      '\n  (No Angular workspace found. cd into the folder that has angular cide.json, or run from a monorepo parent that contains it.)\n'
+    );
+    return;
+  }
+  console.log(`\n  Angular root: ${ws.angularRoot}`);
+  console.log(`  Monorepo:     ${ws.monorepoRoot}`);
+  console.log(`  Angular libs: ${ws.angularLibs.length} (auto-discovered via projects/*/ng-package.json)`);
+  if (ws.nodeBackend) console.log(`  Node API:     ${ws.nodeBackend.name}`);
+  console.log('\n  Repos:');
+  for (const r of ws.repos) {
+    const { hint } = gitRepoStatusSummary(r.absPath);
+    console.log(`  * ${r.name.padEnd(22)} ${hint}`);
+  }
+  console.log('');
+}
+
+function runGitAll(ws, args, inherit) {
+  for (const r of ws.repos) {
+    console.log(`\n--- ${r.name} ---`);
+    try {
+      execSync(`git ${args}`, { cwd: r.absPath, stdio: inherit ? 'inherit' : 'pipe', shell: true });
+    } catch (e) {
+      console.error(`  (git failed in ${r.name})`);
+    }
+  }
+}
+
+function runGitOne(ws, repoName, args, inherit) {
+  const r = findRepo(ws, repoName);
+  if (!r) {
+    console.error(`Unknown repo: ${repoName}. Use: ${ws.repos.map((x) => x.name).join(', ')}`);
+    return;
+  }
+  execSync(`git ${args}`, { cwd: r.absPath, stdio: inherit ? 'inherit' : 'pipe', shell: true });
+}
+
+function handleStatus(ws) {
+  for (const r of ws.repos) {
+    const st = gitShortStatus(r.absPath);
+    const line = st && st.length ? st.split('\n').slice(0, 5).join('; ') : '(clean)';
+    const more = st && st.split('\n').length > 5 ? '...' : '';
+    console.log(`  ${r.name.padEnd(22)} ${line}${more}`);
+  }
+}
+
+function handleCommit(ws, message) {
+  if (!message || !String(message).trim()) {
+    console.error('Usage: commit "your message"');
+    return;
+  }
+  const msg = String(message).trim();
+  for (const r of ws.repos) {
+    const st = gitShortStatus(r.absPath);
+    if (!st || !st.length) {
+      console.log(`  ${r.name}: (no changes, skip)`);
+      continue;
+    }
+    console.log(`  ${r.name}: committing...`);
+    try {
+      execSync('git add -A', { cwd: r.absPath, stdio: 'inherit', shell: true });
+      execSync(`git commit -m ${JSON.stringify(msg)}`, { cwd: r.absPath, stdio: 'inherit', shell: true });
+      console.log(`       done`);
+    } catch {
+      console.log(`       (commit skipped or failed — maybe nothing staged)`);
+    }
+  }
+}
+
+function handlePush(ws, repoName) {
+  if (repoName) {
+    runGitOne(ws, repoName, 'push', true);
+    return;
+  }
+  for (const r of ws.repos) {
+    const ahead = gitAheadCount(r.absPath);
+    if (ahead <= 0) {
+      console.log(`  ${r.name}: up to date`);
+      continue;
+    }
+    console.log(`  ${r.name}: ${ahead} ahead — pushing...`);
+    try {
+      execSync('git push', { cwd: r.absPath, stdio: 'inherit', shell: true });
+      console.log(`       done`);
+    } catch {
+      console.error(`       failed`);
+    }
+  }
+}
+
+function handlePull(ws, repoName) {
+  if (repoName) {
+    runGitOne(ws, repoName, 'pull', true);
+    return;
+  }
+  runGitAll(ws, 'pull', true);
+}
+
+function handleDiff(ws, repoName) {
+  if (repoName) runGitOne(ws, repoName, 'diff', true);
+  else runGitAll(ws, 'diff', true);
+}
+
+function handleLog(ws, repoName) {
+  const args = 'log --oneline -5';
+  if (repoName) runGitOne(ws, repoName, args, true);
+  else runGitAll(ws, args, true);
+}
+
+function handleStash(ws, repoName) {
+  if (repoName) runGitOne(ws, repoName, 'stash', true);
+  else runGitAll(ws, 'stash', true);
+}
+
+function handleBranch(ws, repoName) {
+  if (repoName) runGitOne(ws, repoName, 'branch -vv', true);
+  else runGitAll(ws, 'branch -vv', true);
+}
+
+function killBgServer() {
+  if (!bgServerPid) {
+    console.log('No background server PID tracked (start with: server dev)');
+    return;
+  }
+  try {
+    if (process.platform === 'win32') {
+      execSync(`taskkill /PID ${bgServerPid} /T /F`, { stdio: 'inherit', shell: true });
+    } else {
+      process.kill(-bgServerPid, 'SIGTERM');
+    }
+    console.log(`Stopped process tree ${bgServerPid}`);
+  } catch (e) {
+    console.error('Stop failed:', e.message);
+  }
+  bgServerPid = null;
+}
+
+function spawnBg(cwd, command, args) {
+  const child = spawn(command, args, {
+    cwd,
+    shell: true,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  bgServerPid = child.pid;
+  console.log(`Started background PID ${child.pid} (${command} ${args.join(' ')})`);
+  console.log('(Output not shown here; use server stop to end, or run npm in another terminal for logs.)');
+}
+
+async function handleServer(ws, sub, rest, rl) {
+  // init & listener don't need a node backend — they manage the .cide/ upload server
+  if (sub === 'init') {
+    const type = rest[0] || '';
+    const targetPath = rest[1] || '';
+    await serverInit({ type, path: targetPath, readlineInterface: rl });
+    return;
+  }
+  if (sub === 'listener') {
+    const action = (rest[0] || '').toLowerCase();
+    const { findCideDir, startNodeListener, stopNodeListener, listenerStatus } = serverInit;
+    const cideDir = findCideDir();
+    if (!cideDir) {
+      console.error('  No .cide/ folder found. Run: server init first.');
+      return;
+    }
+    if (action === 'start')        startNodeListener(cideDir);
+    else if (action === 'stop')    stopNodeListener(cideDir);
+    else if (action === 'restart') { stopNodeListener(cideDir); startNodeListener(cideDir); }
+    else if (action === 'status')  listenerStatus(cideDir);
+    else console.error('  Usage: server listener start | stop | restart | status');
+    return;
+  }
+
+  // build/start/dev/stop need the node backend project
+  const nb = ws.nodeBackend;
+  if (!nb) {
+    console.error('No Node backend found (cide.json with templete: node).');
+    return;
+  }
+  const cwd = nb.absPath;
+  if (sub === 'build') {
+    execSync('npm run build', { cwd, stdio: 'inherit', shell: true });
+    return;
+  }
+  if (sub === 'start') {
+    spawnBg(cwd, 'npm', ['run', 'start']);
+    return;
+  }
+  if (sub === 'dev') {
+    spawnBg(cwd, 'npm', ['run', 'dev']);
+    return;
+  }
+  if (sub === 'stop') {
+    killBgServer();
+    return;
+  }
+  console.error('Usage: server build | start | dev | stop | init | listener start|stop|status|restart');
+}
+
+function handleSeed(ws, name) {
+  const nb = ws.nodeBackend;
+  if (!nb) {
+    console.error('No Node backend found.');
+    return;
+  }
+  if (!name) {
+    console.log('Seed scripts:');
+    for (const s of ws.seedScripts) console.log(`  ${s.name}`);
+    return;
+  }
+  const hit = ws.seedScripts.find(
+    (s) =>
+      s.name === name ||
+      s.name === `seed-${name}` ||
+      s.file === `${name}.ts` ||
+      s.file === `seed-${name}.ts`
+  );
+  if (!hit) {
+    console.error(`Unknown seed: ${name}`);
+    return;
+  }
+  const rel = `src/scripts/${hit.file}`;
+  console.log(`Running: npx ts-node ${rel}`);
+  execSync(`npx ts-node ${rel}`, { cwd: nb.absPath, stdio: 'inherit', shell: true });
+}
+
+function readAngularWorkspaceScripts(ws) {
+  const pj = path.join(ws.angularRoot, 'package.json');
+  const pkg = safeReadJson(pj);
+  return (pkg && pkg.scripts) || {};
+}
+
+function handleServe(ws) {
+  const scripts = readAngularWorkspaceScripts(ws);
+  if (!scripts.start) {
+    console.error(`No "start" script in ${path.basename(ws.angularRoot)}/package.json`);
+    return;
+  }
+  spawnBg(ws.angularRoot, 'npm', ['run', 'start']);
+}
+
+function handleTailwind(ws) {
+  const scripts = readAngularWorkspaceScripts(ws);
+  if (!scripts.tailwindcss) {
+    console.error(`No "tailwindcss" script in ${path.basename(ws.angularRoot)}/package.json`);
+    return;
+  }
+  spawnBg(ws.angularRoot, 'npm', ['run', 'tailwindcss']);
+}
+
+function handleLint(ws) {
+  execSync('npm run lint', { cwd: ws.angularRoot, stdio: 'inherit', shell: true });
+}
+
+function handleTest(ws) {
+  execSync('npm run test', { cwd: ws.angularRoot, stdio: 'inherit', shell: true });
+}
+
+function handleAnalyze(ws) {
+  const scripts = readAngularWorkspaceScripts(ws);
+  const key = scripts['build:analyze'] ? 'build:analyze' : null;
+  if (!key) {
+    console.error('No build:analyze script.');
+    return;
+  }
+  execSync(`npm run ${key}`, { cwd: ws.angularRoot, stdio: 'inherit', shell: true });
+}
+
+function handleNpm(ws, tokens) {
+  // npm install <repo> | npm install all | npm update <repo> | npm outdated <repo> | npm list <repo>
+  // Optional --force anywhere after "npm" for install | update
+  const force = tokens.some((t) => t === '--force');
+  const filtered = tokens.filter((t) => t !== '--force');
+  const sub = filtered[1]?.toLowerCase();
+  const target = filtered[2];
+  const forceSuffix = force ? ' --force' : '';
+  if (sub === 'install' && target && target.toLowerCase() === 'all') {
+    for (const r of ws.repos) {
+      console.log(`\nnpm install in ${r.name}...${force ? ' (--force)' : ''}`);
+      execSync(`npm install${forceSuffix}`, { cwd: r.absPath, stdio: 'inherit', shell: true });
+    }
+    return;
+  }
+  if (!target) {
+    console.error('Usage: npm install <repoName|all> [--force] | npm update <repo> [--force] | npm outdated <repo> | npm list <repo>');
+    return;
+  }
+  const r = findRepo(ws, target);
+  if (!r) {
+    console.error(`Unknown repo: ${target}`);
+    return;
+  }
+  if (sub === 'install') execSync(`npm install${forceSuffix}`, { cwd: r.absPath, stdio: 'inherit', shell: true });
+  else if (sub === 'update') execSync(`npm update${forceSuffix}`, { cwd: r.absPath, stdio: 'inherit', shell: true });
+  else if (sub === 'outdated') execSync('npm outdated', { cwd: r.absPath, stdio: 'inherit', shell: true });
+  else if (sub === 'list') execSync('npm list --depth=0', { cwd: r.absPath, stdio: 'inherit', shell: true });
+  else console.error('Unknown npm subcommand');
+}
+
+function handleEnv(ws, sub) {
+  const nb = ws.nodeBackend;
+  if (!nb) {
+    console.error('No Node backend.');
+    return;
+  }
+  const envPath = path.join(nb.absPath, '.env');
+  if (sub === 'show') {
+    if (!existsSync(envPath)) {
+      console.log('No .env file.');
+      return;
+    }
+    const raw = fs.readFileSync(envPath, 'utf8');
+    const keys = [];
+    for (const line of raw.split('\n')) {
+      const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+      if (m) keys.push(m[1]);
+    }
+    console.log('Keys in .env:', keys.join(', ') || '(none)');
+    return;
+  }
+  if (sub === 'check') {
+    if (!existsSync(envPath)) {
+      console.log('MISSING .env file at', envPath);
+      return;
+    }
+    const raw = fs.readFileSync(envPath, 'utf8');
+    const map = {};
+    for (const line of raw.split('\n')) {
+      const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+      if (m) map[m[1]] = m[2].trim();
+    }
+    for (const k of ENV_KEYS_TO_CHECK) {
+      const v = map[k];
+      const ok = v && v.length && v !== '""' && v !== "''";
+      console.log(`  ${k.padEnd(22)} ${ok ? 'OK' : 'MISSING or empty'}`);
+    }
+    return;
+  }
+  console.error('Usage: env check | env show');
+}
+
+function handleLibs(ws) {
+  for (const L of ws.angularLibs) {
+    console.log(`  ${L.folderName.padEnd(28)} ${String(L.packageName).padEnd(44)} v${L.version}`);
+  }
+}
+
+function handlePackages(ws) {
+  if (!ws.angularRoot) return;
+  const list = ws.publishList;
+  list.forEach((p, i) => {
+    const rel = p.labelRel || p.folderName;
+    console.log(`  [${i + 1}] ${p.name.padEnd(42)} v${p.version}  (${rel})`);
+  });
+}
+
+function handleRepos(ws) {
+  for (const r of ws.repos) {
+    let remote = '';
+    try {
+      remote = execSync('git remote get-url origin', { cwd: r.absPath, encoding: 'utf8', shell: true }).trim();
+    } catch {
+      remote = '(no origin)';
+    }
+    console.log(`  ${r.name.padEnd(22)} ${remote}`);
+  }
+}
+
+function handleVersions(ws) {
+  handlePackages(ws);
+}
+
+function handleDeps(ws, pkgQuery) {
+  if (!pkgQuery) {
+    console.error('Usage: deps <package-name>');
+    return;
+  }
+  const needle = pkgQuery.trim();
+  const roots = [ws.monorepoRoot, ws.angularRoot].filter(Boolean);
+  const seen = new Set();
+  function scanFile(pjPath) {
+    const pkg = safeReadJson(pjPath);
+    if (!pkg) return;
+    const sections = ['dependencies', 'devDependencies', 'peerDependencies'];
+    for (const sec of sections) {
+      const o = pkg[sec];
+      if (!o || typeof o !== 'object') continue;
+      if (Object.prototype.hasOwnProperty.call(o, needle)) {
+        console.log(`  ${path.relative(ws.monorepoRoot, pjPath) || pjPath}  [${sec}]`);
+      }
+    }
+  }
+  function walk(dir, depth) {
+    if (depth > 6) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist' || e.name === 'A-RND') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (e.name === 'package.json') {
+        const rp = path.resolve(full);
+        if (seen.has(rp)) continue;
+        seen.add(rp);
+        scanFile(rp);
+      }
+    }
+  }
+  for (const root of roots) {
+    if (existsSync(path.join(root, 'package.json'))) scanFile(path.join(root, 'package.json'));
+    walk(root, 0);
+  }
+}
+
+async function runBuild(ws, name) {
+  if (!name) {
+    console.error('Usage: build <short-name|folder|scoped-package>   e.g. build fees');
+    return;
+  }
+  const folder = resolveBuildToken(name, ws);
+  const prev = process.cwd();
+  try {
+    process.chdir(ws.angularRoot);
+    await buildProject(folder, false);
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+async function runBuildAll(ws) {
+  const prev = process.cwd();
+  try {
+    process.chdir(ws.angularRoot);
+    await buildAllProjects(false);
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+/** Old cide start behavior (ts-node-dev from cide.json) — use: start legacy */
+function handleStartLegacyProject(ws) {
+  const prev = process.cwd();
+  try {
+    if (ws.nodeBackend) process.chdir(ws.nodeBackend.absPath);
+    startProject();
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+function handleWatch(ws, args) {
+  const prev = process.cwd();
+  try {
+    process.chdir(ws.angularRoot);
+    process.argv = ['node', 'cide', 'watch', ...(args || [])];
+    watchLinkProject();
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+function tokenize(line) {
+  const t = line.trim();
+  if (!t) return [];
+  const parts = [];
+  let i = 0;
+  while (i < t.length) {
+    while (i < t.length && /\s/.test(t[i])) i++;
+    if (i >= t.length) break;
+    if (t[i] === '"') {
+      i++;
+      let s = '';
+      while (i < t.length && t[i] !== '"') s += t[i++];
+      if (t[i] === '"') i++;
+      parts.push(s);
+    } else {
+      let s = '';
+      while (i < t.length && !/\s/.test(t[i])) s += t[i++];
+      parts.push(s);
+    }
+  }
+  return parts;
+}
+
+function printHelp(group) {
+  const g = (group || '').toLowerCase();
+  const all = !g || g === 'all';
+  if (all || g === 'git') {
+    console.log(`
+Git: status | commit "msg" | push [repo] | pull [repo] | diff [repo] | log [repo] | stash [repo] | branch [repo]`);
+  }
+  if (all || g === 'build') {
+    console.log(`
+Build: build [-p 1|all|…] [--resume-from N] | build <name> | build-all | libs`);
+  }
+  if (all || g === 'publish') {
+    console.log(`
+Publish: publish [--force] | install-global [--force]
+        On publish failure: use --retry-from N (same step, no double bump) or --resume-from N (next step)`);
+  }
+  if (all || g === 'server') {
+    console.log(`
+Server: server build | start | dev | stop | init | listener start|stop|status|restart | seed [name]`);
+  }
+  if (all || g === 'upload') {
+    console.log(`
+Upload: upload [N] | upload --list | upload --history | upload --rollback`);
+  }
+  if (all || g === 'angular' || g === 'ui') {
+    console.log(`
+Angular workspace: serve | tailwind | lint | test | analyze`);
+  }
+  if (all || g === 'npm') {
+    console.log(`
+npm: npm install <repo>|all [--force] | npm update <repo> [--force] | npm outdated <repo> | npm list <repo>`);
+  }
+  if (all || g === 'env') {
+    console.log(`
+Env: env check | env show`);
+  }
+  if (all || g === 'info') {
+    console.log(`
+Info: packages | repos | versions | deps <pkg>`);
+  }
+  if (all || g === 'start') {
+    console.log(`
+Start: start — list Angular / Node / Tailwind; in IDE: paste commands in new terminal; else: new OS window (Win)
+       start 1 | start 1,3 | start 1-3 | start all  — skip the menu
+       start legacy — old startProject() from cide.json`);
+  }
+  if (all) {
+    console.log(`
+Other: help [group] | clear | exit`);
+  }
+}
+
+/**
+ * @returns {Promise<{ skipPrompt?: boolean }|void>}
+ */
+async function dispatchLine(ws, line, rl) {
+  const tokens = tokenize(line);
+  if (!tokens.length) return;
+  const cmd = tokens[0].toLowerCase();
+  const rest = tokens.slice(1);
+
+  if (cmd === 'exit' || cmd === 'quit') {
+    // Must set before rl.close(): 'close' can fire synchronously; if _shellExiting is still false,
+    // the handler would reopen readline and "exit" would appear to do nothing (quit looked flaky too).
+    _shellExiting = true;
+    rl.close();
+    return { skipPrompt: true };
+  }
+  if (cmd === 'clear') {
+    console.clear();
+    return;
+  }
+  if (cmd === 'help') {
+    printHelp(rest[0]);
+    return;
+  }
+
+  if (!ws.angularRoot && !['help', 'exit', 'quit', 'clear', 'server', 'upload'].includes(cmd)) {
+    console.error(
+      'No Angular workspace found. cd into a folder with angular cide.json (or a monorepo parent that contains it), then run cide shell again.'
+    );
+    return;
+  }
+
+  try {
+    if (cmd === 'status') handleStatus(ws);
+    else if (cmd === 'commit') handleCommit(ws, rest.join(' '));
+    else if (cmd === 'push') handlePush(ws, rest[0]);
+    else if (cmd === 'pull') handlePull(ws, rest[0]);
+    else if (cmd === 'diff') handleDiff(ws, rest[0]);
+    else if (cmd === 'log') handleLog(ws, rest[0]);
+    else if (cmd === 'stash') handleStash(ws, rest[0]);
+    else if (cmd === 'branch') handleBranch(ws, rest[0]);
+    else if (cmd === 'build-all' || cmd === 'buildall') await runBuildAll(ws);
+    else if (cmd === 'build') {
+      const prev = process.cwd();
+      try {
+        process.chdir(ws.angularRoot);
+        const hasFlag = rest.some((r) => String(r).startsWith('-'));
+        if (rest.length === 0 || hasFlag) {
+          const opts = parseBuildShellArgs(rest);
+          await buildWorkspace({ readlineInterface: rl, ...opts });
+        } else {
+          await runBuild(ws, rest[0]);
+        }
+      } catch (e) {
+        console.error(e.message || e);
+      } finally {
+        process.chdir(prev);
+      }
+    }
+    else if (cmd === 'libs') handleLibs(ws);
+    else if (cmd === 'publish') {
+      const prev = process.cwd();
+      try {
+        process.chdir(ws.angularRoot);
+        const force = rest.includes('--force');
+        await publishPackage({ readlineInterface: rl, force });
+      } catch (e) {
+        console.error(e);
+      } finally {
+        process.chdir(prev);
+      }
+      return { skipPrompt: false };
+    } else if (cmd === 'install-global') {
+      const prev = process.cwd();
+      try {
+        process.chdir(ws.angularRoot);
+        const force = rest.includes('--force');
+        await installGlobalPackage({ readlineInterface: rl, force });
+      } catch (e) {
+        console.error(e);
+      } finally {
+        process.chdir(prev);
+      }
+      return { skipPrompt: false };
+    } else if (cmd === 'server') await handleServer(ws, rest[0]?.toLowerCase(), rest.slice(1), rl);
+    else if (cmd === 'seed') handleSeed(ws, rest[0]);
+    else if (cmd === 'serve') handleServe(ws);
+    else if (cmd === 'tailwind') handleTailwind(ws);
+    else if (cmd === 'lint') handleLint(ws);
+    else if (cmd === 'test') handleTest(ws);
+    else if (cmd === 'analyze') handleAnalyze(ws);
+    else if (cmd === 'npm') handleNpm(ws, tokens);
+    else if (cmd === 'env') handleEnv(ws, rest[0]?.toLowerCase());
+    else if (cmd === 'packages') handlePackages(ws);
+    else if (cmd === 'repos') handleRepos(ws);
+    else if (cmd === 'versions') handleVersions(ws);
+    else if (cmd === 'deps') handleDeps(ws, rest[0]);
+    else if (cmd === 'start') await handleStartCommand(ws, rl, rest);
+    else if (cmd === 'watch') handleWatch(ws, rest);
+    else if (cmd === 'upload') {
+      const uploadOpts = { readlineInterface: rl };
+      if (rest.includes('--list')) uploadOpts.list = true;
+      else if (rest.includes('--history')) uploadOpts.history = true;
+      else if (rest.includes('--rollback')) uploadOpts.rollback = true;
+      // Parse --server flag value
+      const serverIdx = rest.indexOf('--server');
+      if (serverIdx !== -1 && rest[serverIdx + 1]) uploadOpts.server = rest[serverIdx + 1];
+      // Parse -m / --message flag value
+      let msgIdx = rest.indexOf('-m');
+      if (msgIdx === -1) msgIdx = rest.indexOf('--message');
+      if (msgIdx !== -1 && rest[msgIdx + 1]) uploadOpts.message = rest[msgIdx + 1];
+      // First non-flag token (that isn't the --server value) is the project number
+      const num = rest.find((r, i) => !String(r).startsWith('-') && i !== serverIdx + 1);
+      if (num) uploadOpts.packages = num;
+      await uploadProject(uploadOpts);
+    }
+    else console.error(`Unknown command: "${line.trim()}". Type "help".`);
+  } catch (e) {
+    console.error(e.message || e);
+  }
+}
+
+let _shellExiting = false;
+
+function openReadline(ws) {
+  // Keep stdin alive so the process never ends unless the user types exit/quit
+  process.stdin.resume();
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: PROMPT,
+    historySize: 100,
+  });
+
+  let busy = false;
+
+  function safePrompt() {
+    if (!busy && !_shellExiting) rl.prompt();
+  }
+
+  rl.prompt();
+
+  rl.on('line', async (raw) => {
+    const line = raw.trim();
+    if (!line) {
+      safePrompt();
+      return;
+    }
+    // Queue the command; if busy just wait (sequentially)
+    busy = true;
+    try {
+      const r = await dispatchLine(ws, line, rl);
+      if (r && r.skipPrompt) {
+        return;
+      }
+    } catch (e) {
+      console.error(e.message || e);
+    } finally {
+      busy = false;
+      if (!_shellExiting) safePrompt();
+    }
+  });
+
+  rl.on('close', () => {
+    if (_shellExiting) {
+      console.log('Goodbye.');
+      process.exit(0);
+    }
+    // stdin was closed by the terminal emulator but user did NOT type exit.
+    // Re-open readline so the session persists.
+    process.stdout.write('\n');
+    setImmediate(() => openReadline(ws));
+  });
+
+  // Ctrl+C — show prompt again, do NOT exit
+  process.removeAllListeners('SIGINT');
+  process.on('SIGINT', () => {
+    process.stdout.write('\n(Ctrl+C caught — type "exit" or "quit" to leave)\n');
+    busy = false;
+    safePrompt();
+  });
+}
+
+function startShell() {
+  _shellExiting = false;
+  const ws = loadWorkspace();
+  printStartupScan(ws);
+  openReadline(ws);
+}
+
+module.exports = { startShell, loadWorkspace, tokenize, discoverRunnableProjects };