@jskit-ai/jskit-cli 0.2.67 → 0.2.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.66",
-    "@jskit-ai/kernel": "0.1.58",
-    "@jskit-ai/shell-web": "0.1.57"
+    "@jskit-ai/jskit-catalog": "0.1.67",
+    "@jskit-ai/kernel": "0.1.59",
+    "@jskit-ai/shell-web": "0.1.58"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/mutationWhen.js

@@ -69,8 +69,9 @@ function normalizeMutationWhen(value) {
   const notContains = String(source.notContains || "").trim();
   const includes = ensureArray(source.in).map((entry) => String(entry || "").trim()).filter(Boolean);
   const excludes = ensureArray(source.notIn).map((entry) => String(entry || "").trim()).filter(Boolean);
+  const hasText = typeof source.hasText === "boolean" ? source.hasText : null;
 
-  if (!option && !config && allConditions.length < 1 && anyConditions.length < 1) {
+  if (!option && !config && allConditions.length < 1 && anyConditions.length < 1 && hasText == null) {
     return null;
   }
 
@@ -84,7 +85,8 @@ function normalizeMutationWhen(value) {
     contains,
     notContains,
     includes,
-    excludes
+    excludes,
+    hasText
   };
 }
 
@@ -270,6 +272,12 @@ function shouldApplyMutationWhen(
   const notContains = normalizeWhenComparisonValue(when.notContains);
   const includes = ensureArray(when.includes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
   const excludes = ensureArray(when.excludes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
+  const hasText = typeof when.hasText === "boolean" ? when.hasText : null;
+  const sourceText = normalizeWhenSourceValue(sourceValue);
+
+  if (hasText != null && (sourceText.length > 0) !== hasText) {
+    return false;
+  }
 
   if (equals && optionValue !== equals) {
     return false;

package/src/server/commandHandlers/appCommands/linkLocalPackages.js

@@ -60,6 +60,17 @@ async function verifySymlinkTarget(targetPath = "", sourceDir = "", {
   }
 }
 
+async function replaceWithSymlink(targetPath = "", sourceDir = "", {
+  packageName = ""
+} = {}) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await rm(targetPath, { recursive: true, force: true });
+  await symlink(sourceDir, targetPath, resolveSymlinkType());
+  await verifySymlinkTarget(targetPath, sourceDir, {
+    packageName
+  });
+}
+
 async function maybeLinkCompanionPackages({
   appRoot = "",
   repoRoot = "",
@@ -105,15 +116,19 @@ async function maybeLinkCompanionPackages({
       );
     }
 
-    const targetPath = path.join(appRoot, "node_modules", companion.packageName);
-    await mkdir(path.dirname(targetPath), { recursive: true });
-    await rm(targetPath, { recursive: true, force: true });
-    await symlink(sourceDir, targetPath, resolveSymlinkType());
-    await verifySymlinkTarget(targetPath, sourceDir, {
+    const appTargetPath = path.join(appRoot, "node_modules", companion.packageName);
+    await replaceWithSymlink(appTargetPath, sourceDir, {
       packageName: companion.packageName
     });
     stdout.write(`[link-local] linked ${companion.packageName} -> ${sourceDir}\n`);
     linkedCount += 1;
+
+    const repoTargetPath = path.join(repoRoot, "node_modules", companion.packageName);
+    await replaceWithSymlink(repoTargetPath, sourceDir, {
+      packageName: `${companion.packageName} (repo root)`
+    });
+    stdout.write(`[link-local] linked repo companion ${companion.packageName} -> ${sourceDir}\n`);
+    linkedCount += 1;
   }
 
   return linkedCount;
@@ -150,8 +165,9 @@ async function runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options
 
   for (const [packageDirName, sourceDir] of [...packageMap.entries()].sort((left, right) => left[0].localeCompare(right[0]))) {
     const targetPath = path.join(scopeDirectory, packageDirName);
-    await rm(targetPath, { recursive: true, force: true });
-    await symlink(sourceDir, targetPath, resolveSymlinkType());
+    await replaceWithSymlink(targetPath, sourceDir, {
+      packageName: `@jskit-ai/${packageDirName}`
+    });
     stdout.write(`[link-local] linked @jskit-ai/${packageDirName} -> ${sourceDir}\n`);
     await linkPackageBinEntries({
       appRoot,

package/src/server/commandHandlers/health.js

@@ -80,6 +80,34 @@ function createHealthCommands(ctx = {}) {
     "useCrudView",
     "useCrudAddEdit"
   ]);
+  const FEATURE_SERVER_SCAFFOLD_SHAPE = "feature-server-v1";
+  const FEATURE_SERVER_DEFAULT_LANE = "default";
+  const FEATURE_SERVER_JSON_REST_MODE = "json-rest";
+  const FEATURE_SERVER_PERSISTENT_MODES = new Set([
+    "json-rest",
+    "custom-knex"
+  ]);
+  const FEATURE_SERVER_COMPLEX_MARKER_RELATIVE_PATHS = Object.freeze([
+    "src/server/inputSchemas.js",
+    "src/server/actions.js",
+    "src/server/service.js",
+    "src/server/repository.js",
+    "src/server/registerRoutes.js"
+  ]);
+  const FEATURE_SERVER_PERSISTENCE_IMPORT_SOURCE_PATTERNS = Object.freeze([
+    /^@jskit-ai\/json-rest-api-core(?:\/|$)/u,
+    /^@jskit-ai\/database-runtime(?:\/|$)/u,
+    /^@jskit-ai\/database-runtime-mysql(?:\/|$)/u,
+    /^knex(?:\/|$)/u,
+    /^\.{1,2}\/.*repository(?:\.[A-Za-z0-9]+)?$/u
+  ]);
+  const MAIN_SERVER_BASELINE_RELATIVE_PATHS = new Set([
+    "src/server/index.js",
+    "src/server/MainServiceProvider.js",
+    "src/server/loadAppConfig.js"
+  ]);
+  const MAIN_SERVER_DOMAIN_FILE_PATTERN =
+    /^src\/server\/(?!(?:index|MainServiceProvider|loadAppConfig)\.[A-Za-z0-9]+$).+/u;
 
   function collectDescriptorContainerTokens({ packageId, side, values, issues }) {
     const declaredTokens = new Set();
@@ -490,6 +518,331 @@ function createHealthCommands(ctx = {}) {
     return bindings;
   }
 
+  function collectStaticImportSummaries(sourceText = "") {
+    const imports = [];
+    const importPattern = /^\s*import\s+[\s\S]*?\s+from\s+["']([^"']+)["'];?/gmu;
+
+    for (const match of sourceText.matchAll(importPattern)) {
+      const sourcePath = String(match[1] || "").trim();
+      if (!sourcePath) {
+        continue;
+      }
+      imports.push({
+        sourcePath,
+        lineNumber: resolveLineNumberFromIndex(sourceText, match.index || 0)
+      });
+    }
+
+    return imports;
+  }
+
+  function normalizeFeatureLaneMetadata(descriptor = {}) {
+    const metadata = ensureObject(ensureObject(ensureObject(descriptor).metadata).jskit);
+    return {
+      scaffoldShape: String(metadata.scaffoldShape || "").trim(),
+      scaffoldMode: String(metadata.scaffoldMode || "").trim(),
+      lane: String(metadata.lane || "").trim()
+    };
+  }
+
+  function isFeatureLanePersistenceImportSource(sourcePath = "") {
+    const normalizedSourcePath = String(sourcePath || "").trim();
+    if (!normalizedSourcePath) {
+      return false;
+    }
+    return FEATURE_SERVER_PERSISTENCE_IMPORT_SOURCE_PATTERNS.some((pattern) => pattern.test(normalizedSourcePath));
+  }
+
+  function findFirstPatternMatch(sourceText = "", patternEntries = []) {
+    let firstMatch = null;
+
+    for (const rawEntry of ensureArray(patternEntries)) {
+      const entry = ensureObject(rawEntry);
+      const pattern = entry.pattern instanceof RegExp ? entry.pattern : null;
+      if (!pattern) {
+        continue;
+      }
+      const match = pattern.exec(sourceText);
+      if (!match) {
+        continue;
+      }
+      if (!firstMatch || (match.index || 0) < firstMatch.index) {
+        firstMatch = {
+          index: match.index || 0,
+          label: String(entry.label || pattern.source).trim() || pattern.source
+        };
+      }
+    }
+
+    if (!firstMatch) {
+      return null;
+    }
+
+    return {
+      ...firstMatch,
+      lineNumber: resolveLineNumberFromIndex(sourceText, firstMatch.index)
+    };
+  }
+
+  function resolvePrimaryServerProviderPath(packageEntry) {
+    const rootDir = String(packageEntry?.rootDir || "").trim();
+    if (!rootDir) {
+      return "";
+    }
+
+    const providers = ensureArray(ensureObject(ensureObject(packageEntry?.descriptor).runtime).server?.providers);
+    for (const rawProvider of providers) {
+      const provider = ensureObject(rawProvider);
+      const entrypoint = String(provider.entrypoint || "").trim();
+      if (!entrypoint || entrypoint.includes("*")) {
+        continue;
+      }
+      return path.resolve(rootDir, entrypoint);
+    }
+
+    return "";
+  }
+
+  function resolvePackageDisplayPath(packageEntry) {
+    const relativeDir = String(packageEntry?.relativeDir || "").trim();
+    if (relativeDir) {
+      return relativeDir;
+    }
+    return String(packageEntry?.packageId || "").trim() || "package";
+  }
+
+  async function collectFeatureLaneRuleIssuesForPackage({ appRoot, packageEntry, issues }) {
+    const metadata = normalizeFeatureLaneMetadata(packageEntry?.descriptor);
+    if (metadata.scaffoldShape !== FEATURE_SERVER_SCAFFOLD_SHAPE) {
+      return;
+    }
+
+    const rootDir = String(packageEntry?.rootDir || "").trim();
+    if (!rootDir) {
+      return;
+    }
+
+    const packageDisplayPath = resolvePackageDisplayPath(packageEntry);
+    const isDefaultLane = metadata.lane === FEATURE_SERVER_DEFAULT_LANE;
+    const isPersistentMode = FEATURE_SERVER_PERSISTENT_MODES.has(metadata.scaffoldMode);
+
+    const servicePath = path.join(rootDir, "src", "server", "service.js");
+    if (isDefaultLane && (await fileExists(servicePath))) {
+      const serviceSource = await readFile(servicePath, "utf8");
+      const serviceRelativePath = normalizeRelativePath(appRoot, servicePath);
+      const knexMatch = findFirstPatternMatch(serviceSource, [
+        { pattern: /\bjskit\.database\.knex\b/u, label: "jskit.database.knex" },
+        { pattern: /\bcreateWithTransaction\s*\(/u, label: "createWithTransaction(...)" },
+        { pattern: /\bknex\b/u, label: "knex" }
+      ]);
+      if (knexMatch) {
+        issues.push(
+          `${serviceRelativePath}:${knexMatch.lineNumber}: [feature-lane:service-knex] default-lane service code must not use knex directly (${knexMatch.label}). Move persistence into src/server/repository.js or switch the package to an explicit weird-custom lane.`
+        );
+      }
+
+      const offendingServiceImports = collectStaticImportSummaries(serviceSource)
+        .filter((entry) => isFeatureLanePersistenceImportSource(entry.sourcePath));
+      if (offendingServiceImports.length > 0) {
+        const firstImport = offendingServiceImports[0];
+        const importSources = sortStrings(
+          [...new Set(offendingServiceImports.map((entry) => String(entry.sourcePath || "").trim()).filter(Boolean))]
+        );
+        issues.push(
+          `${serviceRelativePath}:${firstImport.lineNumber}: [feature-lane:service-persistence-import] default-lane service code must not import persistence helpers directly (${importSources.join(", ")}). Use the injected repository seam instead.`
+        );
+      }
+    }
+
+    const providerPath = resolvePrimaryServerProviderPath(packageEntry);
+    if (isDefaultLane && providerPath && (await fileExists(providerPath))) {
+      const providerSource = await readFile(providerPath, "utf8");
+      const providerRelativePath = normalizeRelativePath(appRoot, providerPath);
+      const providerPersistenceMatch = findFirstPatternMatch(providerSource, [
+        { pattern: /\bcreateJsonRestContext\s*\(/u, label: "createJsonRestContext(...)" },
+        { pattern: /\.resources\b/u, label: ".resources" },
+        { pattern: /\bjskit\.database\.knex\b/u, label: "jskit.database.knex" },
+        { pattern: /\bcreateWithTransaction\s*\(/u, label: "createWithTransaction(...)" },
+        { pattern: /\bknex\s*\./u, label: "knex." }
+      ]);
+      if (providerPersistenceMatch) {
+        issues.push(
+          `${providerRelativePath}:${providerPersistenceMatch.lineNumber}: [feature-lane:provider-persistence-direct] default-lane providers may wire repositories but must not perform persistence work directly (${providerPersistenceMatch.label}). Move json-rest/database calls into src/server/repository.js.`
+        );
+      }
+    }
+
+    const repositoryPath = path.join(rootDir, "src", "server", "repository.js");
+    if (isPersistentMode && !(await fileExists(repositoryPath))) {
+      issues.push(
+        `${packageDisplayPath}/src/server/repository.js: [feature-lane:repository-required] generated persistent feature packages require src/server/repository.js for scaffoldMode "${metadata.scaffoldMode}".`
+      );
+      return;
+    }
+
+    if (
+      isDefaultLane &&
+      metadata.scaffoldMode === FEATURE_SERVER_JSON_REST_MODE &&
+      (await fileExists(repositoryPath))
+    ) {
+      const repositorySource = await readFile(repositoryPath, "utf8");
+      const repositoryRelativePath = normalizeRelativePath(appRoot, repositoryPath);
+      const directDatabaseMatch = findFirstPatternMatch(repositorySource, [
+        { pattern: /\bjskit\.database\.knex\b/u, label: "jskit.database.knex" },
+        { pattern: /\bcreateWithTransaction\s*\(/u, label: "createWithTransaction(...)" },
+        { pattern: /\bknex\b/u, label: "knex" }
+      ]);
+      const usesJsonRest = /@jskit-ai\/json-rest-api-core|createJsonRestContext\s*\(|\.resources\b|json-rest-api/iu.test(repositorySource);
+      if (directDatabaseMatch || !usesJsonRest) {
+        const locationSuffix = directDatabaseMatch ? `:${directDatabaseMatch.lineNumber}` : "";
+        issues.push(
+          `${repositoryRelativePath}${locationSuffix}: [feature-lane:repository-default-path] default-lane persistent repositories must stay on internal json-rest-api. Use the injected json-rest-api seam or mark the package as an explicit weird-custom lane.`
+        );
+      }
+    }
+  }
+
+  async function collectMainPackageFeatureLaneWarnings({ appRoot, appLocalRegistry, warnings }) {
+    const mainPackageEntry = [...appLocalRegistry.values()].find((packageEntry) => {
+      const packageId = String(packageEntry?.packageId || "").trim();
+      const relativeDir = String(packageEntry?.relativeDir || "").trim();
+      return packageId === "@local/main" || relativeDir === "packages/main";
+    });
+    if (!mainPackageEntry) {
+      return;
+    }
+
+    const rootDir = String(mainPackageEntry.rootDir || "").trim();
+    if (!rootDir) {
+      return;
+    }
+
+    const reasons = [];
+    const serverFilePaths = [];
+    await collectAppSourceFiles(path.join(rootDir, "src", "server"), undefined, serverFilePaths);
+    const relativeServerFiles = sortStrings(serverFilePaths.map((absolutePath) => normalizeRelativePath(rootDir, absolutePath)));
+    const extraDomainFiles = relativeServerFiles.filter(
+      (relativePath) =>
+        !MAIN_SERVER_BASELINE_RELATIVE_PATHS.has(relativePath) &&
+        MAIN_SERVER_DOMAIN_FILE_PATTERN.test(relativePath)
+    );
+    if (extraDomainFiles.length > 0) {
+      reasons.push(`extra server domain files: ${extraDomainFiles.join(", ")}`);
+    }
+
+    const providerPath = path.join(rootDir, "src", "server", "MainServiceProvider.js");
+    if (await fileExists(providerPath)) {
+      const providerSource = await readFile(providerPath, "utf8");
+      const actionBindingCount = (providerSource.match(/\bapp\.actions\s*\(/gu) || []).length;
+      const serviceBindingCount = (providerSource.match(/\bapp\.(?:service|singleton)\s*\(/gu) || []).length;
+      const routeRegistrationCount = (providerSource.match(/\brouter\.register\s*\(/gu) || []).length;
+
+      if (actionBindingCount > 0) {
+        reasons.push("MainServiceProvider registers actions directly");
+      }
+      if (serviceBindingCount > 1) {
+        reasons.push(`MainServiceProvider registers ${serviceBindingCount} service/singleton bindings directly`);
+      }
+      if (routeRegistrationCount > 0) {
+        reasons.push("MainServiceProvider registers HTTP routes directly");
+      }
+    }
+
+    if (reasons.length > 0) {
+      warnings.push(
+        `packages/main: [feature-lane:main-glue-only] packages/main should stay composition/glue. Found ${reasons.join("; ")}. Move substantial server feature logic into a dedicated package generated with feature-server-generator scaffold.`
+      );
+    }
+  }
+
+  async function collectHandmadeFeatureLaneWarnings({ appLocalRegistry, warnings }) {
+    const packageEntries = sortStrings([...appLocalRegistry.keys()])
+      .map((packageId) => appLocalRegistry.get(packageId))
+      .filter(Boolean);
+
+    for (const packageEntry of packageEntries) {
+      const relativeDir = String(packageEntry?.relativeDir || "").trim();
+      if (relativeDir === "packages/main") {
+        continue;
+      }
+
+      const rootDir = String(packageEntry?.rootDir || "").trim();
+      if (!rootDir) {
+        continue;
+      }
+
+      const metadata = normalizeFeatureLaneMetadata(packageEntry?.descriptor);
+      if (metadata.scaffoldShape === FEATURE_SERVER_SCAFFOLD_SHAPE) {
+        continue;
+      }
+
+      const descriptor = ensureObject(packageEntry?.descriptor);
+      const capabilities = ensureObject(descriptor.capabilities);
+      const providedCapabilities = ensureArray(capabilities.provides)
+        .map((value) => String(value || "").trim())
+        .filter(Boolean);
+      const dependsOn = ensureArray(descriptor.dependsOn)
+        .map((value) => String(value || "").trim())
+        .filter(Boolean);
+      if (
+        providedCapabilities.some((value) => value.startsWith("crud.")) ||
+        dependsOn.includes("@jskit-ai/crud-core")
+      ) {
+        continue;
+      }
+
+      const serverProviders = ensureArray(ensureObject(ensureObject(descriptor.runtime).server).providers);
+      const hasDirectServerProvider = serverProviders.some((rawProvider) => {
+        const provider = ensureObject(rawProvider);
+        const entrypoint = String(provider.entrypoint || "").trim();
+        return entrypoint.startsWith("src/server/") && /Provider\.[A-Za-z0-9]+$/u.test(entrypoint);
+      });
+      if (!hasDirectServerProvider) {
+        continue;
+      }
+
+      const markerPaths = [];
+      for (const relativePath of FEATURE_SERVER_COMPLEX_MARKER_RELATIVE_PATHS) {
+        if (await fileExists(path.join(rootDir, relativePath))) {
+          markerPaths.push(relativePath);
+        }
+      }
+
+      const looksLikeFeatureCapability = providedCapabilities.some((value) => value.startsWith("feature."));
+      if (!(markerPaths.length >= 3 || (looksLikeFeatureCapability && markerPaths.length >= 2))) {
+        continue;
+      }
+
+      warnings.push(
+        `${relativeDir || String(packageEntry?.packageId || "").trim()}: [feature-lane:handmade-feature] package looks like a substantial non-CRUD server feature (${markerPaths.join(", ")}) but is missing metadata.jskit.scaffoldShape="${FEATURE_SERVER_SCAFFOLD_SHAPE}". Start from jskit generate feature-server-generator scaffold <feature-name> for this lane instead of hand-making the topology.`
+      );
+    }
+  }
+
+  async function collectFeatureLaneDoctorIssues({ appRoot, appLocalRegistry, issues, warnings }) {
+    const packageEntries = sortStrings([...appLocalRegistry.keys()])
+      .map((packageId) => appLocalRegistry.get(packageId))
+      .filter(Boolean);
+
+    for (const packageEntry of packageEntries) {
+      await collectFeatureLaneRuleIssuesForPackage({
+        appRoot,
+        packageEntry,
+        issues
+      });
+    }
+
+    await collectMainPackageFeatureLaneWarnings({
+      appRoot,
+      appLocalRegistry,
+      warnings
+    });
+    await collectHandmadeFeatureLaneWarnings({
+      appLocalRegistry,
+      warnings
+    });
+  }
+
   function hasTopLevelObjectProperty(sourceText = "", propertyName = "") {
     const normalizedPropertyName = String(propertyName || "").trim();
     const normalizedSourceText = String(sourceText || "").trim();
@@ -903,6 +1256,7 @@ function createHealthCommands(ctx = {}) {
     const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
     const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
     const issues = [];
+    const warnings = [];
     const installed = ensureObject(lock.installedPackages);
     await hydratePackageRegistryFromInstalledNodeModules({
       appRoot,
@@ -940,12 +1294,19 @@ function createHealthCommands(ctx = {}) {
       appRoot,
       issues
     });
+    await collectFeatureLaneDoctorIssues({
+      appRoot,
+      appLocalRegistry,
+      issues,
+      warnings
+    });
 
     const payload = {
       appRoot,
       lockVersion: lock.lockVersion,
       installedPackages: sortStrings(Object.keys(installed)),
-      issues
+      issues,
+      warnings: sortStrings(warnings)
     };
 
     if (options.json) {
@@ -953,13 +1314,21 @@ function createHealthCommands(ctx = {}) {
     } else {
       stdout.write(`App root: ${appRoot}\n`);
       stdout.write(`Installed packages: ${payload.installedPackages.length}\n`);
-      if (issues.length === 0) {
+      if (issues.length === 0 && payload.warnings.length === 0) {
         stdout.write("Doctor status: healthy\n");
+      } else if (issues.length === 0) {
+        stdout.write(`Doctor status: warnings (${payload.warnings.length} warning(s))\n`);
+        for (const warning of payload.warnings) {
+          stdout.write(`! ${warning}\n`);
+        }
       } else {
         stdout.write(`Doctor status: unhealthy (${issues.length} issue(s))\n`);
         for (const issue of issues) {
           stdout.write(`- ${issue}\n`);
         }
+        for (const warning of payload.warnings) {
+          stdout.write(`! ${warning}\n`);
+        }
       }
     }
 

package/src/server/commandHandlers/list.js

@@ -12,6 +12,8 @@ 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 JSKIT_SCOPE_PREFIX = "@jskit-ai/";
+const FEATURE_SERVER_GENERATOR_PACKAGE_ID = "@jskit-ai/feature-server-generator";
 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"]);
@@ -41,6 +43,41 @@ function appendTokenSource(map, token = "", source = "") {
   map.set(normalizedToken, existingSources);
 }
 
+function toShortPackageId(packageId = "") {
+  const normalizedPackageId = String(packageId || "").trim();
+  if (!normalizedPackageId.startsWith(JSKIT_SCOPE_PREFIX)) {
+    return normalizedPackageId;
+  }
+  return normalizedPackageId.slice(JSKIT_SCOPE_PREFIX.length);
+}
+
+function resolveGeneratorPrimarySubcommand(packageEntry = {}) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  const metadata = ensureObject(descriptor.metadata);
+  return String(metadata.generatorPrimarySubcommand || descriptor.generatorPrimarySubcommand || "").trim();
+}
+
+function resolveGeneratorDescription(packageEntry = {}) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  return String(descriptor.description || "").trim();
+}
+
+function resolveGeneratorQuickStartRows(packageEntry = {}, { limit = 3 } = {}) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  const metadata = ensureObject(descriptor.metadata);
+  const subcommands = ensureObject(metadata.generatorSubcommands || descriptor.generatorSubcommands);
+  const primarySubcommandName = resolveGeneratorPrimarySubcommand(packageEntry);
+  const primarySubcommand = ensureObject(subcommands[primarySubcommandName]);
+  const examples = ensureArray(primarySubcommand.examples);
+  return examples
+    .slice(0, Math.max(0, Number(limit) || 0))
+    .map((example) => ({
+      label: String(ensureObject(example).label || "").trim(),
+      lines: ensureArray(ensureObject(example).lines).map((value) => String(value || "").trim()).filter(Boolean)
+    }))
+    .filter((example) => example.lines.length > 0);
+}
+
 function isLinkItemToken(token = "") {
   return String(token || "").trim().toLowerCase().endsWith(LINK_ITEM_TOKEN_SUFFIX);
 }
@@ -265,6 +302,21 @@ function createListCommands(ctx = {}) {
       if (lines.length > 0) {
         lines.push("");
       }
+      const featureServerEntry = packageRegistry.get(FEATURE_SERVER_GENERATOR_PACKAGE_ID);
+      const recommendedQuickStarts = resolveGeneratorQuickStartRows(featureServerEntry, { limit: 3 });
+      if (recommendedQuickStarts.length > 0) {
+        lines.push(color.heading(`Recommended non-CRUD server starts (${recommendedQuickStarts.length}):`));
+        for (const example of recommendedQuickStarts) {
+          const label = String(example.label || "").trim();
+          if (label) {
+            lines.push(`- ${color.item(label)}`);
+          }
+          for (const commandLine of ensureArray(example.lines)) {
+            lines.push(`  ${commandLine}`);
+          }
+        }
+        lines.push("");
+      }
       lines.push(color.heading("Available generators:"));
       const packageIds = sortStrings([...packageRegistry.keys()].filter((packageId) => {
         const packageEntry = packageRegistry.get(packageId);
@@ -273,8 +325,14 @@ function createListCommands(ctx = {}) {
       for (const packageId of packageIds) {
         const packageEntry = packageRegistry.get(packageId);
         const installedLabel = installedPackages.has(packageId) ? " (installed)" : "";
+        const shortId = toShortPackageId(packageId);
+        const shortIdPrefix = shortId && shortId !== packageId ? `${color.item(shortId)} ` : "";
+        const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
+        const primarySuffix = primarySubcommand ? ` ${color.dim(`[primary:${primarySubcommand}]`)}` : "";
+        const description = resolveGeneratorDescription(packageEntry);
+        const descriptionSuffix = description ? `: ${description}` : "";
         lines.push(
-          `- ${color.item(packageId)} ${color.version(`(${packageEntry.version})`)}${installedLabel ? color.installed(installedLabel) : ""}`
+          `- ${shortIdPrefix}${color.item(packageId)} ${color.version(`(${packageEntry.version})`)}${primarySuffix}${installedLabel ? color.installed(installedLabel) : ""}${descriptionSuffix}`.trim()
         );
       }
     }
@@ -328,8 +386,12 @@ function createListCommands(ctx = {}) {
             }
             return {
               packageId,
+              shortId: toShortPackageId(packageId),
               version: packageEntry.version,
-              installed: installedPackages.has(packageId)
+              installed: installedPackages.has(packageId),
+              description: resolveGeneratorDescription(packageEntry),
+              primarySubcommand: resolveGeneratorPrimarySubcommand(packageEntry),
+              quickStarts: resolveGeneratorQuickStartRows(packageEntry, { limit: 3 })
             };
           }).filter(Boolean)
           : [],

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

@@ -10,6 +10,7 @@ import {
 } from "../../shared/outputFormatting.js";
 
 const JSKIT_SCOPE_PREFIX = "@jskit-ai/";
+const FEATURE_SERVER_GENERATOR_PACKAGE_ID = "@jskit-ai/feature-server-generator";
 const HELP_TEXT_BY_KEY = Object.freeze({
   "page-target-file":
     "Vue page file relative to src/pages/. It must resolve to a configured surface.",
@@ -223,7 +224,8 @@ function appendHelpExamples(lines = [], exampleRows = [], { color = null } = {})
   }
 
   lines.push("");
-  lines.push(color ? color.heading(`Examples (${examples.length}):`) : `Examples (${examples.length}):`);
+  const headingLabel = color ? color.heading(`Examples (${examples.length}):`) : `Examples (${examples.length}):`;
+  lines.push(headingLabel);
   appendSeparatedBlocks(
     lines,
     examples.map((example) => {
@@ -250,6 +252,31 @@ function appendHelpExamples(lines = [], exampleRows = [], { color = null } = {})
   );
 }
 
+function appendHelpExamplesWithHeading(lines = [], exampleRows = [], heading = "", { color = null } = {}) {
+  const examples = ensureArray(exampleRows);
+  const headingText = String(heading || "").trim();
+  if (examples.length < 1 || !headingText) {
+    return;
+  }
+
+  lines.push("");
+  lines.push(color ? color.heading(headingText) : headingText);
+  appendSeparatedBlocks(
+    lines,
+    examples.map((example) => {
+      const block = [];
+      const label = String(example?.label || "").trim();
+      if (label) {
+        block.push(`- ${color ? color.item(label) : label}`);
+      }
+      for (const commandLine of ensureArray(example?.lines)) {
+        block.push(`  ${commandLine}`);
+      }
+      return block;
+    }).filter((block) => block.length > 0)
+  );
+}
+
 function appendHelpNotes(lines = [], rawNotes = [], { color = null } = {}) {
   const notes = normalizeHelpNoteRows(rawNotes);
   if (notes.length < 1) {
@@ -420,6 +447,23 @@ function buildSubcommandOptionRows(optionRows = [], subcommandRow = {}) {
   return rows;
 }
 
+function resolvePrimaryGeneratorQuickStartRows(packageEntry = {}, { limit = 3 } = {}) {
+  const metadata = resolveGeneratorSubcommandMetadata(packageEntry);
+  const subcommands = ensureArray(metadata.subcommands);
+  const primarySubcommand = subcommands.find((row) => row.primary) || subcommands[0] || null;
+  if (!primarySubcommand) {
+    return [];
+  }
+
+  return ensureArray(primarySubcommand.examples)
+    .slice(0, Math.max(0, Number(limit) || 0))
+    .map((example) => Object.freeze({
+      label: String(example?.label || "").trim(),
+      lines: ensureArray(example?.lines).map((value) => String(value || "").trim()).filter(Boolean)
+    }))
+    .filter((example) => example.lines.length > 0);
+}
+
 function renderGenerateCatalogHelp({
   io,
   packageRegistry,
@@ -438,11 +482,14 @@ function renderGenerateCatalogHelp({
         description: resolvePackageSummary(entry)
       });
     });
+  const featureServerPackageEntry = packageRegistry.get(FEATURE_SERVER_GENERATOR_PACKAGE_ID);
+  const recommendedQuickStarts = resolvePrimaryGeneratorQuickStartRows(featureServerPackageEntry, { limit: 3 });
 
   if (json) {
     io.stdout.write(`${JSON.stringify({
       command: "generate",
       generators,
+      recommendedQuickStarts,
       usage: [
         "jskit generate <generatorId> help",
         "jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...]",
@@ -471,6 +518,12 @@ function renderGenerateCatalogHelp({
   lines.push("- jskit generate <generatorId> help");
   lines.push("- jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...]");
   lines.push("- jskit list generators");
+  appendHelpExamplesWithHeading(
+    lines,
+    recommendedQuickStarts,
+    `Recommended non-CRUD server starts (${recommendedQuickStarts.length}):`,
+    { color }
+  );
   writeWrappedLines({
     stdout: io.stdout,
     lines
@@ -619,6 +672,12 @@ function renderGeneratePackageHelp({
       const descriptionSuffix = subcommand.description ? `: ${subcommand.description}` : "";
       lines.push(`- ${color.item(subcommand.name)}${primarySuffix}${descriptionSuffix}`);
     }
+    appendHelpExamplesWithHeading(
+      lines,
+      resolvePrimaryGeneratorQuickStartRows(packageEntry, { limit: 3 }),
+      `Primary quick starts (${resolvePrimaryGeneratorQuickStartRows(packageEntry, { limit: 3 }).length}):`,
+      { color }
+    );
     lines.push("");
     lines.push("Use subcommand help for positional args, options, notes, and examples:");
     lines.push(`  ${color.item("jskit generate <generatorId> <subcommand> help")}`);

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

@@ -240,7 +240,7 @@ async function runPackageGenerateCommand(
     });
     if (!resolvedPackageId) {
       throw createCliError(
-        `Unknown package: ${packageIdInput}. Install it first (npm install ${packageIdInput}) if you want to run generator subcommands from node_modules.`
+        `Unknown package: ${packageIdInput}. Use jskit list generators to discover available generators. If you want to run generator subcommands from node_modules, install the generator first (npm install ${packageIdInput}). For a substantial non-CRUD server feature, start with: jskit generate feature-server-generator scaffold <feature-name>.`
       );
     }
 
@@ -255,7 +255,7 @@ async function runPackageGenerateCommand(
     }
     if (resolvePackageKind(packageEntry) !== "generator") {
       throw createCliError(
-        `Package ${resolvedPackageId} is a runtime package. Use: jskit add package ${resolvedPackageId}`
+        `Package ${resolvedPackageId} is a runtime package. Use: jskit add package ${resolvedPackageId}. For a new substantial non-CRUD server feature, start with: jskit generate feature-server-generator scaffold <feature-name>.`
       );
     }
 

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

@@ -23,7 +23,9 @@ async function runPackageUpdateCommand(
   const installedPackages = ensureObject(lock.installedPackages);
   const resolvedTargetId = resolveInstalledPackageIdInput(targetId, installedPackages);
   if (!resolvedTargetId) {
-    throw createCliError(`Package is not installed: ${targetId}`);
+    throw createCliError(
+      `Package is not installed: ${targetId}. update package only reapplies packages already recorded in .jskit/lock.json. If you meant to install it, run: jskit add package ${targetId}`
+    );
   }
 
   return runCommandAdd({

package/src/server/commandHandlers/show/renderPackageText.js

@@ -6,6 +6,35 @@ import { createShowRenderHelpers } from "./renderHelpers.js";
 import { writePackageExportsSection } from "./renderPackageExports.js";
 import { writeCapabilitiesSections } from "./renderPackageCapabilities.js";
 
+function resolveGeneratorSubcommandRows(payload = {}) {
+  const metadata = ensureObject(payload.metadata);
+  const generatorSubcommands = ensureObject(metadata.generatorSubcommands);
+  const primarySubcommand = String(metadata.generatorPrimarySubcommand || "").trim();
+  return Object.keys(generatorSubcommands)
+    .sort((left, right) => left.localeCompare(right))
+    .map((subcommandName) => {
+      const definition = ensureObject(generatorSubcommands[subcommandName]);
+      return {
+        name: subcommandName,
+        primary: primarySubcommand === subcommandName,
+        description: String(definition.description || "").trim(),
+        examples: ensureArray(definition.examples)
+          .map((example) => {
+            const record = ensureObject(example);
+            return {
+              label: String(record.label || "").trim(),
+              lines: ensureArray(record.lines).map((value) => String(value || "").trim()).filter(Boolean)
+            };
+          })
+          .filter((example) => example.lines.length > 0)
+      };
+    });
+}
+
+function resolveOwnershipGuidance(payload = {}) {
+  return ensureObject(ensureObject(ensureObject(payload.metadata).jskit).ownershipGuidance);
+}
+
 function renderPackagePayloadText({
   payload,
   provides,
@@ -70,6 +99,8 @@ function renderPackagePayloadText({
   const bindingSections = ensureObject(payload.containerBindings);
   const serverBindings = ensureArray(bindingSections.server);
   const clientBindings = ensureArray(bindingSections.client);
+  const generatorSubcommands = resolveGeneratorSubcommandRows(payload);
+  const ownershipGuidance = resolveOwnershipGuidance(payload);
 
   stdout.write(`${color.heading("Information")}\n`);
   writeField("Package", payload.packageId, color.item);
@@ -98,6 +129,50 @@ function renderPackagePayloadText({
     }
   }
 
+  if (generatorSubcommands.length > 0) {
+    stdout.write(`${color.heading(`Generator commands (${generatorSubcommands.length}):`)}\n`);
+    for (const subcommand of generatorSubcommands) {
+      const primarySuffix = subcommand.primary ? ` ${color.installed("[primary]")}` : "";
+      const descriptionSuffix = subcommand.description ? `: ${subcommand.description}` : "";
+      stdout.write(`- ${color.item(subcommand.name)}${primarySuffix}${descriptionSuffix}\n`);
+      if (options.details && subcommand.examples.length > 0) {
+        for (const example of subcommand.examples.slice(0, 2)) {
+          const exampleLabel = String(example.label || "").trim();
+          if (exampleLabel) {
+            stdout.write(`  ${color.dim(`example: ${exampleLabel}`)}\n`);
+          }
+          for (const commandLine of ensureArray(example.lines)) {
+            stdout.write(`  ${commandLine}\n`);
+          }
+        }
+      }
+    }
+  }
+
+  if (options.details && Object.keys(ownershipGuidance).length > 0) {
+    const title = String(ownershipGuidance.title || "Ownership guidance").trim() || "Ownership guidance";
+    const summary = String(ownershipGuidance.summary || "").trim();
+    const responsibilities = ensureArray(ownershipGuidance.responsibilities)
+      .map((value) => String(value || "").trim())
+      .filter(Boolean);
+    const examples = ensureArray(ownershipGuidance.examples)
+      .map((value) => String(value || "").trim())
+      .filter(Boolean);
+    stdout.write(`${color.heading(title)}\n`);
+    if (summary) {
+      stdout.write(`- ${summary}\n`);
+    }
+    for (const responsibility of responsibilities) {
+      stdout.write(`- ${responsibility}\n`);
+    }
+    if (examples.length > 0) {
+      stdout.write(`- ${color.dim("quick starts:")}\n`);
+      for (const example of examples) {
+        stdout.write(`  ${example}\n`);
+      }
+    }
+  }
+
   if (placementOutlets.length > 0) {
     stdout.write(`${color.heading(`Placement outlets (${placementOutlets.length}):`)}\n`);
     for (const outlet of placementOutlets) {

package/src/server/core/commandCatalog.js

@@ -223,22 +223,23 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "Short ids resolve to @jskit-ai/<id> when available.",
       "Running without args lists available generators.",
       "Running with only <generatorId> shows generator help.",
+      "For substantial non-CRUD server features, start with feature-server-generator scaffold.",
       "Use jskit generate <generatorId> <subcommand> help for subcommand-specific usage."
     ]),
     examples: Object.freeze([
       Object.freeze({
         label: "Common usage",
         lines: Object.freeze([
-          "npx jskit generate ui-generator page \\",
-          "  admin/reports/index.vue"
+          "npx jskit generate feature-server-generator scaffold \\",
+          "  booking-engine"
         ])
       }),
       Object.freeze({
         label: "More advanced usage",
         lines: Object.freeze([
-          "npx jskit generate crud-ui-generator crud \\",
-          "  admin/catalog/index/products \\",
-          "  --resource-file packages/products/src/shared/productResource.js"
+          "npx jskit generate feature-server-generator scaffold \\",
+          "  availability-engine \\",
+          "  --mode orchestrator"
         ])
       })
     ]),
@@ -265,6 +266,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     ]),
     defaults: Object.freeze([
       "Without mode, list prints bundles + runtime packages + generators.",
+      "Use list generators when you want the standard non-CRUD server lane command examples.",
       "placements are listed by the dedicated list-placements command.",
       "--full and --expanded only affect bundle/package listing views."
     ]),
@@ -338,6 +340,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     ]),
     defaults: Object.freeze([
       "Basic output is compact; --details expands capability and runtime sections.",
+      "Generator packages may include lane ownership guidance and subcommand examples under --details.",
       "--debug-exports implies --details."
     ]),
     fullUse: "jskit show <id> [--details] [--debug-exports] [--json]",

package/src/server/core/usageHelp.js

@@ -39,6 +39,12 @@ function printTopLevelHelp(stream = process.stderr) {
   for (const entry of listOverviewCommandDescriptors()) {
     lines.push(`  ${color.item(entry.command.padEnd(16, " "))} ${entry.summary}`);
   }
+  lines.push("");
+  lines.push(color.heading("Generator quick starts:"));
+  lines.push("  substantial non-CRUD server feature:");
+  lines.push(`    ${color.item("jskit generate feature-server-generator scaffold booking-engine")}`);
+  lines.push("  non-persistent workflow/orchestrator:");
+  lines.push(`    ${color.item("jskit generate feature-server-generator scaffold availability-engine --mode orchestrator")}`);
   writeHelpLines(stream, lines);
 }