@whittakertech/virgil 0.1.0

package/src/engine/lock.ts

@@ -0,0 +1,72 @@
+import { readFile, writeFile } from 'fs/promises';
+import { VirgilLock, LockEntry } from '../types/lock.js';
+
+const LOCK_VERSION = '0.1' as const;
+
+/**
+ * Load lock file if it exists, return empty lock otherwise
+ */
+export async function loadLock(lockPath: string): Promise<VirgilLock> {
+  try {
+    const contents = await readFile(lockPath, 'utf-8');
+    return JSON.parse(contents);
+  } catch (err) {
+    // Lock doesn't exist or is invalid - start fresh
+    return {
+      version: LOCK_VERSION,
+      entries: {}
+    };
+  }
+}
+
+/**
+ * Write lock file atomically
+ */
+export async function saveLock(lockPath: string, lock: VirgilLock): Promise<void> {
+  const contents = JSON.stringify(lock, null, 2);
+  
+  // Write to temp file, then rename (atomic on POSIX)
+  const tempPath = `${lockPath}.tmp`;
+  await writeFile(tempPath, contents, 'utf-8');
+  
+  // Atomic rename
+  const { rename } = await import('fs/promises');
+  await rename(tempPath, lockPath);
+}
+
+/**
+ * Check if output needs regeneration
+ */
+export function needsRegeneration(
+  lock: VirgilLock,
+  id: string,
+  currentHash: string
+): boolean {
+  const entry = lock.entries[id];
+  
+  if (!entry) {
+    // Never generated before
+    return true;
+  }
+  
+  // Compare hashes
+  return entry.hash !== currentHash;
+}
+
+/**
+ * Update lock entry
+ */
+export function updateLockEntry(
+  lock: VirgilLock,
+  id: string,
+  hash: string,
+  generator: string,
+  generatorVersion: string
+): void {
+  lock.entries[id] = {
+    hash,
+    generatedAt: new Date().toISOString(),
+    generator,
+    generatorVersion
+  };
+}

package/src/engine/manifest.ts

@@ -0,0 +1,52 @@
+import { readFile, writeFile } from 'fs/promises';
+import { VirgilManifest } from '../types/manifest.js';
+
+const MANIFEST_VERSION = '0.1' as const;
+
+/**
+ * Load manifest if it exists, return empty manifest otherwise
+ */
+export async function loadManifest(manifestPath: string): Promise<VirgilManifest> {
+  try {
+    const contents = await readFile(manifestPath, 'utf-8');
+    return JSON.parse(contents);
+  } catch (err) {
+    return {
+      version: MANIFEST_VERSION,
+      og: {},
+      sitemap: {},
+      robots: {}
+    };
+  }
+}
+
+/**
+ * Write manifest atomically
+ */
+export async function saveManifest(
+  manifestPath: string,
+  manifest: VirgilManifest
+): Promise<void> {
+  const contents = JSON.stringify(manifest, null, 2);
+  
+  const tempPath = `${manifestPath}.tmp`;
+  await writeFile(tempPath, contents, 'utf-8');
+  
+  const { rename } = await import('fs/promises');
+  await rename(tempPath, manifestPath);
+}
+
+/**
+ * Update manifest entry for given output type
+ */
+export function updateManifestEntry(
+  manifest: VirgilManifest,
+  type: 'og' | 'sitemap' | 'robots',
+  id: string,
+  path: string
+): void {
+  if (!manifest[type]) {
+    manifest[type] = {};
+  }
+  manifest[type]![id] = path;
+}

package/src/engine/run.ts

@@ -0,0 +1,156 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { VirgilSpec, OutputConfig } from '../types/spec.js';
+import { VirgilLock } from '../types/lock.js';
+import { VirgilManifest } from '../types/manifest.js';
+import { PathResolver } from '../utils/paths.js';
+import { computeHash, GENERATOR_VERSION } from './hash.js';
+import { loadLock, saveLock, needsRegeneration, updateLockEntry } from './lock.js';
+import { loadManifest, saveManifest, updateManifestEntry } from './manifest.js';
+import { generateOGImage, generateOGImageFilename } from '../generators/og-image.js';
+import { generateSitemap } from '../generators/sitemap.js';
+import { generateRobots } from '../generators/robots.js';
+
+export interface RunOptions {
+  rootDir: string;
+  outputDir: string;
+  verbose?: boolean;
+}
+
+export interface RunResult {
+  generated: number;
+  skipped: number;
+  errors: string[];
+}
+
+/**
+ * Main orchestration - this is the heart of Virgil
+ */
+export async function run(options: RunOptions): Promise<RunResult> {
+  const paths = new PathResolver(options.rootDir);
+  const result: RunResult = {
+    generated: 0,
+    skipped: 0,
+    errors: []
+  };
+
+  try {
+    // Step 1: Load spec
+    const specContents = await readFile(paths.spec, 'utf-8');
+    const spec: VirgilSpec = JSON.parse(specContents);
+
+    if (options.verbose) {
+      console.log(`📋 Loaded spec with ${spec.outputs.length} outputs`);
+    }
+
+    // Step 2: Load previous lock
+    const lock = await loadLock(paths.lock);
+
+    // Step 3: Load manifest
+    const manifest = await loadManifest(paths.manifest);
+
+    // Step 4-7: Process each output
+    for (const output of spec.outputs) {
+      try {
+        await processOutput(spec, output, lock, manifest, options, result);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        result.errors.push(`${output.id}: ${message}`);
+      }
+    }
+
+    // Step 8: Write updated lock
+    await saveLock(paths.lock, lock);
+
+    // Step 9: Write updated manifest
+    await saveManifest(paths.manifest, manifest);
+
+    if (options.verbose) {
+      console.log(`✅ Generated: ${result.generated}, Skipped: ${result.skipped}, Errors: ${result.errors.length}`);
+    }
+
+    return result;
+
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    result.errors.push(`Fatal: ${message}`);
+    return result;
+  }
+}
+
+async function processOutput(
+  spec: VirgilSpec,
+  output: OutputConfig,
+  lock: VirgilLock,
+  manifest: VirgilManifest,
+  options: RunOptions,
+  result: RunResult
+): Promise<void> {
+  // Compute current hash
+  const hash = await computeHash({
+    data: output,
+    generatorName: output.type
+  });
+
+  // Check if regeneration needed
+  if (!needsRegeneration(lock, output.id, hash)) {
+    if (options.verbose) {
+      console.log(`⏭️  Skipping ${output.id} (unchanged)`);
+    }
+    result.skipped++;
+    return;
+  }
+
+  if (options.verbose) {
+    console.log(`🔨 Generating ${output.id}`);
+  }
+
+  // Generate based on type
+  let outputPath: string;
+  let manifestPath: string;
+
+  switch (output.type) {
+    case 'og-image': {
+      const filename = generateOGImageFilename(output.id);
+      outputPath = join(options.outputDir, 'og', filename);
+      manifestPath = `/og/${filename}`;
+
+      await generateOGImage(
+        {
+          brand: spec.brand,
+          product: spec.product,
+          output
+        },
+        outputPath
+      );
+
+      updateManifestEntry(manifest, 'og', output.id, manifestPath);
+      break;
+    }
+
+    case 'sitemap': {
+      outputPath = join(options.outputDir, 'sitemap.xml');
+      manifestPath = '/sitemap.xml';
+
+      await generateSitemap({ output }, outputPath);
+      updateManifestEntry(manifest, 'sitemap', output.id, manifestPath);
+      break;
+    }
+
+    case 'robots': {
+      outputPath = join(options.outputDir, 'robots.txt');
+      manifestPath = '/robots.txt';
+
+      await generateRobots({ output }, outputPath);
+      updateManifestEntry(manifest, 'robots', output.id, manifestPath);
+      break;
+    }
+
+    default:
+      throw new Error(`Unknown output type: ${(output as any).type}`);
+  }
+
+  // Update lock
+  updateLockEntry(lock, output.id, hash, output.type, GENERATOR_VERSION);
+  result.generated++;
+}

package/src/generators/og-image.ts

@@ -0,0 +1,65 @@
+import { chromium } from 'playwright';
+import { readFile, writeFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { OGImageOutput, BrandConfig, ProductConfig } from '../types/spec.js';
+import { ensureParentDir } from '../utils/fs.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export interface OGImageContext {
+  brand: BrandConfig;
+  product: ProductConfig;
+  output: OGImageOutput;
+  templatePath?: string;
+}
+
+/**
+ * Generate OG image using Playwright
+ */
+export async function generateOGImage(
+  ctx: OGImageContext,
+  outputPath: string
+): Promise<void> {
+  // Load template
+  const templatePath = ctx.templatePath || join(__dirname, '../templates/og-default.html');
+  let html = await readFile(templatePath, 'utf-8');
+
+  // Replace placeholders
+  html = html
+    .replace(/{{brand.name}}/g, ctx.brand.name)
+    .replace(/{{brand.color}}/g, ctx.brand.color)
+    .replace(/{{product.name}}/g, ctx.product.name)
+    .replace(/{{product.version}}/g, ctx.product.version)
+    .replace(/{{page.title}}/g, ctx.output.page.title)
+    .replace(/{{page.url}}/g, ctx.output.page.url)
+    .replace(/{{page.description}}/g, ctx.output.page.description || '');
+
+  // Launch headless browser
+  const browser = await chromium.launch();
+  const page = await browser.newPage({
+    viewport: { width: 1200, height: 630 }
+  });
+
+  // Set content and wait for fonts/assets
+  await page.setContent(html, { waitUntil: 'networkidle' });
+
+  // Ensure output directory exists
+  await ensureParentDir(outputPath);
+
+  // Screenshot
+  await page.screenshot({
+    path: outputPath,
+    type: 'png'
+  });
+
+  await browser.close();
+}
+
+/**
+ * Generate filename for OG image with cache-busting timestamp
+ */
+export function generateOGImageFilename(id: string): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+  return `${id}.${timestamp}.png`;
+}

package/src/generators/robots.ts

@@ -0,0 +1,44 @@
+import { writeFile } from 'fs/promises';
+import { RobotsOutput } from '../types/spec.js';
+import { ensureParentDir } from '../utils/fs.js';
+
+export interface RobotsContext {
+  output: RobotsOutput;
+}
+
+/**
+ * Generate robots.txt
+ */
+export async function generateRobots(
+  ctx: RobotsContext,
+  outputPath: string
+): Promise<void> {
+  const lines: string[] = [];
+
+  for (const rule of ctx.output.rules) {
+    lines.push(`User-agent: ${rule.userAgent}`);
+
+    if (rule.allow) {
+      for (const path of rule.allow) {
+        lines.push(`Allow: ${path}`);
+      }
+    }
+
+    if (rule.disallow) {
+      for (const path of rule.disallow) {
+        lines.push(`Disallow: ${path}`);
+      }
+    }
+
+    lines.push(''); // Blank line between rules
+  }
+
+  if (ctx.output.sitemap) {
+    lines.push(`Sitemap: ${ctx.output.sitemap}`);
+  }
+
+  const content = lines.join('\n');
+
+  await ensureParentDir(outputPath);
+  await writeFile(outputPath, content, 'utf-8');
+}

package/src/generators/sitemap.ts

@@ -0,0 +1,36 @@
+import { writeFile } from 'fs/promises';
+import { SitemapOutput } from '../types/spec.js';
+import { ensureParentDir } from '../utils/fs.js';
+
+export interface SitemapContext {
+  output: SitemapOutput;
+}
+
+/**
+ * Generate sitemap.xml
+ */
+export async function generateSitemap(
+  ctx: SitemapContext,
+  outputPath: string
+): Promise<void> {
+  const { baseUrl, pages } = ctx.output;
+
+  const urls = pages.map(page => {
+    const loc = `${baseUrl}${page.path}`;
+    const lastmod = page.lastmod ? `<lastmod>${page.lastmod}</lastmod>` : '';
+    const changefreq = page.changefreq ? `<changefreq>${page.changefreq}</changefreq>` : '';
+    const priority = page.priority !== undefined ? `<priority>${page.priority}</priority>` : '';
+
+    return `  <url>
+    <loc>${loc}</loc>${lastmod}${changefreq}${priority}
+  </url>`;
+  }).join('\n');
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+
+  await ensureParentDir(outputPath);
+  await writeFile(outputPath, xml, 'utf-8');
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { run } from './engine/run.js';
+export { computeHash, hashFile } from './engine/hash.js';
+export { loadLock, saveLock } from './engine/lock.js';
+export { loadManifest, saveManifest } from './engine/manifest.js';
+
+export type { VirgilSpec, OutputConfig } from './types/spec.js';
+export type { VirgilLock, LockEntry } from './types/lock.js';
+export type { VirgilManifest } from './types/manifest.js';

package/src/templates/og-default.html

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      width: 1200px;
+      height: 630px;
+      background: linear-gradient(135deg, {{brand.color}} 0%, #1a1a2e 100%);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      padding: 60px;
+    }
+
+    .container {
+      width: 100%;
+      height: 100%;
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+      color: white;
+    }
+
+    .header {
+      display: flex;
+      align-items: center;
+      gap: 20px;
+    }
+
+    .brand {
+      font-size: 24px;
+      font-weight: 600;
+      opacity: 0.9;
+    }
+
+    .content {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+    }
+
+    .title {
+      font-size: 72px;
+      font-weight: 700;
+      line-height: 1.2;
+      margin-bottom: 20px;
+    }
+
+    .description {
+      font-size: 28px;
+      opacity: 0.8;
+      line-height: 1.4;
+    }
+
+    .footer {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      font-size: 20px;
+      opacity: 0.7;
+    }
+
+    .product {
+      font-weight: 600;
+    }
+
+    .version {
+      background: rgba(255, 255, 255, 0.2);
+      padding: 4px 12px;
+      border-radius: 4px;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <div class="brand">{{brand.name}}</div>
+    </div>
+
+    <div class="content">
+      <div class="title">{{page.title}}</div>
+      <div class="description">{{page.description}}</div>
+    </div>
+
+    <div class="footer">
+      <div class="product">{{product.name}}</div>
+      <div class="version">v{{product.version}}</div>
+    </div>
+  </div>
+</body>
+</html>

package/src/types/lock.ts

@@ -0,0 +1,11 @@
+export interface VirgilLock {
+  version: '0.1';
+  entries: Record<string, LockEntry>;
+}
+
+export interface LockEntry {
+  hash: string;
+  generatedAt: string;
+  generator: string;
+  generatorVersion: string;
+}

package/src/types/manifest.ts

@@ -0,0 +1,6 @@
+export interface VirgilManifest {
+  version: '0.1';
+  og?: Record<string, string>;
+  sitemap?: Record<string, string>;
+  robots?: Record<string, string>;
+}

package/src/types/spec.ts

@@ -0,0 +1,52 @@
+export interface VirgilSpec {
+  brand: BrandConfig;
+  product: ProductConfig;
+  outputs: OutputConfig[];
+}
+
+export interface BrandConfig {
+  name: string;
+  logo: string;
+  color: string;
+}
+
+export interface ProductConfig {
+  name: string;
+  logo: string;
+  version: string;
+}
+
+export type OutputConfig = OGImageOutput | SitemapOutput | RobotsOutput;
+
+export interface OGImageOutput {
+  type: 'og-image';
+  id: string;
+  page: {
+    title: string;
+    url: string;
+    description?: string;
+  };
+}
+
+export interface SitemapOutput {
+  type: 'sitemap';
+  id: string;
+  baseUrl: string;
+  pages: Array<{
+    path: string;
+    lastmod?: string;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+  }>;
+}
+
+export interface RobotsOutput {
+  type: 'robots';
+  id: string;
+  rules: Array<{
+    userAgent: string;
+    allow?: string[];
+    disallow?: string[];
+  }>;
+  sitemap?: string;
+}

package/src/utils/fs.ts

@@ -0,0 +1,32 @@
+import { mkdir, access } from 'fs/promises';
+import { dirname } from 'path';
+
+/**
+ * Ensure directory exists, create if needed
+ */
+export async function ensureDir(dirPath: string): Promise<void> {
+  try {
+    await access(dirPath);
+  } catch {
+    await mkdir(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Ensure parent directory exists for a file path
+ */
+export async function ensureParentDir(filePath: string): Promise<void> {
+  await ensureDir(dirname(filePath));
+}
+
+/**
+ * Check if file exists
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/paths.ts

@@ -0,0 +1,33 @@
+import { resolve, join, relative } from 'path';
+
+/**
+ * Resolve paths relative to project root
+ */
+export class PathResolver {
+  constructor(private rootDir: string) {}
+
+  resolve(...segments: string[]): string {
+    return resolve(this.rootDir, ...segments);
+  }
+
+  join(...segments: string[]): string {
+    return join(this.rootDir, ...segments);
+  }
+
+  relative(from: string, to: string): string {
+    return relative(from, to);
+  }
+
+  // Standard Virgil paths
+  get spec(): string {
+    return this.resolve('virgil.spec.json');
+  }
+
+  get lock(): string {
+    return this.resolve('virgil.lock.json');
+  }
+
+  get manifest(): string {
+    return this.resolve('virgil.manifest.json');
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}