nimiq-branding-cli 1.1.0 → 1.2.0

package/scripts/audit.mjs

@@ -0,0 +1,247 @@
+// nq audit — the self-learning branding-drift engine.
+//
+// Branding accuracy has two axes:
+//   (1) our vendored upstream pin == the LIVE Nimiq design  (this file)
+//   (2) our port == the vendored upstream truth render       (scripts/verify.mjs)
+// `nq verify` only covers (2) against a FROZEN snapshot. This audit covers (1):
+// it asks "has the live Nimiq source moved away from what we ported?", attributes
+// any drift to the exact components it touches (via meta.json `source.files`),
+// classifies each change through an accumulated learnings store, runs the pixel
+// verify, and emits a verdict the weekly workflow acts on (auto-PR safe / alert risky).
+//
+// Works locally (uses the gitignored upstream/<repo> clones) AND in CI (no clones:
+// `git ls-remote` for live tips + the GitHub compare API for changed files).
+//
+// Usage: node scripts/audit.mjs [--skip-verify] [--json]
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const COMPONENTS = join(ROOT, 'registry', 'components');
+const SKIP_VERIFY = process.argv.includes('--skip-verify');
+const JSON_ONLY = process.argv.includes('--json');
+
+// ---------- tiny helpers ----------
+function sh(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...opts }).trim();
+}
+function try_(fn, fallback = null) { try { return fn(); } catch { return fallback; } }
+
+// glob ("wallet:**/*Sentry*") -> RegExp. Supports ** (any incl. /), * (any excl. /).
+function globToRe(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') { re += '.*'; i++; if (glob[i + 1] === '/') i++; }
+      else re += '[^/]*';
+    } else if ('.+?^${}()|[]\\'.includes(c)) re += '\\' + c;
+    else re += c;
+  }
+  return new RegExp('^' + re + '$');
+}
+
+// ---------- inputs ----------
+async function loadPins() {
+  return JSON.parse(await readFile(join(ROOT, 'upstream-pins.json'), 'utf8')).repos;
+}
+async function loadLearnings() {
+  const p = join(ROOT, 'audit', 'learnings.json');
+  if (!existsSync(p)) return { rules: [] };
+  return JSON.parse(await readFile(p, 'utf8'));
+}
+// "repo:path" -> [componentName...]   and  componentName -> {repo, files}
+async function loadProvenance() {
+  const index = {}; const byComponent = {};
+  for (const name of (await readdir(COMPONENTS)).sort()) {
+    const meta = JSON.parse(await readFile(join(COMPONENTS, name, 'meta.json'), 'utf8'));
+    const src = meta.source ?? { repo: 'unknown', files: [] };
+    byComponent[name] = src;
+    for (const f of src.files ?? []) (index[f] ??= []).push(name);
+  }
+  return { index, byComponent };
+}
+
+// ---------- upstream drift ----------
+function repoSlug(url) { // https://github.com/nimiq/wallet.git -> nimiq/wallet
+  const m = url.match(/github\.com[:/]+([^/]+\/[^/.]+)/);
+  return m ? m[1] : null;
+}
+function liveTip(repo, info) {
+  const local = join(ROOT, 'upstream', repo);
+  if (existsSync(join(local, '.git'))) {
+    try_(() => sh('git', ['-C', local, 'fetch', '--quiet', 'origin', info.branch]));
+    const tip = try_(() => sh('git', ['-C', local, 'rev-parse', `origin/${info.branch}`]));
+    if (tip) return { tip, via: 'local' };
+  }
+  const ls = try_(() => sh('git', ['ls-remote', info.url, `refs/heads/${info.branch}`]));
+  if (ls) return { tip: ls.split(/\s+/)[0], via: 'ls-remote' };
+  return { tip: null, via: 'unreachable' };
+}
+function changedFiles(repo, info, base, head) {
+  const local = join(ROOT, 'upstream', repo);
+  // local clone: direct diff (most reliable, offline)
+  if (existsSync(join(local, '.git'))) {
+    const out = try_(() => sh('git', ['-C', local, 'diff', '--name-only', `${base}..${head}`]));
+    if (out !== null) return out ? out.split('\n') : [];
+  }
+  // CI: GitHub compare API. Prefer authenticated gh (higher rate limit), else fetch.
+  const slug = repoSlug(info.url);
+  if (slug) {
+    const viaGh = try_(() => sh('gh', ['api', `repos/${slug}/compare/${base}...${head}`, '--jq', '.files[].filename']));
+    if (viaGh !== null) return viaGh ? viaGh.split('\n') : [];
+  }
+  return null; // unknown — drift detected but file list unavailable
+}
+
+function classify(repoPath, learnings) {
+  for (const rule of learnings.rules ?? []) {
+    if (globToRe(rule.pattern).test(repoPath)) return rule;
+  }
+  return null; // unknown -> triage
+}
+
+// ---------- main ----------
+const pins = await loadPins();
+const learnings = await loadLearnings();
+const { index: provIndex, byComponent } = await loadProvenance();
+
+const report = {
+  generatedAtNote: 'timestamp stamped by caller',
+  verdict: 'clean',
+  repos: {},
+  driftedComponents: [],   // components whose upstream source changed
+  tokenDrift: [],          // framework-level css/scss/token changes
+  unknownPaths: [],        // changed paths with no learnings rule -> need triage
+  verify: { ran: false },
+  newComponents: [],       // upstream components not yet in the registry
+  summary: '',
+};
+
+let anyDrift = false, riskyDrift = false;
+
+for (const [repo, info] of Object.entries(pins)) {
+  const { tip, via } = liveTip(repo, info);
+  const base = info.pinned;
+  const drifted = tip && tip !== base;
+  const entry = { branch: info.branch, pinned: base.slice(0, 8), live: tip ? tip.slice(0, 8) : null, pinnedFull: base, liveFull: tip, via, drifted: !!drifted };
+  if (drifted) {
+    anyDrift = true;
+    const files = changedFiles(repo, info, base, tip);
+    entry.changedFileCount = files ? files.length : null;
+    entry.changedFiles = files ? files.slice(0, 500) : null;
+    for (const path of files ?? []) {
+      const repoPath = `${repo}:${path}`;
+      // does this file feed a registry component?
+      const touchedComponents = new Set();
+      for (const [provFile, comps] of Object.entries(provIndex)) {
+        if (provFile === repoPath) comps.forEach(c => touchedComponents.add(c));
+      }
+      const rule = classify(repoPath, learnings);
+      if (touchedComponents.size) {
+        riskyDrift = true; // a real component source moved -> needs re-port review
+        report.driftedComponents.push({ repoPath, components: [...touchedComponents], verdict: rule?.verdict ?? 'branding' });
+      } else if (rule?.verdict === 'branding' || rule?.verdict === 'token') {
+        riskyDrift = true;
+        report.tokenDrift.push({ repoPath, rule: rule.pattern, reason: rule.reason });
+      } else if (rule?.verdict === 'ignore') {
+        // benign churn (deps, telemetry, CI) — known noise, no action
+      } else {
+        report.unknownPaths.push(repoPath); // no rule -> triage (treated risky)
+        riskyDrift = true;
+      }
+    }
+    if (files === null) { entry.note = 'drift detected but changed-file list unavailable (no clone + compare API failed)'; riskyDrift = true; }
+  }
+  report.repos[repo] = entry;
+}
+
+// ---------- new-component radar (best-effort, needs the vue-components clone) ----------
+{
+  const vc = join(ROOT, 'upstream', 'vue-components', 'src', 'components');
+  if (existsSync(vc)) {
+    const ported = new Set(Object.values(byComponent).flatMap(s => (s.files ?? []).filter(f => f.startsWith('vue-components:')).map(f => f.split(':')[1])));
+    for (const f of (await readdir(vc)).filter(f => f.endsWith('.vue'))) {
+      const path = `src/components/${f}`;
+      if (!ported.has(path)) report.newComponents.push(`vue-components:${path}`);
+    }
+  } else {
+    report.newComponents = ['(skipped — vue-components clone not present; see FEATURES.md roadmap)'];
+  }
+}
+
+// ---------- port fidelity (pixel verify) ----------
+if (!SKIP_VERIFY) {
+  try {
+    const { verify } = await import(join(ROOT, 'scripts', 'verify.mjs'));
+    const names = (await readdir(COMPONENTS)).sort();
+    let pass = 0, fail = 0, skip = 0; const failed = [];
+    for (const n of names) {
+      const r = await verify(n);
+      if (r.status === 'pass') pass++;
+      else if (r.status === 'skip') skip++;
+      else { fail++; failed.push({ name: n, diffPct: r.diffPct }); }
+    }
+    report.verify = { ran: true, pass, fail, skip, failed };
+    if (fail) riskyDrift = true;
+  } catch (e) {
+    report.verify = { ran: false, error: e.message };
+  }
+}
+
+// ---------- verdict ----------
+// clean  : nothing moved, ports green
+// safe   : upstream moved but ONLY in benign (learnings-classified "ignore") files,
+//          no component/token touched, no unknown paths, verify green -> auto-PR pin bump
+// risky  : a component source moved, token-relevant change, unknown paths, or verify failed -> alert
+if (!anyDrift && (!report.verify.ran || report.verify.fail === 0)) report.verdict = 'clean';
+else if (anyDrift && !riskyDrift) report.verdict = 'safe';
+else report.verdict = 'risky';
+
+report.summary = [
+  `verdict: ${report.verdict}`,
+  `${Object.values(report.repos).filter(r => r.drifted).length}/${Object.keys(report.repos).length} upstream(s) drifted`,
+  `${report.driftedComponents.length} component(s) upstream-touched`,
+  `${report.tokenDrift.length} token-drift`,
+  `${report.unknownPaths.length} unknown path(s)`,
+  report.verify.ran ? `verify ${report.verify.pass}✓/${report.verify.fail}✗/${report.verify.skip}·` : 'verify skipped',
+].join(' · ');
+
+// ---------- write report ----------
+await mkdir(join(ROOT, '.audit'), { recursive: true });
+await writeFile(join(ROOT, '.audit', 'report.json'), JSON.stringify(report, null, 2) + '\n');
+await writeFile(join(ROOT, '.audit', 'report.md'), renderMd(report));
+
+if (JSON_ONLY) console.log(JSON.stringify(report, null, 2));
+else {
+  console.log(`\nnq audit — ${report.summary}\n`);
+  for (const [repo, r] of Object.entries(report.repos)) {
+    console.log(`  ${r.drifted ? '⚠' : '✓'} ${repo.padEnd(15)} ${r.pinned} → ${r.live ?? '?'}${r.drifted ? `  (${r.changedFileCount ?? '?'} files, ${r.via})` : '  up-to-date'}`);
+  }
+  if (report.driftedComponents.length) { console.log('\n  upstream-touched components (need re-port review):'); report.driftedComponents.forEach(d => console.log(`    ✗ ${d.components.join(', ')}  ←  ${d.repoPath}`)); }
+  if (report.tokenDrift.length) { console.log('\n  token / framework drift:'); report.tokenDrift.forEach(d => console.log(`    ! ${d.repoPath} (${d.reason})`)); }
+  if (report.unknownPaths.length) { console.log(`\n  unknown paths needing triage: ${report.unknownPaths.length} (see .audit/report.md)`); }
+  if (report.newComponents.length) { console.log(`\n  new-component radar: ${report.newComponents.length} upstream component(s) not in registry`); }
+  console.log(`\n  full report: .audit/report.md\n`);
+}
+
+// verdict drives the workflow; non-zero only on risky so a CI step can branch on it too
+process.exitCode = report.verdict === 'risky' ? 2 : 0;
+
+function renderMd(r) {
+  const L = [];
+  L.push(`# nq audit report`, ``, `**${r.summary}**`, ``);
+  L.push(`## Upstream pins vs live`, ``, `| repo | branch | pinned | live | drifted | changed files |`, `|---|---|---|---|---|---|`);
+  for (const [repo, e] of Object.entries(r.repos)) L.push(`| ${repo} | ${e.branch} | \`${e.pinned}\` | \`${e.live ?? '?'}\` | ${e.drifted ? '**yes**' : 'no'} | ${e.drifted ? (e.changedFileCount ?? '?') : '—'} |`);
+  L.push(``);
+  if (r.driftedComponents.length) { L.push(`## ⚠ Components whose upstream source changed (re-port review)`, ``); for (const d of r.driftedComponents) L.push(`- \`${d.repoPath}\` → **${d.components.join(', ')}**`); L.push(``); }
+  if (r.tokenDrift.length) { L.push(`## Token / framework drift`, ``); for (const d of r.tokenDrift) L.push(`- \`${d.repoPath}\` — ${d.reason}`); L.push(``); }
+  if (r.unknownPaths.length) { L.push(`## Unknown changed paths (need triage → add a learnings rule)`, ``); for (const p of r.unknownPaths) L.push(`- \`${p}\``); L.push(``); }
+  if (r.verify.ran) { L.push(`## Port fidelity (pixel verify)`, ``, `${r.verify.pass} pass · ${r.verify.fail} fail · ${r.verify.skip} skip`, ``); if (r.verify.failed?.length) for (const f of r.verify.failed) L.push(`- ✗ ${f.name} (${f.diffPct}%)`); L.push(``); }
+  if (r.newComponents.length) { L.push(`## New-component radar`, ``, `Upstream components with no registry port yet (candidates — cross-ref FEATURES.md):`, ``); for (const n of r.newComponents) L.push(`- \`${n}\``); L.push(``); }
+  L.push(`---`, ``, `Verdicts: **clean** (nothing moved) · **safe** (only learnings-"ignore" churn → auto-PR pin bump) · **risky** (component/token/unknown/verify-fail → human review).`);
+  return L.join('\n') + '\n';
+}

package/scripts/bootstrap-provenance.mjs

@@ -0,0 +1,126 @@
+// One-time (idempotent) bootstrap: write a structured `source` provenance block
+// into every registry component's meta.json. The audit (scripts/audit.mjs) reads
+// this to attribute an upstream diff to the exact components it touches.
+//
+// `source` schema:
+//   { "repo": "<primary repo|original|nimiq-com>",
+//     "ref":  "<short sha of the primary repo's vendored pin at bootstrap>",
+//     "files": ["<repo>:<path within upstream/<repo>>", ...] }
+//
+// `files` entries are "repo:path" strings (primary repo first) so the audit can
+// split on ":" and the format matches audit/learnings.json patterns.
+//
+// Run: node scripts/bootstrap-provenance.mjs [--check]
+//   --check : report only, do not write.
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const COMPONENTS = join(ROOT, 'registry', 'components');
+const CHECK = process.argv.includes('--check');
+
+// Primary repo + the upstream source file(s) each component was ported from.
+// Derived from meta.notes citations, the @nimiq/vue-components PascalCase
+// mapping, and the FEATURES.md "Built from:" survey. Marketing components are
+// calibrated to nimiq.com screenshots/assets (no vendored git repo → "nimiq-com");
+// flag-hex is an original brand composition ("original").
+const MAP = {
+  // --- @nimiq/vue-components ports (upstream/vue-components/src/components/*.vue) ---
+  'account-list':      { repo: 'vue-components', files: ['vue-components:src/components/AccountList.vue', 'vue-components:src/components/Identicon.vue'] },
+  'account-ring':      { repo: 'vue-components', files: ['vue-components:src/components/AccountRing.vue', 'vue-components:src/components/Identicon.vue'] },
+  'address-display':   { repo: 'vue-components', files: ['vue-components:src/components/AddressDisplay.vue'] },
+  'address-input':     { repo: 'vue-components', files: ['vue-components:src/components/AddressInput.vue'] },
+  'amount':            { repo: 'vue-components', files: ['vue-components:src/components/Amount.vue'] },
+  'amount-input':      { repo: 'vue-components', files: ['vue-components:src/components/AmountInput.vue'] },
+  'amount-with-fee':   { repo: 'vue-components', files: ['vue-components:src/components/AmountWithFee.vue', 'vue-components:src/components/AmountInput.vue'] },
+  'close-button':      { repo: 'vue-components', files: ['vue-components:src/components/CloseButton.vue'] },
+  'copyable':          { repo: 'vue-components', files: ['vue-components:src/components/Copyable.vue'] },
+  'fiat-amount':       { repo: 'vue-components', files: ['vue-components:src/components/FiatAmount.vue'] },
+  'identicon':         { repo: 'vue-components', files: ['vue-components:src/components/Identicon.vue'] },
+  'label-input':       { repo: 'vue-components', files: ['vue-components:src/components/LabelInput.vue'] },
+  'loading-spinner':   { repo: 'vue-components', files: ['vue-components:src/components/LoadingSpinner.vue'] },
+  'page-body':         { repo: 'vue-components', files: ['vue-components:src/components/PageBody.vue'] },
+  'page-footer':       { repo: 'vue-components', files: ['vue-components:src/components/PageFooter.vue'] },
+  'page-header':       { repo: 'vue-components', files: ['vue-components:src/components/PageHeader.vue'] },
+  'payment-info-line': { repo: 'vue-components', files: ['vue-components:src/components/PaymentInfoLine.vue', 'vue-components:src/components/Timer.vue', 'vue-components:src/components/Identicon.vue'] },
+  'qr-code':           { repo: 'vue-components', files: ['vue-components:src/components/QrCode.vue'] },
+  'select-bar':        { repo: 'vue-components', files: ['vue-components:src/components/SelectBar.vue'] },
+  'slider-toggle':     { repo: 'vue-components', files: ['vue-components:src/components/SliderToggle.vue'] },
+  'small-page':        { repo: 'vue-components', files: ['vue-components:src/components/SmallPage.vue'] },
+  'timer':             { repo: 'vue-components', files: ['vue-components:src/components/Timer.vue'] },
+  'tooltip':           { repo: 'vue-components', files: ['vue-components:src/components/Tooltip.vue'] },
+
+  // --- CSS-framework components (upstream/nimiq-style) ---
+  'buttons': { repo: 'nimiq-style', files: ['nimiq-style:src/buttons.css', 'nimiq-style:nimiq-style.min.css'] },
+  'card':    { repo: 'nimiq-style', files: ['nimiq-style:src/layout.css', 'nimiq-style:nimiq-style.min.css'] },
+
+  // --- wallet ports (upstream/wallet/src/components) ---
+  'account-header':       { repo: 'wallet', files: ['wallet:src/components/layouts/AddressOverview.vue', 'wallet:src/components/SearchBar.vue', 'wallet:src/components/staking/StakingButton.vue', 'wallet:src/components/icons/Staking/StakingIcon.vue'] },
+  'backup-banner':        { repo: 'wallet', files: ['wallet:src/components/layouts/AccountOverview.vue'] },
+  'balance-distribution': { repo: 'wallet', files: ['wallet:src/components/BalanceDistribution.vue'] },
+  'consensus-icon':       { repo: 'wallet', files: ['wallet:src/components/ConsensusIcon.vue', 'wallet:src/components/icons/WorldCheckIcon.vue'] },
+  'price-chart':          { repo: 'wallet', files: ['wallet:src/components/PriceChart.vue', 'wallet:src/components/LineChart.vue'] },
+  'search-bar':           { repo: 'wallet', files: ['wallet:src/components/SearchBar.vue'] },
+  'swap-balance-bar':     { repo: 'wallet', files: ['wallet:src/components/swap/SwapBalanceBar.vue'] },
+  'toast-notification':   { repo: 'wallet', files: ['wallet:src/components/swap/SwapNotification.vue'] },
+  'transaction-list':     { repo: 'wallet', files: ['wallet:src/components/TransactionListItem.vue', 'wallet:src/components/TransactionList.vue'] },
+
+  // --- hub ---
+  'status-screen': { repo: 'hub', files: ['hub:src/components/StatusScreen.vue'] },
+
+  // --- nimiq-ui (docs theme) ---
+  'status-alert': { repo: 'nimiq-ui', files: ['nimiq-ui:packages/nimiq-vitepress-theme/src/assets/github-callouts.css'] },
+
+  // --- marketing: calibrated to nimiq.com (no vendored git repo) ---
+  'app-showcase-card': { repo: 'nimiq-com', files: [] },
+  'hero-section':      { repo: 'nimiq-com', files: [] },
+  'honeycomb-band':    { repo: 'nimiq-com', files: [] },
+
+  // --- original brand composition ---
+  'flag-hex': { repo: 'original', files: [] },
+};
+
+const VIRTUAL = new Set(['original', 'nimiq-com']); // not vendored git repos
+
+function shortHead(repo) {
+  if (VIRTUAL.has(repo)) return null;
+  try {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: join(ROOT, 'upstream', repo), encoding: 'utf8',
+    }).trim();
+  } catch { return null; }
+}
+
+function fileExists(spec) {
+  const [repo, ...rest] = spec.split(':');
+  const path = rest.join(':');
+  if (VIRTUAL.has(repo)) return true;
+  return existsSync(join(ROOT, 'upstream', repo, path));
+}
+
+const { readdir } = await import('node:fs/promises');
+const names = (await readdir(COMPONENTS)).sort();
+let missing = [], unresolved = [], wrote = 0;
+
+for (const name of names) {
+  const entry = MAP[name];
+  if (!entry) { missing.push(name); continue; }
+  for (const f of entry.files) if (!fileExists(f)) unresolved.push(`${name} → ${f}`);
+
+  const metaPath = join(COMPONENTS, name, 'meta.json');
+  const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+  meta.source = { repo: entry.repo, ref: shortHead(entry.repo), files: entry.files };
+  if (!CHECK) {
+    await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    wrote++;
+  }
+}
+
+console.log(`components: ${names.length}, mapped: ${names.length - missing.length}, ${CHECK ? 'checked' : `wrote ${wrote}`}`);
+if (missing.length) console.log(`UNMAPPED (no MAP entry): ${missing.join(', ')}`);
+if (unresolved.length) { console.log(`UNRESOLVED upstream paths:`); unresolved.forEach(u => console.log('  ✗ ' + u)); }
+else console.log('all upstream paths resolve ✓');
+process.exitCode = (missing.length || unresolved.length) ? 1 : 0;

package/scripts/hooks.mjs

@@ -0,0 +1,152 @@
+// nq hooks install — drift hooks that keep an app on the canonical stack.
+//
+//   git pre-commit   → `nq align --fail-on=settlement,styling`  (blocks a commit that
+//                       introduces the broken light-client path or off-brand styling)
+//   SessionStart     → `nq align --quiet` advisory drift banner (one line)
+//   weekly GH Action → `nq align --all` → PR safe fixes / file a rolling drift issue,
+//                       reusing the existing nq audit weekly machinery.
+//
+// `nq hooks install [target]` writes the git pre-commit hook into the target repo (cwd
+// by default) and prints the SessionStart + workflow snippets (with --write to drop the
+// workflow file too). Artifacts also live under hooks/ in this repo for copy/paste.
+import { mkdir, writeFile, chmod, readFile, copyFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '..');
+
+export const PRE_COMMIT = `#!/usr/bin/env bash
+# nq align pre-commit gate — installed by \`nq hooks install\`.
+# Blocks a commit that introduces the broken @nimiq/core light-client path
+# (Client.create / @nimiq/core/web / waitForConsensusEstablished) or off-brand styling.
+set -euo pipefail
+if command -v nq >/dev/null 2>&1; then
+  nq align --fail-on=settlement,styling
+else
+  npx -y github:Andjroo111/nimiq-branding-cli align --fail-on=settlement,styling
+fi
+`;
+
+export const SESSION_START = `# nq align — SessionStart advisory drift banner.
+# Add to .claude/settings.json hooks.SessionStart, or run at the top of a session.
+nq align --quiet 2>/dev/null || true
+`;
+
+export const WEEKLY_WORKFLOW = `name: stack-align
+
+# Weekly fleet stack-alignment audit — the sibling of branding-audit.yml. Runs
+# \`nq align --all\` across the repo, PRs safe manifest fixes (nq align --fix), and
+# files/updates a rolling stack-drift issue on any risky-fail (the broken light-client
+# path, off-brand styling). Reuses the same verdict-driven shape as audit.yml.
+on:
+  schedule:
+    - cron: '30 9 * * 1' # Mondays 09:30 UTC (after branding-audit at 09:00)
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: stack-align
+  cancel-in-progress: false
+
+jobs:
+  align:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Run nq align
+        id: align
+        run: |
+          npx -y github:Andjroo111/nimiq-branding-cli align --all . --json > align.json || true
+          node -e "const r=require('./align.json').results.filter(x=>!x.exempt); const bad=r.filter(x=>x.overall==='risky-fail'); const drift=r.filter(x=>x.overall==='safe-drift'); console.log('risky='+bad.length); console.log('drift='+drift.length); process.stdout.write('');"
+          risky=\$(node -e "console.log(require('./align.json').results.filter(x=>!x.exempt&&x.overall==='risky-fail').length)")
+          drift=\$(node -e "console.log(require('./align.json').results.filter(x=>!x.exempt&&x.overall==='safe-drift').length)")
+          echo "risky=\$risky" >> "\$GITHUB_OUTPUT"
+          echo "drift=\$drift" >> "\$GITHUB_OUTPUT"
+
+      # ---- SAFE: only manifest drift → autofix the manifests + open a PR ----
+      - name: PR safe manifest fixes
+        if: steps.align.outputs.risky == '0' && steps.align.outputs.drift != '0'
+        run: |
+          npx -y github:Andjroo111/nimiq-branding-cli align --all . --fix || true
+          git config user.name  "nq-align-bot"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="align/auto-manifest-fix"
+          git checkout -B "\$branch"
+          git add -A '*nimiq-stack.json'
+          if git diff --cached --quiet; then echo "nothing to fix"; exit 0; fi
+          git commit -m "align: safe manifest fixes (nq align --fix)"
+          git push -f origin "\$branch"
+          if [ "\$(gh pr list --head "\$branch" --state open --json number --jq 'length')" = "0" ]; then
+            gh pr create --head "\$branch" --base main \\
+              --title "align: safe manifest fixes" \\
+              --body "Automated \\\`nq align --fix\\\` — manifest-only, no source changes."
+          fi
+
+      # ---- RISKY: a load-bearing axis failed (light client / off-brand) → rolling issue ----
+      - name: Open/update stack-drift issue
+        if: steps.align.outputs.risky != '0'
+        run: |
+          gh label create stack-drift --color B91C1C \\
+            --description "an app drifted off the canonical Nimiq fleet stack" 2>/dev/null || true
+          body="$(npx -y github:Andjroo111/nimiq-branding-cli align --all . 2>&1 || true)"
+          existing=\$(gh issue list --state open --label stack-drift --json number --jq '.[0].number')
+          if [ -n "\$existing" ]; then
+            printf '%s\\n' "\$body" | gh issue comment "\$existing" --body-file -
+          else
+            printf '%s\\n' "\$body" | gh issue create --title "⚙️ Nimiq stack drift needs review" \\
+              --label stack-drift --body-file -
+          fi
+`;
+
+export async function installHooks(target, opts = {}) {
+  const repo = resolve(target ?? '.');
+  const out = { wrote: [], printed: [] };
+
+  // 1) git pre-commit
+  const gitDir = join(repo, '.git');
+  if (existsSync(gitDir)) {
+    const hookDir = join(gitDir, 'hooks');
+    await mkdir(hookDir, { recursive: true });
+    const hookPath = join(hookDir, 'pre-commit');
+    await writeFile(hookPath, PRE_COMMIT);
+    await chmod(hookPath, 0o755);
+    out.wrote.push(hookPath);
+  } else {
+    out.printed.push(`(no .git in ${repo} — skipped pre-commit; init git then re-run)`);
+  }
+
+  // 2) weekly workflow (write only with --write)
+  if (opts.write) {
+    const wfDir = join(repo, '.github', 'workflows');
+    await mkdir(wfDir, { recursive: true });
+    const wfPath = join(wfDir, 'stack-align.yml');
+    await writeFile(wfPath, WEEKLY_WORKFLOW);
+    out.wrote.push(wfPath);
+  }
+
+  return out;
+}
+
+// write the committed artifacts under hooks/ in THIS repo (used by build/CI, not the app)
+export async function emitArtifacts() {
+  const dir = join(ROOT, 'hooks');
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'pre-commit'), PRE_COMMIT);
+  await chmod(join(dir, 'pre-commit'), 0o755);
+  await writeFile(join(dir, 'session-start.sh'), SESSION_START);
+  await writeFile(join(dir, 'stack-align.yml'), WEEKLY_WORKFLOW);
+  return dir;
+}