@creativeintelligence/abbie 0.1.0

package/src/lib/digest/index.ts

@@ -0,0 +1,529 @@
+/**
+ * Project digest generation
+ *
+ * Analyzes projects and generates world-class progress digests using codex.
+ */
+
+import { execSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+export type ProjectStatus = {
+  emoji: "🟢" | "🟡" | "🟠" | "🔴" | "⚪";
+  label: "healthy" | "attention" | "at-risk" | "blocked" | "dormant";
+  color: string;
+};
+
+export type Project = {
+  name: string;
+  repo: string;
+  commits7d: number;
+  uncommitted: number;
+  branch: string;
+  status: ProjectStatus;
+  linearIssues?: string[];
+};
+
+export type DigestResult = {
+  project: string;
+  repo: string;
+  status: ProjectStatus;
+  rawPath: string;
+  digestPath: string;
+  rawBytes: number;
+  digestBytes: number;
+  success: boolean;
+  error?: string;
+};
+
+export type DigestOptions = {
+  projects: string[];
+  outputDir: string;
+  days?: number;
+  concurrency?: number;
+  linear?: boolean;
+  dryRun?: boolean;
+};
+
+const SEARCH_DIRS = [join(homedir(), "Developer", "apps"), join(homedir(), "Developer")];
+
+/**
+ * Calculate project status based on activity
+ */
+export function calculateStatus(commits: number, uncommitted: number): ProjectStatus {
+  if (commits >= 10 && uncommitted < 30) {
+    return { emoji: "🟢", label: "healthy", color: "green" };
+  }
+  if (commits >= 5 || (uncommitted >= 30 && uncommitted < 50)) {
+    return { emoji: "🟡", label: "attention", color: "yellow" };
+  }
+  if (commits >= 1 || uncommitted >= 50) {
+    return { emoji: "🟠", label: "at-risk", color: "orange" };
+  }
+  if (commits === 0 && uncommitted >= 50) {
+    return { emoji: "🔴", label: "blocked", color: "red" };
+  }
+  return { emoji: "⚪", label: "dormant", color: "gray" };
+}
+
+/**
+ * Resolve project name to repo path
+ */
+export function resolveProject(nameOrPath: string): string | null {
+  // If it's already a path, validate it
+  if (nameOrPath.startsWith("/") || nameOrPath.startsWith("~")) {
+    const expanded = nameOrPath.replace(/^~/, homedir());
+    if (existsSync(join(expanded, ".git"))) {
+      return expanded;
+    }
+    return null;
+  }
+
+  // Search for project by name
+  for (const dir of SEARCH_DIRS) {
+    // Direct match: ~/Developer/apps/arbor
+    const direct = join(dir, nameOrPath);
+    if (existsSync(join(direct, ".git"))) {
+      return direct;
+    }
+
+    // Monorepo pattern: ~/Developer/apps/arbor/arbor-xyz
+    const monorepo = join(dir, nameOrPath, `${nameOrPath}-xyz`);
+    if (existsSync(join(monorepo, ".git"))) {
+      return monorepo;
+    }
+
+    // Any subdirectory with .git
+    if (existsSync(direct)) {
+      try {
+        const entries = execSync(`ls -1 "${direct}"`, { encoding: "utf-8" }).trim().split("\n");
+        for (const entry of entries) {
+          const subdir = join(direct, entry);
+          if (existsSync(join(subdir, ".git"))) {
+            return subdir;
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Discover projects with activity
+ */
+export function discoverProjects(options: {
+  minCommits?: number;
+  maxProjects?: number;
+  days?: number;
+}): Project[] {
+  const { minCommits = 1, maxProjects, days = 7 } = options;
+  const windowStart = new Date();
+  windowStart.setDate(windowStart.getDate() - days);
+  const since = windowStart.toISOString().split("T")[0];
+
+  const projects: Array<{ commits: number; project: Project }> = [];
+  const seen = new Set<string>();
+
+  for (const searchDir of SEARCH_DIRS) {
+    if (!existsSync(searchDir)) continue;
+
+    try {
+      const gitDirs = execSync(`find "${searchDir}" -maxdepth 3 -type d -name ".git" 2>/dev/null`, {
+        encoding: "utf-8",
+      })
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+
+      for (const gitDir of gitDirs) {
+        const repoDir = gitDir.replace(/\/.git$/, "");
+        const repoName = basename(repoDir);
+
+        // Skip non-project dirs
+        if (/^(node_modules|dist|build|vendor|\..*)$/.test(repoName)) continue;
+
+        // Deduplicate
+        const realPath = execSync(`cd "${repoDir}" && pwd -P`, { encoding: "utf-8" }).trim();
+        if (seen.has(realPath)) continue;
+        seen.add(realPath);
+
+        // Get git stats
+        let commits = 0;
+        let uncommitted = 0;
+        let branch = "main";
+
+        try {
+          const log = execSync(`git -C "${repoDir}" log --since="${since}" --oneline 2>/dev/null`, {
+            encoding: "utf-8",
+          });
+          commits = log.trim().split("\n").filter(Boolean).length;
+
+          const status = execSync(`git -C "${repoDir}" status --porcelain 2>/dev/null`, {
+            encoding: "utf-8",
+          });
+          uncommitted = status.trim().split("\n").filter(Boolean).length;
+
+          branch =
+            execSync(`git -C "${repoDir}" branch --show-current 2>/dev/null`, {
+              encoding: "utf-8",
+            }).trim() || "main";
+        } catch {
+          // ignore git errors
+        }
+
+        if (commits < minCommits) continue;
+
+        projects.push({
+          commits,
+          project: {
+            name: repoName,
+            repo: repoDir,
+            commits7d: commits,
+            uncommitted,
+            branch,
+            status: calculateStatus(commits, uncommitted),
+          },
+        });
+      }
+    } catch {
+      // ignore find errors
+    }
+  }
+
+  // Sort by commits desc
+  projects.sort((a, b) => b.commits - a.commits);
+
+  const result = projects.map((p) => p.project);
+  return maxProjects ? result.slice(0, maxProjects) : result;
+}
+
+/**
+ * Fetch Linear issues for a project
+ */
+export function fetchLinearIssues(projectName: string): string[] {
+  // Derive team key from project name (e.g., kumori-xyz → KUMORI)
+  const teamKey = projectName
+    .toUpperCase()
+    .replace(/-XYZ$/, "")
+    .replace(/-APPLE$/, "")
+    .replace(/-ANDROID$/, "");
+
+  try {
+    const output = execSync(
+      `linear issue list --workspace luke-labs --team "${teamKey}" --limit 10 --json 2>/dev/null`,
+      { encoding: "utf-8" },
+    );
+    const parsed: unknown = JSON.parse(output);
+    if (!Array.isArray(parsed)) return [];
+
+    const issues = parsed
+      .map((issue) => {
+        if (typeof issue !== "object" || issue === null) return null;
+        const record = issue as Record<string, unknown>;
+
+        const identifier = typeof record.identifier === "string" ? record.identifier : "?";
+        const title = typeof record.title === "string" ? record.title : "";
+        const state = typeof record.state === "string" ? record.state : "";
+
+        return `- ${identifier}: ${title} [${state}]`;
+      })
+      .filter((line): line is string => typeof line === "string");
+
+    return issues;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Build the unified prompt for codex
+ */
+export function buildPrompt(project: Project, windowStart: string, windowEnd: string): string {
+  const linearSection = project.linearIssues?.length
+    ? `\nLinear Issues:\n${project.linearIssues.join("\n")}`
+    : "";
+
+  return `<role>Agent Digest Specialist</role>
+
+<context>
+Project: ${project.name}
+Repo: ${project.repo}
+Window: ${windowStart} to ${windowEnd}
+Status: ${project.status.emoji} ${project.status.label} (${project.commits7d} commits, ${project.uncommitted} uncommitted)${linearSection}
+</context>
+
+<workflow>
+Execute these steps in order, then produce output:
+
+**Phase 1: Gather (3-4 min)**
+1. \`git log --since="${windowStart}" --oneline\` - get commit list
+2. \`git diff --stat HEAD~${project.commits7d}\` - get diffstat
+3. Read AGENTS.md or CLAUDE.md (first 200 lines) for project context
+4. \`git show --stat\` on 2-3 key commits to understand changes
+
+**Phase 2: Analyze (2-3 min)**
+5. Group commits into 2-4 work themes by scanning messages
+6. For each theme, identify 1-2 key files and note paths
+7. Check for test files in diffstat (quality signal)
+8. Note any security-related, config, or deletion patterns (risks)
+
+**Phase 3: Synthesize (2-3 min)**
+9. Write status summary based on commit velocity and WIP count
+10. Draft 2-3 recommendations based on risks and patterns
+11. Compile evidence section with file paths from diffstat
+
+**Phase 4: Output**
+12. Produce the digest in the exact format below
+</workflow>
+
+<output_format>
+# ${project.name} ${project.status.emoji}
+
+Repo: \`${project.repo}\`
+Window: ${windowStart} → ${windowEnd}
+
+## Status
+
+- ${project.status.emoji} [One-line health summary with commit/uncommitted counts]. (Confidence: X/10)
+- [Activity pattern observation]. (Confidence: X/10)
+
+## Work Themes & Accomplishments
+
+### 1) [Theme from commits] ([brief description])
+
+- [Finding with file path evidence]. (Confidence: X/10)
+- [Another finding]. (Confidence: X/10)
+
+### 2) [Second theme]...
+
+[2-4 themes total based on commit groupings]
+
+## Linear Issue Correlation
+
+[If Linear issues provided in context, correlate commits with issues. Otherwise skip this section.]
+
+- [PROJ-123: correlates with commits X, Y]. (Confidence: X/10)
+- [PROJ-456: no commits in window, still in backlog]. (Confidence: X/10)
+
+## Quality Signals
+
+- [Test coverage, documentation, CI observations]. (Confidence: X/10)
+
+## Key Risks
+
+- [Risk with evidence if applicable]. (Confidence: X/10)
+
+## Recommendations
+
+1) [Actionable recommendation]. (Confidence: X/10)
+2) [Another recommendation]. (Confidence: X/10)
+
+## Evidence (selected)
+
+- [Description]: \`file/path.ts\`
+- [Description]: \`another/file.ts\`
+
+## Commits (last 7 days)
+
+\`\`\`text
+[Full git log output from step 1]
+\`\`\`
+
+## Diffstat (HEAD~N)
+
+\`\`\`text
+[Full diffstat output from step 2]
+\`\`\`
+</output_format>
+
+<constraints>
+- READ-ONLY: Do NOT modify any files
+- Every claim needs a confidence score (1-10)
+- Include file paths as evidence where applicable
+- Produce output after completing workflow - don't loop back
+- If a step fails, note it and continue
+</constraints>`;
+}
+
+/**
+ * Run digest for a single project
+ */
+export async function runDigest(
+  project: Project,
+  outputDir: string,
+  windowStart: string,
+  windowEnd: string,
+): Promise<DigestResult> {
+  const promptPath = join(outputDir, `${project.name}-prompt.md`);
+  const rawPath = join(outputDir, `${project.name}-raw.txt`);
+  const digestPath = join(outputDir, `${project.name}-digest.md`);
+
+  // Build and write prompt
+  const prompt = buildPrompt(project, windowStart, windowEnd);
+  writeFileSync(promptPath, prompt);
+
+  return new Promise((resolve) => {
+    // Spawn codex
+    const codex = spawn("codex", ["exec", "-", "--dangerously-bypass-approvals-and-sandbox"], {
+      cwd: project.repo,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    codex.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    codex.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    codex.stdin.write(prompt);
+    codex.stdin.end();
+
+    codex.on("close", (code) => {
+      // Write raw output
+      writeFileSync(rawPath, stdout);
+
+      // Post-process to extract digest
+      let digest = "";
+      const lines = stdout.split("\n");
+      const codexIndex = lines.lastIndexOf("codex");
+      if (codexIndex >= 0) {
+        digest = lines
+          .slice(codexIndex + 1)
+          .join("\n")
+          .trim();
+      }
+
+      if (!digest) {
+        // Fallback: remove thinking blocks
+        digest = stdout
+          .split("\n")
+          .filter((l) => !l.startsWith("thinking") && !l.startsWith("**"))
+          .join("\n")
+          .trim();
+      }
+
+      writeFileSync(digestPath, digest);
+
+      const rawBytes = stdout.length;
+      const digestBytes = digest.length;
+
+      resolve({
+        project: project.name,
+        repo: project.repo,
+        status: project.status,
+        rawPath,
+        digestPath,
+        rawBytes,
+        digestBytes,
+        success: code === 0 && digestBytes > 0,
+        error: code !== 0 ? `Exit code ${code}: ${stderr}` : undefined,
+      });
+    });
+
+    codex.on("error", (err) => {
+      resolve({
+        project: project.name,
+        repo: project.repo,
+        status: project.status,
+        rawPath,
+        digestPath,
+        rawBytes: 0,
+        digestBytes: 0,
+        success: false,
+        error: err.message,
+      });
+    });
+  });
+}
+
+/**
+ * Run digests for multiple projects with concurrency control
+ */
+export async function runDigests(options: DigestOptions): Promise<DigestResult[]> {
+  const { projects: projectNames, outputDir, days = 7, concurrency = 2, linear = true } = options;
+
+  // Ensure output dir exists
+  mkdirSync(outputDir, { recursive: true });
+
+  // Calculate window
+  const windowEnd = new Date();
+  const windowStart = new Date();
+  windowStart.setDate(windowStart.getDate() - days);
+  const windowStartStr = windowStart.toISOString().split("T")[0];
+  const windowEndStr = windowEnd.toISOString().split("T")[0];
+
+  // Resolve projects
+  const resolvedProjects: Project[] = [];
+  for (const name of projectNames) {
+    const repo = resolveProject(name);
+    if (!repo) {
+      console.error(`Project not found: ${name}`);
+      continue;
+    }
+
+    // Get git stats
+    let commits = 0;
+    let uncommitted = 0;
+    let branch = "main";
+
+    try {
+      const log = execSync(
+        `git -C "${repo}" log --since="${windowStartStr}" --oneline 2>/dev/null`,
+        {
+          encoding: "utf-8",
+        },
+      );
+      commits = log.trim().split("\n").filter(Boolean).length;
+
+      const status = execSync(`git -C "${repo}" status --porcelain 2>/dev/null`, {
+        encoding: "utf-8",
+      });
+      uncommitted = status.trim().split("\n").filter(Boolean).length;
+
+      branch =
+        execSync(`git -C "${repo}" branch --show-current 2>/dev/null`, {
+          encoding: "utf-8",
+        }).trim() || "main";
+    } catch {
+      // ignore
+    }
+
+    const project: Project = {
+      name: basename(repo),
+      repo,
+      commits7d: commits,
+      uncommitted,
+      branch,
+      status: calculateStatus(commits, uncommitted),
+    };
+
+    // Fetch Linear issues if enabled
+    if (linear) {
+      project.linearIssues = fetchLinearIssues(project.name);
+    }
+
+    resolvedProjects.push(project);
+  }
+
+  // Run with concurrency control
+  const results: DigestResult[] = [];
+  for (let i = 0; i < resolvedProjects.length; i += concurrency) {
+    const batch = resolvedProjects.slice(i, i + concurrency);
+    const batchResults = await Promise.all(
+      batch.map((p) => runDigest(p, outputDir, windowStartStr, windowEndStr)),
+    );
+    results.push(...batchResults);
+  }
+
+  return results;
+}

package/src/lib/docs/lint.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { join, sep } from "node:path";
+import { lintAgentsDocs } from "./lint";
+
+function createTempDir(prefix: string): string {
+  const root = join(process.cwd(), ".tmp-tests");
+  mkdirSync(root, { recursive: true });
+  const dir = join(root, `${prefix}-${randomUUID()}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function cleanupTemp(dir: string): void {
+  const marker = `${sep}.tmp-tests${sep}`;
+  if (!dir.includes(marker)) return;
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function writeAgentsDoc(dir: string, content: string): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "AGENTS.md"), content);
+  try {
+    symlinkSync("AGENTS.md", join(dir, "CLAUDE.md"));
+  } catch {
+    writeFileSync(join(dir, "CLAUDE.md"), content);
+  }
+}
+
+describe("lintAgentsDocs", () => {
+  test("scans apps/packages/utils but not forks", () => {
+    const workspaceRoot = createTempDir("docs-lint");
+    try {
+      // Good doc under apps
+      writeAgentsDoc(join(workspaceRoot, "apps", "good", "repo"), "# Good\n\n## Notes\n\nHello.");
+
+      // Bad doc under forks (should not be scanned)
+      mkdirSync(join(workspaceRoot, "forks", "bad"), { recursive: true });
+      writeFileSync(join(workspaceRoot, "forks", "bad", "AGENTS.md"), "## Bad");
+
+      const result = lintAgentsDocs({
+        workspaceRoot,
+        warnShortWordsUnder: 0,
+        warnLongWordsOver: Number.MAX_SAFE_INTEGER,
+      });
+
+      expect(result.errors).toBe(0);
+      expect(result.agentsFiles).toBe(1);
+    } finally {
+      cleanupTemp(workspaceRoot);
+    }
+  });
+
+  test("flags missing H1", () => {
+    const workspaceRoot = createTempDir("docs-lint");
+    try {
+      writeAgentsDoc(join(workspaceRoot, "apps", "missing-h1"), "## Only H2\n\nText.");
+
+      const result = lintAgentsDocs({
+        workspaceRoot,
+        warnShortWordsUnder: 0,
+        warnLongWordsOver: Number.MAX_SAFE_INTEGER,
+      });
+
+      expect(result.issues.some((i) => i.type === "missing-h1")).toBe(true);
+      expect(result.ok).toBe(false);
+    } finally {
+      cleanupTemp(workspaceRoot);
+    }
+  });
+
+  test("flags XML-ish AGENTS.md", () => {
+    const workspaceRoot = createTempDir("docs-lint");
+    try {
+      writeAgentsDoc(
+        join(workspaceRoot, "utils", "xmlish"),
+        "<INSTRUCTIONS>\n  <foo>bar</foo>\n</INSTRUCTIONS>\n",
+      );
+
+      const result = lintAgentsDocs({
+        workspaceRoot,
+        warnShortWordsUnder: 0,
+        warnLongWordsOver: Number.MAX_SAFE_INTEGER,
+      });
+
+      expect(result.issues.some((i) => i.type === "xmlish-agents")).toBe(true);
+      expect(result.ok).toBe(false);
+    } finally {
+      cleanupTemp(workspaceRoot);
+    }
+  });
+
+  test("reports duplicate clusters without failing", () => {
+    const workspaceRoot = createTempDir("docs-lint");
+    try {
+      const content = "# Template\n\n## Notes\n\nSame everywhere.";
+      writeAgentsDoc(join(workspaceRoot, "apps", "a"), content);
+      writeAgentsDoc(join(workspaceRoot, "packages", "b"), content);
+
+      const result = lintAgentsDocs({
+        workspaceRoot,
+        warnShortWordsUnder: 0,
+        warnLongWordsOver: Number.MAX_SAFE_INTEGER,
+      });
+
+      expect(result.ok).toBe(true);
+      expect(result.duplicateGroups.length).toBe(1);
+      expect(result.duplicateGroups[0]?.count).toBe(2);
+    } finally {
+      cleanupTemp(workspaceRoot);
+    }
+  });
+
+  test("flags inverted symlink direction (AGENTS.md → CLAUDE.md)", () => {
+    const workspaceRoot = createTempDir("docs-lint");
+    try {
+      const dir = join(workspaceRoot, "apps", "inverted");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, "CLAUDE.md"), "# Inverted\n");
+      symlinkSync("CLAUDE.md", join(dir, "AGENTS.md"));
+
+      const result = lintAgentsDocs({
+        workspaceRoot,
+        warnShortWordsUnder: 0,
+        warnLongWordsOver: Number.MAX_SAFE_INTEGER,
+      });
+
+      expect(result.issues.some((i) => i.type === "agents-inverted-symlink")).toBe(true);
+      expect(result.ok).toBe(false);
+    } finally {
+      cleanupTemp(workspaceRoot);
+    }
+  });
+});