@creativeintelligence/abbie 0.1.0

package/src/cli/commands/find/index.ts

@@ -0,0 +1,313 @@
+import { execSync } from "node:child_process";
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+
+interface ToolMatch {
+  type: "cli" | "skill" | "prompt" | "role";
+  name: string;
+  description: string;
+  score: number;
+  usage?: string;
+}
+
+export default class Find extends BaseCommand {
+  static override description =
+    "Find tools by intent or keyword. Searches across CLIs, skills, prompts, and roles.";
+  static override hidden = false;
+
+  static override examples = [
+    '<%= config.bin %> find "run tests"',
+    '<%= config.bin %> find "send slack message"',
+    '<%= config.bin %> find "analyze code" --type cli',
+    '<%= config.bin %> find "architect" --type role',
+  ];
+
+  static override args = {
+    query: Args.string({
+      description: "Search query (intent or keyword)",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    type: Flags.string({
+      char: "t",
+      description: "Filter by tool type",
+      options: ["cli", "skill", "prompt", "role", "all"],
+      default: "all",
+    }),
+    limit: Flags.integer({
+      char: "l",
+      description: "Limit results",
+      default: 5,
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(Find);
+    this.parsedFlags = flags;
+
+    const query = args.query.toLowerCase();
+    const toolType = flags.type;
+    const limit = flags.limit;
+
+    const allMatches: ToolMatch[] = [];
+
+    // Search CLIs
+    if (toolType === "all" || toolType === "cli") {
+      const cliMatches = await this.searchCLIs(query);
+      allMatches.push(...cliMatches);
+    }
+
+    // Search skills
+    if (toolType === "all" || toolType === "skill") {
+      const skillMatches = await this.searchSkills(query);
+      allMatches.push(...skillMatches);
+    }
+
+    // Search prompts
+    if (toolType === "all" || toolType === "prompt") {
+      const promptMatches = await this.searchPrompts(query);
+      allMatches.push(...promptMatches);
+    }
+
+    // Search roles
+    if (toolType === "all" || toolType === "role") {
+      const roleMatches = await this.searchRoles(query);
+      allMatches.push(...roleMatches);
+    }
+
+    // Sort by score and limit
+    const sortedMatches = allMatches.sort((a, b) => b.score - a.score).slice(0, limit);
+
+    if (flags.json || flags.format === "json") {
+      return sortedMatches;
+    }
+
+    // Text output
+    if (sortedMatches.length === 0) {
+      console.log(`No matches found for "${args.query}"`);
+      return sortedMatches;
+    }
+
+    console.log(`\nFound ${sortedMatches.length} match(es) for "${args.query}":\n`);
+
+    for (const match of sortedMatches) {
+      const typeIcon = this.getTypeIcon(match.type);
+      console.log(`${typeIcon} ${match.name} (${match.type})`);
+      console.log(`   ${match.description}`);
+      if (match.usage) {
+        console.log(`   Usage: ${match.usage}`);
+      }
+      console.log("");
+    }
+
+    return sortedMatches;
+  }
+
+  private getTypeIcon(type: string): string {
+    switch (type) {
+      case "cli":
+        return "🔧";
+      case "skill":
+        return "⚡";
+      case "prompt":
+        return "📝";
+      case "role":
+        return "🎭";
+      default:
+        return "•";
+    }
+  }
+
+  private calculateScore(text: string, query: string): number {
+    const lowerText = text.toLowerCase();
+    const words = query.split(/\s+/);
+
+    // Exact match
+    if (lowerText.includes(query)) {
+      return 100;
+    }
+
+    // All words present
+    const allWordsPresent = words.every((word) => lowerText.includes(word));
+    if (allWordsPresent) {
+      return 80;
+    }
+
+    // Count matching words
+    const matchingWords = words.filter((word) => lowerText.includes(word));
+    const wordScore = (matchingWords.length / words.length) * 60;
+
+    return wordScore;
+  }
+
+  private async searchCLIs(query: string): Promise<ToolMatch[]> {
+    const clis = [
+      { name: "outline", desc: "AST-based code structure analysis", usage: "outline src/" },
+      { name: "layer", desc: "Dependency and architecture analysis", usage: "layer ." },
+      { name: "verify", desc: "Test runner adapter", usage: "verify --format=summary" },
+      {
+        name: "abbie",
+        desc: "Agent session management and orchestration",
+        usage: "abbie session start",
+      },
+      {
+        name: "abbie report",
+        desc: "Lifecycle event persistence and notifications",
+        usage: "abbie report start \"task\"",
+      },
+      { name: "abbie history", desc: "Query lifecycle event history", usage: "abbie history" },
+      { name: "mem", desc: "Memory audit and zombie cleanup", usage: "mem audit" },
+      {
+        name: "slack",
+        desc: "Slack messaging and notifications",
+        usage: "slack dm send --user luke",
+      },
+      { name: "linear", desc: "Linear issue tracking", usage: "linear issue view ARBOR-123" },
+      {
+        name: "format",
+        desc: "Cross-platform markdown formatting",
+        usage: 'echo "**bold**" | format slack',
+      },
+      {
+        name: "prompts",
+        desc: "Prompt templates and commands",
+        usage: "prompts commands export /tdd",
+      },
+      { name: "roles", desc: "Agent persona management", usage: "roles export jony" },
+      { name: "epub", desc: "E-book generation and library management", usage: "epub compile" },
+    ];
+
+    const matches: ToolMatch[] = [];
+    for (const cli of clis) {
+      const searchText = `${cli.name} ${cli.desc}`;
+      const score = this.calculateScore(searchText, query);
+      if (score > 20) {
+        matches.push({
+          type: "cli",
+          name: cli.name,
+          description: cli.desc,
+          score,
+          usage: cli.usage,
+        });
+      }
+    }
+    return matches;
+  }
+
+  private async searchSkills(query: string): Promise<ToolMatch[]> {
+    const skillsDir = join(homedir(), ".abbie", "skills");
+    const matches: ToolMatch[] = [];
+
+    try {
+      const entries = await readdir(skillsDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === "components" || entry.name === "runbooks") continue;
+
+        const skillPath = join(skillsDir, entry.name, "SKILL.md");
+        try {
+          const content = await readFile(skillPath, "utf-8");
+
+          // Parse frontmatter for description
+          const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+          let description = entry.name;
+
+          if (frontmatterMatch) {
+            const descMatch = frontmatterMatch[1].match(/description:\s*(.+)/);
+            if (descMatch) {
+              description = descMatch[1].trim();
+            }
+          }
+
+          const searchText = `${entry.name} ${description}`;
+          const score = this.calculateScore(searchText, query);
+
+          if (score > 20) {
+            matches.push({
+              type: "skill",
+              name: entry.name,
+              description,
+              score,
+              usage: `Use skill: /${entry.name}`,
+            });
+          }
+        } catch {
+          // Skill file doesn't exist or can't be read
+        }
+      }
+    } catch {
+      // Skills directory doesn't exist
+    }
+
+    return matches;
+  }
+
+  private async searchPrompts(query: string): Promise<ToolMatch[]> {
+    const matches: ToolMatch[] = [];
+
+    try {
+      const output = execSync("prompts commands list --json --quiet 2>/dev/null", {
+        encoding: "utf-8",
+      });
+      const prompts = JSON.parse(output);
+
+      for (const prompt of prompts) {
+        const searchText = `${prompt.alias || prompt.id} ${prompt.title || ""}`;
+        const score = this.calculateScore(searchText, query);
+
+        if (score > 20) {
+          matches.push({
+            type: "prompt",
+            name: prompt.alias || prompt.id,
+            description: prompt.title || prompt.id,
+            score,
+            usage: `prompts commands export ${prompt.alias || prompt.id}`,
+          });
+        }
+      }
+    } catch {
+      // prompts CLI not available
+    }
+
+    return matches;
+  }
+
+  private async searchRoles(query: string): Promise<ToolMatch[]> {
+    const matches: ToolMatch[] = [];
+
+    try {
+      const output = execSync("roles list --json --quiet 2>/dev/null", { encoding: "utf-8" });
+      const categories = JSON.parse(output);
+
+      for (const [category, roles] of Object.entries(categories)) {
+        if (!Array.isArray(roles)) continue;
+
+        for (const role of roles) {
+          const searchText = `${role.name} ${role.description || ""} ${category}`;
+          const score = this.calculateScore(searchText, query);
+
+          if (score > 20) {
+            matches.push({
+              type: "role",
+              name: role.name,
+              description: `${role.description || role.name} (${category})`,
+              score,
+              usage: `roles export ${role.name}`,
+            });
+          }
+        }
+      }
+    } catch {
+      // roles CLI not available
+    }
+
+    return matches;
+  }
+}

package/src/cli/commands/history/index.ts

@@ -0,0 +1,257 @@
+import { api, type Doc, getHttpClient } from "@abbie/sdk/convex";
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+
+type HistoryEvent = Doc<"reports">;
+
+interface HistoryResult {
+  success: boolean;
+  events: HistoryEvent[];
+  count: number;
+  filters: {
+    last?: number;
+    since?: string;
+    sessionId?: string;
+    traceId?: string;
+    agent?: string;
+  };
+}
+
+/**
+ * Parse duration strings like "1h", "30m", "2d", "24h" into milliseconds.
+ */
+function parseDuration(input: string): number {
+  const match = input.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)$/);
+  if (!match) throw new Error(`Invalid duration: "${input}" (expected e.g. 1h, 30m, 2d)`);
+
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+
+  const multipliers: Record<string, number> = {
+    ms: 1,
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+  };
+
+  return value * multipliers[unit];
+}
+
+export default class HistoryCommand extends BaseCommand {
+  static override summary = "Query agent event history";
+  static override description = `Query event history with a unified interface.
+
+Reads lifecycle events from Convex reports table.
+
+SYMMETRY: abbie report writes → abbie history reads`;
+
+  static override examples = [
+    "$ abbie history                         # recent events (default: 10)",
+    "$ abbie history --last 20               # last 20 events",
+    "$ abbie history --since 1h              # events from last hour",
+    "$ abbie history --since 24h --agent claude",
+    "$ abbie history --trace-id tr_abc123    # events in a trace",
+    "$ abbie history --session sess_xyz      # events in a session",
+    "$ abbie history --json                  # machine output",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    last: Flags.integer({
+      char: "n",
+      description: "Number of recent events to show",
+      default: 10,
+    }),
+    since: Flags.string({
+      char: "s",
+      description: "Time filter (e.g., 1h, 30m, 2d, 24h)",
+    }),
+    "trace-id": Flags.string({
+      char: "t",
+      description: "Filter by trace ID",
+    }),
+    session: Flags.string({
+      description: "Filter by session ID",
+    }),
+    agent: Flags.string({
+      char: "a",
+      description: "Filter by agent (claude, codex, copilot, etc.)",
+    }),
+    action: Flags.string({
+      description: "Filter by action (started, completed, blocked, escalated)",
+    }),
+    "min-confidence": Flags.integer({
+      description: "Minimum confidence score",
+      min: 1,
+      max: 10,
+    }),
+    pattern: Flags.string({
+      char: "p",
+      description: "Regex pattern to match task/summary",
+    }),
+    count: Flags.boolean({
+      description: "Only output count of matching events",
+      default: false,
+    }),
+  };
+
+  async execute(): Promise<HistoryResult> {
+    const { flags } = await this.parse(HistoryCommand);
+    this.parsedFlags = flags;
+
+    const hasSieveFilters = flags.agent || flags.action || flags["min-confidence"];
+
+    try {
+      const client = getHttpClient();
+
+      let sinceMs: number | undefined;
+      if (flags.since) {
+        sinceMs = Date.now() - parseDuration(flags.since);
+      }
+
+      let events: HistoryEvent[];
+      if (flags["trace-id"]) {
+        events = await client.query(api.reports.getTrace, {
+          traceId: flags["trace-id"],
+          limit: flags.last,
+        });
+      } else if (hasSieveFilters) {
+        events = await client.query(api.reports.sieve, {
+          agent: flags.agent,
+          action: flags.action,
+          minConfidence: flags["min-confidence"],
+          since: sinceMs,
+          sessionId: flags.session,
+          limit: flags.last,
+        });
+      } else {
+        events = await client.query(api.reports.replay, {
+          limit: flags.last,
+          since: sinceMs,
+          sessionId: flags.session,
+        });
+      }
+
+      events = this.postFilter(events, flags, sinceMs);
+      if (flags.last) {
+        events = events.slice(0, flags.last);
+      }
+
+      const result: HistoryResult = {
+        success: true,
+        events,
+        count: events.length,
+        filters: this.buildFilters(flags),
+      };
+
+      if (!this.jsonEnabled?.()) {
+        this.renderTextOutput(result, flags);
+      }
+
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return this.error(`history query failed: ${message}`, { exit: 1 });
+    }
+  }
+
+  /**
+   * Client-side post-filter for cross-filter scenarios.
+   *
+   * The server query picks the best single index (e.g., by_agent, by_timestamp),
+   * but can't intersect multiple dimensions in one index scan. This pass applies
+   * all remaining filters unconditionally — redundant filters are no-ops.
+   * Pattern matching also uses regex here vs. substring on the server.
+   */
+  private postFilter(
+    events: HistoryEvent[],
+    flags: {
+      "trace-id"?: string;
+      session?: string;
+      agent?: string;
+      action?: string;
+      "min-confidence"?: number;
+      pattern?: string;
+    },
+    sinceMs?: number,
+  ): HistoryEvent[] {
+    let filtered = events;
+
+    if (sinceMs !== undefined) {
+      filtered = filtered.filter((e) => e.timestamp >= sinceMs);
+    }
+    if (flags["trace-id"]) {
+      filtered = filtered.filter((e) => e.traceId === flags["trace-id"]);
+    }
+    if (flags.session) {
+      filtered = filtered.filter((e) => e.sessionId === flags.session);
+    }
+    if (flags.agent) {
+      filtered = filtered.filter((e) => e.agent === flags.agent);
+    }
+    if (flags.action) {
+      filtered = filtered.filter((e) => e.action === flags.action);
+    }
+    if (flags["min-confidence"] !== undefined) {
+      filtered = filtered.filter((e) => (e.confidence ?? 0) >= flags["min-confidence"]!);
+    }
+    if (flags.pattern) {
+      let regex: RegExp;
+      try {
+        regex = new RegExp(flags.pattern, "i");
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid regex pattern "${flags.pattern}": ${msg}`);
+      }
+      filtered = filtered.filter((e) => regex.test(`${e.task ?? ""} ${e.summary ?? ""}`));
+    }
+
+    return filtered;
+  }
+
+  private buildFilters(flags: unknown): HistoryResult["filters"] {
+    const typedFlags = flags as Record<string, unknown>;
+    return {
+      last: typeof typedFlags.last === "number" ? typedFlags.last : undefined,
+      since: typeof typedFlags.since === "string" ? typedFlags.since : undefined,
+      sessionId: typeof typedFlags.session === "string" ? typedFlags.session : undefined,
+      traceId: typeof typedFlags["trace-id"] === "string" ? typedFlags["trace-id"] : undefined,
+      agent: typeof typedFlags.agent === "string" ? typedFlags.agent : undefined,
+    };
+  }
+
+  private renderTextOutput(result: HistoryResult, flags: unknown): void {
+    const typedFlags = flags as Record<string, unknown>;
+    if (typedFlags.count === true) {
+      this.log(`${result.count} events`);
+      return;
+    }
+
+    if (result.events.length === 0) {
+      this.logInfo("no events found");
+      return;
+    }
+
+    for (const event of result.events) {
+      const timestamp = event.timestamp
+        ? new Date(event.timestamp).toLocaleString("en-US", {
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+          })
+        : "";
+
+      const agent = event.agent ?? "unknown";
+      const action = event.action ?? "";
+      const confidence = event.confidence !== undefined ? `(${event.confidence}/10)` : "";
+      const task = event.task ?? event.summary ?? "";
+
+      this.log(`${timestamp} ${agent}:${action} ${confidence} ${task}`.trim());
+    }
+
+    this.logInfo(`\n${result.count} events`);
+  }
+}

package/src/cli/commands/hooks/guard.ts

@@ -0,0 +1,71 @@
+import {
+  cleanupStaleLockfiles,
+  getActiveLockfiles,
+  isInHookContext,
+} from "../../../lib/hooks/index.js";
+import { BaseCommand } from "../../base-command.js";
+
+interface GuardOutput {
+  inContext: boolean;
+  lockfiles: number;
+  cleaned: number;
+}
+
+export default class HooksGuardCommand extends BaseCommand {
+  static override summary = "Check if currently in hook context (should skip execution)";
+  static override description = `Returns exit code 0 if in hook context (skip), 1 if should proceed.
+
+Used at the start of hook scripts to prevent recursive triggers:
+  abbie hook guard && exit 0
+
+Also cleans up stale lockfiles (>2 minutes old) on each check.`;
+
+  static override examples = [
+    "# In a hook script",
+    "abbie hook guard && exit 0",
+    "",
+    "# Check status",
+    "abbie hook guard --json --quiet",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+  };
+
+  async execute(): Promise<GuardOutput> {
+    // Clean up stale lockfiles first
+    const cleaned = cleanupStaleLockfiles();
+
+    const inContext = isInHookContext();
+    const lockfiles = getActiveLockfiles();
+
+    if (!this.jsonEnabled?.()) {
+      if (inContext) {
+        this.log(
+          `in hook context (${lockfiles.length} active lockfile${lockfiles.length === 1 ? "" : "s"})`,
+        );
+        if (cleaned > 0) {
+          this.logInfo(`cleaned ${cleaned} stale lockfile${cleaned === 1 ? "" : "s"}`);
+        }
+      } else {
+        this.log("not in hook context");
+        if (cleaned > 0) {
+          this.logInfo(`cleaned ${cleaned} stale lockfile${cleaned === 1 ? "" : "s"}`);
+        }
+      }
+    }
+
+    // Exit 0 if in context (caller should skip), 1 if should proceed
+    if (inContext) {
+      process.exitCode = 0;
+    } else {
+      process.exitCode = 1;
+    }
+
+    return {
+      inContext,
+      lockfiles: lockfiles.length,
+      cleaned,
+    };
+  }
+}