zz-meridian 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# zz-meridian
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bring [ZZ Meridian](https://github.com/zhixuan312/zz-meridian), a dashboard design system for Next.js, into your
+project, or start a new dashboard on it. The package copies the files in and installs the agent skill; nothing in your
+dashboard depends on it afterwards.
+
+## The one sentence
+
+Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, from your frontend's folder:
+
+> Run `npx zz-meridian@latest adopt` here, then follow the zz-meridian skill it installs: keep our data layer and
+> routes, restyle every page with Meridian's components and tokens, and run pnpm verify until it passes.
+
+## Commands
+
+```sh
+npx zz-meridian@latest adopt [brand flags]        # bring Meridian into this Next.js App Router project
+npx zz-meridian@latest create <dir> [brand flags] # start a new dashboard
+npx zz-meridian@latest skill [--global]           # install only the agent skill
+```
+
+Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|jade|graphite`), `--workspace`,
+`--timezone`, `--currency`, `--user`, `--role`.
+
+**adopt** copies Meridian's tokens, styles, components, gates and scripts into `src/`, `tokens/` and `scripts/`;
+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; appends Meridian's rules to your `AGENTS.md`; installs the skill into
+`.agents/skills/` (Codex) and `.claude/skills/` (Claude Code); records every copied file 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/…`.
+
+It refuses, and writes nothing, when the git tree has uncommitted changes (so its change is one reviewable diff), when
+the project is not Next.js with the App Router, or when a file it would copy already exists with other content.
+
+**create** copies the template into a new folder, branded as your product, with the Design Atlas and the design
+system's own documents left out.
+
+Requires Node 22.18 or newer. The checks (`pnpm verify`) also need Google Chrome.
+
+## What this package does not do
+
+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
+commit and workflow each version came from.
+
+## License
+
+MIT

package/dist/adopt.js

@@ -0,0 +1,296 @@
+/**
+ * `zz-meridian adopt`: bring Meridian into an existing Next.js App Router project, in place, keeping its routes and
+ * 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.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { PAYLOAD, VERSION, brandArgs, inside, installSkill, packageManager, payloadFiles, readJsonc, readPayload, relativeImports, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
+/** The library modules Meridian's components and gates import; the rest of src/lib belongs to the template's pages. */
+const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown'].map((n) => `src/lib/${n}.ts`);
+/** What adopt copies from the template, as payload paths. The fixture build in CI is what keeps this list complete. */
+export function adoptSet() {
+    const own = (f) => !/(^|\/)(README\.md|preview\.tsx)$/.test(f);
+    return [
+        ...payloadFiles('tokens'),
+        ...payloadFiles('src/styles'),
+        ...payloadFiles('src/components').filter(own),
+        ...payloadFiles('scripts').filter((f) => f !== 'scripts/verify.config.ts'),
+        ...LIB,
+        'src/lib/assistant/prompt.ts',
+        'src/views/console-chrome.tsx',
+        'tests/setup.ts',
+    ];
+}
+/** 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'];
+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/jest-dom'];
+const SCRIPTS = ['typecheck', 'test', 'tokens', 'check', 'contrast', 'gate', 'audit', 'verify', 'brand', 'shot', 'interactions', 'keyboard', 'vitals'];
+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. */
+function exactImports(rel, source, known) {
+    const pin = (spec) => {
+        if (!spec.startsWith('.'))
+            return spec;
+        const base = path.posix.normalize(path.posix.join(path.posix.dirname(rel), spec));
+        if (['.ts', '.tsx'].some((x) => known.has(base + x)) || /\.(ts|tsx|css|json)$/.test(spec))
+            return spec;
+        if (['.ts', '.tsx'].some((x) => known.has(`${base}/index${x}`)))
+            return spec === '.' ? './index' : `${spec.replace(/\/$/, '')}/index`;
+        return spec;
+    };
+    return relativeImports(rel, source).replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])([\w@./()[\]-]+)\2/g, (_m, lead, q, spec) => `${lead}${q}${pin(spec)}${q}`);
+}
+function appDir(root) {
+    for (const d of ['app', 'src/app'])
+        if (['tsx', 'jsx', 'ts', 'js'].some((x) => fs.existsSync(path.join(root, d, `layout.${x}`))))
+            return d;
+    return null;
+}
+/** The static pages under the app folder, as routes: the first navigation, which the agent then edits. */
+function routes(root, dir) {
+    const out = [];
+    const walk = (abs, route) => {
+        for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+            if (e.isDirectory()) {
+                if (e.name.startsWith('[') || e.name.startsWith('_') || e.name.startsWith('@') || e.name === 'api' || e.name === 'node_modules')
+                    continue;
+                walk(path.join(abs, e.name), /^\(.*\)$/.test(e.name) ? route : [...route, e.name]);
+            }
+            else if (/^page\.(tsx|jsx|ts|js)$/.test(e.name))
+                out.push('/' + route.join('/'));
+        }
+    };
+    walk(path.join(root, dir), []);
+    // Only a plain path goes into generated code; anything else is left for the agent to add by hand.
+    return [...new Set(out)].filter((r) => /^\/[\w/.-]*$/.test(r)).sort((a, b) => (a === '/' ? -1 : b === '/' ? 1 : a.localeCompare(b)));
+}
+const label = (route) => (route === '/' ? 'Home' : route.split('/').pop().replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase()));
+function appConfig(pages) {
+    const template = readPayload('src/app.config.ts');
+    const items = pages.map((r) => `      { href: ${JSON.stringify(r)}, label: ${JSON.stringify(label(r))}, icon: LayoutGrid },`).join('\n');
+    return template
+        .replace(/^import \{[\s\S]*?\} from 'lucide-react';/m, "import { LayoutGrid, type LucideIcon } from 'lucide-react';")
+        .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];`);
+}
+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: [],
+};`);
+}
+/** The template's stylesheet, with its paths made relative to where the project keeps its own. */
+function globals(cssRel, dir) {
+    const from = path.posix.dirname(cssRel);
+    const rel = (to) => { const r = path.posix.relative(from, to) || '.'; return r.startsWith('.') ? r : `./${r}`; };
+    return readPayload('app/globals.css')
+        .replace(/"\.\.\/src\/styles\/([^"]+)"/g, (_m, f) => `"${rel(`src/styles/${f}`)}"`)
+        .replace(/@source "\.\.\/app";/, `@source "${rel(dir)}";`)
+        .replace(/@source "\.\.\/src";/, `@source "${rel('src')}";`);
+}
+function vitestConfig(alias) {
+    const aliases = [`'@meridian': path.resolve(import.meta.dirname, 'src')`, ...(alias !== null ? [`'@': path.resolve(import.meta.dirname, ${JSON.stringify(alias)})`] : [])];
+    return `import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+
+// Written by zz-meridian adopt: the gate runs these tests; tests/setup.ts stands in for what jsdom lacks.
+export default defineConfig({
+  plugins: [react()],
+  resolve: { alias: { ${aliases.join(', ')} } },
+  test: { environment: 'jsdom', setupFiles: ['./tests/setup.ts'], include: ['tests/**/*.test.{ts,tsx}'], passWithNoTests: true },
+});
+`;
+}
+export function adopt(o) {
+    const { root } = o;
+    const say = (s) => console.log(s);
+    const pkgPath = path.join(root, 'package.json');
+    // ── 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`);
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const dir = appDir(root);
+    if (!deps.next || !dir) {
+        return fail(`this is not a Next.js App Router project (no "next" dependency, or no app/layout or src/app/layout).
+Meridian's components are React; for another stack, read Route B or C in
+https://github.com/zhixuan312/zz-meridian/blob/master/skills/zz-meridian/references/existing-project.md`);
+    }
+    if (!o.allowDirty) {
+        const git = run('git', ['status', '--porcelain'], root, true);
+        if (git.status !== 0)
+            return fail('this folder is not a git repository, so the change could not be reviewed or undone as one diff. Commit it to git first, or pass --allow-dirty.');
+        if (git.stdout.trim())
+            return fail('the git tree has uncommitted changes. Commit or stash them first, so adopt\'s change is one reviewable diff (or pass --allow-dirty).');
+    }
+    const set = adoptSet();
+    const known = new Set(set);
+    const writes = new Map();
+    const owned = [];
+    const conflicts = [];
+    const notes = [];
+    const own = (rel, content) => {
+        const abs = path.join(root, rel);
+        if (fs.existsSync(abs)) {
+            if (fs.readFileSync(abs).equals(Buffer.from(content))) {
+                owned.push(rel);
+                return;
+            }
+            conflicts.push(rel);
+            return;
+        }
+        writes.set(rel, content);
+        owned.push(rel);
+    };
+    for (const rel of set) {
+        const raw = fs.readFileSync(path.join(PAYLOAD, rel));
+        own(rel, TS.test(rel) ? exactImports(rel, raw.toString('utf8'), known) : raw);
+    }
+    own('src/app.config.ts', exactImports('src/app.config.ts', appConfig(routes(root, dir)), known));
+    own('scripts/verify.config.ts', verifyConfig());
+    // Meridian's scripts are ES modules; a project whose package.json is not "type": "module" gets that for scripts/ only.
+    if (pkg.type !== 'module')
+        own('scripts/package.json', '{\n  "type": "module"\n}\n');
+    if (conflicts.length) {
+        return fail(`these files already exist with other content, so nothing was written:\n${conflicts.map((c) => `  ${c}`).join('\n')}
+Rename or move them, then run adopt again.`);
+    }
+    // ── Merged files: the project's own, changed only where Meridian needs it ────────────────────────────
+    const tpl = JSON.parse(readPayload('package.json'));
+    const merge = (field, names) => {
+        pkg[field] ??= {};
+        for (const n of names) {
+            const want = tpl.dependencies?.[n] ?? tpl.devDependencies?.[n];
+            if (!want)
+                continue;
+            const have = pkg.dependencies?.[n] ?? pkg.devDependencies?.[n];
+            if (!have) {
+                pkg[field][n] = want;
+                continue;
+            }
+            if (major(have) < major(want)) {
+                const at = pkg.dependencies?.[n] ? 'dependencies' : 'devDependencies';
+                pkg[at][n] = want;
+                notes.push(`raised ${n} from ${have} to ${want} (Meridian needs the newer major; read its upgrade guide)`);
+            }
+        }
+    };
+    merge('dependencies', DEPS);
+    merge('devDependencies', DEV_DEPS);
+    pkg.scripts ??= {};
+    for (const s of SCRIPTS) {
+        const want = tpl.scripts[s];
+        if (!pkg.scripts[s])
+            pkg.scripts[s] = want;
+        else if (pkg.scripts[s] !== want)
+            notes.push(`kept your "${s}" script; Meridian's is "${want}"`);
+    }
+    writes.set('package.json', JSON.stringify(pkg, null, 2) + '\n');
+    // tsconfig: Meridian's scripts import with .ts extensions, and its code needs ES2022; @meridian/* reaches its files.
+    const tsPath = path.join(root, 'tsconfig.json');
+    let atAlias = null;
+    if (fs.existsSync(tsPath)) {
+        const ts = readJsonc(tsPath);
+        ts.compilerOptions ??= {};
+        ts.compilerOptions.allowImportingTsExtensions = true;
+        ts.compilerOptions.noEmit = true;
+        if (!/^es20(2[2-9]|[3-9]\d)|^esnext$/i.test(ts.compilerOptions.target ?? '')) {
+            notes.push(`raised tsconfig target from ${ts.compilerOptions.target ?? 'its default'} to ES2022`);
+            ts.compilerOptions.target = 'ES2022';
+        }
+        ts.compilerOptions.paths ??= {};
+        ts.compilerOptions.paths['@meridian/*'] = ['./src/*'];
+        const at = ts.compilerOptions.paths['@/*']?.[0];
+        if (typeof at === 'string')
+            atAlias = at.replace(/\/\*$/, '').replace(/^\.\//, '') || '.';
+        writes.set('tsconfig.json', JSON.stringify(ts, null, 2) + '\n');
+    }
+    else {
+        return fail('no tsconfig.json: Meridian is TypeScript. Add one (next dev writes it), then run adopt again.');
+    }
+    // The global stylesheet: Meridian's, at the place the root layout already imports; theirs kept beside it to port from.
+    const layout = ['tsx', 'jsx', 'ts', 'js'].map((x) => `${dir}/layout.${x}`).find((f) => fs.existsSync(path.join(root, f)));
+    const layoutSrc = fs.readFileSync(path.join(root, layout), 'utf8');
+    const cssImport = /import\s+['"](\.{1,2}\/[^'"]+\.css)['"]/.exec(layoutSrc)?.[1];
+    const cssRel = cssImport ? path.posix.normalize(path.posix.join(path.posix.dirname(layout), cssImport)) : `${dir}/globals.css`;
+    const cssAbs = path.join(root, cssRel);
+    if (fs.existsSync(cssAbs)) {
+        const before = cssRel.replace(/\.css$/, '.before.css');
+        writes.set(before, fs.readFileSync(cssAbs));
+        notes.push(`your stylesheet is now Meridian's; the old one is ${before}, to port anything still needed from it as tokens`);
+    }
+    writes.set(cssRel, globals(cssRel, dir));
+    if (!cssImport) {
+        writes.set(layout, `import './globals.css';\n${layoutSrc}`);
+        notes.push(`${layout} now imports ./globals.css`);
+    }
+    const postcss = ['postcss.config.mjs', 'postcss.config.js', 'postcss.config.cjs'].find((f) => fs.existsSync(path.join(root, f)));
+    if (!postcss)
+        writes.set('postcss.config.mjs', readPayload('postcss.config.mjs'));
+    else if (!fs.readFileSync(path.join(root, postcss), 'utf8').includes('@tailwindcss/postcss')) {
+        writes.set(postcss.replace(/(\.[cm]?js)$/, '.before$1'), fs.readFileSync(path.join(root, postcss)));
+        writes.set(postcss, readPayload('postcss.config.mjs'));
+        notes.push(`${postcss} now runs Tailwind v4; the old one is kept beside it`);
+    }
+    if (!['ts', 'mts', 'js', 'mjs'].some((x) => fs.existsSync(path.join(root, `vitest.config.${x}`))))
+        writes.set('vitest.config.ts', vitestConfig(atAlias));
+    else
+        notes.push('kept your vitest config: add tests/setup.ts to its setupFiles and passWithNoTests for the gate');
+    if (!fs.readdirSync(path.join(root, dir)).some((f) => /^(icon|favicon)\./.test(f)))
+        writes.set(`${dir}/icon.ts`, exactImports(`${dir}/icon.ts`, readPayload('app/icon.ts'), known));
+    const ignore = path.join(root, '.gitignore');
+    const ignored = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
+    if (!/^\/?out\/?$/m.test(ignored))
+        writes.set('.gitignore', `${ignored.trimEnd()}\n\n# zz-meridian: verify's report and the screenshots\n/out/\n`);
+    // ── Write: every target checked first, so a bad one stops it before anything changes ─────────────────
+    try {
+        for (const rel of writes.keys())
+            inside(root, rel);
+    }
+    catch (e) {
+        return fail(e.message);
+    }
+    for (const [rel, content] of writes)
+        writeIn(root, rel, content);
+    const name = o.brand.name ?? String(pkg.name ?? path.basename(root)).replace(/^@[^/]+\//, '').replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    const brand = { ...o.brand, name };
+    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');
+    const files = {};
+    for (const rel of owned)
+        files[rel] = sha256(fs.readFileSync(inside(root, rel)));
+    installSkill(root, files);
+    writeManifest(root, { version: VERSION, route: 'adopt', brand, files });
+    // ── Install and prove it compiles ─────────────────────────────────────────────────────────────────────
+    const pm = packageManager(root);
+    let typed = 'not run (--no-install)';
+    if (o.install) {
+        say(`\nInstalling with ${pm}…`);
+        if (run(pm, ['install'], root).status !== 0)
+            return fail(`${pm} install failed (above). Fix it, then run ${pm} install and ${pm} run typecheck.`);
+        // Route types first (LayoutProps, PageProps), as the gate does.
+        runTool(root, 'next/dist/bin/next', ['typegen']);
+        const tsc = runTool(root, 'typescript/bin/tsc', ['--noEmit']);
+        typed = tsc.status === 0 ? 'passes' : `fails:\n${(tsc.stdout + tsc.stderr).trim().split('\n').slice(0, 30).join('\n')}`;
+    }
+    say(`
+Meridian ${VERSION} is in ${root}.
+  copied: ${owned.length} files (recorded in .meridian/manifest.json)
+  skill: .agents/skills/zz-meridian (Codex) and .claude/skills/zz-meridian (Claude Code)
+  types: ${typed}${notes.length ? `\n  notes:\n${notes.map((n) => `    - ${n}`).join('\n')}` : ''}
+
+Next: follow .agents/skills/zz-meridian/references/existing-project.md, Route A, from step 2 (step 1 was this). The
+template to read from is https://github.com/zhixuan312/zz-meridian/tree/v${VERSION}. Import Meridian's components as
+'@meridian/components/…'. Before the first ${pm} run verify, read step 5: verify presses every control, Delete included.`);
+    return 0;
+}
+function fail(msg) {
+    console.error(`zz-meridian adopt: ${msg}`);
+    return 1;
+}

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * zz-meridian: bring ZZ Meridian into a Next.js project, or start a new dashboard on it. The package copies files in
+ * and installs the agent skill; nothing in the dashboard depends on it afterwards.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { adopt } from './adopt.js';
+import { create } from './create.js';
+import { BRAND_FLAGS, VERSION, installSkill } from './files.js';
+const HELP = `zz-meridian ${VERSION}
+
+  npx zz-meridian@latest adopt [brand flags] [--allow-dirty] [--no-install]
+      Bring Meridian into the Next.js App Router project in this folder, keeping its routes and data layer.
+
+  npx zz-meridian@latest create <dir> [brand flags] [--no-install]
+      Start a new dashboard on Meridian in <dir>.
+
+  npx zz-meridian@latest skill [--global]
+      Install only the agent skill: into this project, or for every project (~/.agents/skills, ~/.claude/skills).
+
+Brand flags: --name "Acme Ops" --workspace Production --timezone Europe/London --currency EUR
+             --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' },
+        global: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+    },
+});
+const flags = values;
+const brand = Object.fromEntries(BRAND_FLAGS.flatMap((f) => (typeof flags[f] === 'string' ? [[f, flags[f]]] : [])));
+const install = !values['no-install'];
+const [command, arg] = positionals;
+function main() {
+    if (values.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    // A brand value is written into TypeScript and JSON; refuse what could end its string before anything is copied.
+    const unsafe = Object.entries(brand).find(([, v]) => /[\\\r\n\u2028\u2029]/.test(v));
+    if (unsafe) {
+        console.error(`zz-meridian: --${unsafe[0]} may not contain a backslash or a line break`);
+        return 1;
+    }
+    if (values.help || !command) {
+        console.log(HELP);
+        return command || values.help ? 0 : 1;
+    }
+    if (command === 'adopt')
+        return adopt({ root: process.cwd(), brand, allowDirty: Boolean(values['allow-dirty']), install });
+    if (command === 'create') {
+        if (!arg) {
+            console.error('zz-meridian create: name the folder for the new dashboard');
+            return 1;
+        }
+        return create({ dir: arg, brand, install });
+    }
+    if (command === 'skill') {
+        const roots = values.global ? [os.homedir()] : [process.cwd()];
+        for (const r of roots)
+            installSkill(r);
+        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.`);
+        return 0;
+    }
+    console.error(`zz-meridian: unknown command "${command}"\n\n${HELP}`);
+    return 1;
+}
+process.exitCode = main();

package/dist/create.js

@@ -0,0 +1,62 @@
+/**
+ * `zz-meridian create <dir>`: a new dashboard from the template, branded as the person's product (scripts/brand.ts
+ * --product removes the Design Atlas, the specifications and the design system's own docs), with the agent skill in
+ * the project and every file recorded in the manifest.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { PAYLOAD, VERSION, brandArgs, hasCommand, inside, installSkill, payloadFiles, run, sha256, writeIn, writeManifest } from './files.js';
+export function create(o) {
+    const root = path.resolve(o.dir);
+    if (fs.existsSync(root) && fs.readdirSync(root).length)
+        return fail(`${root} exists and is not empty: name a new folder`);
+    for (const rel of payloadFiles()) {
+        if (rel.startsWith('skills/'))
+            continue;
+        writeIn(root, rel, fs.readFileSync(path.join(PAYLOAD, rel)));
+    }
+    const name = o.brand.name ?? path.basename(root).replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    const brand = { ...o.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');
+    }
+    // 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.
+    const install = hasCommand('pnpm') ? ['pnpm', ['install']] : hasCommand('corepack') ? ['corepack', ['pnpm', 'install']] : ['npm', ['install', '--ignore-scripts']];
+    const pm = install[0] === 'npm' ? 'npm' : 'pnpm';
+    if (pm === 'npm') {
+        for (const f of ['pnpm-lock.yaml', 'pnpm-workspace.yaml'])
+            fs.rmSync(path.join(root, f), { force: true });
+        console.log('pnpm is not available: installing with npm from the version ranges, without a lockfile.');
+    }
+    const files = {};
+    const walk = (rel) => {
+        for (const e of fs.readdirSync(inside(root, rel || '.'), { withFileTypes: true })) {
+            const p = rel ? `${rel}/${e.name}` : e.name;
+            if (['node_modules', '.git', '.meridian', '.next'].includes(p))
+                continue;
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile())
+                files[p] = sha256(fs.readFileSync(inside(root, p)));
+        }
+    };
+    walk('');
+    installSkill(root, files);
+    writeManifest(root, { version: VERSION, route: 'create', brand, files });
+    if (hasCommand('git'))
+        run('git', ['init', '-q'], root);
+    if (o.install && run(install[0], install[1], root).status !== 0)
+        return fail(`${install.join(' ')} failed (above); run it again in ${root}`);
+    console.log(`
+${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 5 (the template is fetched and branded): data first, then
+the pages, then ${pm} run verify until it passes.`);
+    return 0;
+}
+function fail(msg) {
+    console.error(`zz-meridian create: ${msg}`);
+    return 1;
+}

package/dist/files.js

@@ -0,0 +1,144 @@
+/**
+ * The file work every command shares: where the payload is, reading and writing inside one project without ever
+ * leaving it, hashing for the manifest, and running a tool without a shell.
+ */
+import { createHash } from 'node:crypto';
+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. */
+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;
+/** Every file under a payload folder, as posix paths relative to the payload. Symbolic links are never followed. */
+export function payloadFiles(dir = '') {
+    const out = [];
+    const walk = (rel) => {
+        for (const e of fs.readdirSync(path.join(PAYLOAD, rel), { withFileTypes: true })) {
+            const p = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isSymbolicLink())
+                continue;
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile())
+                out.push(p);
+        }
+    };
+    if (fs.existsSync(path.join(PAYLOAD, dir)))
+        walk(dir);
+    return out.sort();
+}
+export const readPayload = (rel) => fs.readFileSync(path.join(PAYLOAD, rel), 'utf8');
+/**
+ * A path inside `root`; anything that would resolve outside it is refused: `..`, an absolute path, or a symbolic link
+ * on the way (a linked folder or file could carry a write somewhere else).
+ */
+export function inside(root, rel) {
+    const abs = path.resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + path.sep))
+        throw new Error(`refusing to touch ${rel}: it is outside ${root}`);
+    for (let p = abs; p !== root && p.startsWith(root + path.sep); p = path.dirname(p)) {
+        if (fs.lstatSync(p, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error(`refusing to touch ${rel}: ${path.relative(root, p)} is a symbolic link`);
+    }
+    return abs;
+}
+export function writeIn(root, rel, content) {
+    const abs = inside(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+}
+export const sha256 = (content) => `sha256-${createHash('sha256').update(content).digest('hex')}`;
+/**
+ * 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
+ * only, never a brand flag or a path the person typed; node itself (the brand script) never goes through a shell.
+ */
+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 });
+}
+/** The package manager a project already uses, from its lockfile; npm when it has none. */
+export function packageManager(root) {
+    if (fs.existsSync(path.join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(root, 'yarn.lock')))
+        return 'yarn';
+    if (fs.existsSync(path.join(root, 'bun.lock')) || fs.existsSync(path.join(root, 'bun.lockb')))
+        return 'bun';
+    return 'npm';
+}
+/** 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' });
+}
+export const hasCommand = (cmd) => spawnSync(cmd, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
+/** JSON with the comments and trailing commas a tsconfig may carry. */
+export function readJsonc(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    let out = '';
+    for (let i = 0, str = false; i < text.length; i++) {
+        const c = text[i];
+        if (str) {
+            out += c;
+            if (c === '\\')
+                out += text[++i];
+            else if (c === '"')
+                str = false;
+            continue;
+        }
+        if (c === '"') {
+            str = true;
+            out += c;
+            continue;
+        }
+        if (c === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+            continue;
+        }
+        if (c === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+}
+/**
+ * Meridian's own `@/` imports, made relative to the file. An adopting project may map `@/` somewhere else, or already
+ * have a `components/ui/button`; a relative import can never resolve to the team's file instead of Meridian's.
+ */
+export function relativeImports(rel, source) {
+    // A literal specifier only: a template string such as `import('@/${dir}')` is code that builds a path, not an import.
+    return source.replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])@\/([\w./()[\]-]+)\2/g, (_m, lead, q, spec) => {
+        let to = path.posix.relative(path.posix.dirname(rel), `src/${spec}`);
+        if (!to.startsWith('.'))
+            to = `./${to}`;
+        return `${lead}${q}${to}${q}`;
+    });
+}
+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');
+}
+/** The agent skill, into the folders each agent reads in a repository: Codex (.agents) and Claude Code (.claude). */
+export function installSkill(root, record) {
+    const files = payloadFiles('skills/zz-meridian');
+    for (const base of ['.agents/skills/zz-meridian', '.claude/skills/zz-meridian']) {
+        for (const f of files) {
+            const rel = `${base}/${f.slice('skills/zz-meridian/'.length)}`;
+            const content = fs.readFileSync(path.join(PAYLOAD, f));
+            writeIn(root, rel, content);
+            if (record)
+                record[rel] = sha256(content);
+        }
+    }
+}
+/** Brand flags passed through to scripts/brand.ts, in the order it reads them. */
+export const BRAND_FLAGS = ['name', 'workspace', 'timezone', 'currency', 'user', 'role', 'accent', 'hex', 'hue', 'chroma'];
+export const brandArgs = (brand) => BRAND_FLAGS.flatMap((k) => (brand[k] ? [`--${k}`, brand[k]] : []));