oh-my-harness 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyu1204
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,343 @@
+<div align="center">
+
+# 🐴 oh-my-harness
+
+**Tame your AI coding agents with natural language.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/Tests-131%20passing-brightgreen.svg)](#)
+
+> Stop hand-writing CLAUDE.md files. Describe your project, get enforced guardrails.
+
+</div>
+
+---
+
+## The Problem
+
+Every AI code agent needs configuration files. Claude Code needs `CLAUDE.md` + hooks. Cursor needs `.cursorrules`. Codex needs `AGENTS.md`. You end up:
+
+- Copy-pasting config files between projects
+- Forgetting to set up TDD enforcement hooks
+- Agents committing code without running tests
+- Inconsistent behavior across projects
+
+## The Solution
+
+```bash
+oh-my-harness init "React + FastAPI fullstack, TDD enforced, lint on save"
+```
+
+That's it. oh-my-harness generates **enforced guardrails** — not just instructions, but hooks that actually **block** bad behavior:
+
+- ❌ Commit without tests passing? **Blocked.**
+- ❌ Write to `node_modules/` or `.next/`? **Blocked.**
+- ❌ Run `rm -rf /`? **Blocked.**
+- ✅ Auto-lint on every file save? **Done.**
+- ✅ TDD workflow enforced in every plan? **Done.**
+
+---
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/your-username/oh-my-harness.git
+cd oh-my-harness && npm install
+
+# NL-first: describe your project
+npx tsx bin/oh-my-harness.ts init "TypeScript Next.js frontend with Python FastAPI backend"
+
+# Or use built-in presets (offline, instant)
+npx tsx bin/oh-my-harness.ts init --preset nextjs fastapi
+```
+
+### What Gets Generated
+
+```
+your-project/
+├── CLAUDE.md                          # TDD rules, coding standards, architecture guide
+├── harness.yaml                       # Your harness config (editable, git-trackable)
+└── .claude/
+    ├── settings.json                  # Hook configs, permissions (allow/deny)
+    ├── hooks/
+    │   ├── base-command-guard.sh      # Blocks dangerous commands
+    │   ├── base-test-before-commit.sh # Tests must pass before commit
+    │   ├── nextjs-file-guard.sh       # Protects build outputs
+    │   └── fastapi-lint-on-save.sh    # Auto-formats Python on save
+    └── oh-my-harness.json             # Active preset tracking
+```
+
+---
+
+## How It Works
+
+```
+                    ┌─────────────────────┐
+  "React + FastAPI  │                     │
+   TDD enforced"    │   claude -p (NL)    │
+  ─────────────────▶│   or --preset flag  │
+                    │                     │
+                    └────────┬────────────┘
+                             │
+                             ▼
+                    ┌─────────────────────┐
+                    │   harness.yaml      │  ← Intermediate representation
+                    │   (editable, git    │    (source of truth)
+                    │    trackable)       │
+                    └────────┬────────────┘
+                             │
+                             ▼
+              ┌──────────────┼──────────────┐
+              ▼              ▼              ▼
+        ┌──────────┐  ┌──────────┐  ┌──────────────┐
+        │ CLAUDE.md│  │  Hooks   │  │ settings.json│
+        │ (rules)  │  │ (enforce)│  │ (permissions)│
+        └──────────┘  └──────────┘  └──────────────┘
+```
+
+### Two Modes
+
+| Mode | Command | Speed | Requires |
+|------|---------|-------|----------|
+| **NL-first** | `init "description"` | ~5s | Claude CLI installed |
+| **Preset** | `init --preset nextjs` | Instant | Nothing |
+
+---
+
+## Built-in Presets
+
+### `_base` — Always Applied
+- TDD enforcement (mandatory test-first workflow)
+- Dangerous command blocking
+- Pre-commit test gate
+- Branch management rules
+- File safety rules
+
+### `nextjs` — Next.js + TypeScript
+- App Router conventions (Server Components default)
+- Component test enforcement
+- ESLint auto-fix on save
+- Build output protection (`.next/`, `out/`)
+- pnpm permissions
+
+### `fastapi` — FastAPI + Python
+- Async-first, Pydantic v2 patterns
+- pytest + real DB testing (no mocks)
+- Ruff auto-format on save
+- Virtual env protection
+- uv/pytest permissions
+
+### `nextjs-fastapi` — Full Stack
+- Composes both presets
+- Cross-cutting rules (CORS, API boundaries)
+- Dual test suite enforcement (both must pass before commit)
+
+---
+
+## Commands
+
+```bash
+# Initialize with natural language
+oh-my-harness init "your project description"
+
+# Initialize with presets
+oh-my-harness init --preset nextjs fastapi
+
+# Add a preset to existing config
+oh-my-harness add nextjs
+
+# Remove a preset
+oh-my-harness remove fastapi
+
+# Health check
+oh-my-harness doctor
+```
+
+### `doctor` Output
+
+```
+oh-my-harness: running health checks...
+  ✓ .claude/oh-my-harness.json found (presets: _base, nextjs)
+  ✓ CLAUDE.md exists with intact markers
+  ✓ .claude/settings.json is valid
+  ✓ All hook scripts are executable
+oh-my-harness: all checks passed
+```
+
+---
+
+## Enforcement in Action
+
+### TDD Gate (Pre-commit Hook)
+
+When Claude Code tries to `git commit`, oh-my-harness intercepts:
+
+```bash
+# Agent attempts: git commit -m "add login page"
+oh-my-harness: Running tests before commit...
+# pnpm test runs...
+# If tests fail:
+{"decision": "block", "reason": "oh-my-harness: tests failed, commit blocked"}
+# Agent must fix tests before committing
+```
+
+### File Guard (Pre-write Hook)
+
+```bash
+# Agent attempts: Write to .next/cache/something.js
+{"decision": "block", "reason": "oh-my-harness: protected path .next/"}
+# Agent cannot write to build outputs
+```
+
+### Command Guard
+
+```bash
+# Agent attempts: rm -rf /
+{"decision": "block", "reason": "oh-my-harness: dangerous command blocked"}
+```
+
+---
+
+## The `harness.yaml` File
+
+After init, a `harness.yaml` is saved to your project root. This is the **source of truth** — edit it directly, then re-run init to regenerate:
+
+```yaml
+version: "1.0"
+project:
+  description: "E-commerce platform"
+  stacks:
+    - name: frontend
+      framework: nextjs
+      language: typescript
+      testRunner: vitest
+      linter: eslint
+
+rules:
+  - id: tdd-rules
+    title: TDD Workflow
+    content: |
+      ## TDD Workflow (MANDATORY)
+      1. Write failing test FIRST
+      2. Implement minimal code to pass
+      3. Refactor while green
+    priority: 10
+
+enforcement:
+  preCommit: ["test", "lint", "build"]
+  blockedPaths: [".next/", "node_modules/"]
+  blockedCommands: ["rm -rf", "sudo"]
+  postSave:
+    - pattern: "*.ts"
+      command: "eslint --fix"
+```
+
+---
+
+## Architecture
+
+```
+oh-my-harness/
+├── bin/                    # CLI entry point
+├── src/
+│   ├── cli/commands/       # init, add, remove, doctor
+│   ├── core/
+│   │   ├── preset-types.ts     # Zod schemas
+│   │   ├── preset-loader.ts    # YAML → typed config
+│   │   ├── preset-registry.ts  # Discover & search presets
+│   │   ├── config-merger.ts    # Merge multiple presets
+│   │   ├── harness-schema.ts   # harness.yaml schema
+│   │   ├── harness-converter.ts # harness.yaml → MergedConfig
+│   │   └── generator.ts        # Orchestrates all generators
+│   ├── generators/
+│   │   ├── claude-md.ts    # CLAUDE.md with idempotent markers
+│   │   ├── hooks.ts        # Executable hook scripts
+│   │   ├── settings.ts     # .claude/settings.json
+│   │   └── gitignore.ts    # .gitignore updater
+│   ├── nl/
+│   │   ├── parse-intent.ts     # claude -p integration
+│   │   └── prompt-templates.ts # LLM prompt construction
+│   └── utils/
+│       ├── markdown.ts     # Marker-based section management
+│       └── yaml.ts         # YAML helpers
+├── presets/                # Built-in preset definitions
+│   ├── _base/
+│   ├── nextjs/
+│   ├── fastapi/
+│   └── nextjs-fastapi/
+└── tests/                  # 131 tests (unit + integration)
+```
+
+---
+
+## Adding Custom Presets
+
+Create a directory in `presets/` with a `preset.yaml`:
+
+```yaml
+name: my-preset
+displayName: "My Custom Preset"
+description: "Custom rules for my team"
+version: "1.0.0"
+extends: ["_base"]
+tags: ["custom"]
+
+claudeMd:
+  sections:
+    - id: "my-rules"
+      title: "My Rules"
+      content: |
+        ## My Team Rules
+        - Always write JSDoc comments
+        - Use barrel exports
+      priority: 30
+
+hooks:
+  preToolUse:
+    - id: "my-guard"
+      matcher: "Bash"
+      inline: |
+        #!/bin/bash
+        # Your custom enforcement logic
+        exit 0
+```
+
+No code changes required. The registry auto-discovers it.
+
+---
+
+## Requirements
+
+- **Node.js** >= 20
+- **Claude CLI** (optional, for NL mode) — [Install guide](https://docs.anthropic.com/en/docs/claude-code)
+
+---
+
+## Roadmap
+
+- [ ] Cursor (`.cursor/rules/`) emitter
+- [ ] Codex (`AGENTS.md`) emitter
+- [ ] GitHub Copilot emitter
+- [ ] `oh-my-harness sync` — drift detection
+- [ ] Community preset registry
+- [ ] `npx oh-my-harness` — zero-install usage
+- [ ] `oh-my-harness modify "change X"` — NL config editing
+
+---
+
+## License
+
+MIT
+
+---
+
+<div align="center">
+
+**Your agents are only as good as their guardrails.**
+
+Built with frustration from hand-writing CLAUDE.md files.
+
+</div>

package/dist/bin/oh-my-harness.d.ts

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

package/dist/bin/oh-my-harness.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { createCli } from "../cli/index.js";
+const cli = createCli();
+cli.parse(process.argv);

package/dist/cli/commands/add.d.ts

@@ -0,0 +1,5 @@
+export interface AddOptions {
+    projectDir?: string;
+    presetsDir?: string;
+}
+export declare function addCommand(presetName: string, options?: AddOptions): Promise<void>;

package/dist/cli/commands/add.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { PresetRegistry } from "../../core/preset-registry.js";
+import { mergePresets } from "../../core/config-merger.js";
+import { generate } from "../../core/generator.js";
+import { readHarnessState, writeHarnessState, loadAndMergePresets } from "./init.js";
+function getDefaultPresetsDir() {
+    return path.resolve(import.meta.dirname, "../../../presets");
+}
+export async function addCommand(presetName, options = {}) {
+    const projectDir = options.projectDir ?? process.cwd();
+    const presetsDir = options.presetsDir ?? getDefaultPresetsDir();
+    // Read existing state (throws if not initialized)
+    const state = await readHarnessState(projectDir).catch(() => {
+        throw new Error("Harness not initialized. Run `oh-my-harness init` first.");
+    });
+    // Discover presets
+    const registry = new PresetRegistry();
+    await registry.discover(presetsDir);
+    // Verify preset exists
+    if (!registry.has(presetName)) {
+        throw new Error(`Preset not found: ${presetName}`);
+    }
+    // Add preset (deduplicate)
+    const updatedPresets = Array.from(new Set([...state.presets, presetName]));
+    // Load, resolve, merge
+    const presetConfigs = await loadAndMergePresets(updatedPresets, registry);
+    const config = mergePresets(presetConfigs);
+    // Regenerate
+    const result = await generate({ projectDir, config });
+    // Save updated state
+    await writeHarnessState(projectDir, {
+        presets: updatedPresets,
+        generatedAt: new Date().toISOString(),
+    });
+    console.log(`\noh-my-harness: added preset "${presetName}"`);
+    console.log(`Active presets: ${updatedPresets.join(", ")}`);
+    console.log("Regenerated files:");
+    for (const f of result.files) {
+        console.log(`  ${f}`);
+    }
+}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,14 @@
+export interface DoctorOptions {
+    projectDir?: string;
+}
+export interface DoctorResult {
+    healthy: boolean;
+    checks: {
+        stateFile: boolean;
+        claudeMd: boolean;
+        settingsJson: boolean;
+        hooksExecutable: boolean;
+    };
+    messages: string[];
+}
+export declare function doctorCommand(options?: DoctorOptions): Promise<DoctorResult>;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,84 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function doctorCommand(options = {}) {
+    const projectDir = options.projectDir ?? process.cwd();
+    const messages = [];
+    const checks = {
+        stateFile: false,
+        claudeMd: false,
+        settingsJson: false,
+        hooksExecutable: false,
+    };
+    // 1. Check .claude/oh-my-harness.json exists
+    const stateFile = path.join(projectDir, ".claude", "oh-my-harness.json");
+    try {
+        await fs.access(stateFile);
+        checks.stateFile = true;
+    }
+    catch {
+        messages.push("FAIL: .claude/oh-my-harness.json not found. Run `oh-my-harness init` first.");
+    }
+    // 2. Check CLAUDE.md exists and has managed markers
+    const claudeMdPath = path.join(projectDir, "CLAUDE.md");
+    try {
+        const content = await fs.readFile(claudeMdPath, "utf-8");
+        if (content.includes("<!-- oh-my-harness:")) {
+            checks.claudeMd = true;
+        }
+        else {
+            messages.push("WARN: CLAUDE.md exists but has no oh-my-harness managed sections.");
+            checks.claudeMd = true; // File exists, just no markers — acceptable
+        }
+    }
+    catch {
+        messages.push("FAIL: CLAUDE.md not found.");
+    }
+    // 3. Check settings.json exists and is valid JSON
+    const settingsPath = path.join(projectDir, ".claude", "settings.json");
+    try {
+        const raw = await fs.readFile(settingsPath, "utf-8");
+        JSON.parse(raw);
+        checks.settingsJson = true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            messages.push("FAIL: .claude/settings.json not found.");
+        }
+        else {
+            messages.push("FAIL: .claude/settings.json is not valid JSON.");
+        }
+    }
+    // 4. Check hook scripts exist and are executable
+    const hooksDir = path.join(projectDir, ".claude", "hooks");
+    try {
+        const files = await fs.readdir(hooksDir);
+        const scripts = files.filter((f) => f.endsWith(".sh"));
+        let allExecutable = true;
+        for (const script of scripts) {
+            const scriptPath = path.join(hooksDir, script);
+            try {
+                await fs.access(scriptPath, fs.constants.X_OK);
+            }
+            catch {
+                messages.push(`FAIL: Hook script not executable: ${script}`);
+                allExecutable = false;
+            }
+        }
+        checks.hooksExecutable = allExecutable;
+    }
+    catch {
+        // No hooks dir — acceptable if no hooks defined
+        checks.hooksExecutable = true;
+    }
+    const healthy = Object.values(checks).every(Boolean);
+    if (healthy) {
+        console.log("oh-my-harness: all checks passed");
+    }
+    else {
+        console.log("oh-my-harness: some checks failed:");
+        for (const msg of messages) {
+            console.log(`  ${msg}`);
+        }
+    }
+    return { healthy, checks, messages };
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,21 @@
+import { PresetRegistry } from "../../core/preset-registry.js";
+import type { PresetConfig } from "../../core/preset-types.js";
+import type { ClaudeRunner } from "../../nl/parse-intent.js";
+export interface InitOptions {
+    yes?: boolean;
+    projectDir?: string;
+    presetsDir?: string;
+    preset?: string[];
+    nlRunner?: ClaudeRunner;
+    _nlDescription?: string;
+}
+export interface HarnessState {
+    presets: string[];
+    generatedAt: string;
+}
+export declare function readHarnessState(projectDir: string): Promise<HarnessState>;
+export declare function writeHarnessState(projectDir: string, state: HarnessState): Promise<void>;
+export declare function loadAndMergePresets(presetNames: string[], registry: PresetRegistry): Promise<PresetConfig[]>;
+export declare function initCommand(presetNames: string[], options?: InitOptions): Promise<void>;
+/** Headless init for CI/automation — bypasses TUI */
+export declare const initCommandHeadless: typeof initCommand;