@ultimat3/cli 27.9.0 → 27.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.9.0",
+  "version": "27.10.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.9.0",
-    "@ultimat3/admin": "27.9.0",
-    "@ultimat3/ai": "27.9.0",
-    "@ultimat3/auth": "27.9.0",
-    "@ultimat3/cache": "27.9.0",
-    "@ultimat3/core": "27.9.0",
-    "@ultimat3/db": "27.9.0",
-    "@ultimat3/entity": "27.9.0",
-    "@ultimat3/flags": "27.9.0",
-    "@ultimat3/http": "27.9.0",
-    "@ultimat3/i18n": "27.9.0",
-    "@ultimat3/jobs": "27.9.0",
-    "@ultimat3/mail": "27.9.0",
-    "@ultimat3/manifest": "27.9.0",
-    "@ultimat3/mcp": "27.9.0",
-    "@ultimat3/money": "27.9.0",
-    "@ultimat3/notify": "27.9.0",
-    "@ultimat3/policy": "27.9.0",
-    "@ultimat3/pwa": "27.9.0",
-    "@ultimat3/query": "27.9.0",
-    "@ultimat3/realtime": "27.9.0",
-    "@ultimat3/render": "27.9.0",
-    "@ultimat3/schema": "27.9.0",
-    "@ultimat3/seo": "27.9.0",
-    "@ultimat3/storage": "27.9.0",
-    "@ultimat3/testing": "27.9.0",
-    "@ultimat3/time": "27.9.0",
+    "@ultimat3/action": "27.10.0",
+    "@ultimat3/admin": "27.10.0",
+    "@ultimat3/ai": "27.10.0",
+    "@ultimat3/auth": "27.10.0",
+    "@ultimat3/cache": "27.10.0",
+    "@ultimat3/core": "27.10.0",
+    "@ultimat3/db": "27.10.0",
+    "@ultimat3/entity": "27.10.0",
+    "@ultimat3/flags": "27.10.0",
+    "@ultimat3/http": "27.10.0",
+    "@ultimat3/i18n": "27.10.0",
+    "@ultimat3/jobs": "27.10.0",
+    "@ultimat3/mail": "27.10.0",
+    "@ultimat3/manifest": "27.10.0",
+    "@ultimat3/mcp": "27.10.0",
+    "@ultimat3/money": "27.10.0",
+    "@ultimat3/notify": "27.10.0",
+    "@ultimat3/policy": "27.10.0",
+    "@ultimat3/pwa": "27.10.0",
+    "@ultimat3/query": "27.10.0",
+    "@ultimat3/realtime": "27.10.0",
+    "@ultimat3/render": "27.10.0",
+    "@ultimat3/schema": "27.10.0",
+    "@ultimat3/seo": "27.10.0",
+    "@ultimat3/storage": "27.10.0",
+    "@ultimat3/testing": "27.10.0",
+    "@ultimat3/time": "27.10.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-generate.ts

@@ -19,6 +19,7 @@ import { followUpEdits } from './generate-follow-ups';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { refusePluralTable } from './generate-plural';
+import { followReexports } from './generate-reexports';
 import { refuseShadowedTypes, refuseShadowedValues } from './generate-shadow';
 import { declaresOnlyOtherEntities } from './generate-sibling';
 import { containedPath, planWrites, writeFiles } from './generate-write';
@@ -90,6 +91,12 @@ export const generateCommand: CliCommand = {
     // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
     assertFeatureExists(root, kind, featureFlag, slice);
     const sliceErrors = await readSliceErrors(root, kind, slice);
+    // And its `policy.ts`, for the same two kinds and the same reason: the action imports from it.
+    const slicePolicy = await followReexports(
+      root,
+      slice,
+      await readSliceErrors(root, kind, slice, 'policy.ts'),
+    );
     // Same reason again: whether `job`/`task` may assume the tenant-scoped shape is a fact about
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
     const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
@@ -105,6 +112,7 @@ export const generateCommand: CliCommand = {
         name: planned,
         ...(featureFlag === undefined ? {} : { feature: featureFlag }),
         ...(sliceErrors === undefined ? {} : { sliceErrors }),
+        ...(slicePolicy === undefined ? {} : { slicePolicy }),
         ...(sliceEntity === undefined ? {} : { sliceEntity }),
         ...(sliceRepo === undefined ? {} : { sliceRepo }),
         ...(at === undefined ? {} : { at }),
@@ -321,9 +329,10 @@ async function readSliceErrors(
   root: string,
   kind: Generator,
   slice: string,
+  name: 'errors.ts' | 'policy.ts' = 'errors.ts',
 ): Promise<string | undefined> {
   if (kind !== 'action' && kind !== 'mutator') return undefined;
-  const file = containedPath(root, `${slice}/errors.ts`);
+  const file = containedPath(root, `${slice}/${name}`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
 

package/src/error-codes.ts

@@ -233,6 +233,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ISLAND_MODULE_DUPLICATED',
   'X_BACKFILL_SLICE_ENTITY',
   'X_LAYOUT_SIBLING_MODULE',
+  'X_SLICE_POLICY_INCOMPLETE',
 ] as const;
 
 /**
@@ -422,6 +423,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
   X_BACKFILL_SLICE_ENTITY: 'the slice holds no entity a generated backfill can sweep',
   X_LAYOUT_SIBLING_MODULE: 'a primitive module beside its directory',
+  X_SLICE_POLICY_INCOMPLETE: 'a generator needs an export the slice policy.ts does not declare',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/generate-files.ts

@@ -70,6 +70,8 @@ export interface GenerateOptions {
   readonly sliceEntity?: string;
   /** The same kinds: the slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
   readonly sliceRepo?: string;
+  /** `action` and `mutator`: the slice's `policy.ts` as it stands on disk, absent when it has none. */
+  readonly slicePolicy?: string;
   /**
    * The app's own db package, `@<app>/db` — what every generated `repo.ts` imports the typed handle
    * from. Supplied by `run` (`resolveDbModule`) for `catalogModule`'s reason: the name lives in a
@@ -152,6 +154,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         actionFiles(options.name, {
           ...target,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+          ...(options.slicePolicy === undefined ? {} : { slicePolicy: options.slicePolicy }),
           ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
           ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),
@@ -162,6 +165,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           ...target,
           mutator: true,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+          ...(options.slicePolicy === undefined ? {} : { slicePolicy: options.slicePolicy }),
           ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
           ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),

package/src/generate-reexports.ts

@@ -0,0 +1,40 @@
+// Single responsibility: reading a slice module's relative `export * from './x'` targets off the
+// app's disk, one level deep, so a barrel is judged by what it really exports.
+
+// why: Bun has no synchronous "is this a FILE": a directory passes `existsSync`, and reading one
+// as a file is an uncoded EISDIR.
+import { statSync } from 'node:fs';
+import { containedPath } from './generate-write';
+import { inlineReexports } from './templates/slice-foundation';
+
+/**
+ * A slice module with its relative `export * from './x'` lines read in, one level deep — so a
+ * `policy.ts` that is a barrel is judged by what it really exports (`inlineReexports`).
+ */
+export async function followReexports(
+  root: string,
+  slice: string,
+  source: string | undefined,
+): Promise<string | undefined> {
+  if (source === undefined) return undefined;
+  const found = new Map<string, string>();
+  for (const match of source.matchAll(/\bexport\s*\*\s*from\s*['"](\.[^'"]+)['"]/g)) {
+    const specifier = match[1] ?? '';
+    for (const candidate of [`${specifier}.ts`, `${specifier}/index.ts`, specifier]) {
+      const file = containedPath(root, `${slice}/${candidate}`);
+      // A FILE, or it is not followed: `./rules` naming a directory with no `index.ts` is left as
+      // the `export *` it was, which is "cannot tell".
+      if (found.has(specifier) || !isFile(file)) continue;
+      found.set(specifier, await Bun.file(file).text());
+    }
+  }
+  return inlineReexports(source, (specifier) => found.get(specifier));
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/generate-slice-policy.ts

@@ -0,0 +1,29 @@
+// Single responsibility: the refusal `x g action` / `x g mutator` raise when the slice they were
+// pointed at has a hand-written `policy.ts` without the exports the generated file imports.
+// Declared outside `templates/` (source the CLI emits) and beside nothing else, as
+// `generate-feature.ts`'s `FeatureUnknownError` is: `errors.ts` sits at its line ceiling.
+
+import { UltimateError } from '@ultimat3/core';
+
+/** Thrown while the files are PLANNED, so nothing is on disk when it is. */
+export class SlicePolicyIncompleteError extends UltimateError {
+  constructor(input: {
+    readonly policy: string;
+    readonly feature: string;
+    readonly missing: readonly string[];
+    readonly kind: 'action' | 'mutator';
+  }) {
+    super({
+      code: 'X_SLICE_POLICY_INCOMPLETE',
+      cause: `${input.policy} does not export ${input.missing.join(' or ')}, which the ${input.kind} x g ${input.kind} writes imports from it — the file is hand-written, a generator never edits it, and nothing was written`,
+      // The fix IS the edit: `x g policy --dry-run` prints a write plan, never the source to copy.
+      fix: `${input.missing.map((name) => exportLine(name, input.feature)).join(' ')}   # add to ${input.policy} (tag from @ultimat3/cache, can from @ultimat3/policy; the permission must be one its definePermissions() declares), then run x g ${input.kind} again`,
+    });
+  }
+}
+
+/** The export line a scaffolded `policy.ts` carries for `name`. */
+const exportLine = (name: string, feature: string): string =>
+  name.endsWith('Tag')
+    ? `export const ${name} = tag('${feature}');`
+    : `export const ${name} = can('${feature}:write');`;

package/src/mcp-errors.ts

@@ -304,6 +304,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors explain X_BACKFILL_SLICE_ENTITY --json   # the refusal itself names the x g job line for this slice',
   X_LAYOUT_SIBLING_MODULE:
     'x verify --only boundaries --json   # then move each declaration in X.ts to X/<name>.ts, one primitive per file',
+  X_SLICE_POLICY_INCOMPLETE:
+    'x policy list --json   # names the slice policy module; add the export lines the thrown fix spells out to it, then run the generator again',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/templates/action.ts

@@ -2,12 +2,19 @@
 // pins both. One declaration projects to an HTTP route, an OpenAPI operation, a typed client, a
 // job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
 
+import { SlicePolicyIncompleteError } from '../generate-slice-policy';
 import type { FeatureTarget } from './entity';
 import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
 import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
-import { sliceExports, sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
+import {
+  exportsUnknown,
+  grantOf,
+  sliceExports,
+  sliceFoundation,
+  sliceTakesScaffoldRow,
+} from './slice-foundation';
 import { wrapImport } from './wrap';
 
 /**
@@ -177,6 +184,12 @@ interface HandlerShape {
   /** The slice still takes the row `x g entity` scaffolds, so the test may store one. */
   readonly storesRow: boolean;
   readonly dbModule: string;
+  /**
+   * The permission the writer is granted — `<feature>:write` for the policy this generator wrote,
+   * the one literal `can('<perm>')` of a handwritten one, or `undefined` when that policy's grant
+   * cannot be read, and then no assertion depends on it.
+   */
+  readonly grant: string | undefined;
 }
 
 /**
@@ -204,6 +217,12 @@ unitTest('the local twin invents no row the store never held', () => {
 
 /** The authoritative half's cases, refusal first, in the shape the slice earns. */
 const handlerTests = (feature: NameSet, shape: HandlerShape): string => {
+  if (shape.grant === undefined) {
+    return `
+// No handler assertion: ../policy.ts is hand-written and its grant is not one literal can('…'),
+// so which actor reaches the handler is the author's to state — add that test here.
+`;
+  }
   const answer = shape.isMutator ? "{ id, title: 'a title' }" : '{ id }';
   if (!shape.lookup) {
     return `
@@ -253,7 +272,8 @@ unitTest('the handler answers the row it found', async () => {
  * it would be a guess about someone else's table.
  */
 const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): string => {
-  const stores = shape.lookup && shape.storesRow;
+  const known = shape.grant !== undefined;
+  const stores = known && shape.lookup && shape.storesRow;
   const testing = [
     ...(stores ? ['afterEach'] : []),
     'expect',
@@ -264,7 +284,7 @@ const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): s
 // process, so all three belong to the \`unit\` step. The contract projections are next door.
 ${sortedImports([
   ...(stores ? ["import { ctxOf, runWithContext } from '@ultimat3/core';"] : []),
-  "import { testActor } from '@ultimat3/policy';",
+  ...(known ? ["import { testActor } from '@ultimat3/policy';"] : []),
   `import { ${testing} } from '@ultimat3/testing';`,
   ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
 ])}${stores ? "\nimport * as repo from '../repo';" : ''}
@@ -278,11 +298,15 @@ ${shape.isMutator ? `\n// The client store's table: the entity's own, so the twi
 // At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
 // object, so each projection of it works there with nothing to remember.
 const target = ${name.camel}.named('${name.camel}');
-
+${
+  known
+    ? `
 // Holds the grant in the org the input names: past the policy, so what answers is the handler.
-const grant = ['${feature.kebab}:write'];
+const grant = ['${shape.grant}'];
 const writer = testActor('writer', { orgId, permissions: grant }).actor;
-${
+`
+    : ''
+}${
   stores
     ? `
 // One store per process: without this, one test's rows are the next test's fixtures.
@@ -305,9 +329,11 @@ const actionContractTest = (
   name: NameSet,
   feature: NameSet,
   isMutator: boolean,
+  /** The slice's policy is the one this generator wrote, so its tenancy rule is known. */
+  scaffoldPolicy = true,
 ): string => `// ${name.camel}: the contract every action owes, and the foreign-org actor it denies before the
 // handler runs. One declaration, every surface.
-${preamble(name, feature, isMutator, 'contractTest, expect', true)}
+${preamble(name, feature, isMutator, 'contractTest, expect', scaffoldPolicy)}
 contractTest('${name.camel} passes the action contract', async () => {
   // Three assertions the framework makes for any action, without knowing what this one does:
   // garbage input is rejected, an anonymous actor is denied, and the operation reaches the
@@ -315,13 +341,19 @@ contractTest('${name.camel} passes the action contract', async () => {
   for (const contract of target.contract()) await contract.run();
 });
 
-contractTest('${name.camel} denies a foreign org', async () => {
+${
+  scaffoldPolicy
+    ? `contractTest('${name.camel} denies a foreign org', async () => {
   // \`.as()\` is the one execution path with the actor swapped, so this denial is the same one
   // HTTP, MCP and the job surface would produce — and no repo call happened to produce it.
   const denied = await target.as(outsider, input).catch((error: unknown) => error);
   expect(denied).toBeUltimateError('X_FORBIDDEN');
 });
-
+`
+    : `// No foreign-org assertion: ../policy.ts is hand-written, and whether it checks the org is the
+// author's rule to state — add that test here.
+`
+}
 // No MCP tool until it is described: a placeholder description misleads the agent reading it.
 contractTest('${name.camel} projects one operation and no tool', () => {
   expect(target.openapi().operationId).toBe('${name.camel}');
@@ -346,6 +378,12 @@ export interface ActionOptions extends FeatureTarget {
   readonly sliceEntity?: string;
   /** The slice's `repo.ts` as it stands on disk, or absent alongside `sliceEntity`. */
   readonly sliceRepo?: string;
+  /**
+   * The slice's `policy.ts` as it stands on disk, absent when the slice has none yet (and then the
+   * scaffolded one is written). Read for `sliceErrors`'s reason: the generated file IMPORTS from
+   * it, and what it exports is a fact about this app's disk.
+   */
+  readonly slicePolicy?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -354,16 +392,26 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
   const entity = target.sliceEntity !== undefined;
+  // Before a file is planned: a generated action that does not compile is refused, never written.
+  assertPolicyExports(target, feature, isMutator);
   const lookup =
     entity &&
     (target.sliceErrors === undefined ||
-      sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`));
+      sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`)) &&
+    // The lookup calls `repo.byId`: a `repo.ts` an author wrote without one gets the neutral body.
+    (target.sliceRepo === undefined || sliceExports(target.sliceRepo, 'byId'));
   return [
     // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
     // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
     // into a slice no `x g resource` had created emitted all three imports and wrote none of them.
     // With no entity, only the policy: a lookup-free body imports neither ../errors nor ../repo.
-    ...sliceFoundation(target, entity ? ['entity', 'policy', 'errors'] : ['policy']),
+    // And ONLY those: an action is not a resource scaffold. A module already on disk is its
+    // author's — it gets no test from here and no admin labels, both of which assert the shape
+    // `x g resource` writes, not the one that is there (`withoutOwned`).
+    ...withoutOwned(
+      sliceFoundation(target, entity ? ['entity', 'policy', 'errors'] : ['policy']),
+      target,
+    ),
     {
       path: `${dir}/${name.kebab}.ts`,
       contents: isMutator
@@ -381,11 +429,63 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
         lookup,
         storesRow: sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),
         dbModule: target.dbModule ?? PLACEHOLDER_DB_MODULE,
+        // The policy this run writes grants `<feature>:write`; a handwritten one, what it says.
+        grant:
+          target.slicePolicy === undefined
+            ? `${feature.kebab}:write`
+            : grantOf(target.slicePolicy, `can${feature.pascal}Write`),
       }),
     },
     {
       path: `${dir}/${name.kebab}.contract.test.ts`,
-      contents: actionContractTest(name, feature, isMutator),
+      contents: actionContractTest(name, feature, isMutator, target.slicePolicy === undefined),
     },
   ];
 }
+
+/** The slice modules a run may find already written, and the files each would otherwise be handed. */
+const OWNED = [
+  ['sliceEntity', ['/entity.ts', '/entity.test.ts', '.json']],
+  ['sliceRepo', ['/repo.ts', '/repo.test.ts']],
+  ['slicePolicy', ['/policy.ts', '/policy.test.ts']],
+] as const;
+
+/**
+ * The planted slice files, minus everything that belongs to a module ALREADY on disk. `if-absent`
+ * protects a file; it does not know that `repo.test.ts` belongs to a `repo.ts` somebody wrote, so
+ * a hand-written slice was handed three tests asserting the scaffold's shape and six admin labels
+ * (the catalog `.json`) for an entity it had declared itself. A module this run does write keeps
+ * every companion.
+ */
+function withoutOwned(
+  files: readonly GeneratedFile[],
+  target: ActionOptions,
+): readonly GeneratedFile[] {
+  const owned = OWNED.flatMap(([module, suffixes]) =>
+    target[module] === undefined ? [] : suffixes,
+  );
+  return files.filter((file) => !owned.some((suffix) => file.path.endsWith(suffix)));
+}
+
+/**
+ * Refuse a slice whose own `policy.ts` lacks what the generated file imports from it. An absent
+ * `policy.ts` is not this case — the scaffolded one is written beside the action, with both names.
+ *
+ * Refused rather than adapted, unlike a missing `<Feature>NotFoundError`: there is no neutral
+ * policy to fall back to. An inline `can('<feature>:write')` names a permission the slice's
+ * `definePermissions()` never declared, which is a type error of its own.
+ */
+function assertPolicyExports(target: ActionOptions, feature: NameSet, isMutator: boolean): void {
+  const source = target.slicePolicy;
+  // A barrel re-exporting a module nobody could read: cannot tell, so never refused on a guess.
+  if (source === undefined || exportsUnknown(source)) return;
+  const needed = [`can${feature.pascal}Write`, ...(isMutator ? [] : [`${feature.camel}Tag`])];
+  const missing = needed.filter((name) => !sliceExports(source, name));
+  if (missing.length === 0) return;
+  throw new SlicePolicyIncompleteError({
+    policy: `${target.surfaceDir}/${target.feature}/policy.ts`,
+    feature: target.feature,
+    missing,
+    kind: isMutator ? 'mutator' : 'action',
+  });
+}

package/src/templates/slice-foundation.ts

@@ -131,7 +131,59 @@ export function sliceExports(source: string, name: string): boolean {
   const declared = new RegExp(
     `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|(?:async\\s+)?function|enum)\\s+${name}\\b`,
   );
-  return declared.test(code) || listedExports(code).includes(name);
+  return (
+    declared.test(code) || listedExports(code).includes(name) || destructured(code).includes(name)
+  );
+}
+
+/** The names an `export const { a, b: c } = …` declares — `a` and `c`, never `b`. */
+const destructured = (code: string): readonly string[] =>
+  [...code.matchAll(/\bexport\s+(?:const|let|var)\s*\{([^}]*)\}\s*=/g)].flatMap((match) =>
+    (match[1] ?? '')
+      .split(',')
+      .map((entry) => (entry.split(':').at(-1) ?? '').split('=')[0]?.trim() ?? '')
+      .filter((entry) => entry !== ''),
+  );
+
+const STAR = /\bexport\s*\*\s*from\s*['"]([^'"]+)['"]\s*;?/g;
+
+/**
+ * `source` with each `export * from '<specifier>'` replaced by the module `read` answers for it —
+ * ONE level, which is what a slice's barrel is. A specifier `read` cannot answer (a package, a
+ * missing file) is left as it stands, and that leftover is what `exportsUnknown` reports.
+ */
+export function inlineReexports(
+  source: string,
+  read: (specifier: string) => string | undefined,
+): string {
+  return stripComments(source).replace(STAR, (statement: string, specifier: string) => {
+    const inner = read(specifier);
+    // Its own `export *` lines are dropped rather than followed: one level, and a module that
+    // re-exports further is "cannot tell" only if THIS file still says so.
+    return inner === undefined ? statement : stripComments(inner).replace(STAR, '');
+  });
+}
+
+/** Whether `source` re-exports a module nobody read: what it exports cannot be known from here. */
+export const exportsUnknown = (source: string): boolean => {
+  const code = stripComments(source);
+  return /\bexport\s*\*\s*from\b/.test(code) || nestedPattern(code);
+};
+
+/**
+ * Whether an exported destructuring pattern is one the flat reader above cannot spell: a nested
+ * object or array pattern, or a rest element. Its names are then UNKNOWN — never "missing".
+ */
+function nestedPattern(code: string): boolean {
+  for (const match of code.matchAll(/\bexport\s+(?:const|let|var)\s*\{/g)) {
+    let depth = 1;
+    for (let at = (match.index ?? 0) + match[0].length; at < code.length && depth > 0; at += 1) {
+      const char = code[at];
+      if (char === '{' || char === '[' || code.startsWith('...', at)) return true;
+      if (char === '}') depth -= 1;
+    }
+  }
+  return false;
 }
 
 /** `    title: text({ max: 200 }),` — one column of an entity, as its name and its builder. */
@@ -162,3 +214,16 @@ export function sliceTakesScaffoldRow(
   if (wanted === '' || columnsOf(sliceEntity) !== wanted) return false;
   return sliceRepo === undefined || sliceExports(sliceRepo, 'insert');
 }
+
+/**
+ * The ONE permission `name` grants, when `source` declares it as a single literal call:
+ * `export const canBlogWrite = can('blog:publish');`. Anything else — a predicate argument,
+ * `and`/`or`, a function, a re-export — is `undefined`: the grant cannot be read, and a generated
+ * test must not assume one.
+ */
+export function grantOf(source: string, name: string): string | undefined {
+  const declared = new RegExp(
+    `\\bexport\\s+const\\s+${name}\\s*=\\s*can\\(\\s*(['"\`])([A-Za-z0-9_.*:-]+)\\1\\s*\\)\\s*;`,
+  );
+  return declared.exec(stripComments(source))?.[2];
+}