@helical-design/substrate 0.1.0

package/src/scaffold.mjs

@@ -0,0 +1,200 @@
+// src/scaffold.mjs — create-helical core. A pure, offline, deterministic
+// project stamper. Layered model: _base skeleton → profile overlay → (app only)
+// a DB overlay assembled from the Spec D templates under templates/db/<provider>.
+//
+// Atomicity: everything is stamped into a staging temp dir first, then moved into
+// the target in one shot. On ANY error the staging dir AND every entry written
+// into the target are removed, so a failed scaffold never leaves a half-project.
+import {
+  readFileSync, writeFileSync, mkdtempSync, mkdirSync, rmSync, cpSync,
+  readdirSync, existsSync, renameSync, statSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(HERE, '..');
+
+const PROFILES = new Set(['marketing', 'app']);
+const DBS = new Set(['neon', 'supabase']);
+// npm package name: lowercase, no spaces/uppercase/illegal chars. Scoped names
+// are allowed; this is the practical kebab-ish subset the scaffolder accepts.
+const NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+function readOwnPackage() {
+  return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+}
+
+// Pick a dependency's exact declared range from the substrate's own package.json
+// (dependencies or devDependencies), so a stamped app stays in lockstep with us.
+function ownRange(pkg, dep) {
+  const range = pkg.dependencies?.[dep] ?? pkg.devDependencies?.[dep];
+  if (!range) throw new Error(`scaffold: substrate package.json is missing a range for '${dep}'`);
+  return range;
+}
+
+// Recursively copy `src` into `dest`, skipping `.keep` overlay markers.
+function copyTree(src, dest) {
+  if (!existsSync(src)) throw new Error(`scaffold: template source missing: ${src}`);
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    if (entry === '.keep') continue;
+    const s = join(src, entry);
+    const d = join(dest, entry);
+    if (statSync(s).isDirectory()) copyTree(s, d);
+    else cpSync(s, d);
+  }
+}
+
+function copyFile(src, dest) {
+  if (!existsSync(src)) throw new Error(`scaffold: template source missing: ${src}`);
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest);
+}
+
+function dirIsEmpty(dir) {
+  return !existsSync(dir) || readdirSync(dir).length === 0;
+}
+
+export function scaffold({
+  name, dir, profile = 'marketing', db, force = false, __templatesRoot,
+} = {}) {
+  // --- validation (fail loud, before touching the filesystem) ---------------
+  if (!name || !NAME_RE.test(name)) {
+    throw new Error(`scaffold: invalid project name: ${JSON.stringify(name)} — use a valid npm package name (lowercase, no spaces)`);
+  }
+  if (!PROFILES.has(profile)) {
+    throw new Error(`scaffold: unknown profile: ${JSON.stringify(profile)} — expected 'marketing' or 'app'`);
+  }
+  if (db !== undefined) {
+    if (profile !== 'app') {
+      throw new Error(`scaffold: db is only meaningful for the app profile (got profile '${profile}')`);
+    }
+    if (!DBS.has(db)) {
+      throw new Error(`scaffold: unknown db: ${JSON.stringify(db)} — expected 'neon' or 'supabase'`);
+    }
+  }
+  const provider = profile === 'app' ? (db ?? 'neon') : null;
+
+  if (!dir) throw new Error('scaffold: a target dir is required');
+  if (!force && !dirIsEmpty(dir)) {
+    throw new Error(`scaffold: target dir is not empty: ${dir} — pass force to overwrite`);
+  }
+
+  const templatesRoot = __templatesRoot ?? join(PKG_ROOT, 'templates');
+  const ownPkg = readOwnPackage();
+  const version = ownPkg.version;
+
+  // --- stage everything into a temp dir, then move atomically ---------------
+  const staging = mkdtempSync(join(tmpdir(), 'helical-stage-'));
+  // Track what we move into the target so rollback can undo a partial move.
+  const moved = [];
+  try {
+    stampInto(staging, { name, profile, provider, version, templatesRoot, ownPkg });
+
+    mkdirSync(dir, { recursive: true });
+    for (const entry of readdirSync(staging)) {
+      const from = join(staging, entry);
+      const to = join(dir, entry);
+      rmSync(to, { recursive: true, force: true });
+      try {
+        renameSync(from, to);
+      } catch (err) {
+        // Cross-filesystem move (tmp and target on different mounts) — rename
+        // can't span devices, so copy-then-remove. Common on CI.
+        if (err.code !== 'EXDEV') throw err;
+        cpSync(from, to, { recursive: true });
+        rmSync(from, { recursive: true, force: true });
+      }
+      moved.push(to); // track the target regardless of which move path was taken
+    }
+  } catch (err) {
+    // Roll back any entries already moved into the target, plus staging.
+    for (const p of moved) rmSync(p, { recursive: true, force: true });
+    rmSync(staging, { recursive: true, force: true });
+    throw err;
+  }
+  rmSync(staging, { recursive: true, force: true });
+  return dir;
+}
+
+// Stamp the full layered project into an (empty) staging dir.
+function stampInto(out, { name, profile, provider, version, templatesRoot, ownPkg }) {
+  const profilesRoot = join(templatesRoot, 'profiles');
+  const dbRoot = join(templatesRoot, 'db');
+
+  // 1. _base skeleton (tokens / content / templates / pages.json / .gitignore / README).
+  copyTree(join(profilesRoot, '_base'), out);
+
+  // 2. profile overlay (static profile-specific files, if any).
+  copyTree(join(profilesRoot, profile), out);
+
+  // 3. rendered, version-aware files.
+  const pkg = {
+    name,
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    scripts: {
+      build: "node -e \"import('@helical/substrate').then(m => m.build())\"",
+    },
+    dependencies: { '@helical/substrate': `^${version}` },
+  };
+  // app projects import the DB drivers from their OWN node_modules (the stamped
+  // db/*.mjs + drizzle.config.mjs load them), so they must declare them — pinned
+  // to the exact ranges the substrate declares so the two stay in lockstep.
+  if (profile === 'app') {
+    pkg.dependencies['drizzle-orm'] = ownRange(ownPkg, 'drizzle-orm');
+    if (provider === 'supabase') {
+      pkg.dependencies['postgres'] = ownRange(ownPkg, 'postgres');
+    } else {
+      pkg.dependencies['@neondatabase/serverless'] = ownRange(ownPkg, '@neondatabase/serverless');
+    }
+    pkg.devDependencies = { 'drizzle-kit': ownRange(ownPkg, 'drizzle-kit') };
+  }
+  writeFileSync(join(out, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+  writeFileSync(join(out, 'helical.config.mjs'), renderConfig({ profile, provider, version }));
+
+  // README name substitution (keeps the skeleton template generic).
+  const readmePath = join(out, 'README.md');
+  if (existsSync(readmePath)) {
+    writeFileSync(readmePath, readFileSync(readmePath, 'utf8').replaceAll('{{name}}', name));
+  }
+
+  // 4. app-only DB overlay, assembled from the Spec D templates + src/db.
+  if (profile === 'app') stampDb(out, { provider, dbRoot });
+}
+
+function renderConfig({ profile, provider, version }) {
+  const lines = [
+    '// helical.config.mjs — generated by create-helical. Pins the substrate',
+    '// version this project was scaffolded against.',
+    'export default {',
+    `  profile: '${profile}',`,
+  ];
+  if (provider) lines.push(`  db: '${provider}',`);
+  lines.push(`  substrateVersion: '${version}',`, '};', '');
+  return lines.join('\n');
+}
+
+// Assemble the app's db/ from the shared Spec D templates — never duplicated here.
+//   db/schema.mjs, db/vector.mjs  ← src/db/ (the ONE shared schema + query)
+//   db/client.mjs                 ← templates/db/<provider>/client.mjs
+//   drizzle.config.mjs            ← templates/db/_shared/drizzle.config.mjs
+//   .env.example                  ← templates/db/<provider>/env.example
+//   supabase/{config.toml,migrations/}  ← templates/db/supabase/ (supabase only)
+function stampDb(out, { provider, dbRoot }) {
+  const srcDb = join(PKG_ROOT, 'src', 'db');
+  copyFile(join(srcDb, 'schema.mjs'), join(out, 'db', 'schema.mjs'));
+  copyFile(join(srcDb, 'vector.mjs'), join(out, 'db', 'vector.mjs'));
+
+  copyFile(join(dbRoot, provider, 'client.mjs'), join(out, 'db', 'client.mjs'));
+  copyFile(join(dbRoot, '_shared', 'drizzle.config.mjs'), join(out, 'drizzle.config.mjs'));
+  copyFile(join(dbRoot, provider, 'env.example'), join(out, '.env.example'));
+
+  if (provider === 'supabase') {
+    copyFile(join(dbRoot, 'supabase', 'config.toml'), join(out, 'supabase', 'config.toml'));
+    copyTree(join(dbRoot, 'supabase', 'migrations'), join(out, 'supabase', 'migrations'));
+  }
+}

package/src/scale.mjs

@@ -0,0 +1,268 @@
+// src/scale.mjs — Size is as generative as color. One config-driven scale
+// generator turns a profile (plain data) into space / size / radius / leading /
+// tracking ladders + an a11y target, emitted as DTCG JSON for Style Dictionary —
+// the size-side mirror of src/palette.mjs.
+//
+// Algorithm (the genuine core): a constructive monotonic grid scale. Each ladder
+// is built ascending from its smallest step:
+//
+//   step[n] = max( step[n-1] + gridUnit,  snapToGrid( base · ratio^n ) )
+//
+// The grid floor IS the damping — where geometric steps fall closer than one grid
+// unit (the small end) the +gridUnit term dominates and the bottom goes linear on
+// the grid automatically (space: 4,8,12,16). A duplicate is unrepresentable, so
+// the ladder is strictly increasing by construction. Density (compact ×0.85) is
+// applied INSIDE the build to the geometric ideal, then the same constructive
+// build re-runs — never multiply-the-output-then-resnap (that collides).
+//
+// The grid is 4px-aligned throughout (every space/radius/target value is a
+// multiple of 4 — the "common denominator"); the snap granularity itself grows
+// with magnitude (4 → 8 → 16) so the grid stays the floor at every scale instead
+// of fracturing large steps. Type snaps to whole px (unit stays rem upstream).
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SPACE_STEPS = 8;       // space.1..8
+const COMPACT_MULT = 0.85;   // density multiplier (applied inside the build)
+const SPACIOUS_MULT = 1.15;  // airier density (v2) — same constructive build, larger ideal
+const TYPE_FLOOR = 12;       // a11y: smallest type role never below 12px (every density)
+const COMPACT_BODY_FLOOR = 14; // a11y SHOULD: compact body never below 14px
+const BODY_FLOOR = 16;       // comfy/spacious body floor (px) — iOS form-field zoom guard
+// (compact uses the existing COMPACT_BODY_FLOOR = 14 at every endpoint)
+// Leading couples to density (v2): body leading tightens compact / loosens spacious by
+// this much, floored for legibility. Heading (`tight`) leading stays density-stable.
+const LEADING_DENSITY_DELTA = 0.1;
+const LEADING_FLOOR = 1.4;
+
+// --- profiles: plain data only (no functions, no per-profile branching) ------
+// `ui` is the built/committed default; `editorial` is the alternate. In v1 they
+// differ ONLY by these data rows — every code path is shared.
+export const PROFILES = {
+  ui: {
+    name: 'ui',
+    typeBase: 16,     // body size in px (16px === 1rem)
+    typeRatio: 1.5,   // perfect fifth → h3/h2/h1 = 24/36/54
+    spaceBase: 4,     // smallest space step in px
+    spaceRatio: 1.5,
+    leading: { body: 1.6, tight: 1.2 },
+    // Size-coupled tracking curve (em): track(px) = clamp(min, max, intercept + slope·px),
+    // applied per heading. ui is flat (slope 0) → −0.01em on every heading, unchanged.
+    tracking: { slope: 0, intercept: -0.01, min: -0.01, max: -0.01 },
+    viewport:       { min: 480, max: 1280 },
+    fluidMagnitude: { min: 0.8, max: 1.0 },
+    breakpoints:    { sm: 480, md: 768, lg: 1024, xl: 1280 },
+    container:      { sm: 480, md: 720, lg: 960, xl: 1200 },
+  },
+  editorial: {
+    name: 'editorial',
+    typeBase: 16,
+    typeRatio: 1.618, // golden ratio → larger, more dramatic display headings
+    spaceBase: 4,
+    spaceRatio: 1.5,
+    leading: { body: 1.7, tight: 1.15 },
+    // Optical: bigger display type tracks tighter. ~0 near body, clamps at −0.05em for h1.
+    tracking: { slope: -0.0018, intercept: 0.0288, min: -0.05, max: 0.01 },
+    viewport:       { min: 480, max: 1280 },
+    fluidMagnitude: { min: 0.8, max: 1.0 },
+    breakpoints:    { sm: 480, md: 768, lg: 1024, xl: 1280 },
+    container:      { sm: 480, md: 720, lg: 960, xl: 1200 },
+  },
+};
+
+// --- grid primitives ---------------------------------------------------------
+
+// Snap a value to a 4px-aligned grid whose granularity grows with magnitude so
+// the grid remains the construction floor at every scale: 4 below ~16, 8 below
+// ~32, 16 above. Every result is a multiple of 4.
+function snapToGrid(x) {
+  const unit = x <= 16 ? 4 : x <= 32 ? 8 : 16;
+  return Math.round(x / unit) * unit;
+}
+
+// One constructive ladder. `snap` maps the geometric ideal onto the grid (4px
+// for space, 1px for type); `floor` is the per-step grid increment that damps the
+// small end (4 for space, 1 for type). `mult` is the density multiplier applied
+// to the geometric ideal BEFORE snapping (monotonic-safe by re-running the build).
+function gridScale(base, ratio, count, { snap, floor, mult = 1 }) {
+  const out = [];
+  for (let n = 0; n < count; n++) {
+    const ideal = snap(base * ratio ** n * mult);
+    out.push(n === 0 ? Math.max(floor, ideal) : Math.max(out[n - 1] + floor, ideal));
+  }
+  return out;
+}
+
+// Constructive descent for the sub-body type roles (small, caption). Built from
+// the bottom up so a 12px floor damps the descent exactly as the grid floor damps
+// the ascent — strictly increasing toward body by construction.
+function descendType(base, ratio, mult) {
+  const caption = Math.max(TYPE_FLOOR, Math.round((base / ratio ** 2) * mult));
+  const small = Math.max(caption + 1, Math.round((base / ratio) * mult));
+  return { caption, small };
+}
+
+const clamp = (lo, hi, x) => Math.min(hi, Math.max(lo, x));
+const round4 = (x) => Math.round(x * 1e4) / 1e4; // em precision, no float tails
+
+// --- buildScale: pure, no IO -------------------------------------------------
+
+export function buildScale(config) {
+  const { typeBase, typeRatio, spaceBase, spaceRatio, leading, tracking } = config;
+  if (typeRatio <= 1 || typeRatio >= 2) {
+    throw new Error(`scale: typeRatio must be in (1, 2), got ${typeRatio}`);
+  }
+
+  const space = (mult) =>
+    gridScale(spaceBase, spaceRatio, SPACE_STEPS, { snap: snapToGrid, floor: 4, mult });
+
+  // Type: ascend headings geometrically (whole px), descend sub-body with a 12px
+  // floor. `bodyFloor` lifts the compact body to ≥14px (and re-floors caption/small
+  // off the lifted body) so density never pushes prose below legibility.
+  const size = (mult, bodyFloor = 0) => {
+    const bodyIdeal = Math.round(typeBase * mult);     // unfloored, magnitude-scaled
+    const body = Math.max(bodyFloor, bodyIdeal);       // reading floor (per-density)
+    const { caption, small } = descendType(body, typeRatio, 1); // sub-body from floored body
+    return {
+      caption,
+      small,
+      body,
+      h3: Math.round(bodyIdeal * typeRatio),           // headings from the IDEAL
+      h2: Math.round(bodyIdeal * typeRatio ** 2),
+      h1: Math.round(bodyIdeal * typeRatio ** 3),
+    };
+  };
+
+  // Radius: its own small geometric series on 4px — 0, then 4·2^n → 0,4,8,16,
+  // plus the pill sentinel. Density-stable (generated once).
+  const radius = { none: 0, sm: 4, md: 8, lg: 16, pill: 999 };
+
+  // Body leading coupled to density (v2), floored for legibility. round2 keeps the
+  // value clean (1.6 − 0.1 = 1.4999998 in float → 1.5).
+  const round2 = (x) => Math.round(x * 100) / 100;
+  const leadBody = (delta) => Math.max(LEADING_FLOOR, round2(leading.body + delta));
+
+  // Size-coupled tracking (em), per heading, from the comfy heading sizes. One curve;
+  // ui's data is flat, editorial's is sloped → tighter as type grows. Density-stable.
+  const comfySize = size(1, BODY_FLOOR);
+  const track = (px) => round4(clamp(tracking.min, tracking.max, tracking.intercept + tracking.slope * px));
+  const tracks = {
+    h1: track(comfySize.h1),
+    h2: track(comfySize.h2),
+    h3: track(comfySize.h3),
+  };
+
+  const comfy = {
+    space: space(1),
+    size: comfySize,
+    radius,
+    leading: { body: leading.body, tight: leading.tight },
+    tracking: tracks,
+    target: { min: 24 }, // a11y SC 2.5.8 — 24px (1.5rem), density-stable
+  };
+
+  // The density blocks carry ONLY the density-responsive groups: space + size +
+  // body leading (v2). radius/tracking/target stay density-stable (:root only).
+  // Each multiplier is applied inside the build, never to the comfy output.
+  const compact = {
+    space: space(COMPACT_MULT),
+    size: size(COMPACT_MULT, COMPACT_BODY_FLOOR),
+    leading: { body: leadBody(-LEADING_DENSITY_DELTA) },
+  };
+  const spacious = {
+    space: space(SPACIOUS_MULT),
+    size: size(SPACIOUS_MULT, BODY_FLOOR),
+    leading: { body: leadBody(LEADING_DENSITY_DELTA) },
+  };
+
+  const magMin = config.fluidMagnitude.min;
+  const fluidMin = {
+    comfy:    { space: space(1 * magMin),             size: size(1 * magMin, BODY_FLOOR) },
+    compact:  { space: space(COMPACT_MULT * magMin),  size: size(COMPACT_MULT * magMin, COMPACT_BODY_FLOOR) },
+    spacious: { space: space(SPACIOUS_MULT * magMin), size: size(SPACIOUS_MULT * magMin, BODY_FLOOR) },
+  };
+  return { comfy, compact, spacious, fluidMin };
+}
+
+// --- generateScale: mirrors generatePalette (calls buildScale, writes DTCG) ---
+
+// Fixed-precision string output → deterministic, no float tails (13.6000001).
+function num(n) {
+  return Number.isInteger(n) ? String(n) : String(Math.round(n * 1e4) / 1e4);
+}
+const remOf = (px) => `${num(px / 16)}rem`; // 16px === 1rem
+const pxOf = (px) => `${num(px)}px`;
+
+// Emit one fluid dimension as a zoom-safe clamp. min/max are px endpoints; vpMin/vpMax px.
+// Zero-slope (min === max) collapses to a bare rem value so non-flexing tokens stay stable.
+export function fluidDimension(minPx, maxPx, vpMin, vpMax) {
+  if (minPx === maxPx) return remOf(minPx);
+  const slopeVw = ((maxPx - minPx) / (vpMax - vpMin)) * 100;
+  const interceptPx = minPx - (slopeVw / 100) * vpMin;
+  return `clamp(${remOf(minPx)}, calc(${remOf(interceptPx)} + ${num(slopeVw)}vw), ${remOf(maxPx)})`;
+}
+
+function spaceGroup(minArr, maxArr, vp) {
+  return Object.fromEntries(maxArr.map((maxPx, i) => [
+    String(i + 1),
+    { $value: fluidDimension(minArr[i], maxPx, vp.min, vp.max), $type: 'dimension' },
+  ]));
+}
+function sizeGroup(minSize, maxSize, vp) {
+  return Object.fromEntries(Object.keys(maxSize).map((k) => [
+    k,
+    { $value: fluidDimension(minSize[k], maxSize[k], vp.min, vp.max), $type: 'dimension' },
+  ]));
+}
+
+export function generateScale(profileName, root = '.') {
+  const config = PROFILES[profileName];
+  if (!config) throw new Error(`scale: unknown profile '${profileName}'`);
+  const { comfy, compact, spacious, fluidMin } = buildScale(config);
+  const vp = config.viewport;
+
+  // :root pass — space + size in rem; radius + target in px; leading unitless;
+  // tracking em. Top-level DTCG paths (size/space/radius/…), never nested under
+  // scale.* — the CSS var name derives from the path, and the named consumers
+  // expect --space-*, --size-*, --radius-*, --leading-*, --tracking-*.
+  const scale = {
+    space: spaceGroup(fluidMin.comfy.space, comfy.space, vp),
+    size: sizeGroup(fluidMin.comfy.size, comfy.size, vp),
+    radius: Object.fromEntries(
+      Object.entries(comfy.radius).map(([k, v]) => [k, { $value: pxOf(v), $type: 'dimension' }]),
+    ),
+    leading: {
+      body: { $value: num(comfy.leading.body), $type: 'number' },
+      tight: { $value: num(comfy.leading.tight), $type: 'number' },
+    },
+    tracking: Object.fromEntries(
+      Object.entries(comfy.tracking).map(([k, v]) => [k, { $value: `${num(v)}em`, $type: 'dimension' }]),
+    ),
+    target: {
+      min: { $value: pxOf(comfy.target.min), $type: 'dimension' },
+    },
+  };
+
+  // density passes — density-responsive groups ONLY (space + size + body leading).
+  // radius/tracking/target are omitted so they inherit from :root (density-stable).
+  const densityDtcg = (maxBlock, minBlock) => ({
+    space: spaceGroup(minBlock.space, maxBlock.space, vp),
+    size:  sizeGroup(minBlock.size,  maxBlock.size,  vp),
+    leading: { body: { $value: num(maxBlock.leading.body), $type: 'number' } },
+  });
+
+  // Breakpoints + container max-widths: mode/density-independent px dimensions, so
+  // they ride the :root/static pass exactly like radius/target (never a density block).
+  const bpDtcg = {
+    bp: Object.fromEntries(Object.entries(config.breakpoints).map(
+      ([k, v]) => [k, { $value: pxOf(v), $type: 'dimension' }])),
+    container: Object.fromEntries(Object.entries(config.container).map(
+      ([k, v]) => [k, { $value: pxOf(v), $type: 'dimension' }])),
+  };
+
+  mkdirSync(join(root, 'tokens'), { recursive: true });
+  writeFileSync(join(root, 'tokens/scale.json'), JSON.stringify(scale, null, 2) + '\n');
+  writeFileSync(join(root, 'tokens/scale.compact.json'), JSON.stringify(densityDtcg(compact, fluidMin.compact), null, 2) + '\n');
+  writeFileSync(join(root, 'tokens/scale.spacious.json'), JSON.stringify(densityDtcg(spacious, fluidMin.spacious), null, 2) + '\n');
+  writeFileSync(join(root, 'tokens/breakpoints.json'), JSON.stringify(bpDtcg, null, 2) + '\n');
+}

package/src/store.mjs

@@ -0,0 +1,38 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+import matter from 'gray-matter';
+import { marked } from 'marked';
+
+marked.setOptions({ mangle: false, headerIds: false }); // deterministic output
+
+function loadMd(file) {
+  const { data, content } = matter(readFileSync(file, 'utf8'));
+  // gray-matter parses YAML dates to Date objects; coerce to an ISO string so
+  // templates can safely render {{ ...date }} and lexicographic sort still works.
+  if (data.date instanceof Date) data.date = data.date.toISOString().slice(0, 10);
+  return { ...data, html: marked.parse(content).trim() };
+}
+
+export function loadStore(dir) {
+  const store = {};
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith('.') || name === 'README.md') continue; // skip OS cruft + docs
+    const full = join(dir, name);
+    const ext = extname(name);
+    const key = basename(name, ext);
+    if (ext === '.json') {
+      try { store[key] = JSON.parse(readFileSync(full, 'utf8')); }
+      catch (e) { throw new Error(`store: bad JSON in ${name}: ${e.message}`); }
+    } else if (ext === '.md') {
+      store[key] = loadMd(full);
+    } else if (name === 'journal') {
+      store.journal = readdirSync(full)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => ({ slug: basename(f, '.md'), ...loadMd(join(full, f)) }))
+        .sort((a, b) => new Date(b.date) - new Date(a.date));
+    } else {
+      throw new Error(`store: unexpected entry in content dir: ${name}`); // fail-loud on typos
+    }
+  }
+  return store;
+}

package/src/tokens.mjs

@@ -0,0 +1,79 @@
+// src/tokens.mjs — DTCG token sources → CSS.
+//   :root (dark)            ← base + semantic + palette.dark + accent.dark + SCALE
+//   [data-mode="light"]     ← base + semantic + palette.light + accent.light
+//   [data-density="compact"]← scale.compact (space + size only)
+//
+// Scale tokens are mode-independent → emitted in the :root pass ONLY (T3); the
+// compact block carries only the density-responsive groups and is concatenated
+// AFTER the mode blocks so its --space-*/--size-* overrides win (the ordering
+// contract). The compact block is emitted by a direct string templater (flat
+// values, no refs) so Style Dictionary owns the mode/color axis and the runtime
+// density axis stays a plain cascade override — SD never has to model a second
+// selector dimension.
+import StyleDictionary from 'style-dictionary';
+import { readFileSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+function configFor(root, mode, selector, outDir, extraSources = [], overrideDir = null) {
+  const baseNames = ['base.json', 'semantic.json', `palette.${mode}.json`, `accent.${mode}.json`];
+  const base = baseNames.map((n) => join(root, 'tokens', n));
+  // Override files (same basename) are appended AFTER base + scale so Style
+  // Dictionary's later-source-wins resolves to the consumer's value.
+  const overrides = overrideDir
+    ? baseNames.map((n) => join(overrideDir, n)).filter((p) => existsSync(p))
+    : [];
+  return {
+    usesDtcg: true,
+    source: [...base, ...extraSources, ...overrides],
+    platforms: { css: { transformGroup: 'css', buildPath: outDir.endsWith('/') ? outDir : outDir + '/',
+      files: [{ destination: `tokens.${mode}.css`, format: 'css/variables',
+                options: { selector, outputReferences: false } }] } }
+  };
+}
+
+// Flatten a scale DTCG group ({ space:{1:{$value}}, size:{body:{$value}} }) into
+// CSS custom-property declarations: --space-1, --size-body, …
+function scaleVars(scale) {
+  const decls = [];
+  for (const [group, tokens] of Object.entries(scale)) {
+    for (const [key, tok] of Object.entries(tokens)) {
+      decls.push(`  --${group}-${key}: ${tok.$value};`);
+    }
+  }
+  return decls.join('\n');
+}
+
+// One runtime density override block. Emitted by a direct string templater (flat
+// values, no refs) so Style Dictionary owns only the mode/color axis; each density
+// stays a plain cascade override layered after the mode blocks.
+function densityBlock(root, density) {
+  const path = join(root, `tokens/scale.${density}.json`);
+  if (!existsSync(path)) return '';
+  const scale = JSON.parse(readFileSync(path, 'utf8'));
+  return `[data-density="${density}"] {\n${scaleVars(scale)}\n}\n`;
+}
+
+export async function buildTokens(root = '.', outDir = join(root, 'dist'), overrideDir = null) {
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+  // Scale tokens ride the :root/dark pass only (mode-independent). Breakpoints +
+  // container widths are likewise mode/density-independent static dimensions, so
+  // they join the same static source set (→ --bp-*/--container-* at :root).
+  const scalePath = join(root, 'tokens/scale.json');
+  const bpPath = join(root, 'tokens/breakpoints.json');
+  const scaleSource = [
+    ...(existsSync(scalePath) ? [scalePath] : []),
+    ...(existsSync(bpPath) ? [bpPath] : []),
+  ];
+  for (const [mode, selector] of [['dark', ':root'], ['light', '[data-mode="light"]']]) {
+    const sd = new StyleDictionary(configFor(root, mode, selector, outDir,
+      mode === 'dark' ? scaleSource : [], overrideDir));
+    await sd.buildAllPlatforms();
+  }
+  const css = `${readFileSync(join(outDir, 'tokens.dark.css'), 'utf8')}\n`
+    + `${readFileSync(join(outDir, 'tokens.light.css'), 'utf8')}\n`
+    + densityBlock(root, 'compact')
+    + densityBlock(root, 'spacious');
+  writeFileSync(join(outDir, 'tokens.css'), css);
+  return join(outDir, 'tokens.css');
+}

package/templates/db/_shared/drizzle.config.mjs

@@ -0,0 +1,9 @@
+// drizzle.config.mjs — shared drizzle-kit config for both providers.
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './db/schema.mjs',
+  out: './drizzle',
+  dbCredentials: { url: process.env.DATABASE_URL },
+});

package/templates/db/neon/client.mjs

@@ -0,0 +1,7 @@
+// db/client.mjs — Neon serverless (neon-http) data client. Default provider.
+// Reads the pooled DATABASE_URL; neon() is lazy, so no socket opens at import.
+import { drizzle } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+import * as schema from './schema.mjs';
+
+export const db = drizzle(neon(process.env.DATABASE_URL), { schema });

package/templates/db/neon/env.example

@@ -0,0 +1,6 @@
+# Neon (default provider) — use the POOLED connection string for serverless.
+# The host must contain `-pooler`; a direct host will be flagged at setup.
+DATABASE_URL=postgresql://user:password@ep-example-pooler.us-east-1.aws.neon.tech/dbname?sslmode=require
+
+# Embedding width. 1536 = OpenAI text-embedding-3-small. Must match your schema.
+EMBEDDING_DIM=1536

package/templates/db/supabase/client.mjs

@@ -0,0 +1,7 @@
+// db/client.mjs — Supabase (postgres-js) data client. Opt-in provider.
+// prepare:false is required for Supabase's transaction-mode pooler (port 6543).
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schema from './schema.mjs';
+
+export const db = drizzle(postgres(process.env.DATABASE_URL, { prepare: false }), { schema });

package/templates/db/supabase/config.toml

@@ -0,0 +1,11 @@
+# Supabase local config — minimal. Generated by the helical scaffolder.
+project_id = "helical-app"
+
+[db]
+port = 54322
+major_version = 15
+
+[db.pooler]
+enabled = true
+# Transaction mode is what the postgres-js client connects through (port 6543).
+default_pool_mode = "transaction"

package/templates/db/supabase/env.example

@@ -0,0 +1,8 @@
+# Supabase (opt-in provider) — use the transaction-mode POOLER (port 6543).
+DATABASE_URL=postgresql://postgres.project:password@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Server-side privileged key. Keep secret; never expose to the client.
+SUPABASE_SERVICE_ROLE_KEY=
+
+# Embedding width. 1536 = OpenAI text-embedding-3-small. Must match your schema.
+EMBEDDING_DIM=1536

package/templates/db/supabase/migrations/0001_init.sql

@@ -0,0 +1,12 @@
+-- 0001_init.sql — pgvector + the documents table + an HNSW cosine index.
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS documents (
+  id        serial PRIMARY KEY,
+  body      text NOT NULL,
+  embedding vector(1536) NOT NULL
+);
+
+-- Approximate nearest-neighbour index used by the cosine `<=>` query.
+CREATE INDEX IF NOT EXISTS documents_embedding_idx
+  ON documents USING hnsw (embedding vector_cosine_ops);