@jskit-ai/jskit-cli 0.2.64 → 0.2.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.64",
+  "version": "0.2.66",
   "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.63",
-    "@jskit-ai/kernel": "0.1.55",
-    "@jskit-ai/shell-web": "0.1.54"
+    "@jskit-ai/jskit-catalog": "0.1.65",
+    "@jskit-ai/kernel": "0.1.57",
+    "@jskit-ai/shell-web": "0.1.56"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/completion.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { access, readdir, readFile } from "node:fs/promises";
+import { buildCrudFieldContractMap } from "@jskit-ai/kernel/shared/support/crudFieldContract";
 import {
   buildAppCommandOptionMeta,
   listAppCommandDefinitions
@@ -659,26 +660,7 @@ async function discoverResourceDisplayFields(appRoot, resourceFile = "") {
     if (!resource || typeof resource !== "object") {
       return [];
     }
-    const fieldKeys = new Set();
-
-    const outputSchemaProperties = resource?.operations?.view?.outputValidator?.schema?.properties;
-    if (outputSchemaProperties && typeof outputSchemaProperties === "object") {
-      for (const key of Object.keys(outputSchemaProperties)) {
-        if (key === resource?.contract?.lookup?.containerKey) {
-          continue;
-        }
-        fieldKeys.add(key);
-      }
-    }
-
-    for (const fieldMeta of Array.isArray(resource?.fieldMeta) ? resource.fieldMeta : []) {
-      const key = normalizeText(fieldMeta?.key);
-      if (key) {
-        fieldKeys.add(key);
-      }
-    }
-
-    return uniqueSorted([...fieldKeys]);
+    return uniqueSorted(Object.keys(buildCrudFieldContractMap(resource)));
   } catch {
     return [];
   }

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

@@ -196,7 +196,10 @@ async function applyFileMutations(
   managedMigrations,
   touchedFiles,
   warnings = [],
-  existingManagedFiles = []
+  existingManagedFiles = [],
+  {
+    reapplyManagedAppFiles = false
+  } = {}
 ) {
   const existingManagedFilesByPath = new Map();
   for (const managedFileValue of ensureArray(existingManagedFiles)) {
@@ -242,8 +245,16 @@ async function applyFileMutations(
       const relativeTargetPath = normalizeRelativePath(appRoot, targetPath);
       const previous = await readFileBufferIfExists(targetPath);
       const existingManaged = existingManagedFilesByPath.get(relativeTargetPath);
+      const existingManagedHash = String(existingManaged?.hash || "").trim();
+      const currentContentMatchesManagedVersion =
+        previous.exists &&
+        existingManagedHash &&
+        hashBuffer(previous.buffer) === existingManagedHash;
+      const canSafelyReapplyManagedAppFile =
+        reapplyManagedAppFiles === true &&
+        (!previous.exists || currentContentMatchesManagedVersion);
 
-      if (mutation.ownership === "app" && existingManaged) {
+      if (mutation.ownership === "app" && existingManaged && !canSafelyReapplyManagedAppFile) {
         managedFiles.push({
           ...existingManaged,
           path: relativeTargetPath,

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

@@ -30,80 +30,11 @@ import {
 } from "./templateContext.js";
 import { normalizeMutationRelativeFilePath } from "./mutationPathUtils.js";
 
-const SETTINGS_FIELDS_CONTRACT_TARGETS = Object.freeze({
-  "packages/main/src/shared/resources/consoleSettingsFields.js": Object.freeze({
-    contractId: "console.settings-fields.v1",
-    marker: "@jskit-contract console.settings-fields.v1",
-    requiredSnippets: Object.freeze([
-      "defineField",
-      "resetConsoleSettingsFields"
-    ])
-  }),
-  "packages/main/src/shared/resources/workspaceSettingsFields.js": Object.freeze({
-    contractId: "users.settings-fields.workspace.v1",
-    marker: "@jskit-contract users.settings-fields.workspace.v1",
-    requiredSnippets: Object.freeze([
-      "defineField",
-      "resetWorkspaceSettingsFields"
-    ])
-  })
-});
 const PRE_FILE_CONFIG_MUTATION_TARGETS = new Set([
   "config/public.js",
   "config/server.js"
 ]);
 
-function resolveSettingsFieldsContractTarget(relativeFile = "") {
-  const normalizedRelativeFile = normalizeMutationRelativeFilePath(relativeFile);
-  if (!normalizedRelativeFile) {
-    return null;
-  }
-  const target = SETTINGS_FIELDS_CONTRACT_TARGETS[normalizedRelativeFile];
-  if (!target) {
-    return null;
-  }
-  return {
-    normalizedRelativeFile,
-    target
-  };
-}
-
-async function validateSettingsFieldsContractMutationTarget({
-  appRoot,
-  relativeFile,
-  packageId
-} = {}) {
-  const contractTarget = resolveSettingsFieldsContractTarget(relativeFile);
-  if (!contractTarget) {
-    return;
-  }
-
-  const { normalizedRelativeFile, target } = contractTarget;
-  const absoluteFile = path.join(appRoot, normalizedRelativeFile);
-  const existing = await readFileBufferIfExists(absoluteFile);
-  if (!existing.exists) {
-    throw createCliError(
-      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} is missing. ` +
-      `Install @jskit-ai/console-core to scaffold ${target.contractId}.`
-    );
-  }
-
-  const source = existing.buffer.toString("utf8");
-  if (!source.includes(target.marker)) {
-    throw createCliError(
-      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} is missing contract marker "${target.marker}".`
-    );
-  }
-  for (const snippet of target.requiredSnippets) {
-    if (source.includes(snippet)) {
-      continue;
-    }
-    throw createCliError(
-      `Invalid append-text mutation in ${packageId}: ${normalizedRelativeFile} must include "${snippet}" for ${target.contractId}.`
-    );
-  }
-}
-
 async function applyTextMutations(packageEntry, appRoot, textMutations, options, managedText, touchedFiles) {
   for (const mutation of textMutations) {
     const when = normalizeMutationWhen(mutation?.when);
@@ -167,11 +98,6 @@ async function applyTextMutations(packageEntry, appRoot, textMutations, options,
       if (position !== "top" && position !== "bottom") {
         throw createCliError(`Invalid append-text mutation in ${packageEntry.packageId}: "position" must be "top" or "bottom".`);
       }
-      await validateSettingsFieldsContractMutationTarget({
-        appRoot,
-        relativeFile,
-        packageId: packageEntry.packageId
-      });
 
       const absoluteFile = path.join(appRoot, relativeFile);
       const previous = await readFileBufferIfExists(absoluteFile);

package/src/server/cliRuntime/packageInstallFlow.js

@@ -18,6 +18,9 @@ import {
   applyPackageJsonField,
   removePackageJsonField
 } from "./appState.js";
+import {
+  loadMutationWhenConfigContext
+} from "./ioAndMigrations.js";
 import {
   isGeneratorPackageEntry,
   loadAppLocalPackageRegistry
@@ -82,6 +85,44 @@ function cloneManagedArray(value = []) {
   }));
 }
 
+function normalizeModeToken(value = "") {
+  return String(value || "").trim().toLowerCase();
+}
+
+function isWorkspaceCapableTenancyMode(value = "") {
+  const normalized = normalizeModeToken(value);
+  return normalized === "personal" || normalized === "workspaces";
+}
+
+async function collectInstallWarnings({
+  packageEntry,
+  appRoot,
+  appPackageJson
+}) {
+  const warnings = [];
+
+  if (packageEntry?.packageId !== "@jskit-ai/users-core") {
+    return warnings;
+  }
+
+  const configContext = await loadMutationWhenConfigContext(appRoot);
+  const tenancyMode = normalizeModeToken(ensureObject(configContext).merged?.tenancyMode);
+  const runtimeDependencies = ensureObject(appPackageJson.dependencies);
+  const devDependencies = ensureObject(appPackageJson.devDependencies);
+  const hasWorkspacesCore = Boolean(
+    runtimeDependencies["@jskit-ai/workspaces-core"] || devDependencies["@jskit-ai/workspaces-core"]
+  );
+
+  if (isWorkspaceCapableTenancyMode(tenancyMode) && !hasWorkspacesCore) {
+    warnings.push(
+      `users-core selected the workspace users scaffold because config.tenancyMode is "${tenancyMode}". ` +
+      'Install @jskit-ai/workspaces-core so the app gets the required "app" and "admin" surfaces and workspace helpers.'
+    );
+  }
+
+  return warnings;
+}
+
 function resolveManagedSourceRecord(packageEntry, existingInstall = {}) {
   const existingSource = ensureObject(existingInstall.source);
   if (Object.keys(existingSource).length > 0) {
@@ -462,7 +503,10 @@ async function applyPackageInstall({
     managedRecord.managed.migrations,
     touchedFiles,
     mutationWarnings,
-    ensureArray(existingManaged.files)
+    ensureArray(existingManaged.files),
+    {
+      reapplyManagedAppFiles: Object.keys(existingInstall).length > 0
+    }
   );
 
   await applyTextMutations(
@@ -483,6 +527,12 @@ async function applyPackageInstall({
     touchedFiles
   );
 
+  mutationWarnings.push(...await collectInstallWarnings({
+    packageEntry,
+    appRoot,
+    appPackageJson
+  }));
+
   if (generatorPackage) {
     delete lock.installedPackages[packageEntry.packageId];
   } else {

package/src/server/commandHandlers/appCommandCatalog.js

@@ -5,7 +5,7 @@ const APP_SCRIPT_WRAPPERS = Object.freeze({
   release: "jskit app release"
 });
 
-const LEGACY_APP_SCRIPT_VALUES = Object.freeze({
+const COPIED_APP_SCRIPT_VALUES = Object.freeze({
   verify: Object.freeze([
     "npm run lint && npm run test && npm run test:client && npm run build && npx jskit doctor"
   ]),
@@ -20,7 +20,7 @@ const LEGACY_APP_SCRIPT_VALUES = Object.freeze({
   ])
 });
 
-const LEGACY_APP_SCRIPT_FILES = Object.freeze([
+const COPIED_APP_SCRIPT_FILES = Object.freeze([
   "scripts/update-jskit-packages.sh",
   "scripts/link-local-jskit-packages.sh",
   "scripts/release.sh"
@@ -120,7 +120,7 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
   }),
   "adopt-managed-scripts": Object.freeze({
     name: "adopt-managed-scripts",
-    summary: "Rewrite legacy scaffolded maintenance scripts to the modern jskit app wrappers.",
+    summary: "Rewrite copied scaffolded maintenance scripts to the managed jskit app wrappers.",
     usage: "jskit app adopt-managed-scripts [--dry-run] [--force]",
     options: Object.freeze([
       Object.freeze({
@@ -129,13 +129,13 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
       }),
       Object.freeze({
         label: "--force",
-        description: "Replace customized script values too, and remove the legacy copied maintenance scripts if they exist."
+        description: "Replace customized script values too, and remove copied maintenance scripts if they exist."
       })
     ]),
     defaults: Object.freeze([
       "Known scaffolded script values are rewritten automatically.",
       "Customized script values are reported and left alone unless --force is used.",
-      "This command is the migration path for existing apps that still carry copied JSKIT maintenance scripts."
+      "This command is for apps that still carry copied JSKIT maintenance scripts."
     ])
   })
 });
@@ -190,8 +190,8 @@ function buildAppCommandOptionMeta(subcommandName = "") {
 
 export {
   APP_SCRIPT_WRAPPERS,
-  LEGACY_APP_SCRIPT_VALUES,
-  LEGACY_APP_SCRIPT_FILES,
+  COPIED_APP_SCRIPT_VALUES,
+  COPIED_APP_SCRIPT_FILES,
   APP_COMMAND_DEFINITIONS,
   listAppCommandDefinitions,
   resolveAppCommandDefinition,

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

@@ -2,8 +2,8 @@ import path from "node:path";
 import { rm } from "node:fs/promises";
 import {
   APP_SCRIPT_WRAPPERS,
-  LEGACY_APP_SCRIPT_FILES,
-  LEGACY_APP_SCRIPT_VALUES
+  COPIED_APP_SCRIPT_FILES,
+  COPIED_APP_SCRIPT_VALUES
 } from "../appCommandCatalog.js";
 import { fileExists, isTruthyFlag } from "./shared.js";
 
@@ -22,10 +22,10 @@ function shouldRewriteScript(currentValue = "", scriptName = "", force = false)
       reason: "already-current"
     };
   }
-  if ((LEGACY_APP_SCRIPT_VALUES[scriptName] || []).includes(normalizedCurrentValue)) {
+  if ((COPIED_APP_SCRIPT_VALUES[scriptName] || []).includes(normalizedCurrentValue)) {
     return {
       rewrite: true,
-      reason: "legacy"
+      reason: "copied"
     };
   }
   if (force) {
@@ -84,12 +84,12 @@ async function runAppAdoptManagedScriptsCommand(ctx = {}, { appRoot = "", option
     });
   }
 
-  const removableLegacyFiles = [];
+  const removableCopiedFiles = [];
   if (force) {
-    for (const relativePath of LEGACY_APP_SCRIPT_FILES) {
+    for (const relativePath of COPIED_APP_SCRIPT_FILES) {
       const absolutePath = path.join(appRoot, relativePath);
       if (await fileExists(absolutePath)) {
-        removableLegacyFiles.push({
+        removableCopiedFiles.push({
           relativePath,
           absolutePath
         });
@@ -102,12 +102,12 @@ async function runAppAdoptManagedScriptsCommand(ctx = {}, { appRoot = "", option
   }
 
   if (!dryRun && force) {
-    for (const { absolutePath } of removableLegacyFiles) {
+    for (const { absolutePath } of removableCopiedFiles) {
       await rm(absolutePath, { recursive: true, force: true });
     }
   }
 
-  if (changedScripts.length < 1 && skippedScripts.length < 1 && removableLegacyFiles.length < 1) {
+  if (changedScripts.length < 1 && skippedScripts.length < 1 && removableCopiedFiles.length < 1) {
     stdout.write("[adopt-managed-scripts] package.json already uses the managed JSKIT wrappers.\n");
     return 0;
   }
@@ -118,7 +118,7 @@ async function runAppAdoptManagedScriptsCommand(ctx = {}, { appRoot = "", option
   for (const record of skippedScripts) {
     stdout.write(`[adopt-managed-scripts] kept customized script ${record.scriptName}: ${record.currentValue}\n`);
   }
-  for (const record of removableLegacyFiles) {
+  for (const record of removableCopiedFiles) {
     stdout.write(`[adopt-managed-scripts] ${dryRun ? "would remove" : "removed"} ${record.relativePath}\n`);
   }
 

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

@@ -128,16 +128,33 @@ async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd,
       warnings: migrationWarnings
     }, null, 2)}\n`);
   } else {
-    io.stdout.write(`Generated migrations (${scope}).\n`);
-    io.stdout.write(`Resolved packages (${requestedPackageIds.length}):\n`);
-    for (const packageId of requestedPackageIds) {
-      io.stdout.write(`- ${packageId}\n`);
+    io.stdout.write(`Generated managed migrations (${scope}).\n`);
+    io.stdout.write(`Packages needing migration sync (${requestedPackageIds.length}):\n`);
+    if (requestedPackageIds.length > 0) {
+      for (const packageId of requestedPackageIds) {
+        io.stdout.write(`- ${packageId}\n`);
+      }
+    } else {
+      io.stdout.write("- none\n");
+      io.stdout.write(
+        "  Installed packages are already migration-synced, or they do not ship JSKIT-managed migrations.\n"
+      );
     }
-    io.stdout.write(`Touched files (${touchedFileList.length}):\n`);
-    for (const touchedFile of touchedFileList) {
-      io.stdout.write(`- ${touchedFile}\n`);
+
+    io.stdout.write(`Migration files written (${touchedFileList.length}):\n`);
+    if (touchedFileList.length > 0) {
+      for (const touchedFile of touchedFileList) {
+        io.stdout.write(`- ${touchedFile}\n`);
+      }
+    } else {
+      io.stdout.write("- none\n");
+      io.stdout.write("  No managed migration files were written in this run.\n");
     }
+
     io.stdout.write(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}\n`);
+    io.stdout.write(
+      "Reminder: this command only writes or refreshes JSKIT-managed migration files. Run `npm run db:migrate` separately to apply pending migrations to the database.\n"
+    );
     if (options.verbose && migrationWarnings.length > 0) {
       io.stdout.write(`Warnings (${migrationWarnings.length}):\n`);
       for (const warning of migrationWarnings) {