@assembly-js/app-foundation 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -19,6 +19,14 @@ 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.13.0
+- [new] `<ClientName client={client} />` and `<CompanyName company={company} />` from `@assembly-js/app-foundation/lib-client` render a name that opens the record's CRM page for staff and is plain text for a client viewer.
+- [new] `bun run build` runs `check:linked-names`, which fails when a client's or company's name is rendered by hand instead of through those components. It only runs on apps that carry the platform-links skill.
+- [guidance] `assembly-platform-links` leads with rendering client and company names through the components.
+
+## 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.

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-linked-names.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Fails the build when a client's or company's name is rendered by hand in a
+// component instead of through `<ClientName>` / `<CompanyName>` from
+// `@assembly-js/app-foundation/lib-client`. The components link the name to the
+// record's CRM page for staff and render plain text for a client viewer; a
+// hand-rendered name never links, and the prose guidance to call `linkTo` was
+// not followed. The match favours precision, because a false positive blocks the
+// build: it only looks at a name placed directly in JSX, or a full name built
+// from `X.givenName` and `X.familyName`, where the object is called `client`
+// or `customer` (and `company` for the company name).
+// Dependency free on purpose: it runs inside the generated app's sandbox before
+// any deps beyond Node are guaranteed.
+//
+// Inert unless the platform-links skill was written into the app (it ships only when
+// the deep-link flag is on) and the app depends on the foundation package, which is
+// where the components live: a vendored app has nothing to switch to.
+// On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
+// update never rewrites how an app renders names.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const PLATFORM_LINKS_SKILL = join(ROOT, '.claude', 'skills', 'assembly-platform-links', 'SKILL.md');
+const SOURCE_FILE = /\.(tsx|jsx)$/;
+const PACKAGE_JSON = join(ROOT, 'package.json');
+const OPT_OUT = /linked-names:\s*plain/;
+
+const OBJECT_PATH = String.raw`(?:[\w$]+\??\.)*`;
+const FALLBACK = String.raw`(?:\s*(?:\?\?|\|\|)\s*(?:'[^']*'|"[^"]*"))?`;
+// `{client.givenName}` placed in JSX, not an attribute value (`=`) or a template (`$`).
+const CLIENT_NAME_CHILD = new RegExp(
+  String.raw`(?<!=\s*)(?<!\$)\{\s*${OBJECT_PATH}(?:client|customer)\??\.(?:givenName|familyName)${FALLBACK}\s*\}`,
+  'gi',
+);
+const COMPANY_NAME_CHILD = new RegExp(
+  String.raw`(?<!=\s*)(?<!\$)\{\s*${OBJECT_PATH}company\??\.name${FALLBACK}\s*\}`,
+  'gi',
+);
+// `${client.givenName} ${client.familyName}`, `[client.givenName, client.familyName].join(' ')`
+// and `client.givenName + ' ' + client.familyName`; a lone `[0]` initial is not a name.
+const FULL_NAME = new RegExp(
+  String.raw`(?:` +
+    String.raw`\$\{\s*${OBJECT_PATH}(?:client|customer)\??\.givenName\s*\}[^\`]{0,20}\$\{\s*${OBJECT_PATH}(?:client|customer)\??\.familyName\s*\}` +
+    String.raw`|\[\s*${OBJECT_PATH}(?:client|customer)\??\.givenName\s*,\s*${OBJECT_PATH}(?:client|customer)\??\.familyName\s*\]` +
+    String.raw`|${OBJECT_PATH}(?:client|customer)\??\.givenName\s*\+\s*['"\`][^'"\`]*['"\`]\s*\+\s*${OBJECT_PATH}(?:client|customer)\??\.familyName` +
+    String.raw`)`,
+  'gi',
+);
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (SOURCE_FILE.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// An attribute value (`alt={...}`, `title={`...`}`) is not rendered text.
+function inAttribute(src, index) {
+  return /=\s*\{\s*`?$/.test(src.slice(Math.max(0, index - 16), index));
+}
+
+// A built string that is not rendered as JSX text (an object label, a filter key) cannot
+// be a component; only a name sitting in text, or returned/assigned for display, is flagged.
+function inStringOnlyUse(src, index) {
+  const lineStart = src.lastIndexOf('\n', index) + 1;
+  return /(?:\blabel|\bvalue|\bkey|\bsearch\w*|\bfilter\w*|\bquery)\s*[:=]\s*[^\n]*$/i.test(src.slice(lineStart, index));
+}
+
+function lineOf(src, index) {
+  return src.slice(0, index).split('\n').length;
+}
+
+if (!existsSync(PLATFORM_LINKS_SKILL)) process.exit(0);
+try {
+  if (!readFileSync(PACKAGE_JSON, 'utf8').includes('app-foundation')) process.exit(0);
+} catch {
+  process.exit(0);
+}
+
+const violations = [];
+for (const file of [...sourceFiles(join(ROOT, 'app')), ...sourceFiles(join(ROOT, 'components'))]) {
+  const src = readFileSync(file, 'utf8');
+  if (OPT_OUT.test(src)) continue;
+  const where = relative(ROOT, file).split(sep).join('/');
+  const found = new Map();
+  for (const [re, kind] of [
+    [CLIENT_NAME_CHILD, 'client name'],
+    [FULL_NAME, 'client name'],
+    [COMPANY_NAME_CHILD, 'company name'],
+  ]) {
+    for (const m of src.matchAll(re)) if (!inAttribute(src, m.index) && !(re === FULL_NAME && inStringOnlyUse(src, m.index))) found.set(m.index, `${where}:${lineOf(src, m.index)}  (${kind}: ${m[0].trim()})`);
+  }
+  violations.push(...[...found.entries()].sort((a, b) => a[0] - b[0]).map(([, v]) => v));
+}
+
+if (violations.length > 0 && UPDATE_TURN) {
+  console.warn('');
+  console.warn('check-linked-names: names rendered by hand (this update turn is not failed for it):');
+  for (const v of violations) console.warn('  - ' + v);
+  console.warn('');
+} else if (violations.length > 0) {
+  console.error('');
+  console.error('A client or company name is rendered by hand, so it never links to its record:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error("Render it with the components from '@assembly-js/app-foundation/lib-client':");
+  console.error('  <ClientName client={client} className="..." />   // a client with givenName/familyName');
+  console.error('  <CompanyName company={company} className="..." />   // a company with name');
+  console.error('Staff get a link to the CRM record; a client viewer gets plain text.');
+  console.error('A name that must stay plain (the viewer\'s own greeting, a title attribute) can add the');
+  console.error('comment `// linked-names: plain` to the file.');
+  console.error('A string-only use (a `label:` or `filter` value) is not flagged.');
+  process.exit(1);
+}

package/dist/lib-client.d.ts

@@ -1,4 +1,6 @@
+import type { ReactElement } from 'react';
 import type { NavigateDestination, NavigateToOptions } from './bridge-vnext.js';
+import { type ClientNameRecord, type CompanyNameRecord } from './record-names.js';
 export declare function resetRenewalStateForTests(): void;
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
@@ -28,3 +30,22 @@ export declare function handleVisibilityChangeForTests(): void;
  * </button>
  */
 export declare function linkTo(destination: NavigateDestination, options?: NavigateToOptions): () => void;
+interface RecordNameProps {
+    className?: string;
+    viewer?: 'internal' | 'client';
+}
+/**
+ * A client's name that opens their CRM record for staff and is plain text for a
+ * client viewer, who cannot reach the destination.
+ *
+ * @example
+ * <ClientName client={client} className="font-medium" />
+ */
+export declare function ClientName({ client, className, viewer }: RecordNameProps & {
+    client: ClientNameRecord;
+}): ReactElement;
+/** A company's name that opens its CRM record for staff and is plain text for a client viewer. */
+export declare function CompanyName({ company, className, viewer }: RecordNameProps & {
+    company: CompanyNameRecord;
+}): ReactElement;
+export {};

package/dist/lib-client.js

@@ -5,7 +5,10 @@
 // never be dragged into the Edge middleware bundle that imports ./client
 // (proxy.ts pulls constants from that barrel).
 import { AssemblyBridge } from '@assembly-js/app-bridge';
+import { createElement } from 'react';
+import { usePathname } from 'next/navigation';
 import { APP_CSRF_HEADER, COOKIE_PROBE_NAME, logRenewOutcome, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { clientDisplayName, isClientSurfacePath, } from './record-names.js';
 import { readBearerExpiry, readCookie } from './origin-bootstrap.js';
 import { cookielessReexchangeHeaders, cookiesAreBlocked, getCookielessBearer, setCookielessBearer, } from './cookieless-bearer.js';
 const REEXCHANGE_PATH = '/api/assembly-reexchange';
@@ -338,3 +341,43 @@ export function linkTo(destination, options) {
         });
     };
 }
+function isClientViewer(viewer, pathname) {
+    return viewer ? viewer === 'client' : isClientSurfacePath(pathname);
+}
+// A button so the link is keyboard reachable, reset to read as inline text; the
+// colour is only inherited when the app gave no class, so its own colour wins.
+// createElement keeps the package free of a jsx compiler setting.
+function recordName(name, destination, className) {
+    if (!destination)
+        return createElement('span', { className }, name);
+    return createElement('button', {
+        type: 'button',
+        className,
+        onClick: linkTo(destination),
+        style: {
+            background: 'none',
+            border: 0,
+            padding: 0,
+            font: 'inherit',
+            textAlign: 'inherit',
+            cursor: 'pointer',
+            color: className ? undefined : 'inherit',
+        },
+    }, name);
+}
+/**
+ * A client's name that opens their CRM record for staff and is plain text for a
+ * client viewer, who cannot reach the destination.
+ *
+ * @example
+ * <ClientName client={client} className="font-medium" />
+ */
+export function ClientName({ client, className, viewer }) {
+    const isClient = isClientViewer(viewer, usePathname());
+    return recordName(clientDisplayName(client), isClient ? null : { to: 'client', clientId: client.id }, className);
+}
+/** A company's name that opens its CRM record for staff and is plain text for a client viewer. */
+export function CompanyName({ company, className, viewer }) {
+    const isClient = isClientViewer(viewer, usePathname());
+    return recordName(company.name ?? '', isClient ? null : { to: 'company', companyId: company.id }, className);
+}

package/dist/record-names.d.ts

@@ -0,0 +1,16 @@
+export interface ClientNameRecord {
+    id: string;
+    givenName?: string | null;
+    familyName?: string | null;
+}
+export interface CompanyNameRecord {
+    id: string;
+    name?: string | null;
+}
+export declare function clientDisplayName(client: ClientNameRecord): string;
+/**
+ * Whether the page is rendered for a client in the portal. `client` and `company`
+ * are staff-only destinations, so an unknown surface also counts as a client:
+ * plain text is the safe failure, a dead link is not.
+ */
+export declare function isClientSurfacePath(pathname: string): boolean;

package/dist/record-names.js

@@ -0,0 +1,15 @@
+import { getSurfacePrefix } from './location-prefix.js';
+// The notification surface is staff-facing, so only the other prefixed surface is the client portal.
+const NOTIFICATION_PREFIX = '/n';
+export function clientDisplayName(client) {
+    return [client.givenName, client.familyName].filter(Boolean).join(' ');
+}
+/**
+ * Whether the page is rendered for a client in the portal. `client` and `company`
+ * are staff-only destinations, so an unknown surface also counts as a client:
+ * plain text is the safe failure, a dead link is not.
+ */
+export function isClientSurfacePath(pathname) {
+    const prefix = getSurfacePrefix(pathname);
+    return prefix !== '' && prefix !== NOTIFICATION_PREFIX;
+}

package/package.json

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

package/skills/assembly-platform-links/SKILL.md

@@ -22,6 +22,10 @@ If it reports `unsupported`, upgrade the app in this same turn instead of skippi
 4. Run `bunx tsc --noEmit` and `bun run build`, and confirm the existing header and toast bridge calls still type-check. Fix any break before continuing.
 5. Re-run the check above, then proceed with this skill.
 
+## Client and company names: use the components
+
+Render every client or company name with `<ClientName client={client} />` and `<CompanyName company={company} />` from `@assembly-js/app-foundation/lib-client`, in place of `{client.givenName} {client.familyName}` or `{company.name}`. They take the record objects the app already fetches and accept `className`. Staff get a link to the record's CRM page; a client viewer gets plain text. `bun run build` fails `check:linked-names` for a name rendered by hand. The rest of this skill covers other destinations.
+
 ## When to reach for this skill
 
 Any time the app renders a **name or reference to a platform entity** — a client name, a company badge, an invoice number, a contract, a form, a file — offer a link that opens the platform's canonical detail page, on surfaces where that destination is reachable (see the "Client portal" column in the destination catalog below). Internal/staff users can navigate to any destination. Clients in the portal can only reach the destinations marked available there — their own invoices, contracts, help articles, files, channels, and other installed apps — not `client`, `company`, `form`, or the other staff-only destinations, which the host rejects for a client viewer.