@jskit-ai/jskit-cli 0.2.27 → 0.2.28

package/src/server/commandHandlers/packageCommands/add.js

@@ -0,0 +1,282 @@
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../../shared/collectionUtils.js";
+
+async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io }) {
+  const {
+    createCliError,
+    normalizeRelativePath,
+    resolveAppRootFromCwd,
+    loadPackageRegistry,
+    loadAppLocalPackageRegistry,
+    loadBundleRegistry,
+    mergePackageRegistries,
+    loadAppPackageJson,
+    loadLockFile,
+    resolvePackageIdFromRegistryOrNodeModules,
+    hydratePackageRegistryFromInstalledNodeModules,
+    resolvePackageKind,
+    validateInlineOptionsForPackage,
+    resolveLocalDependencyOrder,
+    validatePlannedCapabilityClosure,
+    validateInlineOptionsForBundle,
+    resolveBundleInlineOptionsForPackage,
+    resolvePackageOptions,
+    applyPackageInstall,
+    adoptAppLocalPackageDependencies,
+    writeJsonFile,
+    runNpmInstall,
+    renderResolvedSummary
+  } = ctx;
+
+  const invocationMode = options?.commandMode === "generate" ? "generate" : "add";
+  const targetType = String(positional[0] || "").trim();
+  const targetId = String(positional[1] || "").trim();
+
+  if (!targetType || !targetId) {
+    if (invocationMode === "generate") {
+      throw createCliError("generate requires a package id (generate <packageId>).", {
+        showUsage: true
+      });
+    }
+    throw createCliError("add requires target type and id (add bundle <id> | add package <id>).", {
+      showUsage: true
+    });
+  }
+  if (targetType !== "bundle" && targetType !== "package") {
+    throw createCliError(`Unsupported add target type: ${targetType}`, { showUsage: true });
+  }
+  if (invocationMode === "generate" && targetType !== "package") {
+    throw createCliError("generate requires a package id (generate <packageId>).", {
+      showUsage: true
+    });
+  }
+
+  const appRoot = await resolveAppRootFromCwd(cwd);
+  const packageRegistry = await loadPackageRegistry();
+  const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+  const bundleRegistry = await loadBundleRegistry();
+  const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
+  const { packageJsonPath, packageJson } = await loadAppPackageJson(appRoot);
+  const { lockPath, lock } = await loadLockFile(appRoot);
+  const resolvedTargetPackageId = targetType === "package"
+    ? await resolvePackageIdFromRegistryOrNodeModules({
+        appRoot,
+        packageRegistry: combinedPackageRegistry,
+        packageIdInput: targetId
+      })
+    : "";
+
+  const targetPackageIds = targetType === "bundle"
+    ? ensureArray(bundleRegistry.get(targetId)?.packages).map((value) => String(value))
+    : [resolvedTargetPackageId];
+  if (targetType === "bundle" && targetPackageIds.length === 0) {
+    throw createCliError(`Unknown bundle: ${targetId}`);
+  }
+  if (targetType === "package" && !resolvedTargetPackageId) {
+    throw createCliError(
+      `Unknown package: ${targetId}. Install an external module first (npm install ${targetId}) if you want to adopt it into lock.`
+    );
+  }
+
+  await hydratePackageRegistryFromInstalledNodeModules({
+    appRoot,
+    packageRegistry: combinedPackageRegistry,
+    seedPackageIds: targetPackageIds
+  });
+
+  if (targetType === "package") {
+    const targetPackageEntry = combinedPackageRegistry.get(resolvedTargetPackageId);
+    if (!targetPackageEntry) {
+      throw createCliError(`Unknown package: ${targetId}`);
+    }
+    const packageKind = resolvePackageKind(targetPackageEntry);
+    if (invocationMode === "add" && packageKind === "generator") {
+      throw createCliError(
+        `Package ${resolvedTargetPackageId} is a generator. Use: jskit generate ${resolvedTargetPackageId}`
+      );
+    }
+    if (invocationMode === "generate" && packageKind !== "generator") {
+      throw createCliError(
+        `Package ${resolvedTargetPackageId} is a runtime package. Use: jskit add package ${resolvedTargetPackageId}`
+      );
+    }
+    validateInlineOptionsForPackage(targetPackageEntry, options.inlineOptions);
+  }
+
+  const { ordered: resolvedPackageIds, externalDependencies } = resolveLocalDependencyOrder(
+    targetPackageIds,
+    combinedPackageRegistry
+  );
+  if (invocationMode === "add" && targetType === "bundle") {
+    const bundledGenerators = resolvedPackageIds.filter((packageId) => {
+      const packageEntry = combinedPackageRegistry.get(packageId);
+      return resolvePackageKind(packageEntry) === "generator";
+    });
+    if (bundledGenerators.length > 0) {
+      throw createCliError(
+        `Bundle ${targetId} includes generator package(s): ${bundledGenerators.join(", ")}. Use: jskit generate <packageId>`
+      );
+    }
+  }
+  const plannedInstalledPackageIds = sortStrings([
+    ...new Set([
+      ...Object.keys(ensureObject(lock.installedPackages)).map((value) => String(value || "").trim()).filter(Boolean),
+      ...resolvedPackageIds
+    ])
+  ]);
+  validatePlannedCapabilityClosure(
+    plannedInstalledPackageIds,
+    combinedPackageRegistry,
+    `${invocationMode} ${targetType} ${targetId}`
+  );
+
+  if (targetType === "bundle") {
+    validateInlineOptionsForBundle({
+      bundleId: targetId,
+      inlineOptions: options.inlineOptions,
+      packageIds: resolvedPackageIds,
+      packageRegistry: combinedPackageRegistry
+    });
+  }
+
+  const packagesToInstall = [];
+  const resolvedOptionsByPackage = {};
+  const forceReapplyTarget = options?.forceReapplyTarget === true;
+  const hasInlineOptions = Object.keys(ensureObject(options.inlineOptions)).length > 0;
+  for (const packageId of resolvedPackageIds) {
+    const packageEntry = combinedPackageRegistry.get(packageId);
+    const existingInstall = ensureObject(lock.installedPackages[packageId]);
+    const existingVersion = String(existingInstall.version || "").trim();
+    const isDirectTargetPackage = targetType === "package" && packageId === resolvedTargetPackageId;
+    const packageInlineOptions = targetType === "bundle"
+      ? resolveBundleInlineOptionsForPackage(packageEntry, options.inlineOptions)
+      : isDirectTargetPackage
+        ? ensureObject(options.inlineOptions)
+        : {};
+    const hasPackageInlineOptions = Object.keys(packageInlineOptions).length > 0;
+    const shouldReapplyInstalledPackage =
+      (isDirectTargetPackage && (forceReapplyTarget || hasInlineOptions)) ||
+      (targetType === "bundle" && hasPackageInlineOptions);
+    const shouldSkipGenerateDependencyReinstall =
+      invocationMode === "generate" &&
+      !isDirectTargetPackage &&
+      Boolean(existingVersion);
+    if (shouldSkipGenerateDependencyReinstall && !shouldReapplyInstalledPackage) {
+      continue;
+    }
+    if (existingVersion && existingVersion === packageEntry.version && !shouldReapplyInstalledPackage) {
+      continue;
+    }
+    packagesToInstall.push(packageId);
+    const lockEntryOptions = ensureObject(existingInstall.options);
+    resolvedOptionsByPackage[packageId] = await resolvePackageOptions(
+      packageEntry,
+      {
+        ...lockEntryOptions,
+        ...packageInlineOptions
+      },
+      io,
+      { appRoot }
+    );
+  }
+
+  const touchedFiles = new Set();
+  const installedPackageRecords = [];
+
+  for (const packageId of packagesToInstall) {
+    const packageEntry = combinedPackageRegistry.get(packageId);
+    const managedRecord = await applyPackageInstall({
+      packageEntry,
+      packageOptions: resolvedOptionsByPackage[packageId],
+      appRoot,
+      appPackageJson: packageJson,
+      lock,
+      packageRegistry: combinedPackageRegistry,
+      touchedFiles
+    });
+    installedPackageRecords.push(managedRecord);
+  }
+
+  const {
+    appLocalRegistry: refreshedAppLocalRegistry,
+    adoptedPackageIds
+  } = await adoptAppLocalPackageDependencies({
+    appRoot,
+    appPackageJson: packageJson,
+    lock
+  });
+  for (const [packageId, packageEntry] of refreshedAppLocalRegistry.entries()) {
+    combinedPackageRegistry.set(packageId, packageEntry);
+  }
+  if (adoptedPackageIds.length > 0) {
+    const postInstallPackageIds = sortStrings(Object.keys(ensureObject(lock.installedPackages)));
+    validatePlannedCapabilityClosure(
+      postInstallPackageIds,
+      combinedPackageRegistry,
+      `${invocationMode} ${targetType} ${targetId}`
+    );
+  }
+
+  const finalResolvedPackageIds = sortStrings([...resolvedPackageIds, ...adoptedPackageIds]);
+
+  const touchedFileList = sortStrings([...touchedFiles]);
+  const successLabel = invocationMode === "generate"
+    ? "Generated with"
+    : targetType === "bundle"
+      ? "Added bundle"
+      : "Added package";
+  const installWarnings = installedPackageRecords
+    .flatMap((record) => ensureArray(ensureObject(record).warnings))
+    .map((value) => String(value || "").trim())
+    .filter(Boolean);
+
+  if (!options.dryRun) {
+    await writeJsonFile(packageJsonPath, packageJson);
+    await writeJsonFile(lockPath, lock);
+    if (options.runNpmInstall) {
+      await runNpmInstall(appRoot, io.stderr);
+    }
+  }
+
+  if (options.json) {
+    io.stdout.write(`${JSON.stringify({
+      targetType: invocationMode === "generate" ? "generator" : targetType,
+      targetId,
+      resolvedPackages: finalResolvedPackageIds,
+      touchedFiles: touchedFileList,
+      lockPath: normalizeRelativePath(appRoot, lockPath),
+      externalDependencies,
+      dryRun: options.dryRun,
+      installed: installedPackageRecords,
+      warnings: installWarnings
+    }, null, 2)}\n`);
+  } else {
+    io.stdout.write(
+      `${renderResolvedSummary(
+        `${successLabel}`,
+        targetId,
+        finalResolvedPackageIds,
+        touchedFileList,
+        appRoot,
+        lockPath,
+        externalDependencies
+      )}\n`
+    );
+    if (installWarnings.length > 0) {
+      io.stdout.write(`Warnings (${installWarnings.length}):\n`);
+      for (const warning of installWarnings) {
+        io.stdout.write(`- ${warning}\n`);
+      }
+    }
+    if (options.dryRun) {
+      io.stdout.write("Dry run enabled: no files were written.\n");
+    }
+  }
+
+  return 0;
+}
+
+export { runPackageAddCommand };

package/src/server/commandHandlers/packageCommands/create.js

@@ -0,0 +1,155 @@
+import {
+  ensureObject,
+  sortStrings
+} from "../../shared/collectionUtils.js";
+
+async function runPackageCreateCommand(ctx = {}, { positional, options, cwd, io }) {
+  const {
+    createCliError,
+    normalizeRelativePath,
+    normalizeRelativePosixPath,
+    resolveAppRootFromCwd,
+    loadAppPackageJson,
+    loadLockFile,
+    resolveLocalPackageId,
+    createLocalPackageScaffoldFiles,
+    path,
+    toFileDependencySpecifier,
+    fileExists,
+    mkdir,
+    writeFile,
+    applyPackageJsonField,
+    writeJsonFile,
+    runNpmInstall
+  } = ctx;
+
+  const targetType = String(positional[0] || "").trim();
+  const rawName = String(positional[1] || "").trim();
+  if (targetType !== "package" || !rawName) {
+    throw createCliError("create requires: create package <name>", { showUsage: true });
+  }
+
+  const appRoot = await resolveAppRootFromCwd(cwd);
+  const { packageJsonPath, packageJson } = await loadAppPackageJson(appRoot);
+  const { lockPath, lock } = await loadLockFile(appRoot);
+  const installedPackages = ensureObject(lock.installedPackages);
+  const dependencies = ensureObject(packageJson.dependencies);
+  const devDependencies = ensureObject(packageJson.devDependencies);
+
+  const { packageId, packageDirName } = resolveLocalPackageId({
+    rawName,
+    appPackageName: packageJson.name,
+    inlineOptions: options.inlineOptions
+  });
+  const localPackagesRoot = path.join(appRoot, "packages");
+  const packageRoot = path.join(localPackagesRoot, packageDirName);
+  const packageRelativePath = normalizeRelativePath(appRoot, packageRoot);
+  const descriptorRelativePath = `${normalizeRelativePosixPath(packageRelativePath)}/package.descriptor.mjs`;
+  const localDependencySpecifier = toFileDependencySpecifier(packageRelativePath);
+  const packageDescription = String(options.inlineOptions.description || "").trim() || `App-local package ${packageId}.`;
+
+  if (await fileExists(packageRoot)) {
+    throw createCliError(`Package directory already exists: ${normalizeRelativePath(appRoot, packageRoot)}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(installedPackages, packageId)) {
+    throw createCliError(`Package is already present in lock file: ${packageId}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(dependencies, packageId)) {
+    throw createCliError(`package.json dependencies already contains ${packageId}.`);
+  }
+  if (Object.prototype.hasOwnProperty.call(devDependencies, packageId)) {
+    throw createCliError(`package.json devDependencies already contains ${packageId}.`);
+  }
+
+  const scaffoldFiles = createLocalPackageScaffoldFiles({
+    packageId,
+    packageDescription
+  });
+  const touchedFiles = new Set(["package.json", normalizeRelativePath(appRoot, lockPath)]);
+  for (const scaffoldFile of scaffoldFiles) {
+    touchedFiles.add(
+      `${normalizeRelativePosixPath(packageRelativePath)}/${normalizeRelativePosixPath(scaffoldFile.relativePath)}`
+    );
+  }
+
+  if (!options.dryRun) {
+    for (const scaffoldFile of scaffoldFiles) {
+      const absoluteFilePath = path.join(packageRoot, scaffoldFile.relativePath);
+      await mkdir(path.dirname(absoluteFilePath), { recursive: true });
+      await writeFile(absoluteFilePath, String(scaffoldFile.content || ""), "utf8");
+    }
+  }
+
+  const dependencyApplied = applyPackageJsonField(packageJson, "dependencies", packageId, localDependencySpecifier);
+  const managedRecord = {
+    packageId,
+    version: "0.1.0",
+    source: {
+      type: "local-package",
+      packagePath: normalizeRelativePosixPath(packageRelativePath),
+      descriptorPath: descriptorRelativePath
+    },
+    managed: {
+      packageJson: {
+        dependencies: {},
+        devDependencies: {},
+        scripts: {}
+      },
+      text: {},
+      vite: {},
+      files: [],
+      migrations: []
+    },
+    options: {},
+    installedAt: new Date().toISOString()
+  };
+  if (dependencyApplied.changed) {
+    managedRecord.managed.packageJson.dependencies[packageId] = dependencyApplied.managed;
+  }
+  lock.installedPackages[packageId] = managedRecord;
+
+  const touchedFileList = sortStrings([...touchedFiles]);
+  if (!options.dryRun) {
+    await writeJsonFile(packageJsonPath, packageJson);
+    await writeJsonFile(lockPath, lock);
+    if (options.runNpmInstall) {
+      await runNpmInstall(appRoot, io.stderr);
+    }
+  }
+
+  if (options.json) {
+    io.stdout.write(
+      `${JSON.stringify(
+        {
+          targetType: "package",
+          packageId,
+          packageDirectory: normalizeRelativePosixPath(packageRelativePath),
+          descriptorPath: descriptorRelativePath,
+          dependency: localDependencySpecifier,
+          touchedFiles: touchedFileList,
+          lockPath: normalizeRelativePath(appRoot, lockPath),
+          dryRun: options.dryRun
+        },
+        null,
+        2
+      )}\n`
+    );
+  } else {
+    io.stdout.write(`Created local package ${packageId}.\n`);
+    io.stdout.write(`Directory: ${normalizeRelativePosixPath(packageRelativePath)}\n`);
+    io.stdout.write(`Dependency: ${packageId} -> ${localDependencySpecifier}\n`);
+    io.stdout.write(`Descriptor: ${descriptorRelativePath}\n`);
+    io.stdout.write(`Touched files (${touchedFileList.length}):\n`);
+    for (const touchedFile of touchedFileList) {
+      io.stdout.write(`- ${touchedFile}\n`);
+    }
+    io.stdout.write(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}\n`);
+    if (options.dryRun) {
+      io.stdout.write("Dry run enabled: no files were written.\n");
+    }
+  }
+
+  return 0;
+}
+
+export { runPackageCreateCommand };

package/src/server/commandHandlers/packageCommands/generate.js

@@ -0,0 +1,116 @@
+async function runPackageGenerateCommand(
+  ctx = {},
+  { positional, options, cwd, io },
+  { runCommandAdd }
+) {
+  const {
+    createCliError,
+    resolveAppRootFromCwd,
+    loadPackageRegistry,
+    loadAppLocalPackageRegistry,
+    mergePackageRegistries,
+    resolvePackageIdFromRegistryOrNodeModules,
+    hydratePackageRegistryFromInstalledNodeModules,
+    resolvePackageKind,
+    resolveGeneratorPrimarySubcommand,
+    hasGeneratorSubcommandDefinition,
+    runGeneratorSubcommand
+  } = ctx;
+
+  const firstToken = String(positional[0] || "").trim();
+  const secondToken = String(positional[1] || "").trim();
+  const thirdToken = String(positional[2] || "").trim();
+  if (firstToken === "bundle") {
+    throw createCliError("generate supports packages only (generate <packageId>).", {
+      showUsage: true
+    });
+  }
+  const targetId = firstToken === "package" ? secondToken : firstToken;
+  const subcommandName = firstToken === "package" ? thirdToken : secondToken;
+  const subcommandArgs = firstToken === "package" ? positional.slice(3) : positional.slice(2);
+  if (!targetId) {
+    throw createCliError("generate requires a package id (generate <packageId>).", {
+      showUsage: true
+    });
+  }
+
+  if (subcommandName) {
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const packageRegistry = await loadPackageRegistry();
+    const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+    const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
+
+    const resolvedPackageId = await resolvePackageIdFromRegistryOrNodeModules({
+      appRoot,
+      packageRegistry: combinedPackageRegistry,
+      packageIdInput: targetId
+    });
+    if (!resolvedPackageId) {
+      throw createCliError(
+        `Unknown package: ${targetId}. Install it first (npm install ${targetId}) if you want to run generator subcommands from node_modules.`
+      );
+    }
+
+    await hydratePackageRegistryFromInstalledNodeModules({
+      appRoot,
+      packageRegistry: combinedPackageRegistry,
+      seedPackageIds: [resolvedPackageId]
+    });
+    const packageEntry = combinedPackageRegistry.get(resolvedPackageId);
+    if (!packageEntry) {
+      throw createCliError(`Unknown package: ${targetId}`);
+    }
+
+    if (resolvePackageKind(packageEntry) !== "generator") {
+      throw createCliError(
+        `Package ${resolvedPackageId} is a runtime package. Use: jskit add package ${resolvedPackageId}`
+      );
+    }
+
+    const normalizedSubcommandName = String(subcommandName || "").trim().toLowerCase();
+    const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
+    if (
+      normalizedSubcommandName &&
+      normalizedSubcommandName === primarySubcommand &&
+      !hasGeneratorSubcommandDefinition(packageEntry, normalizedSubcommandName)
+    ) {
+      if (subcommandArgs.length > 0) {
+        throw createCliError(
+          `Generator command "${primarySubcommand}" for ${resolvedPackageId} does not accept positional arguments.`
+        );
+      }
+      return runCommandAdd({
+        positional: ["package", resolvedPackageId],
+        options: {
+          ...options,
+          commandMode: "generate"
+        },
+        cwd,
+        io
+      });
+    }
+
+    return runGeneratorSubcommand({
+      packageEntry,
+      subcommandName,
+      subcommandArgs,
+      inlineOptions: options.inlineOptions,
+      appRoot,
+      io,
+      dryRun: options.dryRun,
+      json: options.json
+    });
+  }
+
+  return runCommandAdd({
+    positional: ["package", targetId],
+    options: {
+      ...options,
+      commandMode: "generate"
+    },
+    cwd,
+    io
+  });
+}
+
+export { runPackageGenerateCommand };

package/src/server/commandHandlers/packageCommands/migrations.js

@@ -0,0 +1,155 @@
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../../shared/collectionUtils.js";
+
+async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd, io }) {
+  const {
+    createCliError,
+    normalizeRelativePath,
+    resolveAppRootFromCwd,
+    loadPackageRegistry,
+    loadAppLocalPackageRegistry,
+    mergePackageRegistries,
+    loadLockFile,
+    hydratePackageRegistryFromInstalledNodeModules,
+    resolveInstalledPackageIdInput,
+    validateInlineOptionsForPackage,
+    resolvePackageOptions,
+    applyPackageMigrationsOnly,
+    writeJsonFile
+  } = ctx;
+
+  const scope = String(positional[0] || "").trim().toLowerCase();
+  const targetId = String(positional[1] || "").trim();
+  if (!scope || (scope !== "all" && scope !== "changed" && scope !== "package")) {
+    throw createCliError("migrations requires: migrations <all|changed|package <packageId>>", {
+      showUsage: true
+    });
+  }
+  if (scope === "package" && !targetId) {
+    throw createCliError("migrations package requires a package id.", {
+      showUsage: true
+    });
+  }
+  if (scope !== "package" && Object.keys(ensureObject(options.inlineOptions)).length > 0) {
+    throw createCliError("Inline options are only supported with: migrations package <packageId>.");
+  }
+
+  const appRoot = await resolveAppRootFromCwd(cwd);
+  const packageRegistry = await loadPackageRegistry();
+  const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+  const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
+  const { lockPath, lock } = await loadLockFile(appRoot);
+  const installedPackages = ensureObject(lock.installedPackages);
+  const installedPackageIds = sortStrings(Object.keys(installedPackages));
+  await hydratePackageRegistryFromInstalledNodeModules({
+    appRoot,
+    packageRegistry: combinedPackageRegistry,
+    seedPackageIds: installedPackageIds
+  });
+
+  let requestedPackageIds = [];
+  if (scope === "all") {
+    requestedPackageIds = installedPackageIds;
+  } else if (scope === "package") {
+    const resolvedTargetId = resolveInstalledPackageIdInput(targetId, installedPackages);
+    if (!resolvedTargetId) {
+      throw createCliError(`Package is not installed: ${targetId}`);
+    }
+    requestedPackageIds = [resolvedTargetId];
+  } else {
+    requestedPackageIds = installedPackageIds.filter((packageId) => {
+      const packageEntry = combinedPackageRegistry.get(packageId);
+      if (!packageEntry) {
+        return true;
+      }
+      const lockEntry = ensureObject(installedPackages[packageId]);
+      const migrationSyncVersion = String(lockEntry.migrationSyncVersion || "").trim();
+      return migrationSyncVersion !== String(packageEntry.version || "").trim();
+    });
+  }
+
+  const touchedFiles = new Set();
+  const migratedRecords = [];
+  const migrationWarnings = [];
+  for (const packageId of requestedPackageIds) {
+    const packageEntry = combinedPackageRegistry.get(packageId);
+    if (!packageEntry) {
+      throw createCliError(
+        `Installed package descriptor not found: ${packageId}. Ensure it is available in catalog, app packages/, or node_modules.`
+      );
+    }
+    validateInlineOptionsForPackage(packageEntry, options.inlineOptions);
+    const installedRecord = ensureObject(installedPackages[packageId]);
+    const mergedInlineOptions = scope === "package" ? ensureObject(options.inlineOptions) : {};
+    const resolvedOptions = await resolvePackageOptions(
+      packageEntry,
+      {
+        ...ensureObject(installedRecord.options),
+        ...mergedInlineOptions
+      },
+      io,
+      { appRoot }
+    );
+
+    const managedRecord = await applyPackageMigrationsOnly({
+      packageEntry,
+      packageOptions: resolvedOptions,
+      appRoot,
+      lock,
+      touchedFiles
+    });
+    migratedRecords.push(managedRecord);
+    for (const warning of ensureArray(ensureObject(managedRecord).warnings)) {
+      const normalizedWarning = String(warning || "").trim();
+      if (!normalizedWarning) {
+        continue;
+      }
+      migrationWarnings.push(normalizedWarning);
+    }
+  }
+
+  const touchedFileList = sortStrings([...touchedFiles]);
+  if (!options.dryRun) {
+    await writeJsonFile(lockPath, lock);
+  }
+
+  if (options.json) {
+    io.stdout.write(`${JSON.stringify({
+      targetType: "migrations",
+      scope,
+      requestedPackages: requestedPackageIds,
+      touchedFiles: touchedFileList,
+      lockPath: normalizeRelativePath(appRoot, lockPath),
+      dryRun: options.dryRun,
+      migrated: migratedRecords,
+      warnings: migrationWarnings
+    }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`Generated migrations (${scope}).\n`);
+    io.stdout.write(`Resolved packages (${requestedPackageIds.length}):\n`);
+    for (const packageId of requestedPackageIds) {
+      io.stdout.write(`- ${packageId}\n`);
+    }
+    io.stdout.write(`Touched files (${touchedFileList.length}):\n`);
+    for (const touchedFile of touchedFileList) {
+      io.stdout.write(`- ${touchedFile}\n`);
+    }
+    io.stdout.write(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}\n`);
+    if (options.verbose && migrationWarnings.length > 0) {
+      io.stdout.write(`Warnings (${migrationWarnings.length}):\n`);
+      for (const warning of migrationWarnings) {
+        io.stdout.write(`- ${warning}\n`);
+      }
+    }
+    if (options.dryRun) {
+      io.stdout.write("Dry run enabled: no files were written.\n");
+    }
+  }
+
+  return 0;
+}
+
+export { runPackageMigrationsCommand };