@jskit-ai/jskit-cli 0.2.25 → 0.2.27

package/src/server/commandHandlers.js

@@ -124,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);
@@ -177,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();
@@ -207,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 });
     }
   
@@ -238,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)" : "";
@@ -281,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 = {
@@ -299,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) => {
@@ -1103,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
       });
@@ -1114,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();
@@ -1123,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);
@@ -1157,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);
     }
   
@@ -1164,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),
@@ -1173,7 +1418,7 @@ function createCommandHandlers(deps) {
     validatePlannedCapabilityClosure(
       plannedInstalledPackageIds,
       combinedPackageRegistry,
-      `add ${targetType} ${targetId}`
+      `${invocationMode} ${targetType} ${targetId}`
     );
 
     if (targetType === "bundle") {
@@ -1252,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())
@@ -1275,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,
@@ -1310,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();
@@ -1455,7 +1730,7 @@ function createCommandHandlers(deps) {
         io.stdout.write(`- ${touchedFile}\n`);
       }
       io.stdout.write(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}\n`);
-      if (migrationWarnings.length > 0) {
+      if (options.verbose && migrationWarnings.length > 0) {
         io.stdout.write(`Warnings (${migrationWarnings.length}):\n`);
         for (const warning of migrationWarnings) {
           io.stdout.write(`- ${warning}\n`);
@@ -1760,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;
   }
@@ -1782,6 +2096,7 @@ function createCommandHandlers(deps) {
     commandShow,
     commandCreate,
     commandAdd,
+    commandGenerate,
     commandMigrations,
     commandPosition,
     commandUpdate,

package/src/server/pathResolution.js

@@ -8,66 +8,6 @@ import { createCliError } from "./cliError.js";
 const CLI_PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const require = createRequire(import.meta.url);
 
-function isWorkspaceRoot(candidateRoot) {
-  if (!candidateRoot) {
-    return false;
-  }
-  return (
-    existsSync(path.join(candidateRoot, "packages")) &&
-    existsSync(path.join(candidateRoot, "packages", "kernel")) &&
-    existsSync(path.join(candidateRoot, "tooling", "jskit-cli"))
-  );
-}
-
-function collectAncestorDirectories(startDirectory) {
-  const ancestors = [];
-  let current = path.resolve(startDirectory);
-  while (true) {
-    ancestors.push(current);
-    const parent = path.dirname(current);
-    if (parent === current) {
-      break;
-    }
-    current = parent;
-  }
-  return ancestors;
-}
-
-function resolveWorkspaceRoot() {
-  const candidates = [];
-  const seen = new Set();
-  const appendCandidate = (candidatePath) => {
-    const raw = String(candidatePath || "").trim();
-    if (!raw) {
-      return;
-    }
-    const absolute = path.resolve(raw);
-    if (seen.has(absolute)) {
-      return;
-    }
-    seen.add(absolute);
-    candidates.push(absolute);
-  };
-
-  appendCandidate(process.env.JSKIT_REPO_ROOT);
-  appendCandidate(path.resolve(CLI_PACKAGE_ROOT, "../.."));
-  appendCandidate(CLI_PACKAGE_ROOT);
-
-  const cwdAncestors = collectAncestorDirectories(process.cwd());
-  for (const ancestor of cwdAncestors) {
-    appendCandidate(ancestor);
-    appendCandidate(path.join(ancestor, "jskit-ai"));
-  }
-
-  for (const candidate of candidates) {
-    if (isWorkspaceRoot(candidate)) {
-      return candidate;
-    }
-  }
-
-  return "";
-}
-
 function resolveCatalogPackagesPath() {
   const explicitPath = String(process.env.JSKIT_CATALOG_PACKAGES_PATH || "").trim();
   if (explicitPath) {
@@ -92,15 +32,11 @@ function resolveCatalogPackagesPath() {
   );
 }
 
-const WORKSPACE_ROOT = resolveWorkspaceRoot();
-const MODULES_ROOT = WORKSPACE_ROOT ? path.join(WORKSPACE_ROOT, "packages") : "";
 const BUNDLES_ROOT = path.join(CLI_PACKAGE_ROOT, "bundles");
 const CATALOG_PACKAGES_PATH = resolveCatalogPackagesPath();
 
 export {
   CLI_PACKAGE_ROOT,
-  WORKSPACE_ROOT,
-  MODULES_ROOT,
   BUNDLES_ROOT,
   CATALOG_PACKAGES_PATH
 };

package/src/server/runCli.js

@@ -64,6 +64,14 @@ function createRunCli({
           io: { stdin, stdout, stderr }
         });
       }
+      if (command === "generate") {
+        return await commandHandlers.commandGenerate({
+          positional,
+          options,
+          cwd,
+          io: { stdin, stdout, stderr }
+        });
+      }
       if (command === "position") {
         return await commandHandlers.commandPosition({
           positional,