@jskit-ai/crud-server-generator 0.1.71 → 0.1.72

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-server-generator",
-  version: "0.1.71",
+  version: "0.1.72",
   kind: "generator",
   description: "CRUD server generator with routes, actions, and persistence scaffolding.",
   options: {
@@ -56,6 +56,13 @@ export default Object.freeze({
       defaultValue: "",
       promptLabel: "Force overwrite",
       promptHint: "Overwrite generated scaffold files if the namespace package directory already exists."
+    },
+    internal: {
+      required: false,
+      inputType: "flag",
+      defaultValue: "",
+      promptLabel: "Internal HTTP routes",
+      promptHint: "Mark generated CRUD HTTP routes as internal-only so they are not publicly registered."
     }
   },
   optionPolicies: {
@@ -103,7 +110,8 @@ export default Object.freeze({
           "table-name",
           "id-column",
           "directory-prefix",
-          "force"
+          "force",
+          "internal"
         ],
         createTarget: {
           pathTemplate: "packages/${option:namespace|kebab}",
@@ -152,14 +160,14 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/auth-core": "0.1.62",
-        "@jskit-ai/crud-core": "0.1.71",
-        "@jskit-ai/database-runtime": "0.1.63",
-        "@jskit-ai/http-runtime": "0.1.62",
-        "@jskit-ai/json-rest-api-core": "0.1.8",
-        "@jskit-ai/kernel": "0.1.63",
-        "@jskit-ai/realtime": "0.1.62",
-        "@jskit-ai/resource-crud-core": "0.1.8",
+        "@jskit-ai/auth-core": "0.1.63",
+        "@jskit-ai/crud-core": "0.1.72",
+        "@jskit-ai/database-runtime": "0.1.64",
+        "@jskit-ai/http-runtime": "0.1.63",
+        "@jskit-ai/json-rest-api-core": "0.1.9",
+        "@jskit-ai/kernel": "0.1.64",
+        "@jskit-ai/realtime": "0.1.63",
+        "@jskit-ai/resource-crud-core": "0.1.9",
         "@local/${option:namespace|kebab}": "file:packages/${option:namespace|kebab}"
       },
       dev: {}
@@ -194,7 +202,11 @@ export default Object.freeze({
         to: "packages/${option:namespace|kebab}/package.descriptor.mjs",
         reason: "Install app-local CRUD package descriptor.",
         category: "crud",
-        id: "crud-local-package-descriptor-${option:namespace|snake}"
+        id: "crud-local-package-descriptor-${option:namespace|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        }
       },
       {
         from: "templates/src/local-package/server/CrudProvider.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-server-generator",
-  "version": "0.1.71",
+  "version": "0.1.72",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -13,12 +13,12 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.2",
-    "@jskit-ai/crud-core": "0.1.71",
-    "@jskit-ai/database-runtime": "0.1.63",
-    "@jskit-ai/http-runtime": "0.1.62",
-    "@jskit-ai/json-rest-api-core": "0.1.8",
-    "@jskit-ai/kernel": "0.1.63",
-    "@jskit-ai/resource-crud-core": "0.1.8",
+    "@jskit-ai/crud-core": "0.1.72",
+    "@jskit-ai/database-runtime": "0.1.64",
+    "@jskit-ai/http-runtime": "0.1.63",
+    "@jskit-ai/json-rest-api-core": "0.1.9",
+    "@jskit-ai/kernel": "0.1.64",
+    "@jskit-ai/resource-crud-core": "0.1.9",
     "recast": "^0.23.11"
   }
 }

package/src/server/buildTemplateContext.js

@@ -15,6 +15,7 @@ import {
   loadAppConfigFromModuleUrl,
   resolveRequiredAppRoot
 } from "@jskit-ai/kernel/server/support";
+import { normalizeBoolean } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeCrudLookupNamespace } from "@jskit-ai/kernel/shared/support/crudLookup";
 import { toCamelCase, toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
 import descriptor from "../../package.descriptor.mjs";
@@ -78,6 +79,19 @@ function asRecord(value) {
   return value;
 }
 
+function resolveInternalRouteOption(options = {}) {
+  if (!Object.prototype.hasOwnProperty.call(options, "internal")) {
+    return false;
+  }
+  if (options.internal === "" || options.internal === true) {
+    return true;
+  }
+  if (options.internal === false) {
+    return false;
+  }
+  return normalizeBoolean(options.internal);
+}
+
 function normalizeRequestedOwnershipFilter(value, { strict = false } = {}) {
   const normalized = normalizeText(value).toLowerCase();
   if (OWNERSHIP_FILTER_VALUES.has(normalized)) {
@@ -1823,7 +1837,8 @@ function buildReplacementsFromSnapshot({
   snapshot,
   resolvedOwnershipFilter,
   surfaceRequiresWorkspace = true,
-  surfaceId = ""
+  surfaceId = "",
+  routeInternal = false
 }) {
   const requiresNamedPermissions = surfaceRequiresWorkspace === true;
   const scaffoldColumns = resolveScaffoldColumns(snapshot);
@@ -1888,6 +1903,7 @@ function buildReplacementsFromSnapshot({
     __JSKIT_CRUD_ROUTE_WORKSPACE_SUPPORT_IMPORTS__: renderRouteWorkspaceSupportImports({
       surfaceRequiresWorkspace
     }),
+    __JSKIT_CRUD_ROUTE_INTERNAL_LINE__: routeInternal === true ? "      internal: true," : "",
     __JSKIT_CRUD_ROUTE_CONTRACTS_RESOURCE_ARGS__: surfaceRequiresWorkspace ? ",\n  routeParamsValidator" : "",
     __JSKIT_CRUD_ROUTE_VALIDATOR_CONSTANTS__: renderRouteValidatorConstants({
       surfaceRequiresWorkspace
@@ -1969,7 +1985,8 @@ function createCacheKey({ appRoot, options }) {
       surface: normalizeText(options?.surface),
       ownershipFilter: normalizeText(options?.["ownership-filter"]),
       tableName: normalizeText(options?.["table-name"]),
-      idColumn: normalizeText(options?.["id-column"])
+      idColumn: normalizeText(options?.["id-column"]),
+      internal: resolveInternalRouteOption(options)
     }
   };
 
@@ -2010,13 +2027,15 @@ async function buildCrudTemplateContext(input = {}) {
     options,
     surface: resolvedSurface
   });
+  const routeInternal = resolveInternalRouteOption(options);
 
   return buildReplacementsFromSnapshot({
     namespace,
     snapshot,
     resolvedOwnershipFilter,
     surfaceRequiresWorkspace,
-    surfaceId: resolvedSurface
+    surfaceId: resolvedSurface,
+    routeInternal
   });
 }
 
@@ -2058,7 +2077,8 @@ const __testables = Object.freeze({
   renderActionInputExpressions,
   renderRouteValidatorConstants,
   renderRouteParamsValidatorLine,
-  renderRouteInputLines
+  renderRouteInputLines,
+  resolveInternalRouteOption
 });
 
 export {

package/templates/src/local-package/server/registerRoutes.js

@@ -38,6 +38,7 @@ function registerRoutes(
     {
       auth: "required",
       surface: normalizedRouteSurface,
+__JSKIT_CRUD_ROUTE_INTERNAL_LINE__
       visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
@@ -64,6 +65,7 @@ __JSKIT_CRUD_LIST_ROUTE_INPUT_LINES__
     {
       auth: "required",
       surface: normalizedRouteSurface,
+__JSKIT_CRUD_ROUTE_INTERNAL_LINE__
       visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
@@ -89,6 +91,7 @@ __JSKIT_CRUD_VIEW_ROUTE_INPUT_LINES__
     {
       auth: "required",
       surface: normalizedRouteSurface,
+__JSKIT_CRUD_ROUTE_INTERNAL_LINE__
       visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
@@ -114,6 +117,7 @@ __JSKIT_CRUD_CREATE_ROUTE_INPUT_LINES__
     {
       auth: "required",
       surface: normalizedRouteSurface,
+__JSKIT_CRUD_ROUTE_INTERNAL_LINE__
       visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],
@@ -139,6 +143,7 @@ __JSKIT_CRUD_UPDATE_ROUTE_INPUT_LINES__
     {
       auth: "required",
       surface: normalizedRouteSurface,
+__JSKIT_CRUD_ROUTE_INTERNAL_LINE__
       visibility: checkRouteVisibility(routeOwnershipFilter),
       meta: {
         tags: ["crud"],

package/test/buildTemplateContext.test.js

@@ -235,6 +235,43 @@ test("resolveOwnershipFilterForGeneration rejects explicit ownership filters whe
   );
 });
 
+test("buildReplacementsFromSnapshot renders an internal route line only when requested", () => {
+  const snapshot = createSnapshot();
+
+  const publicReplacements = __testables.buildReplacementsFromSnapshot({
+    namespace: "customers",
+    snapshot,
+    resolvedOwnershipFilter: "workspace_user",
+    surfaceRequiresWorkspace: true,
+    surfaceId: "admin",
+    routeInternal: false
+  });
+  const internalReplacements = __testables.buildReplacementsFromSnapshot({
+    namespace: "customers",
+    snapshot,
+    resolvedOwnershipFilter: "workspace_user",
+    surfaceRequiresWorkspace: true,
+    surfaceId: "admin",
+    routeInternal: true
+  });
+
+  assert.equal(publicReplacements.__JSKIT_CRUD_ROUTE_INTERNAL_LINE__, "");
+  assert.equal(internalReplacements.__JSKIT_CRUD_ROUTE_INTERNAL_LINE__, "      internal: true,");
+});
+
+test("resolveInternalRouteOption rejects invalid internal flag values instead of silently generating public routes", () => {
+  assert.throws(
+    () => __testables.resolveInternalRouteOption({ internal: "maybe" }),
+    /Boolean field must be true or false/
+  );
+});
+
+test("resolveInternalRouteOption treats an empty-string flag presence as true", () => {
+  assert.equal(__testables.resolveInternalRouteOption({ internal: "" }), true);
+  assert.equal(__testables.resolveInternalRouteOption({ internal: "true" }), true);
+  assert.equal(__testables.resolveInternalRouteOption({ internal: "false" }), false);
+});
+
 test("resolveCrudGenerationTableName defaults table-name from namespace", () => {
   assert.equal(
     __testables.resolveCrudGenerationTableName({

package/test/packageDescriptor.test.js

@@ -16,8 +16,10 @@ test("crud-server-generator surface option validates against enabled surface ids
     descriptor.options?.["table-name"]?.defaultFromOptionTemplate,
     "${option:namespace}"
   );
+  assert.equal(descriptor.options?.internal?.inputType, "flag");
   assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("surface"), true);
   assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("force"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("internal"), true);
   assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.createTarget?.pathTemplate, "packages/${option:namespace|kebab}");
 });
 
@@ -30,10 +32,17 @@ test("crud-server-generator no longer installs a separate jsonRestResource serve
 
 test("crud-server-generator wires action and role mutations through template context", () => {
   const files = descriptor.mutations?.files || [];
+  const descriptorTemplate = files.find((entry) => entry.from === "templates/src/local-package/package.descriptor.mjs");
   const actionsTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/actions.js");
   const routesTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/registerRoutes.js");
   const roleGrantMutation = (descriptor.mutations?.text || []).find((entry) => entry.file === "config/roles.js");
 
+  assert.ok(descriptorTemplate);
+  assert.deepEqual(descriptorTemplate.templateContext, {
+    entrypoint: "src/server/buildTemplateContext.js",
+    export: "buildTemplateContext"
+  });
+
   assert.ok(actionsTemplate);
   assert.deepEqual(actionsTemplate.templateContext, {
     entrypoint: "src/server/buildTemplateContext.js",

package/test/routeInputContracts.test.js

@@ -9,12 +9,17 @@ const nonWorkspaceFixture = await createTemplateServerFixture({
   surfaceRequiresWorkspace: false,
   requiresNamedPermissions: false
 });
+const internalFixture = await createTemplateServerFixture({
+  routeInternal: true
+});
 const { registerRoutes: registerWorkspaceRoutes } = await workspaceFixture.importServerModule("registerRoutes.js");
 const { registerRoutes: registerNonWorkspaceRoutes } = await nonWorkspaceFixture.importServerModule("registerRoutes.js");
+const { registerRoutes: registerInternalRoutes } = await internalFixture.importServerModule("registerRoutes.js");
 
 after(async () => {
   await workspaceFixture.cleanup();
   await nonWorkspaceFixture.cleanup();
+  await internalFixture.cleanup();
 });
 
 function createReplyDouble() {
@@ -436,3 +441,34 @@ test("crud view route forwards include query input", async () => {
     include: "vetId"
   });
 });
+
+test("crud routes mark every generated HTTP route as internal when requested", () => {
+  const registeredRoutes = [];
+  const router = {
+    register(method, path, route, handler) {
+      registeredRoutes.push({
+        method,
+        path,
+        route,
+        handler
+      });
+    }
+  };
+  const app = {
+    make(token) {
+      if (token !== "jskit.http.router") {
+        throw new Error(`Unexpected token: ${String(token)}`);
+      }
+      return router;
+    }
+  };
+
+  registerInternalRoutes(app, {
+    routeRelativePath: "/customers"
+  });
+
+  assert.equal(registeredRoutes.length, 5);
+  for (const route of registeredRoutes) {
+    assert.equal(route.route.internal, true);
+  }
+});

package/test-support/templateServerFixture.js

@@ -17,7 +17,8 @@ const CRUD_NAMESPACE = Object.freeze({
 function buildTemplateReplacements({
   surfaceRequiresWorkspace = true,
   requiresNamedPermissions = surfaceRequiresWorkspace === true,
-  surfaceId = surfaceRequiresWorkspace ? "admin" : "home"
+  surfaceId = surfaceRequiresWorkspace ? "admin" : "home",
+  routeInternal = false
 } = {}) {
   const routeWorkspaceSupportImports = surfaceRequiresWorkspace
     ? [
@@ -141,6 +142,7 @@ function buildTemplateReplacements({
     ["__JSKIT_CRUD_ROUTE_SURFACE_REQUIRES_WORKSPACE__", String(surfaceRequiresWorkspace === true)],
     ["__JSKIT_CRUD_ROUTE_BASE__", JSON.stringify(surfaceRequiresWorkspace ? "/w/:workspaceSlug" : "/")],
     ["__JSKIT_CRUD_ROUTE_WORKSPACE_SUPPORT_IMPORTS__", routeWorkspaceSupportImports],
+    ["__JSKIT_CRUD_ROUTE_INTERNAL_LINE__", routeInternal === true ? "      internal: true," : ""],
     ["__JSKIT_CRUD_ROUTE_CONTRACTS_RESOURCE_ARGS__", surfaceRequiresWorkspace ? ",\n  routeParamsValidator" : ""],
     ["__JSKIT_CRUD_ROUTE_VALIDATOR_CONSTANTS__", surfaceRequiresWorkspace
       ? [