@jskit-ai/jskit-cli 0.2.24 → 0.2.26

package/src/server/commandHandlers.js

@@ -28,6 +28,7 @@ function createCommandHandlers(deps) {
     validatePlannedCapabilityClosure,
     resolvePackageOptions,
     applyPackageInstall,
+    applyPackageMigrationsOnly,
     applyPackagePositioning,
     adoptAppLocalPackageDependencies,
     loadAppPackageJson,
@@ -123,6 +124,18 @@ function createCommandHandlers(deps) {
     return sortStrings(dependents);
   }
 
+  function resolvePackageKind(packageEntry) {
+    const descriptor = ensureObject(packageEntry?.descriptor);
+    const normalizedKind = String(descriptor.kind || "").trim().toLowerCase();
+    if (normalizedKind === "runtime" || normalizedKind === "generator") {
+      return normalizedKind;
+    }
+    const packageId = String(packageEntry?.packageId || descriptor.packageId || "unknown-package").trim();
+    throw createCliError(
+      `Invalid package descriptor for ${packageId}: missing/invalid kind (expected runtime or generator).`
+    );
+  }
+
   function resolvePackageOptionNames(packageEntry) {
     const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
     return Object.keys(optionSchemas);
@@ -176,6 +189,155 @@ function createCommandHandlers(deps) {
       : " This bundle does not accept inline options.";
     throw createCliError(`Unknown option(s) for bundle ${bundleId}: ${sortedUnknown.join(", ")}.${suffix}`);
   }
+
+  function collectDescriptorContainerTokens({ packageId, side, values, issues }) {
+    const declaredTokens = new Set();
+    const duplicateTokens = new Set();
+    let invalidCount = 0;
+
+    for (const rawValue of ensureArray(values)) {
+      if (typeof rawValue !== "string") {
+        invalidCount += 1;
+        continue;
+      }
+      const token = rawValue.trim();
+      if (!token) {
+        invalidCount += 1;
+        continue;
+      }
+      if (declaredTokens.has(token)) {
+        duplicateTokens.add(token);
+        continue;
+      }
+      declaredTokens.add(token);
+    }
+
+    if (invalidCount > 0) {
+      issues.push({
+        packageId,
+        side,
+        code: "descriptor-token-invalid",
+        message: `${packageId} (${side}): metadata.apiSummary.containerTokens includes ${invalidCount} non-string or empty token value(s).`
+      });
+    }
+    for (const token of sortStrings([...duplicateTokens])) {
+      issues.push({
+        packageId,
+        side,
+        code: "descriptor-token-duplicate",
+        token,
+        message: `${packageId} (${side}): descriptor token is declared more than once: ${token}.`
+      });
+    }
+
+    return declaredTokens;
+  }
+
+  function collectUsedContainerTokens({ packageId, side, bindings, issues }) {
+    const usedTokens = new Set();
+    for (const rawBinding of ensureArray(bindings)) {
+      const binding = ensureObject(rawBinding);
+      const tokenExpression = String(binding.tokenExpression || "").trim();
+      const token = String(binding.token || "").trim();
+      const location = String(binding.location || "").trim();
+      if (binding.tokenResolved !== true || !token) {
+        const expressionLabel = tokenExpression || "<empty>";
+        const locationSuffix = location ? ` at ${location}` : "";
+        issues.push({
+          packageId,
+          side,
+          code: "binding-token-unresolved",
+          tokenExpression: expressionLabel,
+          location,
+          message: `${packageId} (${side}): unresolved DI token expression "${expressionLabel}"${locationSuffix}.`
+        });
+        continue;
+      }
+      usedTokens.add(token);
+    }
+    return usedTokens;
+  }
+
+  function collectProviderIntrospectionIssues({ packageId, packageInsights, issues }) {
+    const introspection = ensureObject(packageInsights);
+    if (!introspection.available) {
+      issues.push({
+        packageId,
+        side: "",
+        code: "provider-introspection-unavailable",
+        message: `${packageId}: provider source introspection is unavailable, so DI token parity cannot be verified.`
+      });
+      return;
+    }
+
+    const notes = ensureArray(introspection.notes).map((value) => String(value || "").trim()).filter(Boolean);
+    for (const note of notes) {
+      if (
+        note.startsWith("Skipped wildcard provider entrypoint during introspection:") ||
+        note.startsWith("Provider file missing during introspection:") ||
+        note.startsWith("Failed reading provider ")
+      ) {
+        issues.push({
+          packageId,
+          side: "",
+          code: "provider-introspection-incomplete",
+          message: `${packageId}: ${note}`
+        });
+      }
+    }
+  }
+
+  function collectDiLabelParityIssuesForPackage({ packageEntry, packageInsights }) {
+    const packageId = String(packageEntry?.packageId || "").trim();
+    const descriptor = ensureObject(packageEntry?.descriptor);
+    const metadataApiSummary = ensureObject(ensureObject(descriptor.metadata).apiSummary);
+    const descriptorTokenSummary = ensureObject(metadataApiSummary.containerTokens);
+    const bindingSections = ensureObject(ensureObject(packageInsights).containerBindings);
+    const issues = [];
+    const sides = ["server", "client"];
+
+    collectProviderIntrospectionIssues({ packageId, packageInsights, issues });
+
+    for (const side of sides) {
+      const declaredTokens = collectDescriptorContainerTokens({
+        packageId,
+        side,
+        values: descriptorTokenSummary[side],
+        issues
+      });
+      const usedTokens = collectUsedContainerTokens({
+        packageId,
+        side,
+        bindings: bindingSections[side],
+        issues
+      });
+
+      for (const token of sortStrings([...usedTokens])) {
+        if (!declaredTokens.has(token)) {
+          issues.push({
+            packageId,
+            side,
+            code: "binding-token-undeclared",
+            token,
+            message: `${packageId} (${side}): token is used by providers but missing from metadata.apiSummary.containerTokens.${side}: ${token}.`
+          });
+        }
+      }
+      for (const token of sortStrings([...declaredTokens])) {
+        if (!usedTokens.has(token)) {
+          issues.push({
+            packageId,
+            side,
+            code: "descriptor-token-unused",
+            token,
+            message: `${packageId} (${side}): token is declared in metadata.apiSummary.containerTokens.${side} but never bound by providers: ${token}.`
+          });
+        }
+      }
+    }
+
+    return issues;
+  }
   
   async function commandList({ positional, options, cwd, stdout }) {
     const packageRegistry = await loadPackageRegistry();
@@ -206,8 +368,9 @@ function createCommandHandlers(deps) {
     const mode = String(positional[0] || "").trim();
     const shouldListBundles = !mode || mode === "bundles";
     const shouldListPackages = !mode || mode === "packages";
-  
-    if (!shouldListBundles && !shouldListPackages) {
+    const shouldListGenerators = !mode || mode === "generators";
+
+    if (!shouldListBundles && !shouldListPackages && !shouldListGenerators) {
       throw createCliError(`Unknown list mode: ${mode}`, { showUsage: true });
     }
   
@@ -237,8 +400,11 @@ function createCommandHandlers(deps) {
       if (lines.length > 0) {
         lines.push("");
       }
-      lines.push(color.heading("Available packages:"));
-      const packageIds = sortStrings([...packageRegistry.keys()]);
+      lines.push(color.heading("Available runtime packages:"));
+      const packageIds = sortStrings([...packageRegistry.keys()].filter((packageId) => {
+        const packageEntry = packageRegistry.get(packageId);
+        return resolvePackageKind(packageEntry) === "runtime";
+      }));
       for (const packageId of packageIds) {
         const packageEntry = packageRegistry.get(packageId);
         const installedLabel = installedPackages.has(packageId) ? " (installed)" : "";
@@ -280,6 +446,24 @@ function createCommandHandlers(deps) {
         }
       }
     }
+
+    if (shouldListGenerators) {
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      lines.push(color.heading("Available generators:"));
+      const packageIds = sortStrings([...packageRegistry.keys()].filter((packageId) => {
+        const packageEntry = packageRegistry.get(packageId);
+        return resolvePackageKind(packageEntry) === "generator";
+      }));
+      for (const packageId of packageIds) {
+        const packageEntry = packageRegistry.get(packageId);
+        const installedLabel = installedPackages.has(packageId) ? " (installed)" : "";
+        lines.push(
+          `- ${color.item(packageId)} ${color.version(`(${packageEntry.version})`)}${installedLabel ? color.installed(installedLabel) : ""}`
+        );
+      }
+    }
   
     if (options.json) {
       const payload = {
@@ -298,14 +482,42 @@ function createCommandHandlers(deps) {
           })
           : [],
         packages: shouldListPackages
+          ? sortStrings([...packageRegistry.keys()])
+            .filter((packageId) => resolvePackageKind(packageRegistry.get(packageId)) === "runtime")
+            .map((packageId) => {
+              const packageEntry = packageRegistry.get(packageId);
+              return {
+                packageId,
+                version: packageEntry.version,
+                installed: installedPackages.has(packageId)
+              };
+            })
+          : [],
+        runtimePackages: shouldListPackages
           ? sortStrings([...packageRegistry.keys()]).map((packageId) => {
             const packageEntry = packageRegistry.get(packageId);
+            if (resolvePackageKind(packageEntry) !== "runtime") {
+              return null;
+            }
             return {
               packageId,
               version: packageEntry.version,
               installed: installedPackages.has(packageId)
             };
-          })
+          }).filter(Boolean)
+          : [],
+        generators: shouldListGenerators
+          ? sortStrings([...packageRegistry.keys()]).map((packageId) => {
+            const packageEntry = packageRegistry.get(packageId);
+            if (resolvePackageKind(packageEntry) !== "generator") {
+              return null;
+            }
+            return {
+              packageId,
+              version: packageEntry.version,
+              installed: installedPackages.has(packageId)
+            };
+          }).filter(Boolean)
           : [],
         installedLocalPackages: shouldListPackages
           ? installedLocalPackageIds.map((packageId) => {
@@ -1102,10 +1314,16 @@ function createCommandHandlers(deps) {
   }
   
   async function commandAdd({ positional, options, cwd, io }) {
+    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
       });
@@ -1113,6 +1331,11 @@ function createCommandHandlers(deps) {
     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();
@@ -1122,10 +1345,11 @@ function createCommandHandlers(deps) {
     const { packageJsonPath, packageJson } = await loadAppPackageJson(appRoot);
     const { lockPath, lock } = await loadLockFile(appRoot);
     let resolvedTargetPackageId = targetType === "package" ? resolvePackageIdInput(targetId, combinedPackageRegistry) : "";
-    if (targetType === "package" && !resolvedTargetPackageId) {
+    if (targetType === "package") {
+      const packageIdForNodeModulesLookup = resolvedTargetPackageId || targetId;
       const installedNodeModuleEntry = await resolveInstalledNodeModulePackageEntry({
         appRoot,
-        packageId: targetId
+        packageId: packageIdForNodeModulesLookup
       });
       if (installedNodeModuleEntry) {
         combinedPackageRegistry.set(installedNodeModuleEntry.packageId, installedNodeModuleEntry);
@@ -1156,6 +1380,17 @@ function createCommandHandlers(deps) {
       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);
     }
   
@@ -1163,6 +1398,17 @@ function createCommandHandlers(deps) {
       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),
@@ -1172,7 +1418,7 @@ function createCommandHandlers(deps) {
     validatePlannedCapabilityClosure(
       plannedInstalledPackageIds,
       combinedPackageRegistry,
-      `add ${targetType} ${targetId}`
+      `${invocationMode} ${targetType} ${targetId}`
     );
 
     if (targetType === "bundle") {
@@ -1251,14 +1497,18 @@ function createCommandHandlers(deps) {
       validatePlannedCapabilityClosure(
         postInstallPackageIds,
         combinedPackageRegistry,
-        `add ${targetType} ${targetId}`
+        `${invocationMode} ${targetType} ${targetId}`
       );
     }
   
     const finalResolvedPackageIds = sortStrings([...resolvedPackageIds, ...adoptedPackageIds]);
   
     const touchedFileList = sortStrings([...touchedFiles]);
-    const successLabel = targetType === "bundle" ? "Added bundle" : "Added package";
+    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())
@@ -1274,7 +1524,7 @@ function createCommandHandlers(deps) {
   
     if (options.json) {
       io.stdout.write(`${JSON.stringify({
-        targetType,
+        targetType: invocationMode === "generate" ? "generator" : targetType,
         targetId,
         resolvedPackages: finalResolvedPackageIds,
         touchedFiles: touchedFileList,
@@ -1309,6 +1559,32 @@ function createCommandHandlers(deps) {
   
     return 0;
   }
+
+  async function commandGenerate({ positional, options, cwd, io }) {
+    const firstToken = String(positional[0] || "").trim();
+    const secondToken = String(positional[1] || "").trim();
+    if (firstToken === "bundle") {
+      throw createCliError("generate supports packages only (generate <packageId>).", {
+        showUsage: true
+      });
+    }
+    const targetId = firstToken === "package" ? secondToken : firstToken;
+    if (!targetId) {
+      throw createCliError("generate requires a package id (generate <packageId>).", {
+        showUsage: true
+      });
+    }
+
+    return commandAdd({
+      positional: ["package", targetId],
+      options: {
+        ...options,
+        commandMode: "generate"
+      },
+      cwd,
+      io
+    });
+  }
   
   async function commandUpdate({ positional, options, cwd, io }) {
     const targetType = String(positional[0] || "").trim();
@@ -1336,6 +1612,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 (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;
+  }
+
   async function commandPosition({ positional, options, cwd, io }) {
     const targetType = String(positional[0] || "").trim();
     const targetId = String(positional[1] || "").trim();
@@ -1627,19 +2035,58 @@ function createCommandHandlers(deps) {
   async function commandLintDescriptors({ options, stdout }) {
     const packageRegistry = await loadPackageRegistry();
     const bundleRegistry = await loadBundleRegistry();
+    const shouldCheckDiLabels = options.checkDiLabels === true;
+    let diLabelIssues = [];
+    if (shouldCheckDiLabels) {
+      const issues = [];
+      for (const packageId of sortStrings([...packageRegistry.keys()])) {
+        const packageEntry = packageRegistry.get(packageId);
+        if (!packageEntry) {
+          continue;
+        }
+        const packageInsights = await inspectPackageOfferings({ packageEntry });
+        issues.push(...collectDiLabelParityIssuesForPackage({ packageEntry, packageInsights }));
+      }
+      diLabelIssues = issues;
+    }
     const payload = {
       packageCount: packageRegistry.size,
       bundleCount: bundleRegistry.size,
       packages: sortStrings([...packageRegistry.keys()]),
-      bundles: sortStrings([...bundleRegistry.keys()])
+      bundles: sortStrings([...bundleRegistry.keys()]),
+      diLabelCheck: shouldCheckDiLabels
+        ? {
+            enabled: true,
+            issueCount: diLabelIssues.length,
+            issues: diLabelIssues
+          }
+        : {
+            enabled: false
+          }
     };
 
     if (options.json) {
       stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
     } else {
-      stdout.write(`Descriptor lint passed.\n`);
+      const descriptorStatus = shouldCheckDiLabels && diLabelIssues.length > 0 ? "failed" : "passed";
+      stdout.write(`Descriptor lint ${descriptorStatus}.\n`);
       stdout.write(`Packages: ${payload.packageCount}\n`);
       stdout.write(`Bundles: ${payload.bundleCount}\n`);
+      if (shouldCheckDiLabels) {
+        if (diLabelIssues.length === 0) {
+          stdout.write("DI label parity check passed.\n");
+        } else {
+          stdout.write(`DI label parity check failed (${diLabelIssues.length} issue(s)).\n`);
+          for (const issue of diLabelIssues) {
+            const code = String(issue?.code || "").trim();
+            const codeLabel = code ? `[${code}] ` : "";
+            stdout.write(`- ${codeLabel}${String(issue?.message || "").trim()}\n`);
+          }
+        }
+      }
+    }
+    if (shouldCheckDiLabels && diLabelIssues.length > 0) {
+      return 1;
     }
     return 0;
   }
@@ -1649,6 +2096,8 @@ function createCommandHandlers(deps) {
     commandShow,
     commandCreate,
     commandAdd,
+    commandGenerate,
+    commandMigrations,
     commandPosition,
     commandUpdate,
     commandRemove,