zz-meridian 0.15.0 → 0.16.0

package/README.md

@@ -42,7 +42,7 @@ in a page's kicker ("Production"); it does not touch the navigation workspaces.
 merges the dependencies and scripts it needs into your `package.json`; replaces your global stylesheet (yours is kept
 beside it as `*.before.css`); brands it; adds Meridian's managed block to your `AGENTS.md` between two markers, keeping your own text there byte
 for byte; writes an empty `docs/brief.md` (your product, users, data, decisions and glossary) if you have none; installs the skill into
-`.agents/skills/` (Codex) and `.claude/skills/` (Claude Code); records every copied file in `.meridian/manifest.json`;
+`.agents/skills/` (Codex) and `.claude/skills/` (Claude Code); records every Meridian file it copied in `.meridian/manifest.json`;
 installs and type checks. Your routes, your data layer and your own components are not touched. Meridian's files
 import each other by relative path, so a `components/ui/button` of your own is never confused with Meridian's; your
 code imports Meridian as `@meridian/…`.
@@ -61,7 +61,8 @@ writes nothing; run it first.
   deleted or kept (`.meridian/keep.json`) is never overwritten: an edited or deleted one is staged as base/ours/new copies
   for you to merge.
 - It adds the dependencies and scripts this release needs to `package.json` and updates Meridian's managed block in
-  `AGENTS.md`; a version or script you chose yourself becomes a migration to resolve, never a silent change.
+  `AGENTS.md`; an older version of the same major is raised, and a newer version, an older major or a script you
+  chose yourself becomes a migration to resolve, never a silent change.
 - It reports a migration for each interface the release changed where one of your own files still has the old shape,
   such as `cache-components-config` or `nav-needs`. `cli/src/migrations.ts` holds every one; resolve them as the skill's
   `references/update.md` says.
@@ -83,7 +84,7 @@ Requires Node 22.18 or newer. The default `pnpm verify` runs without Google Chro
 
 It has no dependencies and no install scripts: running it executes only its own code, and only when you call it. It
 sends nothing anywhere; the only network access is your package manager's install, which you can skip with
-`--no-install`. Every release is built and published by GitHub Actions with npm provenance, so the registry shows the
+`--no-install`, and `update` reading releases from npm. Every release is built and published by GitHub Actions with npm provenance, so the registry shows the
 commit and workflow each version came from.
 
 ## Privacy and feedback

package/dist/adopt.js

@@ -96,6 +96,8 @@ function verifyConfig() {
     return readPayload('scripts/verify.config.ts').replace(/const config: VerifyConfig = \{[\s\S]*?\n\};/, `const config: VerifyConfig = {
   // One detail page per state worth seeing (a normal record, a failed one, a missing one), with ids from your data.
   detailRoutes: [],
+  // What a route a persona may not open draws: the product's choice in src/app.config.ts.
+  refusal,
 };`);
 }
 /** The template's stylesheet, with its paths made relative to where the project keeps its own. */

package/dist/migrations.js

@@ -100,6 +100,134 @@ function callArity(src, fn) {
     }
     return out;
 }
+/** Where an import of the team's file `rel` points, as a project path with no extension; null for a package. */
+const resolvedImport = (rel, spec) => {
+    const bare = spec.replace(/\.[mc]?[jt]sx?$/, '');
+    if (bare.startsWith('@/'))
+        return `src/${bare.slice(2)}`;
+    return bare.startsWith('.') ? path.posix.join(path.posix.dirname(rel), bare) : null;
+};
+/** Each import of a file of the team's: the module it resolves to, the names it takes and its namespace, if it has one. */
+function importsOf(rel, src) {
+    const out = [];
+    for (const m of src.matchAll(/^\s*import\s+(?:type\s+)?([^'"]*?)\s+from\s+(['"])([^'"]+)\2/gm)) {
+        const from = resolvedImport(rel, m[3]);
+        if (from === null)
+            continue;
+        const names = (/\{([^}]*)\}/.exec(m[1])?.[1] ?? '').split(',').map((s) => s.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0]).filter(Boolean);
+        out.push({ from, names, namespace: /\*\s*as\s+([\w$]+)/.exec(m[1])?.[1] ?? null });
+    }
+    return out;
+}
+/**
+ * The index just past the string, template or comment that starts at `i`, or `i` when none does. A regular expression is
+ * not told from a division here: a view tool's object holds none whose brackets or quotes do not balance.
+ */
+function skipLiteral(src, i) {
+    const c = src[i], next = src[i + 1];
+    if (c === '/' && next === '/') {
+        const e = src.indexOf('\n', i);
+        return e < 0 ? src.length : e;
+    }
+    if (c === '/' && next === '*') {
+        const e = src.indexOf('*/', i + 2);
+        return e < 0 ? src.length : e + 2;
+    }
+    if (c === "'" || c === '"') {
+        let j = i + 1;
+        while (j < src.length && src[j] !== c && src[j] !== '\n')
+            j += src[j] === '\\' ? 2 : 1;
+        return j + 1;
+    }
+    if (c === '`') {
+        let j = i + 1;
+        while (j < src.length && src[j] !== '`') {
+            if (src[j] === '\\')
+                j += 2;
+            else if (src[j] === '$' && src[j + 1] === '{')
+                j = closeOf(src, j + 1) + 1;
+            else
+                j++;
+        }
+        return j + 1;
+    }
+    return i;
+}
+/** The index of the bracket that closes the `{`, `(` or `[` at `open`, passing over strings and comments. */
+function closeOf(src, open) {
+    let depth = 0;
+    for (let i = open; i < src.length;) {
+        const past = skipLiteral(src, i);
+        if (past !== i) {
+            i = past;
+            continue;
+        }
+        const c = src[i];
+        if ('{(['.includes(c))
+            depth++;
+        else if ('})]'.includes(c) && --depth === 0)
+            return i;
+        i++;
+    }
+    return src.length;
+}
+/**
+ * Each `defineViewTool({ … })` call of a file, as the keys of its object's own level, each with its value when that is a
+ * string and null otherwise; a key inside a nested object, call or function body, such as an input's `page`, is not
+ * the tool's. An object that spreads another has the key `...`, since what it spreads cannot be read here.
+ */
+function viewToolCalls(src) {
+    const out = [];
+    const call = /defineViewTool\s*(?:<[^>]*>)?\s*\(\s*\{/y;
+    const key = /(?:async\s+)?([A-Za-z_$][\w$]*)(?:\s*:\s*(['"])((?:\\.|(?!\2)[^\\\n])*)\2)?/y;
+    for (let i = 0; i < src.length;) {
+        const past = skipLiteral(src, i);
+        if (past !== i) {
+            i = past;
+            continue;
+        }
+        call.lastIndex = i;
+        const m = call.exec(src);
+        if (!m || /[\w$.]/.test(src[i - 1] ?? '')) {
+            i++;
+            continue;
+        }
+        const open = i + m[0].length - 1;
+        const close = closeOf(src, open);
+        const keys = new Map();
+        let prev = '{';
+        for (let k = open + 1; k < close;) {
+            const lit = skipLiteral(src, k);
+            if (lit !== k) {
+                k = lit;
+                continue;
+            }
+            const c = src[k];
+            if (/\s/.test(c)) {
+                k++;
+                continue;
+            }
+            if (prev === '{' || prev === ',') {
+                if (src.startsWith('...', k))
+                    keys.set('...', null);
+                key.lastIndex = k;
+                const found = key.exec(src);
+                if (found && !keys.has(found[1]))
+                    keys.set(found[1], found[3] ?? null);
+            }
+            if ('{(['.includes(c)) {
+                k = closeOf(src, k) + 1;
+                prev = '}';
+                continue;
+            }
+            prev = c;
+            k++;
+        }
+        out.push(keys);
+        i = close + 1;
+    }
+    return out;
+}
 // ── The registry ─────────────────────────────────────────────────────────────────────────────────────
 const GATE_AND_BUILD = ['gate', 'build'];
 export const RELEASE_MIGRATIONS = [
@@ -254,7 +382,135 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'The gate asked this of pages under `app/(dashboard)/` only; from 0.15.0 it asks it under whatever route group sits at the top of the app folder. Read "A page spec" in references/customize.md. Under `## Agents` in each page\'s README.md listed here, add `### What the agent reads`: what the page\'s shared context tells each agent, with a real line of it, and what the MCP App and the console assistant do with it. A copy of the rule kept in `scripts/check.local.ts` for the project\'s own group can be deleted.',
         checks: ['gate'],
     },
+    {
+        id: 'refusal-declared',
+        since: '0.16.0',
+        applies: refusalUndeclared,
+        summary: 'The product says what an address a person may not open draws: `refusal` in `src/app.config.ts`.',
+        instructions: 'Read "Navigation: `src/app.config.ts`" in references/customize.md. Add `export const refusal: \'explain\' | \'absent\' = \'explain\';` to `src/app.config.ts`, beside `facts`: `explain` keeps the no-access page a refused page draws today, and `absent` answers as an address that names nothing. A project that keeps the sample\'s access seam brings `src/data/access.ts` and `src/data/refusal.ts` over from the release (`gate` reads `refusal`, with `gatedMetadata` and `withheldEntries` beside it, and `gatedLoading` reads it alone), titles each gated page with `export function generateMetadata() { return gatedMetadata(\'<feature>\', { title: \'<its title>\' }); }` in place of a static `metadata`, passes its loading state\'s `name` and `title` through `gatedLoading`, and adds `refusal,` to the config object of `scripts/verify.config.ts`, imported from `../src/app.config.ts`, so `verify --as` expects the page the product chose.',
+        checks: GATE_AND_BUILD,
+    },
+    {
+        id: 'managed-exports-removed',
+        since: '0.16.0',
+        applies: removedExportReaders,
+        summary: 'A file of the team\'s imports an export the release removed from a managed module: `deviations`, `largest`, `runs` or `weekendRatio` from `src/lib/insight.ts`, or `queryInput` from `src/lib/collection.ts`.',
+        instructions: 'The update brought `src/lib/insight.ts` and `src/lib/collection.ts` without them, so each file listed here fails the type check. A file of the sample\'s comes over from the release: the Overview context is Home\'s, `src/views/home-context.ts` (see `sample-pages-renamed`); the assistant reads through `view_<name>` and `explore_<view>` and has no `query_<name>` tools, so bring `src/lib/assistant/tools.ts` and `src/lib/assistant/respond.ts` over and pass `readable`, every collection the person may read, from the assistant route to `respond` beside `collections` (read "Prepared queries" in references/agents.md); and a shipped test that imports one, such as `tests/shared-context.test.tsx` or `tests/collection.test.ts`, comes over as the release has it. A file of your own that still needs one of the functions writes it in that file, from its 0.15.0 source.',
+        checks: GATE_AND_BUILD,
+    },
+    {
+        id: 'view-tool-page-explore',
+        since: '0.16.0',
+        applies: (root) => matching(root, (_, src) => viewToolCalls(src).some((k) => !k.has('...') && !(k.has('page') && k.has('explore')))),
+        summary: 'Every view tool names the page it renders and its prepared query: `page` and `explore` on `defineViewTool`.',
+        instructions: 'Read "Prepared queries" in references/agents.md. Add to each `defineViewTool` call in the files listed here `page`, the console route of the page the view renders (a rail destination\'s `href` in `nav`, or a detail page\'s route with its segment, such as `/customers/[id]`), and `explore`, its prepared query (`PreparedQuery` in `src/lib/explore.ts`), declared beside the view as the sample\'s are in `src/views/<view>-explore.ts`. `ViewTool` in `src/lib/shared-context.ts` requires both, so a tool without them fails the type check. A project that kept the sample\'s view tools brings `src/views/tools.ts` and the `src/views/*-explore.ts` files over from the release. Once a tool names its page, the gate asks that page\'s specification what the agent does there (`agent-does-here-section`).',
+        checks: GATE_AND_BUILD,
+    },
+    {
+        id: 'agent-does-here-section',
+        since: '0.16.0',
+        applies: viewToolPagesWithoutAgentDoes,
+        summary: 'The specification of a page a view tool renders says what the agent does there.',
+        instructions: 'Read "Prepared queries" in references/agents.md. Under `## Agents` in the README.md of each page a view tool\'s `page` names, add `### What the agent does here`: a line `Protagonist: <the card\'s name>.`, then at least three questions a person on the page asks that its context does not answer alone, each `- "<question>" — <what the prepared query is asked>`, and mark that card on the page with `data-protagonist="<name>"`. `scripts/check.ts` fails the gate on such a page without the part. While a view tool in `src/views/tools.ts` names no page yet (`view-tool-page-explore`), every console page specification without the part is listed: one that no tool comes to name needs nothing.',
+        checks: ['gate'],
+    },
+    {
+        id: 'sample-pages-renamed',
+        since: '0.16.0',
+        applies: renamedSampleFiles,
+        summary: 'The project holds the sample\'s pages and views under their 0.15.0 names: Overview is Home, Analytics is Usage at `/usage` and Operations is Services at `/services`.',
+        instructions: 'The release renamed them with no redirect, and an update writes none of the team\'s pages, views or tests. Each file listed is one of them or names one: a page or a view, the view tools, `src/app.config.ts`\'s nav and the feature ids it names, the routes of `scripts/verify.config.ts`, or a shipped test that expects them. A project that kept the sample\'s pages as they were brings the release\'s over: `app/(dashboard)/` and `app/embed/`, `src/views/`, `src/data/`, `src/lib/assistant/` beside `prompt.ts`, `src/app.config.ts` with its own `app` kept, and each shipped test as the release has it; a file listed here that the release no longer has is deleted. A project that made the pages its own keeps its own names, makes the changes this release\'s other migrations list in them, and reads "not applicable" for the assistant walk-through\'s steps on Home and Now (`scripts/lib/sample.ts`).',
+        checks: GATE_AND_BUILD,
+    },
 ];
+/** The team's files that import an export 0.16.0 removed from a managed module, by name or through a namespace. */
+function removedExportReaders(root) {
+    const removed = { 'src/lib/insight': ['deviations', 'largest', 'runs', 'weekendRatio'], 'src/lib/collection': ['queryInput'] };
+    return matching(root, (rel, src) => importsOf(rel, src).some(({ from, names, namespace }) => {
+        const gone = removed[from] ?? [];
+        return names.some((n) => gone.includes(n)) || (namespace !== null && gone.some((g) => new RegExp(`(?<![\\w$.])${namespace.replace(/\$/g, '\\$')}\\.${g}\\b`).test(src)));
+    }));
+}
+/**
+ * The specifications of the pages the view tools of `src/views/tools.ts` render, as the gate reads them from 0.16.0,
+ * that lack "What the agent does here". While a tool names no page, the gate cannot tell its page, and neither can this:
+ * every console page specification without the part is listed then.
+ */
+function viewToolPagesWithoutAgentDoes(root) {
+    const tools = text(root, 'src/views/tools.ts');
+    if (tools === null)
+        return null;
+    const calls = viewToolCalls(tools).filter((k) => !k.has('...'));
+    if (calls.length === 0)
+        return null;
+    const pages = new Set(calls.map((k) => k.get('page')).filter((p) => typeof p === 'string'));
+    const unnamed = calls.some((k) => !k.has('page'));
+    const app = fs.existsSync(path.join(root, 'app')) ? 'app' : 'src/app';
+    const specs = [];
+    walk(root, app, specs, /^README\.md$/);
+    const hits = specs.filter((rel) => {
+        const rest = rel.slice(app.length + 1);
+        if (!/^\([^/)]+\)\//.test(rest))
+            return false;
+        const route = `/${path.posix.dirname(rest).split('/').filter((s) => !/^\(.*\)$/.test(s)).join('/')}`;
+        return (unnamed || pages.has(route)) && !/^## Agents$(?:\n(?!## ).*)*\n### What the agent does here$/m.test(text(root, rel) ?? '');
+    });
+    return hits.length > 0 ? hits : null;
+}
+/**
+ * The sample's pages and views under the names 0.16.0 replaced, and every file of the team's that names one: an import
+ * of one of their modules, a feature id or view tool of theirs, the walk-through's surfaces as they were, and the
+ * verify config's routes for them. Only a project that still holds one of the sample's old files is read, so a page of
+ * a product's own at the same address, or a feature of its own of the same name, is never taken for the sample's. The
+ * names are put together from their parts: the repository holds them out of everything but its history.
+ */
+function renamedSampleFiles(root) {
+    const old = ['overview', 'analytics', 'health'];
+    const modules = new Set([...old.flatMap((n) => [`src/views/${n}`, `src/views/${n}-context`]), `src/data/${old[1]}`]);
+    const group = `(${old[0]})`;
+    const named = new RegExp(`\\b(?:FEATURES\\.|view_)(?:${old.join('|')})\\b`);
+    const isOld = (rel) => modules.has(rel.replace(/\.[mc]?[jt]sx?$/, '')) || (/^(?:src\/)?app\//.test(rel) && rel.split('/').includes(group));
+    const sources = teamSources(root);
+    if (!sources.some((f) => isOld(f.rel)))
+        return null;
+    const seeds = sources.filter(({ rel, src }) => isOld(rel)
+        || importsOf(rel, src).some((i) => modules.has(i.from))
+        || named.test(src)
+        || (/\bsampleSurfaces\b/.test(src) && new RegExp(`\\b${old[0]}\\s*:|\\.${old[0]}\\b`).test(src))).map((f) => f.rel);
+    // A page or an embed view of the sample's goes with its folder: its loading state and its specification name nothing
+    // of the old, and are as much the sample's. A file that imports one of the old files, such as a test that renders the
+    // page, names it too; a file that only names one, such as the configuration, is not itself the old.
+    const oldFiles = new Set(sources.map((f) => f.rel).filter(isOld));
+    const pages = sources.filter(({ rel, src }) => /^(?:src\/)?app\//.test(rel) && /^(?:page|view)\.tsx?$/.test(base(rel)) && (isOld(rel) || importsOf(rel, src).some((i) => modules.has(i.from))));
+    for (const { rel } of pages) {
+        const dir = path.posix.dirname(rel);
+        try {
+            for (const e of fs.readdirSync(path.join(root, dir), { withFileTypes: true }))
+                if (e.isFile())
+                    oldFiles.add(`${dir}/${e.name}`);
+        }
+        catch { /* gone since it was read */ }
+    }
+    const oldPaths = new Set([...oldFiles].map((r) => r.replace(/\.[mc]?[jt]sx?$/, '')));
+    const found = new Set([...seeds, ...oldFiles]);
+    for (const { rel, src } of sources)
+        if (importsOf(rel, src).some((i) => oldPaths.has(i.from)))
+            found.add(rel);
+    const hits = [...found].sort();
+    const verifyConfig = 'scripts/verify.config.ts';
+    const routes = new RegExp(`'/(?:${old[1]}|${old[2]})'|title:\\s*'(?:Overview|Analytics|Operations)'`);
+    if (routes.test(text(root, verifyConfig) ?? ''))
+        hits.push(verifyConfig);
+    return hits;
+}
+/** The project's configuration, when it does not yet say what an address a person may not open draws (0.16.0). */
+function refusalUndeclared(root) {
+    const rel = 'src/app.config.ts';
+    const body = text(root, rel);
+    if (body === null)
+        return null;
+    return /^export const refusal\b/m.test(body) ? null : [rel];
+}
 /** The project's own nav, with any item still missing the `needs` that 0.13.0 requires of it. */
 function navItemsWithoutNeeds(root) {
     const rel = 'src/app.config.ts';

package/dist/ownership.js

@@ -1,14 +1,14 @@
 const HASH = /^sha256-[0-9a-f]{64}$/;
 const SEMVER = /^\d+\.\d+\.\d+$/;
 /** The library modules Meridian's components and gates import; the rest of src/lib belongs to the template's pages. */
-export const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown', 'logo', 'collection', 'live', 'shared-context', 'agent-guidance', 'insight'].map((n) => `src/lib/${n}.ts`);
+export const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown', 'logo', 'collection', 'explore', 'live', 'shared-context', 'agent-guidance', 'insight', 'facts'].map((n) => `src/lib/${n}.ts`);
 /** The single files adopt copies besides the folders and the library: all of them must be in a payload that is whole. */
 export const FIXED = [...LIB, 'src/lib/assistant/prompt.ts', 'src/views/console-chrome.tsx', 'tests/setup.ts'];
 /** The one rule, a plain-English line per clause. `references/ownership.md` renders it, so the guidance cannot drift. */
 export const OWNERSHIP = [
     'Managed: the payload files under `tokens/`, `src/styles/` and `src/components/`, except each component\'s `README.md` and `preview.tsx`.',
     'Managed: the distributed scripts under `scripts/`, except `scripts/verify.config.ts`, the first-load baseline `optional:scripts/verify.baseline.json` and a team-local `optional:scripts/check.local.ts`.',
-    'Managed: the library helpers `src/lib/cn.ts`, `src/lib/format.ts`, `src/lib/format-date.ts`, `src/lib/period.ts`, `src/lib/color.ts`, `src/lib/host.ts`, `src/lib/preferences.ts`, `src/lib/csv.ts`, `src/lib/safe-markdown.ts`, `src/lib/logo.ts`, `src/lib/collection.ts`, `src/lib/live.ts`, `src/lib/shared-context.ts`, `src/lib/agent-guidance.ts` and `src/lib/insight.ts`, and the assistant prompt `src/lib/assistant/prompt.ts`.',
+    'Managed: the library helpers `src/lib/cn.ts`, `src/lib/format.ts`, `src/lib/format-date.ts`, `src/lib/period.ts`, `src/lib/color.ts`, `src/lib/host.ts`, `src/lib/preferences.ts`, `src/lib/csv.ts`, `src/lib/safe-markdown.ts`, `src/lib/logo.ts`, `src/lib/collection.ts`, `src/lib/explore.ts`, `src/lib/live.ts`, `src/lib/shared-context.ts`, `src/lib/agent-guidance.ts`, `src/lib/insight.ts` and `src/lib/facts.ts`, and the assistant prompt `src/lib/assistant/prompt.ts`.',
     'Managed: `src/views/console-chrome.tsx` and `tests/setup.ts`.',
     'Managed: `optional:scripts/package.json`, only when the adopt or create that set the project up generated it for this project shape.',
     'Managed: both installed skill trees, `optional:.agents/skills/zz-meridian/` and `optional:.claude/skills/zz-meridian/`, taken from the release\'s skill payload.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",