clawdie-ai/CONTRIBUTING.md

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

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

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:

  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:

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:

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

If blocked by a false positive:

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