cloud-ide-cide 2.0.34

package/publishPackage.js

@@ -0,0 +1,969 @@
+/**
+ * cide publish — interactive multi-package publish to GitHub Packages,
+ * with workspace-wide dependent updates (file: and ^ → ^newVersion).
+ *
+ * Dependent refresh skips `<angularRoot>/<dist>` (ng-packagr output): those package.json
+ * files are not workspace consumers, and `npm install` there caused duplicate @angular
+ * installs and flaky DI / InputSignal types.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { resolveNgProjectNameForPackageDir } = require('./resolveNgProjectName');
+
+const GPR_HOST = 'npm.pkg.github.com';
+
+function existsSync(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True if `childPath` is `ancestorPath` or a file/folder inside it (Windows-safe). */
+function isPathInsideOrEqual(childPath, ancestorPath) {
+  const c = path.resolve(childPath);
+  const a = path.resolve(ancestorPath);
+  if (c === a) return true;
+  const rel = path.relative(a, c);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function writeJson(p, obj) {
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+}
+
+function isGithubPackagesPublishable(pkg) {
+  const r = pkg && pkg.publishConfig && pkg.publishConfig.registry;
+  return typeof r === 'string' && r.includes(GPR_HOST);
+}
+
+function bumpSemver(version, kind) {
+  const m = String(version).match(/^(\d+)\.(\d+)\.(\d+)(.*)?$/);
+  if (!m) throw new Error(`Invalid semver: ${version}`);
+  let major = parseInt(m[1], 10);
+  let minor = parseInt(m[2], 10);
+  let patch = parseInt(m[3], 10);
+  const rest = m[4] || '';
+  if (kind === 'major') {
+    major += 1;
+    minor = 0;
+    patch = 0;
+  } else if (kind === 'minor') {
+    minor += 1;
+    patch = 0;
+  } else {
+    patch += 1;
+  }
+  return `${major}.${minor}.${patch}${rest}`;
+}
+
+function question(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => resolve(answer));
+  });
+}
+
+/**
+ * Resolve workspace: angularRoot = cwd (where cide.json lives),
+ * monorepoRoot = workspace_root relative to angularRoot (default ".")
+ */
+function loadCideConfig(angularRoot) {
+  const cidePath = path.join(angularRoot, 'cide.json');
+  if (!existsSync(cidePath)) {
+    return { cide: {}, angularRoot, monorepoRoot: angularRoot, cidePath: null };
+  }
+  const cide = readJson(cidePath);
+  const wr = cide.workspace_root != null ? cide.workspace_root : '.';
+  const monorepoRoot = path.resolve(angularRoot, wr);
+  return { cide, angularRoot, monorepoRoot, cidePath };
+}
+
+function safeReaddir(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Angular lib dist output: ng-packagr "dest" is relative to the project folder
+ * (e.g. ../../dist/@cloudidesys/cloud-ide-element). Do not assume dist/<folderName>.
+ */
+function resolveAngularDistDir(angularRoot, distPath, entry) {
+  const ngPkgPath = path.join(entry.absDir, 'ng-package.json');
+  if (existsSync(ngPkgPath)) {
+    try {
+      const ngPkg = readJson(ngPkgPath);
+      if (ngPkg.dest) {
+        return path.resolve(entry.absDir, ngPkg.dest);
+      }
+    } catch {
+      /* fall through */
+    }
+  }
+  const scopedDist = path.join(angularRoot, distPath, '@cloudidesys', entry.folderName);
+  if (existsSync(scopedDist)) return scopedDist;
+  return path.join(angularRoot, distPath, entry.folderName);
+}
+
+/**
+ * Collect publishable packages: projects/* under angular root, sibling_packages, and monorepo children with publishConfig.
+ */
+function discoverPublishablePackages({ cide, angularRoot, monorepoRoot }) {
+  const seen = new Set();
+  const list = [];
+
+  // workspaceRoot defaults to angularRoot; sibling Angular workspaces override this per-entry
+  function add(absDir, kind, labelRel, workspaceRoot) {
+    const resolved = path.resolve(absDir);
+    if (seen.has(resolved)) return;
+    const pj = path.join(absDir, 'package.json');
+    if (!existsSync(pj)) return;
+    let pkg;
+    try {
+      pkg = readJson(pj);
+    } catch {
+      return;
+    }
+    if (!isGithubPackagesPublishable(pkg)) return;
+    seen.add(resolved);
+    const folderName = path.basename(absDir);
+    list.push({
+      absDir: resolved,
+      packageJsonPath: pj,
+      name: pkg.name,
+      version: pkg.version || '0.0.0',
+      folderName,
+      kind, // 'angular-lib' | 'node-package'
+      labelRel,
+      workspaceRoot: path.resolve(workspaceRoot || angularRoot),
+      hasBuildScript: !!(pkg.scripts && pkg.scripts.build),
+    });
+  }
+
+  // Angular libraries: angularRoot/projects/* and projects/@cloudidesys/* (scoped layout)
+  const projectsDir = path.join(angularRoot, 'projects');
+  if (existsSync(projectsDir)) {
+    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;
+          add(path.join(scoped, e2.name), 'angular-lib', path.join('projects', '@cloudidesys', e2.name));
+        }
+        continue;
+      }
+      add(path.join(projectsDir, e.name), 'angular-lib', path.join('projects', e.name));
+    }
+  }
+
+  // Explicit sibling_packages (paths relative to angularRoot)
+  // If a sibling is an Angular workspace (has angular.json + projects/), scan its projects too.
+  const siblings = Array.isArray(cide.sibling_packages) ? cide.sibling_packages : [];
+  for (const rel of siblings) {
+    const abs = path.resolve(angularRoot, rel);
+    const siblingProjectsDir = path.join(abs, 'projects');
+    const siblingAngularJson = path.join(abs, 'angular.json');
+    if (existsSync(siblingAngularJson) && existsSync(siblingProjectsDir)) {
+      // Angular workspace sibling — scan its projects/* for publishable libs, build from sibling root
+      for (const e of safeReaddir(siblingProjectsDir)) {
+        if (!e.isDirectory()) continue;
+        if (e.name === '@cloudidesys') {
+          const scoped = path.join(siblingProjectsDir, e.name);
+          for (const e2 of safeReaddir(scoped)) {
+            if (!e2.isDirectory()) continue;
+            add(path.join(scoped, e2.name), 'angular-lib', path.join(rel, 'projects', '@cloudidesys', e2.name), abs);
+          }
+          continue;
+        }
+        add(path.join(siblingProjectsDir, e.name), 'angular-lib', path.join(rel, 'projects', e.name), abs);
+      }
+    } else {
+      add(abs, 'node-package', rel.replace(/\\/g, '/'));
+    }
+  }
+
+  // Auto: immediate children of monorepoRoot with publishable package.json
+  for (const e of safeReaddir(monorepoRoot)) {
+    if (!e.isDirectory()) continue;
+    if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+    const abs = path.join(monorepoRoot, e.name);
+    if (path.resolve(abs) === path.resolve(angularRoot)) continue;
+    add(abs, 'node-package', e.name);
+  }
+
+  // Angular workspace root app package.json if publishable (unusual)
+  add(angularRoot, 'node-package', '.');
+
+  return list;
+}
+
+function parseSelection(input, maxN) {
+  const s = String(input).trim().toLowerCase();
+  if (s === 'q' || s === 'quit' || s === '') return null;
+  if (s === 'all') {
+    return 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);
+    }
+  }
+  return [...set].sort((a, b) => a - b);
+}
+
+/** Loose semver X.Y.Z (allows pre-release suffix) */
+function isValidSemverString(v) {
+  return /^\d+\.\d+\.\d+/.test(String(v).trim());
+}
+
+/**
+ * Parse --packages / interactive input.
+ * Form A: 1,3,5 | 1-5 | all  → indices only, versionByIndex null
+ * Form B: 1=2.0.1,4=1.2.0    → each index gets its version (1-based index in list)
+ */
+function parsePackagePublishSpec(raw, maxN) {
+  const s = String(raw).trim();
+  if (!s || s.toLowerCase() === 'q' || s.toLowerCase() === 'quit') {
+    return { ok: false, error: 'cancelled', indices: [], versionByIndex: null };
+  }
+  if (s.toLowerCase() === 'all') {
+    return {
+      ok: true,
+      indices: Array.from({ length: maxN }, (_, i) => i),
+      versionByIndex: null,
+    };
+  }
+  if (s.includes('=')) {
+    const versionByIndex = new Map();
+    const parts = s.split(',').map((p) => p.trim()).filter(Boolean);
+    for (const part of parts) {
+      const eq = part.indexOf('=');
+      if (eq < 0) {
+        return {
+          ok: false,
+          error: `Mixed format: use only "num=version" pairs in one line (got: "${part}").`,
+          indices: [],
+          versionByIndex: null,
+        };
+      }
+      const idxStr = part.slice(0, eq).trim();
+      const ver = part.slice(eq + 1).trim();
+      const idx1 = parseInt(idxStr, 10);
+      if (!Number.isFinite(idx1) || idx1 < 1 || idx1 > maxN) {
+        return { ok: false, error: `Invalid index: ${idxStr} (valid 1–${maxN})`, indices: [], versionByIndex: null };
+      }
+      if (!isValidSemverString(ver)) {
+        return { ok: false, error: `Invalid version for #${idx1}: "${ver}" (need e.g. 2.0.1)`, indices: [], versionByIndex: null };
+      }
+      versionByIndex.set(idx1 - 1, ver);
+    }
+    const indices = [...versionByIndex.keys()].sort((a, b) => a - b);
+    return { ok: true, indices, versionByIndex };
+  }
+  const indices = parseSelection(s, maxN);
+  if (indices === null || indices.length === 0) {
+    return { ok: false, error: 'No valid package numbers.', indices: [], versionByIndex: null };
+  }
+  return { ok: true, indices, versionByIndex: null };
+}
+
+function printPublishUsageBox() {
+  console.log(`
+----------------------------------------------------------------
+ HOW TO PUBLISH — read this FIRST, then use the numbered list below
+----------------------------------------------------------------
+  NUMBERS ONLY (then you will choose version or patch/minor/major):
+    1                 single package from the list
+    1,3,5             several packages
+    1-5               range (1 through 5)
+    all               every package in the list
+
+  NUMBERS + EXACT VERSION (no second question — each gets its version):
+    1=2.0.1           package [1] will be published as 2.0.1
+    1=2.0.1,4=1.2.0   package [1] as 2.0.1, package [4] as 1.2.0
+
+  CANCEL entire publish: q
+----------------------------------------------------------------
+  Non-interactive (same rules; no prompts):
+  cide publish -p 1 --set-version 2.0.1
+  cide publish -p "1,4,5" --bump minor
+  cide publish -p "1=2.0.1,4=1.2.0" --global 3
+  cide publish --help          ← full flags and more examples
+
+  After a failure (same -p list):
+  --resume-from N     start at step N of the batch (skip 1..N-1); fix failed package.json if needed first
+  --continue-on-error keep going without stopping at the first failure
+----------------------------------------------------------------
+`);
+}
+
+/**
+ * After publish: optional npm install -g using SAME numbered list.
+ * Skip if user types: n | no | none | skip | 0 | - | empty
+ */
+function parseGlobalInstallSpec(raw, maxN) {
+  const s = String(raw).trim().toLowerCase();
+  if (!s || s === 'n' || s === 'no' || s === 'none' || s === 'skip' || s === '-' || s === '0' || s === 'q' || s === 'quit') {
+    return { ok: true, skip: true, indices: [] };
+  }
+  const indices = parseSelection(s, maxN);
+  if (indices === null || indices.length === 0) {
+    return { ok: false, skip: false, indices: [], error: 'No valid numbers. Type n to skip global install.' };
+  }
+  return { ok: true, skip: false, indices };
+}
+
+function printGlobalInstallUsageBox() {
+  console.log(`
+----------------------------------------------------------------
+ GLOBAL npm install (optional) — uses the SAME numbers as the list
+----------------------------------------------------------------
+  After publishing, you can install packages from the registry globally.
+  Type ONE line BEFORE you are asked — examples:
+
+    3                 global-install only item [3]  →  npm install -g name@version
+    2,5               global-install [2] and [5]
+    1-4               global-install every item from [1] through [4]
+    all               global-install every item in the list (use carefully)
+
+  SKIP (no global install) — type any of:
+    n     no     none     skip     0     -     q     (or just press Enter)
+
+  Non-interactive (with publish):
+    cide publish -p 1 --set-version 2.0.1 --global 3
+    cide publish -p all --bump patch --global "2,5"
+
+  Standalone (no publish):
+    cide install-global
+    cide install-global -p 3
+    cide install-global --help
+----------------------------------------------------------------
+`);
+}
+
+function npmInstallGlobalForEntries(packages, indices, npmOpts = {}) {
+  const force = npmOpts.force ? ' --force' : '';
+  for (const idx of indices) {
+    const entry = packages[idx];
+    if (!entry) {
+      console.warn(`  ⚠ Skip invalid index ${idx + 1}`);
+      continue;
+    }
+    const pkg = readJson(entry.packageJsonPath);
+    const name = pkg.name;
+    const version = pkg.version || '0.0.0';
+    if (!name) {
+      console.warn(`  ⚠ Skip index ${idx + 1}: missing package name`);
+      continue;
+    }
+    const spec = `${name}@${version}`;
+    console.log(`  npm install -g ${spec}${force ? ' --force' : ''}`);
+    try {
+      execSync(`npm install -g ${JSON.stringify(spec)}${force}`, { stdio: 'inherit' });
+    } catch (e) {
+      console.error(`  ⚠ Global install failed for ${spec}:`, e.message);
+    }
+  }
+}
+
+async function runOptionalGlobalInstall(rl, packages, options) {
+  const maxN = packages.length;
+  const cliGlobal = options.global != null ? String(options.global).trim() : '';
+
+  if (cliGlobal.length > 0) {
+    const g = parseGlobalInstallSpec(cliGlobal, maxN);
+    if (!g.ok) {
+      console.error(g.error || 'Invalid --global');
+      return;
+    }
+    if (g.skip || g.indices.length === 0) {
+      console.log('\n(Skipping global install: --global is n / skip / empty.)\n');
+      return;
+    }
+    console.log('\n--- Global install (from --global) ---');
+    npmInstallGlobalForEntries(packages, g.indices, { force: !!options.force });
+    return;
+  }
+
+  if (options.packages != null && String(options.packages).trim() !== '') {
+    // Non-interactive publish without --global → skip global step
+    return;
+  }
+
+  printGlobalInstallUsageBox();
+  const raw = await question(rl, 'Global install: type numbers (or n / Enter to skip): ');
+  const g = parseGlobalInstallSpec(raw, maxN);
+  if (!g.ok) {
+    console.error(g.error || 'Invalid input.');
+    return;
+  }
+  if (g.skip || g.indices.length === 0) {
+    console.log('\n(No global install.)\n');
+    return;
+  }
+  console.log('\n--- Global install ---');
+  npmInstallGlobalForEntries(packages, g.indices, { force: !!options.force });
+}
+
+/**
+ * Standalone: cide install-global — npm install -g by workspace list index.
+ * @param {object} [options]
+ * @param {string} [options.packages] - same index spec as -p (1,3,5 | 1-5 | all | n)
+ * @param {import('readline').Interface} [options.readlineInterface] - Reuse shell readline when inside `cide shell`
+ * @param {boolean} [options.force] - Pass --force to npm install -g
+ */
+async function installGlobalPackage(options = {}) {
+  const cliPackages = options.packages != null ? String(options.packages).trim() : '';
+  const fromCli = cliPackages.length > 0;
+
+  const angularRoot = process.cwd();
+  const { cide, monorepoRoot } = loadCideConfig(angularRoot);
+
+  if (!existsSync(path.join(angularRoot, 'cide.json'))) {
+    console.warn('No cide.json in current directory — using cwd as both angular and monorepo root.');
+  }
+
+  console.log('\nScanning workspace for publishable packages (global install uses name@version from each package.json)...\n');
+  const packages = discoverPublishablePackages({ cide, angularRoot, monorepoRoot });
+  if (!packages.length) {
+    console.error('No publishable packages found (need publishConfig.registry → GitHub Packages).');
+    return;
+  }
+
+  if (!fromCli) {
+    printGlobalInstallUsageBox();
+  }
+
+  console.log('Packages:\n');
+  packages.forEach((p, i) => {
+    const rel = p.labelRel || p.folderName;
+    console.log(`  [${i + 1}]  ${p.name.padEnd(42)} v${p.version}    (${rel})`);
+  });
+
+  const ownsReadline = !options.readlineInterface;
+  const rl = options.readlineInterface || readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const raw = fromCli ? cliPackages : await question(rl, '\nYour choice (see HOW TO above): ');
+    const g = parseGlobalInstallSpec(raw, packages.length);
+    if (!g.ok) {
+      if (g.error) console.error(g.error);
+      return;
+    }
+    if (g.skip || g.indices.length === 0) {
+      console.log('\n(No global install.)\n');
+      return;
+    }
+    console.log('\n--- npm install -g ---\n');
+    npmInstallGlobalForEntries(packages, g.indices, { force: !!options.force });
+    console.log('\n✅ Done.\n');
+  } finally {
+    if (ownsReadline) rl.close();
+  }
+}
+
+/**
+ * Find every package.json under root (max depth), skip node_modules, .git.
+ * @param {object} [opts]
+ * @param {string[]} [opts.excludeAncestorDirs] - Absolute dirs: never collect package.json under these (e.g. Angular ng-packagr output).
+ */
+function findConsumerPackageJsonFiles(root, maxDepth = 5, opts = {}) {
+  const excludeAncestorDirs = Array.isArray(opts.excludeAncestorDirs)
+    ? opts.excludeAncestorDirs.map((d) => path.resolve(d))
+    : [];
+
+  function shouldSkipPath(absPath) {
+    for (const ex of excludeAncestorDirs) {
+      if (isPathInsideOrEqual(absPath, ex)) return true;
+    }
+    return false;
+  }
+
+  const files = [];
+  function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    const absDir = path.resolve(dir);
+    if (shouldSkipPath(absDir)) 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 === 'A-RND') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'dist' && depth > 0) {
+          // skip dist subtrees (built output); still allow root-level if any
+          continue;
+        }
+        const absFull = path.resolve(full);
+        if (shouldSkipPath(absFull)) continue;
+        const pj = path.join(full, 'package.json');
+        if (existsSync(pj) && !shouldSkipPath(path.resolve(pj))) files.push(pj);
+        walk(full, depth + 1);
+      }
+    }
+  }
+  const rootPj = path.join(root, 'package.json');
+  if (existsSync(rootPj)) {
+    if (!shouldSkipPath(path.resolve(rootPj))) files.push(rootPj);
+  }
+  walk(root, 0);
+  return [...new Set(files.map((f) => path.resolve(f)))];
+}
+
+function shouldReplaceDepVersion(cur) {
+  if (typeof cur !== 'string') return false;
+  if (cur === '*') return false;
+  if (cur.startsWith('workspace:')) return false;
+  if (cur.startsWith('file:')) return true;
+  if (cur.startsWith('^') || cur.startsWith('~')) return true;
+  if (/^\d/.test(cur)) return true;
+  if (cur === 'latest') return true;
+  return false;
+}
+
+function updateDepsSection(section, packageName, newCaret) {
+  if (!section || typeof section !== 'object') return false;
+  if (!Object.prototype.hasOwnProperty.call(section, packageName)) return false;
+  const cur = section[packageName];
+  if (!shouldReplaceDepVersion(cur)) return false;
+  section[packageName] = newCaret;
+  return true;
+}
+
+/**
+ * Update all workspace package.json files that depend on packageName.
+ * excludePackageJsonPaths: published package.json path(s) to skip (consumers only).
+ * @param {object} [depOptions]
+ * @param {string} [depOptions.distPath] - Relative to angularRoot (default `dist`). Ignores package.json under this tree so ng-packagr output is never treated as a workspace consumer (avoids stale edits and `npm install` duplicating @angular in dist).
+ */
+function updateDependentsInWorkspace(monorepoRoot, angularRoot, packageName, newVersion, excludePackageJsonPaths, depOptions = {}) {
+  const newCaret = `^${newVersion}`;
+  const exclude = new Set((excludePackageJsonPaths || []).map((p) => path.resolve(p)));
+  const distPathRel = depOptions.distPath != null ? depOptions.distPath : 'dist';
+  const angularDistAbs = path.resolve(angularRoot, distPathRel);
+  const findOpts = { excludeAncestorDirs: [angularDistAbs] };
+
+  const roots = [...new Set([path.resolve(monorepoRoot), path.resolve(angularRoot)])];
+  const allPj = new Set();
+  for (const r of roots) {
+    for (const f of findConsumerPackageJsonFiles(r, 5, findOpts)) {
+      allPj.add(f);
+    }
+  }
+  const touchedDirs = new Set();
+  for (const pjPath of allPj) {
+    if (exclude.has(path.resolve(pjPath))) continue;
+    let pkg;
+    try {
+      pkg = readJson(pjPath);
+    } catch {
+      continue;
+    }
+    let changed = false;
+    if (updateDepsSection(pkg.dependencies, packageName, newCaret)) changed = true;
+    if (updateDepsSection(pkg.devDependencies, packageName, newCaret)) changed = true;
+    if (updateDepsSection(pkg.peerDependencies, packageName, newCaret)) changed = true;
+    if (changed) {
+      writeJson(pjPath, pkg);
+      touchedDirs.add(path.dirname(pjPath));
+      console.log(`    ${path.relative(monorepoRoot, pjPath) || path.basename(path.dirname(pjPath))} → ${newCaret}`);
+    }
+  }
+  return [...touchedDirs];
+}
+
+function runNpmInstall(dir, npmOpts = {}) {
+  const force = npmOpts.force ? ' --force' : '';
+  console.log(`  npm install in ${dir}${npmOpts.force ? ' (--force)' : ''}`);
+  try {
+    execSync(`npm install${force}`, { cwd: dir, stdio: 'inherit' });
+  } catch (e) {
+    console.error(`  ⚠ npm install failed in ${dir}:`, e.message);
+  }
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.packages] - CLI: -p / --packages
+ * @param {string} [options.setVersion] - CLI: exact semver for all selected (when not using idx=ver)
+ * @param {string} [options.bump] - CLI: patch | minor | major
+ * @param {import('readline').Interface} [options.readlineInterface] - If set (e.g. from `cide shell`), reuse this
+ *   instead of creating a second readline on stdin — avoids doubled keypresses (ppeettaattcchh).
+ * @param {boolean} [options.continueOnError] - If true, on failure log and continue with remaining packages (no prompt).
+ * @param {string|number} [options.resumeFrom] - 1-based step in this publish batch to start from (skips earlier steps).
+ * @param {boolean} [options.force] - Pass --force to npm install (dependents) and npm install -g (--global).
+ * @param {string|number} [options.retryFrom] - Same as --resume-from but skips version bump on that step only (retry failed publish).
+ * @param {boolean} [options.noBumpOnResume] - With --resume-from (step &gt; 1): do not bump on the resumed step.
+ */
+async function publishPackage(options = {}) {
+  const cliPackages = options.packages != null ? String(options.packages).trim() : '';
+  const cliSetVersion = options.setVersion != null ? String(options.setVersion).trim() : '';
+  const cliBump = options.bump != null ? String(options.bump).trim().toLowerCase() : 'patch';
+  const fromCli = cliPackages.length > 0;
+
+  const angularRoot = process.cwd();
+  const { cide, monorepoRoot } = loadCideConfig(angularRoot);
+
+  if (!existsSync(path.join(angularRoot, 'cide.json'))) {
+    console.warn('No cide.json in current directory — using cwd as both angular and monorepo root.');
+  }
+
+  console.log('\nScanning workspace for publishable packages...\n');
+  const packages = discoverPublishablePackages({ cide, angularRoot, monorepoRoot });
+  if (!packages.length) {
+    console.error('No publishable packages found (need publishConfig.registry → GitHub Packages).');
+    console.error('Check cide.json workspace_root / sibling_packages and package publishConfig.');
+    return;
+  }
+
+  if (!fromCli) {
+    printPublishUsageBox();
+  }
+
+  console.log('Publishable packages:\n');
+  packages.forEach((p, i) => {
+    const rel = p.labelRel || p.folderName;
+    console.log(`  [${i + 1}]  ${p.name.padEnd(42)} v${p.version}    (${rel})`);
+  });
+
+  const ownsReadline = !options.readlineInterface;
+  const rl = options.readlineInterface || readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    let parsed;
+    if (fromCli) {
+      parsed = parsePackagePublishSpec(cliPackages, packages.length);
+      if (!parsed.ok) {
+        if (parsed.error !== 'cancelled') console.error(parsed.error || 'Invalid --packages');
+        return;
+      }
+      if (cliSetVersion && parsed.versionByIndex) {
+        console.warn('Note: --set-version ignored because --packages uses num=version pairs.');
+      }
+    } else {
+      const raw = await question(rl, '\nYour choice (see HOW TO PUBLISH above): ');
+      parsed = parsePackagePublishSpec(raw, packages.length);
+      if (!parsed.ok) {
+        if (parsed.error !== 'cancelled') console.error(parsed.error || 'Invalid input.');
+        console.log('Aborted.');
+        return;
+      }
+    }
+
+    const { indices, versionByIndex } = parsed;
+
+    const rawRetryFrom = options.retryFrom != null ? String(options.retryFrom).trim() : '';
+    let rawResume = options.resumeFrom != null ? String(options.resumeFrom).trim() : '';
+    if (rawRetryFrom !== '') {
+      rawResume = rawRetryFrom;
+    }
+    const usedRetryFromShorthand = rawRetryFrom !== '';
+    const noBumpOnResumeFlag = !!options.noBumpOnResume;
+    const parsedResume = rawResume === '' ? 1 : parseInt(rawResume, 10);
+    const startStep =
+      Number.isFinite(parsedResume) && parsedResume >= 1 ? parsedResume : 1;
+    if (startStep > indices.length) {
+      console.error(
+        `--resume-from ${startStep} is past the end of this batch (${indices.length} step(s)). Nothing to do.`
+      );
+      return;
+    }
+    if (startStep > 1) {
+      const bumpHint =
+        usedRetryFromShorthand || (noBumpOnResumeFlag && startStep > 1)
+          ? ' (version bump skipped for this step — retry)'
+          : '';
+      console.log(
+        `\n(Resuming: skipping batch steps 1..${startStep - 1}, starting at step ${startStep}/${indices.length})${bumpHint}\n`
+      );
+    }
+
+    if (noBumpOnResumeFlag && startStep === 1 && !usedRetryFromShorthand) {
+      console.warn(
+        'Note: --no-bump-on-resume is ignored when starting at step 1 without --retry-from. Use --retry-from 1 to retry the first package without bumping.'
+      );
+    }
+
+    const continueOnError = !!options.continueOnError;
+
+    /** @type {string|null} same semver for every selected index when no per-index map */
+    let sharedExactVersion = null;
+    /** @type {string} */
+    let bumpKind = 'patch';
+
+    if (versionByIndex) {
+      // per-index versions already set
+    } else if (fromCli) {
+      if (cliSetVersion) {
+        if (!isValidSemverString(cliSetVersion)) {
+          console.error(`Invalid --set-version "${cliSetVersion}" (need e.g. 2.0.1)`);
+          return;
+        }
+        sharedExactVersion = cliSetVersion;
+      } else {
+        bumpKind = cliBump === 'major' || cliBump === 'minor' || cliBump === 'patch' ? cliBump : 'patch';
+      }
+    } else {
+      const vAns = (await question(
+        rl,
+        'Version for ALL selected: type exact semver (e.g. 2.0.1) OR press Enter to bump instead [patch]: '
+      )).trim();
+      if (isValidSemverString(vAns)) {
+        sharedExactVersion = vAns.match(/^\d+\.\d+\.\d+[^\s]*/)[0];
+      } else if (vAns !== '') {
+        bumpKind = vAns === 'major' || vAns === 'minor' ? vAns : 'patch';
+      } else {
+        const bumpAns = (await question(rl, 'Bump type? (patch / minor / major) [patch]: ')).trim().toLowerCase();
+        bumpKind = bumpAns === 'major' || bumpAns === 'minor' ? bumpAns : 'patch';
+      }
+    }
+
+    const distPath = cide.dist_path || 'dist';
+    const angularDistAbs = path.resolve(angularRoot, distPath);
+
+    function resolveNewVersion(entry, idx) {
+      if (versionByIndex && versionByIndex.has(idx)) {
+        return versionByIndex.get(idx);
+      }
+      if (sharedExactVersion) {
+        return sharedExactVersion;
+      }
+      return bumpSemver(entry.version, bumpKind);
+    }
+
+    let publishOk = 0;
+    let skippedAfterFailure = 0;
+
+    /** First step after resume: optionally skip bump (retry same step after failure). */
+    function shouldSkipBumpThisStep(k) {
+      if (k !== startStep - 1) return false;
+      if (usedRetryFromShorthand) return true;
+      if (noBumpOnResumeFlag && startStep > 1) return true;
+      return false;
+    }
+
+    function formatResumeFlagSuffix() {
+      const parts = [];
+      if (cliSetVersion) parts.push(`--set-version ${cliSetVersion}`);
+      else parts.push(`--bump ${cliBump === 'major' || cliBump === 'minor' || cliBump === 'patch' ? cliBump : 'patch'}`);
+      if (options.force) parts.push('--force');
+      if (options.continueOnError) parts.push('--continue-on-error');
+      const g = options.global != null ? String(options.global).trim() : '';
+      if (g) parts.push(`--global ${g}`);
+      return parts.length ? ` ${parts.join(' ')}` : '';
+    }
+
+    function printStoppedResumeHints(failedStep, nextStep, total) {
+      const pSpec =
+        fromCli && cliPackages ? cliPackages : '<same -p as before (e.g. all — must match your batch)>';
+      const flags = formatResumeFlagSuffix();
+      console.log('\nAfter fixing the issue, you can:');
+      console.log(
+        `  • Retry the SAME step (${failedStep}/${total}) without bumping again (version was already set in package.json):`
+      );
+      console.log(`    cide publish -p ${pSpec} --retry-from ${failedStep}${flags}`);
+      if (nextStep <= total) {
+        console.log(
+          `  • Or skip the failed package and continue from the NEXT step (${nextStep}/${total}) with a new bump:`
+        );
+        console.log(`    cide publish -p ${pSpec} --resume-from ${nextStep}${flags}`);
+      }
+      console.log(
+        '(Equivalent: --retry-from N = --resume-from N --no-bump-on-resume for that first resumed step.)'
+      );
+    }
+
+    for (let k = startStep - 1; k < indices.length; k++) {
+      const idx = indices[k];
+      const entry = packages[idx];
+      const n = k + 1;
+      const total = indices.length;
+
+      /** After an interactive [r]etry, do not bump version again (already written to package.json). */
+      let forceNoBump = false;
+      let stepComplete = false;
+
+      while (!stepComplete) {
+        console.log(`\n--- Publishing ${n}/${total}: ${entry.name} ---`);
+
+        let pkg = readJson(entry.packageJsonPath);
+        const oldVersion = pkg.version;
+        const skipBump = shouldSkipBumpThisStep(k) || forceNoBump;
+        let newVersion;
+        if (skipBump) {
+          newVersion = pkg.version;
+          console.log(
+            `  Version (unchanged${forceNoBump ? ' — retry same step' : ''}): ${newVersion}`
+          );
+        } else {
+          newVersion = resolveNewVersion(entry, idx);
+          pkg.version = newVersion;
+          writeJson(entry.packageJsonPath, pkg);
+          console.log(`  Version ${oldVersion} → ${newVersion}`);
+        }
+
+        const originalCwd = process.cwd();
+
+        try {
+          if (entry.kind === 'angular-lib') {
+            if (cide.templete !== 'angular') {
+              console.warn('  Warning: cide.templete is not "angular"; still running ng build.');
+            }
+            // entry.workspaceRoot is the Angular workspace that owns this library
+            // (may be a sibling workspace, e.g. LMS-UI, not the cwd where cide publish ran).
+            const entryWorkspaceRoot = entry.workspaceRoot || angularRoot;
+            const ngProjectName = resolveNgProjectNameForPackageDir(
+              entryWorkspaceRoot,
+              entry.absDir,
+              entry.packageJsonPath
+            );
+            console.log(`  Building: ng build --project "${ngProjectName}" (workspace: ${entryWorkspaceRoot})`);
+            execSync(`ng build --project "${ngProjectName}"`, { cwd: entryWorkspaceRoot, stdio: 'inherit', shell: true });
+
+            const distDir = resolveAngularDistDir(entryWorkspaceRoot, distPath, entry);
+            if (!existsSync(distDir)) {
+              throw new Error(`Dist folder not found: ${distDir}`);
+            }
+            console.log('  Publishing from dist...');
+            execSync('npm publish', { cwd: distDir, stdio: 'inherit' });
+          } else {
+            if (entry.hasBuildScript) {
+              console.log('  Building: npm run build');
+              execSync('npm run build', { cwd: entry.absDir, stdio: 'inherit' });
+            } else {
+              console.log('  Skipping build (no build script).');
+            }
+            console.log('  Publishing from package root...');
+            execSync('npm publish', { cwd: entry.absDir, stdio: 'inherit' });
+          }
+
+          console.log('  Updating dependents:');
+          const touched = updateDependentsInWorkspace(
+            monorepoRoot,
+            angularRoot,
+            entry.name,
+            newVersion,
+            [entry.packageJsonPath],
+            { distPath }
+          );
+          let rootsToInstall = new Set();
+          for (const d of touched) {
+            if (isPathInsideOrEqual(d, angularDistAbs)) {
+              console.log(`  (skip npm install in Angular build output: ${d})`);
+              continue;
+            }
+            
+            // In Angular workspaces, library dependencies are satisfied by the root node_modules.
+            // Installing inside projects/xyz creates unwanted local node_modules.
+            const absD = path.resolve(d);
+            const absRoot = path.resolve(angularRoot);
+            if (absD !== absRoot && isPathInsideOrEqual(absD, absRoot)) {
+              console.log(`  (skip npm install in library folder: ${d} — will install at workspace root instead)`);
+              rootsToInstall.add(absRoot);
+            } else {
+              rootsToInstall.add(absD);
+            }
+          }
+          
+          for (const rootToInstall of rootsToInstall) {
+            runNpmInstall(rootToInstall, { force: !!options.force });
+          }
+          if (touched.length === 0) {
+            console.log('    (no other package.json references updated)');
+          }
+          publishOk++;
+          stepComplete = true;
+        } catch (err) {
+          console.error(`  ❌ Failed: ${err.message}`);
+          process.chdir(originalCwd);
+
+          const nextStep = k + 2;
+          const canAsk =
+            rl &&
+            (process.stdin.isTTY || options.readlineInterface) &&
+            !continueOnError;
+
+          if (continueOnError) {
+            skippedAfterFailure++;
+            console.log('  (--continue-on-error: continuing with remaining packages.)');
+            stepComplete = true;
+          } else if (!canAsk) {
+            console.error('\nStopped.');
+            console.error(
+              '(Non-interactive: add --continue-on-error to keep going, or use --retry-from for the failed step / --resume-from for the next.)'
+            );
+            printStoppedResumeHints(n, nextStep, total);
+            throw err;
+          } else {
+            const ans = await question(
+              rl,
+              '\n[y] skip to next package / [r]etry this step (re-run build & publish; no extra bump) / [N] stop: '
+            );
+            const a = String(ans).trim().toLowerCase();
+            if (a === 'r' || a === 'retry') {
+              forceNoBump = true;
+              console.log(`\n  ↻ Retrying step ${n}/${total} (${entry.name})...\n`);
+              continue;
+            } else if (/^y(es)?$/i.test(a)) {
+              skippedAfterFailure++;
+              console.log('\n  (Leaving failed package as-is; continuing with the rest.)');
+              stepComplete = true;
+            } else {
+              console.log('\nStopped.');
+              printStoppedResumeHints(n, nextStep, total);
+              return;
+            }
+          }
+        } finally {
+          process.chdir(originalCwd);
+        }
+      }
+    }
+
+    const batchSteps = indices.length - (startStep - 1);
+    if (skippedAfterFailure === 0) {
+      console.log(`\n✅ Published ${publishOk} package(s) successfully.\n`);
+    } else {
+      console.log(
+        `\n⚠️ Batch finished: ${publishOk} published OK, ${skippedAfterFailure} failed (skipped; ${batchSteps} step(s) in this run).\n`
+      );
+    }
+
+    await runOptionalGlobalInstall(rl, packages, options);
+  } finally {
+    if (ownsReadline) rl.close();
+  }
+}
+
+publishPackage.loadCideConfig = loadCideConfig;
+publishPackage.discoverPublishablePackages = discoverPublishablePackages;
+publishPackage.installGlobalPackage = installGlobalPackage;
+publishPackage.parsePackagePublishSpec = parsePackagePublishSpec;
+
+module.exports = publishPackage;