Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,131 @@
+# DevRunbook
+
+DevRunbook is a self-hosted platform for turning development intent into
+structured, reusable and verifiable tasks for coding agents such as Codex. It
+combines a reviewed playbook, repository context, risk controls and validation
+requirements into a deterministic prompt or multi-file Run Pack.
+
+The platform helps developers stop rewriting the same instructions while
+keeping scope, provenance and evidence visible. It does **not** execute
+repository commands or write to your Git forge.
+
+## What users can do
+
+- Browse and search 28 built-in, versioned development playbooks.
+- Create reusable repository profiles with commands, protected paths and policies.
+- Compose tasks in a guided Simple flow or a detailed Expert flow.
+- Inspect compatibility, provenance, guardrails and prompt-lint results before generation.
+- Save immutable generated tasks and export exact Markdown or verified Run Pack archives.
+- Connect Gitea read-only to import bounded repository evidence while retaining useful local state during an outage.
+- Author and review private playbooks in Prompt Lab without making draft claims look validated.
+
+The interface supports Dutch and English presentation, keyboard navigation,
+reduced motion, light/dark themes and responsive desktop/mobile layouts.
+
+## Quick start with Docker Compose
+
+Requirements:
+
+- Docker Engine with Docker Compose 2.40 or newer;
+- a release checkout of this repository;
+- four independently generated secrets.
+
+```sh
+cp .env.example .env
+chmod 600 .env
+
+openssl rand -hex 24       # POSTGRES_PASSWORD
+openssl rand -hex 32       # SESSION_SECRET
+openssl rand -base64 32    # INTEGRATION_ENCRYPTION_KEY
+openssl rand -hex 24       # BOOTSTRAP_TOKEN
+```
+
+Place those values in `.env`, set `PUBLIC_BASE_URL`, then start the stack:
+
+```sh
+docker compose -p devrunbook --env-file .env build
+docker compose -p devrunbook --env-file .env up -d
+docker compose -p devrunbook --env-file .env ps
+```
+
+Open `PUBLIC_BASE_URL/setup`, enter the bootstrap token and create the first
+owner. The setup route closes after successful initialization. Keep public
+registration closed unless you deliberately configure an invitation workflow.
+
+Health endpoints:
+
+```sh
+curl --fail http://127.0.0.1:3000/health/live
+curl --fail http://127.0.0.1:3000/health/ready
+```
+
+For production upgrades, backups, restores, Unraid and reverse-proxy guidance,
+read the [operator guide](docs/operator-guide.md). Do not publish PostgreSQL,
+mount the Docker socket or weaken the default Gitea network policy. The
+reference stack binds its HTTP port to host loopback; terminate public HTTPS at
+a maintained reverse proxy on the same host or adjust the binding deliberately.
+
+## Local development
+
+DevRunbook requires Node.js 24, pnpm 10.33.0 and Python 3 for the specification
+contracts. PostgreSQL is required for integration tests and a complete local
+application flow.
+
+```sh
+corepack enable
+pnpm install --frozen-lockfile
+python3 scripts/validate_pack.py
+python3 scripts/reference_compose.py --check
+pnpm verify
+pnpm test:security
+```
+
+`pnpm verify` runs formatting, linting, strict type checks, unit tests,
+specification/golden-fixture validation and production builds. See
+[`docs/15-test-strategy.md`](docs/15-test-strategy.md) for integration,
+Playwright, clean-room and release gates.
+
+## Architecture and safety
+
+DevRunbook is a TypeScript modular monolith with separate web and worker roles
+and PostgreSQL as its only required data service. Important boundaries include:
+
+- generated runs and published playbook versions are immutable snapshots;
+- imported repository text is untrusted evidence, never governing instruction;
+- templates and conditions use restricted, non-executable data models;
+- archives are bounded, inventoried and verified without unsafe extraction;
+- workspace authorization is enforced server-side for every private resource;
+- Gitea tokens are encrypted at rest and the first integration is read-only;
+- default containers run non-root with read-only roots, dropped capabilities and no Docker socket.
+
+Start with the [product vision](docs/00-product-vision.md),
+[technical architecture](docs/06-technical-architecture.md) and
+[security threat model](docs/13-security-privacy-threat-model.md). Contributors
+should also read [`AGENTS.md`](AGENTS.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Project status
+
+The implemented release candidate covers the core library, repository profiles,
+deterministic composition, exports, read-only Gitea intelligence, Prompt Lab,
+operations, localization and accessibility hardening. Detailed evidence is in
+[`CURRENT_STATE.md`](CURRENT_STATE.md) and
+[`docs/19-acceptance-criteria.md`](docs/19-acceptance-criteria.md).
+
+Direct code execution, forge writes, a public marketplace, billing, Kubernetes
+as a required deployment and vector search remain deliberately out of scope.
+
+The application and Unraid icons were created for this project; their source
+and licensing are recorded in [the asset notice](docs/ASSET_PROVENANCE.md).
+
+`BUILD_PACK.json`, `FILE_INDEX.txt`, `PACK_MANIFEST.sha256` and the version 1.2
+documents describe the historical implementation-contract pack from which the
+0.1 application was built. They are not the current application version or a
+release manifest. See [publication readiness](docs/PUBLICATION_READINESS.md)
+for the remaining owner-controlled launch decisions.
+
+## License and security
+
+DevRunbook is available under the [MIT License](LICENSE). Please report
+vulnerabilities through the private channel described in
+[`SECURITY.md`](SECURITY.md); do not post tokens, private repository contents or
+exploit details in a public issue.