@creativeintelligence/abbie 0.1.4 → 0.1.6

package/src/lib/references.ts

@@ -1,481 +0,0 @@
-/**
- * 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;
-}