astrotype 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lexington Themes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# Astrotypes
+
+Astrotypes is an Astro-first typography pairing project with a built-in CLI.
+
+The project includes:
+- A JSON registry for fonts and pairings in `registry/`.
+- CLI commands to generate, sync, and publish registry artifacts.
+- Astro home page to browse pairings (CLI usage is in this README).
+- CSS-first styling tokens (no required Tailwind color utility classes).
+
+## Core Commands
+
+| Command | Action |
+|---|---|
+| `npm run dev` | Start Astro dev server |
+| `npm run build` | Build registry artifacts and Astro site |
+| `npm run preview` | Preview production build |
+| `npm run generate:candidates` | Generate pairing JSON files |
+| `npm run generate:fonts` | Generate font JSON files |
+| `npm run sync:pairings` | Create `src/data/pairings.generated.mjs` |
+| `npm run build:registry` | Write `registry.json` and `public/registry/**` |
+| `npx astrotype add <pairing>` | Install a pairing into an Astro project |
+
+## CLI Usage
+
+```bash
+npx astrotype add product
+```
+
+### Google Fonts API key (optional)
+
+`generate:fonts` works without a key using public metadata, but you can provide a key for the official Webfonts API.
+
+```bash
+GOOGLE_FONTS_API_KEY=your_key npm run generate:fonts
+```
+
+or:
+
+```bash
+node ./bin/astrotypes.mjs generate:fonts --api-key your_key
+```
+
+This command:
+1. Verifies the target directory is an Astro project.
+2. Writes pairing CSS to `src/styles/astrotypes/<pairing>.css`.
+3. Adds an import in `src/styles/global.css`.
+
+## Notes
+
+- Styling is CSS-token first (`@theme`, `:root`, `.dark`), Tailwind v4 is used as tooling.
+- The generated registry files are static and served from `public/registry`.

package/bin/astrotypes.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { generateFontsCommand } from "../cli/commands/generate-fonts.mjs";
+import { generateCandidatesCommand } from "../cli/commands/generate-candidates.mjs";
+import { syncPairingsCommand } from "../cli/commands/sync-pairings.mjs";
+import { buildRegistryCommand } from "../cli/commands/build-registry.mjs";
+import { addPairingCommand } from "../cli/commands/add.mjs";
+import { addFontCommand } from "../cli/commands/add-font.mjs";
+
+function printHelp() {
+  console.log(`astrotypes CLI
+
+Usage:
+  astrotypes generate:fonts [--api-key <key>] [--target <n>]
+  astrotypes generate:candidates [--target <n>]
+  astrotypes sync:pairings
+  astrotypes build:registry
+  astrotypes add <pairing> [--cwd <path>]
+  astrotypes add:font <font> [--cwd <path>]
+`);
+}
+
+async function run() {
+  const [, , command, ...args] = process.argv;
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "generate:fonts") {
+    let apiKey;
+    let targetFonts;
+    const apiKeyFlag = args.indexOf("--api-key");
+    if (apiKeyFlag >= 0) apiKey = args[apiKeyFlag + 1];
+    const targetFlag = args.indexOf("--target");
+    if (targetFlag >= 0) targetFonts = Number(args[targetFlag + 1]);
+    return generateFontsCommand({ apiKey, targetFonts });
+  }
+  if (command === "generate:candidates") {
+    let targetPairings;
+    const targetFlag = args.indexOf("--target");
+    if (targetFlag >= 0) targetPairings = Number(args[targetFlag + 1]);
+    return generateCandidatesCommand({ targetPairings });
+  }
+  if (command === "sync:pairings") return syncPairingsCommand();
+  if (command === "build:registry") return buildRegistryCommand();
+  if (command === "add") {
+    const pairing = args[0];
+    if (!pairing) {
+      console.error("Missing pairing name. Example: astrotypes add product");
+      process.exit(1);
+    }
+    let cwd;
+    const cwdFlag = args.indexOf("--cwd");
+    if (cwdFlag >= 0) cwd = args[cwdFlag + 1];
+    return addPairingCommand(pairing, { cwd });
+  }
+  if (command === "add:font") {
+    const font = args[0];
+    if (!font) {
+      console.error("Missing font name. Example: astrotypes add:font inter");
+      process.exit(1);
+    }
+    let cwd;
+    const cwdFlag = args.indexOf("--cwd");
+    if (cwdFlag >= 0) cwd = args[cwdFlag + 1];
+    return addFontCommand(font, { cwd });
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+run().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+

package/cli/commands/add-font.mjs

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { getFontByName } from "../lib/registry.mjs";
+import {
+  buildFontImports,
+  isAstroProject,
+  writeAstrotypeCss,
+} from "../lib/add-utils.mjs";
+
+function toCssRules(font) {
+  const family =
+    font.font.provider === "google"
+      ? `"${String(font.font.family || font.title).replace(/ Variable$/, "").replace(/"/g, '\\"')}"`
+      : `"${String(font.title).replace(/"/g, '\\"')}"`;
+  const variable = font.font.variable || `--font-${font.name}`;
+  return `:root {\n  ${variable}: ${family};\n}\n`;
+}
+
+export async function addFontCommand(fontName, options = {}) {
+  const targetDir = path.resolve(options.cwd || process.cwd());
+  if (!isAstroProject(targetDir)) {
+    console.error(
+      "astrotypes add:font can only run inside an Astro project (missing astro.config.* or Astro dependency)."
+    );
+    process.exit(1);
+  }
+
+  const font = getFontByName(fontName);
+  if (!font) {
+    console.error(`Font not found: ${fontName}`);
+    process.exit(1);
+  }
+
+  const fontImports = buildFontImports([font]);
+  const cssText = `${fontImports}
+
+${toCssRules(font)}`;
+  const cssPath = writeAstrotypeCss(targetDir, font.name, cssText);
+  console.log(`Installed font "${font.name}" into ${path.relative(targetDir, cssPath)}.`);
+}

package/cli/commands/add.mjs

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { getFontByName, getPairingByName } from "../lib/registry.mjs";
+import {
+  buildFontImports,
+  isAstroProject,
+  writeAstrotypeCss,
+} from "../lib/add-utils.mjs";
+
+function toCssRules(ruleMap) {
+  return Object.entries(ruleMap)
+    .map(([selector, declarations]) => {
+      const lines = Object.entries(declarations)
+        .map(([prop, value]) => `  ${prop}: ${value};`)
+        .join("\n");
+      return `${selector} {\n${lines}\n}`;
+    })
+    .join("\n\n");
+}
+
+export async function addPairingCommand(pairingName, options = {}) {
+  const targetDir = path.resolve(options.cwd || process.cwd());
+  if (!isAstroProject(targetDir)) {
+    console.error(
+      "astrotypes add can only run inside an Astro project (missing astro.config.* or Astro dependency)."
+    );
+    process.exit(1);
+  }
+
+  const pairing = getPairingByName(pairingName);
+  if (!pairing) {
+    console.error(`Pairing not found: ${pairingName}`);
+    process.exit(1);
+  }
+
+  const fontNames = [pairing.fonts.heading, pairing.fonts.body, pairing.fonts.mono];
+  const fonts = fontNames.map((name) => getFontByName(name));
+  const missing = fontNames.filter((_, index) => !fonts[index]);
+  if (missing.length > 0) {
+    console.error(`Missing font definitions: ${missing.join(", ")}`);
+    process.exit(1);
+  }
+
+  const fontImports = buildFontImports(fonts);
+  const cssText = `${fontImports}
+
+${toCssRules(pairing.css)}
+`;
+  const pairingCssPath = writeAstrotypeCss(targetDir, pairing.name, cssText);
+
+  console.log(`Installed pairing "${pairing.name}" into ${path.relative(targetDir, pairingCssPath)}.`);
+  console.log("No Tailwind color utilities are required; styles are CSS-token driven.");
+}
+

package/cli/commands/build-registry.mjs

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  PUBLIC_REGISTRY_DIR,
+  PROJECT_ROOT,
+  REGISTRY_FONTS_DIR,
+  REGISTRY_PAIRINGS_DIR,
+} from "../lib/paths.mjs";
+import { ensureDir, listJsonFiles, readJson, writeJson } from "../lib/fs-utils.mjs";
+import { buildRegistryIndex, validateRegistry } from "../lib/registry.mjs";
+
+function copyRegistryItems(sourceDir) {
+  const files = listJsonFiles(sourceDir);
+  for (const fileName of files) {
+    fs.copyFileSync(path.join(sourceDir, fileName), path.join(PUBLIC_REGISTRY_DIR, fileName));
+  }
+  return files.length;
+}
+
+export async function buildRegistryCommand() {
+  ensureDir(PUBLIC_REGISTRY_DIR);
+  const { fontErrors, pairingErrors } = validateRegistry();
+  if (fontErrors.length || pairingErrors.length) {
+    for (const error of [...fontErrors, ...pairingErrors]) {
+      console.error(error);
+    }
+    process.exit(1);
+  }
+
+  const fontCount = copyRegistryItems(REGISTRY_FONTS_DIR);
+  const pairingCount = copyRegistryItems(REGISTRY_PAIRINGS_DIR);
+  const baseUrl = process.env.BASE_URL || "https://astrotypes.dev";
+  const index = buildRegistryIndex(baseUrl);
+
+  writeJson(path.join(PROJECT_ROOT, "registry.json"), index);
+  writeJson(path.join(PUBLIC_REGISTRY_DIR, "index.json"), index);
+  console.log(`Registry built: ${fontCount} fonts, ${pairingCount} pairings.`);
+}
+

package/cli/commands/generate-candidates.mjs

@@ -0,0 +1,300 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { PAIRING_RECIPES } from "../data/pairing-recipes.mjs";
+import { REGISTRY_PAIRINGS_DIR } from "../lib/paths.mjs";
+import { ensureDir, listJsonFiles, readJson, writeJson } from "../lib/fs-utils.mjs";
+
+function toKebab(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+
+/** One-word display label from slug (no spaces). */
+function slugToDisplayTitle(slug) {
+  const s = String(slug);
+  if (!s) return "";
+  return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+}
+
+/**
+ * Real English one-word slugs only (no compounds like analogcapsule).
+ * Sorted + deduped; must cover max `--target` with room to grow.
+ */
+const SINGLE_WORD_POOL = (() => {
+  const raw = `
+    abalone acacia agate aileron alchemy alpine amber anchor anvil apex aria atlas aurora
+    azimuth badger barley basil beacon birch bison blackboard blizzard bluebird briar
+    bronze brook brushwood butte caldera canvas cardinal cedar chalk chisel citadel
+    cobalt comet compass coral corbel cormorant crag crescent crowbar crystal cypress
+    delta denim desert dune eagle eddy elm ember equinox falcon fathom fern finch fjord
+    flint fogbank forge fossil frost galaxy garnet gecko glacier glen glyph granite
+    graphite grebe grove gull harbor harvest haven hawthorn hazel heath heron hoarfrost
+    horizon ibis inkwell iris islet ivory jade jasper jetty kestrel kiln lagoon lark
+    latitude laurel ledger lichen lighthouse limestone lotus lumen lunar lynx magnet
+    malachite maple marble marlin meridian meteor mica midnight millet mist mongoose
+    monsoon moor mosaic moss narwhal nebula nettle nexus nickel nightshade nutmeg oak
+    obsidian ocelot octagon onyx opal orbit osprey otter oxbow oyster parchment patina
+    pearl pelican peridot petrel phoenix pigeon pine pivot plenum plumage polaris pollen
+    porpoise prairie prism prow pulsar quarry quartz quill raven reef rhodium rialto
+    ridge riptide riverbed roadrunner robin sage sandstone sapphire scoria scree seabird
+    sequoia serpent shale shoal sienna signal silverfin skylark slate sleet snowdrift
+    solstice sorrel sparrow spinel spruce stalactite stalagmite starling steeple
+    stratus summit sundial sunstone surf swale swift talon tanager teak tempest thistle
+    thorn tide timberline topaz tor tourmaline trailhead trove tundra turnstone twilight
+    urchin vale valley vellum vertex viper vireo vortex wasp watershed waypoint westerly
+    whimbrel wildrice willow windlass windshear winter wren yarrow zenith zircon zephyr
+  `
+    .trim()
+    .split(/\s+/)
+    .map((w) => w.toLowerCase().replace(/[^a-z]/g, ""))
+    .filter(Boolean);
+  return [...new Set(raw)].sort((a, b) => a.localeCompare(b));
+})();
+
+/** One real word per pairing; if you exceed the pool, append a generation suffix (rare). */
+function oneWordSlugAt(index) {
+  const n = SINGLE_WORD_POOL.length;
+  const base = SINGLE_WORD_POOL[index % n];
+  const gen = Math.floor(index / n);
+  return gen === 0 ? base : `${base}${gen + 1}`;
+}
+
+function applyHipsterNames(recipes) {
+  return recipes.map((recipe, index) => {
+    const name = oneWordSlugAt(index);
+    return {
+      ...recipe,
+      name,
+      title: slugToDisplayTitle(name),
+    };
+  });
+}
+
+/** Stable key for the same font stack across renames / regens. */
+function fontTripleKeyFromRecipe(recipe) {
+  return `${toKebab(recipe.heading)}|${toKebab(recipe.body)}|${toKebab(recipe.mono)}`;
+}
+
+function fontTripleKeyFromPairingJson(p) {
+  if (!p?.fonts?.heading || !p.fonts.body || !p.fonts.mono) return null;
+  return `${p.fonts.heading}|${p.fonts.body}|${p.fonts.mono}`;
+}
+
+/**
+ * Before wiping pairings, remember ids + every slug ever used (name + aliases) per font triple
+ * so the next write can emit `aliases` for old URLs and keep the same `id`.
+ */
+function loadPriorPairingState(pairingsDir) {
+  /** @type {Map<string, { id: string, names: Set<string> }>} */
+  const byTriple = new Map();
+  for (const fileName of listJsonFiles(pairingsDir)) {
+    let p;
+    try {
+      p = readJson(path.join(pairingsDir, fileName));
+    } catch {
+      continue;
+    }
+    const triple = fontTripleKeyFromPairingJson(p);
+    if (!triple) continue;
+    const nameSet = new Set(
+      [p.name, ...(Array.isArray(p.aliases) ? p.aliases : [])].filter(
+        (x) => typeof x === "string" && x.trim(),
+      ),
+    );
+    const existingId = typeof p.id === "string" && p.id.trim() ? p.id.trim() : null;
+    const cur = byTriple.get(triple);
+    if (cur) {
+      for (const n of nameSet) cur.names.add(n);
+      if (existingId) cur.id = existingId;
+    } else {
+      byTriple.set(triple, {
+        id: existingId || randomUUID(),
+        names: nameSet,
+      });
+    }
+  }
+  for (const v of byTriple.values()) {
+    if (!v.id) v.id = randomUUID();
+  }
+  return byTriple;
+}
+
+/**
+ * Reserve each slug globally: canonical names win; aliases must not collide with another pairing.
+ */
+function finalizePairingSlugs(pairings) {
+  const taken = new Set(pairings.map((p) => p.name));
+  for (const p of pairings) {
+    const next = [];
+    for (const a of p.aliases) {
+      if (!a || a === p.name || taken.has(a)) continue;
+      taken.add(a);
+      next.push(a);
+    }
+    p.aliases = next;
+  }
+}
+
+function toPairing(recipe) {
+  const heading = toKebab(recipe.heading);
+  const body = toKebab(recipe.body);
+  const mono = toKebab(recipe.mono);
+  const title = recipe.title || slugToDisplayTitle(recipe.name);
+  const category = recipe.category || recipe.categories?.[0] || "general";
+  const aliases = Array.isArray(recipe.aliases)
+    ? [...new Set(recipe.aliases)].filter((x) => typeof x === "string" && x.trim())
+    : [];
+
+  return {
+    id: recipe.id,
+    name: recipe.name,
+    aliases,
+    type: "astrotypes:pairing",
+    title: `${title} - ${heading} + ${body} + ${mono}`,
+    description: recipe.description,
+    category,
+    fonts: {
+      heading,
+      body,
+      mono,
+    },
+    tokens: {
+      "--font-heading": `var(--font-${heading})`,
+      "--font-body": `var(--font-${body})`,
+      "--font-mono": `var(--font-${mono})`,
+    },
+    typography: {
+      h1: { "font-size": "2.25rem", "line-height": "1.2", "letter-spacing": "-0.02em", "font-weight": "700" },
+      h2: { "font-size": "1.875rem", "line-height": "1.25", "letter-spacing": "-0.015em", "font-weight": "600" },
+      h3: { "font-size": "1.5rem", "line-height": "1.3", "letter-spacing": "-0.01em", "font-weight": "600" },
+      body: { "font-size": "1rem", "line-height": "1.65", "font-weight": "400" },
+    },
+    css: {
+      ":root": {
+        "--font-heading": `var(--font-${heading})`,
+        "--font-body": `var(--font-${body})`,
+        "--font-mono": `var(--font-${mono})`,
+      },
+      "h1, h2, h3, h4, h5, h6": {
+        "font-family": "var(--font-heading)",
+      },
+      "body, p": {
+        "font-family": "var(--font-body)",
+      },
+      "code, pre": {
+        "font-family": "var(--font-mono)",
+      },
+    },
+    meta: {
+      mood: recipe.mood || [],
+      useCase: recipe.useCase || [],
+      preview: "The quick brown fox jumps over the lazy dog.",
+    },
+  };
+}
+
+function synthesizeRecipes(targetPairings) {
+  const generated = [];
+  const seenNames = new Set(PAIRING_RECIPES.map((r) => r.name));
+  const seenTriples = new Set(
+    PAIRING_RECIPES.map((r) => `${toKebab(r.heading)}|${toKebab(r.body)}|${toKebab(r.mono)}`),
+  );
+  const seeds = [...PAIRING_RECIPES];
+  const headingPool = [...new Set(seeds.map((r) => r.heading))];
+  const bodyPool = [...new Set(seeds.map((r) => r.body))];
+  const monoPool = [...new Set(seeds.map((r) => r.mono))];
+  const maxCombos = headingPool.length * bodyPool.length * monoPool.length;
+
+  let i = 0;
+  while (
+    seeds.length + generated.length < targetPairings &&
+    i < maxCombos &&
+    generated.length < maxCombos
+  ) {
+    const heading = headingPool[i % headingPool.length];
+    const body =
+      bodyPool[Math.floor(i / headingPool.length) % bodyPool.length];
+    const mono =
+      monoPool[
+        Math.floor(i / (headingPool.length * bodyPool.length)) % monoPool.length
+      ];
+
+    const a = seeds[i % seeds.length];
+    const b = seeds[(i + 7) % seeds.length];
+    const c = seeds[(i + 13) % seeds.length];
+    const tripleKey = `${toKebab(heading)}|${toKebab(body)}|${toKebab(mono)}`;
+    if (seenTriples.has(tripleKey)) {
+      i++;
+      continue;
+    }
+
+    const name = `blend${String(generated.length + 1).padStart(3, "0")}`;
+    if (seenNames.has(name)) {
+      i++;
+      continue;
+    }
+
+    generated.push({
+      name,
+      title: `Blend ${String(generated.length + 1).padStart(3, "0")}`,
+      heading,
+      body,
+      mono,
+      description: `Auto-generated stack using ${heading}, ${body}, and ${mono}.`,
+      categories: [a.categories?.[0] || b.categories?.[0] || "sans-serif"],
+      mood: [...new Set([...(a.mood || []), ...(b.mood || [])])].slice(0, 3),
+      useCase: [...new Set([...(a.useCase || []), ...(b.useCase || []), ...(c.useCase || [])])].slice(0, 3),
+    });
+    seenNames.add(name);
+    seenTriples.add(tripleKey);
+    i++;
+  }
+
+  return generated;
+}
+
+export async function generateCandidatesCommand(options = {}) {
+  ensureDir(REGISTRY_PAIRINGS_DIR);
+  const priorState = loadPriorPairingState(REGISTRY_PAIRINGS_DIR);
+  for (const fileName of listJsonFiles(REGISTRY_PAIRINGS_DIR)) {
+    if (fileName.endsWith(".json")) {
+      // Regeneration is authoritative; remove stale pairings from prior runs.
+      fs.unlinkSync(path.join(REGISTRY_PAIRINGS_DIR, fileName));
+    }
+  }
+  const parsedTarget = Number(options.targetPairings);
+  const targetPairings =
+    Number.isFinite(parsedTarget) && parsedTarget > 0
+      ? Math.floor(parsedTarget)
+      : PAIRING_RECIPES.length;
+  const recipes =
+    targetPairings > PAIRING_RECIPES.length
+      ? [...PAIRING_RECIPES, ...synthesizeRecipes(targetPairings)]
+      : PAIRING_RECIPES;
+  const namedRecipes = applyHipsterNames(recipes);
+
+  const pairings = [];
+  for (const recipe of namedRecipes) {
+    const triple = fontTripleKeyFromRecipe(recipe);
+    const prev = priorState.get(triple);
+    const id = prev?.id || randomUUID();
+    const aliases = [];
+    if (prev) {
+      for (const n of prev.names) {
+        if (n !== recipe.name) aliases.push(n);
+      }
+    }
+    const pairing = toPairing({ ...recipe, id, aliases });
+    pairings.push(pairing);
+  }
+  finalizePairingSlugs(pairings);
+
+  for (const pairing of pairings) {
+    writeJson(path.join(REGISTRY_PAIRINGS_DIR, `${pairing.name}.json`), pairing);
+  }
+  console.log(`Generated ${pairings.length} Astrotypes pairing entries in registry/pairings.`);
+}
+