@helical-design/substrate 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @helical-design/substrate
+
+The Helical build substrate: unified, fail-loud, deterministic build for **design tokens** and **content**, both authored as flat-files-by-key.
+
+## API
+```js
+import { buildTokens, buildContent, generatePalette } from '@helical-design/substrate';
+
+generatePalette('.');             // Leonardo → tokens/palette.{dark,light}.json
+await buildTokens('.');           // DTCG tokens → dist/tokens.css (dark + light)
+buildContent({                    // content × templates → dist/*.html (throws on missing key)
+  contentDir: 'content', templatesDir: 'templates', outDir: 'dist',
+  pages: [
+    { out: 'index.html', template: 'home' },
+    { out: 'journal/:slug.html', template: 'entry', forEach: 'journal', as: 'entry' },
+  ],
+});
+```
+
+## Guarantees
+- **Flat-files-by-key** - one fact in one place (`tokens/*.json`, `content/*.json|md`).
+- **Fail-loud** - a missing/renamed key breaks the build; never ships a blank or hallucination.
+- **Deterministic** - same inputs -> byte-identical output (golden-snapshot friendly).

package/bin/create-helical.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// bin/create-helical.mjs — a thin, non-interactive-capable CLI over scaffold().
+// All real logic (validation, stamping) lives in src/scaffold.mjs; this file
+// only parses args, surfaces errors as plain messages, and prints a success line.
+import { parseArgs } from 'node:util';
+import { scaffold } from '../src/scaffold.mjs';
+
+const USAGE = `create-helical — stamp a new Helical project.
+
+Usage:
+  create-helical <name> [options]
+
+Options:
+  --dir <path>             target directory (default ./<name>)
+  --profile marketing|app  project profile (default marketing)
+  --db neon|supabase       database for the app profile (default neon)
+  --force                  overwrite a non-empty target dir
+  --yes                    run non-interactively straight from flags
+  --help                   show this help and exit
+`;
+
+function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      dir: { type: 'string' },
+      profile: { type: 'string' },
+      db: { type: 'string' },
+      force: { type: 'boolean' },
+      yes: { type: 'boolean' },
+      help: { type: 'boolean' },
+    },
+  });
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  const name = positionals[0];
+  const dir = values.dir ?? (name ? `./${name}` : undefined);
+
+  const out = scaffold({
+    name,
+    dir,
+    profile: values.profile,
+    db: values.db,
+    force: values.force,
+  });
+
+  process.stdout.write(`Stamped ${name} into ${out}\n`);
+}
+
+try {
+  main();
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@helical-design/substrate",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "create-helical": "bin/create-helical.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./content": "./src/content.mjs",
+    "./harness": "./src/harness.mjs",
+    "./db": "./src/db/client.mjs",
+    "./db/schema": "./src/db/schema.mjs",
+    "./db/vector": "./src/db/vector.mjs"
+  },
+  "files": ["src", "bin", "templates", "tokens", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "gen:palette": "node scripts/gen-palette.mjs",
+    "gen:scale": "node scripts/gen-scale.mjs",
+    "build": "node scripts/build-tokens.mjs && node scripts/build-registry.mjs",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@adobe/leonardo-contrast-colors": "^1.1.0",
+    "@neondatabase/serverless": "^1.1.0",
+    "culori": "^4.0.2",
+    "drizzle-orm": "^0.45.2",
+    "gray-matter": "^4.0.3",
+    "marked": "^12.0.2",
+    "postgres": "^3.4.9",
+    "style-dictionary": "^4.4.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "~0.4.6",
+    "drizzle-kit": "^0.31.10"
+  }
+}

package/src/build-all.mjs

@@ -0,0 +1,59 @@
+// src/build-all.mjs — the composed builder. buildTokens and buildContent each
+// rmSync their own outDir before writing, so pointing both at one dist/ makes the
+// second clobber the first. This orchestrator builds each into its OWN temp
+// staging dir, then assembles a single coherent outDir from both — HTML + assets
+// from the content stage, plus the combined token CSS dropped at the dist root
+// (so the layout's absolute `/tokens.css` link resolves on a deployed site).
+import {
+  readFileSync, existsSync, mkdtempSync, mkdirSync, rmSync, cpSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { buildTokens } from './tokens.mjs';
+import { buildContent } from './build.mjs';
+
+export async function build({
+  root = '.', outDir = join(root, 'dist'), pages, assetsDir, stylesheet = 'tokens.css',
+} = {}) {
+  // Resolve the page manifest: explicit arg wins, else read root/pages.json.
+  if (pages === undefined) {
+    const manifest = join(root, 'pages.json');
+    if (!existsSync(manifest)) {
+      throw new Error(`build: no pages provided and no manifest found at ${manifest}`);
+    }
+    pages = JSON.parse(readFileSync(manifest, 'utf8'));
+  }
+
+  // Default assetsDir to root/assets only when it exists; otherwise omit.
+  if (assetsDir === undefined) {
+    const candidate = join(root, 'assets');
+    if (existsSync(candidate)) assetsDir = candidate;
+  }
+
+  // Two separate staging dirs so neither builder's rmSync wipes the other.
+  const tokensStage = mkdtempSync(join(tmpdir(), 'helical-build-tokens-'));
+  const contentStage = mkdtempSync(join(tmpdir(), 'helical-build-content-'));
+  try {
+    await buildTokens(root, tokensStage);
+    buildContent({
+      contentDir: join(root, 'content'),
+      templatesDir: join(root, 'templates'),
+      outDir: contentStage,
+      pages,
+      assetsDir,
+    });
+
+    // Assemble the final dist ONCE from the two stages.
+    rmSync(outDir, { recursive: true, force: true });
+    mkdirSync(outDir, { recursive: true });
+    // Content stage carries the HTML (and its assets/ subdir) — copy it wholesale.
+    cpSync(contentStage, outDir, { recursive: true });
+    // Combined token CSS lands at the dist root, matching the /tokens.css link.
+    cpSync(join(tokensStage, 'tokens.css'), join(outDir, stylesheet));
+
+    return outDir;
+  } finally {
+    rmSync(tokensStage, { recursive: true, force: true });
+    rmSync(contentStage, { recursive: true, force: true });
+  }
+}

package/src/build.mjs

@@ -0,0 +1,31 @@
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, rmSync, cpSync, existsSync } from 'node:fs';
+import { join, dirname, basename, extname, resolve, sep } from 'node:path';
+import { loadStore } from './store.mjs';
+import { render } from './render.mjs';
+import { resolvePages } from './pages.mjs';
+
+function loadPartials(templatesDir) {
+  const dir = join(templatesDir, 'partials');
+  const partials = {};
+  if (existsSync(dir)) for (const f of readdirSync(dir))
+    if (extname(f) === '.html') partials[basename(f, '.html')] = readFileSync(join(dir, f), 'utf8');
+  return partials;
+}
+
+export function buildContent({ contentDir, templatesDir, outDir, pages, assetsDir }) {
+  const store = loadStore(contentDir);
+  const partials = loadPartials(templatesDir);
+  const layout = readFileSync(join(templatesDir, 'layout.html'), 'utf8');
+  rmSync(outDir, { recursive: true, force: true });
+  for (const page of resolvePages(pages, store)) {
+    const tpl = readFileSync(join(templatesDir, `pages/${page.template}.html`), 'utf8');
+    const body = render(tpl, page.context, partials); // throws on missing key
+    const html = render(layout, { ...page.context, body: '%%BODY%%' }, partials).replace('%%BODY%%', body);
+    const outPath = join(outDir, page.out);
+    if (!resolve(outPath).startsWith(resolve(outDir) + sep)) throw new Error(`build: page out escapes outDir: ${page.out}`);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, html);
+  }
+  if (assetsDir && existsSync(assetsDir)) cpSync(assetsDir, join(outDir, 'assets'), { recursive: true });
+  return outDir;
+}

package/src/content.mjs

@@ -0,0 +1,6 @@
+// Content-only entrypoint — the renderer/store/pages primitives a static-site
+// consumer needs, WITHOUT the db/token graph the '.' entrypoint re-exports.
+// Import via '@helical/substrate/content'.
+export { render } from './render.mjs';
+export { loadStore } from './store.mjs';
+export { resolvePages } from './pages.mjs';

package/src/db/client.mjs

@@ -0,0 +1,45 @@
+// src/db/client.mjs — provider-swappable Drizzle factory.
+// Neon (neon-http) is the default; Supabase (postgres-js) is opt-in. Both bind
+// the SAME schema — only the connection driver changes. Client construction is
+// lazy: neon()/postgres() do not open a socket here, so createDb() is safe to
+// call without a live database (the wiring is what callers assert).
+import { drizzle as drizzleNeon } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schema from './schema.mjs';
+
+export function createDb({
+  provider = process.env.DB_PROVIDER ?? 'neon',
+  url = process.env.DATABASE_URL,
+} = {}) {
+  switch (provider) {
+    case 'neon':
+      return drizzleNeon(neon(url), { schema });
+    case 'supabase':
+      // prepare:false is required for Supabase's transaction-mode pooler (:6543).
+      return drizzlePostgres(postgres(url, { prepare: false }), { schema });
+    default:
+      throw new Error(`unknown provider: ${provider} — expected 'neon' or 'supabase'`);
+  }
+}
+
+// Serverless drivers need a pooled connection string. Flag direct hosts so a
+// misconfigured DATABASE_URL fails loudly at setup rather than under load.
+// A host is "pooled" if its hostname carries a `-pooler` segment (Neon),
+// resolves to the Supabase pooler domain, or uses the :6543 transaction port.
+export function assertPooled(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return [`connection string is not a valid URL: ${url} — use the pooled connection string for serverless`];
+  }
+  const pooled =
+    u.hostname.includes('-pooler') ||
+    u.hostname.includes('pooler.supabase') ||
+    u.port === '6543';
+  return pooled
+    ? []
+    : [`connection is not pooled: ${u.host} — use the pooled connection string for serverless`];
+}

package/src/db/schema.mjs

@@ -0,0 +1,15 @@
+// src/db/schema.mjs — ONE relational+vector schema, shared by every provider.
+// Embedding width is config-driven (EMBEDDING_DIM) so re-skinning the model
+// never means editing the schema. Default 1536 = OpenAI text-embedding-3-small.
+import { pgTable, serial, text, vector, index } from 'drizzle-orm/pg-core';
+
+const DIM = Number(process.env.EMBEDDING_DIM ?? 1536);
+
+export const documents = pgTable('documents', {
+  id: serial('id').primaryKey(),
+  body: text('body').notNull(),
+  embedding: vector('embedding', { dimensions: DIM }).notNull(),
+}, (t) => ({
+  // HNSW + cosine: the index pgvector uses for approximate nearest-neighbour.
+  embIdx: index('documents_embedding_idx').using('hnsw', t.embedding.op('vector_cosine_ops')),
+}));

package/src/db/vector.mjs

@@ -0,0 +1,10 @@
+// src/db/vector.mjs — cosine nearest-neighbour query, provider-agnostic.
+// Returns the k rows closest to queryEmbedding, nearest first. Drizzle emits the
+// `<=>` cosine-distance operator, which the HNSW index in schema.mjs accelerates.
+import { cosineDistance, asc } from 'drizzle-orm';
+
+export async function nearest(db, table, queryEmbedding, k = 5) {
+  const distance = cosineDistance(table.embedding, queryEmbedding);
+  return db.select({ id: table.id, body: table.body, distance })
+           .from(table).orderBy(asc(distance)).limit(k);
+}