@creativeintelligence/abbie 0.1.4 → 0.1.6

package/src/lib/docs/lint.ts

@@ -1,310 +0,0 @@
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, relative } from "node:path";
-
-export type AgentsDocsLintSeverity = "error" | "warn";
-
-export type AgentsDocsLintIssueType =
-  | "missing-claude"
-  | "claude-not-symlink"
-  | "claude-wrong-target"
-  | "agents-is-symlink"
-  | "agents-inverted-symlink"
-  | "missing-h1"
-  | "no-headings"
-  | "xmlish-agents"
-  | "short-doc"
-  | "long-doc";
-
-export type AgentsDocsLintIssue = {
-  type: AgentsDocsLintIssueType;
-  severity: AgentsDocsLintSeverity;
-  path: string;
-  detail: string;
-};
-
-export type AgentsDocsDuplicateGroup = {
-  hash: string;
-  count: number;
-  paths: string[];
-};
-
-export type AgentsDocsLintResult = {
-  ok: boolean;
-  workspaceRoot: string;
-  includedRoots: string[];
-  agentsFiles: number;
-  errors: number;
-  warnings: number;
-  issues: AgentsDocsLintIssue[];
-  duplicateGroups: AgentsDocsDuplicateGroup[];
-  exitCode?: number;
-};
-
-export type AgentsDocsLintOptions = {
-  workspaceRoot?: string;
-  include?: string[];
-  ignoreDirNames?: string[];
-  warnShortWordsUnder?: number;
-  warnLongWordsOver?: number;
-};
-
-const DEFAULT_IGNORE_DIR_NAMES = [
-  ".git",
-  ".next",
-  ".turbo",
-  ".cache",
-  "node_modules",
-  "dist",
-  "build",
-  "coverage",
-  ".tmp-tests",
-] as const;
-
-function resolveWorkspaceRoot(workspaceRoot?: string): string {
-  if (workspaceRoot) return workspaceRoot;
-  return join(homedir(), "Developer");
-}
-
-function normalizeSymlinkTarget(target: string): string {
-  // readlink can return "AGENTS.md" or "./AGENTS.md" depending on how it was created
-  return target.replace(/^[.][/]/, "");
-}
-
-function normalizeForHash(content: string): string {
-  return content
-    .replace(/\r\n/g, "\n")
-    .replace(/[ \t]+$/gm, "")
-    .trim();
-}
-
-function wordCount(content: string): number {
-  const words = content.trim().split(/\s+/).filter(Boolean);
-  return words.length;
-}
-
-function hasAnyHeading(content: string): boolean {
-  return /^#{1,6}\s+\S/m.test(content);
-}
-
-function hasH1(content: string): boolean {
-  return /^#\s+\S/m.test(content);
-}
-
-function isXmlishAgentsDoc(content: string): boolean {
-  const trimmed = content.trimStart();
-  const firstLine = trimmed.split(/\r?\n/, 1)[0]?.trim() ?? "";
-  if (!firstLine.startsWith("<")) return false;
-  if (hasAnyHeading(content)) return false;
-  const tagLikeCount = (content.match(/<\/?[A-Za-z][^>]*>/g) ?? []).length;
-  return tagLikeCount >= 3;
-}
-
-function* walkForAgentsMd(rootDirs: string[], ignoreDirNames: Set<string>): Generator<string> {
-  const stack = [...rootDirs];
-  while (stack.length > 0) {
-    const dir = stack.pop();
-    if (!dir) continue;
-
-    let entries: Array<import("node:fs").Dirent>;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      // Include AGENTS.md even if it's a symlink so we can validate direction.
-      if (entry.name === "AGENTS.md" && (entry.isFile() || entry.isSymbolicLink())) {
-        yield join(dir, entry.name);
-        continue;
-      }
-
-      // Avoid following symlinked directories (potential cycles).
-      if (entry.isSymbolicLink()) continue;
-
-      if (entry.isDirectory()) {
-        if (ignoreDirNames.has(entry.name)) continue;
-        stack.push(join(dir, entry.name));
-      }
-    }
-  }
-}
-
-export function lintAgentsDocs(options: AgentsDocsLintOptions = {}): AgentsDocsLintResult {
-  const workspaceRoot = resolveWorkspaceRoot(options.workspaceRoot);
-  const include = options.include ?? ["apps", "packages", "utils"];
-  const ignoreDirNames = new Set([...DEFAULT_IGNORE_DIR_NAMES, ...(options.ignoreDirNames ?? [])]);
-
-  const includedRoots = include.map((dir) => join(workspaceRoot, dir)).filter(existsSync);
-  const issues: AgentsDocsLintIssue[] = [];
-  const hashes = new Map<string, { hash: string; paths: string[] }>();
-  let agentsFiles = 0;
-
-  const warnShortWordsUnder = options.warnShortWordsUnder ?? 100;
-  const warnLongWordsOver = options.warnLongWordsOver ?? 2000;
-
-  for (const agentsPath of walkForAgentsMd(includedRoots, ignoreDirNames)) {
-    agentsFiles++;
-    const dir = dirname(agentsPath);
-    const claudePath = join(dir, "CLAUDE.md");
-
-    // ---------------------------------------------------------------------
-    // Symlink checks
-    // ---------------------------------------------------------------------
-    let agentsIsSymlink = false;
-    let agentsTarget: string | undefined;
-    try {
-      agentsIsSymlink = lstatSync(agentsPath).isSymbolicLink();
-      if (agentsIsSymlink) agentsTarget = readlinkSync(agentsPath);
-    } catch {
-      // ignore
-    }
-
-    if (agentsIsSymlink) {
-      const normalizedTarget = agentsTarget ? normalizeSymlinkTarget(agentsTarget) : undefined;
-      if (normalizedTarget === "CLAUDE.md") {
-        issues.push({
-          type: "agents-inverted-symlink",
-          severity: "error",
-          path: agentsPath,
-          detail: "Invalid direction: AGENTS.md → CLAUDE.md (should be canonical file)",
-        });
-      } else {
-        issues.push({
-          type: "agents-is-symlink",
-          severity: "warn",
-          path: agentsPath,
-          detail: `AGENTS.md is a symlink (target: ${agentsTarget ?? "?"})`,
-        });
-      }
-    }
-
-    if (!existsSync(claudePath)) {
-      issues.push({
-        type: "missing-claude",
-        severity: "error",
-        path: agentsPath,
-        detail: "Missing CLAUDE.md (should be symlink → AGENTS.md)",
-      });
-    } else {
-      let claudeIsSymlink = false;
-      let claudeTarget: string | undefined;
-      try {
-        claudeIsSymlink = lstatSync(claudePath).isSymbolicLink();
-        if (claudeIsSymlink) claudeTarget = readlinkSync(claudePath);
-      } catch {
-        // ignore
-      }
-
-      if (!claudeIsSymlink) {
-        issues.push({
-          type: "claude-not-symlink",
-          severity: "warn",
-          path: claudePath,
-          detail: "CLAUDE.md is not a symlink (expected CLAUDE.md → AGENTS.md)",
-        });
-      } else if (normalizeSymlinkTarget(claudeTarget ?? "") !== "AGENTS.md") {
-        issues.push({
-          type: "claude-wrong-target",
-          severity: "error",
-          path: claudePath,
-          detail: `CLAUDE.md points to ${claudeTarget ?? "?"} (expected AGENTS.md)`,
-        });
-      }
-    }
-
-    // ---------------------------------------------------------------------
-    // Content checks
-    // ---------------------------------------------------------------------
-    let content = "";
-    try {
-      content = readFileSync(agentsPath, "utf-8");
-    } catch {
-      continue;
-    }
-
-    if (!hasAnyHeading(content)) {
-      issues.push({
-        type: "no-headings",
-        severity: "error",
-        path: agentsPath,
-        detail: "No Markdown headings found",
-      });
-    }
-
-    if (!hasH1(content)) {
-      issues.push({
-        type: "missing-h1",
-        severity: "error",
-        path: agentsPath,
-        detail: "Missing H1 title (`# ...`)",
-      });
-    }
-
-    if (isXmlishAgentsDoc(content)) {
-      issues.push({
-        type: "xmlish-agents",
-        severity: "error",
-        path: agentsPath,
-        detail: "Appears to be XML-ish (non-Markdown) AGENTS.md",
-      });
-    }
-
-    const words = wordCount(content);
-    if (words > 0 && words < warnShortWordsUnder) {
-      issues.push({
-        type: "short-doc",
-        severity: "warn",
-        path: agentsPath,
-        detail: `Very short doc (${words} words)`,
-      });
-    } else if (words > warnLongWordsOver) {
-      issues.push({
-        type: "long-doc",
-        severity: "warn",
-        path: agentsPath,
-        detail: `Very long doc (${words} words)`,
-      });
-    }
-
-    // ---------------------------------------------------------------------
-    // Duplicate detection
-    // ---------------------------------------------------------------------
-    const normalized = normalizeForHash(content);
-    const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 12);
-    const group = hashes.get(hash);
-    if (group) {
-      group.paths.push(agentsPath);
-    } else {
-      hashes.set(hash, { hash, paths: [agentsPath] });
-    }
-  }
-
-  const duplicateGroups: AgentsDocsDuplicateGroup[] = Array.from(hashes.values())
-    .filter((g) => g.paths.length > 1)
-    .map((g) => ({
-      hash: g.hash,
-      count: g.paths.length,
-      paths: [...g.paths].sort((a, b) => a.localeCompare(b)),
-    }))
-    .sort((a, b) => b.count - a.count || a.hash.localeCompare(b.hash));
-
-  const errors = issues.filter((i) => i.severity === "error").length;
-  const warnings = issues.filter((i) => i.severity === "warn").length;
-
-  // By default, duplicates do not fail the run. They’re a drift report.
-  const ok = errors === 0;
-
-  return {
-    ok,
-    workspaceRoot,
-    includedRoots: includedRoots.map((p) => relative(workspaceRoot, p) || p),
-    agentsFiles,
-    errors,
-    warnings,
-    issues: issues.sort((a, b) => a.path.localeCompare(b.path)),
-    duplicateGroups,
-  };
-}

package/src/lib/docs/sync.ts

@@ -1,184 +0,0 @@
-import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, relative } from "node:path";
-
-export type AgentsDocsSyncOptions = {
-  workspaceRoot?: string;
-  include?: string[];
-  dryRun?: boolean;
-  ignoreDirNames?: string[];
-};
-
-export type AgentsDocsSyncResult = {
-  ok: boolean;
-  workspaceRoot: string;
-  includedRoots: string[];
-  scanned: number;
-  updated: number;
-  skipped: number;
-  dryRun: boolean;
-  touchedPaths: string[];
-  skippedPaths: Array<{ path: string; reason: string }>;
-};
-
-const DEFAULT_INCLUDE = ["apps", "packages", "utils"] as const;
-const DEFAULT_IGNORE_DIR_NAMES = [
-  ".git",
-  ".next",
-  ".turbo",
-  ".cache",
-  "node_modules",
-  "dist",
-  "build",
-  "coverage",
-  ".tmp-tests",
-  ".build",
-  "checkouts",
-  "vendor",
-  "Pods",
-  "DerivedData",
-  "target",
-] as const;
-
-const SPAWN_PROTOCOL_MARKER = "## Agent Spawn Protocol (Recommended)";
-
-const SPAWN_PROTOCOL_BLOCK = `${SPAWN_PROTOCOL_MARKER}
-
-When spawning sub-agents, prefer skill-aware orchestration for better routing and reuse:
-
-1. Choose a relevant skill when possible (for example: \`use convex-god skill\`).
-2. Build or compose prompt context with \`prompts build\`.
-3. Spawn via tracked sessions: \`abbie session start --await --json -q\`.
-4. If no skill applies, continue without blocking and log rationale in the session summary.
-
-Canonical pattern:
-
-\`\`\`bash
-PROMPT=$(prompts build /agent --json --quiet | jq -r '.content')
-printf "%s\\n\\n%s" "$PROMPT" "use convex-god skill" | \\
-  abbie session start -a codex -p <project> -s convex-god --await --json -q
-\`\`\`
-`;
-
-function resolveWorkspaceRoot(workspaceRoot?: string): string {
-  if (workspaceRoot) return workspaceRoot;
-  return join(homedir(), "Developer");
-}
-
-function hasAnyHeading(content: string): boolean {
-  return /^#{1,6}\s+\S/m.test(content);
-}
-
-function isXmlishAgentsDoc(content: string): boolean {
-  const trimmed = content.trimStart();
-  const firstLine = trimmed.split(/\r?\n/, 1)[0]?.trim() ?? "";
-  if (!firstLine.startsWith("<")) return false;
-  if (hasAnyHeading(content)) return false;
-  const tagLikeCount = (content.match(/<\/?[A-Za-z][^>]*>/g) ?? []).length;
-  return tagLikeCount >= 3;
-}
-
-function* walkForAgentsMd(rootDirs: string[], ignoreDirNames: Set<string>): Generator<string> {
-  const stack = [...rootDirs];
-  while (stack.length > 0) {
-    const dir = stack.pop();
-    if (!dir) continue;
-
-    let entries: Array<import("node:fs").Dirent>;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name);
-
-      if (entry.name === "AGENTS.md" && (entry.isFile() || entry.isSymbolicLink())) {
-        yield fullPath;
-        continue;
-      }
-
-      if (entry.isSymbolicLink()) continue;
-      if (entry.isDirectory()) {
-        if (ignoreDirNames.has(entry.name)) continue;
-        stack.push(fullPath);
-      }
-    }
-  }
-}
-
-function appendSpawnProtocolBlock(content: string): string {
-  const trimmed = content.trimEnd();
-  if (trimmed.length === 0) return `${SPAWN_PROTOCOL_BLOCK}\n`;
-  return `${trimmed}\n\n${SPAWN_PROTOCOL_BLOCK}\n`;
-}
-
-export function syncAgentsDocs(options: AgentsDocsSyncOptions = {}): AgentsDocsSyncResult {
-  const workspaceRoot = resolveWorkspaceRoot(options.workspaceRoot);
-  const include = options.include ?? [...DEFAULT_INCLUDE];
-  const dryRun = options.dryRun ?? false;
-
-  const ignoreDirNames = new Set([...DEFAULT_IGNORE_DIR_NAMES, ...(options.ignoreDirNames ?? [])]);
-  const includedRoots = include.map((dir) => join(workspaceRoot, dir)).filter(existsSync);
-
-  const touchedPaths: string[] = [];
-  const skippedPaths: Array<{ path: string; reason: string }> = [];
-  let scanned = 0;
-
-  for (const agentsPath of walkForAgentsMd(includedRoots, ignoreDirNames)) {
-    scanned++;
-
-    try {
-      if (lstatSync(agentsPath).isSymbolicLink()) {
-        skippedPaths.push({ path: agentsPath, reason: "AGENTS.md is symlink" });
-        continue;
-      }
-    } catch {
-      skippedPaths.push({ path: agentsPath, reason: "lstat failed" });
-      continue;
-    }
-
-    let content = "";
-    try {
-      content = readFileSync(agentsPath, "utf-8");
-    } catch {
-      skippedPaths.push({ path: agentsPath, reason: "read failed" });
-      continue;
-    }
-
-    if (isXmlishAgentsDoc(content)) {
-      skippedPaths.push({ path: agentsPath, reason: "xml-ish doc" });
-      continue;
-    }
-
-    if (content.includes(SPAWN_PROTOCOL_MARKER)) {
-      skippedPaths.push({ path: agentsPath, reason: "already has spawn protocol" });
-      continue;
-    }
-
-    const next = appendSpawnProtocolBlock(content);
-    if (!dryRun) {
-      try {
-        writeFileSync(agentsPath, next, "utf-8");
-      } catch {
-        skippedPaths.push({ path: agentsPath, reason: "write failed" });
-        continue;
-      }
-    }
-
-    touchedPaths.push(agentsPath);
-  }
-
-  return {
-    ok: true,
-    workspaceRoot,
-    includedRoots: includedRoots.map((p) => relative(workspaceRoot, p) || p),
-    scanned,
-    updated: touchedPaths.length,
-    skipped: skippedPaths.length,
-    dryRun,
-    touchedPaths: touchedPaths.sort((a, b) => a.localeCompare(b)),
-    skippedPaths: skippedPaths.sort((a, b) => a.path.localeCompare(b.path)),
-  };
-}