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:
vvzvlad
2026-06-16 18:54:29 +03:00
parent cc584a97f3
commit ef223e13ff
19 changed files with 2736 additions and 0 deletions

61
AGENTS.md Normal file
View 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.