@3xhaust/oh-my-design 0.16.1

package/core/source-seal/index.ts

@@ -0,0 +1,174 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+
+export const SOURCE_SEAL_SCHEMA_VERSION = 1;
+
+const SOURCE_EXTENSIONS = new Set([
+  '.astro', '.cjs', '.css', '.gif', '.html', '.ico', '.jpeg', '.jpg', '.js', '.json',
+  '.jsx', '.less', '.mjs', '.otf', '.png', '.sass', '.scss', '.svg', '.svelte', '.ts',
+  '.tsx', '.ttf', '.vue', '.wasm', '.webp', '.woff', '.woff2',
+]);
+
+const EXCLUDED_DIRECTORIES = new Set([
+  '.cache', '.git', '.next', '.nuxt', '.omd', '.output', '.svelte-kit',
+  '__tests__', 'build', 'cache', 'coverage', 'dist', 'e2e', 'generated',
+  'node_modules', 'out', 'temp', 'test', 'tests', 'tmp', 'vendor',
+]);
+
+const EXCLUDED_FILES = new Set([
+  'bun.lock', 'bun.lockb', 'npm-shrinkwrap.json', 'package-lock.json', 'pnpm-lock.yaml',
+  'yarn.lock',
+]);
+
+export interface SourceSealArtifact {
+  schemaVersion: 1;
+  sealedAt: string;
+  inputs: {
+    copyDeckSha256: string;
+    typeProofSha256: string;
+    compositionSha256: string;
+  };
+  sources: Array<{ path: string; sha256: string }>;
+}
+
+export interface SourceSealFinding {
+  id: 'SOURCE-SEAL-MISSING' | 'SOURCE-SEAL-STALE';
+  path: string;
+  message: string;
+}
+
+const hashBytes = (bytes: Buffer | string): string => createHash('sha256').update(bytes).digest('hex');
+const slash = (path: string): string => path.split(sep).join('/');
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isSafeSourcePath(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length === 0 || value.includes('\\') || value.includes('\0')) return false;
+  if (value.startsWith('/') || /^[A-Za-z]:\//.test(value)) return false;
+  return value.split('/').every((segment) => segment.length > 0 && segment !== '.' && segment !== '..');
+}
+
+function isSourceSealArtifact(value: unknown): value is SourceSealArtifact {
+  if (!isRecord(value) || value.schemaVersion !== SOURCE_SEAL_SCHEMA_VERSION || typeof value.sealedAt !== 'string') return false;
+  if (!isRecord(value.inputs) || !Array.isArray(value.sources)) return false;
+  for (const key of ['copyDeckSha256', 'typeProofSha256', 'compositionSha256'] as const) {
+    if (typeof value.inputs[key] !== 'string' || !SHA256_PATTERN.test(value.inputs[key])) return false;
+  }
+  return value.sources.every((item) => (
+    isRecord(item)
+    && isSafeSourcePath(item.path)
+    && typeof item.sha256 === 'string'
+    && SHA256_PATTERN.test(item.sha256)
+  ));
+}
+
+export function listProductionSourceFiles(rootInput: string): string[] {
+  const root = resolve(rootInput);
+  const files: string[] = [];
+  const walk = (directory: string): void => {
+    const entries = readdirSync(directory, { withFileTypes: true })
+      .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const absolute = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith('.') || EXCLUDED_DIRECTORIES.has(entry.name)) continue;
+        walk(absolute);
+        continue;
+      }
+      if (!entry.isFile() || EXCLUDED_FILES.has(entry.name.toLowerCase())) continue;
+      if (!SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
+      files.push(slash(relative(root, absolute)));
+    }
+  };
+  walk(root);
+  return files.sort();
+}
+
+function inputHashes(root: string): SourceSealArtifact['inputs'] {
+  const omd = join(root, '.omd');
+  const required = [
+    ['copyDeckSha256', 'copy-deck.md'],
+    ['typeProofSha256', 'type-proof.md'],
+    ['compositionSha256', 'composition.md'],
+  ] as const;
+  const values: Partial<SourceSealArtifact['inputs']> = {};
+  for (const [key, filename] of required) {
+    const path = join(omd, filename);
+    if (!existsSync(path)) throw new Error(`cannot seal source: missing .omd/${filename}`);
+    values[key] = hashBytes(readFileSync(path));
+  }
+  return values as SourceSealArtifact['inputs'];
+}
+
+export function createSourceSeal(rootInput: string, sealedAt = new Date().toISOString()): SourceSealArtifact {
+  const root = resolve(rootInput);
+  const stat = lstatSync(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`source root must be a non-symlink directory: ${root}`);
+  return {
+    schemaVersion: SOURCE_SEAL_SCHEMA_VERSION,
+    sealedAt,
+    inputs: inputHashes(root),
+    sources: listProductionSourceFiles(root).map((path) => ({
+      path,
+      sha256: hashBytes(readFileSync(join(root, path))),
+    })),
+  };
+}
+
+export function writeSourceSeal(rootInput: string): string {
+  const root = resolve(rootInput);
+  const path = join(root, '.omd', 'source-seal.json');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(createSourceSeal(root), null, 2)}\n`);
+  return path;
+}
+
+export function validateSourceSeal(rootInput: string): SourceSealFinding[] {
+  const root = resolve(rootInput);
+  const path = join(root, '.omd', 'source-seal.json');
+  if (!existsSync(path)) {
+    return [{ id: 'SOURCE-SEAL-MISSING', path: '.omd/source-seal.json', message: 'source seal is missing' }];
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch {
+    return [{ id: 'SOURCE-SEAL-STALE', path: '.omd/source-seal.json', message: 'source seal is not valid JSON' }];
+  }
+  if (!isSourceSealArtifact(parsed)) {
+    return [{ id: 'SOURCE-SEAL-STALE', path: '.omd/source-seal.json', message: 'source seal schema is invalid' }];
+  }
+  const sealed = parsed;
+
+  let current: SourceSealArtifact;
+  try {
+    current = createSourceSeal(root, sealed.sealedAt);
+  } catch (error) {
+    return [{ id: 'SOURCE-SEAL-STALE', path: '.omd/source-seal.json', message: error instanceof Error ? error.message : String(error) }];
+  }
+  const findings: SourceSealFinding[] = [];
+  for (const [key, filename] of [
+    ['copyDeckSha256', 'copy-deck.md'],
+    ['typeProofSha256', 'type-proof.md'],
+    ['compositionSha256', 'composition.md'],
+  ] as const) {
+    if (sealed.inputs[key] !== current.inputs[key]) {
+      findings.push({ id: 'SOURCE-SEAL-STALE', path: `.omd/${filename}`, message: `${filename} changed after source seal` });
+    }
+  }
+
+  const sealedSources = new Map(sealed.sources.map((item) => [item.path, item.sha256]));
+  const currentSources = new Map(current.sources.map((item) => [item.path, item.sha256]));
+  for (const sourcePath of [...new Set([...sealedSources.keys(), ...currentSources.keys()])].sort()) {
+    if (sealedSources.get(sourcePath) !== currentSources.get(sourcePath)) {
+      findings.push({ id: 'SOURCE-SEAL-STALE', path: sourcePath, message: `${sourcePath} was added, removed, or changed after source seal` });
+    }
+  }
+  return findings.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}

package/core/stack/index.ts

@@ -0,0 +1,53 @@
+import { discoverEvidence } from '../design/index.ts';
+
+/**
+ * Deterministic stack routing. The agents repeatedly misread a folder — treating a truly blank
+ * greenfield, or their own leftover `index.html`, as "an existing vanilla-HTML project" and dropping
+ * to plain HTML. This computes the stack from folder evidence so the model does not have to judge it:
+ * the tool measures, the model builds exactly what it names. The only lawful override to plain HTML on
+ * a greenfield is a verbatim explicit user request, recorded via `omd decision`.
+ */
+export interface StackDecision {
+  stack: 'react-vite-typescript' | 'existing' | 'plain-html-css-js';
+  framework: string | null;
+  greenfield: boolean;
+  /** Whether a plain-HTML choice is even permitted here (only on a blank greenfield, with an explicit request). */
+  htmlOverrideAllowed: boolean;
+  reason: string;
+}
+
+export function computeStack(cwd: string): StackDecision {
+  const ev = discoverEvidence(cwd);
+
+  if (ev.hasPackageJson && ev.framework) {
+    return {
+      stack: 'existing',
+      framework: ev.framework,
+      greenfield: false,
+      htmlOverrideAllowed: false,
+      reason: `existing ${ev.framework} project (package.json) — build in it and add no unnecessary dependencies`,
+    };
+  }
+
+  if (ev.hasPackageJson || ev.appEvidencePaths.length > 0) {
+    const marker = ev.hasPackageJson ? 'package.json' : ev.appEvidencePaths[0]!;
+    return {
+      stack: 'existing',
+      framework: ev.framework,
+      greenfield: false,
+      htmlOverrideAllowed: false,
+      reason: `existing toolchain (${marker}) — preserve and investigate it, never cover it with a React scaffold`,
+    };
+  }
+
+  return {
+    stack: 'react-vite-typescript',
+    framework: null,
+    greenfield: true,
+    htmlOverrideAllowed: true,
+    reason:
+      'truly blank greenfield (no package.json, no build config) — default to React + Vite + TypeScript. '
+      + 'A loose leftover index.html/.css/.js is NOT an existing stack, and one static page is no reason to drop '
+      + 'to plain HTML. Emit plain HTML/CSS/JS only on a verbatim explicit user request, recorded via omd decision.',
+  };
+}

package/core/target/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Visual target loop — RE-C (일반 시각 타깃 루프).
+ *
+ * Generalises the Figma pixel-diff loop to work against ANY image reference —
+ * a mockup, a screenshot, a live-URL render — so "make it look like this picture"
+ * becomes a measured convergence loop.
+ *
+ * ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────
+ *
+ * An LLM judges spatial layout poorly by eye. Telling a model "make the hero taller"
+ * or "the padding looks off" requires the model to estimate pixel distances from
+ * a render it has never measured. The pixel diff replaces that eyeballing with
+ * numbers: a score (0–1), a pass/fail decision at a threshold, and a 6×6 grid
+ * that names the worst-mismatch cells so each iteration targets a specific region
+ * rather than re-guessing the whole layout.
+ *
+ * ── REUSE ───────────────────────────────────────────────────────────────────────
+ *
+ * This module reuses two existing in-repo primitives:
+ *
+ *   - `compareImages` from `core/figma/diff.ts`   — diff math + grid logic
+ *   - `formatDiffReport` from `core/figma/diff.ts` — human-readable grid report
+ *   - `decodePng` from `core/motion/energy.ts`     — PNG decoder (no new dep)
+ *
+ * The `DiffResult` / `DiffCell` types are re-exported so callers never depend on
+ * the figma module path directly.
+ *
+ * ── JSON CONTRACT ────────────────────────────────────────────────────────────────
+ *
+ * `compareAgainstTarget` returns the same `DiffResult` shape as `compareImages`
+ * so `--json` output and loop drivers work identically for both figma diff and
+ * target diff:
+ *
+ *   {
+ *     score:     number,          // 0–1, fraction of "same" pixels
+ *     threshold: number,
+ *     pass:      boolean,
+ *     cells: [{ row, col, x, y, width, height, mismatch }],
+ *     dimMismatch?: { refWidth, refHeight, buildWidth, buildHeight,
+ *                     overlapWidth, overlapHeight }
+ *   }
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { decodePng } from '../motion/energy.ts';
+import { compareImages, formatDiffReport } from '../figma/diff.ts';
+
+// ── Re-exports (stable contract) ─────────────────────────────────────────────
+
+export type { DiffResult, DiffCell } from '../figma/diff.ts';
+export { compareImages, formatDiffReport } from '../figma/diff.ts';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface TargetViewport {
+  width: number;
+  height: number;
+}
+
+/** One entry in the target manifest. */
+export interface TargetEntry {
+  /** Human-readable name used with `--target <name>`. */
+  name: string;
+  /** Original source: a file path or a URL. */
+  source: string;
+  /** Absolute path to the stored PNG inside `.omd/target/`. */
+  path: string;
+  /** Dimensions decoded from the target PNG — used as the render viewport. */
+  viewport: TargetViewport;
+  registeredAt: string;
+}
+
+interface TargetManifest {
+  targets: TargetEntry[];
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function targetDir(cwd: string): string {
+  return join(cwd, '.omd', 'target');
+}
+
+function manifestPath(cwd: string): string {
+  return join(targetDir(cwd), 'manifest.json');
+}
+
+function loadManifest(cwd: string): TargetManifest {
+  const p = manifestPath(cwd);
+  if (!existsSync(p)) return { targets: [] };
+  return JSON.parse(readFileSync(p, 'utf8')) as TargetManifest;
+}
+
+function saveManifest(cwd: string, manifest: TargetManifest): void {
+  mkdirSync(targetDir(cwd), { recursive: true });
+  writeFileSync(manifestPath(cwd), JSON.stringify(manifest, null, 2));
+}
+
+/** Sanitise a target name into a safe file basename. */
+export function safeName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Register a PNG buffer as a named visual target.
+ *
+ * Decodes the buffer to read its dimensions (the intended render viewport),
+ * writes the PNG to `.omd/target/<safeName>.png`, and upserts the manifest.
+ *
+ * @param cwd    Project working directory (`.omd/` is created here).
+ * @param name   Human-readable target name (used with `--target <name>`).
+ * @param source Original source identifier (URL or file path) — stored for reference.
+ * @param buf    Valid PNG buffer.
+ */
+export function registerTarget(
+  cwd: string,
+  name: string,
+  source: string,
+  buf: Buffer,
+): TargetEntry {
+  const dir = targetDir(cwd);
+  mkdirSync(dir, { recursive: true });
+
+  const pngPath = join(dir, `${safeName(name)}.png`);
+  writeFileSync(pngPath, buf);
+
+  // Decode to get dimensions — decodePng from core/motion/energy.ts, no new dep.
+  const { width, height } = decodePng(buf);
+
+  const entry: TargetEntry = {
+    name,
+    source,
+    path: pngPath,
+    viewport: { width, height },
+    registeredAt: new Date().toISOString(),
+  };
+
+  const manifest = loadManifest(cwd);
+  const idx = manifest.targets.findIndex((t) => t.name === name);
+  if (idx >= 0) {
+    manifest.targets[idx] = entry;
+  } else {
+    manifest.targets.push(entry);
+  }
+  saveManifest(cwd, manifest);
+
+  return entry;
+}
+
+/** Return all registered targets for the project at `cwd`. */
+export function listTargets(cwd: string): TargetEntry[] {
+  return loadManifest(cwd).targets;
+}
+
+/**
+ * Look up one registered target by name.
+ * Returns `undefined` when no target with that name has been registered.
+ */
+export function findTarget(cwd: string, name: string): TargetEntry | undefined {
+  return loadManifest(cwd).targets.find((t) => t.name === name);
+}
+
+/**
+ * Compare a build PNG buffer against a target PNG buffer.
+ *
+ * Pure wrapper around `compareImages` from `core/figma/diff.ts` — same
+ * algorithm, same JSON contract, same tolerance constants. The `DiffResult`
+ * returned here is bitwise-identical to what `omd figma diff` would produce
+ * for the same pair of images.
+ *
+ * @param targetBuf  Reference PNG (the registered visual target).
+ * @param buildBuf   Build render PNG (the "actual" to be improved).
+ * @param threshold  Pass/fail threshold (0–1, default 0.97).
+ */
+export function compareAgainstTarget(
+  targetBuf: Buffer,
+  buildBuf: Buffer,
+  threshold = 0.97,
+): ReturnType<typeof compareImages> {
+  return compareImages(targetBuf, buildBuf, threshold);
+}