@jskit-ai/jskit-cli 0.2.72 → 0.2.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.72",
+  "version": "0.2.73",
   "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.71",
-    "@jskit-ai/kernel": "0.1.63",
-    "@jskit-ai/shell-web": "0.1.62"
+    "@jskit-ai/jskit-catalog": "0.1.72",
+    "@jskit-ai/kernel": "0.1.64",
+    "@jskit-ai/shell-web": "0.1.63"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/completion.js

@@ -14,10 +14,11 @@ import {
 } from "../core/commandCatalog.js";
 
 const WRAPPER_COMMANDS = new Set(["npx", "jsx"]);
-const KNOWN_GENERATE_FLAG_OPTIONS = Object.freeze(["dry-run", "run-npm-install", "json", "verbose"]);
+const KNOWN_GENERATE_FLAG_OPTIONS = Object.freeze(["dry-run", "run-npm-install", "devlinks", "json", "verbose"]);
 const BOOLEAN_OPTION_NAMES = new Set([
   "dry-run",
   "run-npm-install",
+  "devlinks",
   "full",
   "expanded",
   "details",
@@ -747,6 +748,7 @@ function buildCommandOptionMeta(command = "", catalogModule) {
     const labels = {
       dryRun: "dry-run",
       runNpmInstall: "run-npm-install",
+      devlinks: "devlinks",
       full: "full",
       expanded: "expanded",
       details: "details",

package/src/server/cliRuntime/descriptorValidation.js

@@ -61,6 +61,54 @@ function validateFileMutationShape(descriptor, descriptorPath) {
   }
 }
 
+function validateLifecycleHookSpec(spec = {}, descriptorPath, label = "lifecycle hook") {
+  const normalized = ensureObject(spec);
+  if (Object.keys(normalized).length < 1) {
+    return null;
+  }
+
+  const entrypoint = String(normalized.entrypoint || "").trim();
+  if (!entrypoint) {
+    throw createCliError(`Invalid package descriptor at ${descriptorPath}: ${label} requires "entrypoint".`);
+  }
+
+  const exportName = String(normalized.export || "").trim() || "default";
+  return {
+    ...normalized,
+    entrypoint,
+    export: exportName
+  };
+}
+
+function validateLifecycleShape(descriptor, descriptorPath) {
+  const lifecycle = ensureObject(ensureObject(descriptor).lifecycle);
+  const install = ensureObject(lifecycle.install);
+  if (Object.keys(install).length < 1) {
+    return lifecycle;
+  }
+
+  const prepare = validateLifecycleHookSpec(install.prepare, descriptorPath, "lifecycle.install.prepare");
+  const finalize = validateLifecycleHookSpec(install.finalize, descriptorPath, "lifecycle.install.finalize");
+
+  if (install.finalize && typeof install.finalize === "object") {
+    const managesNpmInstall = install.finalize.managesNpmInstall;
+    if (typeof managesNpmInstall !== "undefined" && typeof managesNpmInstall !== "boolean") {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: lifecycle.install.finalize.managesNpmInstall must be boolean when provided.`
+      );
+    }
+  }
+
+  return {
+    ...lifecycle,
+    install: {
+      ...install,
+      ...(prepare ? { prepare } : {}),
+      ...(finalize ? { finalize } : {})
+    }
+  };
+}
+
 function validatePackageDescriptorShape(descriptor, descriptorPath) {
   const normalized = ensureObject(descriptor);
   const packageId = String(normalized.packageId || "").trim();
@@ -85,9 +133,11 @@ function validatePackageDescriptorShape(descriptor, descriptorPath) {
   }
 
   validateFileMutationShape(normalized, descriptorPath);
+  const lifecycle = validateLifecycleShape(normalized, descriptorPath);
 
   return {
     ...normalized,
+    lifecycle,
     kind: normalizePackageKind(normalized.kind, descriptorPath)
   };
 }
@@ -115,11 +165,13 @@ function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { ex
   }
 
   validateFileMutationShape(normalized, descriptorPath);
+  const lifecycle = validateLifecycleShape(normalized, descriptorPath);
 
   return {
     ...normalized,
     packageId,
     version,
+    lifecycle,
     kind: normalizePackageKind(normalized.kind, descriptorPath)
   };
 }

package/src/server/cliRuntime/mutations/fileMutations.js

@@ -198,6 +198,7 @@ async function applyFileMutations(
   warnings = [],
   existingManagedFiles = [],
   {
+    dryRun = false,
     reapplyManagedAppFiles = false
   } = {}
 ) {
@@ -224,18 +225,19 @@ async function applyFileMutations(
   for (const preparedMutation of ensureArray(preparedMutations)) {
     const mutation = ensureObject(preparedMutation.mutation);
     const operation = String(preparedMutation.operation || "").trim() || "copy-file";
-    if (operation === "install-migration") {
-      await applyInstallMigrationMutation({
-        packageEntry,
-        preparedMutation,
-        appRoot,
-        managedMigrations,
-        managedMigrationById,
-        touchedFiles,
-        warnings
-      });
-      continue;
-    }
+      if (operation === "install-migration") {
+        await applyInstallMigrationMutation({
+          packageEntry,
+          preparedMutation,
+          appRoot,
+          managedMigrations,
+          managedMigrationById,
+          touchedFiles,
+          warnings,
+          dryRun
+        });
+        continue;
+      }
 
     const renderedSourceContent = String(preparedMutation.renderedSourceContent || "");
     const renderedSourceBuffer = Buffer.from(renderedSourceContent, "utf8");
@@ -280,8 +282,10 @@ async function applyFileMutations(
         continue;
       }
 
-      await mkdir(path.dirname(targetPath), { recursive: true });
-      await writeFile(targetPath, renderedSourceContent, "utf8");
+      if (!dryRun) {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, renderedSourceContent, "utf8");
+      }
 
       managedFiles.push({
         path: relativeTargetPath,

package/src/server/cliRuntime/mutations/installMigrationMutation.js

@@ -26,7 +26,8 @@ async function applyInstallMigrationMutation({
   managedMigrations,
   managedMigrationById,
   touchedFiles,
-  warnings
+  warnings,
+  dryRun = false
 } = {}) {
   const mutation = ensureObject(preparedMutation?.mutation);
   if (mutation.preserveOnRemove === true) {
@@ -81,8 +82,10 @@ async function applyInstallMigrationMutation({
     }
 
     if (!(await fileExists(absolutePath))) {
-      await mkdir(path.dirname(absolutePath), { recursive: true });
-      await writeFile(absolutePath, renderedSourceContent, "utf8");
+      if (!dryRun) {
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, renderedSourceContent, "utf8");
+      }
       touchedFiles.add(relativePath);
     }
 
@@ -165,8 +168,10 @@ async function applyInstallMigrationMutation({
 
   const relativePath = targetPath.relativePath;
   const absolutePath = targetPath.absolutePath;
-  await mkdir(path.dirname(absolutePath), { recursive: true });
-  await writeFile(absolutePath, renderedSourceContent, "utf8");
+  if (!dryRun) {
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, renderedSourceContent, "utf8");
+  }
   touchedFiles.add(relativePath);
 
   const nextManagedRecord = {

package/src/server/cliRuntime/mutations/textMutations.js

@@ -35,7 +35,15 @@ const PRE_FILE_CONFIG_MUTATION_TARGETS = new Set([
   "config/server.js"
 ]);
 
-async function applyTextMutations(packageEntry, appRoot, textMutations, options, managedText, touchedFiles) {
+async function applyTextMutations(
+  packageEntry,
+  appRoot,
+  textMutations,
+  options,
+  managedText,
+  touchedFiles,
+  { dryRun = false } = {}
+) {
   for (const mutation of textMutations) {
     const when = normalizeMutationWhen(mutation?.when);
     const configContext = when?.config ? await loadMutationWhenConfigContext(appRoot) : {};
@@ -69,8 +77,10 @@ async function applyTextMutations(packageEntry, appRoot, textMutations, options,
       const resolvedValue = interpolateOptionValue(mutation?.value || "", options, packageEntry.packageId, resolvedKey);
       const upserted = upsertEnvValue(previousContent, resolvedKey, resolvedValue);
 
-      await mkdir(path.dirname(absoluteFile), { recursive: true });
-      await writeFile(absoluteFile, upserted.content, "utf8");
+      if (!dryRun) {
+        await mkdir(path.dirname(absoluteFile), { recursive: true });
+        await writeFile(absoluteFile, upserted.content, "utf8");
+      }
 
       const recordKey = `${relativeFile}::${String(mutation?.id || resolvedKey)}`;
       managedText[recordKey] = {
@@ -136,8 +146,10 @@ async function applyTextMutations(packageEntry, appRoot, textMutations, options,
         continue;
       }
 
-      await mkdir(path.dirname(absoluteFile), { recursive: true });
-      await writeFile(absoluteFile, appended.content, "utf8");
+      if (!dryRun) {
+        await mkdir(path.dirname(absoluteFile), { recursive: true });
+        await writeFile(absoluteFile, appended.content, "utf8");
+      }
 
       const recordKey = `${relativeFile}::${mutationId}`;
       managedText[recordKey] = {

package/src/server/cliRuntime/packageInstallFlow.js

@@ -146,7 +146,8 @@ async function applyPackagePositioning({
   packageOptions,
   appRoot,
   lock,
-  touchedFiles
+  touchedFiles,
+  dryRun = false
 }) {
   const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
   if (Object.keys(existingInstall).length < 1) {
@@ -196,7 +197,10 @@ async function applyPackagePositioning({
       [],
       touchedFiles,
       [],
-      nextManaged.files
+      nextManaged.files,
+      {
+        dryRun
+      }
     );
   }
   if (positioningMutations.text.length > 0) {
@@ -206,7 +210,10 @@ async function applyPackagePositioning({
       positioningMutations.text,
       packageOptions,
       appliedManagedText,
-      touchedFiles
+      touchedFiles,
+      {
+        dryRun
+      }
     );
   }
 
@@ -250,7 +257,8 @@ async function applyPackageMigrationsOnly({
   packageOptions,
   appRoot,
   lock,
-  touchedFiles
+  touchedFiles,
+  dryRun = false
 }) {
   const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
   if (Object.keys(existingInstall).length < 1) {
@@ -303,7 +311,10 @@ async function applyPackageMigrationsOnly({
       nextManaged.migrations,
       touchedFiles,
       mutationWarnings,
-      nextManaged.files
+      nextManaged.files,
+      {
+        dryRun
+      }
     );
   }
 
@@ -333,7 +344,8 @@ async function applyPackageInstall({
   lock,
   packageRegistry,
   touchedFiles,
-  reportTemplateFetchStatus = null
+  reportTemplateFetchStatus = null,
+  dryRun = false
 }) {
   const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
   const existingManaged = ensureObject(existingInstall.managed);
@@ -376,7 +388,10 @@ async function applyPackageInstall({
       preFileTextMutations,
       packageOptions,
       managedRecord.managed.text,
-      touchedFiles
+      touchedFiles,
+      {
+        dryRun
+      }
     );
   }
 
@@ -391,7 +406,8 @@ async function applyPackageInstall({
     appRoot,
     packageId: packageEntry.packageId,
     managedViteChanges: ensureObject(existingManaged.vite),
-    touchedFiles
+    touchedFiles,
+    dryRun
   });
 
   const mutationDependencies = ensureObject(mutations.dependencies);
@@ -499,15 +515,16 @@ async function applyPackageInstall({
     packageEntryForMutations,
     appRoot,
     preparedFileMutations,
-    managedRecord.managed.files,
-    managedRecord.managed.migrations,
-    touchedFiles,
-    mutationWarnings,
-    ensureArray(existingManaged.files),
-    {
-      reapplyManagedAppFiles: Object.keys(existingInstall).length > 0
-    }
-  );
+      managedRecord.managed.files,
+      managedRecord.managed.migrations,
+      touchedFiles,
+      mutationWarnings,
+      ensureArray(existingManaged.files),
+      {
+        dryRun,
+        reapplyManagedAppFiles: Object.keys(existingInstall).length > 0
+      }
+    );
 
   await applyTextMutations(
     packageEntryForMutations,
@@ -515,7 +532,10 @@ async function applyPackageInstall({
     postFileTextMutations,
     packageOptions,
     managedRecord.managed.text,
-    touchedFiles
+    touchedFiles,
+    {
+      dryRun
+    }
   );
 
   await applyViteMutations(
@@ -524,7 +544,10 @@ async function applyPackageInstall({
     ensureObject(mutations.vite),
     packageOptions,
     managedRecord.managed.vite,
-    touchedFiles
+    touchedFiles,
+    {
+      dryRun
+    }
   );
 
   mutationWarnings.push(...await collectInstallWarnings({

package/src/server/cliRuntime/viteProxy.js

@@ -144,14 +144,16 @@ async function loadViteDevProxyConfig(appRoot, { context = "vite proxy config" }
   });
 }
 
-async function writeViteDevProxyConfig(appRoot, config = {}, touchedFiles = null) {
+async function writeViteDevProxyConfig(appRoot, config = {}, touchedFiles = null, { dryRun = false } = {}) {
   const absolutePath = resolveViteDevProxyConfigAbsolutePath(appRoot);
   const relativePath = normalizeRelativePath(appRoot, absolutePath);
   const normalizedConfig = normalizeViteDevProxyConfig(config);
 
   if (normalizedConfig.entries.length < 1) {
     if (await fileExists(absolutePath)) {
-      await rm(absolutePath);
+      if (!dryRun) {
+        await rm(absolutePath);
+      }
       if (touchedFiles && typeof touchedFiles.add === "function") {
         touchedFiles.add(relativePath);
       }
@@ -159,7 +161,9 @@ async function writeViteDevProxyConfig(appRoot, config = {}, touchedFiles = null
     return;
   }
 
-  await writeJsonFile(absolutePath, normalizedConfig);
+  if (!dryRun) {
+    await writeJsonFile(absolutePath, normalizedConfig);
+  }
   if (touchedFiles && typeof touchedFiles.add === "function") {
     touchedFiles.add(relativePath);
   }
@@ -181,7 +185,15 @@ function normalizeViteProxyMutationRecord(value = {}) {
   });
 }
 
-async function applyViteMutations(packageEntry, appRoot, viteMutations, options, managedVite, touchedFiles) {
+async function applyViteMutations(
+  packageEntry,
+  appRoot,
+  viteMutations,
+  options,
+  managedVite,
+  touchedFiles,
+  { dryRun = false } = {}
+) {
   const mutations = ensureArray(ensureObject(viteMutations).proxy).map((entry) => normalizeViteProxyMutationRecord(entry));
   if (mutations.length < 1) {
     return;
@@ -291,10 +303,16 @@ async function applyViteMutations(packageEntry, appRoot, viteMutations, options,
     return;
   }
 
-  await writeViteDevProxyConfig(appRoot, nextConfig, touchedFiles);
+  await writeViteDevProxyConfig(appRoot, nextConfig, touchedFiles, { dryRun });
 }
 
-async function removeManagedViteProxyEntries({ appRoot, packageId, managedViteChanges = {}, touchedFiles = null } = {}) {
+async function removeManagedViteProxyEntries({
+  appRoot,
+  packageId,
+  managedViteChanges = {},
+  touchedFiles = null,
+  dryRun = false
+} = {}) {
   const managedChanges = Object.values(ensureObject(managedViteChanges))
     .map((entry) => ensureObject(entry))
     .filter((entry) => String(entry.op || "").trim() === "upsert-vite-proxy");
@@ -339,7 +357,7 @@ async function removeManagedViteProxyEntries({ appRoot, packageId, managedViteCh
     return;
   }
 
-  await writeViteDevProxyConfig(appRoot, nextConfig, touchedFiles);
+  await writeViteDevProxyConfig(appRoot, nextConfig, touchedFiles, { dryRun });
 }
 
 export {

package/src/server/commandHandlers/health.js

@@ -603,7 +603,9 @@ function createHealthCommands(ctx = {}) {
         packagePath,
         tableName,
         provenance: String(entry.provenance || "").trim().toLowerCase(),
-        ownerKind: String(entry.ownerKind || "").trim().toLowerCase()
+        ownerKind: String(entry.ownerKind || "").trim().toLowerCase(),
+        providerEntrypoint: String(entry.providerEntrypoint || "").trim(),
+        ownershipFilter: normalizeDbIdentifier(entry.ownershipFilter)
       });
     }
 
@@ -969,7 +971,7 @@ function createHealthCommands(ctx = {}) {
       .join(", ");
   }
 
-  async function resolveAppLocalCrudOwnershipFilters({ appRoot, appLocalRegistry }) {
+  async function resolveAppLocalCrudOwnershipFilters({ appRoot, appLocalRegistry, issues }) {
     const ownershipByTable = new Map();
     const packageEntries = sortStrings([...appLocalRegistry.keys()])
       .map((packageId) => appLocalRegistry.get(packageId))
@@ -980,26 +982,73 @@ function createHealthCommands(ctx = {}) {
         continue;
       }
 
-      const providerPath = resolvePrimaryServerProviderPath(packageEntry);
-      if (!providerPath || !(await fileExists(providerPath))) {
-        continue;
-      }
+      const serverProviderEntries = resolveServerProviderEntries(packageEntry);
+      const providerInfoByEntrypoint = new Map();
+      for (const providerEntry of serverProviderEntries) {
+        if (!(await fileExists(providerEntry.absolutePath))) {
+          continue;
+        }
 
-      const sourceText = await readFile(providerPath, "utf8");
-      const match = CRUD_OWNERSHIP_FILTER_LITERAL_PATTERN.exec(sourceText);
-      if (!match) {
-        continue;
+        const sourceText = await readFile(providerEntry.absolutePath, "utf8");
+        const match = CRUD_OWNERSHIP_FILTER_LITERAL_PATTERN.exec(sourceText);
+        if (!match) {
+          continue;
+        }
+
+        const ownershipFilter = normalizeDbIdentifier(match[1]);
+        providerInfoByEntrypoint.set(providerEntry.entrypoint, {
+          providerPath: normalizeRelativePath(appRoot, providerEntry.absolutePath),
+          ownershipFilter,
+          requiredOwnerKinds: resolveRequiredOwnerKindsFromOwnershipFilter(ownershipFilter)
+        });
       }
-      const ownershipFilter = normalizeDbIdentifier(match[1]);
-      const requiredOwnerKinds = resolveRequiredOwnerKindsFromOwnershipFilter(ownershipFilter);
 
       for (const ownershipEntry of normalizeOwnedTableEntries(packageEntry)) {
+        const descriptorPath = `${resolvePackageDisplayPath(packageEntry)}/package.descriptor.mjs`;
+        let providerInfo = null;
+        if (ownershipEntry.providerEntrypoint) {
+          providerInfo = providerInfoByEntrypoint.get(ownershipEntry.providerEntrypoint) || null;
+          if (!providerInfo) {
+            issues.push(
+              `${descriptorPath}: [crud-ownership:provider-unresolved] table "${ownershipEntry.tableName}" points at providerEntrypoint "${ownershipEntry.providerEntrypoint}" but doctor could not resolve an ownershipFilter from that provider. Make sure the file exists and declares a literal CRUD_MODULE_CONFIG.ownershipFilter.`
+            );
+          }
+        } else if (serverProviderEntries.length === 1) {
+          providerInfo = providerInfoByEntrypoint.get(serverProviderEntries[0].entrypoint) || null;
+          if (!providerInfo) {
+            issues.push(
+              `${descriptorPath}: [crud-ownership:provider-unresolved] table "${ownershipEntry.tableName}" relies on the package's only server provider, but doctor could not resolve a literal CRUD_MODULE_CONFIG.ownershipFilter from "${serverProviderEntries[0].entrypoint}".`
+            );
+          }
+        } else if (serverProviderEntries.length > 1) {
+          issues.push(
+            `${descriptorPath}: [crud-ownership:missing-provider-entrypoint] table "${ownershipEntry.tableName}" is claimed by a multi-provider CRUD package but does not declare metadata.jskit.tableOwnership.tables[].providerEntrypoint. Point it at the owning provider so doctor can verify the real ownershipFilter.`
+          );
+        }
+
+        if (
+          ownershipEntry.ownershipFilter &&
+          providerInfo?.ownershipFilter &&
+          ownershipEntry.ownershipFilter !== providerInfo.ownershipFilter
+        ) {
+          issues.push(
+            `${providerInfo.providerPath}: [crud-ownership:ownership-filter-mismatch] metadata declares ownershipFilter "${ownershipEntry.ownershipFilter}" for live table "${ownershipEntry.tableName}" but provider code uses "${providerInfo.ownershipFilter}". Update the provider or metadata so doctor verifies the real contract.`
+          );
+        }
+
+        const ownershipFilter = providerInfo?.ownershipFilter || "";
+        if (!ownershipFilter) {
+          continue;
+        }
+
         ownershipByTable.set(ownershipEntry.tableName, {
           tableName: ownershipEntry.tableName,
           ownershipFilter,
-          requiredOwnerKinds,
+          requiredOwnerKinds: providerInfo?.requiredOwnerKinds || new Set(),
           packagePath: resolvePackageDisplayPath(packageEntry),
-          providerPath: normalizeRelativePath(appRoot, providerPath)
+          providerPath:
+            providerInfo?.providerPath ||
+            normalizeRelativePath(appRoot, resolvePrimaryServerProviderPath(packageEntry))
         });
       }
     }
@@ -1149,6 +1198,29 @@ function createHealthCommands(ctx = {}) {
     return "";
   }
 
+  function resolveServerProviderEntries(packageEntry) {
+    const rootDir = String(packageEntry?.rootDir || "").trim();
+    if (!rootDir) {
+      return [];
+    }
+
+    const providers = ensureArray(ensureObject(ensureObject(packageEntry?.descriptor).runtime).server?.providers);
+    const resolved = [];
+    for (const rawProvider of providers) {
+      const provider = ensureObject(rawProvider);
+      const entrypoint = String(provider.entrypoint || "").trim();
+      if (!entrypoint || entrypoint.includes("*")) {
+        continue;
+      }
+      resolved.push({
+        entrypoint,
+        absolutePath: path.resolve(rootDir, entrypoint)
+      });
+    }
+
+    return resolved;
+  }
+
   function resolvePackageDisplayPath(packageEntry) {
     const relativeDir = String(packageEntry?.relativeDir || "").trim();
     if (relativeDir) {
@@ -1517,7 +1589,8 @@ function createHealthCommands(ctx = {}) {
     });
     const crudOwnershipByTable = await resolveAppLocalCrudOwnershipFilters({
       appRoot,
-      appLocalRegistry
+      appLocalRegistry,
+      issues
     });
     const exceptionEntriesByName = new Map();
     for (const entry of exceptionConfig.exceptions) {