anidb-client 1.0.0__tar.gz

anidb_client-1.0.0/.claude/agents/scripts/ci-drift-detector.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+/**
+ * CI invocation script for the drift detector agent.
+ *
+ * Determines the diff, passes it to Claude via the Agent SDK with the
+ * drift-detector agent instructions as system prompt, and exits with
+ * the appropriate code:
+ *   0 — no drift detected
+ *   1 — drift detected
+ *   2 — infrastructure error
+ */
+
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// --- Structured output schema ---
+
+const driftSchema = {
+  type: "object",
+  properties: {
+    drift_detected: { type: "boolean" },
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file: { type: "string" },
+          lines: { type: "string" },
+          affected_artifact: { type: "string" },
+          justification: { type: "string" },
+          suggestion: { type: "string" },
+        },
+        required: ["file", "affected_artifact", "justification", "suggestion"],
+      },
+    },
+    summary: { type: "string" },
+  },
+  required: ["drift_detected", "findings", "summary"],
+};
+
+// --- Helpers ---
+
+function git(cmd) {
+  return execSync(`git ${cmd}`, { encoding: "utf-8" }).trim();
+}
+
+function parseArgs(argv) {
+  const args = { base: null, head: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--base" && argv[i + 1]) {
+      args.base = argv[++i];
+    } else if (argv[i] === "--head" && argv[i + 1]) {
+      args.head = argv[++i];
+    }
+  }
+  return args;
+}
+
+function determineDiff(cliArgs) {
+  // 1. Explicit CLI refs
+  if (cliArgs.base && cliArgs.head) {
+    return git(`diff ${cliArgs.base}..${cliArgs.head}`);
+  }
+
+  // 2. GitLab MR pipeline — diff the MR base against current commit
+  const mrBase = process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+  const commitSha = process.env.CI_COMMIT_SHA;
+  if (mrBase && commitSha) {
+    return git(`diff ${mrBase}..${commitSha}`);
+  }
+
+  // 3. Branch pipeline — diff against merge base with default branch
+  const branch = process.env.CI_COMMIT_BRANCH;
+  const defaultBranch = process.env.CI_DEFAULT_BRANCH;
+  if (branch && defaultBranch) {
+    if (branch === defaultBranch) {
+      // On main: diff the latest commit only
+      return git("diff HEAD~1..HEAD");
+    }
+    // Feature branch: deepen history and fetch default branch to find merge base
+    try { git("fetch --unshallow"); } catch {}
+    git(`fetch origin ${defaultBranch}`);
+    const mergeBase = git(`merge-base origin/${defaultBranch} HEAD`);
+    return git(`diff ${mergeBase}..HEAD`);
+  }
+
+  // 4. Cannot determine — fail explicitly
+  console.error(
+    "Error: Cannot determine diff. Provide --base and --head, " +
+      "or run in a GitLab MR/branch pipeline.",
+  );
+  process.exit(2);
+}
+
+function formatFindings(result) {
+  if (!result.drift_detected || result.findings.length === 0) {
+    console.log("No drift detected.");
+    return;
+  }
+
+  for (const f of result.findings) {
+    const location = f.lines ? `${f.file}:${f.lines}` : f.file;
+    console.log(`DRIFT: ${location}`);
+    console.log(`  Affected: ${f.affected_artifact}`);
+    console.log(`  Reason: ${f.justification}`);
+    console.log(`  Suggestion: ${f.suggestion}`);
+    console.log();
+  }
+
+  if (result.summary) {
+    console.log(result.summary);
+  }
+}
+
+// --- Main ---
+
+async function main() {
+  const cliArgs = parseArgs(process.argv);
+  const diff = determineDiff(cliArgs);
+
+  if (!diff) {
+    console.log("Empty diff — nothing to check.");
+    process.exit(0);
+  }
+
+  // Read the agent instructions from the markdown file (strip frontmatter)
+  const agentPath = join(process.cwd(), ".claude", "agents", "drift-detector.md");
+  const agentRaw = readFileSync(agentPath, "utf-8");
+  const agentPrompt = agentRaw.replace(/^---[\s\S]*?---\n*/, "");
+
+  const prompt = [
+    "Analyze the following diff for drift against the project's specs, ADRs, tests, and navigation aids.",
+    "",
+    "```diff",
+    diff,
+    "```",
+  ].join("\n");
+
+  let structured = null;
+  let resultMessage = null;
+
+  for await (const message of query({
+    prompt,
+    options: {
+      systemPrompt: agentPrompt,
+      allowedTools: ["Read", "Glob", "Grep", "Bash"],
+      permissionMode: "acceptEdits",
+      settingSources: ["project"],
+      cwd: process.cwd(),
+      outputFormat: {
+        type: "json_schema",
+        schema: driftSchema,
+      },
+    },
+  })) {
+    if (message.type === "result") {
+      resultMessage = message;
+      structured = message.structured_output;
+    }
+  }
+
+  if (!resultMessage) {
+    console.error("Error: No result received from drift detector.");
+    process.exit(2);
+  }
+
+  // Try structured_output first, fall back to parsing result text
+  if (!structured && resultMessage.result) {
+    try {
+      structured = JSON.parse(resultMessage.result);
+    } catch {
+      console.error("Error: Failed to parse result as JSON.");
+      console.error(resultMessage.result);
+      process.exit(2);
+    }
+  }
+
+  if (!structured) {
+    console.error("Error: No output from drift detector.");
+    process.exit(2);
+  }
+
+  formatFindings(structured);
+  process.exit(structured.drift_detected ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error("Error: Drift detection failed.");
+  console.error(err.message || err);
+  if (err.stack) console.error(err.stack);
+  process.exit(2);
+});

anidb_client-1.0.0/.claude/skills/adr/scripts/generate_index.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Validate ADR frontmatter and generate docs/decisions/INDEX.md."""
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+DECISIONS_DIR = Path(__file__).resolve().parent.parent.parent.parent.parent / "docs" / "decisions"
+INDEX_PATH = DECISIONS_DIR / "INDEX.md"
+FILENAME_RE = re.compile(r"^ADR-(\d{3})-[\w-]+\.md$")
+VALID_STATUSES = {"draft", "accepted"}
+REQUIRED_FIELDS = ("title", "description", "status", "tags")
+REQUIRED_SECTIONS = ("Context", "Decision", "Consequences")
+
+
+def parse_frontmatter(path: Path) -> dict | None:
+    """Extract YAML frontmatter from a file. Returns None if no frontmatter."""
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return None
+    end = text.find("---", 3)
+    if end == -1:
+        return None
+    raw = text[3:end]
+    return yaml.safe_load(raw)
+
+
+def validate_adrs(adr_files: list[Path]) -> tuple[list[dict], list[str], list[str]]:
+    """Validate all ADR files. Returns (parsed entries, errors, warnings)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    entries: list[dict] = []
+
+    for path in adr_files:
+        name = path.name
+        match = FILENAME_RE.match(name)
+        if not match:
+            errors.append(f"ERROR [{name}]: Filename doesn't match ADR-NNN-slug.md pattern")
+            continue
+
+        number = int(match.group(1))
+        fm = parse_frontmatter(path)
+
+        if fm is None:
+            errors.append(f"ERROR [{name}]: Missing YAML frontmatter entirely")
+            continue
+
+        file_errors = False
+        for field in REQUIRED_FIELDS:
+            if not fm.get(field):
+                errors.append(f"ERROR [{name}]: Missing required field: {field}")
+                file_errors = True
+
+        status = fm.get("status", "")
+        if status == "draft":
+            errors.append(f"ERROR [{name}]: status is 'draft' (signals incomplete work)")
+            file_errors = True
+        elif status and status not in VALID_STATUSES:
+            errors.append(f"ERROR [{name}]: Unrecognized status '{status}' (expected 'draft' or 'accepted')")
+            file_errors = True
+
+        # Check required body sections
+        text = path.read_text(encoding="utf-8")
+        body = text.split("---", 2)[-1] if text.startswith("---") else text
+        for section in REQUIRED_SECTIONS:
+            if not re.search(rf"^#{{1,6}}\s+{section}\b", body, re.MULTILINE):
+                errors.append(f"ERROR [{name}]: Missing required section: {section}")
+                file_errors = True
+
+        if not file_errors:
+            entries.append(
+                {
+                    "number": number,
+                    "filename": name,
+                    "title": fm["title"],
+                    "description": fm["description"],
+                    "status": fm["status"],
+                    "tags": ", ".join(fm.get("tags", [])),
+                }
+            )
+
+    return entries, errors, warnings
+
+
+def generate_index(entries: list[dict]) -> str:
+    """Generate INDEX.md content from validated entries."""
+    entries.sort(key=lambda e: e["number"])
+
+    lines = [
+        "<!-- AUTO-GENERATED by .claude/skills/adr/scripts/generate_index.py — do not edit manually -->",
+        "",
+        "# Architecture Decision Records",
+        "",
+        "| Number | Title | Description | Status | Tags |",
+        "|--------|-------|-------------|--------|------|",
+    ]
+
+    for e in entries:
+        num = f"ADR-{e['number']:03d}"
+        link = f"[{num}]({e['filename']})"
+        lines.append(f"| {link} | {e['title']} | {e['description']} | {e['status']} | {e['tags']} |")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    if not DECISIONS_DIR.is_dir():
+        print(f"ERROR: Directory not found: {DECISIONS_DIR}", file=sys.stderr)
+        return 1
+
+    adr_files = sorted(DECISIONS_DIR.glob("ADR-*.md"))
+    if not adr_files:
+        print("No ADR files found.", file=sys.stderr)
+        return 1
+
+    entries, errors, warnings = validate_adrs(adr_files)
+
+    for w in warnings:
+        print(w, file=sys.stderr)
+    for e in errors:
+        print(e, file=sys.stderr)
+
+    if errors:
+        print(f"\n{len(errors)} error(s) found. Fix them before INDEX.md can be generated.", file=sys.stderr)
+        return 1
+
+    index_content = generate_index(entries)
+
+    # --check verifies the committed index without writing, for CI. Done here rather
+    # than by regenerating and diffing with git, because the image this runs in is a
+    # Python toolchain and carries no git -- and adding one to compare two strings
+    # would be an unpinned apt package in the supply chain for no gain.
+    if "--check" in sys.argv[1:]:
+        committed = INDEX_PATH.read_text(encoding="utf-8") if INDEX_PATH.is_file() else None
+        if committed != index_content:
+            print(
+                f"ERROR: {INDEX_PATH} is out of date with the ADR frontmatter.\n"
+                f"Run `task adr-index` and commit the result.",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"{INDEX_PATH} is up to date ({len(entries)} entries).")
+        return 0
+
+    INDEX_PATH.write_text(index_content, encoding="utf-8")
+    print(f"Generated {INDEX_PATH} with {len(entries)} entries.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

anidb_client-1.0.0/.claude/skills/spec/scripts/generate_index.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Validate spec frontmatter and generate docs/specs/INDEX.md."""
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+SPECS_DIR = Path(__file__).resolve().parent.parent.parent.parent.parent / "docs" / "specs"
+INDEX_PATH = SPECS_DIR / "INDEX.md"
+FILENAME_RE = re.compile(r"^SPEC-(\d{3})-[\w-]+\.md$")
+VALID_STATUSES = {"draft", "accepted"}
+REQUIRED_FIELDS = ("title", "description", "status", "tags")
+
+
+def parse_frontmatter(path: Path) -> dict | None:
+    """Extract YAML frontmatter from a file. Returns None if no frontmatter."""
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return None
+    end = text.find("---", 3)
+    if end == -1:
+        return None
+    raw = text[3:end]
+    return yaml.safe_load(raw)
+
+
+def validate_specs(spec_files: list[Path]) -> tuple[list[dict], list[str], list[str]]:
+    """Validate all spec files. Returns (parsed entries, errors, warnings)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    entries: list[dict] = []
+
+    for path in spec_files:
+        name = path.name
+        match = FILENAME_RE.match(name)
+        if not match:
+            errors.append(f"ERROR [{name}]: Filename doesn't match SPEC-NNN-slug.md pattern")
+            continue
+
+        number = int(match.group(1))
+        fm = parse_frontmatter(path)
+
+        if fm is None:
+            errors.append(f"ERROR [{name}]: Missing YAML frontmatter entirely")
+            continue
+
+        file_errors = False
+        for field in REQUIRED_FIELDS:
+            if not fm.get(field):
+                errors.append(f"ERROR [{name}]: Missing required field: {field}")
+                file_errors = True
+
+        status = fm.get("status", "")
+        if status == "draft":
+            errors.append(f"ERROR [{name}]: status is 'draft' (signals incomplete work)")
+            file_errors = True
+        elif status and status not in VALID_STATUSES:
+            errors.append(f"ERROR [{name}]: Unrecognized status '{status}' (expected 'draft' or 'accepted')")
+            file_errors = True
+
+        if not file_errors:
+            entries.append(
+                {
+                    "number": number,
+                    "filename": name,
+                    "title": fm["title"],
+                    "description": fm["description"],
+                    "status": fm["status"],
+                    "tags": ", ".join(fm.get("tags", [])),
+                }
+            )
+
+    return entries, errors, warnings
+
+
+def generate_index(entries: list[dict]) -> str:
+    """Generate INDEX.md content from validated entries."""
+    entries.sort(key=lambda e: e["number"])
+
+    lines = [
+        "<!-- AUTO-GENERATED by .claude/skills/spec/scripts/generate_index.py — do not edit manually -->",
+        "",
+        "# Specifications",
+        "",
+        "| Number | Title | Description | Status | Tags |",
+        "|--------|-------|-------------|--------|------|",
+    ]
+
+    for e in entries:
+        num = f"SPEC-{e['number']:03d}"
+        link = f"[{num}]({e['filename']})"
+        lines.append(f"| {link} | {e['title']} | {e['description']} | {e['status']} | {e['tags']} |")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    if not SPECS_DIR.is_dir():
+        print(f"ERROR: Directory not found: {SPECS_DIR}", file=sys.stderr)
+        return 1
+
+    spec_files = sorted(SPECS_DIR.glob("SPEC-*.md"))
+    if not spec_files:
+        print("No spec files found.", file=sys.stderr)
+        return 1
+
+    entries, errors, warnings = validate_specs(spec_files)
+
+    for w in warnings:
+        print(w, file=sys.stderr)
+    for e in errors:
+        print(e, file=sys.stderr)
+
+    if errors:
+        print(f"\n{len(errors)} error(s) found. Fix them before INDEX.md can be generated.", file=sys.stderr)
+        return 1
+
+    index_content = generate_index(entries)
+
+    # --check verifies the committed index without writing, for CI. Done here rather
+    # than by regenerating and diffing with git, because the image this runs in is a
+    # Python toolchain and carries no git -- and adding one to compare two strings
+    # would be an unpinned apt package in the supply chain for no gain.
+    if "--check" in sys.argv[1:]:
+        committed = INDEX_PATH.read_text(encoding="utf-8") if INDEX_PATH.is_file() else None
+        if committed != index_content:
+            print(
+                f"ERROR: {INDEX_PATH} is out of date with the spec frontmatter.\n"
+                f"Run `task spec-index` and commit the result.",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"{INDEX_PATH} is up to date ({len(entries)} entries).")
+        return 0
+
+    INDEX_PATH.write_text(index_content, encoding="utf-8")
+    print(f"Generated {INDEX_PATH} with {len(entries)} entries.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

anidb_client-1.0.0/.gitignore

@@ -0,0 +1,67 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtualenvs / environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv-cache/
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.cache/
+.tox/
+
+# Test / coverage reports
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+report.xml
+junit.xml
+gl-code-quality-report.json
+
+# Local cache written by the anime-titles / anime-list fetchers when a developer
+# points them at the working tree instead of the system temp dir.
+*.xml.gz
+
+# Sphinx documentation
+docs/_build/
+
+# Secrets — never commit. The library reads credentials from a netrc file.
+.netrc
+*.netrc
+
+# Local scratch databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Editor / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/