@jskit-ai/crud-ui-generator 0.1.15 → 0.1.17

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-ui-generator",
-  version: "0.1.15",
+  version: "0.1.17",
   kind: "generator",
   description: "Generate CRUD route trees from resource validators at an explicit route root relative to src/pages/.",
   options: {
@@ -24,6 +24,8 @@ export default Object.freeze({
       required: false,
       inputType: "text",
       defaultValue: "list,view,new,edit",
+      validationType: "csv-enum",
+      allowedValues: ["list", "view", "new", "edit"],
       promptLabel: "Operations",
       promptHint: "Optional comma-separated values from: list, view, new, edit. Defaults to all four."
     },
@@ -53,7 +55,15 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Link placement",
-      promptHint: "Optional host:position override for the generated list-page link placement."
+      promptHint: "Optional target override for the generated list-page link placement (format: host:position)."
+    },
+    "link-component-token": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Link component token",
+      promptHint:
+        "Optional component token override for the generated list-page link placement (example: local.main.ui.tab-link-item)."
     },
     namespace: {
       required: false,
@@ -80,10 +90,11 @@ export default Object.freeze({
     generatorPrimarySubcommand: "crud",
     generatorSubcommands: {
       crud: {
+        requiresShellWeb: true,
         description: "Create CRUD pages at an explicit route root relative to src/pages/.",
         longDescription: [
           "CRUD generation follows the same page-placement model as `ui-generator page`.",
-          "That means the generated list page link uses the same nearest-parent-host inference, tab-link inference, and relative `props.to` inference as a normal generated page. If you want the detailed host behavior, read `jskit generate ui-generator page help`."
+          "That means the generated list page link uses the same nearest-parent-target inference, tab-link inference, and relative `props.to` inference as a normal generated page. If you want the detailed target behavior, read `jskit generate ui-generator page help`."
         ],
         positionalArgs: [
           {
@@ -92,7 +103,16 @@ export default Object.freeze({
             descriptionKey: "crud-target-root"
           }
         ],
-        optionNames: ["resource-file", "operations", "display-fields", "id-param", "link-placement", "namespace", "force"],
+        optionNames: [
+          "resource-file",
+          "operations",
+          "display-fields",
+          "id-param",
+          "link-placement",
+          "link-component-token",
+          "namespace",
+          "force"
+        ],
         requiredOptionNames: ["resource-file"],
         createTarget: {
           pathTemplate: "src/pages/${option:target-root|trim}",
@@ -127,6 +147,7 @@ export default Object.freeze({
         ]
       },
       field: {
+        requiresShellWeb: true,
         entrypoint: "src/server/subcommands/addField.js",
         export: "runGeneratorSubcommand"
       }
@@ -147,7 +168,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.47"
+        "@jskit-ai/users-web": "0.1.49"
       },
       dev: {}
     },
@@ -332,7 +353,7 @@ export default Object.freeze({
         position: "bottom",
         skipIfContains: "__JSKIT_UI_MENU_MARKER__",
         value:
-          "\n// __JSKIT_UI_MENU_MARKER__\n{\n  addPlacement({\n    id: \"__JSKIT_UI_MENU_PLACEMENT_ID__\",\n    host: \"__JSKIT_UI_MENU_PLACEMENT_HOST__\",\n    position: \"__JSKIT_UI_MENU_PLACEMENT_POSITION__\",\n    surfaces: [\"__JSKIT_UI_SURFACE_ID__\"],\n    order: 155,\n    componentToken: \"__JSKIT_UI_MENU_COMPONENT_TOKEN__\",\n    props: {\n      label: \"__JSKIT_UI_MENU_LABEL__\",\n      surface: \"__JSKIT_UI_SURFACE_ID__\",\n      workspaceSuffix: \"__JSKIT_UI_MENU_WORKSPACE_SUFFIX__\",\n      nonWorkspaceSuffix: \"__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__\",\n__JSKIT_UI_MENU_TO_PROP_LINE__    },\n    when: ({ auth }) => Boolean(auth?.authenticated)\n  });\n}\n",
+          "\n// __JSKIT_UI_MENU_MARKER__\n{\n  addPlacement({\n    id: \"__JSKIT_UI_MENU_PLACEMENT_ID__\",\n    target: \"__JSKIT_UI_MENU_PLACEMENT_TARGET__\",\n    surfaces: [\"__JSKIT_UI_SURFACE_ID__\"],\n    order: 155,\n    componentToken: \"__JSKIT_UI_MENU_COMPONENT_TOKEN__\",\n    props: {\n      label: \"__JSKIT_UI_MENU_LABEL__\",\n      surface: \"__JSKIT_UI_SURFACE_ID__\",\n      workspaceSuffix: \"__JSKIT_UI_MENU_WORKSPACE_SUFFIX__\",\n      nonWorkspaceSuffix: \"__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__\",\n__JSKIT_UI_MENU_TO_PROP_LINE__    },\n__JSKIT_UI_MENU_WHEN_LINE__  });\n}\n",
         reason: "Append generated CRUD list-page placement.",
         category: "crud-ui-generator",
         id: "crud-ui-placement-menu",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jskit-ai/crud-ui-generator",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.40",
-    "@jskit-ai/kernel": "0.1.32"
+    "@jskit-ai/crud-core": "0.1.42",
+    "@jskit-ai/kernel": "0.1.34"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"

package/src/server/buildTemplateContext.js

@@ -24,13 +24,38 @@ import {
   buildListRowColumns,
   buildViewColumns,
   buildFormColumns,
+  resolveRecordIdFieldKey,
   renderObjectPushLines,
   resolveRecordChangedEventName,
   resolveRecordIdExpression
 } from "./resourceSupport.js";
+import descriptor from "../../package.descriptor.mjs";
 
-const ALLOWED_OPERATIONS = new Set(["list", "view", "new", "edit"]);
-const DEFAULT_OPERATIONS = "list,view,new,edit";
+const DEFAULT_ALLOWED_OPERATIONS = Object.freeze(["list", "view", "new", "edit"]);
+function resolveAllowedValues(schema = {}, fallbackValues = []) {
+  const resolvedValues = [];
+  const seen = new Set();
+  for (const rawValue of Array.isArray(schema?.allowedValues) ? schema.allowedValues : []) {
+    const value = normalizeText(typeof rawValue === "string" ? rawValue : rawValue?.value).toLowerCase();
+    if (!value || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    resolvedValues.push(value);
+  }
+  if (resolvedValues.length > 0) {
+    return Object.freeze(resolvedValues);
+  }
+  return Object.freeze(
+    (Array.isArray(fallbackValues) ? fallbackValues : [])
+      .map((value) => normalizeText(value).toLowerCase())
+      .filter(Boolean)
+  );
+}
+
+const OPERATION_VALUES = resolveAllowedValues(descriptor?.options?.operations, DEFAULT_ALLOWED_OPERATIONS);
+const ALLOWED_OPERATIONS = new Set(OPERATION_VALUES);
+const DEFAULT_OPERATIONS = normalizeText(descriptor?.options?.operations?.defaultValue) || OPERATION_VALUES.join(",");
 const DEFAULT_LIST_HIDDEN_FIELD_KEYS = new Set(["createdAt", "updatedAt"]);
 const DEFAULT_FORM_COMPONENT_FILE = "CrudAddEditForm.vue";
 const DEFAULT_FORM_FIELDS_FILE = "CrudAddEditFormFields.js";
@@ -160,7 +185,7 @@ function parseOperationsOption(options) {
   const unique = new Set();
   for (const operation of operations) {
     if (!ALLOWED_OPERATIONS.has(operation)) {
-      throw new Error('crud-ui-generator option "operations" supports only: list, view, new, edit.');
+      throw new Error(`crud-ui-generator option "operations" supports only: ${OPERATION_VALUES.join(", ")}.`);
     }
     unique.add(operation);
   }
@@ -233,14 +258,20 @@ function filterDisplayFields(selectedFieldKeys, fields) {
   });
 }
 
-function filterDefaultHiddenListFields(selectedFieldKeys, fields) {
+function filterDefaultHiddenListFields(selectedFieldKeys, fields, { recordIdFieldKey = "" } = {}) {
   const selectedFields = Array.isArray(selectedFieldKeys) ? selectedFieldKeys : [];
   const availableFields = Array.isArray(fields) ? fields : [];
   if (selectedFields.length > 0) {
     return availableFields;
   }
 
-  return availableFields.filter((field) => !DEFAULT_LIST_HIDDEN_FIELD_KEYS.has(normalizeText(field?.key)));
+  const hiddenFieldKeys = new Set(DEFAULT_LIST_HIDDEN_FIELD_KEYS);
+  const normalizedRecordIdFieldKey = normalizeText(recordIdFieldKey);
+  if (normalizedRecordIdFieldKey) {
+    hiddenFieldKeys.add(normalizedRecordIdFieldKey);
+  }
+
+  return availableFields.filter((field) => !hiddenFieldKeys.has(normalizeText(field?.key)));
 }
 
 function ensureFields(fields, fallbackFields = createFieldDefinitions({})) {
@@ -408,10 +439,16 @@ async function buildUiTemplateContext({ appRoot, options } = {}) {
     validateDisplayFieldsForOperation(selectedDisplayFields, editFieldsAll, "patch");
   }
 
+  const listRecordIdFieldKey = hasListOperation
+    ? resolveRecordIdFieldKey(listFieldsAll)
+    : "";
+
   const listFields = hasListOperation
     ? filterDisplayFields(
       selectedDisplayFields,
-      filterDefaultHiddenListFields(selectedDisplayFields, ensureFields(listFieldsAll))
+      filterDefaultHiddenListFields(selectedDisplayFields, ensureFields(listFieldsAll), {
+        recordIdFieldKey: listRecordIdFieldKey
+      })
     )
     : createFieldDefinitions({});
   const viewFields = hasViewOperation
@@ -441,6 +478,7 @@ async function buildUiTemplateContext({ appRoot, options } = {}) {
       pageTarget,
       targetFile: listTargetFile,
       placement: options?.["link-placement"],
+      componentToken: options?.["link-component-token"],
       context: "crud-ui-generator"
     })
     : null;
@@ -478,11 +516,11 @@ async function buildUiTemplateContext({ appRoot, options } = {}) {
     __JSKIT_UI_EDIT_FORM_FIELD_PUSH_LINES__: renderObjectPushLines("UI_EDIT_FORM_FIELDS", editFields),
     __JSKIT_UI_MENU_MARKER__: menuMarker,
     __JSKIT_UI_MENU_PLACEMENT_ID__: String(pageLinkTarget?.pageTarget?.placementId || ""),
-    __JSKIT_UI_MENU_PLACEMENT_HOST__: String(pageLinkTarget?.placementTarget?.host || ""),
-    __JSKIT_UI_MENU_PLACEMENT_POSITION__: String(pageLinkTarget?.placementTarget?.position || ""),
+    __JSKIT_UI_MENU_PLACEMENT_TARGET__: String(pageLinkTarget?.placementTarget?.id || ""),
     __JSKIT_UI_MENU_COMPONENT_TOKEN__: String(pageLinkTarget?.componentToken || ""),
     __JSKIT_UI_MENU_WORKSPACE_SUFFIX__: String(pageLinkTarget?.pageTarget?.routeUrlSuffix || ""),
     __JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__: String(pageLinkTarget?.pageTarget?.routeUrlSuffix || ""),
+    __JSKIT_UI_MENU_WHEN_LINE__: String(pageLinkTarget?.whenLine || ""),
     __JSKIT_UI_MENU_TO_PROP_LINE__: resolveMenuToPropLine(pageLinkTarget?.linkTo || ""),
     __JSKIT_UI_MENU_LABEL__: pageTarget.defaultName
   };

package/src/server/resourceSupport.js

@@ -1,10 +1,10 @@
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { resolveCrudRecordChangedEvent } from "@jskit-ai/crud-core/shared/crudNamespaceSupport";
 import {
   checkCrudLookupFormControl,
   isCrudRuntimeOutputOnlyFieldKey
 } from "@jskit-ai/crud-core/shared/crudFieldMetaSupport";
+import { importFreshModuleFromAbsolutePath } from "@jskit-ai/kernel/server/support";
 import {
   normalizeCrudLookupApiPath,
   normalizeCrudLookupNamespace,
@@ -64,7 +64,7 @@ async function loadResourceDefinition({
 
   let moduleNamespace = null;
   try {
-    moduleNamespace = await import(`${pathToFileURL(resourceModulePath).href}?t=${Date.now()}_${Math.random()}`);
+    moduleNamespace = await importFreshModuleFromAbsolutePath(resourceModulePath);
   } catch (error) {
     throw new Error(
       `${context} could not load resource file "${resourceFile}": ${String(error?.message || error || "unknown error")}`
@@ -885,6 +885,20 @@ function buildFormColumns(fields = []) {
     .join("\n");
 }
 
+function resolveRecordIdFieldKey(fields = []) {
+  const normalizedFields = Array.isArray(fields) ? fields : [];
+  const preferred =
+    normalizedFields.find((field) => normalizeText(field?.key).toLowerCase() === "id") ||
+    normalizedFields.find((field) => {
+      const key = normalizeText(field?.key).toLowerCase();
+      return key.endsWith("id") || key.endsWith("_id") || key.endsWith("-id");
+    }) ||
+    normalizedFields[0] ||
+    { key: "id" };
+
+  return normalizeText(preferred?.key) || "id";
+}
+
 function renderObjectPushLines(arrayName, entries = []) {
   const normalizedArrayName = normalizeText(arrayName);
   if (!normalizedArrayName) {
@@ -903,17 +917,7 @@ function renderObjectPushLines(arrayName, entries = []) {
 }
 
 function resolveRecordIdExpression(fields = []) {
-  const normalizedFields = Array.isArray(fields) ? fields : [];
-  const preferred =
-    normalizedFields.find((field) => normalizeText(field?.key).toLowerCase() === "id") ||
-    normalizedFields.find((field) => {
-      const key = normalizeText(field?.key).toLowerCase();
-      return key.endsWith("id") || key.endsWith("_id") || key.endsWith("-id");
-    }) ||
-    normalizedFields[0] ||
-    { key: "id" };
-
-  return toAccessorExpression("item", preferred.key);
+  return toAccessorExpression("item", resolveRecordIdFieldKey(fields));
 }
 
 export {
@@ -936,6 +940,7 @@ export {
   buildListRowColumns,
   buildViewColumns,
   buildFormColumns,
+  resolveRecordIdFieldKey,
   renderObjectPushLines,
   resolveCrudRecordChangedEvent as resolveRecordChangedEventName,
   resolveRecordIdExpression

package/test/buildTemplateContext.test.js

@@ -24,9 +24,16 @@ async function withTempApp(run) {
       path.join(appRoot, "src", "components", "ShellLayout.vue"),
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="top-right" />
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
-    <ShellOutlet host="shell-layout" position="secondary-menu" />
+    <ShellOutlet target="shell-layout:top-right" />
+    <ShellOutlet
+      target="shell-layout:primary-menu"
+      default
+      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+    />
+    <ShellOutlet
+      target="shell-layout:secondary-menu"
+      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+    />
   </div>
 </template>
 `,
@@ -248,16 +255,50 @@ test("buildUiTemplateContext derives CRUD placeholders from the explicit target-
     assert.equal(context.__JSKIT_UI_HAS_VIEW_ROUTE__, "true");
     assert.equal(context.__JSKIT_UI_HAS_NEW_ROUTE__, "true");
     assert.equal(context.__JSKIT_UI_HAS_EDIT_ROUTE__, "true");
+    assert.equal(context.__JSKIT_UI_MENU_WHEN_LINE__, "");
+    assert.doesNotMatch(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /Id/);
+    assert.doesNotMatch(context.__JSKIT_UI_LIST_ROW_COLUMNS__, /record\.id/);
     assert.match(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /First Name/);
     assert.match(context.__JSKIT_UI_LIST_ROW_COLUMNS__, /record\.firstName/);
     assert.match(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\?\.firstName/);
     assert.match(context.__JSKIT_UI_CREATE_FORM_COLUMNS__, /formRuntime\.form\.firstName/);
     assert.match(context.__JSKIT_UI_EDIT_FORM_COLUMNS__, /formRuntime\.form\.email/);
     assert.equal(context.__JSKIT_UI_RECORD_CHANGED_EVENT__, "\"customers.record.changed\"");
+    assert.equal(context.__JSKIT_UI_LIST_RECORD_ID_EXPR__, "item.id");
     assert.equal(context.__JSKIT_UI_VIEW_TITLE_FALLBACK_FIELD_KEY__, "\"firstName\"");
   });
 });
 
+test("buildUiTemplateContext derives menu auth visibility from the target surface policy", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFile(
+      path.join(appRoot, "config", "public.js"),
+      `export const config = {
+  surfaceAccessPolicies: {
+    authenticated: {
+      requireAuth: true
+    }
+  },
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "app", enabled: true, accessPolicyId: "authenticated" }
+  }
+};
+`,
+      "utf8"
+    );
+    await writeResource(appRoot, RESOURCE_FILE, FULL_RESOURCE_SOURCE);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: createOptions({
+        "target-root": "app/customers"
+      })
+    });
+
+    assert.equal(context.__JSKIT_UI_MENU_WHEN_LINE__, "    when: ({ auth }) => Boolean(auth?.authenticated)\n");
+  });
+});
+
 test("buildUiTemplateContext falls back to target-root leaf for namespace when resource.resource is missing", async () => {
   await withTempApp(async (appRoot) => {
     await writeResource(
@@ -299,6 +340,23 @@ test("buildUiTemplateContext filters rendered fields when display-fields is prov
   });
 });
 
+test("buildUiTemplateContext keeps an explicitly requested id display field", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeResource(appRoot, RESOURCE_FILE, FULL_RESOURCE_SOURCE);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: createOptions({
+        operations: "list,view",
+        "display-fields": "id,firstName"
+      })
+    });
+
+    assert.match(context.__JSKIT_UI_LIST_HEADER_COLUMNS__, /Id/);
+    assert.match(context.__JSKIT_UI_LIST_ROW_COLUMNS__, /record\.id/);
+  });
+});
+
 test("buildUiTemplateContext maps lookup metadata into form field definitions", async () => {
   await withTempApp(async (appRoot) => {
     await writeResource(appRoot, RESOURCE_FILE, LOOKUP_RESOURCE_SOURCE);
@@ -325,9 +383,8 @@ test("buildUiTemplateContext resolves list placement from the app default shell
     });
 
     assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_ID__, "ui-generator.page.admin.customers.link");
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "shell-layout");
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "primary-menu");
-    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "users.web.shell.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_TARGET__, "shell-layout:primary-menu");
+    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
     assert.equal(context.__JSKIT_UI_MENU_WORKSPACE_SUFFIX__, "/customers");
     assert.equal(context.__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__, "/customers");
     assert.equal(context.__JSKIT_UI_MENU_TO_PROP_LINE__, "");
@@ -345,7 +402,7 @@ test("buildUiTemplateContext infers tab placement and relative link-to from the
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="catalog" position="sub-pages" />
+      <ShellOutlet target="catalog:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -360,14 +417,44 @@ test("buildUiTemplateContext infers tab placement and relative link-to from the
       })
     });
 
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "catalog");
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "sub-pages");
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_TARGET__, "catalog:sub-pages");
     assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
     assert.equal(context.__JSKIT_UI_MENU_TO_PROP_LINE__, "      to: \"./products\",\n");
     assert.equal(context.__JSKIT_UI_MENU_WORKSPACE_SUFFIX__, "/catalog/products");
   });
 });
 
+test("buildUiTemplateContext prefers an outlet-declared default link token over subpage heuristics", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeResource(appRoot, RESOURCE_FILE, FULL_RESOURCE_SOURCE);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/settings.vue",
+      `<template>
+  <section>
+    <ShellOutlet
+      target="admin-settings:primary-menu"
+      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+    />
+    <RouterView />
+  </section>
+</template>
+`
+    );
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: createOptions({
+        "target-root": "admin/settings/customers"
+      })
+    });
+
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_TARGET__, "admin-settings:primary-menu");
+    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_MENU_TO_PROP_LINE__, "      to: \"./customers\",\n");
+  });
+});
+
 test("buildUiTemplateContext honors explicit link-placement override", async () => {
   await withTempApp(async (appRoot) => {
     await writeResource(appRoot, RESOURCE_FILE, FULL_RESOURCE_SOURCE);
@@ -379,25 +466,24 @@ test("buildUiTemplateContext honors explicit link-placement override", async ()
       })
     });
 
-    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "secondary-menu");
-    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "users.web.shell.surface-aware-menu-link-item");
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_TARGET__, "shell-layout:secondary-menu");
+    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.surface-aware-menu-link-item");
   });
 });
 
-test("buildUiTemplateContext rejects target-roots with a src/pages prefix", async () => {
+test("buildUiTemplateContext accepts target-roots with a src/pages prefix", async () => {
   await withTempApp(async (appRoot) => {
     await writeResource(appRoot, RESOURCE_FILE, FULL_RESOURCE_SOURCE);
 
-    await assert.rejects(
-      () =>
-        buildUiTemplateContext({
-          appRoot,
-          options: createOptions({
-            "target-root": "src/pages/admin/customers"
-          })
-        }),
-      /must be relative to src\/pages\/, without the src\/pages\/ prefix/
-    );
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: createOptions({
+        "target-root": "src/pages/admin/customers"
+      })
+    });
+
+    assert.equal(context.__JSKIT_UI_SURFACE_ID__, "admin");
+    assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_ID__, "ui-generator.page.admin.customers.link");
   });
 });
 

package/test/packageDescriptor.test.js

@@ -0,0 +1,14 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import descriptor from "../package.descriptor.mjs";
+
+test("crud-ui-generator operations option exposes structured csv-enum metadata", () => {
+  assert.equal(descriptor.kind, "generator");
+  assert.equal(descriptor.options?.operations?.validationType, "csv-enum");
+  assert.deepEqual(
+    descriptor.options?.operations?.allowedValues,
+    ["list", "view", "new", "edit"]
+  );
+  assert.equal(descriptor.options?.operations?.defaultValue, "list,view,new,edit");
+  assert.equal(descriptor.metadata?.generatorSubcommands?.crud?.optionNames?.includes("operations"), true);
+});

package/README.md

@@ -1,67 +0,0 @@
-# @jskit-ai/crud-ui-generator
-
-Generate CRUD route trees from an explicit route root relative to `src/pages/...`.
-
-## Mental Model
-
-This generator follows the same file-driven model as `@jskit-ai/ui-generator`.
-
-- You point at one explicit route root relative to `src/pages/...`.
-- The surface is derived from that path.
-- The visible route URL is derived from that path.
-- The generated list-page link placement is inferred from the nearest real parent subpages host when there is one.
-- Explicit overrides still exist, but they are not required for the normal case.
-
-## Command
-
-```bash
-npx jskit generate @jskit-ai/crud-ui-generator crud \
-  admin/catalog/index/products \
-  --resource-file packages/products/src/shared/productResource.js
-```
-
-That generates:
-
-- `src/pages/admin/catalog/index/products/index.vue`
-- `src/pages/admin/catalog/index/products/[recordId]/index.vue`
-- `src/pages/admin/catalog/index/products/new.vue`
-- `src/pages/admin/catalog/index/products/[recordId]/edit.vue`
-- `src/pages/admin/catalog/index/products/_components/...`
-
-## Defaults
-
-From the explicit `target-root`, the generator derives:
-
-- the owning surface
-- the visible CRUD route
-- the default list-page placement target
-- the default link component token
-- the default relative `to` for nested subpage links
-
-The generated list-page link follows the same parent-host inference as `@jskit-ai/ui-generator page`.
-
-If you want the detailed behavior, read:
-
-- `npx jskit generate ui-generator page help`
-
-That is where the parent-host, tab-link, and relative `to` behavior is explained.
-
-## Options
-
-- `--resource-file`: required resource module path relative to the app root
-- `--operations`: optional comma-separated subset of `list,view,new,edit`, defaulting to all four
-- `--display-fields`: optional comma-separated subset of fields to render
-- `--id-param`: optional route param name for record pages, default `recordId`
-- `--link-placement`: optional link placement override for the generated list page
-- `--namespace`: optional CRUD namespace override when the resource module does not expose `resource.resource`
-
-## Route Roots
-
-Use the real route root you want in the app:
-
-- index-route parent child: `admin/catalog/index/products`
-- nested under a record view page: `admin/customers/[customerId]/index/pets`
-- file-route parent child: `admin/customers/[customerId]/orders`
-- top-level route: `admin/products`
-
-There is no separate `surface`, `directory-prefix`, `route-path`, or `container` assembly step anymore.