chore(scaffold): bootstrap docmost-sync Node/TS project skeleton
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.
This commit is contained in:
61
AGENTS.md
Normal file
61
AGENTS.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user