@jskit-ai/jskit-cli 0.2.134 → 0.2.135

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.134",
+  "version": "0.2.135",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,7 +20,7 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.129",
+    "@jskit-ai/jskit-catalog": "0.1.130",
     "@jskit-ai/kernel": "0.1.120",
     "@jskit-ai/shell-web": "0.1.119",
     "@vue/compiler-sfc": "^3.5.29",

package/src/server/commandHandlers/appCommandCatalog.js

@@ -75,7 +75,7 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
   }),
   "update-packages": Object.freeze({
     name: "update-packages",
-    summary: "Update installed @jskit-ai dependencies and refresh managed migrations.",
+    summary: "Update @jskit-ai dependencies across the app and its npm workspaces.",
     usage: "jskit app update-packages [--registry <url>] [--dry-run]",
     options: Object.freeze([
       Object.freeze({
@@ -88,9 +88,9 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
       })
     ]),
     defaults: Object.freeze([
-      "Runtime and dev @jskit-ai dependencies are updated separately so package.json sections stay correct.",
-      "Each package is moved to the latest available major.x range and npm saves the resolved exact version.",
-      "Managed migrations and the composed CI workflow are refreshed afterwards unless --dry-run is used."
+      "Root runtime, development, optional, and peer dependencies are installed at their exact latest registry versions.",
+      "JSKIT ranges in npm workspace manifests and package descriptors are aligned with the latest major release, then workspace resolutions are refreshed in the lockfile.",
+      "The command reports elapsed progress and refreshes managed migrations and the composed CI workflow unless --dry-run is used."
     ])
   }),
   "sync-ci": Object.freeze({

package/src/server/commandHandlers/appCommands/shared.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import path from "node:path";
 import { access, mkdir, readFile, readdir, rm, symlink } from "node:fs/promises";
 
@@ -80,6 +80,94 @@ function runExternalCommand(
   });
 }
 
+function runExternalCommandAsync(
+  command,
+  args = [],
+  {
+    cwd = "",
+    env = {},
+    stdout,
+    stderr,
+    quiet = false,
+    createCliError
+  } = {}
+) {
+  return new Promise((resolve, reject) => {
+    let capturedStdout = "";
+    let capturedStderr = "";
+    let settled = false;
+    let child;
+
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      try {
+        resolve(ensureCommandSucceeded(result, command, {
+          createCliError,
+          cwd,
+          stdout,
+          stderr,
+          quiet: true
+        }));
+      } catch (error) {
+        reject(error);
+      }
+    };
+
+    try {
+      child = spawn(command, Array.isArray(args) ? args : [], {
+        cwd: cwd || process.cwd(),
+        env: {
+          ...process.env,
+          ...env
+        },
+        shell: process.platform === "win32"
+      });
+    } catch (error) {
+      finish({
+        error,
+        status: null,
+        stdout: capturedStdout,
+        stderr: capturedStderr
+      });
+      return;
+    }
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      capturedStdout += chunk;
+      if (!quiet) {
+        stdout?.write(chunk);
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      capturedStderr += chunk;
+      if (!quiet) {
+        stderr?.write(chunk);
+      }
+    });
+    child.once("error", (error) => {
+      finish({
+        error,
+        status: null,
+        stdout: capturedStdout,
+        stderr: capturedStderr
+      });
+    });
+    child.once("close", (status, signal) => {
+      finish({
+        error: signal ? new Error(`${command} terminated by signal ${signal}.`) : null,
+        status,
+        stdout: capturedStdout,
+        stderr: capturedStderr
+      });
+    });
+  });
+}
+
 function runExternalShellCommand(
   commandText,
   {
@@ -155,6 +243,32 @@ async function runLocalJskit(
   });
 }
 
+async function runLocalJskitAsync(
+  appRoot,
+  args = [],
+  {
+    stdout,
+    stderr,
+    createCliError,
+    quiet = false
+  } = {}
+) {
+  const localJskitBin = resolveLocalJskitBin(appRoot);
+  if (!(await fileExists(localJskitBin))) {
+    throw createCliError(`Local jskit binary not found at ${path.relative(appRoot, localJskitBin)}. Run npm install first.`, {
+      exitCode: 1
+    });
+  }
+
+  return runExternalCommandAsync(localJskitBin, args, {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet,
+    createCliError
+  });
+}
+
 async function resolveLocalRepoRoot({ appRoot = "", explicitRepoRoot = "" } = {}) {
   const explicit = normalizeText(explicitRepoRoot);
   if (explicit) {
@@ -295,10 +409,12 @@ export {
   normalizeText,
   isTruthyFlag,
   runExternalCommand,
+  runExternalCommandAsync,
   runExternalShellCommand,
   formatUtcReleaseTimestamp,
   resolveLocalJskitBin,
   runLocalJskit,
+  runLocalJskitAsync,
   resolveLocalRepoRoot,
   discoverLocalPackageMap,
   linkPackageBinEntries,

package/src/server/commandHandlers/appCommands/updatePackages.js

@@ -1,20 +1,65 @@
-import { runLocalJskit, runExternalCommand } from "./shared.js";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  runExternalCommandAsync,
+  runLocalJskitAsync
+} from "./shared.js";
+
+const DEPENDENCY_SECTIONS = Object.freeze([
+  Object.freeze({
+    installArgs: Object.freeze(["--save-exact"]),
+    label: "runtime",
+    name: "dependencies"
+  }),
+  Object.freeze({
+    installArgs: Object.freeze(["--save-dev", "--save-exact"]),
+    label: "development",
+    name: "devDependencies"
+  }),
+  Object.freeze({
+    installArgs: Object.freeze(["--save-optional", "--save-exact"]),
+    label: "optional",
+    name: "optionalDependencies"
+  }),
+  Object.freeze({
+    installArgs: Object.freeze(["--save-peer", "--save-exact"]),
+    label: "peer",
+    name: "peerDependencies"
+  })
+]);
+const JSKIT_PACKAGE_PATTERN = /^@jskit-ai\/[a-z0-9._-]+$/iu;
+const PROGRESS_INTERVAL_MS = 5_000;
 
 function collectJskitPackageNames(packageMap = {}) {
   return Object.keys(packageMap && typeof packageMap === "object" ? packageMap : {})
-    .filter((name) => String(name || "").startsWith("@jskit-ai/"))
+    .filter((name) => JSKIT_PACKAGE_PATTERN.test(String(name || "")))
     .sort((left, right) => left.localeCompare(right));
 }
 
-function resolveMajorRangeFromVersion(packageName = "", rawVersion = "", createCliError) {
+function collectManifestJskitPackageNames(packageJson = {}) {
+  const packageNames = new Set();
+  for (const section of DEPENDENCY_SECTIONS) {
+    for (const packageName of collectJskitPackageNames(packageJson?.[section.name])) {
+      packageNames.add(packageName);
+    }
+  }
+  return [...packageNames].sort((left, right) => left.localeCompare(right));
+}
+
+function resolveExactVersion(packageName = "", rawVersion = "", createCliError) {
   const normalizedVersion = String(rawVersion || "").trim();
-  const match = normalizedVersion.match(/^(\d+)\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?$/u);
-  if (!match) {
+  if (!/^\d+\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?$/u.test(normalizedVersion)) {
     throw createCliError(`Invalid latest version for ${packageName}: ${normalizedVersion || "<empty>"}.`, {
       exitCode: 1
     });
   }
-  return `${match[1]}.x`;
+  return normalizedVersion;
+}
+
+function resolveMajorRange(packageName = "", version = "", createCliError) {
+  const exactVersion = resolveExactVersion(packageName, version, createCliError);
+  return `${exactVersion.slice(0, exactVersion.indexOf("."))}.x`;
 }
 
 function resolveRegistryArgs(registryUrl = "") {
@@ -25,8 +70,359 @@ function resolveRegistryArgs(registryUrl = "") {
   return ["--registry", normalizedRegistryUrl];
 }
 
-function resolveInstallSpecs(packageNames = [], resolveMajorRange) {
-  return packageNames.map((packageName) => `${packageName}@${resolveMajorRange(packageName)}`);
+function resolveInstallSpecs(packageNames = [], latestVersions = new Map()) {
+  return packageNames.map((packageName) => `${packageName}@${latestVersions.get(packageName)}`);
+}
+
+function formatElapsedTime(elapsedMilliseconds = 0) {
+  const elapsedSeconds = Math.max(0, Math.floor(Number(elapsedMilliseconds) / 1000));
+  if (elapsedSeconds < 1) {
+    return "under 1s";
+  }
+  if (elapsedSeconds < 60) {
+    return `${elapsedSeconds}s`;
+  }
+
+  const minutes = Math.floor(elapsedSeconds / 60);
+  const seconds = elapsedSeconds % 60;
+  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+}
+
+async function runWithProgress(task, {
+  activity,
+  progressIntervalMs = PROGRESS_INTERVAL_MS,
+  stdout,
+  step
+} = {}) {
+  const normalizedActivity = String(activity || "running update").trim();
+  const normalizedStep = String(step || "Update").trim();
+  const startedAt = Date.now();
+  stdout?.write(`[jskit:update] ${normalizedStep}: ${normalizedActivity}.\n`);
+
+  const progressTimer = setInterval(() => {
+    stdout?.write(
+      `[jskit:update] ${normalizedStep} is still running (${formatElapsedTime(Date.now() - startedAt)} elapsed): ${normalizedActivity}.\n`
+    );
+  }, progressIntervalMs);
+  progressTimer.unref();
+
+  try {
+    const result = await task();
+    stdout?.write(
+      `[jskit:update] ${normalizedStep} complete in ${formatElapsedTime(Date.now() - startedAt)}.\n`
+    );
+    return result;
+  } finally {
+    clearInterval(progressTimer);
+  }
+}
+
+function hasNpmWorkspaces(packageJson = {}) {
+  const workspaces = Array.isArray(packageJson?.workspaces)
+    ? packageJson.workspaces
+    : packageJson?.workspaces?.packages;
+  return Array.isArray(workspaces) && workspaces.some((workspace) => String(workspace || "").trim());
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+async function readOptionalFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+async function resolveWorkspaceDirectories({
+  appRoot,
+  createCliError,
+  packageJson,
+  stderr,
+  stdout
+}) {
+  if (!hasNpmWorkspaces(packageJson)) {
+    return [];
+  }
+
+  const result = await runExternalCommandAsync("npm", ["query", ".workspace", "--json"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet: true,
+    createCliError
+  });
+
+  let entries;
+  try {
+    entries = JSON.parse(String(result.stdout || "[]"));
+  } catch (error) {
+    throw createCliError(`npm returned invalid workspace metadata: ${error instanceof Error ? error.message : String(error)}.`, {
+      exitCode: 1
+    });
+  }
+  if (!Array.isArray(entries)) {
+    throw createCliError("npm returned invalid workspace metadata: expected a JSON array.", {
+      exitCode: 1
+    });
+  }
+
+  const normalizedAppRoot = path.resolve(appRoot);
+  const workspaceDirectories = new Set();
+  for (const entry of entries) {
+    const location = String(entry?.location || "").trim();
+    if (!location) {
+      continue;
+    }
+    const workspaceDirectory = path.resolve(normalizedAppRoot, location);
+    if (
+      workspaceDirectory === normalizedAppRoot ||
+      !workspaceDirectory.startsWith(`${normalizedAppRoot}${path.sep}`)
+    ) {
+      throw createCliError(`npm returned a workspace outside the app root: ${location}.`, {
+        exitCode: 1
+      });
+    }
+    workspaceDirectories.add(workspaceDirectory);
+  }
+
+  return [...workspaceDirectories].sort((left, right) => left.localeCompare(right));
+}
+
+function descriptorJskitPackageNames(source = "") {
+  const packageNames = new Set();
+  const patterns = [
+    /(["'])(@jskit-ai\/[a-z0-9._-]+)\1\s*:\s*(["'])[^"']+\3/giu,
+    /(["'])(@jskit-ai\/[a-z0-9._-]+)\1\s*:\s*\{[^{}]*?(?:["'](?:version|value)["']|version|value)\s*:\s*(["'])[^"']+\3/giu
+  ];
+  for (const pattern of patterns) {
+    for (const match of String(source || "").matchAll(pattern)) {
+      packageNames.add(match[2]);
+    }
+  }
+  return [...packageNames].sort((left, right) => left.localeCompare(right));
+}
+
+async function loadWorkspacePackages(workspaceDirectories = []) {
+  const workspacePackages = [];
+  for (const directory of workspaceDirectories) {
+    const packageJsonPath = path.join(directory, "package.json");
+    const descriptorPath = path.join(directory, "package.descriptor.mjs");
+    workspacePackages.push({
+      descriptorPath,
+      descriptorSource: await readOptionalFile(descriptorPath),
+      directory,
+      packageJson: await readJson(packageJsonPath),
+      packageJsonPath
+    });
+  }
+  return workspacePackages;
+}
+
+async function resolveLatestVersions(packageNames = [], latestVersions = new Map(), {
+  appRoot,
+  createCliError,
+  registryArgs,
+  stderr,
+  stdout
+}) {
+  const unresolvedPackageNames = packageNames
+    .filter((packageName) => !latestVersions.has(packageName))
+    .sort((left, right) => left.localeCompare(right));
+
+  for (const [index, packageName] of unresolvedPackageNames.entries()) {
+    stdout?.write(
+      `[jskit:update] resolving latest package ${index + 1}/${unresolvedPackageNames.length}: ${packageName}.\n`
+    );
+    const result = await runExternalCommandAsync(
+      "npm",
+      ["view", ...registryArgs, packageName, "version"],
+      {
+        cwd: appRoot,
+        stdout,
+        stderr,
+        quiet: true,
+        createCliError
+      }
+    );
+    const version = resolveExactVersion(packageName, result.stdout, createCliError);
+    latestVersions.set(packageName, version);
+    stdout?.write(`[jskit:update] resolved ${packageName}@${version}.\n`);
+  }
+
+  return latestVersions;
+}
+
+function updateWorkspaceManifest(packageJson = {}, latestVersions = new Map(), createCliError) {
+  const updates = [];
+  for (const section of DEPENDENCY_SECTIONS) {
+    const packageMap = packageJson?.[section.name];
+    for (const packageName of collectJskitPackageNames(packageMap)) {
+      const targetRange = resolveMajorRange(packageName, latestVersions.get(packageName), createCliError);
+      if (packageMap[packageName] === targetRange) {
+        continue;
+      }
+      packageMap[packageName] = targetRange;
+      updates.push(`${packageName}@${targetRange}`);
+    }
+  }
+  return updates;
+}
+
+function updateWorkspaceDescriptor(source = "", latestVersions = new Map(), createCliError) {
+  const updates = [];
+  const replaceVersion = (match, keyQuote, packageName, separator, valueQuote, currentVersion) => {
+    const targetRange = resolveMajorRange(packageName, latestVersions.get(packageName), createCliError);
+    if (currentVersion === targetRange) {
+      return match;
+    }
+    updates.push(`${packageName}@${targetRange}`);
+    return `${keyQuote}${packageName}${keyQuote}${separator}${valueQuote}${targetRange}${valueQuote}`;
+  };
+  let nextSource = String(source || "").replace(
+    /(["'])(@jskit-ai\/[a-z0-9._-]+)\1(\s*:\s*)(["'])([^"']+)\4/giu,
+    replaceVersion
+  );
+  nextSource = nextSource.replace(
+    /(["'])(@jskit-ai\/[a-z0-9._-]+)\1(\s*:\s*\{[^{}]*?(?:["'](?:version|value)["']|version|value)\s*:\s*)(["'])([^"']+)\4/giu,
+    replaceVersion
+  );
+  return {
+    nextSource,
+    updates
+  };
+}
+
+async function synchronizeWorkspacePackageSpecs({
+  appRoot,
+  createCliError,
+  dryRun,
+  latestVersions,
+  packageJson,
+  registryArgs,
+  stderr,
+  stdout
+}) {
+  const workspaceDirectories = await resolveWorkspaceDirectories({
+    appRoot,
+    createCliError,
+    packageJson,
+    stderr,
+    stdout
+  });
+  const workspacePackages = await loadWorkspacePackages(workspaceDirectories);
+  const workspaceJskitPackages = new Set();
+  for (const workspacePackage of workspacePackages) {
+    for (const packageName of collectManifestJskitPackageNames(workspacePackage.packageJson)) {
+      workspaceJskitPackages.add(packageName);
+    }
+    for (const packageName of descriptorJskitPackageNames(workspacePackage.descriptorSource)) {
+      workspaceJskitPackages.add(packageName);
+    }
+  }
+
+  const packageNames = [...workspaceJskitPackages].sort((left, right) => left.localeCompare(right));
+  await resolveLatestVersions(packageNames, latestVersions, {
+    appRoot,
+    createCliError,
+    registryArgs,
+    stderr,
+    stdout
+  });
+
+  const changedFiles = [];
+  for (const workspacePackage of workspacePackages) {
+    const manifestUpdates = updateWorkspaceManifest(
+      workspacePackage.packageJson,
+      latestVersions,
+      createCliError
+    );
+    if (manifestUpdates.length > 0) {
+      const relativePath = path.relative(appRoot, workspacePackage.packageJsonPath).replaceAll(path.sep, "/");
+      changedFiles.push(relativePath);
+      stdout?.write(`[jskit:update] workspace manifest ${relativePath} -> ${manifestUpdates.join(", ")}\n`);
+      if (!dryRun) {
+        await writeFile(
+          workspacePackage.packageJsonPath,
+          `${JSON.stringify(workspacePackage.packageJson, null, 2)}\n`,
+          "utf8"
+        );
+      }
+    }
+
+    if (!workspacePackage.descriptorSource) {
+      continue;
+    }
+    const descriptorResult = updateWorkspaceDescriptor(
+      workspacePackage.descriptorSource,
+      latestVersions,
+      createCliError
+    );
+    if (descriptorResult.updates.length < 1) {
+      continue;
+    }
+    const relativePath = path.relative(appRoot, workspacePackage.descriptorPath).replaceAll(path.sep, "/");
+    changedFiles.push(relativePath);
+    stdout?.write(`[jskit:update] workspace descriptor ${relativePath} -> ${descriptorResult.updates.join(", ")}\n`);
+    if (!dryRun) {
+      await writeFile(workspacePackage.descriptorPath, descriptorResult.nextSource, "utf8");
+    }
+  }
+
+  return {
+    changedFiles,
+    packageNames
+  };
+}
+
+async function updateRootPackages({
+  appRoot,
+  createCliError,
+  dryRun,
+  latestVersions,
+  packageJson,
+  registryArgs,
+  stderr,
+  stdout
+}) {
+  const rootPackageNames = collectManifestJskitPackageNames(packageJson);
+  if (rootPackageNames.length < 1) {
+    stdout?.write("[jskit:update] no root @jskit-ai packages found.\n");
+    return false;
+  }
+
+  await resolveLatestVersions(rootPackageNames, latestVersions, {
+    appRoot,
+    createCliError,
+    registryArgs,
+    stderr,
+    stdout
+  });
+  const dryRunArgs = dryRun ? ["--dry-run"] : [];
+  for (const section of DEPENDENCY_SECTIONS) {
+    const packageNames = collectJskitPackageNames(packageJson?.[section.name]);
+    if (packageNames.length < 1) {
+      continue;
+    }
+    const installSpecs = resolveInstallSpecs(packageNames, latestVersions);
+    stdout?.write(`[jskit:update] updating ${section.label} packages: ${installSpecs.join(" ")}\n`);
+    await runExternalCommandAsync(
+      "npm",
+      ["install", ...section.installArgs, ...registryArgs, ...dryRunArgs, ...installSpecs],
+      {
+        cwd: appRoot,
+        stdout,
+        stderr,
+        createCliError
+      }
+    );
+  }
+  return true;
 }
 
 async function runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
@@ -38,73 +434,111 @@ async function runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {
 
   await assertAppManagedCiWorkflowUnmodified({ appRoot });
   const { packageJson } = await loadAppPackageJson(appRoot);
-  const runtimePackages = collectJskitPackageNames(packageJson?.dependencies);
-  const devPackages = collectJskitPackageNames(packageJson?.devDependencies);
   const registryUrl = String(options?.inlineOptions?.registry || "").trim();
   const registryArgs = resolveRegistryArgs(registryUrl);
   const dryRun = options?.dryRun === true;
-
-  if (runtimePackages.length < 1 && devPackages.length < 1) {
-    stdout.write("[jskit:update] no @jskit-ai packages found in dependencies.\n");
-    return 0;
-  }
-
-  const resolveMajorRange = (packageName) => {
-    const result = runExternalCommand("npm", ["view", ...registryArgs, packageName, "version"], {
-      cwd: appRoot,
-      stdout,
-      stderr,
-      quiet: true,
-      createCliError
-    });
-    return resolveMajorRangeFromVersion(packageName, result.stdout, createCliError);
-  };
-
-  const runtimeSpecs = resolveInstallSpecs(runtimePackages, resolveMajorRange);
-  const devSpecs = resolveInstallSpecs(devPackages, resolveMajorRange);
-  const dryRunArgs = dryRun ? ["--dry-run"] : [];
+  const latestVersions = new Map();
 
   if (dryRun) {
-    stdout.write("[jskit:update] dry-run mode enabled.\n");
+    stdout?.write("[jskit:update] dry-run mode enabled.\n");
   }
 
-  if (runtimeSpecs.length > 0) {
-    stdout.write(`[jskit:update] updating runtime packages: ${runtimeSpecs.join(" ")}\n`);
-    runExternalCommand("npm", ["install", "--save-exact", ...registryArgs, ...dryRunArgs, ...runtimeSpecs], {
-      cwd: appRoot,
+  await runWithProgress(
+    async () => {
+      const updatedRootPackages = await updateRootPackages({
+        appRoot,
+        createCliError,
+        dryRun,
+        latestVersions,
+        packageJson,
+        registryArgs,
+        stderr,
+        stdout
+      });
+      if (!updatedRootPackages || dryRun) {
+        return;
+      }
+      stdout?.write("[jskit:update] generating managed migrations for changed packages.\n");
+      await runLocalJskitAsync(appRoot, ["migrations", "changed"], {
+        stdout,
+        stderr,
+        createCliError
+      });
+      stdout?.write("[jskit:update] synchronizing the managed CI workflow.\n");
+      await runLocalJskitAsync(appRoot, ["app", "sync-ci"], {
+        stdout,
+        stderr,
+        createCliError
+      });
+    },
+    {
+      activity: dryRun
+        ? "checking root JSKIT package updates"
+        : "updating root JSKIT packages and managed artifacts",
       stdout,
-      stderr,
-      createCliError
-    });
-  }
+      step: "Step 1/3"
+    }
+  );
 
-  if (devSpecs.length > 0) {
-    stdout.write(`[jskit:update] updating dev packages: ${devSpecs.join(" ")}\n`);
-    runExternalCommand("npm", ["install", "--save-dev", "--save-exact", ...registryArgs, ...dryRunArgs, ...devSpecs], {
-      cwd: appRoot,
+  let workspaceResult = {
+    changedFiles: [],
+    packageNames: []
+  };
+  await runWithProgress(
+    async () => {
+      workspaceResult = await synchronizeWorkspacePackageSpecs({
+        appRoot,
+        createCliError,
+        dryRun,
+        latestVersions,
+        packageJson,
+        registryArgs,
+        stderr,
+        stdout
+      });
+    },
+    {
+      activity: "aligning JSKIT ranges in workspace manifests and descriptors",
       stdout,
-      stderr,
-      createCliError
-    });
-  }
+      step: "Step 2/3"
+    }
+  );
+  stdout?.write(
+    `[jskit:update] Step 2/3 summary: ${workspaceResult.changedFiles.length} workspace files ${dryRun ? "would change" : "changed"}.\n`
+  );
 
-  if (!dryRun) {
-    stdout.write("[jskit:update] generating managed migrations for changed packages.\n");
-    await runLocalJskit(appRoot, ["migrations", "changed"], {
-      stdout,
-      stderr,
-      createCliError
-    });
-    stdout.write("[jskit:update] synchronizing the managed CI workflow.\n");
-    await runLocalJskit(appRoot, ["app", "sync-ci"], {
-      stdout,
-      stderr,
-      createCliError
-    });
+  if (dryRun) {
+    stdout?.write(
+      `[jskit:update] Step 3/3 skipped in dry-run mode: ${workspaceResult.packageNames.length} workspace JSKIT packages would be refreshed.\n`
+    );
+  } else if (workspaceResult.packageNames.length > 0) {
+    await runWithProgress(
+      () => runExternalCommandAsync(
+        "npm",
+        ["update", ...registryArgs, "--workspaces", ...workspaceResult.packageNames],
+        {
+          cwd: appRoot,
+          stdout,
+          stderr,
+          createCliError
+        }
+      ),
+      {
+        activity: `refreshing ${workspaceResult.packageNames.length} workspace JSKIT packages and updating the lockfile`,
+        stdout,
+        step: "Step 3/3"
+      }
+    );
+  } else {
+    stdout?.write("[jskit:update] Step 3/3 skipped: no workspace JSKIT packages were found.\n");
   }
 
-  stdout.write("[jskit:update] done.\n");
+  stdout?.write("[jskit:update] done.\n");
   return 0;
 }
 
-export { runAppUpdatePackagesCommand };
+export {
+  formatElapsedTime,
+  runAppUpdatePackagesCommand,
+  runWithProgress
+};