# Contributing

## Dev Setup

### Prerequisites

- Node.js 24+ and npm
- `just` — command runner (`pkg install just` on FreeBSD, `cargo install just` or download from GitHub on Linux/macOS)
- FreeBSD (for runtime testing) or Linux/macOS (for code + test changes)

### Install

```sh
git clone git@codeberg.org:Clawdie/Clawdie-AI.git
cd Clawdie-AI
npm ci --legacy-peer-deps
just install-hooks
just build
```

### Useful Commands

Primary interface is `just`. Run `just` (or `just --list`) to see all recipes grouped by category.

| Command                     | What                                          |
| --------------------------- | --------------------------------------------- |
| `just build`                | Compile TypeScript (`src/` → `dist/`)         |
| `just typecheck`            | Type-check without emitting                   |
| `just test`                 | Run all tests once                            |
| `just test src/foo.test.ts` | Run a single test file                        |
| `just test-watch`           | Run tests in watch mode                       |
| `just format`               | Auto-format with Prettier                     |
| `just format-check`         | Check Prettier formatting                     |
| `just check`                | Full quality gate (typecheck + format + test) |
| `just install-hooks`        | Activate git hooks from `hooks/`              |
| `just doctor`               | System health diagnostics                     |
| `just pull`                 | Git pull + rebuild                            |

`npm run <name>` equivalents exist for CI and scripting but `just` is the canonical CLI.

## Source Code Changes

**Accepted:** Bug fixes, security fixes, simplifications, reducing code.

**Not accepted:** Features, capabilities, compatibility, enhancements. These should be skills.

## Skills

A skill is a markdown file in `.agent/skills/` that teaches the Coding Agent how to transform a Clawdie installation.

A PR that contributes a skill should not modify any source files.

Your skill should contain the **instructions** the agent follows to add the feature — not pre-built code. See `.agent/skills/add-telegram/` for a good example.

### Why?

Every user should have clean and minimal code that does exactly what they need. Skills let users selectively add features to their fork without inheriting code for features they don't want.

Test your skill by running it on a fresh clone before submitting.

## Testing

### Running Tests

```sh
just test                        # all tests
just test src/router.test.ts     # single file
npx vitest run --reporter=verbose # verbose output
just test-watch                  # watch mode
```

### Writing Tests

- **Framework:** Vitest (`describe`, `it`, `expect`, `vi`)
- **Location:** Test files live next to the source file: `src/router.ts` → `src/router.test.ts`
- **Pattern:** `import { describe, it, expect, vi } from 'vitest'`
- **Config:** `vitest.config.ts` includes `src/**/*.test.ts`, `setup/**/*.test.ts`, `skills-engine/**/*.test.ts`

### Conventions

- Test pure functions directly. Mock system calls (fs, child_process, network).
- Use `vi.mock()` for config and external dependencies:
  ```ts
  vi.mock('./config.js', async () => {
    const actual =
      await vi.importActual<typeof import('./config.js')>('./config.js');
    return { ...actual, DATA_DIR: '', POLL_INTERVAL: 1000 };
  });
  ```
- Use temp directories for fs tests, clean up in `finally` blocks.
- Don't test FreeBSD-specific commands (`bastille`, `service`) — mock `child_process`.
- Tests must pass on Linux. 4 pre-existing failures in `controlplane-runner.test.ts` are FreeBSD-only (hardcoded workspace path).

### Known Platform Differences

- FreeBSD-specific commands (`bastille`, `service`, `pkg`) only run on FreeBSD hosts. Tests mock these on Linux.
- Do not attempt to fix FreeBSD-only test failures from Linux.

## Commit Style

### Format

```
type(scope): short description (Attribution)

Optional body paragraph.

---
Build: pass | Tests: pass — N passed (M files)
```

### Types

- `feat` — new feature
- `fix` — bug fix
- `docs` — documentation only
- `test` — test additions/changes
- `chore` — build, config, tooling
- `refactor` — code restructuring

### Scope

Module or area: `runner`, `db`, `jails`, `service`, `docs`, etc.

### Attribution

- `Sam & Claude` — changes by Sam and Claude
- `Sam & Codex` — changes by Sam and Codex
- `C&C` — joint Claude + Codex change

### Build/Test Footer

The `hooks/prepare-commit-msg` hook appends this automatically when hooks are active (`just install-hooks`). When committing without hooks, append manually:

- `Build: pass | Tests: pass — 1527 passed (91 files)`
- `Build: pass | Tests: not run (Linux)`
- `Build: FAIL | Tests: FAIL — 3 failed`

Failures are sometimes expected (WIP, mid-refactor). The footer is a record, not a gate.

### Version Tags

Run `just release` only on minor or major version bumps (never patches). The script reads `version` from `package.json`, creates an annotated tag, and pushes to Codeberg. Always confirm with the maintainer before tagging.

## Pre-Commit Hooks

Activate once after cloning:

```sh
just install-hooks
# equivalent: git config core.hooksPath hooks
```

### `hooks/pre-commit`

Reads `package.json` version and patches the version line in `README.md` automatically. Keeps README in sync without manual edits.

### Security Hook

`scripts/hooks/pre-commit` scans staged files for sensitive data (credentials, private IPs). Install separately:

```sh
cp scripts/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

If blocked by a false positive:

```sh
echo "docs/router-setup.md:192\.168\." >> .git/hooks/sensitive-allowlist.txt
```

See `scripts/hooks/SECURITY.md` for details.

## Documentation Update Protocol

Docs stay accurate by updating them **at the same time** you update code.

| Trigger                    | Action                              |
| -------------------------- | ----------------------------------- |
| Software version change    | Update "Tested With" section + date |
| Architecture change        | Update relevant guide               |
| New skill or guide         | Add "Tested With" + date            |
| Bug fix affecting workflow | Update affected guide               |

No special tooling — just include doc updates in the same commit as code changes.

## Project Structure

```
src/              Runtime TypeScript (compiled to dist/)
setup/            Install-time provisioner scripts
scripts/          CLI utilities (backup, dashboard, changelog)
infra/            Jail registry, package lists, PF rules
.agent/           Agent identities, skills, context
  identities/     Agent role prompts (SYSADMIN, DB_ADMIN, etc.)
  skills/         Feature and operational skills
  context/        Agent context files (FREEBSD.md)
hooks/            Git hooks (pre-commit, prepare-commit-msg)
docs/
  public/         Operator documentation (synced to docs.clawdie.si)
  internal/       Technical internals (not published)
bootstrap/        CMS bootstrap templates
html/             Generated HTML sites
```