ef223e13ff
Set up the project structure per the new-project guide, adapted from the Python skeleton to the Node/TS stack fixed in SPEC.md (reuses docmost-mcp). Scaffold only — the sync engine is not implemented yet. - src/settings.ts: single config layer on zod, schema keyed by real ENV names; credentials and own-service address have no default (fail fast). - src/config-errors.ts: loadSettingsOrExit — clear startup message naming the missing/invalid env var instead of a raw stack trace; exit(1). - src/index.ts: thin entry point that validates config and logs (stub). - test/: vitest unit tests for settings parsing and config errors (10 tests). - Makefile (install/env/build/test/run/dev/clean), strict tsconfig, vitest. - Dockerfile (single-stage, no EXPOSE, prunes dev deps), docker-compose (daemon, volume on /app/data, watchtower), ghcr CI with build needs test. - .env.example, .gitignore/.dockerignore, AGENTS.md, README.md. - Pinned deps (dotenv, zod) + committed package-lock.json.
62 lines
2.6 KiB
Markdown
62 lines
2.6 KiB
Markdown
# AGENTS.md
|
|
|
|
Onboarding notes for agents working on **docmost-sync** (Node / TypeScript, ESM).
|
|
|
|
## What this is
|
|
|
|
A daemon that bidirectionally syncs Docmost articles with a local Markdown git
|
|
vault (git is the state store). It reuses the sibling project **docmost-mcp** as
|
|
a library (DocmostClient, ProseMirror ↔ Markdown converter, collab-write).
|
|
|
|
**Status: scaffold only — the sync engine is NOT implemented yet.** `src/index.ts`
|
|
is a thin stub that validates config and exits. See `SPEC.md` for the full design
|
|
and the phased plan before adding engine logic.
|
|
|
|
## Project structure
|
|
|
|
- `src/` — application code.
|
|
- `src/settings.ts` — the single config entry point (zod schema keyed by the
|
|
real ENV var names; `parseSettings` is pure, `loadSettings` reads `.env`).
|
|
- `src/config-errors.ts` — `loadSettingsOrExit` turns a config error into a
|
|
clear startup message that names the missing/invalid variable, then exits.
|
|
- `src/index.ts` — thin entry point.
|
|
- `test/` — vitest tests (`*.test.ts`).
|
|
- `data/` — all mutable runtime state (the git vault lives here). Gitignored;
|
|
mounted as a docker volume in production. Never put code/static assets here.
|
|
- `build/` — compiled output (`tsc`). Gitignored.
|
|
|
|
Relative imports inside `src/` use the `.js` extension (NodeNext), e.g.
|
|
`import { loadSettings } from './settings.js'`.
|
|
|
|
## Setup
|
|
|
|
- `make install` — install dependencies (`npm ci`).
|
|
- `make env` — create `.env` from `.env.example` (or `cp .env.example .env`),
|
|
then fill in the values.
|
|
|
|
## Running
|
|
|
|
- `make test` — run the test suite (vitest).
|
|
- `make run` — build and run the app.
|
|
- `make dev` — run in watch mode (tsx).
|
|
|
|
`make` (or `make help`) lists all targets.
|
|
|
|
## Conventions
|
|
|
|
- All mutable state lives ONLY under `data/`. Static assets are code, never in `data/`.
|
|
- All config and credentials come ONLY from ENV / `.env`, read through
|
|
`src/settings.ts`. Credentials and the addresses of our own services that the
|
|
user provides go ONLY into `.env` (never into code, never as inline env vars on
|
|
the command line) and are read through settings.
|
|
- No default/example credentials in code. Addresses of our own services (Docmost)
|
|
have NO default either. A missing required variable must FAIL AT STARTUP with a
|
|
clear message that names the variable — no raw stack trace.
|
|
- Defaults are allowed only for non-secret tunables (log level, intervals, vault
|
|
path under `data/`).
|
|
- All code comments are written in ENGLISH.
|
|
- Repeated actions go through the `Makefile`.
|
|
- Tests are required for new code. In CI the `build` job needs `test` (tests gate
|
|
the docker build).
|
|
- No `EXPOSE` in the Dockerfile — this is a daemon with no inbound HTTP port.
|