harness-auto-docs 0.1.0

package/.nvmrc

@@ -0,0 +1 @@
+24

package/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+This is the entry point for AI coding agents working in this repository.
+Read this file first, then follow the pointers below for deeper context.
+
+## What this project does
+
+`harness-engineering-auto-docs` is a TypeScript CLI that auto-generates Harness Engineering-style
+documentation when a git tag is pushed. It diffs two adjacent tags, selects relevant
+doc targets, calls an LLM (Claude or GPT), writes Markdown files, and opens a GitHub PR.
+
+## Repository map
+
+| Path | Purpose |
+|------|---------|
+| `src/cli.ts` | CLI entry point — env wiring, orchestration, git/PR ops |
+| `src/core/diff.ts` | Extract git diff between last two tags; group changed files |
+| `src/core/relevance.ts` | Select which doc targets to generate from file groups |
+| `src/core/generator.ts` | LLM prompts per target; generate + write file paths |
+| `src/core/writer.ts` | `appendSection` / `createFile` helpers |
+| `src/ai/interface.ts` | `AIProvider` interface |
+| `src/ai/anthropic.ts` | Claude implementation |
+| `src/ai/openai.ts` | OpenAI Chat implementation |
+| `src/providers/interface.ts` | `PlatformProvider` interface |
+| `src/providers/github.ts` | GitHub PR creation/update via Octokit |
+| `src/providers/gitlab.ts` | GitLab stub — **not yet implemented** |
+| `tests/` | Vitest unit + integration tests, diff fixtures |
+| `examples/github-workflow.yml` | Copy into target repos to enable automation |
+
+## Knowledge store
+
+| Document | What it covers |
+|----------|---------------|
+| `ARCHITECTURE.md` | Domain layers, dependency rules, module map |
+| `docs/DESIGN.md` | Design philosophy, key decisions, trade-offs |
+| `docs/QUALITY_SCORE.md` | Per-domain quality grades and gap tracking |
+| `docs/design-docs/index.md` | Index of all per-release design docs |
+| `docs/design-docs/core-beliefs.md` | Agent-first operating principles |
+| `docs/exec-plans/tech-debt-tracker.md` | Known tech debt, active work items |
+| `docs/product-specs/index.md` | Feature spec index |
+| `docs/references/` | Library-specific LLM reference files |
+
+## Conventions
+
+- **Language / runtime**: TypeScript, ESM (`"type": "module"`), Node ≥18, built with `tsc`
+- **Package manager**: pnpm
+- **Test runner**: Vitest (`npm test`)
+- **Build**: `npm run build` → `dist/`
+- **AI dispatch**: model prefix determines provider — `claude-*` → Anthropic, `gpt-*` → OpenAI, `MiniMax-*` → MiniMax (Anthropic-compatible, base URL `https://api.minimax.io/anthropic`)
+- **File grouping heuristics** live in `src/core/diff.ts:groupFiles` — update there first when changing routing logic
+- **Doc target set** is defined in `src/core/relevance.ts` — `CORE_TARGETS` always run; conditional targets gated on file groups
+- **Prompts** are all colocated in `src/core/generator.ts:PROMPTS` — one entry per `DocTarget`
+- **Output paths** are defined in `src/core/generator.ts:writeResult` switch — keep in sync with README table
+
+## Required environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `AI_MODEL` | Model name: `claude-sonnet-4-6`, `gpt-4o`, etc. |
+| `AI_API_KEY` | Anthropic or OpenAI API key |
+| `GITHUB_TOKEN` | GitHub PAT or Actions token |
+
+## How to extend
+
+1. Add a new `DocTarget` literal to the union in `src/core/relevance.ts`
+2. Add an entry to `CORE_TARGETS` or a conditional push in `selectTargets`
+3. Add a prompt function in `PROMPTS` in `src/core/generator.ts`
+4. Add an output path case in `writeResult`
+5. Add tests in `tests/core/`

package/ARCHITECTURE.md

@@ -0,0 +1,123 @@
+# ARCHITECTURE.md
+
+Top-level architecture of `harness-engineering-auto-docs`.
+See `AGENTS.md` for navigation and `docs/design-docs/` for per-release decisions.
+
+## Overview
+
+`harness-engineering-auto-docs` is a single-binary CLI (Node.js ESM) with no server or database.
+It is invoked once per git tag event, runs to completion, and exits.
+
+```
+CLI entry (src/cli.ts)
+       │
+       ├─ Core pipeline
+       │     ├─ diff.ts       — git diff extraction & file classification
+       │     ├─ relevance.ts  — doc target selection
+       │     ├─ generator.ts  — LLM prompt dispatch & file writing
+       │     └─ writer.ts     — filesystem helpers
+       │
+       ├─ AI layer (src/ai/)
+       │     ├─ interface.ts  — AIProvider { generate(prompt): Promise<string> }
+       │     ├─ anthropic.ts  — AnthropicProvider
+       │     └─ openai.ts     — OpenAIProvider
+       │
+       └─ Platform layer (src/providers/)
+             ├─ interface.ts  — PlatformProvider { createOrUpdatePR(opts) }
+             ├─ github.ts     — GitHubProvider (Octokit)
+             └─ gitlab.ts     — GitLabProvider (stub — NOT IMPLEMENTED)
+```
+
+## Layers and dependency rules
+
+Dependencies flow strictly **downward**. No layer may import from a layer above it.
+
+```
+cli.ts  (orchestration)
+  └── core/  (pure business logic — no AI or platform imports)
+        └── ai/       (AI provider abstraction)
+        └── providers/ (platform PR abstraction)
+```
+
+- `core/` must not import from `ai/` or `providers/` — it accepts them as injected interfaces
+- `ai/` and `providers/` must not import from each other
+- All cross-cutting types (`AIProvider`, `PlatformProvider`) live in `interface.ts` files within their layer
+
+## Data flow
+
+```
+git tag push
+  → GitHub Actions triggers workflow
+  → npx harness-engineering-auto-docs
+      → extractDiff()        reads git history, returns DiffResult
+      → selectTargets()      classifies files, returns DocTarget[]
+      → generateDocs()       calls AI provider in parallel, returns GenerationResult[]
+      → writeResults()       writes/appends Markdown files, returns written paths
+      → git branch + commit + push
+      → createOrUpdatePR()   opens or updates GitHub PR
+```
+
+## Key interfaces
+
+### `DiffResult` (`src/core/diff.ts`)
+
+```typescript
+interface DiffResult {
+  raw: string;           // full git diff text (truncated to 8000 chars in prompts)
+  prevTag: string;       // e.g. "v0.1.0" or "(initial)"
+  currentTag: string;    // e.g. "v0.2.0"
+  changedFiles: string[];
+  fileGroups: FileGroups; // { frontend, schema, auth, infra, other }
+}
+```
+
+### `AIProvider` (`src/ai/interface.ts`)
+
+```typescript
+interface AIProvider {
+  generate(prompt: string): Promise<string>;
+}
+```
+
+### `PlatformProvider` (`src/providers/interface.ts`)
+
+```typescript
+interface PlatformProvider {
+  createOrUpdatePR(opts: PROptions): Promise<string>; // returns PR URL
+}
+```
+
+## Doc output layout (in target repositories)
+
+```
+<repo-root>/
+├── AGENTS.md
+├── ARCHITECTURE.md
+├── changelog/
+│   └── vX.Y.Z.md
+└── docs/
+    ├── DESIGN.md
+    ├── QUALITY_SCORE.md
+    ├── FRONTEND.md          (conditional)
+    ├── SECURITY.md          (conditional)
+    ├── RELIABILITY.md       (conditional)
+    ├── design-docs/
+    │   ├── index.md
+    │   └── vX.Y.Z.md
+    ├── exec-plans/
+    │   └── tech-debt-tracker.md
+    ├── generated/
+    │   └── db-schema.md  (conditional)
+    ├── product-specs/
+    │   └── index.md      (conditional)
+    └── references/
+        └── <lib>-llms.txt (conditional)
+```
+
+## Constraints
+
+- **No global state** — all state flows through function arguments
+- **Parallel AI calls** — `generateDocs` uses `Promise.all`; each target is independent
+- **Diff truncation** — prompts cap raw diff at 8 000 characters (see `PROMPTS` in `generator.ts`)
+- **ESM only** — all imports use `.js` extensions per NodeNext module resolution
+- **Strict TypeScript** — `strict: true` in `tsconfig.json`; no `any` types

package/README.md

@@ -0,0 +1,52 @@
+# harness-engineering-auto-docs
+
+Auto-generate [Harness Engineering](https://openai.com/research/harness-engineering) style documentation when your project creates a git tag. Opens a PR with updated docs.
+
+## Usage
+
+Add `.github/workflows/harness-docs.yml` to your project (see `examples/github-workflow.yml`), then set:
+
+- `AI_API_KEY` — your Anthropic, OpenAI, or MiniMax API key (repository secret)
+- `AI_MODEL` — model name, e.g. `claude-sonnet-4-6`, `gpt-4o`, or `MiniMax-Text-01`
+- `GITHUB_TOKEN` — provided automatically by GitHub Actions
+
+When you push a tag (`git tag v1.2.0 && git push --tags`), a PR is automatically opened with updated documentation.
+
+## What gets updated
+
+| File | Always | Conditional |
+|------|--------|-------------|
+| `AGENTS.md` | ✓ | |
+| `ARCHITECTURE.md` | ✓ | |
+| `docs/DESIGN.md` | ✓ | |
+| `docs/QUALITY_SCORE.md` | ✓ | |
+| `changelog/vX.Y.Z.md` | ✓ | |
+| `docs/design-docs/vX.Y.Z.md` | ✓ | |
+| `docs/design-docs/index.md` | ✓ | |
+| `docs/exec-plans/tech-debt-tracker.md` | ✓ | |
+| `docs/FRONTEND.md` | | frontend files changed |
+| `docs/SECURITY.md` | | auth/security files changed |
+| `docs/RELIABILITY.md` | | infra files changed |
+| `docs/generated/db-schema.md` | | SQL/schema files changed |
+| `docs/product-specs/index.md` | | new features detected |
+| `docs/references/` | | new dependencies added |
+
+## Local run
+
+```bash
+AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-engineering-auto-docs
+```
+
+## Supported models
+
+Model routing is determined by the prefix of `AI_MODEL`:
+
+| Prefix | Provider | Example models |
+|--------|----------|----------------|
+| `claude-*` | Anthropic | `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001` |
+| `gpt-*` | OpenAI | `gpt-4o`, `gpt-4o-mini`, `o3` |
+| `MiniMax-*` | MiniMax (Anthropic-compatible) | `MiniMax-Text-01` |
+
+## Future
+
+- GitLab support (MR creation)

package/dist/ai/anthropic.d.ts

@@ -0,0 +1,7 @@
+import type { AIProvider } from './interface.js';
+export declare class AnthropicProvider implements AIProvider {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string);
+    generate(prompt: string): Promise<string>;
+}

package/dist/ai/anthropic.js

@@ -0,0 +1,20 @@
+import Anthropic from '@anthropic-ai/sdk';
+export class AnthropicProvider {
+    client;
+    model;
+    constructor(apiKey, model) {
+        this.client = new Anthropic({ apiKey });
+        this.model = model;
+    }
+    async generate(prompt) {
+        const message = await this.client.messages.create({
+            model: this.model,
+            max_tokens: 4096,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const content = message.content[0];
+        if (content.type !== 'text')
+            throw new Error('Unexpected response type');
+        return content.text;
+    }
+}

package/dist/ai/interface.d.ts

@@ -0,0 +1,3 @@
+export interface AIProvider {
+    generate(prompt: string): Promise<string>;
+}

package/dist/ai/interface.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/minimax.d.ts

@@ -0,0 +1,7 @@
+import type { AIProvider } from './interface.js';
+export declare class MiniMaxProvider implements AIProvider {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string);
+    generate(prompt: string): Promise<string>;
+}

package/dist/ai/minimax.js

@@ -0,0 +1,21 @@
+import Anthropic from '@anthropic-ai/sdk';
+const MINIMAX_BASE_URL = 'https://api.minimax.io/anthropic';
+export class MiniMaxProvider {
+    client;
+    model;
+    constructor(apiKey, model) {
+        this.client = new Anthropic({ apiKey, baseURL: MINIMAX_BASE_URL });
+        this.model = model;
+    }
+    async generate(prompt) {
+        const message = await this.client.messages.create({
+            model: this.model,
+            max_tokens: 4096,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const content = message.content[0];
+        if (content.type !== 'text')
+            throw new Error('Unexpected response type');
+        return content.text;
+    }
+}

package/dist/ai/openai.d.ts

@@ -0,0 +1,7 @@
+import type { AIProvider } from './interface.js';
+export declare class OpenAIProvider implements AIProvider {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string);
+    generate(prompt: string): Promise<string>;
+}

package/dist/ai/openai.js

@@ -0,0 +1,16 @@
+import OpenAI from 'openai';
+export class OpenAIProvider {
+    client;
+    model;
+    constructor(apiKey, model) {
+        this.client = new OpenAI({ apiKey });
+        this.model = model;
+    }
+    async generate(prompt) {
+        const completion = await this.client.chat.completions.create({
+            model: this.model,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        return completion.choices[0].message.content ?? '';
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// src/cli.ts
+import { execSync } from 'child_process';
+import { extractDiff } from './core/diff.js';
+import { selectTargets } from './core/relevance.js';
+import { generateDocs, writeResults } from './core/generator.js';
+import { GitHubProvider } from './providers/github.js';
+import { GitLabProvider } from './providers/gitlab.js';
+import { AnthropicProvider } from './ai/anthropic.js';
+import { OpenAIProvider } from './ai/openai.js';
+import { MiniMaxProvider } from './ai/minimax.js';
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        console.error(`Error: ${name} environment variable is required`);
+        process.exit(1);
+    }
+    return value;
+}
+function detectPlatform() {
+    if (process.env.GITHUB_ACTIONS) {
+        return new GitHubProvider(requireEnv('GITHUB_TOKEN'));
+    }
+    if (process.env.GITLAB_CI) {
+        return new GitLabProvider();
+    }
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) {
+        console.error('Error: GITHUB_TOKEN is required (or run in GITHUB_ACTIONS / GITLAB_CI)');
+        process.exit(1);
+    }
+    return new GitHubProvider(token);
+}
+function selectAI(model, apiKey) {
+    if (model.startsWith('claude-'))
+        return new AnthropicProvider(apiKey, model);
+    if (model.startsWith('gpt-'))
+        return new OpenAIProvider(apiKey, model);
+    if (model.startsWith('MiniMax-'))
+        return new MiniMaxProvider(apiKey, model);
+    console.error(`Error: Unknown model "${model}". Use a claude-*, gpt-*, or MiniMax-* model.`);
+    process.exit(1);
+}
+function getDefaultBranch() {
+    try {
+        return execSync('git symbolic-ref refs/remotes/origin/HEAD --short')
+            .toString().trim().replace('origin/', '');
+    }
+    catch {
+        return 'main';
+    }
+}
+async function main() {
+    const model = requireEnv('AI_MODEL');
+    const apiKey = requireEnv('AI_API_KEY');
+    const diff = extractDiff();
+    if (!diff.raw.trim()) {
+        console.log('No diff between tags. Nothing to document.');
+        process.exit(0);
+    }
+    console.log(`Generating docs: ${diff.prevTag} → ${diff.currentTag}`);
+    const ai = selectAI(model, apiKey);
+    const targets = selectTargets(diff.fileGroups, diff.changedFiles);
+    console.log(`Updating ${targets.length} documents: ${targets.join(', ')}`);
+    const results = await generateDocs(ai, diff, targets);
+    const failures = results.filter(r => r.error);
+    if (failures.length > 0) {
+        console.warn(`\nWarning: ${failures.length} document(s) failed:`);
+        failures.forEach(f => console.warn(`  - ${f.target}: ${f.error}`));
+    }
+    const cwd = process.cwd();
+    const writtenFiles = writeResults(results.filter(r => !r.error), diff, cwd);
+    console.log(`\nWrote ${writtenFiles.length} files.`);
+    if (writtenFiles.length === 0) {
+        console.log('No files written. Skipping PR creation.');
+        process.exit(0);
+    }
+    const branch = `harness-docs/${diff.currentTag}`;
+    const baseBranch = getDefaultBranch();
+    execSync(`git checkout -b ${branch}`);
+    execSync(`git add ${writtenFiles.map(f => `"${f}"`).join(' ')}`);
+    execSync(`git commit -m "docs: Harness Engineering docs update for ${diff.currentTag}"`, { env: { ...process.env, GIT_AUTHOR_NAME: 'harness-engineering-auto-docs', GIT_AUTHOR_EMAIL: 'bot@harness-engineering-auto-docs' } });
+    execSync(`git push -u origin ${branch}`);
+    const platform = detectPlatform();
+    const prUrl = await platform.createOrUpdatePR({
+        branch,
+        title: `docs: Harness Engineering docs for ${diff.currentTag}`,
+        body: [
+            `Auto-generated by [harness-engineering-auto-docs](https://github.com/your-org/harness-engineering-auto-docs).`,
+            ``,
+            `Updates documentation based on changes from **${diff.prevTag}** to **${diff.currentTag}**.`,
+            ``,
+            `**Updated files:**`,
+            writtenFiles.map(f => `- \`${f.replace(cwd + '/', '')}\``).join('\n'),
+        ].join('\n'),
+        baseBranch,
+    });
+    console.log(`\nPR created: ${prUrl}`);
+}
+main().catch(err => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/dist/core/diff.d.ts

@@ -0,0 +1,17 @@
+export interface FileGroups {
+    frontend: string[];
+    schema: string[];
+    auth: string[];
+    infra: string[];
+    other: string[];
+}
+export interface DiffResult {
+    raw: string;
+    prevTag: string;
+    currentTag: string;
+    changedFiles: string[];
+    fileGroups: FileGroups;
+}
+export declare function extractDiff(): DiffResult;
+export declare function parseChangedFiles(diff: string): string[];
+export declare function groupFiles(files: string[]): FileGroups;

package/dist/core/diff.js

@@ -0,0 +1,46 @@
+// src/core/diff.ts
+import { execSync } from 'child_process';
+export function extractDiff() {
+    const tags = execSync('git tag --sort=version:refname')
+        .toString()
+        .trim()
+        .split('\n')
+        .filter(Boolean);
+    if (tags.length === 0)
+        throw new Error('No tags found in repository');
+    const currentTag = tags[tags.length - 1];
+    const prevTag = tags.length >= 2 ? tags[tags.length - 2] : null;
+    const raw = prevTag
+        ? execSync(`git diff ${prevTag} ${currentTag}`).toString()
+        : execSync(`git show ${currentTag} --format='' -p`).toString();
+    const changedFiles = parseChangedFiles(raw);
+    const fileGroups = groupFiles(changedFiles);
+    return {
+        raw,
+        prevTag: prevTag ?? '(initial)',
+        currentTag,
+        changedFiles,
+        fileGroups,
+    };
+}
+export function parseChangedFiles(diff) {
+    const matches = diff.match(/^diff --git a\/.+ b\/(.+)$/gm) ?? [];
+    return matches.map(line => {
+        const match = line.match(/^diff --git a\/.+ b\/(.+)$/);
+        return match ? match[1] : '';
+    }).filter(Boolean);
+}
+export function groupFiles(files) {
+    const isFrontend = (f) => /\.(tsx?|jsx?|css|scss|html|vue|svelte)$/.test(f) ||
+        /\b(ui|frontend|components|pages|views)\b/.test(f);
+    const isSchema = (f) => /\.sql$/.test(f) || /\b(schema|migration|migrate)\b/i.test(f);
+    const isAuth = (f) => /\b(auth|permission|security|oauth|jwt|session|token)\b/i.test(f);
+    const isInfra = (f) => /\b(infra|deploy|k8s|docker|compose|helm|terraform|service|gateway)\b/i.test(f);
+    return {
+        frontend: files.filter(isFrontend),
+        schema: files.filter(isSchema),
+        auth: files.filter(isAuth),
+        infra: files.filter(isInfra),
+        other: files.filter(f => !isFrontend(f) && !isSchema(f) && !isAuth(f) && !isInfra(f)),
+    };
+}

package/dist/core/generator.d.ts

@@ -0,0 +1,10 @@
+import type { AIProvider } from '../ai/interface.js';
+import type { DocTarget } from './relevance.js';
+import type { DiffResult } from './diff.js';
+export interface GenerationResult {
+    target: DocTarget;
+    content: string;
+    error?: string;
+}
+export declare function generateDocs(ai: AIProvider, diff: DiffResult, targets: DocTarget[]): Promise<GenerationResult[]>;
+export declare function writeResults(results: GenerationResult[], diff: DiffResult, cwd: string): string[];