@jskit-ai/jskit-cli 0.2.30 → 0.2.31

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

@@ -1,3 +1,67 @@
+import {
+  isHelpToken,
+  renderGenerateCatalogHelp,
+  renderGeneratePackageHelp,
+  renderGenerateSubcommandHelp
+} from "./discoverabilityHelp.js";
+
+function resolveGeneratorSubcommandDefinitionMetadata(packageEntry = {}, subcommandName = "") {
+  const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
+    ? packageEntry.descriptor
+    : {};
+  const metadata = descriptor?.metadata && typeof descriptor.metadata === "object"
+    ? descriptor.metadata
+    : {};
+  const subcommands = metadata?.generatorSubcommands && typeof metadata.generatorSubcommands === "object"
+    ? metadata.generatorSubcommands
+    : descriptor?.generatorSubcommands && typeof descriptor.generatorSubcommands === "object"
+      ? descriptor.generatorSubcommands
+      : {};
+  const normalizedSubcommandName = String(subcommandName || "").trim();
+  if (!normalizedSubcommandName) {
+    return {};
+  }
+  const definition = subcommands[normalizedSubcommandName];
+  return definition && typeof definition === "object" ? definition : {};
+}
+
+function resolveSubcommandRequiresInput(packageEntry = {}, subcommandName = "") {
+  const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
+    ? packageEntry.descriptor
+    : {};
+  const optionSchemas = descriptor?.options && typeof descriptor.options === "object"
+    ? descriptor.options
+    : {};
+  const subcommandDefinition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName);
+  const positionalArgs = Array.isArray(subcommandDefinition?.positionalArgs)
+    ? subcommandDefinition.positionalArgs
+    : [];
+  if (positionalArgs.length > 0) {
+    return true;
+  }
+  const requiredOptionNames = Array.isArray(subcommandDefinition?.requiredOptionNames)
+    ? subcommandDefinition.requiredOptionNames
+    : [];
+  if (requiredOptionNames.some((optionName) => String(optionName || "").trim().length > 0)) {
+    return true;
+  }
+
+  const optionNames = Array.isArray(subcommandDefinition?.optionNames) && subcommandDefinition.optionNames.length > 0
+    ? subcommandDefinition.optionNames
+    : Object.keys(optionSchemas);
+  for (const optionName of optionNames) {
+    const normalizedOptionName = String(optionName || "").trim();
+    if (!normalizedOptionName) {
+      continue;
+    }
+    const schema = optionSchemas[normalizedOptionName];
+    if (schema && typeof schema === "object" && schema.required === true) {
+      return true;
+    }
+  }
+  return false;
+}
+
 async function runPackageGenerateCommand(
   ctx = {},
   { positional, options, cwd, io },
@@ -28,13 +92,8 @@ async function runPackageGenerateCommand(
   const targetId = firstToken === "package" ? secondToken : firstToken;
   const subcommandName = firstToken === "package" ? thirdToken : secondToken;
   const subcommandArgs = firstToken === "package" ? positional.slice(3) : positional.slice(2);
-  if (!targetId) {
-    throw createCliError("generate requires a package id (generate <packageId>).", {
-      showUsage: true
-    });
-  }
 
-  if (subcommandName) {
+  async function resolveGeneratorPackageEntry(packageIdInput = "") {
     const appRoot = await resolveAppRootFromCwd(cwd);
     const packageRegistry = await loadPackageRegistry();
     const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
@@ -43,11 +102,11 @@ async function runPackageGenerateCommand(
     const resolvedPackageId = await resolvePackageIdFromRegistryOrNodeModules({
       appRoot,
       packageRegistry: combinedPackageRegistry,
-      packageIdInput: targetId
+      packageIdInput
     });
     if (!resolvedPackageId) {
       throw createCliError(
-        `Unknown package: ${targetId}. Install it first (npm install ${targetId}) if you want to run generator subcommands from node_modules.`
+        `Unknown package: ${packageIdInput}. Install it first (npm install ${packageIdInput}) if you want to run generator subcommands from node_modules.`
       );
     }
 
@@ -58,15 +117,97 @@ async function runPackageGenerateCommand(
     });
     const packageEntry = combinedPackageRegistry.get(resolvedPackageId);
     if (!packageEntry) {
-      throw createCliError(`Unknown package: ${targetId}`);
+      throw createCliError(`Unknown package: ${packageIdInput}`);
     }
-
     if (resolvePackageKind(packageEntry) !== "generator") {
       throw createCliError(
         `Package ${resolvedPackageId} is a runtime package. Use: jskit add package ${resolvedPackageId}`
       );
     }
 
+    return Object.freeze({
+      appRoot,
+      packageEntry,
+      resolvedPackageId
+    });
+  }
+
+  if (!targetId) {
+    const packageRegistry = await loadPackageRegistry();
+    renderGenerateCatalogHelp({
+      io,
+      packageRegistry,
+      resolvePackageKind,
+      json: options.json
+    });
+    return 0;
+  }
+
+  if (isHelpToken(subcommandName)) {
+    const helpSubcommandName = String(subcommandArgs[0] || "").trim();
+    if (subcommandArgs.length > 1) {
+      throw createCliError("generate help accepts at most one subcommand name.");
+    }
+    const { packageEntry } = await resolveGeneratorPackageEntry(targetId);
+    if (helpSubcommandName) {
+      const rendered = renderGenerateSubcommandHelp({
+        io,
+        packageEntry,
+        packageIdInput: targetId,
+        subcommandName: helpSubcommandName,
+        json: options.json
+      });
+      if (!rendered) {
+        throw createCliError(
+          `Unknown generator subcommand "${helpSubcommandName}" for ${String(packageEntry?.packageId || targetId)}.`
+        );
+      }
+      return 0;
+    }
+
+    renderGeneratePackageHelp({
+      io,
+      packageEntry,
+      packageIdInput: targetId,
+      json: options.json
+    });
+    return 0;
+  }
+
+  if (subcommandName) {
+    const {
+      appRoot,
+      packageEntry,
+      resolvedPackageId
+    } = await resolveGeneratorPackageEntry(targetId);
+    const hasInlineOptions = Object.keys(options?.inlineOptions || {}).length > 0;
+    const hasSubcommandArgs = subcommandArgs.length > 0;
+    if (!hasInlineOptions && !hasSubcommandArgs && resolveSubcommandRequiresInput(packageEntry, subcommandName)) {
+      const rendered = renderGenerateSubcommandHelp({
+        io,
+        packageEntry,
+        packageIdInput: targetId,
+        subcommandName,
+        json: options.json
+      });
+      if (rendered) {
+        return 0;
+      }
+    }
+    if (subcommandArgs.length === 1 && isHelpToken(subcommandArgs[0])) {
+      const rendered = renderGenerateSubcommandHelp({
+        io,
+        packageEntry,
+        packageIdInput: targetId,
+        subcommandName,
+        json: options.json
+      });
+      if (!rendered) {
+        throw createCliError(`Unknown generator subcommand "${subcommandName}" for ${resolvedPackageId}.`);
+      }
+      return 0;
+    }
+
     const normalizedSubcommandName = String(subcommandName || "").trim().toLowerCase();
     const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
     if (

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

@@ -0,0 +1,326 @@
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+const MAIN_CLIENT_PROVIDER_FILE = "packages/main/src/client/providers/MainClientProvider.js";
+const TAB_LINK_COMPONENT_FILE = "src/components/TabLinkItem.vue";
+const TAB_LINK_COMPONENT_NAME = "TabLinkItem";
+const TAB_LINK_COMPONENT_TOKEN = "local.main.ui.tab-link-item";
+
+function toPosixPath(value = "") {
+  return String(value || "").replaceAll("\\", "/");
+}
+
+function ensureTrailingNewline(value = "") {
+  const source = String(value || "");
+  return source.endsWith("\n") ? source : `${source}\n`;
+}
+
+function insertImportIfMissing(source = "", importLine = "") {
+  const normalizedImportLine = String(importLine || "").trim();
+  const sourceText = String(source || "");
+  if (!normalizedImportLine || sourceText.includes(normalizedImportLine)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const importPattern = /^import\s+[^;]+;\s*$/gm;
+  let match = null;
+  let insertionIndex = 0;
+  while ((match = importPattern.exec(sourceText)) !== null) {
+    insertionIndex = match.index + match[0].length;
+  }
+
+  if (insertionIndex > 0) {
+    return {
+      changed: true,
+      content: `${sourceText.slice(0, insertionIndex)}\n${normalizedImportLine}${sourceText.slice(insertionIndex)}`
+    };
+  }
+
+  return {
+    changed: true,
+    content: `${normalizedImportLine}\n${sourceText}`
+  };
+}
+
+function insertBeforeClassDeclaration(source = "", line = "", { className = "", contextFile = "" } = {}) {
+  const normalizedLine = String(line || "").trim();
+  const sourceText = String(source || "");
+  if (!normalizedLine || sourceText.includes(normalizedLine)) {
+    return {
+      changed: false,
+      content: sourceText
+    };
+  }
+
+  const classPattern = new RegExp(`^class\\s+${String(className || "").trim()}\\b`, "m");
+  const classMatch = classPattern.exec(sourceText);
+  if (!classMatch) {
+    throw new Error(`crud-ui-generator could not find ${className} class declaration in ${contextFile || "target file"}.`);
+  }
+
+  return {
+    changed: true,
+    content: `${sourceText.slice(0, classMatch.index)}${normalizedLine}\n\n${sourceText.slice(classMatch.index)}`
+  };
+}
+
+function renderTabLinkItemSource() {
+  return `<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { usePaths } from "@jskit-ai/users-web/client/composables/usePaths";
+import { useWorkspaceRouteContext } from "@jskit-ai/users-web/client/composables/useWorkspaceRouteContext";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  workspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  nonWorkspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  }
+});
+
+const route = useRoute();
+const paths = usePaths();
+const { currentSurfaceId, workspaceSlugFromRoute } = useWorkspaceRouteContext();
+
+function normalizePathname(pathname = "") {
+  const source = String(pathname || "").trim();
+  if (!source) {
+    return "";
+  }
+
+  const queryIndex = source.indexOf("?");
+  const hashIndex = source.indexOf("#");
+  const cutoff =
+    queryIndex < 0
+      ? hashIndex
+      : hashIndex < 0
+        ? queryIndex
+        : Math.min(queryIndex, hashIndex);
+  return cutoff < 0 ? source : source.slice(0, cutoff);
+}
+
+function interpolateBracketParams(pathTemplate = "", params = {}) {
+  const source = String(pathTemplate || "").trim();
+  if (!source) {
+    return "";
+  }
+
+  return source.replace(/\\[([^\\]]+)\\]/g, (_match, rawKey) => {
+    const key = String(rawKey || "").trim();
+    if (!key) {
+      return "";
+    }
+    const value = params?.[key];
+    return value == null ? "[" + key + "]" : encodeURIComponent(String(value));
+  });
+}
+
+const targetSurfaceId = computed(() => {
+  const explicitSurface = String(props.surface || "").trim().toLowerCase();
+  if (explicitSurface && explicitSurface !== "*") {
+    return explicitSurface;
+  }
+  return String(currentSurfaceId.value || paths.currentSurfaceId.value || "").trim().toLowerCase();
+});
+
+const resolvedTo = computed(() => {
+  const explicitTo = String(props.to || "").trim();
+  if (explicitTo) {
+    if (explicitTo.startsWith("./")) {
+      const workspaceSlug = String(workspaceSlugFromRoute.value || "").trim();
+      const suffixTemplate = workspaceSlug ? props.workspaceSuffix : props.nonWorkspaceSuffix;
+      const interpolatedSuffix = interpolateBracketParams(suffixTemplate, route.params || {});
+      if (interpolatedSuffix && !interpolatedSuffix.includes("[")) {
+        return paths.page(interpolatedSuffix, {
+          surface: targetSurfaceId.value,
+          mode: "auto"
+        });
+      }
+    }
+    return explicitTo;
+  }
+
+  const workspaceSlug = String(workspaceSlugFromRoute.value || "").trim();
+  const suffix = workspaceSlug ? props.workspaceSuffix : props.nonWorkspaceSuffix;
+  const normalizedSuffix = String(suffix || "/").trim() || "/";
+  return paths.page(normalizedSuffix, {
+    surface: targetSurfaceId.value,
+    mode: "auto"
+  });
+});
+
+const isActive = computed(() => {
+  const targetPath = normalizePathname(resolvedTo.value);
+  const currentPath = normalizePathname(route.fullPath || route.path || "");
+  if (!targetPath || !currentPath) {
+    return false;
+  }
+  return currentPath === targetPath || currentPath.startsWith(\`\${targetPath}/\`);
+});
+</script>
+
+<template>
+  <v-btn
+    class="tab-link-item"
+    variant="text"
+    size="small"
+    :to="resolvedTo"
+    :active="isActive"
+    :disabled="disabled"
+    color="primary"
+  >
+    {{ label || "Tab" }}
+  </v-btn>
+</template>
+
+<style scoped>
+.tab-link-item {
+  text-transform: none;
+  font-weight: 600;
+  border-radius: 999px;
+}
+</style>
+`;
+}
+
+async function readUtf8FileIfExists(absolutePath = "") {
+  try {
+    return await readFile(absolutePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+async function ensureTabLinkItemComponentFile({ appRoot = "", dryRun = false, touchedFiles = new Set() } = {}) {
+  const componentRelativePath = TAB_LINK_COMPONENT_FILE;
+  const componentAbsolutePath = path.join(appRoot, componentRelativePath);
+  const existingComponentSource = await readUtf8FileIfExists(componentAbsolutePath);
+  if (existingComponentSource) {
+    return;
+  }
+
+  if (dryRun !== true) {
+    await mkdir(path.dirname(componentAbsolutePath), { recursive: true });
+    await writeFile(componentAbsolutePath, renderTabLinkItemSource(), "utf8");
+  }
+  touchedFiles.add(toPosixPath(componentRelativePath));
+}
+
+function hasTabLinkItemTokenRegistration(providerSource = "") {
+  const tokenPattern = TAB_LINK_COMPONENT_TOKEN.replaceAll(".", "\\.");
+  const pattern = new RegExp(`registerMainClientComponent\\(\\s*"${tokenPattern}"\\s*,`, "m");
+  return pattern.test(String(providerSource || ""));
+}
+
+async function loadMainClientProviderSource({ appRoot = "", createCliError } = {}) {
+  const providerAbsolutePath = path.join(appRoot, MAIN_CLIENT_PROVIDER_FILE);
+  let providerSource = "";
+  try {
+    providerSource = await readFile(providerAbsolutePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      throw createCliError(
+        `crud-ui-generator placement component token "${TAB_LINK_COMPONENT_TOKEN}" requires ${MAIN_CLIENT_PROVIDER_FILE}.`
+      );
+    }
+    throw error;
+  }
+
+  if (!/\bregisterMainClientComponent\s*\(/.test(providerSource)) {
+    throw createCliError(
+      `crud-ui-generator placement component token "${TAB_LINK_COMPONENT_TOKEN}" could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
+    );
+  }
+
+  return providerSource;
+}
+
+async function ensureTabLinkItemProviderRegistration({
+  appRoot = "",
+  createCliError,
+  dryRun = false,
+  touchedFiles = new Set()
+} = {}) {
+  const providerRelativePath = MAIN_CLIENT_PROVIDER_FILE;
+  const providerAbsolutePath = path.join(appRoot, providerRelativePath);
+  const providerSource = await loadMainClientProviderSource({
+    appRoot,
+    createCliError
+  });
+  if (hasTabLinkItemTokenRegistration(providerSource)) {
+    return false;
+  }
+
+  const importLine = `import ${TAB_LINK_COMPONENT_NAME} from "/${toPosixPath(TAB_LINK_COMPONENT_FILE)}";`;
+  const registerLine = `registerMainClientComponent("${TAB_LINK_COMPONENT_TOKEN}", () => ${TAB_LINK_COMPONENT_NAME});`;
+
+  const importApplied = insertImportIfMissing(providerSource, importLine);
+  const registerApplied = insertBeforeClassDeclaration(importApplied.content, registerLine, {
+    className: "MainClientProvider",
+    contextFile: MAIN_CLIENT_PROVIDER_FILE
+  });
+
+  if (!importApplied.changed && !registerApplied.changed) {
+    return false;
+  }
+
+  if (dryRun !== true) {
+    await writeFile(providerAbsolutePath, ensureTrailingNewline(registerApplied.content), "utf8");
+  }
+  touchedFiles.add(toPosixPath(providerRelativePath));
+  return true;
+}
+
+async function ensureLocalMainTabLinkItemProvisioning({
+  appRoot = "",
+  createCliError,
+  dryRun = false,
+  touchedFiles = new Set()
+} = {}) {
+  const providerSource = await loadMainClientProviderSource({
+    appRoot,
+    createCliError
+  });
+  if (hasTabLinkItemTokenRegistration(providerSource)) {
+    return;
+  }
+
+  await ensureTabLinkItemComponentFile({ appRoot, dryRun, touchedFiles });
+  await ensureTabLinkItemProviderRegistration({
+    appRoot,
+    createCliError,
+    dryRun,
+    touchedFiles
+  });
+}
+
+export {
+  TAB_LINK_COMPONENT_TOKEN,
+  ensureLocalMainTabLinkItemProvisioning
+};

package/src/server/core/commandCatalog.js

@@ -4,6 +4,7 @@ const KNOWN_COMMAND_IDS = Object.freeze([
   "generate",
   "list",
   "list-placements",
+  "list-link-items",
   "show",
   "view",
   "migrations",
@@ -21,7 +22,9 @@ const COMMAND_ALIASES = Object.freeze({
   view: "show",
   ls: "list",
   gen: "generate",
-  lp: "list-placements"
+  lp: "list-placements",
+  lpct: "list-link-items",
+  "list-placement-component-tokens": "list-link-items"
 });
 
 function resolveCommandAlias(rawCommand) {

package/src/server/core/createCommandHandlers.js

@@ -11,7 +11,7 @@ function createCommandHandlers(deps = {}) {
     ...shared
   };
 
-  const { commandList, commandListPlacements } = createListCommands(commandContext);
+  const { commandList, commandListPlacements, commandListLinkItems } = createListCommands(commandContext);
   const { commandShow } = createShowCommand(commandContext);
   const {
     commandCreate,
@@ -27,6 +27,7 @@ function createCommandHandlers(deps = {}) {
   return {
     commandList,
     commandListPlacements,
+    commandListLinkItems,
     commandShow,
     commandCreate,
     commandAdd,

package/src/server/core/dispatchCli.js

@@ -58,6 +58,9 @@ function createRunCli({
       if (command === "list-placements") {
         return await commandHandlers.commandListPlacements({ options, cwd, stdout });
       }
+      if (command === "list-link-items") {
+        return await commandHandlers.commandListLinkItems({ options, cwd, stdout });
+      }
       if (command === "show") {
         return await commandHandlers.commandShow({ positional, options, stdout });
       }

package/src/server/core/usageHelp.js

@@ -21,6 +21,10 @@ const COMMAND_OVERVIEW = Object.freeze([
     command: "list-placements",
     summary: "List discovered UI placement targets."
   }),
+  Object.freeze({
+    command: "list-link-items",
+    summary: "List available placement link-item component tokens."
+  }),
   Object.freeze({
     command: "show",
     summary: "Show detailed metadata for a bundle or package."
@@ -84,6 +88,7 @@ const COMMAND_HELP = Object.freeze({
     defaults: Object.freeze([
       "No npm install runs unless --run-npm-install is passed.",
       "Short ids resolve to @jskit-ai/<id> when available.",
+      "Running without args lists bundles and runtime packages.",
       "Existing matching version is skipped unless options force reapply."
     ]),
     fullUse: "jskit add <package|bundle> <id> [--<option> <value>...] [--dry-run] [--run-npm-install] [--json] [--verbose]"
@@ -98,7 +103,7 @@ const COMMAND_HELP = Object.freeze({
       }),
       Object.freeze({
         name: "[subcommand]",
-        description: "Optional generator subcommand (for example: add-field)."
+        description: "Optional generator subcommand (for example: scaffold or scaffold-field)."
       }),
       Object.freeze({
         name: "[subcommand args...]",
@@ -108,7 +113,9 @@ const COMMAND_HELP = Object.freeze({
     defaults: Object.freeze([
       "No npm install runs unless --run-npm-install is passed.",
       "Short ids resolve to @jskit-ai/<id> when available.",
-      "If no subcommand is provided, the generator primary command runs."
+      "Running without args lists available generators.",
+      "If no subcommand is provided, the generator primary command runs.",
+      "Use jskit generate <generatorId> <subcommand> help for subcommand-specific usage."
     ]),
     fullUse: "jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...] [--dry-run] [--run-npm-install] [--json] [--verbose]"
   }),
@@ -133,12 +140,34 @@ const COMMAND_HELP = Object.freeze({
     minimalUse: "jskit list-placements",
     parameters: Object.freeze([]),
     defaults: Object.freeze([
-      "Discovers ShellOutlet targets from app src/ Vue files.",
+      "Discovers placement outlets from app Vue ShellOutlet tags and route meta.",
       "Includes placement outlets contributed by installed package metadata.",
       "Shows plain text by default; use --json for structured output."
     ]),
     fullUse: "jskit list-placements [--json]"
   }),
+  "list-link-items": Object.freeze({
+    title: "list-link-items",
+    minimalUse: "jskit list-link-items",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "[--prefix <value>]",
+        description: "Optional token prefix filter (example: local.main. or users.web.shell.)."
+      }),
+      Object.freeze({
+        name: "[--all]",
+        description: "Include all discovered tokens (including non-link-item and client container/runtime tokens)."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Default output shows link-item tokens only (token names ending with link-item).",
+      "Default includes app and installed-package placement-linked token sources.",
+      "Use --prefix to narrow quickly (recommended: --prefix local.main.).",
+      "Use --all when you want the full discovered token set.",
+      "Shows plain text by default; use --json for structured output."
+    ]),
+    fullUse: "jskit list-link-items [--prefix <value>] [--all] [--json]"
+  }),
   show: Object.freeze({
     title: "show",
     minimalUse: "jskit show <id>",
@@ -261,8 +290,6 @@ const COMMAND_HELP = Object.freeze({
 
 const BARE_COMMAND_HELP = new Set([
   "create",
-  "add",
-  "generate",
   "show",
   "migrations",
   "position",

package/src/server/shared/optionInterpolation.js

@@ -197,6 +197,12 @@ function normalizePathValue(value) {
         return normalizedSegment;
       }
 
+      const routeGroupMatch = /^\(([^()]+)\)$/.exec(normalizedSegment);
+      if (routeGroupMatch) {
+        const routeGroupName = wordsToKebab(splitTextIntoWords(routeGroupMatch[1]));
+        return routeGroupName ? `(${routeGroupName})` : "";
+      }
+
       return wordsToKebab(splitTextIntoWords(normalizedSegment));
     })
     .filter(Boolean)