astrotype 0.1.1

package/cli/commands/generate-fonts.mjs

@@ -0,0 +1,169 @@
+import path from "node:path";
+import { PAIRING_RECIPES } from "../data/pairing-recipes.mjs";
+import { REGISTRY_FONTS_DIR, toKebab } from "../lib/paths.mjs";
+import { ensureDir, writeJson } from "../lib/fs-utils.mjs";
+
+const MANUAL_FONTS = [
+  {
+    family: "Geist",
+    category: "sans-serif",
+    weights: ["100", "200", "300", "400", "500", "600", "700", "800", "900"],
+    subsets: ["latin", "latin-ext"],
+    provider: "npm",
+    npmPackage: "geist",
+  },
+  {
+    family: "Geist Mono",
+    category: "monospace",
+    weights: ["100", "200", "300", "400", "500", "600", "700", "800", "900"],
+    subsets: ["latin", "latin-ext"],
+    provider: "npm",
+    npmPackage: "geist",
+  },
+];
+
+function importNameForFamily(family) {
+  return family.replace(/ /g, "_");
+}
+
+function extractWeights(variants) {
+  const weights = new Set();
+  for (const variant of variants) {
+    const match = String(variant).match(/^(\d+)/);
+    if (match) weights.add(match[1]);
+    if (variant === "regular" || variant === "italic") weights.add("400");
+  }
+  return [...weights].sort();
+}
+
+function toAstrotypesFontEntry({ family, category, weights, subsets, provider, dependency, npmPackage }) {
+  const name = toKebab(family);
+  const usesVariablePackage = provider === "google" && !dependency;
+  return {
+    name,
+    type: "astrotypes:font",
+    title: family,
+    description: `${family} font definition for Astrotypes.`,
+    category,
+    font: {
+      family: usesVariablePackage ? `${family} Variable` : family,
+      provider,
+      import: importNameForFamily(family),
+      variable: `--font-${name}`,
+      weight: weights,
+      subsets,
+      ...(dependency ? { dependency } : {}),
+      ...(npmPackage ? { npmPackage } : {}),
+    },
+  };
+}
+
+function parseWebfontsItem(item) {
+  const rawVariants = Array.isArray(item.variants) ? item.variants : ["regular"];
+  return {
+    family: item.family,
+    category: item.category || "sans-serif",
+    subsets: Array.isArray(item.subsets) && item.subsets.length > 0 ? item.subsets : ["latin"],
+    variants: rawVariants,
+  };
+}
+
+function parseMetadataItem(item) {
+  const weights = Object.keys(item.fonts || {}).filter((key) => !key.includes("i"));
+  return {
+    family: item.family,
+    category: item.category || "sans-serif",
+    subsets: item.subsets || ["latin"],
+    variants: weights.length > 0 ? weights : ["400"],
+  };
+}
+
+async function loadGoogleFamilies(apiKey) {
+  if (apiKey) {
+    const webfontsUrl = `https://www.googleapis.com/webfonts/v1/webfonts?key=${encodeURIComponent(
+      apiKey
+    )}`;
+    const response = await fetch(webfontsUrl);
+    if (!response.ok) {
+      throw new Error(`Google Webfonts API failed (${response.status}).`);
+    }
+    const payload = await response.json();
+    return (payload.items ?? []).map(parseWebfontsItem);
+  }
+
+  const response = await fetch("https://fonts.google.com/metadata/fonts");
+  const responseText = await response.text();
+  const metadata = JSON.parse(responseText.replace(/^\)]\}'?\n?/, ""));
+  const familyList = metadata.familyMetadataList ?? [];
+  return familyList.map(parseMetadataItem);
+}
+
+export async function generateFontsCommand(options = {}) {
+  ensureDir(REGISTRY_FONTS_DIR);
+
+  const requiredByRecipes = new Set();
+  for (const recipe of PAIRING_RECIPES) {
+    requiredByRecipes.add(toKebab(recipe.heading));
+    requiredByRecipes.add(toKebab(recipe.body));
+    requiredByRecipes.add(toKebab(recipe.mono));
+  }
+
+  const apiKey = options.apiKey || process.env.GOOGLE_FONTS_API_KEY;
+  if (apiKey) {
+    console.log("Using Google Webfonts API with key from env/flag.");
+  } else {
+    console.log("Using public Google metadata endpoint (no API key).");
+  }
+
+  const familyList = await loadGoogleFamilies(apiKey);
+  const parsedTarget = Number(options.targetFonts);
+  const targetFonts =
+    Number.isFinite(parsedTarget) && parsedTarget > 0
+      ? Math.floor(parsedTarget)
+      : familyList.length;
+
+  const selectedFamilyNames = new Set(requiredByRecipes);
+  if (targetFonts > selectedFamilyNames.size) {
+    for (const item of familyList) {
+      const name = toKebab(item.family);
+      selectedFamilyNames.add(name);
+      if (selectedFamilyNames.size >= targetFonts) break;
+    }
+  }
+
+  let generated = 0;
+  for (const item of familyList) {
+    const family = item.family;
+    const name = toKebab(family);
+    if (!selectedFamilyNames.has(name)) continue;
+
+    const entry = toAstrotypesFontEntry({
+      family,
+      category: item.category || "sans-serif",
+      weights: extractWeights(item.variants ?? ["400"]),
+      subsets: item.subsets || ["latin"],
+      provider: "google",
+      dependency: undefined,
+    });
+    writeJson(path.join(REGISTRY_FONTS_DIR, `${entry.name}.json`), entry);
+    generated++;
+  }
+
+  for (const manual of MANUAL_FONTS) {
+    const entry = toAstrotypesFontEntry({
+      family: manual.family,
+      category: manual.category,
+      weights: manual.weights,
+      subsets: manual.subsets,
+      provider: manual.provider,
+      npmPackage: manual.npmPackage,
+    });
+    writeJson(path.join(REGISTRY_FONTS_DIR, `${entry.name}.json`), entry);
+    generated++;
+  }
+
+  console.log(
+    `Generated ${generated} Astrotypes font entries in registry/fonts (target ${targetFonts}).`,
+  );
+}
+

package/cli/commands/sync-pairings.mjs

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import { GENERATED_DATA_DIR, REGISTRY_PAIRINGS_DIR } from "../lib/paths.mjs";
+import { ensureDir, listJsonFiles, readJson } from "../lib/fs-utils.mjs";
+
+export async function syncPairingsCommand() {
+  ensureDir(GENERATED_DATA_DIR);
+  const files = listJsonFiles(REGISTRY_PAIRINGS_DIR);
+  const entries = files.map((fileName) =>
+    readJson(path.join(REGISTRY_PAIRINGS_DIR, fileName))
+  );
+
+  const output = `// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: registry/pairings/*.json
+
+export const PAIRINGS_DATA = ${JSON.stringify(entries, null, 2)};
+`;
+
+  fs.writeFileSync(path.join(GENERATED_DATA_DIR, "pairings.generated.mjs"), output);
+  console.log(`Synced ${entries.length} pairings to src/data/pairings.generated.mjs`);
+}
+

package/cli/data/pairing-recipes.mjs

@@ -0,0 +1,57 @@
+export const PAIRING_RECIPES = [
+  { name: "product", heading: "Plus Jakarta Sans", body: "Inter", mono: "JetBrains Mono", description: "Product-focused clarity. Jakarta's slightly warmer geometry gives headings personality without the noise, while Inter handles the fine print with surgical precision.", categories: ["sans-serif", "complementary", "product"], mood: ["friendly", "professional"], useCase: ["SaaS", "product", "web app"] },
+  { name: "editorial", heading: "Playfair Display", body: "DM Sans", mono: "JetBrains Mono", description: "High-contrast editorial pairing for storytelling and long-form writing.", categories: ["serif", "contrast", "editorial"], mood: ["sophisticated", "expressive"], useCase: ["blog", "magazine", "content"] },
+  { name: "technical", heading: "IBM Plex Sans", body: "Inter", mono: "IBM Plex Mono", description: "Engineering-focused pairing tuned for docs, changelogs, and product UI.", categories: ["sans-serif", "developer", "technical"], mood: ["precise", "neutral"], useCase: ["docs", "developer-tools", "enterprise"] },
+  { name: "minimal", heading: "Geist", body: "Geist", mono: "Geist Mono", description: "Systematic pairing with Geist family for modern interfaces.", categories: ["system", "minimal"], mood: ["minimal", "focused"], useCase: ["app", "portfolio", "landing"] },
+  { name: "broadsheet", heading: "Playfair Display", body: "DM Sans", mono: "JetBrains Mono", description: "High-contrast editorial with a modern twist.", categories: ["serif", "contrast", "editorial"], mood: ["sophisticated", "editorial"], useCase: ["news", "magazine", "blog"] },
+  { name: "scholar", heading: "EB Garamond", body: "Inter", mono: "Source Code Pro", description: "Academic precision meets digital clarity.", categories: ["serif", "contrast", "academic"], mood: ["academic", "refined"], useCase: ["documentation", "research", "education"] },
+  { name: "hearth", heading: "Lora", body: "Nunito Sans", mono: "Inconsolata", description: "Warm and inviting with narrative personality.", categories: ["serif", "contrast", "warm"], mood: ["warm", "narrative"], useCase: ["blog", "storytelling", "content"] },
+  { name: "journal", heading: "Merriweather", body: "Mulish", mono: "Source Code Pro", description: "Purpose-built reading experience for long-form content.", categories: ["serif", "contrast", "readable"], mood: ["reliable", "readable"], useCase: ["blog", "journal", "publishing"] },
+  { name: "gazette", heading: "Cormorant Garamond", body: "Raleway", mono: "Roboto Mono", description: "Old-world elegance with contemporary grace.", categories: ["serif", "contrast", "elegant"], mood: ["elegant", "dramatic"], useCase: ["magazine", "luxury", "fashion"] },
+  { name: "thesis", heading: "Noto Serif", body: "Noto Sans", mono: "Inconsolata", description: "Universal typography for multilingual products.", categories: ["serif", "contrast", "universal"], mood: ["universal", "professional"], useCase: ["documentation", "i18n", "enterprise"] },
+  { name: "facade", heading: "Outfit", body: "Libre Baskerville", mono: "IBM Plex Mono", description: "Structured headings contrasted with refined body text.", categories: ["sans-serif", "contrast", "structured"], mood: ["structured", "professional"], useCase: ["portfolio", "agency", "architecture"] },
+  { name: "curator", heading: "Plus Jakarta Sans", body: "PT Serif", mono: "Source Code Pro", description: "Contemporary curation with typographic depth.", categories: ["sans-serif", "contrast", "curated"], mood: ["curated", "contemporary"], useCase: ["gallery", "museum", "portfolio"] },
+  { name: "dashboard", heading: "Manrope", body: "DM Sans", mono: "Fira Code", description: "Data-driven clarity for dense interfaces.", categories: ["sans-serif", "complementary", "data"], mood: ["analytical", "clear"], useCase: ["dashboard", "analytics", "admin"] },
+  { name: "ledger", heading: "Outfit", body: "IBM Plex Sans", mono: "IBM Plex Mono", description: "Trustworthy product typography for finance.", categories: ["sans-serif", "complementary", "finance"], mood: ["trustworthy", "precise"], useCase: ["fintech", "banking", "enterprise"] },
+  { name: "studio", heading: "Bricolage Grotesque", body: "Figtree", mono: "Fira Code", description: "Design-forward pairing with strong identity.", categories: ["sans-serif", "creative", "design"], mood: ["creative", "distinctive"], useCase: ["design studio", "agency", "creative"] },
+  { name: "corporate", heading: "Roboto", body: "Roboto", mono: "Roboto Mono", description: "A cohesive and systematic Roboto stack.", categories: ["sans-serif", "superfamily", "corporate"], mood: ["neutral", "systematic"], useCase: ["enterprise", "Android", "Material Design"] },
+  { name: "document", heading: "Source Sans 3", body: "Source Sans 3", mono: "Source Code Pro", description: "Open-source superfamily optimized for docs.", categories: ["sans-serif", "superfamily", "document"], mood: ["professional", "versatile"], useCase: ["documentation", "enterprise", "publishing"] },
+  { name: "startup", heading: "Nunito", body: "Nunito Sans", mono: "Fira Code", description: "Friendly startup-friendly typography stack.", categories: ["sans-serif", "superfamily", "friendly"], mood: ["friendly", "approachable"], useCase: ["startup", "consumer app", "landing page"] },
+  { name: "headline", heading: "Anton", body: "Work Sans", mono: "Roboto Mono", description: "Bold display-first pairing for impact.", categories: ["display", "bold", "impactful"], mood: ["bold", "impactful"], useCase: ["news", "sports", "media"] },
+  { name: "poster", heading: "Oswald", body: "Barlow", mono: "Inconsolata", description: "Condensed, commanding headlines with readable body.", categories: ["display", "condensed", "bold"], mood: ["commanding", "editorial"], useCase: ["media", "news", "marketing"] },
+  { name: "brutalist", heading: "Archivo Black", body: "Archivo", mono: "Source Code Pro", description: "Raw typographic force for expressive layouts.", categories: ["display", "brutalist", "bold"], mood: ["raw", "brutalist"], useCase: ["portfolio", "art", "experimental"] },
+  { name: "handbook", heading: "Lexend", body: "Lexend", mono: "Inconsolata", description: "Readability-first pair for educational content.", categories: ["sans-serif", "superfamily", "readable"], mood: ["accessible", "clear"], useCase: ["education", "documentation", "accessibility"] },
+  { name: "agency", heading: "Schibsted Grotesk", body: "Karla", mono: "Fira Code", description: "Nordic minimalism with grotesque warmth.", categories: ["sans-serif", "complementary", "nordic"], mood: ["minimal", "nordic"], useCase: ["agency", "design", "portfolio"] },
+  { name: "literary", heading: "EB Garamond", body: "Crimson Text", mono: "Inconsolata", description: "A scholarly serif harmony for long reading.", categories: ["serif", "harmonious", "literary"], mood: ["scholarly", "literary"], useCase: ["publishing", "literature", "academic"] },
+  { name: "novel", heading: "Cormorant Garamond", body: "Lora", mono: "JetBrains Mono", description: "Dramatic serif display with narrative warmth.", categories: ["serif", "harmonious", "narrative"], mood: ["dramatic", "literary"], useCase: ["publishing", "book", "longform"] },
+  { name: "launch", heading: "Sora", body: "Public Sans", mono: "Fira Code", description: "Launch-ready confidence and clear UI body text.", categories: ["sans-serif", "complementary", "startup"], mood: ["modern", "confident"], useCase: ["startup", "landing page", "product"] },
+  { name: "saas", heading: "Urbanist", body: "Libre Franklin", mono: "JetBrains Mono", description: "SaaS-native typography for product pages.", categories: ["sans-serif", "complementary", "product"], mood: ["clean", "startup"], useCase: ["SaaS", "pricing page", "product"] },
+  { name: "playful", heading: "Quicksand", body: "Cabin", mono: "Inconsolata", description: "Rounded and approachable UI voice.", categories: ["sans-serif", "complementary", "friendly"], mood: ["playful", "approachable"], useCase: ["kids", "education", "consumer app"] },
+  { name: "venture", heading: "Jost", body: "Rubik", mono: "Roboto Mono", description: "Geometric ambition for modern landing pages.", categories: ["sans-serif", "complementary", "geometric"], mood: ["bold", "geometric"], useCase: ["venture capital", "finance", "landing page"] },
+  { name: "civic", heading: "Public Sans", body: "Lato", mono: "Source Code Pro", description: "Accessible clarity for civic and public services.", categories: ["sans-serif", "complementary", "accessible"], mood: ["trustworthy", "accessible"], useCase: ["government", "healthcare", "public sector"] },
+  { name: "devtool", heading: "Red Hat Display", body: "Red Hat Display", mono: "Fira Code", description: "Technical but approachable devtool typography.", categories: ["sans-serif", "superfamily", "developer"], mood: ["technical", "open-source"], useCase: ["developer tools", "documentation", "open source"] },
+  { name: "social", heading: "Poppins", body: "Hind", mono: "Roboto Mono", description: "Global-ready friendly social product stack.", categories: ["sans-serif", "complementary", "global"], mood: ["friendly", "warm"], useCase: ["social media", "consumer app", "i18n"] },
+  { name: "swiss", heading: "Inter Tight", body: "Open Sans", mono: "IBM Plex Mono", description: "Neo-grotesque precision for admin interfaces.", categories: ["sans-serif", "complementary", "neutral"], mood: ["neutral", "systematic"], useCase: ["enterprise", "dashboard", "admin"] },
+  { name: "wellness", heading: "Figtree", body: "Overpass", mono: "Inconsolata", description: "Calm, clear, and highly legible in critical flows.", categories: ["sans-serif", "complementary", "healthcare"], mood: ["calm", "clear"], useCase: ["healthcare", "wellness", "medical"] },
+  { name: "digest", heading: "Bitter", body: "Open Sans", mono: "Source Code Pro", description: "Substantial slab-serif headlines with neutral body.", categories: ["serif", "contrast", "editorial"], mood: ["reliable", "editorial"], useCase: ["newsletter", "blog", "content"] },
+  { name: "manifesto", heading: "Roboto Slab", body: "Roboto", mono: "Roboto Mono", description: "Complete Roboto system with slab authority.", categories: ["serif", "superfamily", "systematic"], mood: ["systematic", "professional"], useCase: ["enterprise", "Material Design", "documentation"] },
+  { name: "zine", heading: "PT Serif", body: "PT Sans", mono: "Inconsolata", description: "Authoritative serif/sans duo for publishing.", categories: ["serif", "superfamily", "universal"], mood: ["authoritative", "universal"], useCase: ["news", "publishing", "i18n"] },
+  { name: "impact", heading: "Fjalla One", body: "Josefin Sans", mono: "Fira Code", description: "Condensed power with art deco body character.", categories: ["display", "condensed", "bold"], mood: ["impactful", "commanding"], useCase: ["media", "sports", "marketing"] },
+  { name: "capsule", heading: "Montserrat", body: "Karla", mono: "JetBrains Mono", description: "Urban geometric headlines with warm body copy.", categories: ["sans-serif", "complementary", "urban"], mood: ["modern", "bold"], useCase: ["fashion", "retail", "branding"] },
+  { name: "beacon", heading: "Exo 2", body: "Titillium Web", mono: "Source Code Pro", description: "Futuristic geometry with technical readability.", categories: ["sans-serif", "geometric", "futuristic"], mood: ["futuristic", "technical"], useCase: ["tech", "space", "gaming"] },
+  { name: "manila", heading: "Barlow Condensed", body: "Barlow", mono: "IBM Plex Mono", description: "Condensed superfamily optimized for information density.", categories: ["sans-serif", "superfamily", "condensed"], mood: ["efficient", "modern"], useCase: ["dashboard", "data", "news"] },
+  { name: "memoir", heading: "Bitter", body: "Lora", mono: "Inconsolata", description: "Warm long-form serif pairing for story-heavy content.", categories: ["serif", "harmonious", "warm"], mood: ["warm", "narrative"], useCase: ["blog", "memoir", "longform"] },
+  { name: "folio", heading: "Josefin Sans", body: "Raleway", mono: "Roboto Mono", description: "Vintage geometry with elegant fashion-forward tone.", categories: ["sans-serif", "complementary", "elegant"], mood: ["elegant", "sophisticated"], useCase: ["portfolio", "fashion", "luxury"] },
+  { name: "commons", heading: "Cabin", body: "Mukta", mono: "Fira Code", description: "Inclusive humanist pairing across scripts.", categories: ["sans-serif", "complementary", "inclusive"], mood: ["approachable", "inclusive"], useCase: ["community", "nonprofit", "education"] },
+  { name: "protocol", heading: "Saira", body: "Ubuntu", mono: "IBM Plex Mono", description: "Distinctive technical pairing for dev-facing products.", categories: ["sans-serif", "complementary", "technical"], mood: ["technical", "distinctive"], useCase: ["developer tools", "Linux", "open source"] },
+  { name: "dispatch", heading: "Heebo", body: "Assistant", mono: "Source Code Pro", description: "Global communication pairing with script versatility.", categories: ["sans-serif", "complementary", "global"], mood: ["neutral", "inclusive"], useCase: ["i18n", "enterprise", "communication"] },
+  { name: "orbit", heading: "Space Grotesk", body: "Manrope", mono: "JetBrains Mono", description: "High-contrast geometric UI stack for product and docs surfaces.", categories: ["sans-serif", "geometric", "product"], mood: ["modern", "focused"], useCase: ["saas", "dashboard", "docs"] },
+  { name: "atlas", heading: "Merriweather Sans", body: "Inter", mono: "IBM Plex Mono", description: "Pragmatic structure with strong heading rhythm and neutral body copy.", categories: ["sans-serif", "structured", "readable"], mood: ["reliable", "calm"], useCase: ["knowledge base", "editorial", "platform"] },
+  { name: "forge", heading: "Barlow", body: "Noto Sans", mono: "Source Code Pro", description: "Industrial clarity for technical products and enterprise dashboards.", categories: ["sans-serif", "technical", "systematic"], mood: ["systematic", "precise"], useCase: ["enterprise", "admin", "ops"] },
+  { name: "canvas", heading: "Lora", body: "Figtree", mono: "Fira Code", description: "Expressive serif headlines balanced by soft geometric body text.", categories: ["serif", "contrast", "creative"], mood: ["expressive", "warm"], useCase: ["portfolio", "publishing", "studio"] },
+  { name: "signal", heading: "Inter Tight", body: "Public Sans", mono: "JetBrains Mono", description: "Dense information layout pair optimized for fast scanning.", categories: ["sans-serif", "neutral", "data"], mood: ["neutral", "efficient"], useCase: ["analytics", "monitoring", "newsroom"] },
+  { name: "northstar", heading: "Sora", body: "Mulish", mono: "IBM Plex Mono", description: "Balanced startup type system with clean hierarchy and stable rhythm.", categories: ["sans-serif", "complementary", "startup"], mood: ["clean", "confident"], useCase: ["landing page", "product", "marketing"] },
+  { name: "geist", heading: "Geist", body: "Inter", mono: "Geist Mono", description: "Geist for display, Inter for dense UI copy, Geist Mono for code—easy to spot in search and installs.", categories: ["sans-serif", "system", "developer"], mood: ["modern", "precise"], useCase: ["app", "dashboard", "docs"] },
+  { name: "workspace", heading: "Geist", body: "DM Sans", mono: "Geist Mono", description: "Geist headlines with DM Sans body and Geist Mono for snippets.", categories: ["sans-serif", "complementary", "product"], mood: ["modern", "friendly"], useCase: ["SaaS", "workspace", "marketing"] },
+];
+

package/cli/lib/add-utils.mjs

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "./fs-utils.mjs";
+
+export function isAstroProject(targetDir) {
+  const astroConfigCandidates = [
+    "astro.config.mjs",
+    "astro.config.js",
+    "astro.config.ts",
+    "astro.config.cjs",
+  ];
+  const hasConfig = astroConfigCandidates.some((file) =>
+    fs.existsSync(path.join(targetDir, file))
+  );
+  if (!hasConfig) return false;
+
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return false;
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+  return Boolean(
+    packageJson?.dependencies?.astro || packageJson?.devDependencies?.astro
+  );
+}
+
+export function buildFontImports(fontEntries) {
+  const lines = [];
+  for (const font of fontEntries) {
+    if (!font) continue;
+    if (font.font.provider === "npm" && font.font.npmPackage === "geist") {
+      if (font.name === "geist") lines.push('@import "geist/font/sans.css";');
+      if (font.name === "geist-mono") lines.push('@import "geist/font/mono.css";');
+      continue;
+    }
+    if (font.font.dependency) {
+      lines.push(`@import "${font.font.dependency}";`);
+      continue;
+    }
+    if (font.font.provider === "google") {
+      lines.push(
+        `@import url("https://fonts.googleapis.com/css2?family=${encodeURIComponent(
+          font.title
+        ).replace(/%20/g, "+")}:wght@400;500;600;700&display=swap");`
+      );
+    }
+  }
+  return [...new Set(lines)].join("\n");
+}
+
+export function ensureImport(globalCssPath, importLine) {
+  const css = fs.existsSync(globalCssPath) ? fs.readFileSync(globalCssPath, "utf-8") : "";
+  if (css.includes(importLine)) return;
+  fs.writeFileSync(globalCssPath, `${importLine}\n${css}`);
+}
+
+export function writeAstrotypeCss(targetDir, slug, cssText) {
+  const stylesDir = path.join(targetDir, "src", "styles", "astrotypes");
+  ensureDir(stylesDir);
+  const cssPath = path.join(stylesDir, `${slug}.css`);
+  fs.writeFileSync(cssPath, cssText);
+
+  const globalCssPath = path.join(targetDir, "src", "styles", "global.css");
+  ensureDir(path.dirname(globalCssPath));
+  ensureImport(globalCssPath, `@import "./astrotypes/${slug}.css";`);
+  return cssPath;
+}

package/cli/lib/fs-utils.mjs

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+
+export function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n");
+}
+
+export function listJsonFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  return fs
+    .readdirSync(dirPath)
+    .filter((name) => name.endsWith(".json"))
+    .sort();
+}
+
+export function readJsonDirectory(dirPath) {
+  return listJsonFiles(dirPath).map((fileName) =>
+    readJson(path.join(dirPath, fileName))
+  );
+}
+

package/cli/lib/paths.mjs

@@ -0,0 +1,17 @@
+import path from "node:path";
+
+export const PROJECT_ROOT = process.cwd();
+export const REGISTRY_DIR = path.join(PROJECT_ROOT, "registry");
+export const REGISTRY_FONTS_DIR = path.join(REGISTRY_DIR, "fonts");
+export const REGISTRY_PAIRINGS_DIR = path.join(REGISTRY_DIR, "pairings");
+export const PUBLIC_DIR = path.join(PROJECT_ROOT, "public");
+export const PUBLIC_REGISTRY_DIR = path.join(PUBLIC_DIR, "registry");
+export const GENERATED_DATA_DIR = path.join(PROJECT_ROOT, "src", "data");
+
+export function toKebab(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+

package/cli/lib/registry.mjs

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  REGISTRY_FONTS_DIR,
+  REGISTRY_PAIRINGS_DIR,
+} from "./paths.mjs";
+import { readJson, readJsonDirectory } from "./fs-utils.mjs";
+import { validateFontEntry, validatePairingEntry } from "./schema.mjs";
+
+export function getAllFonts() {
+  return readJsonDirectory(REGISTRY_FONTS_DIR);
+}
+
+export function getAllPairings() {
+  return readJsonDirectory(REGISTRY_PAIRINGS_DIR);
+}
+
+export function getFontByName(name) {
+  const normalized = String(name || "").replace(/^font-/, "");
+  const filePath = path.join(REGISTRY_FONTS_DIR, `${normalized}.json`);
+  if (fs.existsSync(filePath)) {
+    try {
+      return readJson(filePath);
+    } catch {
+      /* fall through */
+    }
+  }
+  for (const font of getAllFonts()) {
+    if (font.name === normalized) return font;
+    if (Array.isArray(font.aliases) && font.aliases.includes(normalized)) {
+      return font;
+    }
+  }
+  return null;
+}
+
+export function getPairingByName(name) {
+  const normalized = name.replace(/^pairing-/, "");
+  const filePath = path.join(REGISTRY_PAIRINGS_DIR, `${normalized}.json`);
+  if (fs.existsSync(filePath)) {
+    try {
+      return readJson(filePath);
+    } catch {
+      /* fall through */
+    }
+  }
+  for (const pairing of getAllPairings()) {
+    if (pairing.name === normalized) return pairing;
+    if (Array.isArray(pairing.aliases) && pairing.aliases.includes(normalized)) {
+      return pairing;
+    }
+  }
+  return null;
+}
+
+export function validateRegistry() {
+  const fontErrors = [];
+  const pairingErrors = [];
+  for (const font of getAllFonts()) {
+    const error = validateFontEntry(font);
+    if (error) fontErrors.push(`[font:${font?.name ?? "unknown"}] ${error}`);
+  }
+  for (const pairing of getAllPairings()) {
+    const error = validatePairingEntry(pairing);
+    if (error) pairingErrors.push(`[pairing:${pairing?.name ?? "unknown"}] ${error}`);
+  }
+  return { fontErrors, pairingErrors };
+}
+
+export function buildRegistryIndex(baseUrl) {
+  const fonts = getAllFonts();
+  const pairings = getAllPairings();
+  return {
+    generatedAt: new Date().toISOString(),
+    baseUrl,
+    fonts: fonts.map((font) => ({
+      name: font.name,
+      title: font.title,
+      provider: font.font.provider,
+      variable: font.font.variable,
+      url: `${baseUrl}/registry/${font.name}.json`,
+    })),
+    pairings: pairings.map((pairing) => ({
+      name: pairing.name,
+      title: pairing.title,
+      description: pairing.description,
+      category: pairing.category ?? null,
+      mood: pairing.meta?.mood ?? [],
+      useCase: pairing.meta?.useCase ?? [],
+      url: `${baseUrl}/registry/${pairing.name}.json`,
+    })),
+  };
+}
+

package/cli/lib/schema.mjs

@@ -0,0 +1,43 @@
+export function validateFontEntry(entry) {
+  if (!entry || typeof entry !== "object") return "Font entry must be an object";
+  if (entry.type !== "astrotypes:font") return "Font entry type must be astrotypes:font";
+  if (!entry.name || typeof entry.name !== "string") return "Font entry name is required";
+  if (!entry.title || typeof entry.title !== "string") return "Font entry title is required";
+  if (!entry.font || typeof entry.font !== "object") return "Font entry font block is required";
+  if (!entry.font.family || typeof entry.font.family !== "string") {
+    return "Font family is required";
+  }
+  if (!entry.font.variable || typeof entry.font.variable !== "string") {
+    return "Font variable is required";
+  }
+  if (!Array.isArray(entry.font.weight)) return "Font weight must be an array";
+  if (!Array.isArray(entry.font.subsets)) return "Font subsets must be an array";
+  return null;
+}
+
+export function validatePairingEntry(entry) {
+  if (!entry || typeof entry !== "object") return "Pairing entry must be an object";
+  if (entry.type !== "astrotypes:pairing") {
+    return "Pairing entry type must be astrotypes:pairing";
+  }
+  if (!entry.name || typeof entry.name !== "string") return "Pairing entry name is required";
+  if (!entry.title || typeof entry.title !== "string") return "Pairing title is required";
+  if (!entry.fonts || typeof entry.fonts !== "object") return "Pairing fonts block is required";
+  for (const key of ["heading", "body", "mono"]) {
+    if (!entry.fonts[key] || typeof entry.fonts[key] !== "string") {
+      return `Pairing fonts.${key} is required`;
+    }
+  }
+  if (!entry.tokens || typeof entry.tokens !== "object") return "Pairing tokens block is required";
+  if (entry.id !== undefined) {
+    if (typeof entry.id !== "string" || !entry.id.trim()) return "Pairing id must be a non-empty string";
+  }
+  if (entry.aliases !== undefined) {
+    if (!Array.isArray(entry.aliases)) return "Pairing aliases must be an array";
+    for (const a of entry.aliases) {
+      if (typeof a !== "string" || !a.trim()) return "Each pairing alias must be a non-empty string";
+    }
+  }
+  return null;
+}
+

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "astrotype",
+  "description": "Astro-first font registry and CLI for installing pairings or single fonts.",
+  "type": "module",
+  "version": "0.1.1",
+  "private": false,
+  "keywords": [
+    "astro",
+    "typography",
+    "fonts",
+    "font-pairing",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lexington-Themes/astrotypes.com.git"
+  },
+  "homepage": "https://github.com/Lexington-Themes/astrotypes.com#readme",
+  "bugs": {
+    "url": "https://github.com/Lexington-Themes/astrotypes.com/issues"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "registry/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "astrotypes": "./bin/astrotypes.mjs"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "npm run build:registry && astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "generate:fonts": "node ./bin/astrotypes.mjs generate:fonts",
+    "generate:candidates": "node ./bin/astrotypes.mjs generate:candidates",
+    "sync:pairings": "node ./bin/astrotypes.mjs sync:pairings",
+    "build:registry": "node ./bin/astrotypes.mjs build:registry",
+    "add:pairing": "node ./bin/astrotypes.mjs add"
+  },
+  "dependencies": {
+    "@astrojs/sitemap": "^3.7.1",
+    "@lexingtonthemes/seo": "^0.1.0",
+    "astro": "^6.0.6",
+    "reading-time": "^1.5.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "tailwindcss": "^4.1.18"
+  }
+}

package/registry/fonts/abeezee.json

@@ -0,0 +1,21 @@
+{
+  "name": "abeezee",
+  "type": "astrotypes:font",
+  "title": "ABeeZee",
+  "description": "ABeeZee font definition for Astrotypes.",
+  "category": "Sans Serif",
+  "font": {
+    "family": "ABeeZee Variable",
+    "provider": "google",
+    "import": "ABeeZee",
+    "variable": "--font-abeezee",
+    "weight": [
+      "400"
+    ],
+    "subsets": [
+      "menu",
+      "latin",
+      "latin-ext"
+    ]
+  }
+}

package/registry/fonts/abel.json

@@ -0,0 +1,20 @@
+{
+  "name": "abel",
+  "type": "astrotypes:font",
+  "title": "Abel",
+  "description": "Abel font definition for Astrotypes.",
+  "category": "Sans Serif",
+  "font": {
+    "family": "Abel Variable",
+    "provider": "google",
+    "import": "Abel",
+    "variable": "--font-abel",
+    "weight": [
+      "400"
+    ],
+    "subsets": [
+      "menu",
+      "latin"
+    ]
+  }
+}

package/registry/fonts/abhaya-libre.json

@@ -0,0 +1,26 @@
+{
+  "name": "abhaya-libre",
+  "type": "astrotypes:font",
+  "title": "Abhaya Libre",
+  "description": "Abhaya Libre font definition for Astrotypes.",
+  "category": "Serif",
+  "font": {
+    "family": "Abhaya Libre Variable",
+    "provider": "google",
+    "import": "Abhaya_Libre",
+    "variable": "--font-abhaya-libre",
+    "weight": [
+      "400",
+      "500",
+      "600",
+      "700",
+      "800"
+    ],
+    "subsets": [
+      "menu",
+      "latin",
+      "latin-ext",
+      "sinhala"
+    ]
+  }
+}