@assembly-js/app-foundation 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -19,6 +19,13 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.12.0
+- [behavior] `check:crons` on a platform update turn now only warns about a cron route the app already had without a schedule; a route added this turn, or one that lost its schedule, still fails.
+
+## 0.11.0
+- [behavior] `check:record-urls` now checks each surface on its own: a record opened on the client portal needs its own `/c` route or `useUrlState`, and an internal dynamic route no longer exempts it. It also catches a list/detail view switch held in `useState`, so a client's request page keeps its own URL that can be reloaded or shared.
+- [guidance] `assembly-app-inner-location` says the record URL rule applies to the client portal too, with `app/c/[id]/page.tsx` or `?id=` through `useUrlState` as the two valid shapes.
+
 ## 0.10.0
 - [behavior] A call to another app through the installer client or a raw `fetch` to `/v1/apps/...` made inside a client's request now carries that client, so the platform checks the client could open the other app and the other app sees a client whose calling app is this one. A client who cannot open it gets the platform's `viewer_cannot_open_app` refusal as an error value; staff requests, cron, webhooks and queues are unchanged and send no parent.
 - [behavior] A cross-app call from a client's request whose session cannot be verified (exchange off, a rejected header or expired cookie) now throws the token-invalid error instead of running as the installing admin, and a cross-app call where the request cannot be read (`'use cache'`, prerender, `after()`) throws. Storage, connector, notification and AI proxy installer calls are untouched.

package/bin/check-crons.mjs

@@ -16,7 +16,8 @@
 // as warnings: those paths have no agent who can act on a failure, so failing
 // them would only strand an app that already worked. A below-floor schedule
 // the app shipped before the turn stays a warning even then (see
-// baselineCronSchedules).
+// baselineCronSchedules), as does a cron route the app shipped with no schedule
+// at all (see baselineUnscheduledRoutes).
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, relative, sep } from 'node:path';
@@ -42,7 +43,8 @@ const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
 // Set by the turn program on a platform update turn, where the update itself is
 // the mandate to fix whatever is wrong, so findings fail the build whether or
 // not the turn touched the cron wiring.
-const STRICT = process.argv.includes('--strict') || process.env.ASSEMBLY_UPDATE_TURN === '1';
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const STRICT = process.argv.includes('--strict') || UPDATE_TURN;
 const CRON_WIRING_PATHS = ['vercel.json', 'app/api/cron/'];
 
 function report(lines, { fatal }) {
@@ -92,6 +94,44 @@ function baselineCronSchedules() {
   return schedules;
 }
 
+// Cron route files (repo-relative, posix) that existed at the turn baseline with
+// no vercel.json entry invoking them. An update turn has no mandate to schedule
+// work the app never ran, so these only warn. An unreadable baseline yields an
+// empty set, which keeps every unscheduled route fatal.
+function baselineUnscheduledRoutes() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  const unscheduled = new Set();
+  if (!baseline || !UPDATE_TURN) return unscheduled;
+  const listing = spawnSync('git', ['ls-tree', '-r', '--name-only', baseline, '--', 'app'], {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+  if (listing.status !== 0) return unscheduled;
+  // Route groups can hold cron routes too, so list all of app/ and filter by the URL served.
+  const routePaths = listing.stdout
+    .split('\n')
+    .filter((p) => ROUTE_FILE.test(p.split('/').pop()))
+    .filter((p) => ('/' + urlSegments(p.split('/').slice(1)).join('/') + '/').startsWith(CRON_ROUTE_PREFIX));
+  const shown = spawnSync('git', ['show', `${baseline}:vercel.json`], { cwd: ROOT, encoding: 'utf8' });
+  let baselineCrons = [];
+  if (shown.status === 0) {
+    try {
+      const parsed = JSON.parse(shown.stdout).crons;
+      if (Array.isArray(parsed)) baselineCrons = parsed;
+    } catch {
+      // An unparseable baseline file scheduled nothing.
+    }
+  }
+  const scheduledPaths = baselineCrons
+    .filter((c) => typeof c?.path === 'string')
+    .map((c) => c.path.replace(/\/+$/, '').split('/').filter(Boolean));
+  for (const path of routePaths) {
+    const segments = urlSegments(path.split('/').slice(1));
+    if (!scheduledPaths.some((pathSegments) => routeServes(segments, pathSegments))) unscheduled.add(path);
+  }
+  return unscheduled;
+}
+
 function cronKey(entry) {
   return `${entry?.path}\n${typeof entry?.schedule === 'string' ? entry.schedule.trim() : ''}`;
 }
@@ -146,8 +186,11 @@ function routeFiles(dir) {
 // The URL segments a route file serves; route groups `(group)` and parallel
 // slots `@slot` never appear in the URL.
 function urlSegmentsForRouteFile(file) {
-  return relative(APP_DIR, file)
-    .split(sep)
+  return urlSegments(relative(APP_DIR, file).split(sep));
+}
+
+function urlSegments(pathParts) {
+  return pathParts
     .slice(0, -1)
     .filter((seg) => !(seg.startsWith('(') && seg.endsWith(')')) && !seg.startsWith('@'));
 }
@@ -259,6 +302,7 @@ const entries = Array.isArray(crons) ? crons : [];
 const coveredRoutes = new Set();
 const shippedSchedules = baselineCronSchedules();
 const preexistingIntervals = [];
+const unscheduledAtBaseline = baselineUnscheduledRoutes();
 
 entries.forEach((entry, i) => {
   const label = `vercel.json crons[${i}]`;
@@ -296,6 +340,14 @@ entries.forEach((entry, i) => {
 for (const route of cronRoutes) {
   const url = '/' + route.segments.join('/');
   if (!coveredRoutes.has(route.file)) {
+    const rel = relative(ROOT, route.file).split(sep).join('/');
+    if (unscheduledAtBaseline.has(rel)) {
+      preexistingIntervals.push(
+        `${rel} serves ${url} but no vercel.json cron entry invokes it. The app shipped this route unscheduled, ` +
+          `and the update does not add a schedule, so leave it as it is.`,
+      );
+      continue;
+    }
     problems.push(
       `${relative(ROOT, route.file)} serves ${url} but no vercel.json cron entry invokes it — it will never run ` +
         `after publish. Add { "path": "${url}", "schedule": "*/30 * * * *" } to "crons" or remove the route.`,

package/bin/check-record-urls.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-// Fails the build when a record opened from a list (a Dialog, Sheet, Drawer or
-// detail panel) is driven by React state alone: the host URL never changes, so a
-// reload or a shared link lands on the list instead of the record. The fix is
-// either `useUrlState('id')` from `@assembly-js/app-foundation/client` or a
-// dynamic route for the record on the internal surface. The match is a
-// heuristic on a `selected*`-style `useState` that feeds a panel-like element.
+// Fails the build when a record opened from a list (a Dialog, Sheet, Drawer,
+// detail panel or a list/detail view switch) is driven by React state alone: the
+// host URL never changes, so a reload or a shared link lands on the list instead
+// of the record. The fix is either `useUrlState('id')` from
+// `@assembly-js/app-foundation/client` or a dynamic route for the record on the
+// surface that renders it. The match is a heuristic on a `selected*`-style
+// `useState` that feeds a panel-like element, or a `useState<View>` whose type
+// has a detail-like variant carrying an `id`.
 // Dependency free on purpose: it runs inside the generated app's sandbox before
 // any deps beyond Node are guaranteed.
 //
@@ -14,7 +16,7 @@
 // On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
 // update never rewrites how an app navigates.
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 
 const ROOT = process.cwd();
 const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
@@ -23,13 +25,24 @@ const MANIFEST = join(ROOT, '.assembly', 'app.json');
 const INNER_LOCATION_SKILL = join(ROOT, '.claude', 'skills', 'assembly-app-inner-location', 'SKILL.md');
 const SOURCE_FILE = /\.(tsx|jsx)$/;
 const PAGE_FILE = /^page\.(tsx|ts|jsx|js)$/;
+const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*)['"]([^'"]+)['"]/g;
 
 // `const [selectedRequest, setSelectedRequest] = useState(...)`; the setter name is not trusted.
 const USE_STATE = /const\s+\[\s*([A-Za-z_$][\w$]*)\s*,\s*[A-Za-z_$][\w$]*\s*\]\s*=\s*useState\b/g;
 const RECORD_SELECTION = /^(?:selected|active|viewing|viewed|current|detail|open(?:ed)?)[A-Z_]/;
 // Selection of something that is not a record, or that is genuinely transient.
-const NOT_A_RECORD = /(?:Tab|Filter|Status|Sort|View|Option|Date|Range|Column|Mode|Step|Page|Menu)s?$|^(?:confirm|delete|remove|menu|pending)/i;
+const TRANSIENT_NAME = /^(?:confirm|delete|remove|menu|pending)/i;
+const NOT_A_RECORD = new RegExp(
+  `(?:Tab|Filter|Status|Sort|View|Option|Date|Range|Column|Mode|Step|Page|Menu)s?$|${TRANSIENT_NAME.source}`,
+  'i',
+);
 const PANEL_ELEMENT = /<\w*(?:Dialog|Sheet|Drawer|Panel|Modal|Detail)\w*[\s>/]/;
+// `const [view, setView] = useState<View>(...)`; the generic is read by scanning, since it can nest.
+const TYPED_USE_STATE = /const\s+\[\s*([A-Za-z_$][\w$]*)\s*,\s*[A-Za-z_$][\w$]*\s*\]\s*=\s*useState\s*</g;
+// A view switch that can show one record: a variant naming a detail-like view, and an `id` field.
+const DETAIL_VARIANT = /['"`](?:detail|show|view|open|record|item)['"`]/i;
+const ID_FIELD = /\bid\??\s*:/;
 const OPT_OUT = /record-urls:\s*transient/;
 
 function sourceFiles(dir) {
@@ -47,15 +60,15 @@ function sourceFiles(dir) {
   return out;
 }
 
-// Prefixes of the client and notification surfaces; a dynamic route there does
-// not give the internal dashboard a record URL.
-function nonInternalPrefixes() {
-  const prefixes = new Set(['/c', '/n']);
+// Prefixes of the client and notification surfaces; a dynamic route on one
+// surface does not give another surface a record URL.
+function surfacePrefixes() {
+  const prefixes = { client: new Set(['/c']), notification: new Set(['/n']) };
   try {
     const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
     for (const key of ['client', 'notification']) {
       const p = manifest?.surfaces?.[key]?.path;
-      if (typeof p === 'string' && p.startsWith('/') && p !== '/') prefixes.add(p.replace(/\/+$/, ''));
+      if (typeof p === 'string' && p.startsWith('/') && p !== '/') prefixes[key].add(p.replace(/\/+$/, ''));
     }
   } catch {
     // defaults
@@ -63,6 +76,10 @@ function nonInternalPrefixes() {
   return prefixes;
 }
 
+function underPrefix(route, prefixes) {
+  return [...prefixes].some((p) => route === p || route.startsWith(`${p}/`));
+}
+
 function routeForPageFile(file) {
   const segments = relative(APP_DIR, file).split(sep).slice(0, -1);
   const urlSegments = segments.filter(
@@ -78,31 +95,133 @@ const contents = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
 
 if (!existsSync(INNER_LOCATION_SKILL)) process.exit(0);
 
-const prefixes = nonInternalPrefixes();
-const hasInternalRecordRoute = files.some((f) => {
-  if (!PAGE_FILE.test(f.split(sep).pop())) return false;
-  const route = routeForPageFile(f);
-  if (!route.includes('[')) return false;
-  return ![...prefixes].some((p) => route === p || route.startsWith(`${p}/`));
-});
-if (hasInternalRecordRoute) process.exit(0);
-
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+function relPath(file) {
+  return relative(ROOT, file).split(sep).join('/');
+}
+
+function resolveImport(from, spec) {
+  let base;
+  if (spec.startsWith('./') || spec.startsWith('../')) base = join(dirname(from), spec);
+  else if (spec.startsWith('@/')) base = join(ROOT, spec.slice(2));
+  else return null;
+  const candidates = [
+    base,
+    ...RESOLVE_EXTENSIONS.map((ext) => base + ext),
+    ...RESOLVE_EXTENSIONS.map((ext) => join(base, 'index' + ext)),
+  ];
+  return candidates.find((c) => contents.has(c)) ?? null;
+}
+
+// Files reachable from `roots` through relative and `@/` imports. An import the
+// regex misses (a barrel re-export, a computed path) only shrinks the set.
+function reachableFrom(roots) {
+  const seen = new Set(roots);
+  const queue = [...roots];
+  while (queue.length) {
+    const file = queue.pop();
+    for (const m of contents.get(file).matchAll(IMPORT_SPECIFIER)) {
+      const target = resolveImport(file, m[1]);
+      if (target && !seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return seen;
+}
+
+// The text between the `<` before `start` and its matching `>`, skipping `=>`.
+function genericArgument(src, start) {
+  let depth = 1;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '<') depth++;
+    else if (ch === '>' && src[i - 1] !== '=' && --depth === 0) return src.slice(start, i);
+  }
+  return '';
+}
+
+// The body of `type Name = …` or `interface Name {…}` declared in this file.
+function localTypeBody(src, name) {
+  const n = escapeRe(name);
+  const decl = new RegExp(`\\btype\\s+${n}\\b(?:<[^=]*>)?\\s*=|\\binterface\\s+${n}\\b[^{]*`).exec(src);
+  if (!decl) return '';
+  const isInterface = decl[0].startsWith('interface');
+  const start = decl.index + decl[0].length;
+  let depth = 0;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    if ('{(['.includes(ch)) depth++;
+    else if ('})]'.includes(ch)) {
+      depth--;
+      if (depth === 0 && isInterface) return src.slice(start, i + 1);
+    } else if (depth === 0 && !isInterface && ch === ';') {
+      return src.slice(start, i);
+    } else if (depth === 0 && !isInterface && ch === '\n' && src.slice(start, i).trim() && !/^\s*[|&]/.test(src.slice(i + 1))) {
+      return src.slice(start, i);
+    }
+  }
+  return src.slice(start);
+}
+
+function isDetailViewType(src, typeText) {
+  let text = typeText;
+  for (const ident of new Set(typeText.match(/\b[A-Z][\w$]*\b/g) ?? [])) text += '\n' + localTypeBody(src, ident);
+  return ID_FIELD.test(text) && DETAIL_VARIANT.test(text);
+}
+
+const prefixes = surfacePrefixes();
+const clientPages = [];
+const internalPages = [];
+let hasClientRecordRoute = false;
+let hasInternalRecordRoute = false;
+for (const f of files) {
+  if (!PAGE_FILE.test(f.split(sep).pop())) continue;
+  const route = routeForPageFile(f);
+  if (underPrefix(route, prefixes.client)) {
+    clientPages.push(f);
+    if (route.includes('[')) hasClientRecordRoute = true;
+  } else if (!underPrefix(route, prefixes.notification)) {
+    internalPages.push(f);
+    if (route.includes('[')) hasInternalRecordRoute = true;
+  }
+}
+const clientReachable = reachableFrom(clientPages);
+const internalReachable = reachableFrom(internalPages);
+
+// A route exempts a file only when every surface that renders it has one. A file
+// no page reaches is judged as internal, as it was before the check followed imports.
+function exemptByRoute(file) {
+  const onClient = clientReachable.has(file);
+  const onInternal = internalReachable.has(file) || !onClient;
+  return (!onClient || hasClientRecordRoute) && (!onInternal || hasInternalRecordRoute);
+}
+
 const violations = [];
 for (const file of files) {
   if (!SOURCE_FILE.test(file)) continue;
   const src = contents.get(file);
-  if (/\buseUrlState\b/.test(src) || OPT_OUT.test(src) || !PANEL_ELEMENT.test(src)) continue;
-  for (const match of src.matchAll(USE_STATE)) {
+  if (/\buseUrlState\b/.test(src) || OPT_OUT.test(src) || exemptByRoute(file)) continue;
+  const where = clientReachable.has(file) ? `${relPath(file)}  [client surface]` : relPath(file);
+  if (PANEL_ELEMENT.test(src)) {
+    for (const match of src.matchAll(USE_STATE)) {
+      const name = match[1];
+      if (!RECORD_SELECTION.test(name) || NOT_A_RECORD.test(name)) continue;
+      // Declared and read somewhere else in the file, i.e. it feeds the panel.
+      const uses = src.match(new RegExp(`(?<![\\w$.])${escapeRe(name)}(?![\\w$])`, 'g')) ?? [];
+      if (uses.length < 3) continue;
+      violations.push(`${where}  (useState: ${name})`);
+    }
+  }
+  for (const match of src.matchAll(TYPED_USE_STATE)) {
     const name = match[1];
-    if (!RECORD_SELECTION.test(name) || NOT_A_RECORD.test(name)) continue;
-    // Declared and read somewhere else in the file, i.e. it feeds the panel.
-    const uses = src.match(new RegExp(`(?<![\\w$.])${escapeRe(name)}(?![\\w$])`, 'g')) ?? [];
-    if (uses.length < 3) continue;
-    violations.push(`${relative(ROOT, file).split(sep).join('/')}  (useState: ${name})`);
+    if (TRANSIENT_NAME.test(name)) continue;
+    if (!isDetailViewType(src, genericArgument(src, match.index + match[0].length))) continue;
+    violations.push(`${where}  (useState view switch: ${name})`);
   }
 }
 
@@ -121,7 +240,12 @@ if (violations.length > 0 && UPDATE_TURN) {
   console.error("  - Replace the useState with `const [id, setId] = useUrlState('id')` from");
   console.error("    '@assembly-js/app-foundation/client' and render the record from `id`;");
   console.error('    a cold load with ?id= must open it, and Back must close it.');
-  console.error('  - Give the record its own route (app/requests/[id]/page.tsx) and link to it.');
+  console.error('  - Give the record its own route on the surface that lists it and link to it:');
+  console.error('    app/requests/[id]/page.tsx on the internal surface.');
+  console.error('A file marked [client surface] needs the same fix there: call');
+  console.error("`useUrlState('requestId')` in the client page component instead of a view state,");
+  console.error('or add app/c/[id]/page.tsx and link to it from the list. A cold load of that URL');
+  console.error('must open the record and Back must close it.');
   console.error('A genuinely transient UI (confirm dialog, menu) can add the comment');
   console.error('`// record-urls: transient` to the file.');
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-app-inner-location/SKILL.md

@@ -13,7 +13,7 @@ The host mirrors the app's inner page in its own address bar and can open the ap
 
 ## Records get a URL
 
-Keep which record is open in the URL, not in `useState`: `const [id, setId] = useUrlState('id')` from `@assembly-js/app-foundation/client` for a panel, Sheet or Dialog, or a route like `app/requests/[id]/page.tsx`. A record opened from a list must load cold from its URL and Back must close it. `bun run build` fails `check:record-urls` for a `selectedId`-style `useState` feeding a record panel; use the helper or a route to fix it.
+Keep which record is open in the URL, not in `useState`: `const [id, setId] = useUrlState('id')` from `@assembly-js/app-foundation/client` for a panel, Sheet or Dialog, or a route like `app/requests/[id]/page.tsx`. A record opened from a list must load cold from its URL and Back must close it. `bun run build` fails `check:record-urls` for a `selectedId`-style `useState` feeding a record panel; use the helper or a route to fix it. This applies to the client surface (`/c`) as much as the internal one: a record a client opens from a list is `app/c/[id]/page.tsx` or `?id=` through `useUrlState`, never a `useState<View>` that switches between list and detail; the check fails that too.
 
 ## Notifications deep-link to the record, not the app root