Files

vvzvlad ef223e13ff 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.

2026-06-16 18:54:29 +03:00

2.6 KiB

Raw Blame History

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.

2.6 KiB Raw Blame History