@creativeintelligence/abbie 0.1.0

package/src/cli/commands/reference/extract.ts

@@ -0,0 +1,389 @@
+import { execSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Args, Flags } from "@oclif/core";
+import {
+  getReferenceDir,
+  parseUrl,
+  type Reference,
+  type ReferenceExtract,
+} from "../../../lib/references.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class ReferenceExtractCommand extends BaseCommand {
+  static override description =
+    "Extract one specific thing from a website into a focused gist and record it under the reference";
+  static override hidden = false;
+
+  static override examples = [
+    '<%= config.bin %> reference extract https://linear.app/pricing "pricing table"',
+    '<%= config.bin %> reference extract https://arc.net "navbar" --name arc-net',
+    '<%= config.bin %> reference extract https://cursor.com "command palette" --id command-palette',
+  ];
+
+  static override args = {
+    url: Args.string({
+      description: "URL to extract from (can be a deep link)",
+      required: true,
+    }),
+    thing: Args.string({
+      description: "What to extract (one specific thing/component/pattern)",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    name: Flags.string({
+      char: "n",
+      description: "Reference name to store under (default: derived from hostname)",
+    }),
+    id: Flags.string({
+      description: "Stable extract id (default: slugified THING)",
+    }),
+    notes: Flags.string({
+      description: "Optional notes to store with the extract record",
+    }),
+    force: Flags.boolean({
+      char: "f",
+      description: "Overwrite existing extract record (does not delete files)",
+      default: false,
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(ReferenceExtractCommand);
+    this.parsedFlags = flags;
+
+    const url = args.url;
+    const thing = args.thing.trim();
+
+    const refName = flags.name || deriveReferenceNameFromHost(url);
+    const extractId = flags.id || slugify(thing);
+    if (!extractId) {
+      this.error("Invalid extract id (empty). Provide --id explicitly.", { exit: 2 });
+    }
+
+    const refDir = getReferenceDir("web", refName);
+    const extractDir = join(refDir, "extracts", extractId);
+
+    if (existsSync(extractDir) && !flags.force) {
+      this.error(
+        `Extract '${extractId}' already exists at ${extractDir}. Use --force to overwrite.`,
+        {
+          exit: 1,
+        },
+      );
+    }
+
+    mkdirSync(join(extractDir, "screenshots", "desktop"), { recursive: true });
+    mkdirSync(join(extractDir, "screenshots", "mobile"), { recursive: true });
+
+    // Ensure base reference manifest exists (so the extract is always attachable to a reference)
+    const reference = upsertReferenceManifest(refDir, { url, name: refName });
+    if (!flags.force && reference.extracts?.some((e) => e.id === extractId)) {
+      this.error(
+        `Extract '${extractId}' already exists in ${join(refDir, "reference.json")}. Use --force to overwrite.`,
+        { exit: 1 },
+      );
+    }
+
+    const extract: ReferenceExtract = {
+      id: extractId,
+      thing,
+      url,
+      created: new Date().toISOString(),
+      notes: flags.notes,
+    };
+
+    // Persist a local record immediately (even if the LLM run fails)
+    const extractJsonPath = join(extractDir, "extract.json");
+    writeFileSync(extractJsonPath, JSON.stringify(extract, null, 2));
+    const extractMdPath = join(extractDir, "EXTRACT.md");
+    writeFileSync(extractMdPath, buildExtractStubMarkdown(extract, refName));
+
+    // Also attach to reference.json (discoverable via `abbie reference show`)
+    attachExtractToReference(refDir, reference, extract, { overwrite: flags.force });
+
+    this.logInfo(`📁 Reference: ${refDir}`);
+    this.logInfo(`🧩 Extract: ${extractDir}`);
+    this.logInfo(`🔍 Extracting: ${thing}`);
+
+    const prompt = buildExtractPrompt({ url, thing, refName, refDir, extractDir, extractId });
+
+    let resultText = "";
+    try {
+      this.logInfo("🤖 Spawning Claude with ref-add skill (targeted extract)...");
+
+      const claudePath = join(homedir(), ".local", "bin", "claude");
+      const localBin = join(homedir(), ".local", "bin");
+      const envPath = process.env.PATH?.includes(localBin)
+        ? process.env.PATH
+        : `${localBin}:${process.env.PATH ?? ""}`;
+
+      resultText = execSync(
+        [
+          claudePath,
+          "-p",
+          "--dangerously-skip-permissions",
+          "--output-format",
+          "text",
+          "--session-id",
+          randomUUID(),
+        ].join(" "),
+        {
+          input: prompt,
+          encoding: "utf8",
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 600_000,
+          cwd: extractDir,
+          env: { ...process.env, PATH: envPath },
+        },
+      );
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.error(`Extract failed: ${message}`);
+    }
+
+    const targetGist = parseTargetGist(resultText);
+
+    // Update extract.json + reference.json with the parsed gist URL (best-effort)
+    if (targetGist) {
+      try {
+        const now = new Date().toISOString();
+        const existing = JSON.parse(readFileSync(extractJsonPath, "utf-8")) as ReferenceExtract;
+        existing.updated = now;
+        existing.gist = {
+          ...(existing.gist || {}),
+          url: targetGist,
+          createdAt: existing.gist?.createdAt || now,
+        };
+        writeFileSync(extractJsonPath, JSON.stringify(existing, null, 2));
+
+        try {
+          const md = readFileSync(extractMdPath, "utf-8");
+          const updatedMd = md.replace(
+            /\|\s*\*\*gist\*\*\s*\|\s*.*\|\n/i,
+            `| **gist** | ${targetGist} |\n`,
+          );
+          writeFileSync(extractMdPath, updatedMd);
+        } catch {
+          // best-effort
+        }
+
+        const latestReference = readReferenceManifest(refDir);
+        if (latestReference) {
+          const updated = upsertExtractInReference(latestReference, {
+            ...existing,
+            updated: now,
+          });
+          writeFileSync(join(refDir, "reference.json"), JSON.stringify(updated, null, 2));
+        }
+      } catch {
+        // best-effort
+      }
+    }
+
+    const output = {
+      status: "complete",
+      url,
+      refName,
+      refDir,
+      extractId,
+      extractDir,
+      thing,
+      targetGist,
+    };
+
+    if (flags.json || flags.format === "json") {
+      return output;
+    }
+
+    this.log("\n✅ Extract complete");
+    this.log(`   Reference: ${refDir}`);
+    this.log(`   Extract: ${extractDir}`);
+    if (targetGist) {
+      this.log(`   Gist: ${targetGist}`);
+    } else {
+      this.log("   Gist: (not detected — check EXTRACT.md / extract.json)");
+    }
+
+    return output;
+  }
+}
+
+function deriveReferenceNameFromHost(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname
+      .replace(/^www\./, "")
+      .replace(/\./g, "-")
+      .toLowerCase();
+  } catch {
+    // Fallback: approximate
+    return url
+      .replace(/^https?:\/\//, "")
+      .replace(/\/.*$/, "")
+      .replace(/^www\./, "")
+      .replace(/\./g, "-")
+      .toLowerCase();
+  }
+}
+
+function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, "-")
+    .slice(0, 80);
+}
+
+function buildExtractPrompt(input: {
+  url: string;
+  thing: string;
+  refName: string;
+  refDir: string;
+  extractDir: string;
+  extractId: string;
+}): string {
+  return `Use the ref-add skill for a targeted extraction. Do NOT run the full multi-specialist site audit.
+
+Target URL: ${input.url}
+Reference name: ${input.refName}
+Reference directory: ${input.refDir}
+Extract id: ${input.extractId}
+Extract directory: ${input.extractDir}
+
+Goal: Extract ONE specific thing from the website:
+- Thing: ${input.thing}
+
+Deliverables (REQUIRED):
+1) Create ONE markdown gist that documents the thing (states, structure, layout, tokens, interactions, implementation hints).
+   - minimum 80 lines
+   - factual, terse, no AI-speak
+   - include evidence screenshots (capture minimal set; upload as gist(s) if needed; embed images via raw URLs)
+2) Write a local record at ${input.extractDir}/EXTRACT.md that includes:
+   - date, source URL, thing, extract id
+   - the gist URL(s) produced
+3) Update ${input.extractDir}/extract.json with the gist URL (gist.url) and updated timestamp.
+
+When complete, output EXACTLY one line:
+TARGET_GIST: <gist-url>`;
+}
+
+function parseTargetGist(output: string): string | null {
+  const line = output
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.startsWith("TARGET_GIST:"));
+  if (!line) return null;
+  const url = line.replace(/^TARGET_GIST:\s*/, "").trim();
+  if (!url.startsWith("https://gist.github.com/")) return null;
+  return url;
+}
+
+function buildExtractStubMarkdown(extract: ReferenceExtract, refName: string): string {
+  const createdDate = extract.created.split("T")[0] || extract.created;
+  const notes = extract.notes ? `\n\n## Notes\n\n${extract.notes}\n` : "";
+  return `# Extract: ${extract.thing}
+
+| | |
+|---|---|
+| **reference** | ${refName} |
+| **extract id** | ${extract.id} |
+| **url** | ${extract.url} |
+| **created** | ${createdDate} |
+| **gist** | (pending) |
+${notes}
+`;
+}
+
+function readReferenceManifest(refDir: string): Reference | null {
+  const manifestPath = join(refDir, "reference.json");
+  if (!existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf-8")) as Reference;
+  } catch {
+    return null;
+  }
+}
+
+function upsertReferenceManifest(refDir: string, input: { url: string; name: string }): Reference {
+  mkdirSync(refDir, { recursive: true });
+
+  const manifestPath = join(refDir, "reference.json");
+  const now = new Date().toISOString();
+
+  const parsed = parseUrl(input.url);
+  const domain = parsed.domain;
+
+  let manifest: Reference | null = null;
+  if (existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as Reference;
+    } catch {
+      manifest = null;
+    }
+  }
+
+  if (!manifest) {
+    manifest = {
+      name: input.name,
+      domain,
+      url: input.url,
+      type: "web",
+      created: now,
+    };
+  }
+
+  manifest.name = input.name;
+  manifest.type = "web";
+  manifest.domain = manifest.domain || domain;
+  manifest.url = manifest.url || input.url;
+  manifest.updated = now;
+
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
+function attachExtractToReference(
+  refDir: string,
+  reference: Reference,
+  extract: ReferenceExtract,
+  options: { overwrite: boolean },
+): void {
+  const manifestPath = join(refDir, "reference.json");
+  const latest = readReferenceManifest(refDir) || reference;
+  const updated = upsertExtractInReference(latest, extract, options);
+  writeFileSync(manifestPath, JSON.stringify(updated, null, 2));
+}
+
+function upsertExtractInReference(
+  reference: Reference,
+  extract: ReferenceExtract,
+  options: { overwrite?: boolean } = {},
+): Reference {
+  if (!reference.extracts) reference.extracts = [];
+
+  const idx = reference.extracts.findIndex((e) => e.id === extract.id);
+  if (idx === -1) {
+    reference.extracts.push(extract);
+    reference.updated = new Date().toISOString();
+    return reference;
+  }
+
+  if (!options.overwrite) {
+    return reference;
+  }
+
+  reference.extracts[idx] = {
+    ...reference.extracts[idx],
+    ...extract,
+    updated: new Date().toISOString(),
+  };
+  reference.updated = new Date().toISOString();
+  return reference;
+}

package/src/cli/commands/reference/list.ts

@@ -0,0 +1,117 @@
+import { Flags } from "@oclif/core";
+import {
+  listReferences,
+  type ReferenceType,
+  type ReferenceWithPath,
+} from "../../../lib/references.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class ReferenceList extends BaseCommand {
+  static override description = "List references in the reference bank";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> reference list",
+    "<%= config.bin %> reference list --type web",
+    "<%= config.bin %> reference list --tags inspiration",
+    "<%= config.bin %> reference list --stack next.js",
+    "<%= config.bin %> reference list --pattern faq-driven",
+    "<%= config.bin %> reference list --json",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    type: Flags.string({
+      char: "t",
+      description: "Filter by type (web, ios, android)",
+      options: ["web", "ios", "android"],
+    }),
+    tags: Flags.string({
+      description: "Filter by tags (comma-separated)",
+    }),
+    stack: Flags.string({
+      char: "s",
+      description: "Filter by stack (e.g., next.js, tailwind)",
+    }),
+    pattern: Flags.string({
+      char: "p",
+      description: "Filter by pattern (e.g., faq-driven)",
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { flags } = await this.parse(ReferenceList);
+    this.parsedFlags = flags;
+
+    const refs = listReferences({
+      type: flags.type as ReferenceType | undefined,
+      tags: flags.tags?.split(",").map((t) => t.trim()),
+      stack: flags.stack,
+      pattern: flags.pattern,
+    });
+
+    // JSON output
+    if (flags.json || flags.format === "json") {
+      return refs;
+    }
+
+    // NDJSON output
+    if (this.ndjsonEnabled()) {
+      this.outputNdjson(refs);
+      return refs;
+    }
+
+    // Text output
+    if (refs.length === 0) {
+      this.logInfo("No references found");
+      return [];
+    }
+
+    this.logInfo(`References (${refs.length}):\n`);
+
+    for (const ref of refs) {
+      const icons = this.getIcons(ref);
+      const stack = ref.stack?.framework || "";
+      const patterns = ref.patterns?.slice(0, 3).join(", ") || "";
+
+      this.log(`${icons} ${ref.name} (${ref.type})`);
+      this.log(`   URL: ${ref.url}`);
+      if (stack) {
+        this.log(`   Stack: ${stack}`);
+      }
+      if (patterns) {
+        this.log(`   Patterns: ${patterns}`);
+      }
+      if (ref.tags?.length) {
+        this.log(`   Tags: ${ref.tags.join(", ")}`);
+      }
+      this.log("");
+    }
+
+    return refs;
+  }
+
+  private getIcons(ref: ReferenceWithPath): string {
+    const icons: string[] = [];
+
+    // Type icon
+    switch (ref.type) {
+      case "web":
+        icons.push("🌐");
+        break;
+      case "ios":
+        icons.push("📱");
+        break;
+      case "android":
+        icons.push("🤖");
+        break;
+    }
+
+    // Status icons
+    if (ref.hasAudit) icons.push("📝");
+    if (ref.hasRepo) icons.push("📦");
+    if (ref.hasGist) icons.push("🔗");
+
+    return icons.join(" ");
+  }
+}

package/src/cli/commands/reference/normalize.ts

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Args, Flags } from "@oclif/core";
+import {
+  getReferenceDir,
+  normalizeReferenceJson,
+  type Reference,
+  type ReferenceType,
+} from "../../../lib/references.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class ReferenceNormalize extends BaseCommand {
+  static override description = "Normalize a reference.json to the canonical site-card schema";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> reference normalize wabi-ai",
+    "<%= config.bin %> reference normalize cursor-com --dry-run",
+  ];
+
+  static override args = {
+    name: Args.string({
+      description: "Reference name",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    "dry-run": Flags.boolean({
+      description: "Show the normalized JSON but do not write it",
+      default: false,
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(ReferenceNormalize);
+    this.parsedFlags = flags;
+
+    const { type, dir } = this.resolveReferenceDir(args.name);
+    const manifestPath = join(dir, "reference.json");
+
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readFileSync(manifestPath, "utf-8")) as unknown;
+    } catch {
+      this.error(`Failed to parse ${manifestPath}`, { exit: 2 });
+    }
+
+    const stat = statSync(manifestPath);
+    const createdFallback = (
+      stat.birthtime && !Number.isNaN(stat.birthtime.getTime()) ? stat.birthtime : stat.mtime
+    ).toISOString();
+
+    const normalized: Reference = normalizeReferenceJson(
+      raw,
+      { type, name: args.name, created: createdFallback },
+      { touchUpdated: true },
+    );
+
+    if (flags["dry-run"]) {
+      if (flags.json || flags.format === "json") {
+        return { type, dir, normalized, dryRun: true };
+      }
+      this.log(JSON.stringify(normalized, null, 2));
+      return { type, dir, normalized, dryRun: true };
+    }
+
+    writeFileSync(manifestPath, JSON.stringify(normalized, null, 2));
+
+    const output = { normalized: true, type, dir, manifestPath };
+    if (flags.json || flags.format === "json") {
+      return output;
+    }
+
+    this.logInfo(`✓ Normalized ${type}/${args.name}`);
+    this.logInfo(`  ${manifestPath}`);
+    return output;
+  }
+
+  private resolveReferenceDir(name: string): { type: ReferenceType; dir: string } {
+    for (const type of ["web", "ios", "android"] as ReferenceType[]) {
+      const dir = getReferenceDir(type, name);
+      if (existsSync(join(dir, "reference.json"))) {
+        return { type, dir };
+      }
+    }
+    this.error(`Reference '${name}' not found`, { exit: 1 });
+  }
+}

package/src/cli/commands/reference/open.ts

@@ -0,0 +1,92 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Args, Flags } from "@oclif/core";
+import { findReference } from "../../../lib/references.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class ReferenceOpen extends BaseCommand {
+  static override description = "Open a reference (AUDIT.md, URL, or repo)";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> reference open int-dev",
+    "<%= config.bin %> reference open int-dev --browser",
+    "<%= config.bin %> reference open int-dev --repo",
+    "<%= config.bin %> reference open int-dev --dir",
+  ];
+
+  static override args = {
+    name: Args.string({
+      description: "Reference name",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    browser: Flags.boolean({
+      char: "b",
+      description: "Open URL in browser",
+      default: false,
+    }),
+    repo: Flags.boolean({
+      char: "r",
+      description: "Open repo directory in editor",
+      default: false,
+    }),
+    dir: Flags.boolean({
+      char: "d",
+      description: "Open reference directory in editor",
+      default: false,
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(ReferenceOpen);
+    this.parsedFlags = flags;
+
+    const ref = findReference(args.name);
+    if (!ref) {
+      this.error(`Reference '${args.name}' not found`, { exit: 1 });
+    }
+
+    // Open in browser
+    if (flags.browser) {
+      this.logInfo(`Opening ${ref.url} in browser...`);
+      execSync(`open "${ref.url}"`, { stdio: "inherit" });
+      return { action: "browser", url: ref.url };
+    }
+
+    // Open repo in editor
+    if (flags.repo) {
+      const repoPath = join(ref.path, "repo");
+      if (!existsSync(repoPath)) {
+        this.error(`No repo found for '${args.name}'. Clone it first.`, { exit: 1 });
+      }
+      this.logInfo(`Opening ${repoPath} in editor...`);
+      execSync(`code "${repoPath}"`, { stdio: "inherit" });
+      return { action: "repo", path: repoPath };
+    }
+
+    // Open directory in editor
+    if (flags.dir) {
+      this.logInfo(`Opening ${ref.path} in editor...`);
+      execSync(`code "${ref.path}"`, { stdio: "inherit" });
+      return { action: "dir", path: ref.path };
+    }
+
+    // Default: open AUDIT.md if exists, otherwise directory
+    const auditPath = join(ref.path, "AUDIT.md");
+    if (existsSync(auditPath)) {
+      this.logInfo(`Opening ${auditPath}...`);
+      execSync(`code "${auditPath}"`, { stdio: "inherit" });
+      return { action: "audit", path: auditPath };
+    }
+
+    // Fallback to directory
+    this.logInfo(`Opening ${ref.path}...`);
+    execSync(`code "${ref.path}"`, { stdio: "inherit" });
+    return { action: "dir", path: ref.path };
+  }
+}