@jskit-ai/jskit-cli 0.2.23 → 0.2.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "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.23"
+    "@jskit-ai/jskit-catalog": "0.1.25"
   },
   "engines": {
     "node": "20.x"

package/src/server/argParser.js

@@ -4,6 +4,7 @@ const KNOWN_COMMANDS = new Set([
   "list",
   "show",
   "view",
+  "migrations",
   "add",
   "position",
   "update",
@@ -165,6 +166,7 @@ function printUsage(stream = process.stderr) {
   stream.write("  position element <packageId> Re-apply positioning mutations for one installed package\n");
   stream.write("  show <id>                    Show details for bundle id or package id\n");
   stream.write("  view <id>                    Alias of show <id>\n");
+  stream.write("  migrations <scope>           Generate managed migrations only (scope: all | changed | package <packageId>)\n");
   stream.write("  update package <packageId>   Re-apply one installed package\n");
   stream.write("  remove package <packageId>   Remove one installed package\n");
   stream.write("  doctor                       Validate lockfile + managed files\n");

package/src/server/cliRuntime.js

@@ -4298,6 +4298,79 @@ async function applyPackagePositioning({
   return managedRecord;
 }
 
+async function applyPackageMigrationsOnly({
+  packageEntry,
+  packageOptions,
+  appRoot,
+  lock,
+  touchedFiles
+}) {
+  const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
+  if (Object.keys(existingInstall).length < 1) {
+    throw createCliError(`Package is not installed: ${packageEntry.packageId}`);
+  }
+
+  const existingManaged = ensureObject(existingInstall.managed);
+  const existingPackageJsonManaged = ensureObject(existingManaged.packageJson);
+  const nextManaged = {
+    packageJson: {
+      dependencies: cloneManagedMap(existingPackageJsonManaged.dependencies),
+      devDependencies: cloneManagedMap(existingPackageJsonManaged.devDependencies),
+      scripts: cloneManagedMap(existingPackageJsonManaged.scripts)
+    },
+    text: cloneManagedMap(existingManaged.text),
+    vite: cloneManagedMap(existingManaged.vite),
+    files: cloneManagedArray(existingManaged.files),
+    migrations: cloneManagedArray(existingManaged.migrations)
+  };
+
+  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
+  const packageEntryForMutations =
+    templateRoot === packageEntry.rootDir
+      ? packageEntry
+      : {
+          ...packageEntry,
+          rootDir: templateRoot
+        };
+  const mutations = ensureObject(packageEntry.descriptor.mutations);
+  const migrationFileMutations = ensureArray(mutations.files).filter((mutationValue) => {
+    const normalized = normalizeFileMutationRecord(mutationValue);
+    const operation = String(normalized.op || "copy-file").trim();
+    return operation === "install-migration";
+  });
+  const mutationWarnings = [];
+
+  if (migrationFileMutations.length > 0) {
+    await applyFileMutations(
+      packageEntryForMutations,
+      packageOptions,
+      appRoot,
+      migrationFileMutations,
+      [],
+      nextManaged.migrations,
+      touchedFiles,
+      mutationWarnings
+    );
+  }
+
+  const managedRecord = {
+    ...existingInstall,
+    packageId: packageEntry.packageId,
+    source: resolveManagedSourceRecord(packageEntry, existingInstall),
+    managed: nextManaged,
+    options: {
+      ...ensureObject(packageOptions)
+    },
+    migrationSyncVersion: packageEntry.version,
+    installedAt: String(existingInstall.installedAt || new Date().toISOString())
+  };
+  lock.installedPackages[packageEntry.packageId] = managedRecord;
+  if (mutationWarnings.length > 0) {
+    managedRecord.warnings = mutationWarnings;
+  }
+  return managedRecord;
+}
+
 async function applyPackageInstall({
   packageEntry,
   packageOptions,
@@ -4462,6 +4535,7 @@ async function applyPackageInstall({
   if (cloneOnlyPackage) {
     delete lock.installedPackages[packageEntry.packageId];
   } else {
+    managedRecord.migrationSyncVersion = packageEntry.version;
     lock.installedPackages[packageEntry.packageId] = managedRecord;
   }
   if (mutationWarnings.length > 0) {
@@ -4522,6 +4596,7 @@ const commandHandlers = createCommandHandlers(
     validatePlannedCapabilityClosure,
     resolvePackageOptions,
     applyPackageInstall,
+    applyPackageMigrationsOnly,
     applyPackagePositioning,
     adoptAppLocalPackageDependencies,
     loadAppPackageJson,

package/src/server/commandHandlers.js

@@ -28,6 +28,7 @@ function createCommandHandlers(deps) {
     validatePlannedCapabilityClosure,
     resolvePackageOptions,
     applyPackageInstall,
+    applyPackageMigrationsOnly,
     applyPackagePositioning,
     adoptAppLocalPackageDependencies,
     loadAppPackageJson,
@@ -1336,6 +1337,138 @@ function createCommandHandlers(deps) {
     });
   }
 
+  async function commandMigrations({ positional, options, cwd, io }) {
+    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 (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;
+  }
+
   async function commandPosition({ positional, options, cwd, io }) {
     const targetType = String(positional[0] || "").trim();
     const targetId = String(positional[1] || "").trim();
@@ -1649,6 +1782,7 @@ function createCommandHandlers(deps) {
     commandShow,
     commandCreate,
     commandAdd,
+    commandMigrations,
     commandPosition,
     commandUpdate,
     commandRemove,

package/src/server/runCli.js

@@ -48,6 +48,14 @@ function createRunCli({
       if (command === "show") {
         return await commandHandlers.commandShow({ positional, options, stdout });
       }
+      if (command === "migrations") {
+        return await commandHandlers.commandMigrations({
+          positional,
+          options,
+          cwd,
+          io: { stdin, stdout, stderr }
+        });
+      }
       if (command === "add") {
         return await commandHandlers.commandAdd({
           positional,

package/src/server/runtimeDeps.js

@@ -21,6 +21,7 @@ function createCommandHandlerDeps(deps = {}) {
     validatePlannedCapabilityClosure: deps.validatePlannedCapabilityClosure,
     resolvePackageOptions: deps.resolvePackageOptions,
     applyPackageInstall: deps.applyPackageInstall,
+    applyPackageMigrationsOnly: deps.applyPackageMigrationsOnly,
     applyPackagePositioning: deps.applyPackagePositioning,
     adoptAppLocalPackageDependencies: deps.adoptAppLocalPackageDependencies,
     loadAppPackageJson: deps.loadAppPackageJson,