Development setup
This page gets a contributor from a clone to a running instance, then explains where code lives and
which checks cover what. It complements the repository’s CONTRIBUTING.md, which owns branch, commit
and pull-request conventions.
Requirements
Section titled “Requirements”| Tool | Version | Used for |
|---|---|---|
| Bun | >=1.2 (verified on 1.3.10) |
Package manager, repository scripts, the API runtime |
| Node.js | >=24.0.0 (verified on v24.17.0) |
Vite dev server, check scripts, the node --test runner |
| PostgreSQL 16 | External | Metadata and tests that need a database |
| S3-compatible storage | External, private bucket | Artifact bytes |
| Docker | Optional | Disposable integration stack and production images |
bun.lock is the single lockfile; do not add a second package manager’s lock file. The workspace
covers apps/*, packages/* and plugins/opencode, and one root install feeds all of them.
First run
Section titled “First run”bun install # whole workspace, plugin includedbun run setup:local # .env.local from .env.example (mode 0600) plus the auth secret# edit .env.local: DATABASE_URL and ARTIFLOW_S3_*bun run check:local # SELECT 1 and HeadBucket; creates nothingbun run db:migrate # additive and idempotentbun run dev # API on 8787, dashboard on 5173Open http://127.0.0.1:5173/. bun run dev owns only its child processes and refuses to start when
either port is taken; ARTIFLOW_DEV_RUNTIME=bun|node picks the API runtime (default bun).
Where the code lives
Section titled “Where the code lives”| Path | Responsibility |
|---|---|
apps/api |
Hono API, Better Auth, MCP transport and tools, viewers and HTTP routes. |
apps/dashboard |
React SPA for the library, markdown editor, comments, sharing and account screens. |
apps/web |
This documentation site: Astro + Starlight, mounted at /docs. |
packages/contracts |
Zod wire schemas shared by the API, dashboard and SDK. |
packages/domain |
Pure source-coordinate and Markdown line operations. |
packages/mcp-server |
Transport-agnostic MCP tool logic; receives persistence through ports, imports no drivers. |
packages/mcp-apps |
MCP Apps viewer document and host-capability helpers. |
packages/plugin-core |
Harness-agnostic plugin runtime: OAuth client, associations, tool mapping, conformance kit. |
packages/sdk |
Typed fetch client over the public HTTP surface, with injectable fetch. |
plugins/opencode |
The OpenCode plugin workspace. |
skills |
Canonical SKILL.md content every harness integration packages. |
test |
Root suite: unit tests plus service-gated integration suites. |
scripts, drizzle, docker |
Repository checks, additive migrations, images and the Caddyfile. |
The architecture notes under docs/architecture/ describe current behavior, module boundaries and the
security model; docs/runbook.md is the local operations guide. Both are repository-facing, not part of
this site.
Tests and checks
Section titled “Tests and checks”The root suite runs on Node, not Bun: on Bun 1.3.10 the node:test shim ignores { skip }, so
environment-gated suites execute instead of skipping, and node:module lacks
stripTypeScriptTypes. Keep using node --test.
| Command | What it runs |
|---|---|
bun run test |
Every test/*.test.ts under node --test. Unit and UI tests; no services required, gated suites self-skip. |
bun run test:integration |
Every test/*.test.ts and test/*.integration.ts, serially, using test/integration-config.example. Requires the disposable PostgreSQL + Garage stack. |
bun run test:auth |
test/auth-http.integration.ts against a disposable PostgreSQL. |
bun run test:oauth |
test/oauth-http.integration.ts against a disposable PostgreSQL. |
bun run typecheck |
The API TypeScript project and the dashboard workspace project. |
bun run build |
Docs link check, boundary check, dashboard production build and API type check. |
bun run check:boundaries |
Import boundaries between apps, packages and tests. |
bun run check:hygiene |
Fails when a tracked file matches .gitignore. |
bun run check:changed |
Prettier and oxlint on the files changed against origin/main. Pass a base ref to compare elsewhere. |
bun run check:docs |
Every relative link in README.md and docs/ resolves to an existing file. |
bun run web:verify |
astro check, the docs build, then the built-output verifier; the only docs check that reads apps/web/dist. |
The integration stack and its exact sequence live in docs/runbook.md; never point those commands at
data you care about. The docs site has its own checks:
node --test test/web-docs.test.ts # workspace config, sidebar groups and every /docs/ linknode --test test/web-validation.test.ts # public CLI of the built-output link verifiernode --test test/web-reference.test.ts # public CLI of the configuration verifierbun run web:verify # astro check, the build, then both verifiersnode scripts/check-docs.mjs # relative links in README.md and docs/Two commands verify what the sources cannot prove, and web:verify runs both
after the build:
| Command | Verifies |
|---|---|
node apps/web/scripts/check-built.mjs [distDir] |
Routes, assets and #fragment targets in the emitted HTML resolve inside dist. |
node apps/web/scripts/check-reference.mjs |
apps/api/src/config.ts and reference/configuration.md list the same variables. |
A link check over the Markdown sources is not built proof, so only
check-built.mjs can prove the links. Both accept --help with their exit
codes (0 clean, 1 problems, 2 usage error or unreadable input);
check-reference.mjs also takes --root <dir> for another checkout, which is
what the fixture tests use.
The repository’s verify workflow runs the root checks on every push and pull request
(hygiene, dependency audit, boundaries, changed-file formatting, typecheck, tests and build). It
does not build or deploy the documentation site, so run bun run web:verify
locally before opening a docs change.
The gate audits the resolved tree with bun: after bun install --frozen-lockfile it runs
bun audit --json through scripts/audit.mjs (bun run audit) and fails on any high or critical
advisory that is not listed in scripts/audit-allowlist.json. Each entry names the package, the GHSA
id, the reason the risk is accepted and a reviewBy date. The date only produces a warning, so an
advisory without a patched release never turns the gate red for every pull request; remove the entry
once a patch lands. The MCP transport is Hono (@hono/node-server, apps/api/src/mcp/mount.ts), so
the MCP SDK’s express/body-parser subtree is not on the HTTP path today, and body-parser is
pinned to a patched version regardless.
Add a documentation page
Section titled “Add a documentation page”- Create the file under
apps/web/src/content/docs/docs/<section>/<page>.md. Its route is/docs/<section>/<page>/;<section>/index.mdbecomes the section landing page. - Add frontmatter with a
titleanddescription, andsidebar.orderto position the page inside its section. Groups, their labels and their order live inastro.config.mjs: each group autogenerates one content directory, so a new section directory needs a group entry there. - Write internal links as absolute
/docs/...paths. They must resolve to a real page; the site test fails on a link that does not. - Describe only what the code supports. If a behavior is partial, future or unverified, say so instead of promising it.
- Run
node --test test/web-docs.test.ts,node scripts/check-docs.mjsandbun run web:verify. Usebun run web:devto read the page at http://127.0.0.1:4321/docs/.
The site is English-only today: no locales are configured, so there are no translated routes to keep in sync. Search is Starlight’s built-in Pagefind index, generated at build time; there is no separate search service to run.
Conventions
Section titled “Conventions”- Read
AGENTS.mdbefore changing source: no comments in source, and reasoning belongs in the commit message or the pull request. - Product queries belong behind repositories that take the typed database from
apps/api/src/db/client.ts. HTTP routes and MCP tools consume the same operations instead of duplicating SQL. - Security invariants are summarized in
docs/architecture/README.md; artifact bytes never execute on the application origin and permissions are checked before any byte is read. - Migrations are additive and generated with
bun run db:generate; never create roles, databases, buckets or bucket policies from this repository. - If a statement in
README.mdordocs/stops being true after your change, fix it in the same pull request.
Read CONTRIBUTING.md for branches, commit messages and pull-request expectations, then
Install Artiflow if you are testing a production-like deployment.