zz-meridian 0.34.0 → 0.36.0

package/README.md

@@ -34,7 +34,7 @@ npx zz-meridian@<version> brand [brand flags]     # rebrand this project, with t
 npx zz-meridian@latest skill [--global]           # install only the agent skill
 ```
 
-Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|jade|graphite`), `--theme dark|light`,
+Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--hue 250 --chroma 0.14`, or `--accent indigo|cobalt|jade|graphite`), `--theme dark|light`,
 `--workspace`, `--timezone`, `--currency`, `--user`, `--role`. `--workspace` sets `app.workspace`, the environment named
 in a page's kicker ("Production"); it does not touch the navigation workspaces.
 
@@ -81,7 +81,7 @@ refuses when one of those outputs was edited, while an update is open, or on a d
 it with the version the manifest records. The project's own `pnpm brand` still works, but its changes count as your edits.
 
 The standard a project on Meridian is built to is
-[data-layers.md](https://github.com/zhixuan312/zz-meridian/blob/main/docs/data-layers.md): the four layers between a
+[data-layers.md](https://github.com/zhixuan312/zz-meridian/blob/master/docs/data-layers.md): the four layers between a
 database and the screen, the contract a backend answers, and the six rules a project switches on in its own
 `scripts/check.local.ts`.
 
@@ -104,4 +104,4 @@ Meridian's own template or sample data.
 
 ## License
 
-MIT
+MIT: the text is `payload/LICENSE` in the package and `LICENSE` in a project `create` makes.

package/dist/adopt.js

@@ -3,18 +3,16 @@
  * its data layer. Everything here is the settled part of the skill's Route A; rebuilding each page on Meridian's
  * components is the agent's work, and the printed next step hands it over.
  *
- * Nothing is written until every check has passed: a dirty tree, a project that is not Next.js with the App Router,
- * or a file of the same name with other content stops it before the first write.
+ * Nothing is written until every check has passed: a project already on Meridian (its manifest: update is the command),
+ * a dirty tree, a project that is not Next.js with the App Router, or a file of the same name with other content stops
+ * it before the first write.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { VERSION, brandArgs, effectiveBrand, inside, installArgs, installSkill, jsoncExtras, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, skillPaths, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
 import { BRIEF_TEMPLATE, managedBlock, upsertManagedBlock } from './context.js';
-import { FIXED, adoptSetOf, managedPaths } from './ownership.js';
-/** The template's dependencies a dashboard built from these files needs. */
-const DEPS = ['next', 'react', 'react-dom', 'radix-ui', 'lucide-react', 'clsx', 'tailwind-merge', 'react-markdown', 'remark-gfm', 'ai', '@ai-sdk/react', 'zod'];
-const DEV_DEPS = ['typescript', '@types/node', '@types/react', '@types/react-dom', 'tailwindcss', '@tailwindcss/postcss', 'eslint', 'eslint-config-next', 'vitest', '@vitejs/plugin-react', 'jsdom', '@testing-library/react', '@testing-library/dom', '@testing-library/jest-dom'];
-const SCRIPTS = ['typecheck', 'test', 'tokens', 'check', 'contrast', 'gate', 'audit', 'verify', 'brand', 'shot', 'interactions', 'keyboard', 'vitals'];
+import { FIXED, adoptSetOf, managedPaths, parseManifest } from './ownership.js';
+import { MERIDIAN_SCRIPTS, TOOLCHAIN, needOf } from './reconcile.js';
 const major = (spec) => Number(/(\d+)/.exec(spec)?.[1] ?? NaN);
 const TS = /\.(ts|tsx)$/;
 /** A specifier inside a copied file, pinned to the exact module so a team file of a similar name can never win. */
@@ -93,13 +91,14 @@ export function projectConfig(template, pages) {
         .replace(/export const nav: NavGroup\[\] = \[[\s\S]*?\n\];/, `/** Written by zz-meridian adopt from the project's pages: give each its own icon and group them. */\nexport const nav: NavGroup[] = [\n  {\n    items: [\n${items}\n    ],\n  },\n];`);
 }
 /**
- * `scripts/verify.config.ts` as a project gets it. The sample's persona rows are what used `EVERY_ROUTE`, so replacing the
- * config object leaves the constant declared and never read — which the gate's own lint fails, in the project adopt just
- * wrote, 0.7 s after the other steps passed. Exported so a test can hold the rewrite to that.
+ * `scripts/verify.config.ts` as a project gets it. The sample's persona rows are what used `EVERY_ROUTE` and `ROLE_ROUTES`,
+ * so replacing the config object leaves them declared and never read — which the gate's own lint fails, in the project
+ * adopt just wrote, 0.7 s after the other steps passed — and names the sample's routes in the team's file. Each goes
+ * with its doc line. Exported so a test can hold the rewrite to that.
  */
 export function verifyConfig() {
     return readPayload('scripts/verify.config.ts')
-        .replace(/^const EVERY_ROUTE = \[[^\n]*\n/m, '')
+        .replace(/^\/\*\*[^\n]*\*\/\nconst (?:EVERY_ROUTE|ROLE_ROUTES) = \[[^\n]*\n\n?/gm, '')
         .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: [],
@@ -182,6 +181,17 @@ export function adopt(o) {
     // ── Checks: nothing is written until all of them pass ─────────────────────────────────────────────────
     if (!fs.existsSync(pkgPath))
         return fail(`no package.json in ${root}: run adopt in the project's folder`);
+    // A project adopt or create already set up holds Meridian's files as its manifest records them, and whatever the team
+    // changed since; adopted again, every edited one would be listed as a conflict. Moving it to this release is update's.
+    const manifestPath = path.join(root, '.meridian/manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        let at = '';
+        try {
+            at = ` ${parseManifest(fs.readFileSync(manifestPath, 'utf8')).version}`;
+        }
+        catch { /* the version is only named */ }
+        return fail(`this project is already on Meridian${at} (.meridian/manifest.json): run npx zz-meridian@latest update to move it to this release`);
+    }
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     const dir = appDir(root);
@@ -275,10 +285,13 @@ Rename or move them, then run adopt again.`);
             }
         }
     };
-    merge('dependencies', DEPS);
-    merge('devDependencies', DEV_DEPS);
+    // The packages the adopted modules import, and the framework: the rule `update` applies to a created project.
+    const sources = new Map(set.filter((rel) => TS.test(rel)).map((rel) => [rel, payloadBytes(rel).toString('utf8')]));
+    sources.set('src/app.config.ts', config);
+    merge('dependencies', needOf(tpl, sources).runtime);
+    merge('devDependencies', TOOLCHAIN);
     pkg.scripts ??= {};
-    for (const s of SCRIPTS) {
+    for (const s of MERIDIAN_SCRIPTS) {
         const want = tpl.scripts[s];
         if (!pkg.scripts[s])
             pkg.scripts[s] = want;
@@ -364,8 +377,11 @@ Rename or move them, then run adopt again.`);
     const brandDirs = () => ['tokens', 'src/styles'].flatMap((d) => listFiles(root, d));
     const existed = new Set(brandDirs());
     const b = run(process.execPath, ['scripts/brand.ts', ...brandArgs(brand), '--existing'], root);
-    if (b.status !== 0)
-        return fail('scripts/brand.ts failed (above); the files are copied, so fix the cause and run it again with the same flags');
+    if (b.status !== 0) {
+        // From a clean tree, git takes back exactly what adopt wrote; with --allow-dirty it would take the team's changes too.
+        const back = o.allowDirty ? 'remove what adopt wrote (git status shows it beside your own changes)' : 'put the tree back (git restore . && git clean -fd removes only what adopt wrote, since it started clean)';
+        return fail(`scripts/brand.ts failed (above) after the files were copied, and the manifest and agent files are not written. Fix the cause, ${back}, and run zz-meridian adopt again with the same flags`);
+    }
     // The project's own AGENTS.md keeps every byte and gains the managed block; the brief is the team's, written only when absent.
     // Neither is a Meridian file, so neither is recorded in the manifest.
     const pm = packageManager(root);

package/dist/cli.js

@@ -5,9 +5,8 @@
  */
 import os from 'node:os';
 import path from 'node:path';
-import { parseArgs } from 'node:util';
 import { adopt } from './adopt.js';
-import { misapplied } from './command-flags.js';
+import { misapplied, readFlags } from './command-flags.js';
 import { create } from './create.js';
 import { BRAND_FLAGS, VERSION, installSkill } from './files.js';
 import { brandCommand } from './rebrand.js';
@@ -40,29 +39,17 @@ Brand flags: --name "Acme Ops" --workspace Production --timezone Europe/London -
              --user "Ada Park" --role Admin --accent indigo|cobalt|jade|graphite | --hex '#2E6BE4' | --hue 250 --chroma 0.14
 
 Then give your coding agent the skill: .agents/skills/zz-meridian/SKILL.md.`;
-const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-        ...Object.fromEntries(BRAND_FLAGS.map((f) => [f, { type: 'string' }])),
-        'allow-dirty': { type: 'boolean' },
-        'no-install': { type: 'boolean' },
-        'dry-run': { type: 'boolean' },
-        resume: { type: 'boolean' },
-        finalize: { type: 'boolean' },
-        abort: { type: 'boolean' },
-        verify: { type: 'boolean' },
-        verbose: { type: 'boolean' },
-        global: { type: 'boolean' },
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean', short: 'v' },
-    },
-});
-const flags = values;
+const read = readFlags(process.argv.slice(2));
+if ('error' in read) {
+    console.error(`zz-meridian: ${read.error}. zz-meridian --help lists the commands and their flags.`);
+    process.exit(1);
+}
+const { values: flags, positionals } = read;
 const brand = Object.fromEntries(BRAND_FLAGS.flatMap((f) => (typeof flags[f] === 'string' ? [[f, flags[f]]] : [])));
-const install = !values['no-install'];
+const install = !flags['no-install'];
 const [command, arg] = positionals;
 function main() {
-    if (values.version) {
+    if (flags.version) {
         console.log(VERSION);
         return 0;
     }
@@ -72,9 +59,9 @@ function main() {
         console.error(`zz-meridian: --${unsafe[0]} may not contain a backslash or a line break`);
         return 1;
     }
-    if (values.help || !command) {
+    if (flags.help || !command) {
         console.log(HELP);
-        return command || values.help ? 0 : 1;
+        return command || flags.help ? 0 : 1;
     }
     // A flag a command does not read is refused, never ignored: `adopt --dry-run` wrote the project rather than previewing it.
     const wrong = misapplied(command, flags);
@@ -83,7 +70,7 @@ function main() {
         return 1;
     }
     if (command === 'adopt')
-        return adopt({ root: process.cwd(), brand, allowDirty: Boolean(values['allow-dirty']), install });
+        return adopt({ root: process.cwd(), brand, allowDirty: Boolean(flags['allow-dirty']), install });
     if (command === 'create') {
         if (!arg) {
             console.error('zz-meridian create: name the folder for the new dashboard');
@@ -92,26 +79,26 @@ function main() {
         return create({ dir: arg, brand, install });
     }
     if (command === 'update') {
-        const modes = ['dry-run', 'resume', 'finalize', 'abort'].filter((m) => values[m]);
+        const modes = ['dry-run', 'resume', 'finalize', 'abort'].filter((m) => flags[m]);
         if (modes.length > 1) {
             console.error(`zz-meridian update: ${modes.map((m) => `--${m}`).join(' and ')} cannot be combined`);
             return 1;
         }
-        if (values.verify && !values.finalize) {
+        if (flags.verify && !flags.finalize) {
             console.error('zz-meridian update: --verify belongs to --finalize');
             return 1;
         }
         const mode = modes[0] ?? 'update';
-        return update({ root: process.cwd(), mode, flags: { verbose: Boolean(values.verbose), allowDirty: Boolean(values['allow-dirty']), install, verify: Boolean(values.verify) } });
+        return update({ root: process.cwd(), mode, flags: { verbose: Boolean(flags.verbose), allowDirty: Boolean(flags['allow-dirty']), install, verify: Boolean(flags.verify) } });
     }
     if (command === 'brand')
-        return brandCommand({ root: process.cwd(), flags: brand, allowDirty: Boolean(values['allow-dirty']) });
+        return brandCommand({ root: process.cwd(), flags: brand, allowDirty: Boolean(flags['allow-dirty']) });
     if (command === 'skill') {
-        const roots = values.global ? [os.homedir()] : [process.cwd()];
+        const roots = flags.global ? [os.homedir()] : [process.cwd()];
         for (const r of roots)
             installSkill(r);
         const skill = path.join(roots[0], '.claude/skills/zz-meridian/SKILL.md');
-        console.log(`The zz-meridian skill is in ${values.global ? path.join(os.homedir(), '.agents/skills') + ' and ' + path.join(os.homedir(), '.claude/skills') : '.agents/skills and .claude/skills'}. Codex may need a restart to list it.`);
+        console.log(`The zz-meridian skill is in ${flags.global ? path.join(os.homedir(), '.agents/skills') + ' and ' + path.join(os.homedir(), '.claude/skills') : '.agents/skills and .claude/skills'}. Codex may need a restart to list it.`);
         console.log(`To follow it now, read ${skill} and the references beside it: it says how to build what was asked and when it is done.`);
         return 0;
     }

package/dist/command-flags.js

@@ -3,7 +3,39 @@
  * else it is refused by name rather than accepted and ignored, so `adopt --dry-run` never modifies a project while the
  * person waits for a preview.
  */
+import { parseArgs } from 'node:util';
 import { BRAND_FLAGS } from './files.js';
+/**
+ * The command line, read: its flags and positionals, or the reason it cannot be read (an unknown flag, a value-less one),
+ * as one line for the person rather than a stack trace.
+ */
+export function readFlags(args) {
+    try {
+        const { values, positionals } = parseArgs({
+            args,
+            allowPositionals: true,
+            options: {
+                ...Object.fromEntries(BRAND_FLAGS.map((f) => [f, { type: 'string' }])),
+                'allow-dirty': { type: 'boolean' },
+                'no-install': { type: 'boolean' },
+                'dry-run': { type: 'boolean' },
+                resume: { type: 'boolean' },
+                finalize: { type: 'boolean' },
+                abort: { type: 'boolean' },
+                verify: { type: 'boolean' },
+                verbose: { type: 'boolean' },
+                global: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+        return { values: { ...values }, positionals };
+    }
+    catch (e) {
+        // Node's first sentence names the flag; the rest is about positionals that start with a dash.
+        return { error: e.message.split('. ')[0] };
+    }
+}
 /** Every command reads these. */
 const EVERYWHERE = ['help', 'version'];
 /** The brand flags, read by the commands that write a brand. */

package/dist/context.js

@@ -41,8 +41,8 @@ Brand, layout and behaviour choices already made, one line each with its reason,
 ## Glossary
 The team's own words for things, one per line: term and what it means here.
 `;
-/** One `pnpm <script> [flags]` command, spelled for the package manager; npm needs `--` before flags. */
-function command(pm, script, flags) {
+/** A package script with flags, as the package manager runs it: npm passes flags on only after `--`. */
+export function command(pm, script, flags) {
     if (pm === 'pnpm')
         return `pnpm ${script}${flags}`;
     if (pm === 'npm')

package/dist/create.js

@@ -6,10 +6,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { managedPaths } from './ownership.js';
-import { BRIEF_TEMPLATE, managedBlock, upsertManagedBlock } from './context.js';
+import { BRIEF_TEMPLATE, command, managedBlock, upsertManagedBlock } from './context.js';
 import { VERSION, brandArgs, effectiveBrand, hasCommand, inside, installSkill, payloadBytes, payloadFiles, run, sha256, writeIn, writeManifest } from './files.js';
 export function create(o) {
     const root = path.resolve(o.dir);
+    if (fs.existsSync(root) && !fs.statSync(root).isDirectory())
+        return fail(`${root} is a file: name a new folder`);
     if (fs.existsSync(root) && fs.readdirSync(root).length)
         return fail(`${root} exists and is not empty: name a new folder`);
     let brand;
@@ -27,7 +29,7 @@ export function create(o) {
     const name = brand.name ?? path.basename(root).replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
     brand = effectiveBrand({ ...brand, name });
     if (run(process.execPath, ['scripts/brand.ts', ...brandArgs(brand), '--product'], root).status !== 0) {
-        return fail('scripts/brand.ts failed (above); the template is copied, so fix the cause and run it again with the same flags');
+        return fail(`scripts/brand.ts failed (above). ${root} holds the unbranded template and nothing else: fix the cause, delete the folder and run zz-meridian create again with the same flags`);
     }
     // pnpm installs from the template's lockfile, with install scripts off (pnpm-workspace.yaml). Without pnpm, corepack
     // (bundled with Node 22) runs it; only without both does npm install, from the version ranges, with scripts off too.
@@ -76,11 +78,15 @@ export function create(o) {
 ${name} is a new Meridian ${VERSION} dashboard in ${root}.
   skill: .agents/skills/zz-meridian (Codex) and .claude/skills/zz-meridian (Claude Code)
 
-Next: follow .agents/skills/zz-meridian/SKILL.md from step 3's brief (the template is fetched and branded): the brief,
-step 4's colour check, then data and the pages, then the loop in references/standard.md until ${pm} run verify --full --timed ends with "the project meets the
-Meridian standard" and no view on the scoreboard is Weak.`);
+${nextStep(pm)}`);
     return 0;
 }
+/** What the person does next, with the full verify written so their package manager passes its flags on. */
+export function nextStep(pm) {
+    return `Next: follow .agents/skills/zz-meridian/SKILL.md from step 3's brief (the template is fetched and branded): the brief,
+step 4's colour check, then data and the pages, then the loop in references/standard.md until ${command(pm, 'verify', ' --full --timed')} ends with "the project meets the
+Meridian standard" and no view on the scoreboard is Weak.`;
+}
 function fail(msg) {
     console.error(`zz-meridian create: ${msg}`);
     return 1;

package/dist/files.js

@@ -7,7 +7,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-/** The template snapshot this package carries, built from `git ls-files` at the release commit. */
+/** The template snapshot this package carries, extracted from the release commit by `git archive` (cli/scripts/build-payload.ts). */
 export const PAYLOAD = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'payload');
 export const VERSION = JSON.parse(fs.readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version;
 /**
@@ -73,6 +73,8 @@ export function writeIn(root, rel, content) {
     fs.writeFileSync(abs, content);
 }
 export const sha256 = (content) => `sha256-${createHash('sha256').update(content).digest('hex')}`;
+/** What a quiet command may print and still be read whole: past Node's 1 MiB default the child is killed, and a long gate reads as exit 1. */
+const OUTPUT = 256 * 1024 * 1024;
 /**
  * A command with its arguments, without a shell, so nothing in a name or a path is ever interpreted. The one exception
  * is a Windows .cmd shim (npm, pnpm, tsc), which Node runs only through a shell: those calls pass fixed arguments
@@ -80,7 +82,7 @@ export const sha256 = (content) => `sha256-${createHash('sha256').update(content
  */
 export function run(cmd, args, cwd, quiet = false) {
     const shim = process.platform === 'win32' && cmd !== process.execPath;
-    return spawnSync(shim && cmd.includes(' ') ? `"${cmd}"` : cmd, args, { cwd, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit', shell: shim });
+    return spawnSync(shim && cmd.includes(' ') ? `"${cmd}"` : cmd, args, { cwd, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit', shell: shim, maxBuffer: OUTPUT });
 }
 /** The package manager a project already uses, from its lockfile; npm when it has none. */
 export function packageManager(root) {
@@ -99,7 +101,7 @@ export function packageManager(root) {
 export const installArgs = (pm) => (pm === 'pnpm' ? ['install', '--no-frozen-lockfile'] : ['install']);
 /** A tool in the project's node_modules, run as `node <its script>`: no shell and no .cmd shim on any platform. */
 export function runTool(root, entry, args, quiet = true) {
-    return spawnSync(process.execPath, [path.join(root, 'node_modules', entry), ...args], { cwd: root, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit' });
+    return spawnSync(process.execPath, [path.join(root, 'node_modules', entry), ...args], { cwd: root, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit', maxBuffer: OUTPUT });
 }
 export const hasCommand = (cmd) => spawnSync(cmd, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
 /** A JSONC document's text with the comments dropped, and whether anything had to be dropped to read it. */
@@ -164,9 +166,16 @@ export function relativeImports(rel, source) {
         return `${lead}${q}${to}${q}`;
     });
 }
+/**
+ * The manifest file as every writer writes it: paths sorted by code unit (never the machine's collation), two-space
+ * indent, a final newline. Finalize tells an interrupted rename by comparing the file with this, byte for byte.
+ */
+export function manifestText(m) {
+    const files = Object.fromEntries(Object.entries(m.files).sort(([a], [b]) => (a < b ? -1 : 1)));
+    return `${JSON.stringify({ ...m, files }, null, 2)}\n`;
+}
 export function writeManifest(root, m) {
-    const sorted = Object.fromEntries(Object.entries(m.files).sort(([a], [b]) => a.localeCompare(b)));
-    writeIn(root, '.meridian/manifest.json', JSON.stringify({ ...m, files: sorted }, null, 2) + '\n');
+    writeIn(root, '.meridian/manifest.json', manifestText(m));
 }
 /**
  * Where the skill goes: the folders each agent reads in a repository, Codex (`.agents`) and Claude Code (`.claude`), and