@jskit-ai/jskit-cli 0.2.27 → 0.2.29

package/src/server/commandHandlers/health.js

@@ -0,0 +1,292 @@
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../shared/collectionUtils.js";
+
+function createHealthCommands(ctx = {}) {
+  const {
+    resolveAppRootFromCwd,
+    loadLockFile,
+    loadPackageRegistry,
+    loadBundleRegistry,
+    loadAppLocalPackageRegistry,
+    mergePackageRegistries,
+    hydratePackageRegistryFromInstalledNodeModules,
+    inspectPackageOfferings,
+    fileExists,
+    path
+  } = ctx;
+
+  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 commandDoctor({ cwd, options, stdout }) {
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const { lock } = await loadLockFile(appRoot);
+    const packageRegistry = await loadPackageRegistry();
+    const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+    const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
+    const issues = [];
+    const installed = ensureObject(lock.installedPackages);
+    await hydratePackageRegistryFromInstalledNodeModules({
+      appRoot,
+      packageRegistry: combinedPackageRegistry,
+      seedPackageIds: Object.keys(installed)
+    });
+
+    for (const [packageId, lockEntryValue] of Object.entries(installed)) {
+      const lockEntry = ensureObject(lockEntryValue);
+      if (!combinedPackageRegistry.has(packageId)) {
+        issues.push(`Installed package not found in package registry: ${packageId}`);
+        continue;
+      }
+
+      const managed = ensureObject(lockEntry.managed);
+      for (const fileChange of ensureArray(managed.files)) {
+        const changeRecord = ensureObject(fileChange);
+        const relativePath = String(changeRecord.path || "").trim();
+        const absolutePath = path.join(appRoot, relativePath);
+        if (!(await fileExists(absolutePath))) {
+          issues.push(`${packageId}: managed file missing: ${relativePath}`);
+        }
+      }
+    }
+
+    const payload = {
+      appRoot,
+      lockVersion: lock.lockVersion,
+      installedPackages: sortStrings(Object.keys(installed)),
+      issues
+    };
+
+    if (options.json) {
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      stdout.write(`App root: ${appRoot}\n`);
+      stdout.write(`Installed packages: ${payload.installedPackages.length}\n`);
+      if (issues.length === 0) {
+        stdout.write("Doctor status: healthy\n");
+      } else {
+        stdout.write(`Doctor status: unhealthy (${issues.length} issue(s))\n`);
+        for (const issue of issues) {
+          stdout.write(`- ${issue}\n`);
+        }
+      }
+    }
+
+    return issues.length === 0 ? 0 : 1;
+  }
+
+  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()]),
+      diLabelCheck: shouldCheckDiLabels
+        ? {
+            enabled: true,
+            issueCount: diLabelIssues.length,
+            issues: diLabelIssues
+          }
+        : {
+            enabled: false
+          }
+    };
+
+    if (options.json) {
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      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;
+  }
+
+  return {
+    commandDoctor,
+    commandLintDescriptors
+  };
+}
+
+export { createHealthCommands };

package/src/server/commandHandlers/list.js

@@ -0,0 +1,292 @@
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../shared/collectionUtils.js";
+
+function createListCommands(ctx = {}) {
+  const {
+    createCliError,
+    createColorFormatter,
+    normalizeRelativePosixPath,
+    resolveAppRootFromCwd,
+    loadLockFile,
+    loadPackageRegistry,
+    loadBundleRegistry,
+    loadAppLocalPackageRegistry,
+    discoverShellOutletTargetsFromApp,
+    resolvePackageKind
+  } = ctx;
+
+  async function commandList({ positional, options, cwd, stdout }) {
+    const packageRegistry = await loadPackageRegistry();
+    const bundleRegistry = await loadBundleRegistry();
+
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+    const { lock } = await loadLockFile(appRoot);
+    const installedPackageEntries = ensureObject(lock.installedPackages);
+    const installedPackages = new Set(Object.keys(installedPackageEntries));
+    const installedUnknownPackageIds = sortStrings(
+      [...installedPackages].filter((packageId) => !packageRegistry.has(packageId))
+    );
+    const installedLocalPackageIds = sortStrings(
+      installedUnknownPackageIds.filter((packageId) => {
+        const lockEntry = ensureObject(installedPackageEntries[packageId]);
+        const sourceType = String(ensureObject(lockEntry.source).type || "").trim();
+        return sourceType === "local-package" || sourceType === "app-local-package" || appLocalRegistry.has(packageId);
+      })
+    );
+    const installedExternalPackageIds = sortStrings(
+      installedUnknownPackageIds.filter((packageId) => !installedLocalPackageIds.includes(packageId))
+    );
+    const availableLocalPackageIds = sortStrings(
+      [...appLocalRegistry.keys()].filter((packageId) => !installedPackages.has(packageId))
+    );
+
+    const mode = String(positional[0] || "").trim();
+    const shouldListBundles = !mode || mode === "bundles";
+    const shouldListPackages = !mode || mode === "packages";
+    const shouldListGenerators = !mode || mode === "generators";
+    if (mode === "placements") {
+      throw createCliError('list mode "placements" moved to a dedicated command: jskit list-placements.');
+    }
+
+    if (!shouldListBundles && !shouldListPackages && !shouldListGenerators) {
+      throw createCliError(`Unknown list mode: ${mode}`, { showUsage: true });
+    }
+
+    const color = createColorFormatter(stdout);
+    const lines = [];
+    if (shouldListBundles) {
+      lines.push(color.heading("Available bundles:"));
+      const bundleIds = sortStrings([...bundleRegistry.keys()]);
+      for (const bundleId of bundleIds) {
+        const bundle = bundleRegistry.get(bundleId);
+        const packageIds = ensureArray(bundle.packages).map((value) => String(value));
+        const isInstalled = packageIds.length > 0 && packageIds.every((packageId) => installedPackages.has(packageId));
+        const providerLabel = Number(bundle.provider) === 1 ? " [provider]" : "";
+        const installedLabel = isInstalled ? " (installed)" : "";
+        lines.push(
+          `- ${color.item(bundle.bundleId)} ${color.version(`(${bundle.version})`)}${isInstalled ? color.installed(installedLabel) : installedLabel}${providerLabel ? color.provider(providerLabel) : providerLabel}: ${String(bundle.description || "")}`
+        );
+        if (options.full || options.expanded) {
+          for (const packageId of packageIds) {
+            lines.push(`  - ${color.dim(packageId)}`);
+          }
+        }
+      }
+    }
+
+    if (shouldListPackages) {
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      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)" : "";
+        lines.push(
+          `- ${color.item(packageId)} ${color.version(`(${packageEntry.version})`)}${installedLabel ? color.installed(installedLabel) : ""}`
+        );
+      }
+
+      if (installedLocalPackageIds.length > 0) {
+        lines.push("");
+        lines.push(color.heading("Installed local packages:"));
+        for (const packageId of installedLocalPackageIds) {
+          const lockEntry = ensureObject(installedPackageEntries[packageId]);
+          const version = String(lockEntry.version || "").trim();
+          const versionLabel = version ? ` ${color.version(`(${version})`)}` : "";
+          lines.push(`- ${color.item(packageId)}${versionLabel}${color.installed(" (installed)")}`);
+        }
+      }
+
+      if (installedExternalPackageIds.length > 0) {
+        lines.push("");
+        lines.push(color.heading("Installed external packages:"));
+        for (const packageId of installedExternalPackageIds) {
+          const lockEntry = ensureObject(installedPackageEntries[packageId]);
+          const version = String(lockEntry.version || "").trim();
+          const versionLabel = version ? ` ${color.version(`(${version})`)}` : "";
+          lines.push(`- ${color.item(packageId)}${versionLabel}${color.installed(" (installed)")}`);
+        }
+      }
+
+      if (availableLocalPackageIds.length > 0) {
+        lines.push("");
+        lines.push(color.heading("Available local packages (not installed):"));
+        for (const packageId of availableLocalPackageIds) {
+          const packageEntry = appLocalRegistry.get(packageId);
+          const version = String(packageEntry?.version || "").trim();
+          const versionLabel = version ? ` ${color.version(`(${version})`)}` : "";
+          lines.push(`- ${color.item(packageId)}${versionLabel}`);
+        }
+      }
+    }
+
+    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 = {
+        bundles: shouldListBundles
+          ? sortStrings([...bundleRegistry.keys()]).map((bundleId) => {
+            const bundle = bundleRegistry.get(bundleId);
+            const packageIds = ensureArray(bundle.packages).map((value) => String(value));
+            return {
+              bundleId: bundle.bundleId,
+              version: bundle.version,
+              description: bundle.description || "",
+              provider: Number(bundle.provider) === 1,
+              installed: packageIds.length > 0 && packageIds.every((packageId) => installedPackages.has(packageId)),
+              packages: packageIds
+            };
+          })
+          : [],
+        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) => {
+            const lockEntry = ensureObject(installedPackageEntries[packageId]);
+            return {
+              packageId,
+              version: String(lockEntry.version || "").trim()
+            };
+          })
+          : [],
+        installedExternalPackages: shouldListPackages
+          ? installedExternalPackageIds.map((packageId) => {
+            const lockEntry = ensureObject(installedPackageEntries[packageId]);
+            return {
+              packageId,
+              version: String(lockEntry.version || "").trim(),
+              source: ensureObject(lockEntry.source)
+            };
+          })
+          : [],
+        availableLocalPackages: shouldListPackages
+          ? availableLocalPackageIds.map((packageId) => {
+            const packageEntry = appLocalRegistry.get(packageId);
+            return {
+              packageId,
+              version: String(packageEntry?.version || "").trim(),
+              packagePath: normalizeRelativePosixPath(String(packageEntry?.relativeDir || ""))
+            };
+          })
+          : []
+      };
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      stdout.write(`${lines.join("\n")}\n`);
+    }
+
+    return 0;
+  }
+
+  async function commandListPlacements({ options, cwd, stdout }) {
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const discoveredPlacements = await discoverShellOutletTargetsFromApp({
+      appRoot,
+      sourceRoot: "src"
+    });
+    const placementTargets = ensureArray(discoveredPlacements.targets)
+      .map((entry) => ensureObject(entry))
+      .filter((entry) => String(entry.id || "").trim())
+      .sort((left, right) => String(left.id || "").localeCompare(String(right.id || "")));
+
+    if (options.json) {
+      const payload = {
+        placements: placementTargets.map((placementTarget) => ({
+          id: String(placementTarget.id || "").trim(),
+          host: String(placementTarget.host || "").trim(),
+          position: String(placementTarget.position || "").trim(),
+          default: placementTarget.default === true,
+          sourcePath: String(placementTarget.sourcePath || "").trim()
+        }))
+      };
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      return 0;
+    }
+
+    const color = createColorFormatter(stdout);
+    const lines = [color.heading("Available placements:")];
+    if (placementTargets.length < 1) {
+      lines.push("- none");
+    } else {
+      for (const placementTarget of placementTargets) {
+        const placementId = String(placementTarget.id || "").trim();
+        const sourcePath = String(placementTarget.sourcePath || "").trim();
+        const isDefault = placementTarget.default === true;
+        const defaultLabel = isDefault ? color.installed(" (default)") : "";
+        const sourceLabel = sourcePath ? ` ${color.dim(`[${sourcePath}]`)}` : "";
+        lines.push(`- ${color.item(placementId)}${defaultLabel}${sourceLabel}`);
+      }
+    }
+
+    stdout.write(`${lines.join("\n")}\n`);
+    return 0;
+  }
+
+  return {
+    commandList,
+    commandListPlacements
+  };
+}
+
+export { createListCommands };

package/src/server/commandHandlers/package.js

@@ -0,0 +1,23 @@
+import { runPackageCreateCommand } from "./packageCommands/create.js";
+import { runPackageAddCommand } from "./packageCommands/add.js";
+import { runPackageGenerateCommand } from "./packageCommands/generate.js";
+import { runPackageUpdateCommand } from "./packageCommands/update.js";
+import { runPackageMigrationsCommand } from "./packageCommands/migrations.js";
+import { runPackagePositionCommand } from "./packageCommands/position.js";
+import { runPackageRemoveCommand } from "./packageCommands/remove.js";
+
+function createPackageCommands(ctx = {}) {
+  const commandAdd = async (args) => runPackageAddCommand(ctx, args);
+
+  return {
+    commandCreate: async (args) => runPackageCreateCommand(ctx, args),
+    commandAdd,
+    commandGenerate: async (args) => runPackageGenerateCommand(ctx, args, { runCommandAdd: commandAdd }),
+    commandUpdate: async (args) => runPackageUpdateCommand(ctx, args, { runCommandAdd: commandAdd }),
+    commandMigrations: async (args) => runPackageMigrationsCommand(ctx, args),
+    commandPosition: async (args) => runPackagePositionCommand(ctx, args),
+    commandRemove: async (args) => runPackageRemoveCommand(ctx, args)
+  };
+}
+
+export { createPackageCommands };