@wenathlan/argan 2.0.94 → 2.0.118

package/README.md

@@ -14,3 +14,23 @@ Argan is the DNS and gateway library of the DevThink family: authoritative zones
 pnpm install
 pnpm dev
 ```
+
+---
+
+# The family contract (wave 6-a)
+
+- `family.ts` — the single table of the eight siblings beside argan with the
+  spec §12 accent of each one; the shell rail foot, the landing footer and
+  `tests/family.test.ts` all consume this one table.
+- `familyurl.ts` — the verbatim relative-url contract (`"../" + slug + "/"`)
+  that keeps every cross-app link mount-proof.
+- `restore:entry` — the entry-face guard: a no-op while `index.html` rides the
+  canonical source face (the `./App.tsx` script plus the font triad link), a
+  restore from HEAD otherwise, and a refusal (exit 1, nothing touched) while
+  HEAD itself is not the canonical face. Run it after any local `vite build` —
+  the build rewrites the entry to the hashed face by design. Until the
+  source-face fix lands in a commit, HEAD carries the stale pre-triad face, so
+  the guard refuses instead of restoring an older face over the fix.
+- The root build emits hashed bundles into the app folder (publish contract
+  `.`); `.gitignore` bars every hashed emit (`index-*`, `favicon-*`,
+  `manifest-*`, `icon-*`), so the tree keeps the source faces only.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@wenathlan/argan",
-  "version": "2.0.94",
+  "version": "2.0.118",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"
   },
-  "description": "argan is the DNS and gateway library of the wenathlan family: zones, records, dnssec and handshake — the system network library whose site shares the unified database. The envelope distributes the documentation set, the zero-build site and the tests directory as one package.",
+  "description": "argan is the DNS and gateway library of the wenathlan family: zones, records, dnssec and handshake \u2014 the system network library whose site shares the unified database. The envelope distributes the documentation set, the zero-build site and the tests directory as one package.",
   "keywords": [
     "argan",
     "dns",
@@ -17,6 +17,24 @@
     "static-site"
   ],
   "license": "GPL-3.0-only",
+  "engines": {
+    "bare": "^1.18.0",
+    "bun": "^1.4.2",
+    "chrome": "^16.0.912",
+    "cnpm": "^9.4.0",
+    "corepack": "^0.35.0",
+    "deno": "^2.9.5",
+    "ecmascript": "^5.0.0",
+    "firefox": ">=0.8.0",
+    "iojs": "^1.0.0",
+    "node": "^26.8.2",
+    "npm": "^12.1.0",
+    "pnpm": "^12.6.0",
+    "teleport": ">=0.2.0",
+    "typescript": "^5.8.0",
+    "vscode": "^1.118.0",
+    "yarn": "^4.17.1"
+  },
   "files": [
     "README.md",
     "docs",
@@ -38,7 +56,9 @@
     "start": "vite preview --host",
     "preview": "vite preview --host",
     "check": "tsc --noEmit",
-    "test": "vitest run"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const script=/script[^>]*App\\.tsx/;const triad=/family=Inter[\\s\\S]*Geist\\+Mono/;const face=(h)=>script.test(h)&&triad.test(h);if(face(readFileSync('index.html','utf8'))){console.log('index.html already rides the source face');process.exit(0)}if(!face(execSync('git show HEAD:./index.html',{encoding:'utf8'}))){console.error('refusing: HEAD index.html is not the canonical source face yet (script App.tsx + the font triad) - land the source-face fix first; nothing was touched');process.exit(1)}execSync('git checkout -- index.html',{stdio:'inherit'});console.log('index.html restored from HEAD (the source face)')\""
   },
   "dependencies": {
     "@hono/node-server": "^2.1.3",
@@ -54,6 +74,7 @@
     "@capacitor/cli": "^8.5.2",
     "@capacitor/core": "^8.5.2",
     "@capacitor/ios": "^8.5.2",
+    "@fluentui/react-icons": "^2.0.344",
     "@hookform/resolvers": "^5.9.1",
     "@libsql/client": "^0.18.0",
     "@opencode-ai/sdk": "^1.18.34",

package/tests/design.test.ts

@@ -0,0 +1,130 @@
+// # design.test — the design contract of the argan surface, runnable with the
+// vitest runner:
+//   pnpm test
+// The file reads the shipped sources (stylesheet, entry face, brand mark,
+// app identity, route anchor) and pins the family laws: no banned hue, no
+// pill, no all-properties transition, no zero-scale entry (the windows
+// dtPopIntro bounce excepted), the trylle font stacks, the source-face entry,
+// the reduced-motion stop, tabular numerals, the sticky-footer law, the honest
+// page set of the application identity and the first-run flow contract (the
+// entry gate, the shared onboarding state, the db mirror).
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+function read(path: string): string {
+  return readFileSync(new URL(path, import.meta.url), "utf8");
+}
+
+const CSS = read("../Sol/sol.css");
+const ENTRY = read("../index.html");
+const MARK = read("../Sol/shell/Shell.tsx");
+const TOML = read("../devthink.toml");
+const SOL = read("../Sol/Sol.tsx");
+const FAVICON = read("../favicon.svg");
+const ICON = read("../icon.svg");
+const MANIFEST = read("../manifest.webmanifest");
+
+const BANNED = [/3b82f6/i, /2563eb/i, /f97316/i];
+
+describe("design contract", () => {
+  it("ships no banned hue in the stylesheet, the entry, the mark or the icons", () => {
+    for (const source of [CSS, ENTRY, MARK, FAVICON, ICON, MANIFEST]) {
+      for (const banned of BANNED) {
+        expect(banned.test(source), `banned hue ${banned} found`).toBe(false);
+      }
+    }
+  });
+
+  it("carries the argan jade #34d8a8 as the one signal (mark story #14b98c)", () => {
+    expect(CSS).toMatch(/--sol-primary: #34d8a8/);
+    expect(CSS).toMatch(/--arg-jade: #34d8a8/);
+    expect(MARK).toMatch(/#14b98c/);
+  });
+
+  it("keeps the pill out of the stylesheet (no 999px, no stadium radius)", () => {
+    expect(CSS.includes("999px"), "the pill radius is retired").toBe(false);
+    expect(CSS.includes("--r-pill"), "no pill token survives").toBe(false);
+  });
+
+  it("never ships an all-properties transition", () => {
+    expect(/transition:\s*all/.test(CSS), "transition: all is a reprovação").toBe(false);
+  });
+
+  it("never enters an element from zero scale (the windows dtPopIntro bounce excepted)", () => {
+    const sansPopIntro = CSS.replace(/@keyframes dtPopIntro \{[\s\S]*?\n\}/g, "");
+    expect(
+      /scale\(0\)/.test(sansPopIntro),
+      "scale(0) entries are a reprovação (the dtPopIntro bounce of the windows recipe excepted)",
+    ).toBe(false);
+  });
+
+  it("declares the trylle font stacks (Inter reading, Geist Mono detail)", () => {
+    expect(CSS).toMatch(/--font-sans: "Inter Variable"/);
+    expect(CSS).toMatch(/--font-mono: "Geist Mono Variable"/);
+    expect(ENTRY).toMatch(/family=Inter/);
+    expect(ENTRY).toMatch(/Geist\+Mono/);
+  });
+
+  it("keeps the entry on the source face (./App.tsx, canonical assets, no hashed ghosts)", () => {
+    expect(ENTRY).toMatch(/script[^>]*\.\/App\.tsx/);
+    expect(/-[0-9a-f]{8}\.(js|css)/.test(ENTRY), "no hashed bundle rides the entry").toBe(false);
+    expect(ENTRY).toMatch(/href="\.\/favicon\.svg"/);
+    expect(ENTRY).toMatch(/href="\.\/manifest\.webmanifest"/);
+  });
+
+  it("guards the reduced-motion stop on every layer", () => {
+    const blocks = CSS.match(/@media \(prefers-reduced-motion: reduce\)/g) ?? [];
+    expect(blocks.length >= 4, `expected the hard stop on every layer, found ${blocks.length}`).toBe(true);
+  });
+
+  it("keeps tabular numerals on the platform numbers", () => {
+    expect(CSS).toMatch(/font-variant-numeric:\s*tabular-nums/);
+  });
+
+  it("rests the title-bar mark on the landing (logo discipline)", () => {
+    expect(CSS).toMatch(/data-landing/);
+    expect(MARK).toMatch(/data-landing/);
+  });
+
+  it("pins the footer to the window floor (the sticky-footer law)", () => {
+    expect(CSS).toMatch(/\.winapp__stage > main\.shell \{[^}]*flex-direction: column/);
+    expect(CSS).toMatch(/\.r3a-foot \{[^}]*margin-top: auto/);
+  });
+
+  it("declares the honest page set (home, zones, dnssec, gateway, settings, notfound)", () => {
+    expect(TOML).toMatch(/pages = \["home", "zones", "dnssec", "gateway", "settings", "notfound"\]/);
+    for (const route of ['"/zones"', '"/dnssec"', '"/gateway"', '"/settings"', '"/404"']) {
+      expect(SOL.includes(`path=${route}`), `route ${route} must mount`).toBe(true);
+    }
+  });
+
+  it("keeps the entry flow mounted (intro, onboarding) before the fundamentals", () => {
+    expect(SOL).toMatch(/path="\/intro"/);
+    expect(SOL).toMatch(/path="\/onboarding"/);
+    expect(SOL.indexOf('"/intro"')).toBeLessThan(SOL.indexOf('"/"'));
+  });
+
+  it("carries the flow contract sources (the entry gate behind the home anchor, the shared state module)", () => {
+    const GATE = read("../Sol/home/entrygate.tsx");
+    const STATE = read("../onboardingstate.ts");
+    const HOME = read("../Sol/home/home.tsx");
+    const ONBOARDING = read("../Sol/onboarding/onboarding.tsx");
+    expect(GATE).toMatch(/navigate\("\/intro"/);
+    expect(GATE).toMatch(/navigate\("\/onboarding"/);
+    expect(HOME).toMatch(/EntryGate/);
+    expect(ONBOARDING).toMatch(/markOnboardingSeen/);
+    expect(STATE).toMatch(/argan\.onboarding\.seen/);
+    expect(STATE).toMatch(/\/api\/v1\/onboarding/);
+  });
+
+  it("catalogues the first-run state in the db layer (prisma model + sqlite mirror)", () => {
+    const PRISMA = read("../schema.prisma");
+    const DB = read("../db.ts");
+    expect(PRISMA).toMatch(/model OnboardingState \{/);
+    expect(PRISMA).toMatch(/introseen\s+Boolean\s+@default\(false\)/);
+    expect(PRISMA).toMatch(/onboardingseen\s+Boolean\s+@default\(false\)/);
+    expect(DB).toMatch(/CREATE TABLE IF NOT EXISTS onboarding_state/);
+    expect(DB).toMatch(/getonboardingstate/);
+    expect(DB).toMatch(/setonboardingstage/);
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,89 @@
+// # family.test — the family table the chrome rides, runnable with the
+// vitest runner:
+//   pnpm test
+// Every test watches the promise the row makes: the eight siblings beside
+// argan are listed once, every slug resolves through the familyurl contract
+// into a climb-one-level url, every member carries the spec §12 accent with
+// its own dot ink, and no accent ever collides with the banned palette.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the eight siblings beside argan, never argan itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, [
+      "cadria",
+      "debonair",
+      "forge",
+      "foundry",
+      "getry",
+      "saddle",
+      "stealthhead",
+      "vault",
+    ]);
+    assert.ok(!FAMILY_SLUGS.includes("argan"));
+    assert.ok(!FAMILY_SLUGS.includes("devthink"));
+  });
+
+  it("answers an accent for every listed sibling", () => {
+    for (const slug of FAMILY_SLUGS) {
+      const member = FAMILY_ACCENTS[slug];
+      assert.ok(member, `${slug} must carry an accent`);
+      assert.equal(member.slug, slug);
+      assert.match(member.accent, /^#[0-9a-f]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-f]{6}$/);
+    }
+    // the table holds exactly the siblings — no orphan accents
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [...FAMILY_SLUGS].sort());
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("strips decorative slashes and normalizes the slug", () => {
+    assert.equal(familyurl("/cadria/"), "../cadria/");
+    assert.equal(familyurl("  getry  "), "../  getry  /");
+  });
+
+  it("keeps the spec §12 accents stable", () => {
+    assert.equal(FAMILY_ACCENTS.cadria.accent, "#f472b6");
+    assert.equal(FAMILY_ACCENTS.debonair.accent, "#d9962e");
+    assert.equal(FAMILY_ACCENTS.forge.accent, "#a2cb3a");
+    assert.equal(FAMILY_ACCENTS.foundry.accent, "#2fb8b5");
+    assert.equal(FAMILY_ACCENTS.getry.accent, "#8b5cf6");
+    assert.equal(FAMILY_ACCENTS.saddle.accent, "#e86f2d");
+    assert.equal(FAMILY_ACCENTS.stealthhead.accent, "#e8563f");
+    assert.equal(FAMILY_ACCENTS.vault.accent, "#a3d7e6");
+  });
+
+  it("never ships a banned hue in the row", () => {
+    for (const member of familyrow()) {
+      assert.ok(!BANNED.has(member.accent), `${member.slug} rides a banned accent`);
+    }
+  });
+
+  it("builds the rail row in slug order without gaps", () => {
+    const row = familyrow();
+    assert.equal(row.length, FAMILY_SLUGS.length);
+    assert.deepEqual(
+      row.map((member) => member.slug),
+      [...FAMILY_SLUGS],
+    );
+  });
+
+  it("keeps every dot ink readable on its own accent (the ink is darker)", () => {
+    for (const member of familyrow()) {
+      const lum = (hex: string): number => {
+        const channel = (offset: number) => Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+        return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+      };
+      assert.ok(lum(member.dotInk) < lum(member.accent), `${member.slug} dot ink must be darker than its accent`);
+    }
+  });
+});