@creativeintelligence/abbie 0.1.0

package/src/lib/references.ts

@@ -0,0 +1,481 @@
+/**
+ * Reference bank management for design and implementation references.
+ *
+ * Storage: ~/.abbie/refs/{web,ios,android}/{name}/
+ * Each reference contains:
+ * - reference.json (manifest)
+ * - AUDIT.md (analysis from www-audit)
+ * - repo/ (optional cloned repository)
+ * - screenshots/ (optional visual references)
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type ReferenceType = "web" | "ios" | "android";
+
+export interface ReferenceStack {
+  framework?: string;
+  version?: string;
+  styling?: string;
+  language?: string;
+  hosting?: string;
+  [key: string]: string | undefined;
+}
+
+export interface ReferenceGist {
+  /** Gist URL for AUDIT.md (main index) */
+  auditUrl?: string;
+  /** Legacy: single screenshots gist */
+  screenshotsUrl?: string;
+  /** Screenshots gists (ref-add v2) */
+  desktopScreenshotsUrl?: string;
+  mobileScreenshotsUrl?: string;
+  /** Specialist gist URLs (ref-add v2) */
+  specialists?: Record<string, string>;
+  /** When gist(s) were created */
+  createdAt?: string;
+}
+
+export interface ReferenceExtract {
+  id: string;
+  thing: string;
+  url: string;
+  created: string;
+  updated?: string;
+  notes?: string;
+  gist?: {
+    url?: string;
+    desktopScreenshotsUrl?: string;
+    mobileScreenshotsUrl?: string;
+    createdAt?: string;
+  };
+}
+
+export interface Reference {
+  name: string;
+  domain?: string;
+  url: string;
+  type: ReferenceType;
+  created: string;
+  updated?: string;
+  repo?: string;
+  stack?: ReferenceStack;
+  patterns?: string[];
+  tags?: string[];
+  notes?: string;
+  ecosystem?: string[];
+  pages?: Record<string, string>;
+  colors?: Record<string, string>;
+  screenshots?: Record<string, number>;
+  gist?: ReferenceGist; // GitHub gist links for rendered markdown/media
+  extracts?: ReferenceExtract[];
+  /** Date-only string for the last audit (YYYY-MM-DD). */
+  audit_date?: string;
+  /** Numeric confidence (0-10) from the audit. */
+  audit_confidence?: number;
+  /** Who/what produced the audit (e.g., "ref-add"). */
+  audit_by?: string;
+}
+
+export interface ReferenceWithPath extends Reference {
+  path: string;
+  hasAudit: boolean;
+  hasRepo: boolean;
+  hasGist: boolean;
+}
+
+/**
+ * Get the references root directory.
+ */
+export function getReferencesRoot(): string {
+  return join(homedir(), ".abbie", "refs");
+}
+
+/**
+ * Get the directory for a specific reference type.
+ */
+export function getTypeDir(type: ReferenceType): string {
+  return join(getReferencesRoot(), type);
+}
+
+/**
+ * Get the directory for a specific reference.
+ */
+export function getReferenceDir(type: ReferenceType, name: string): string {
+  return join(getTypeDir(type), name);
+}
+
+/**
+ * Ensure the references directory structure exists.
+ */
+export function ensureReferencesDir(): void {
+  const root = getReferencesRoot();
+  for (const type of ["web", "ios", "android"] as ReferenceType[]) {
+    const typeDir = join(root, type);
+    if (!existsSync(typeDir)) {
+      mkdirSync(typeDir, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Parse a URL to extract domain and suggested name.
+ */
+export function parseUrl(url: string): { domain: string; suggestedName: string } {
+  try {
+    const parsed = new URL(url);
+    const domain = parsed.hostname.replace(/^www\./, "");
+    // Convert domain to name: internet.dev -> int-dev, linear.app -> linear-app
+    const suggestedName = domain
+      .replace(/\./g, "-")
+      .replace(/-com$|-app$|-dev$|-io$|-xyz$/, "")
+      .toLowerCase();
+    return { domain, suggestedName };
+  } catch {
+    // Might be a GitHub URL or other format
+    const parts = url.split("/").filter(Boolean);
+    const last = parts[parts.length - 1] || "unknown";
+    return { domain: url, suggestedName: last.toLowerCase() };
+  }
+}
+
+/**
+ * Read a reference from disk.
+ */
+export function readReference(type: ReferenceType, name: string): ReferenceWithPath | null {
+  const dir = getReferenceDir(type, name);
+  const manifestPath = join(dir, "reference.json");
+
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const stat = statSync(manifestPath);
+    const createdFallback = (
+      stat.birthtime && !Number.isNaN(stat.birthtime.getTime()) ? stat.birthtime : stat.mtime
+    ).toISOString();
+
+    const content = readFileSync(manifestPath, "utf-8");
+    const raw = JSON.parse(content) as unknown;
+    const ref = normalizeReferenceJson(
+      raw,
+      { type, name, created: createdFallback },
+      { touchUpdated: false },
+    );
+    return {
+      ...ref,
+      path: dir,
+      hasAudit: existsSync(join(dir, "AUDIT.md")),
+      hasRepo: existsSync(join(dir, "repo")),
+      hasGist: hasAnyGist(ref.gist),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a reference to disk.
+ */
+export function writeReference(ref: Reference): string {
+  ensureReferencesDir();
+  const dir = getReferenceDir(ref.type, ref.name);
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const manifestPath = join(dir, "reference.json");
+  writeFileSync(manifestPath, JSON.stringify(ref, null, 2));
+  return dir;
+}
+
+/**
+ * Delete a reference from disk.
+ */
+export function deleteReference(type: ReferenceType, name: string): boolean {
+  const dir = getReferenceDir(type, name);
+  if (!existsSync(dir)) {
+    return false;
+  }
+  rmSync(dir, { recursive: true, force: true });
+  return true;
+}
+
+/**
+ * List all references, optionally filtered.
+ */
+export function listReferences(options?: {
+  type?: ReferenceType;
+  tags?: string[];
+  stack?: string;
+  pattern?: string;
+}): ReferenceWithPath[] {
+  ensureReferencesDir();
+  const results: ReferenceWithPath[] = [];
+
+  const types: ReferenceType[] = options?.type ? [options.type] : ["web", "ios", "android"];
+
+  for (const type of types) {
+    const typeDir = getTypeDir(type);
+    if (!existsSync(typeDir)) continue;
+
+    const entries = readdirSync(typeDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+
+      const ref = readReference(type, entry.name);
+      if (!ref) continue;
+
+      // Apply filters
+      if (options?.tags?.length) {
+        const refTags = ref.tags || [];
+        if (!options.tags.some((t) => refTags.includes(t))) continue;
+      }
+
+      if (options?.stack) {
+        const stackValues = Object.values(ref.stack || {}).filter(
+          (value): value is string => typeof value === "string" && value.length > 0,
+        );
+        if (
+          !stackValues.some((value) => value.toLowerCase().includes(options.stack!.toLowerCase()))
+        ) {
+          continue;
+        }
+      }
+
+      if (options?.pattern) {
+        const patterns = ref.patterns || [];
+        if (!patterns.some((p) => p.toLowerCase().includes(options.pattern!.toLowerCase()))) {
+          continue;
+        }
+      }
+
+      results.push(ref);
+    }
+  }
+
+  // Sort by updated/created date, newest first
+  return results.sort((a, b) => {
+    const dateA = new Date(a.updated || a.created).getTime();
+    const dateB = new Date(b.updated || b.created).getTime();
+    return dateB - dateA;
+  });
+}
+
+/**
+ * Search references by text query.
+ */
+export function searchReferences(query: string): ReferenceWithPath[] {
+  const all = listReferences();
+  const lowerQuery = query.toLowerCase();
+
+  return all.filter((ref) => {
+    // Search in name, domain, notes, patterns, tags
+    if (ref.name.toLowerCase().includes(lowerQuery)) return true;
+    if (ref.domain?.toLowerCase().includes(lowerQuery)) return true;
+    if (ref.notes?.toLowerCase().includes(lowerQuery)) return true;
+    if (ref.patterns?.some((p) => p.toLowerCase().includes(lowerQuery))) return true;
+    if (ref.tags?.some((t) => t.toLowerCase().includes(lowerQuery))) return true;
+
+    // Search in stack values
+    const stackValues = Object.values(ref.stack || {}).filter(
+      (value): value is string => typeof value === "string" && value.length > 0,
+    );
+    if (stackValues.some((value) => value.toLowerCase().includes(lowerQuery))) return true;
+
+    return false;
+  });
+}
+
+/**
+ * Find a reference by name across all types.
+ */
+export function findReference(name: string): ReferenceWithPath | null {
+  for (const type of ["web", "ios", "android"] as ReferenceType[]) {
+    const ref = readReference(type, name);
+    if (ref) return ref;
+  }
+  return null;
+}
+
+/**
+ * Get the AUDIT.md content for a reference.
+ */
+export function getAuditContent(type: ReferenceType, name: string): string | null {
+  const dir = getReferenceDir(type, name);
+  const auditPath = join(dir, "AUDIT.md");
+  if (!existsSync(auditPath)) {
+    return null;
+  }
+  return readFileSync(auditPath, "utf-8");
+}
+
+/**
+ * Format a reference for prompt injection (www-studio consumption).
+ */
+export function formatReferenceForPrompt(ref: ReferenceWithPath): string {
+  const lines: string[] = [
+    `# Reference: ${ref.name}`,
+    "",
+    `**URL**: ${ref.url}`,
+    `**Type**: ${ref.type}`,
+  ];
+
+  if (ref.domain) {
+    lines.push(`**Domain**: ${ref.domain}`);
+  }
+
+  if (ref.stack && Object.keys(ref.stack).length > 0) {
+    lines.push("", "## Stack");
+    for (const [key, value] of Object.entries(ref.stack)) {
+      if (value) {
+        lines.push(`- **${key}**: ${value}`);
+      }
+    }
+  }
+
+  if (ref.patterns?.length) {
+    lines.push("", "## Patterns");
+    lines.push(ref.patterns.map((p) => `- ${p}`).join("\n"));
+  }
+
+  if (ref.notes) {
+    lines.push("", "## Notes");
+    lines.push(ref.notes);
+  }
+
+  if (ref.gist) {
+    lines.push("", "## Resources");
+    if (ref.gist.auditUrl) {
+      lines.push(`- **Audit (rendered)**: ${ref.gist.auditUrl}`);
+    }
+    if (ref.gist.desktopScreenshotsUrl) {
+      lines.push(`- **Desktop screenshots**: ${ref.gist.desktopScreenshotsUrl}`);
+    }
+    if (ref.gist.mobileScreenshotsUrl) {
+      lines.push(`- **Mobile screenshots**: ${ref.gist.mobileScreenshotsUrl}`);
+    }
+    if (
+      !ref.gist.desktopScreenshotsUrl &&
+      !ref.gist.mobileScreenshotsUrl &&
+      ref.gist.screenshotsUrl
+    ) {
+      lines.push(`- **Screenshots**: ${ref.gist.screenshotsUrl}`);
+    }
+
+    if (ref.gist.specialists && Object.keys(ref.gist.specialists).length > 0) {
+      lines.push("", "### Specialists");
+      for (const [name, url] of Object.entries(ref.gist.specialists)) {
+        lines.push(`- **${name}**: ${url}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function hasAnyGist(gist: ReferenceGist | undefined): boolean {
+  if (!gist) return false;
+  if (gist.auditUrl) return true;
+  if (gist.screenshotsUrl) return true;
+  if (gist.desktopScreenshotsUrl) return true;
+  if (gist.mobileScreenshotsUrl) return true;
+  if (gist.specialists && Object.keys(gist.specialists).length > 0) return true;
+  return false;
+}
+
+export function normalizeReferenceJson(
+  input: unknown,
+  context: { type: ReferenceType; name: string; url?: string; created?: string },
+  options: { touchUpdated: boolean },
+): Reference {
+  const now = new Date().toISOString();
+
+  const obj: Record<string, unknown> =
+    typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+
+  // Canonical identity fields
+  obj.name = typeof obj.name === "string" && obj.name.trim().length > 0 ? obj.name : context.name;
+  obj.type =
+    obj.type === "web" || obj.type === "ios" || obj.type === "android" ? obj.type : context.type;
+
+  // URL + domain
+  const url =
+    typeof obj.url === "string" && obj.url.trim().length > 0 ? obj.url : (context.url ?? "");
+  obj.url = url;
+  if (url) {
+    if (!obj.domain) {
+      obj.domain = parseUrl(url).domain;
+    }
+  }
+
+  // created/updated
+  obj.created =
+    typeof obj.created === "string" && obj.created.trim().length > 0
+      ? obj.created
+      : context.created || now;
+  if (options.touchUpdated) {
+    obj.updated = now;
+  } else if (obj.updated && typeof obj.updated !== "string") {
+    delete obj.updated;
+  }
+
+  // gists → gist (canonical key)
+  if (!obj.gist && obj.gists) {
+    obj.gist = obj.gists;
+  }
+  if (obj.gists) {
+    delete obj.gists;
+  }
+
+  // summary → notes (canonical key)
+  if (!obj.notes && typeof obj.summary === "string") {
+    obj.notes = obj.summary;
+  }
+  if (obj.summary) {
+    delete obj.summary;
+  }
+
+  // auditDate/confidence → audit_* (canonical keys)
+  if (!obj.audit_date && typeof obj.auditDate === "string") {
+    obj.audit_date = obj.auditDate;
+  }
+  if (obj.auditDate) {
+    delete obj.auditDate;
+  }
+  if (typeof obj.audit_confidence !== "number" && typeof obj.confidence === "number") {
+    obj.audit_confidence = obj.confidence;
+  }
+  if (obj.confidence) {
+    delete obj.confidence;
+  }
+
+  // Best-effort default for audit_by when we have an audit artifact
+  const gist = obj.gist;
+  const auditUrl =
+    typeof gist === "object" && gist !== null
+      ? (gist as Record<string, unknown>).auditUrl
+      : undefined;
+  const hasAuditGist = typeof auditUrl === "string" && auditUrl.trim().length > 0;
+  if (
+    !obj.audit_by &&
+    (hasAuditGist || existsSync(join(getReferenceDir(context.type, context.name), "AUDIT.md")))
+  ) {
+    obj.audit_by = "ref-add";
+  }
+
+  return obj as unknown as Reference;
+}