@jskit-ai/jskit-cli 0.2.29 → 0.2.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,8 +20,8 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.29",
-    "@jskit-ai/kernel": "0.1.21"
+    "@jskit-ai/jskit-catalog": "0.1.31",
+    "@jskit-ai/kernel": "0.1.23"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/mutationWhen.js

@@ -55,11 +55,9 @@ function normalizeMutationWhen(value) {
   const allConditions = ensureArray(source.all)
     .map((entry) => normalizeMutationWhen(entry))
     .filter(Boolean);
-  if (allConditions.length > 0) {
-    return {
-      all: allConditions
-    };
-  }
+  const anyConditions = ensureArray(source.any)
+    .map((entry) => normalizeMutationWhen(entry))
+    .filter(Boolean);
 
   const option = String(source.option || "").trim();
   const config = String(source.config || "").trim();
@@ -70,11 +68,13 @@ function normalizeMutationWhen(value) {
   const includes = ensureArray(source.in).map((entry) => String(entry || "").trim()).filter(Boolean);
   const excludes = ensureArray(source.notIn).map((entry) => String(entry || "").trim()).filter(Boolean);
 
-  if (!option && !config) {
+  if (!option && !config && allConditions.length < 1 && anyConditions.length < 1) {
     return null;
   }
 
   return {
+    all: allConditions,
+    any: anyConditions,
     option,
     config,
     equals,
@@ -217,7 +217,7 @@ function shouldApplyMutationWhen(
 
   const allConditions = ensureArray(when.all).filter((entry) => entry && typeof entry === "object");
   if (allConditions.length > 0) {
-    return allConditions.every((entry) =>
+    const allMatch = allConditions.every((entry) =>
       shouldApplyMutationWhen(entry, {
         options,
         configContext,
@@ -225,6 +225,24 @@ function shouldApplyMutationWhen(
         mutationContext
       })
     );
+    if (!allMatch) {
+      return false;
+    }
+  }
+
+  const anyConditions = ensureArray(when.any).filter((entry) => entry && typeof entry === "object");
+  if (anyConditions.length > 0) {
+    const anyMatch = anyConditions.some((entry) =>
+      shouldApplyMutationWhen(entry, {
+        options,
+        configContext,
+        packageId,
+        mutationContext
+      })
+    );
+    if (!anyMatch) {
+      return false;
+    }
   }
 
   const optionName = String(when.option || "").trim();

package/src/server/commandHandlers/health.js

@@ -1,3 +1,7 @@
+import {
+  readdir,
+  readFile
+} from "node:fs/promises";
 import {
   ensureArray,
   ensureObject,
@@ -15,9 +19,42 @@ function createHealthCommands(ctx = {}) {
     hydratePackageRegistryFromInstalledNodeModules,
     inspectPackageOfferings,
     fileExists,
+    normalizeRelativePath,
     path
   } = ctx;
 
+  const MDI_SVG_MAIN_ENTRY_CANDIDATES = Object.freeze([
+    "src/main.js",
+    "src/main.mjs",
+    "src/main.ts"
+  ]);
+  const MDI_SVG_SCAN_ROOTS = Object.freeze([
+    "src",
+    "packages"
+  ]);
+  const MDI_SVG_IGNORED_DIRECTORY_NAMES = new Set([
+    ".git",
+    ".jskit",
+    ".build",
+    "coverage",
+    "dist",
+    "docs",
+    "LEGACY",
+    "node_modules",
+    "test",
+    "tests",
+    "__tests__"
+  ]);
+  const MDI_SVG_IGNORED_FILE_PATTERNS = Object.freeze([
+    /\.spec\./i,
+    /\.test\./i,
+    /\.vitest\./i
+  ]);
+  const DIRECT_MDI_LITERAL_ICON_PATTERN =
+    /<(v-[a-z0-9-]+)[^>]*?\b(icon|prepend-icon|append-icon)\s*=\s*(['"])(mdi-[^'"]+)\3/gi;
+  const DIRECT_MDI_BOUND_LITERAL_ICON_PATTERN =
+    /<(v-[a-z0-9-]+)[^>]*?(?::|v-bind:)(icon|prepend-icon|append-icon)\s*=\s*(['"])(['"])(mdi-[^'"]+)\4\3/gi;
+
   function collectDescriptorContainerTokens({ packageId, side, values, issues }) {
     const declaredTokens = new Set();
     const duplicateTokens = new Set();
@@ -115,6 +152,104 @@ function createHealthCommands(ctx = {}) {
     }
   }
 
+  async function appUsesVuetifyMdiSvg(appRoot) {
+    for (const relativePath of MDI_SVG_MAIN_ENTRY_CANDIDATES) {
+      const absolutePath = path.join(appRoot, relativePath);
+      if (!(await fileExists(absolutePath))) {
+        continue;
+      }
+      const fileContent = await readFile(absolutePath, "utf8");
+      if (fileContent.includes("vuetify/iconsets/mdi-svg")) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  function shouldSkipMdiSvgDoctorDirectory(directoryName = "") {
+    return MDI_SVG_IGNORED_DIRECTORY_NAMES.has(String(directoryName || "").trim());
+  }
+
+  function shouldSkipMdiSvgDoctorFile(fileName = "") {
+    const normalizedFileName = String(fileName || "").trim();
+    if (!normalizedFileName.endsWith(".vue")) {
+      return true;
+    }
+    return MDI_SVG_IGNORED_FILE_PATTERNS.some((pattern) => pattern.test(normalizedFileName));
+  }
+
+  async function collectVueSourceFiles(rootDirectory, collected = []) {
+    if (!(await fileExists(rootDirectory))) {
+      return collected;
+    }
+
+    const entries = await readdir(rootDirectory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+      const entryPath = path.join(rootDirectory, entry.name);
+      if (entry.isDirectory()) {
+        if (shouldSkipMdiSvgDoctorDirectory(entry.name)) {
+          continue;
+        }
+        await collectVueSourceFiles(entryPath, collected);
+        continue;
+      }
+      if (entry.isFile() && !shouldSkipMdiSvgDoctorFile(entry.name)) {
+        collected.push(entryPath);
+      }
+    }
+
+    return collected;
+  }
+
+  function resolveLineNumberFromIndex(sourceText = "", index = 0) {
+    return String(sourceText || "").slice(0, Math.max(0, index)).split("\n").length;
+  }
+
+  function collectDirectMdiSvgTemplateIconIssues({ sourceText, relativePath, issues }) {
+    DIRECT_MDI_LITERAL_ICON_PATTERN.lastIndex = 0;
+    for (const match of sourceText.matchAll(DIRECT_MDI_LITERAL_ICON_PATTERN)) {
+      const [, tagName = "v-component", propName = "icon", , rawIcon = ""] = match;
+      const lineNumber = resolveLineNumberFromIndex(sourceText, match.index || 0);
+      issues.push(
+        `${relativePath}:${lineNumber}: raw "${rawIcon}" passed to <${tagName}> ${propName} while the app uses vuetify/iconsets/mdi-svg. Use an @mdi/js path or a Vuetify alias.`
+      );
+    }
+
+    DIRECT_MDI_BOUND_LITERAL_ICON_PATTERN.lastIndex = 0;
+    for (const match of sourceText.matchAll(DIRECT_MDI_BOUND_LITERAL_ICON_PATTERN)) {
+      const [, tagName = "v-component", propName = "icon", , , rawIcon = ""] = match;
+      const lineNumber = resolveLineNumberFromIndex(sourceText, match.index || 0);
+      issues.push(
+        `${relativePath}:${lineNumber}: raw "${rawIcon}" passed to <${tagName}> ${propName} while the app uses vuetify/iconsets/mdi-svg. Use an @mdi/js path or a Vuetify alias.`
+      );
+    }
+  }
+
+  async function collectMdiSvgDoctorIssues({ appRoot, issues }) {
+    if (!(await appUsesVuetifyMdiSvg(appRoot))) {
+      return;
+    }
+
+    const vueFilePaths = [];
+    for (const relativeRoot of MDI_SVG_SCAN_ROOTS) {
+      await collectVueSourceFiles(path.join(appRoot, relativeRoot), vueFilePaths);
+    }
+
+    vueFilePaths.sort((left, right) => left.localeCompare(right));
+
+    for (const absolutePath of vueFilePaths) {
+      const sourceText = await readFile(absolutePath, "utf8");
+      collectDirectMdiSvgTemplateIconIssues({
+        sourceText,
+        relativePath: normalizeRelativePath(appRoot, absolutePath),
+        issues
+      });
+    }
+  }
+
   function collectDiLabelParityIssuesForPackage({ packageEntry, packageInsights }) {
     const packageId = String(packageEntry?.packageId || "").trim();
     const descriptor = ensureObject(packageEntry?.descriptor);
@@ -199,6 +334,11 @@ function createHealthCommands(ctx = {}) {
       }
     }
 
+    await collectMdiSvgDoctorIssues({
+      appRoot,
+      issues
+    });
+
     const payload = {
       appRoot,
       lockVersion: lock.lockVersion,

package/src/server/commandHandlers/list.js

@@ -1,9 +1,134 @@
+import path from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
 import {
   ensureArray,
   ensureObject,
   sortStrings
 } from "../shared/collectionUtils.js";
 
+const PLACEMENT_FILE_RELATIVE_PATH = "src/placement.js";
+const MAIN_CLIENT_PROVIDERS_RELATIVE_PATH = "packages/main/src/client/providers";
+const COMPONENT_TOKEN_PATTERN = /\bcomponentToken\s*:\s*["']([^"']+)["']/g;
+const REGISTER_MAIN_CLIENT_COMPONENT_PATTERN = /registerMainClientComponent\(\s*["']([^"']+)["']\s*,/g;
+const LINK_ITEM_TOKEN_SUFFIX = "link-item";
+const PROVIDER_SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx"]);
+const READ_FILE_IGNORE_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR", "EACCES", "EPERM"]);
+const READ_DIRECTORY_IGNORE_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
+
+function collectTokenMatches(source = "", pattern = COMPONENT_TOKEN_PATTERN) {
+  const sourceText = String(source || "");
+  const tokens = [];
+  for (const match of sourceText.matchAll(pattern)) {
+    const token = String(match[1] || "").trim();
+    if (token) {
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+function appendTokenSource(map, token = "", source = "") {
+  const normalizedToken = String(token || "").trim();
+  if (!normalizedToken) {
+    return;
+  }
+  const normalizedSource = String(source || "").trim();
+  const existingSources = map.get(normalizedToken) || new Set();
+  if (normalizedSource) {
+    existingSources.add(normalizedSource);
+  }
+  map.set(normalizedToken, existingSources);
+}
+
+function isLinkItemToken(token = "") {
+  return String(token || "").trim().toLowerCase().endsWith(LINK_ITEM_TOKEN_SUFFIX);
+}
+
+async function readFileIfExists(filePath = "") {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    const errorCode = String(error?.code || "").trim().toUpperCase();
+    if (READ_FILE_IGNORE_ERROR_CODES.has(errorCode)) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+async function resolveDescriptorFromLockEntry({ appRoot = "", packageId = "", installedPackageEntry = {} } = {}) {
+  const source = ensureObject(installedPackageEntry.source);
+  const descriptorRelativePath = String(source.descriptorPath || "").trim();
+  if (!descriptorRelativePath) {
+    return null;
+  }
+
+  const descriptorAbsolutePath = path.resolve(appRoot, descriptorRelativePath);
+  const descriptorSource = await readFileIfExists(descriptorAbsolutePath);
+  if (!descriptorSource) {
+    return null;
+  }
+
+  let descriptorModule = null;
+  try {
+    descriptorModule = await import(`${pathToFileURL(descriptorAbsolutePath).href}?t=${Date.now()}_${Math.random()}`);
+  } catch {
+    return null;
+  }
+
+  const descriptor = ensureObject(descriptorModule?.default);
+  if (Object.keys(descriptor).length < 1) {
+    return null;
+  }
+
+  const resolvedPackageId = String(descriptor.packageId || packageId || "").trim();
+  if (!resolvedPackageId) {
+    return null;
+  }
+
+  return Object.freeze({
+    packageId: resolvedPackageId,
+    descriptor
+  });
+}
+
+async function collectProviderSourceFiles(rootPath = "") {
+  const files = [];
+  const stack = [path.resolve(String(rootPath || ""))];
+
+  while (stack.length > 0) {
+    const currentPath = stack.pop();
+    let entries = [];
+    try {
+      entries = await readdir(currentPath, { withFileTypes: true });
+    } catch (error) {
+      const errorCode = String(error?.code || "").trim().toUpperCase();
+      if (READ_DIRECTORY_IGNORE_ERROR_CODES.has(errorCode)) {
+        continue;
+      }
+      throw error;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const extension = path.extname(entry.name).toLowerCase();
+      if (PROVIDER_SOURCE_EXTENSIONS.has(extension)) {
+        files.push(entryPath);
+      }
+    }
+  }
+
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
 function createListCommands(ctx = {}) {
   const {
     createCliError,
@@ -14,7 +139,9 @@ function createListCommands(ctx = {}) {
     loadPackageRegistry,
     loadBundleRegistry,
     loadAppLocalPackageRegistry,
+    resolveInstalledNodeModulePackageEntry,
     discoverShellOutletTargetsFromApp,
+    normalizePlacementContributions,
     resolvePackageKind
   } = ctx;
 
@@ -51,6 +178,11 @@ function createListCommands(ctx = {}) {
     if (mode === "placements") {
       throw createCliError('list mode "placements" moved to a dedicated command: jskit list-placements.');
     }
+    if (mode === "placement-component-tokens") {
+      throw createCliError(
+        'list mode "placement-component-tokens" moved to a dedicated command: jskit list-link-items.'
+      );
+    }
 
     if (!shouldListBundles && !shouldListPackages && !shouldListGenerators) {
       throw createCliError(`Unknown list mode: ${mode}`, { showUsage: true });
@@ -283,9 +415,144 @@ function createListCommands(ctx = {}) {
     return 0;
   }
 
+  async function commandListLinkItems({ options, cwd, stdout }) {
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const tokenPrefixFilter = String(options?.inlineOptions?.prefix || "").trim();
+    const includeAllClientContainerTokens = options?.all === true;
+    const onlyLinkItemTokens = !includeAllClientContainerTokens;
+    const { lock } = await loadLockFile(appRoot);
+    const packageRegistry = await loadPackageRegistry();
+    const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+    const installedPackageEntries = ensureObject(lock.installedPackages);
+    const installedPackageIds = sortStrings(Object.keys(installedPackageEntries));
+
+    const packageEntryById = new Map();
+    for (const [packageId, packageEntry] of packageRegistry.entries()) {
+      packageEntryById.set(packageId, packageEntry);
+    }
+    for (const [packageId, packageEntry] of appLocalRegistry.entries()) {
+      packageEntryById.set(packageId, packageEntry);
+    }
+    for (const packageId of installedPackageIds) {
+      if (packageEntryById.has(packageId)) {
+        continue;
+      }
+      const installedPackageEntry = ensureObject(installedPackageEntries[packageId]);
+      const descriptorFromLockEntry = await resolveDescriptorFromLockEntry({
+        appRoot,
+        packageId,
+        installedPackageEntry
+      });
+      if (descriptorFromLockEntry) {
+        packageEntryById.set(packageId, descriptorFromLockEntry);
+        packageEntryById.set(descriptorFromLockEntry.packageId, descriptorFromLockEntry);
+        continue;
+      }
+      if (typeof resolveInstalledNodeModulePackageEntry !== "function") {
+        continue;
+      }
+      const resolvedNodeModuleEntry = await resolveInstalledNodeModulePackageEntry({
+        appRoot,
+        packageId
+      });
+      if (resolvedNodeModuleEntry) {
+        packageEntryById.set(resolvedNodeModuleEntry.packageId, resolvedNodeModuleEntry);
+      }
+    }
+
+    const tokenSourceByToken = new Map();
+    for (const packageId of installedPackageIds) {
+      const packageEntry = packageEntryById.get(packageId) || null;
+      if (!packageEntry) {
+        continue;
+      }
+      const descriptor = ensureObject(packageEntry.descriptor);
+      const metadata = ensureObject(descriptor.metadata);
+      const ui = ensureObject(metadata.ui);
+      const placements = ensureObject(ui.placements);
+      const contributions = normalizePlacementContributions(placements.contributions);
+      for (const contribution of contributions) {
+        const componentToken = String(contribution.componentToken || "").trim();
+        if (!componentToken) {
+          continue;
+        }
+        const contributionSource = String(contribution.source || "").trim();
+        const sourceLabel = contributionSource
+          ? `package:${packageId}:${contributionSource}`
+          : `package:${packageId}:metadata.ui.placements.contributions`;
+        appendTokenSource(tokenSourceByToken, componentToken, sourceLabel);
+      }
+
+      if (includeAllClientContainerTokens) {
+        const apiSummary = ensureObject(metadata.apiSummary);
+        const containerTokens = ensureObject(apiSummary.containerTokens);
+        const clientTokens = ensureArray(containerTokens.client).map((value) => String(value || "").trim()).filter(Boolean);
+        for (const clientToken of clientTokens) {
+          appendTokenSource(tokenSourceByToken, clientToken, `package:${packageId}:metadata.apiSummary.containerTokens.client`);
+        }
+      }
+    }
+
+    const placementSourcePath = path.join(appRoot, PLACEMENT_FILE_RELATIVE_PATH);
+    const placementSource = await readFileIfExists(placementSourcePath);
+    for (const token of collectTokenMatches(placementSource, COMPONENT_TOKEN_PATTERN)) {
+      appendTokenSource(tokenSourceByToken, token, `app:${normalizeRelativePosixPath(PLACEMENT_FILE_RELATIVE_PATH)}`);
+    }
+
+    const providersRootPath = path.join(appRoot, MAIN_CLIENT_PROVIDERS_RELATIVE_PATH);
+    const providerSourceFiles = await collectProviderSourceFiles(providersRootPath);
+    for (const providerSourceFile of providerSourceFiles) {
+      const providerSource = await readFileIfExists(providerSourceFile);
+      if (!providerSource) {
+        continue;
+      }
+      const providerRelativePath = normalizeRelativePosixPath(path.relative(appRoot, providerSourceFile));
+      for (const token of collectTokenMatches(providerSource, REGISTER_MAIN_CLIENT_COMPONENT_PATTERN)) {
+        appendTokenSource(tokenSourceByToken, token, `app:${providerRelativePath}`);
+      }
+    }
+
+    const tokens = sortStrings([...tokenSourceByToken.keys()])
+      .filter((token) => !tokenPrefixFilter || token.startsWith(tokenPrefixFilter))
+      .filter((token) => !onlyLinkItemTokens || isLinkItemToken(token))
+      .map((token) => ({
+        token,
+        sources: sortStrings([...(tokenSourceByToken.get(token) || new Set())])
+      }));
+
+    if (options.json) {
+      stdout.write(`${JSON.stringify({ placementComponentTokens: tokens }, null, 2)}\n`);
+      return 0;
+    }
+
+    const color = createColorFormatter(stdout);
+    const lines = [color.heading("Available placement component tokens:")];
+    lines.push(
+      color.dim(
+        includeAllClientContainerTokens
+          ? "Showing all discovered tokens (--all), including non-link-item/container/runtime tokens."
+          : 'Showing link-item tokens only (token must end with "link-item"). Tip: use --all for full token list.'
+      )
+    );
+    if (tokens.length < 1) {
+      lines.push("- none");
+    } else {
+      for (const entry of tokens) {
+        const token = String(entry.token || "").trim();
+        const sources = ensureArray(entry.sources).map((value) => String(value || "").trim()).filter(Boolean);
+        const sourceLabel = sources.length > 0 ? ` ${color.dim(`[${sources.join(", ")}]`)}` : "";
+        lines.push(`- ${color.item(token)}${sourceLabel}`);
+      }
+    }
+
+    stdout.write(`${lines.join("\n")}\n`);
+    return 0;
+  }
+
   return {
     commandList,
-    commandListPlacements
+    commandListPlacements,
+    commandListLinkItems
   };
 }
 

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

@@ -3,6 +3,16 @@ import {
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  isHelpToken,
+  renderAddCatalogHelp,
+  renderAddPackageHelp,
+  renderAddBundleHelp
+} from "./discoverabilityHelp.js";
+import {
+  TAB_LINK_COMPONENT_TOKEN,
+  ensureLocalMainTabLinkItemProvisioning
+} from "./tabLinkItemProvisioning.js";
 
 async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
@@ -34,6 +44,94 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
   const invocationMode = options?.commandMode === "generate" ? "generate" : "add";
   const targetType = String(positional[0] || "").trim();
   const targetId = String(positional[1] || "").trim();
+  const thirdToken = String(positional[2] || "").trim();
+
+  if (invocationMode === "add" && !targetType) {
+    const packageRegistry = await loadPackageRegistry();
+    const bundleRegistry = await loadBundleRegistry();
+    renderAddCatalogHelp({
+      io,
+      packageRegistry,
+      bundleRegistry,
+      resolvePackageKind,
+      json: options.json
+    });
+    return 0;
+  }
+
+  const addShorthandHelpTargetId =
+    invocationMode === "add" &&
+    targetType &&
+    targetType !== "bundle" &&
+    targetType !== "package" &&
+    isHelpToken(targetId) &&
+    !thirdToken
+      ? targetType
+      : "";
+
+  const addPackageHelpTargetId =
+    invocationMode === "add" && targetType === "package" && targetId && isHelpToken(thirdToken)
+      ? targetId
+      : addShorthandHelpTargetId;
+  const addBundleHelpTargetId =
+    invocationMode === "add" && targetType === "bundle" && targetId && isHelpToken(thirdToken)
+      ? targetId
+      : "";
+
+  if (addPackageHelpTargetId) {
+    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: addPackageHelpTargetId
+    });
+    if (!resolvedPackageId) {
+      throw createCliError(
+        `Unknown package: ${addPackageHelpTargetId}. Install an external module first (npm install ${addPackageHelpTargetId}) if you want to adopt it into lock.`
+      );
+    }
+
+    await hydratePackageRegistryFromInstalledNodeModules({
+      appRoot,
+      packageRegistry: combinedPackageRegistry,
+      seedPackageIds: [resolvedPackageId]
+    });
+    const packageEntry = combinedPackageRegistry.get(resolvedPackageId);
+    if (!packageEntry) {
+      throw createCliError(`Unknown package: ${addPackageHelpTargetId}`);
+    }
+    const packageKind = resolvePackageKind(packageEntry);
+    if (packageKind === "generator") {
+      throw createCliError(
+        `Package ${resolvedPackageId} is a generator. Use: jskit generate ${resolvedPackageId}`
+      );
+    }
+    renderAddPackageHelp({
+      io,
+      packageEntry,
+      packageIdInput: addPackageHelpTargetId,
+      json: options.json
+    });
+    return 0;
+  }
+
+  if (addBundleHelpTargetId) {
+    const bundleRegistry = await loadBundleRegistry();
+    const bundle = bundleRegistry.get(addBundleHelpTargetId);
+    if (!bundle) {
+      throw createCliError(`Unknown bundle: ${addBundleHelpTargetId}`);
+    }
+    renderAddBundleHelp({
+      io,
+      bundleId: addBundleHelpTargetId,
+      bundle,
+      json: options.json
+    });
+    return 0;
+  }
 
   if (!targetType || !targetId) {
     if (invocationMode === "generate") {
@@ -222,6 +320,21 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   const finalResolvedPackageIds = sortStrings([...resolvedPackageIds, ...adoptedPackageIds]);
 
+  const requestedPlacementComponentToken = String(options?.inlineOptions?.["placement-component-token"] || "").trim();
+  if (
+    invocationMode === "generate" &&
+    targetType === "package" &&
+    resolvedTargetPackageId === "@jskit-ai/crud-ui-generator" &&
+    requestedPlacementComponentToken === TAB_LINK_COMPONENT_TOKEN
+  ) {
+    await ensureLocalMainTabLinkItemProvisioning({
+      appRoot,
+      createCliError,
+      dryRun: options.dryRun === true,
+      touchedFiles
+    });
+  }
+
   const touchedFileList = sortStrings([...touchedFiles]);
   const successLabel = invocationMode === "generate"
     ? "Generated with"