vvzvlad/gitmost
1
0
Fork 0
Code Issues 14 Pull Requests 12 Packages Projects Releases Activity

fix(git-sync): address PR #119 review (#1571)

Browse Source 
Resolve the code-review findings from comment #1571 on PR #119.

Engine (packages/git-sync):
- Idempotent CREATE on retry: before createPage, look the page up in the
  live Docmost tree by (parentPageId, title) and ADOPT it instead of
  duplicating when a prior cycle created it but failed to persist the
  pageId back to disk. Only trust a COMPLETE tree for the lookup; fall
  back to createPage otherwise. Covered by new tests incl. a complete=false
  regression-lock.
- Route applyPullActions diagnostics through an injected logger instead of
  bare console (thread log from the cycle).
- Add a timeout to the git execFile chokepoint (runRaw) so a hung git
  subprocess cannot wedge a sync cycle.
- Translate remaining Russian code comments to English.
- Remove dead standalone-CLI code (parseArgs/PushParsedArgs,
  parseSettings/envSchema, loadSettingsOrExit + config-errors.ts) and the
  matching index exports/specs; keep the Settings type.
- Fix the dangling docs link in package.json.
- Add a schema-surface snapshot guard so any drift in the vendored
  document schema is a loud, must-review CI failure (+ provenance header).

Server (apps/server):
- Add a configurable watchdog timeout to the spawned git http-backend so a
  stalled push cannot hold the per-space lock forever
  (GIT_SYNC_BACKEND_TIMEOUT_MS).
- Close the in-process TOCTOU window in SpaceLockService.withSpaceLock by
  reserving the slot synchronously before acquire.
- Add tests: removePage git-sync provenance (both branches), ensureServable
  force-push-protection git configs, and the phase-B+ datasource methods.

Docs / build:
- AGENTS.md: list git-sync as the fifth workspace package and note the
  three schema mirrors; fix the dangling git-sync-plan.md backlog link.
- pnpm-lock.yaml: add the missing @docmost/git-sync workspace link so
  pnpm install --frozen-lockfile (CI default) succeeds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
claude_code
2026-06-26 00:06:44 +03:00
committed by claude code agent 227
parent 52959de2f3
commit 28d2560dfd
31 changed files with 767 additions and 462 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/git-sync/package.json
View File

@@ -1,7 +1,7 @@
{
"name": "@docmost/git-sync",
"version": "0.1.0",
"description": "Pure converter + pure sync engine for the Docmost <-> git Markdown sync. See docs/git-sync-plan.md.",
"description": "Pure converter + pure sync engine for the Docmost <-> git Markdown sync. See docs/backlog/git-sync-thin-meta.md.",
"private": true,
"type": "module",
"main": "./build/index.js",

46
packages/git-sync/src/engine/config-errors.ts
View File

@@ -1,46 +0,0 @@
import { ZodError } from 'zod';
// Turn a ZodError from settings validation into a clear, actionable startup
// message that names the offending env var(s), then exit(1) — no raw stack
// trace. Mirrors the Python new-project skeleton's load_settings_or_exit.
// A non-ZodError is left to propagate unchanged.
export function loadSettingsOrExit<T>(factory: () => T): T {
try {
return factory();
} catch (err) {
if (!(err instanceof ZodError)) throw err;
const missing: string[] = [];
const invalid: string[] = [];
for (const issue of err.issues) {
const name = issue.path.length ? String(issue.path[0]) : '?';
// A missing required variable surfaces as an `invalid_type` issue whose
// received value was `undefined`. zod 3 exposed `issue.received` directly;
// zod 4 dropped that field and instead folds it into the message
// ("expected string, received undefined"). Detect both shapes so the
// missing-vs-invalid split holds across zod majors. NOTE: an invalid (but
// present) value uses a different code (invalid_format / invalid_value) or
// an `invalid_type` message that reports a non-undefined received (e.g.
// "received NaN" from a coerced number), so neither is misread as missing.
const i = issue as { received?: unknown; message?: string };
const isMissing =
issue.code === 'invalid_type' &&
(i.received === 'undefined' ||
/received undefined/i.test(i.message ?? ''));
if (isMissing) missing.push(name);
else invalid.push(`${name}: ${issue.message}`);
}
const lines = ['Configuration error in environment / .env:'];
if (missing.length) {
lines.push(' Missing required variable(s):');
for (const n of [...new Set(missing)]) lines.push(` - ${n}`);
}
if (invalid.length) {
lines.push(' Invalid value(s):');
for (const item of invalid) lines.push(` - ${item}`);
}
lines.push('');
lines.push('Set them in .env (see .env.example) and try again.');
process.stderr.write(lines.join('\n') + '\n');
process.exit(1);
}
}

1
packages/git-sync/src/engine/cycle.ts
View File

@@ -114,6 +114,7 @@ export async function runCycle(deps: RunCycleDeps): Promise<RunCycleResult> {
writeFile: (absPath, text) => fs.writeFile(absPath, text),
mkdir: (absDir) => fs.mkdir(absDir),
rm: (absPath) => fs.rm(absPath),
log,
},
pullActions,
vaultRoot,

13
packages/git-sync/src/engine/git.ts
View File

@@ -24,6 +24,12 @@ import { promisify } from "node:util";
const execFileAsync = promisify(execFile);
// Safety net: kill a hung git subprocess. This engine performs only LOCAL git
// operations (no network pushes), so a legitimate call never approaches this
// bound; it only prevents an indefinitely-stuck subprocess from wedging a sync
// cycle (the same risk the http-backend watchdog guards on the server side).
const GIT_EXEC_TIMEOUT_MS = 120_000;
/** Bot identity used for engine-authored vault commits (SPEC §7.3). */
export const BOT_AUTHOR_NAME = "Docmost Sync";
export const BOT_AUTHOR_EMAIL = "docmost-sync@local";
@@ -32,7 +38,7 @@ export const BOT_AUTHOR_EMAIL = "docmost-sync@local";
export const DEFAULT_BRANCH = "main";
/**
* One row of `git diff --name-status` (SPEC §6 "ФС → Docmost"). `status` is the
* One row of `git diff --name-status` (SPEC §6 "FS -> Docmost"). `status` is the
* single-letter change code (`-M` rename detection on), `path` is the (new) file
* path; for a rename/copy (`R`/`C`) `oldPath` is the source and `path` is the
* destination, with `score` carrying git's similarity index (0–100).
@@ -146,6 +152,7 @@ export class VaultGit {
// can be sizable.
...(cwd !== undefined ? { cwd } : {}),
maxBuffer: 64 * 1024 * 1024,
timeout: GIT_EXEC_TIMEOUT_MS,
env: vaultGitEnv(opts?.env),
},
);
@@ -413,7 +420,7 @@ export class VaultGit {
* the listing, e.g. `"*.md"`.
*
* The target wiki is RUSSIAN, so vault file names routinely contain Cyrillic
* (e.g. `Колонка.md`). With git's DEFAULT `core.quotepath=true`, `ls-files`
* (e.g. `Column.md` in Cyrillic). With git's DEFAULT `core.quotepath=true`, `ls-files`
* returns non-ASCII paths octal-escaped and double-quoted (`"\320\232..."`),
* which `src/pull.ts` `readExisting` would then parse as garbage paths,
* breaking move/duplicate detection. We defeat that two ways at once:
@@ -519,7 +526,7 @@ export class VaultGit {
/**
* Read a ref to its SHA, or `null` if unset. Thin alias over `revParse`,
* named for the push direction's marker `refs/docmost/last-pushed` (SPEC §5:
* "что из `main` уже отражено в Docmost").
* "what of `main` is already reflected in Docmost").
*/
async readRef(ref: string): Promise<string | null> {
return this.revParse(ref);

2
packages/git-sync/src/engine/loop-guard.ts
View File

@@ -13,7 +13,7 @@
import { createHash } from "node:crypto";
/**
* Stable hash of a page's markdown BODY (SPEC §10 "хэш тела"). Deterministic:
* Stable hash of a page's markdown BODY (SPEC §10 "body hash"). Deterministic:
* the same input string always yields the same digest, a different input a
* different one. Used to recognize our own write later (loop suppression).
*

38
packages/git-sync/src/engine/pull.ts
View File

@@ -1,5 +1,5 @@
/**
* Pull cycle — Docmost -> vault (SPEC §6 "Docmost -> ФС").
* Pull cycle — Docmost -> vault (SPEC §6 "Docmost -> FS").
*
* This increment turns the read-only mirror into the git-backed pull cycle:
*
@@ -225,6 +225,11 @@ export interface ApplyPullActionsDeps {
mkdir: (absDir: string) => Promise<void>;
/** Remove a file by ABSOLUTE path (force: a missing file is a no-op). */
rm: (absPath: string) => Promise<void>;
/**
* Injected logger for cycle diagnostics (mirrors the push side). Optional —
* falls back to `console.log` so existing callers stay green.
*/
log?: (line: string) => void;
}
/** Outcome counters from `applyPullActions` (for the summary + tests). */
@@ -259,22 +264,25 @@ export async function applyPullActions(
vaultRoot: string,
): Promise<ApplyResult> {
const { client, git } = deps;
// One channel, mirroring the push side: route every cycle diagnostic through
// the injected logger; fall back to `console.log` when none is supplied.
const log = deps.log ?? ((line: string) => console.log(line));
// Emit the SPEC §8 suppression warnings (preserved from the original `main`).
const decision = actions.deletionDecision;
if (!decision.apply) {
if (decision.reason === "incomplete-fetch") {
console.warn(
log(
"pull: tree fetch incomplete — deletions suppressed this cycle (SPEC §8)",
);
} else if (decision.reason === "empty-live") {
console.warn(
log(
`pull: live fetch returned 0 pages but ${actions.existingCount} file(s) are ` +
`tracked — deletions suppressed this cycle (SPEC §8). Re-run when ` +
`Docmost is reachable.`,
);
} else {
console.warn(
log(
`pull: plan would delete ${actions.plannedDeleteCount} of ${actions.existingCount} ` +
`tracked file(s) (mass-delete guard) — deletions suppressed this ` +
`cycle (SPEC §8). Verify the live Docmost tree, then re-run.`,
@@ -311,14 +319,14 @@ export async function applyPullActions(
} catch (err) {
failed++;
failedPageIds.add(w.pageId);
console.error(
`pull: failed page ${w.pageId}:`,
err instanceof Error ? err.message : String(err),
log(
`pull: failed page ${w.pageId}: ` +
(err instanceof Error ? err.message : String(err)),
);
} finally {
completed++;
if (completed % PROGRESS_EVERY === 0) {
console.log(`pulled ${completed}/${actions.toWrite.length}`);
log(`pulled ${completed}/${actions.toWrite.length}`);
}
}
};
@@ -346,9 +354,9 @@ export async function applyPullActions(
await deps.rm(relToAbs(vaultRoot, rel));
return true;
} catch (err) {
console.error(
`pull: failed to ${what} ${rel}:`,
err instanceof Error ? err.message : String(err),
log(
`pull: failed to ${what} ${rel}: ` +
(err instanceof Error ? err.message : String(err)),
);
return false;
}
@@ -364,7 +372,7 @@ export async function applyPullActions(
for (const m of actions.moved) {
if (!m.removeOldPath) continue;
if (failedPageIds.has(m.pageId)) {
console.warn(
log(
`pull: move write for ${m.pageId} failed — keeping old path ` +
`${m.fromRelPath} (SPEC §8)`,
);
@@ -401,15 +409,15 @@ export async function applyPullActions(
await git.checkout(DEFAULT_BRANCH);
const merge = await git.merge(DOCMOST_BRANCH);
if (merge.conflict) {
console.error(
log(
"pull: merge of docmost -> main CONFLICTED. Conflict markers were left " +
"in the vault for manual resolution (SPEC §9). Nothing is pushed to " +
"Docmost (read-only). Resolve locally, then re-run.",
);
} else if (!merge.ok) {
console.error(`pull: merge of docmost -> main failed: ${merge.output}`);
log(`pull: merge of docmost -> main failed: ${merge.output}`);
}
console.log("pull: git push to remote is DEFERRED in this increment (SPEC §7).");
log("pull: git push to remote is DEFERRED in this increment (SPEC §7).");
return { written, movedApplied, deleted, failed, committed, merge };
}

77
packages/git-sync/src/engine/push.ts
View File

@@ -1,5 +1,5 @@
/**
* Push cycle — vault -> Docmost (SPEC §6 "ФС → Docmost"), FIRST increment.
* Push cycle — vault -> Docmost (SPEC §6 "FS -> Docmost"), FIRST increment.
*
* This module mirrors the structure of `./pull.ts`: a set of VaultGit diff/ref
* primitives (in `./git.ts`), a PURE planner (`computePushActions`) that turns
@@ -65,7 +65,7 @@ export interface RenameMoveAction {
/**
* A CLASSIFIED rename/move (push #3): a `RenameMoveAction` resolved into the
* Docmost op(s) it actually needs. The file PATH is the source of truth for tree
* position (SPEC §5: "истина связи — pageId, не путь" — the path is COSMETIC and
* position (SPEC §5: "the identity is the pageId, not the path" — the path is COSMETIC and
* LOCAL, the page identity is its pageId), so we compare the RESOLVED parent of
* the new path against the resolved parent of the old path, and the title in the
* current meta against the title in the previous meta. Each sub-op is emitted
@@ -235,7 +235,7 @@ export interface PushActionsInput {
*/
export function computePushActions(input: PushActionsInput): PushActions {
const { metaAt, currentPageIds } = input;
// PAGE-FILE FILTER (design §"Адопция"): only `.md` files OUTSIDE any dot-folder
// PAGE-FILE FILTER (design §"Adoption"): only `.md` files OUTSIDE any dot-folder
// are Docmost pages. `.obsidian/*`, attachments, and other non-page files are
// committed to the vault (no `.gitignore`) and so appear in the diff, but they
// are NEVER pages — Obsidian owns them. Without this filter every ADDED such
@@ -445,6 +445,7 @@ export const DOCMOST_BRANCH = "docmost";
export interface ApplyPushDeps {
client: Pick<
GitSyncClient,
| "listSpaceTree"
| "importPageMarkdown"
| "createPage"
| "deletePage"
@@ -489,7 +490,7 @@ export interface PushedPageRecord {
* exposed one. Absent when the (fake) client did not return it.
*/
updatedAt?: string;
/** Stable hash of the markdown BODY that was pushed (SPEC §10 "хэш тела"). */
/** Stable hash of the markdown BODY that was pushed (SPEC §10 "body hash"). */
bodyHash: string;
}
@@ -675,8 +676,34 @@ export async function applyPushActions(
}
// 2. CREATES — create the page, then write the assigned pageId back to meta so
// the file becomes tracked (SPEC §4 "записать присвоенный pageId обратно").
// the file becomes tracked (SPEC §4 "write the assigned pageId back").
// Isolated per page like updates.
//
// RETRY-ADOPT (#1 idempotency): create is NOT atomic with the pageId write-back
// (createPage runs, then writeFile, then the write-back commit at runPush 7a). If
// the write-back dies in between, the file on disk still has no pageId and the
// next cycle re-classifies it as a CREATE -> a DUPLICATE page would be created.
// To guard against this, build a (parentPageId|root, title) -> existing pageId map
// ONCE from the LIVE Docmost tree (only when there is at least one create). The
// native-Obsidian layout makes filenames — and therefore titles — unique within a
// folder, so (parentPageId, title) identifies the page; a match means a prior
// cycle already created it, so we ADOPT instead of duplicating.
let liveByParentTitle: Map<string, string> | null = null;
if (actions.creates.length > 0) {
const live = await client.listSpaceTree(deps.spaceId);
// Only trust a COMPLETE tree for retry-adopt: a truncated tree could miss an
// already-created page and let us create a DUPLICATE (the very thing adopt
// prevents). The native client always returns complete:true (reads the DB);
// on an incomplete tree we leave the map null -> fall back to plain createPage.
if (live.complete) {
liveByParentTitle = new Map();
for (const n of live.pages) {
const key = `${n.parentPageId ?? " root"} ${n.title ?? ""}`;
// Keep the FIRST node for a key (the layout makes this unique in practice).
if (!liveByParentTitle.has(key)) liveByParentTitle.set(key, n.id);
}
}
}
for (const c of actions.creates) {
try {
const text = await deps.readFile(c.path);
@@ -687,6 +714,26 @@ export async function applyPushActions(
const title = titleFromPath(c.path);
const parentPageId =
(await resolveParentPageIdViaTree(deps, c.path, "current")) ?? undefined;
// Retry-adopt (#1 idempotency): a prior cycle already created this page in
// Docmost but failed to persist the pageId back to the file, so it was
// re-seen as a create. Adopt the existing page instead of duplicating it:
// write the id back (file becomes tracked) and push the body as an UPDATE
// (idempotent — targets by pageId). Do NOT call createPage again.
const adoptKey = `${parentPageId ?? " root"} ${title}`;
const existingId = liveByParentTitle?.get(adoptKey);
if (existingId) {
const rewritten = serializePageFile(existingId, body);
await deps.writeFile(c.path, rewritten);
writtenBack.push({ path: c.path, pageId: existingId });
const adopted = await client.importPageMarkdown(existingId, body, null);
pushed.push({
pageId: existingId,
...extractUpdatedAt(adopted),
bodyHash: bodyHash(body),
});
created++;
continue;
}
const result = await client.createPage(
title,
body,
@@ -896,7 +943,7 @@ export function parentFolderFile(path: string): string | null {
}
/**
* Whether a vault path is a Docmost PAGE file (design §"Адопция"): a `.md` file
* Whether a vault path is a Docmost PAGE file (design §"Adoption"): a `.md` file
* with NO dot-segment anywhere in its path. This excludes `.obsidian/` config,
* `.trash/`, dotfiles (`.foo.md`), and every non-`.md` file (attachments, JSON,
* …) — Obsidian owns those; they live in the vault but are never pages. Used to
@@ -954,7 +1001,7 @@ function nativeMeta(
* then read its `gitmost_id` frontmatter and return that page's pageId. A root-level path
* (no enclosing folder), a missing/unreadable parent file, or a parent file with
* no parseable pageId all resolve to `null` (parent is ROOT / unknown ->
* `parentPageId: null`, SPEC §16 "parentPageId: null -> в корень").
* `parentPageId: null`, SPEC §16 "parentPageId: null -> to root").
*
* The IO is async, so this returns an ASYNC resolver; the call sites prefetch the
* parent pageIds (the classifier itself stays pure/sync over a plain table).
@@ -1112,7 +1159,7 @@ export interface PushRunResult {
}
/**
* Run one FS->Docmost push cycle (SPEC §6 "ФС → Docmost"), DRY-RUN BY DEFAULT.
* Run one FS->Docmost push cycle (SPEC §6 "FS -> Docmost"), DRY-RUN BY DEFAULT.
*
* Steps (mirrors `pull.ts`):
* 1. Preflight git: `assertGitAvailable` + `ensureRepo`; ABORT (clear message +
@@ -1426,17 +1473,3 @@ function logPlan(
for (const s of actions.skipped)
log(` skipped [${s.status}] ${s.path}: ${s.reason}`);
}
/** Parsed `push` CLI flags. DRY-RUN is the default; `--apply` opts into writes. */
export interface PushParsedArgs {
/** True when `--apply` was passed (the ONLY path that writes to Docmost). */
apply: boolean;
}
/**
* Parse the `push` CLI flags. SAFE BY DEFAULT: without `--apply` the run is a
* DRY-RUN (plan only). Exported so the flag handling is unit-testable.
*/
export function parseArgs(argv: string[]): PushParsedArgs {
return { apply: argv.includes("--apply") };
}

54
packages/git-sync/src/engine/settings.ts
View File

@@ -2,41 +2,10 @@
* Engine settings.
*
* The engine is driven IN-PROCESS by the NestJS server, which builds the
* `Settings` object from `EnvironmentService` — so this module must NOT reach
* into `process.env`. It exposes only:
* - the `Settings` type the engine consumes, and
* - `parseSettings(env)` as a PURE function (validate a raw env object -> typed
* `Settings`), kept for unit tests and for the server to reuse if it wants
* to validate an env-shaped object.
* There is no `.env`-loading side-effecting entry point.
* `Settings` object from `EnvironmentService`. This module therefore exposes
* ONLY the `Settings` type the engine consumes — there is no `.env`-loading
* side-effecting entry point and no env-validation here (the server owns that).
*/
import { z } from 'zod';
// Schema keyed by the real ENV variable names so validation errors name the
// exact variable. Credentials and the address of our OWN Docmost instance have
// NO default — a missing value must fail at startup, never silently fall back.
export const envSchema = z.object({
// Docmost connection — address of our own instance, no default.
DOCMOST_API_URL: z.string().url(),
// Credentials for /auth/login — no default, never hardcoded.
DOCMOST_EMAIL: z.string().min(1),
DOCMOST_PASSWORD: z.string().min(1),
// Which Docmost space to mirror.
DOCMOST_SPACE_ID: z.string().min(1),
// Local git vault (state store) — kept under data/ so the volume persists it.
VAULT_PATH: z.string().min(1).default('data/vault'),
// Optional git remote the vault pushes to. Empty string is treated as unset.
GIT_REMOTE: z.preprocess(
(v) => (v === '' ? undefined : v),
z.string().min(1).optional(),
),
// Non-secret tunables — sensible defaults are fine.
POLL_INTERVAL_MS: z.coerce.number().int().positive().default(15000),
DEBOUNCE_MS: z.coerce.number().int().positive().default(2000),
LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});
export type Settings = {
docmostApiUrl: string;
@@ -49,20 +18,3 @@ export type Settings = {
debounceMs: number;
logLevel: 'debug' | 'info' | 'warn' | 'error';
};
// Pure: validate a raw environment object and map it to a typed Settings.
// Throws ZodError on bad config. No side effects — safe to import in tests.
export function parseSettings(env: NodeJS.ProcessEnv): Settings {
const e = envSchema.parse(env);
return {
docmostApiUrl: e.DOCMOST_API_URL,
docmostEmail: e.DOCMOST_EMAIL,
docmostPassword: e.DOCMOST_PASSWORD,
docmostSpaceId: e.DOCMOST_SPACE_ID,
vaultPath: e.VAULT_PATH,
gitRemote: e.GIT_REMOTE,
pollIntervalMs: e.POLL_INTERVAL_MS,
debounceMs: e.DEBOUNCE_MS,
logLevel: e.LOG_LEVEL,
};
}

2
packages/git-sync/src/engine/stabilize.ts
View File

@@ -1,5 +1,5 @@
/**
* Normalize-on-write helper (SPEC §11 "Резолюция").
* Normalize-on-write helper (SPEC §11 "Resolution").
*
* git diffs byte-for-byte, so writing a page in a NON-fixpoint markdown form
* would make the next pull re-export it to a slightly different (but stable)

5
packages/git-sync/src/index.ts
View File

@@ -81,7 +81,6 @@ export {
applyPushActions,
runPush,
parentFolderFile,
parseArgs,
LAST_PUSHED_REF,
DOCMOST_BRANCH,
LOCAL_AUTHOR_NAME,
@@ -106,14 +105,10 @@ export type {
ApplyPushResult,
PushDeps,
PushRunResult,
PushParsedArgs,
} from "./engine/push.js";
export { parseSettings, envSchema } from "./engine/settings.js";
export type { Settings } from "./engine/settings.js";
export { loadSettingsOrExit } from "./engine/config-errors.js";
export { runCycle } from "./engine/cycle.js";
export type {
RunCycleDeps,

2
packages/git-sync/src/lib/canonicalize.ts
View File

@@ -1,6 +1,6 @@
/**
* Semantic canonicalization of ProseMirror/TipTap documents for the round-trip
* idempotency check (SPEC §11, "Задача №0", option (б): compare a CANONICALIZED
* idempotency check (SPEC §11, "Task #0", option (b): compare a CANONICALIZED
* form rather than raw bytes).
*
* `markdownToProseMirror` reconstructs schema DEFAULT attributes (e.g.

4
packages/git-sync/src/lib/diff.ts
View File

@@ -103,8 +103,8 @@ function countUniqueLinks(doc: any): number {
/**
* Parse the ordered list of integers from `[N]` footnote markers found in the
* BODY only (every top-level block before the first "Примечания..." notes
* heading; if no such heading, the whole doc). Returned in reading order.
* BODY only (every top-level block before the first notes heading; if no such
* heading, the whole doc). Returned in reading order.
*/
function footnoteMarkers(doc: any, notesHeading: string): number[] {
const top: any[] = Array.isArray(doc?.content) ? doc.content : [];

8
packages/git-sync/src/lib/docmost-schema.ts
View File

@@ -6,6 +6,14 @@
* (node ids, image sizing, link targets). Every code path that converts
* to or from ProseMirror JSON must use THIS set, otherwise a round-trip
* loses content.
*
* PROVENANCE / KEEP IN SYNC: this file is a VENDORED MIRROR of the canonical
* Docmost document schema in `@docmost/editor-ext`. The node/mark/attribute
* surface MUST be kept in sync with editor-ext — anything present there but
* missing here is silently dropped on a round-trip (data loss). The exported
* `docmostExtensions` surface is guarded by `test/schema-surface-snapshot.test.ts`,
* which fails loudly on any drift; when it does, re-verify parity against
* `@docmost/editor-ext` before updating the snapshot.
*/
import StarterKit from "@tiptap/starter-kit";
import Image from "@tiptap/extension-image";

47
packages/git-sync/test/apply-pull-actions.test.ts
View File

@@ -99,17 +99,25 @@ function makeFs(opts?: { failWriteFor?: Set<string> }) {
return { fs, writes, mkdirs, rms };
}
// A single injected `log` spy mirrors the push side: applyPullActions now routes
// EVERY cycle diagnostic through `deps.log` (one channel), so tests inspect this
// spy instead of console.warn/console.error. `deps()` creates a fresh spy per
// call and stashes it on `lastLog` for the current test to assert against.
let lastLog: ReturnType<typeof vi.fn>;
function deps(
client: any,
git: any,
fs: ReturnType<typeof makeFs>,
): ApplyPullActionsDeps {
lastLog = vi.fn();
return {
client,
git,
writeFile: fs.fs.writeFile,
mkdir: fs.fs.mkdir,
rm: fs.fs.rm,
log: lastLog,
};
}
@@ -341,7 +349,7 @@ describe('applyPullActions — deletion suppression (SPEC §8)', () => {
// Subject reflects 0 deleted (no ", N deleted" suffix).
expect(g.committedSubject).toBe('docmost: sync 1 page(s)');
// The suppression warning was emitted.
expect(console.warn).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/tree fetch incomplete/),
);
});
@@ -472,10 +480,10 @@ describe('applyPullActions — suppression warning forks (empty-live / mass-dele
expect(fs.rms).toEqual([]);
// The empty-live message names the tracked-file count and "deletions
// suppressed".
expect(console.warn).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/live fetch returned 0 pages but 4 file\(s\) are tracked/),
);
expect(console.warn).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/deletions suppressed/),
);
});
@@ -502,10 +510,10 @@ describe('applyPullActions — suppression warning forks (empty-live / mass-dele
expect(res.deleted).toBe(0);
expect(fs.rms).toEqual([]);
expect(console.warn).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/plan would delete 5 of 6 tracked file\(s\) \(mass-delete guard\)/),
);
expect(console.warn).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/deletions suppressed/),
);
});
@@ -513,8 +521,8 @@ describe('applyPullActions — suppression warning forks (empty-live / mass-dele
describe('applyPullActions — removePath fault tolerance (rm REJECTS)', () => {
it('does NOT reject, logs the failure, and does not count the failed removal', async () => {
// pull.ts 354-364: when `deps.rm` throws, removePath logs via console.error
// and returns false; the run continues. Existing delete tests use an rm
// pull.ts removePath catch: when `deps.rm` throws, it logs via the injected
// `log` and returns false; the run continues. Existing delete tests use an rm
// that always succeeds, leaving this catch branch uncovered.
const { client } = makeClient();
const g = makeGit();
@@ -535,9 +543,8 @@ describe('applyPullActions — removePath fault tolerance (rm REJECTS)', () => {
// Resolved (not rejected) — the pull is fault-tolerant.
expect(res.deleted).toBe(0);
// removePath's catch logs "pull: failed to delete Dead.md: ...".
expect(console.error).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/failed to .* Dead\.md/),
expect.anything(),
);
// The (would-be) removal never succeeded, so nothing was recorded.
expect(fs.rms).toEqual([]);
@@ -567,12 +574,13 @@ describe('applyPullActions — removePath fault tolerance (rm REJECTS)', () => {
expect(res.deleted).toBe(2);
expect(fs.rms).toEqual(['/vault/Dead1.md', '/vault/Dead3.md']);
expect(g.committedSubject).toBe('docmost: sync 0 page(s), 2 deleted');
// Exactly one rejection was logged (Dead2.md).
expect(console.error).toHaveBeenCalledTimes(1);
expect(console.error).toHaveBeenCalledWith(
expect.stringMatching(/failed to .* Dead2\.md/),
expect.anything(),
);
// Exactly one rejection was logged (Dead2.md). Other diagnostics share the
// `log` channel, so count ONLY the "failed to ..." failure lines.
const failLines = lastLog.mock.calls
.map((c: unknown[]) => String(c[0]))
.filter((m: string) => /failed to /.test(m));
expect(failLines.length).toBe(1);
expect(failLines[0]).toMatch(/failed to .* Dead2\.md/);
// The run still reached commit + checkout + merge.
expect(g.order).toEqual([
'stageAll',
@@ -620,17 +628,16 @@ describe('applyPullActions — move old-path removal rejects vs move-write fails
expect(fs.rms).toEqual(['/vault/Dead.md']); // Old/M.md rm threw, not recorded
expect(g.committedSubject).toBe('docmost: sync 1 page(s), 1 deleted');
// The failure log named the moved old path.
expect(console.error).toHaveBeenCalledWith(
expect(lastLog).toHaveBeenCalledWith(
expect.stringMatching(/failed to .* Old\/M\.md/),
expect.anything(),
);
});
it('a move-write FAILURE keeps the old path: rm is never attempted for it (data-loss guard, 374-383)', async () => {
// Distinct branch from the move-old-path rm rejection above: here the
// new-path WRITE itself fails, so `m` enters failedPageIds and the move
// loop short-circuits at line 376 BEFORE calling rm — emitting a
// console.warn and PRESERVING the old path (the only copy).
// loop short-circuits BEFORE calling rm — emitting a warning via the
// injected `log` and PRESERVING the old path (the only copy).
const { client } = makeClient();
const g = makeGit();
const fs = makeFs({ failWriteFor: new Set(['/vault/New/M.md']) });
@@ -661,7 +668,7 @@ describe('applyPullActions — move old-path removal rejects vs move-write fails
expect(fs.fs.rm).not.toHaveBeenCalledWith('/vault/Old/M.md');
expect(fs.rms).toEqual([]);
// The "keeping old path" warning fired exactly once for `m`.
const warnCalls = (console.warn as unknown as ReturnType<typeof vi.fn>).mock.calls
const warnCalls = lastLog.mock.calls
.map((c: unknown[]) => String(c[0]))
.filter((m: string) => m.includes('move write for m failed'));
expect(warnCalls.length).toBe(1);

143
packages/git-sync/test/apply-push-actions.test.ts
View File

@@ -18,6 +18,12 @@ const SPACE_ID = 'sp-test';
/** A recording client fake; createPage returns a configurable assigned id. */
function makeClient(opts?: { createId?: string }) {
const client = {
// Empty live tree by default -> creates take the normal createPage path; the
// retry-adopt lookup only fires when a (parentPageId, title) node matches.
listSpaceTree: vi.fn(async () => ({
pages: [] as { id: string; parentPageId?: string | null; title?: string }[],
complete: true,
})),
importPageMarkdown: vi.fn(async (_pageId: string, _md: string) => ({
success: true,
})),
@@ -227,6 +233,143 @@ describe('applyPushActions — create (assigned pageId written back to meta)', (
});
});
describe('applyPushActions — create RETRY-ADOPT idempotency (#1)', () => {
// Create is NOT atomic with the pageId write-back: if a prior cycle created the
// page in Docmost but died before persisting the id back, the file is re-seen as
// a CREATE. The applier must ADOPT the existing page (write the id back + push the
// body as an idempotent UPDATE) instead of calling createPage again (which would
// duplicate the page). The live page is matched by (parentPageId, title).
it('ADOPTS an existing page (no createPage) when the live tree already has a match', async () => {
const client = makeClient({ createId: 'should-not-be-used' });
// The live Docmost tree already has the page this create targets:
// title "My New Page" under the parent folder's page `parent-9`.
client.listSpaceTree.mockResolvedValue({
pages: [
{ id: 'parent-9', parentPageId: null, title: 'Parent' },
{ id: 'already-created-7', parentPageId: 'parent-9', title: 'My New Page' },
],
complete: true,
});
const { git } = makeGit();
const fs = makeFs({
'Parent/My New Page.md': '# My New Page\n\nbody text\n',
'Parent/Parent.md': fileFor('parent-9'),
});
const res = await applyPushActions(
deps(client, git, fs),
actions({ creates: [{ path: 'Parent/My New Page.md' }] }),
);
expect(res.created).toBe(1);
// CRITICAL: createPage was NOT called — no duplicate page in Docmost.
expect(client.createPage).not.toHaveBeenCalled();
// The body was pushed as an UPDATE targeting the EXISTING id (idempotent).
expect(client.importPageMarkdown).toHaveBeenCalledTimes(1);
expect(client.importPageMarkdown).toHaveBeenCalledWith(
'already-created-7',
expect.stringContaining('body text'),
null,
);
// The file was rewritten with the EXISTING id as gitmost_id (now tracked).
expect(fs.writes.map((w) => w.path)).toEqual(['Parent/My New Page.md']);
const rewritten = fs.store['Parent/My New Page.md'];
expect(parsePageFile(rewritten).id).toBe('already-created-7');
expect(res.writtenBack).toEqual([
{ path: 'Parent/My New Page.md', pageId: 'already-created-7' },
]);
});
it('does NOT adopt from an INCOMPLETE tree even when a node matches (falls back to createPage)', async () => {
// Defensive guard: retry-adopt is only safe from a COMPLETE live tree. A
// TRUNCATED tree (complete:false) could miss an already-created page and let
// us duplicate it — the very thing adopt prevents. So on an incomplete tree
// the map is NOT built and we MUST fall back to the normal createPage path,
// even though this particular tree happens to carry a matching node.
const client = makeClient({ createId: 'page-new-55' });
// A node that WOULD match the create's (parentPageId 'parent-9', title
// 'My New Page') — but the tree is flagged incomplete, so it must be ignored.
client.listSpaceTree.mockResolvedValue({
pages: [
{ id: 'parent-9', parentPageId: null, title: 'Parent' },
{ id: 'already-created-7', parentPageId: 'parent-9', title: 'My New Page' },
],
complete: false,
});
const { git } = makeGit();
const fs = makeFs({
'Parent/My New Page.md': '# My New Page\n\nbody text\n',
'Parent/Parent.md': fileFor('parent-9'),
});
const res = await applyPushActions(
deps(client, git, fs),
actions({ creates: [{ path: 'Parent/My New Page.md' }] }),
);
expect(res.created).toBe(1);
// CRITICAL: createPage ran (normal path) — adopt was suppressed by complete:false.
expect(client.createPage).toHaveBeenCalledTimes(1);
// No adopt-UPDATE happened: the matching node was NOT trusted.
expect(client.importPageMarkdown).not.toHaveBeenCalled();
// The file carries the NEWLY assigned id, not the would-be adopted one.
expect(parsePageFile(fs.store['Parent/My New Page.md']).id).toBe('page-new-55');
expect(res.writtenBack).toEqual([
{ path: 'Parent/My New Page.md', pageId: 'page-new-55' },
]);
});
it('a NORMAL create (empty live tree) STILL calls createPage', async () => {
// No matching live node -> the happy path: createPage runs, no adopt.
const client = makeClient({ createId: 'page-new-99' });
// makeClient's listSpaceTree returns an empty tree by default.
const { git } = makeGit();
const fs = makeFs({
'Parent/My New Page.md': '# My New Page\n\nbody text\n',
'Parent/Parent.md': fileFor('parent-9'),
});
const res = await applyPushActions(
deps(client, git, fs),
actions({ creates: [{ path: 'Parent/My New Page.md' }] }),
);
expect(res.created).toBe(1);
expect(client.createPage).toHaveBeenCalledTimes(1);
// No adopt-UPDATE happened (importPageMarkdown is the update path).
expect(client.importPageMarkdown).not.toHaveBeenCalled();
expect(parsePageFile(fs.store['Parent/My New Page.md']).id).toBe('page-new-99');
});
it('a thrown adopt is isolated as a `create` failure (per-page isolation, SPEC §12)', async () => {
const client = makeClient({ createId: 'unused' });
client.listSpaceTree.mockResolvedValue({
pages: [{ id: 'existing-1', parentPageId: null, title: 'Doc' }],
complete: true,
});
// The adopt pushes the body as an UPDATE; make that throw.
client.importPageMarkdown.mockRejectedValue(new Error('adopt boom'));
const { git, updateRefCalls } = makeGit();
const fs = makeFs({ 'Doc.md': '# Doc\n\nbody\n' });
const res = await applyPushActions(
deps(client, git, fs),
actions({ creates: [{ path: 'Doc.md' }] }),
'sha-adopt-fail',
);
expect(res.created).toBe(0);
expect(client.createPage).not.toHaveBeenCalled();
expect(res.failures).toEqual([
{ kind: 'create', path: 'Doc.md', error: 'adopt boom' },
]);
// A failure means the refs are NOT advanced (re-run retries cleanly, §12).
expect(res.lastPushedAdvanced).toBe(false);
expect(updateRefCalls).toEqual([]);
});
});
describe('applyPushActions — delete (soft-delete to Trash, SPEC §8)', () => {
it('calls deletePage(pageId)', async () => {
const client = makeClient();

139
packages/git-sync/test/config-errors-invalid.test.ts
View File

@@ -1,139 +0,0 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import { z, ZodError } from 'zod';
import { loadSettingsOrExit } from '../src/engine/config-errors';
import { envSchema } from '../src/engine/settings';
// Companion to test/config-errors.test.ts. That file covers the success path,
// the MISSING-required (undefined -> invalid_type) -> exit branch, and the
// non-ZodError passthrough. This file fills the remaining GAP: the
// INVALID-VALUE branch (config-errors.ts lines ~20, 27-30). A ZodError whose
// issue is a CONSTRAINT violation (bad URL, bad enum, too-short string) is NOT
// a missing key, so it must be routed into the `invalid` bucket and reported
// under the "Invalid value(s)" heading with a `<name>: <message>` line — a
// distinct, operator-facing message from the missing-variable case.
describe('loadSettingsOrExit — invalid-value branch', () => {
afterEach(() => {
vi.restoreAllMocks();
});
// Stub process.exit so it throws (control stops at the exit point without
// killing the runner) and capture everything written to stderr. Mirrors the
// approach in the existing config-errors.test.ts.
function stubExitAndStderr() {
const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((
code?: number,
) => {
throw new Error(`exit:${code}`);
}) as never);
const writeSpy = vi
.spyOn(process.stderr, 'write')
.mockImplementation(() => true);
const written = () => writeSpy.mock.calls.map((c) => String(c[0])).join('');
return { exitSpy, writeSpy, written };
}
it('exits(1) and reports an invalid value (bad URL) under "Invalid value(s)"', () => {
const { exitSpy, written } = stubExitAndStderr();
// A present-but-invalid DOCMOST_API_URL: the value exists (so it is NOT a
// missing-key issue), but fails the .url() constraint -> goes to `invalid`.
expect(() =>
loadSettingsOrExit(() =>
envSchema.parse({
DOCMOST_API_URL: 'not-a-url',
DOCMOST_EMAIL: 'ops@example.com',
DOCMOST_PASSWORD: 'hunter2',
DOCMOST_SPACE_ID: 'space-1',
}),
),
).toThrow('exit:1');
expect(exitSpy).toHaveBeenCalledWith(1);
const out = written();
// The invalid-value heading must appear...
expect(out).toContain('Invalid value(s)');
// ...and it must name the offending variable on a `<name>: <message>` line.
expect(out).toContain('DOCMOST_API_URL:');
// The header line is always present.
expect(out).toContain('Configuration error in environment / .env:');
// It must NOT misreport an invalid value as a missing one.
expect(out).not.toContain('Missing required variable(s)');
});
it('exits(1) and reports an invalid enum value (LOG_LEVEL)', () => {
const { exitSpy, written } = stubExitAndStderr();
// All required vars present and valid; only LOG_LEVEL violates the enum.
expect(() =>
loadSettingsOrExit(() =>
envSchema.parse({
DOCMOST_API_URL: 'https://docs.example.com/api',
DOCMOST_EMAIL: 'ops@example.com',
DOCMOST_PASSWORD: 'hunter2',
DOCMOST_SPACE_ID: 'space-1',
LOG_LEVEL: 'verbose', // not in ['debug','info','warn','error']
}),
),
).toThrow('exit:1');
expect(exitSpy).toHaveBeenCalledWith(1);
const out = written();
expect(out).toContain('Invalid value(s)');
expect(out).toContain('LOG_LEVEL:');
expect(out).not.toContain('Missing required variable(s)');
});
it('routes a hand-built constraint-violation ZodError into the invalid bucket', () => {
const { exitSpy, written } = stubExitAndStderr();
// Construct the ZodError directly from a min-length violation so the test
// does not depend on the project schema's exact field set. The issue has a
// non-empty path (so a variable name is printed) and code "too_small"
// (NOT invalid_type/undefined), so config-errors.ts classifies it as
// invalid rather than missing.
const zerr = new ZodError([
{
code: 'too_small',
minimum: 1,
type: 'string',
inclusive: true,
path: ['DOCMOST_PASSWORD'],
message: 'String must contain at least 1 character(s)',
} as z.ZodIssue,
]);
expect(() =>
loadSettingsOrExit(() => {
throw zerr;
}),
).toThrow('exit:1');
expect(exitSpy).toHaveBeenCalledWith(1);
const out = written();
expect(out).toContain('Invalid value(s)');
expect(out).toContain('DOCMOST_PASSWORD: String must contain at least 1');
expect(out).not.toContain('Missing required variable(s)');
});
it('reports missing AND invalid in their own sections when both occur', () => {
const { exitSpy, written } = stubExitAndStderr();
// DOCMOST_API_URL present but invalid (-> invalid section); the three other
// required vars absent (-> missing section). Confirms the two branches are
// populated and emitted independently.
expect(() =>
loadSettingsOrExit(() =>
envSchema.parse({
DOCMOST_API_URL: 'not-a-url',
}),
),
).toThrow('exit:1');
expect(exitSpy).toHaveBeenCalledWith(1);
const out = written();
expect(out).toContain('Missing required variable(s)');
expect(out).toContain('Invalid value(s)');
expect(out).toContain('DOCMOST_API_URL:');
expect(out).toContain('DOCMOST_EMAIL');
});
});

56
packages/git-sync/test/config-errors.test.ts
View File

@@ -1,56 +0,0 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import { z } from 'zod';
import { loadSettingsOrExit } from '../src/engine/config-errors';
describe('loadSettingsOrExit', () => {
afterEach(() => {
vi.restoreAllMocks();
});
it('returns the factory value and does not exit on success', () => {
const exitSpy = vi
.spyOn(process, 'exit')
.mockImplementation((() => undefined) as never);
const result = loadSettingsOrExit(() => ({ ok: true }));
expect(result).toEqual({ ok: true });
expect(exitSpy).not.toHaveBeenCalled();
});
it('prints a named-variable message and exits(1) on a ZodError', () => {
// Mock process.exit to throw so control stops at the exit point, mirroring
// the real exit-the-process behaviour without killing the test runner.
const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((
code?: number,
) => {
throw new Error(`exit:${code}`);
}) as never);
const writeSpy = vi
.spyOn(process.stderr, 'write')
.mockImplementation(() => true);
expect(() =>
loadSettingsOrExit(() => z.object({ FOO: z.string() }).parse({})),
).toThrow('exit:1');
expect(exitSpy).toHaveBeenCalledWith(1);
const written = writeSpy.mock.calls.map((c) => String(c[0])).join('');
expect(written).toContain('Missing required variable(s)');
expect(written).toContain('FOO');
});
it('propagates a non-ZodError without exiting', () => {
const exitSpy = vi
.spyOn(process, 'exit')
.mockImplementation((() => undefined) as never);
const boom = new Error('x');
expect(() =>
loadSettingsOrExit(() => {
throw boom;
}),
).toThrow(boom);
expect(exitSpy).not.toHaveBeenCalled();
});
});

1
packages/git-sync/test/engine-gaps.test.ts
View File

@@ -263,6 +263,7 @@ describe('applyPushActions (push.ts) — move prefetch isolation', () => {
function makeClient() {
return {
listSpaceTree: vi.fn(async () => ({ pages: [], complete: true })),
importPageMarkdown: vi.fn(async () => ({ updatedAt: 'u' })),
createPage: vi.fn(async () => ({ data: { id: 'new-id' } })),
deletePage: vi.fn(async () => ({})),

3
packages/git-sync/test/run-push-realgit.test.ts
View File

@@ -47,6 +47,9 @@ function makeSettings(vaultPath: string): Settings {
/** A recording client fake; createPage returns an assigned id + updatedAt. */
function makeClientFake() {
return {
// Empty live tree -> the create takes the normal createPage path (the
// retry-adopt lookup matches only on a live (parentPageId, title) node).
listSpaceTree: vi.fn(async () => ({ pages: [], complete: true })),
importPageMarkdown: vi.fn(async () => ({
data: { updatedAt: '2026-06-20T00:00:00.000Z' },
success: true,

3
packages/git-sync/test/run-push.test.ts
View File

@@ -114,6 +114,9 @@ function makeGit(opts?: {
/** A recording client fake; createPage returns a configurable assigned id. */
function makeClientFake(opts?: { createId?: string }) {
return {
// Empty live tree by default -> no retry-adopt match, so creates take the
// normal createPage path (the adopt lookup only fires on a (parent,title) hit).
listSpaceTree: vi.fn(async () => ({ pages: [], complete: true })),
importPageMarkdown: vi.fn(async () => ({ success: true })),
createPage: vi.fn(async (title: string) => ({
data: { id: opts?.createId ?? 'assigned-id', title },

116
packages/git-sync/test/schema-surface-snapshot.test.ts Normal file
View File

@@ -0,0 +1,116 @@
import { describe, it, expect } from "vitest";
import { getSchema } from "@tiptap/core";
import { docmostExtensions } from "../src/lib/docmost-schema.js";
// SCHEMA-DRIFT GUARD (must-review gate).
//
// `src/lib/docmost-schema.ts` is a VENDORED MIRROR of the canonical Docmost
// document schema defined in `@docmost/editor-ext`. git-sync uses it to convert
// pages to/from ProseMirror JSON; any node, mark, or attribute that exists in
// the canonical schema but is missing here is silently dropped on a round-trip
// (data loss). The reverse — a node/mark/attr here that no longer exists in the
// canonical schema — is dead surface that can mask drift.
//
// This test derives a stable, sorted "schema surface" (every node/mark name and
// its sorted attribute keys) and pins it against an INLINE expected constant.
// It is intentionally a LOUD must-review gate rather than an automatic
// editor-ext diff: editor-ext's Tiptap representation differs from this
// vendored copy, so a cross-representation compare would be fragile. We do NOT
// use toMatchSnapshot so the reference lives in this file and is reviewed in the
// diff of every change.
//
// WHEN THIS TEST FAILS: do NOT blindly update `expectedSurface`. First confirm
// the change matches `@docmost/editor-ext` (the canonical schema) so the
// markdown <-> ProseMirror round-trip stays lossless, THEN copy the new surface
// into the expected constant below.
interface SurfaceEntry {
name: string;
kind: "node" | "mark";
attrs: string[];
}
/** Derive the deterministic schema surface from the vendored extension set. */
function deriveSurface(): SurfaceEntry[] {
const schema = getSchema(docmostExtensions as never);
const surface: SurfaceEntry[] = [];
for (const [name, type] of Object.entries(schema.nodes)) {
surface.push({
name,
kind: "node",
attrs: Object.keys((type as { spec?: { attrs?: object } }).spec?.attrs ?? {}).sort(),
});
}
for (const [name, type] of Object.entries(schema.marks)) {
surface.push({
name,
kind: "mark",
attrs: Object.keys((type as { spec?: { attrs?: object } }).spec?.attrs ?? {}).sort(),
});
}
// Sort by name, then by kind, for a representation-independent ordering.
surface.sort((a, b) =>
a.name === b.name ? a.kind.localeCompare(b.kind) : a.name.localeCompare(b.name),
);
return surface;
}
// The committed reference surface. Built from the ACTUAL current schema; review
// every change to this constant against `@docmost/editor-ext`.
const expectedSurface: SurfaceEntry[] = [
{ name: "attachment", kind: "node", attrs: ["attachmentId", "mime", "name", "placeholder", "size", "url"] },
{ name: "audio", kind: "node", attrs: ["attachmentId", "placeholder", "size", "src"] },
{ name: "blockquote", kind: "node", attrs: [] },
{ name: "bold", kind: "mark", attrs: [] },
{ name: "bulletList", kind: "node", attrs: [] },
{ name: "callout", kind: "node", attrs: ["icon", "type"] },
{ name: "code", kind: "mark", attrs: [] },
{ name: "codeBlock", kind: "node", attrs: ["language"] },
{ name: "column", kind: "node", attrs: ["width"] },
{ name: "columns", kind: "node", attrs: ["layout", "widthMode"] },
{ name: "comment", kind: "mark", attrs: ["commentId", "resolved"] },
{ name: "details", kind: "node", attrs: ["open"] },
{ name: "detailsContent", kind: "node", attrs: [] },
{ name: "detailsSummary", kind: "node", attrs: [] },
{ name: "doc", kind: "node", attrs: [] },
{ name: "drawio", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "size", "src", "title", "width"] },
{ name: "embed", kind: "node", attrs: ["align", "height", "provider", "src", "width"] },
{ name: "excalidraw", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "size", "src", "title", "width"] },
{ name: "hardBreak", kind: "node", attrs: [] },
{ name: "heading", kind: "node", attrs: ["id", "indent", "level", "textAlign"] },
{ name: "highlight", kind: "mark", attrs: ["color"] },
{ name: "horizontalRule", kind: "node", attrs: [] },
{ name: "image", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "placeholder", "size", "src", "title", "width"] },
{ name: "italic", kind: "mark", attrs: [] },
{ name: "link", kind: "mark", attrs: ["class", "href", "internal", "rel", "target", "title"] },
{ name: "listItem", kind: "node", attrs: [] },
{ name: "mathBlock", kind: "node", attrs: ["text"] },
{ name: "mathInline", kind: "node", attrs: ["text"] },
{ name: "mention", kind: "node", attrs: ["anchorId", "creatorId", "entityId", "entityType", "id", "label", "slugId"] },
{ name: "orderedList", kind: "node", attrs: ["start", "type"] },
{ name: "pageBreak", kind: "node", attrs: [] },
{ name: "paragraph", kind: "node", attrs: ["id", "indent", "textAlign"] },
{ name: "pdf", kind: "node", attrs: ["attachmentId", "height", "name", "placeholder", "size", "src", "width"] },
{ name: "strike", kind: "mark", attrs: [] },
{ name: "subpages", kind: "node", attrs: [] },
{ name: "subscript", kind: "mark", attrs: [] },
{ name: "superscript", kind: "mark", attrs: [] },
{ name: "table", kind: "node", attrs: [] },
{ name: "tableCell", kind: "node", attrs: ["align", "backgroundColor", "backgroundColorName", "colspan", "colwidth", "rowspan"] },
{ name: "tableHeader", kind: "node", attrs: ["align", "backgroundColor", "backgroundColorName", "colspan", "colwidth", "rowspan"] },
{ name: "tableRow", kind: "node", attrs: [] },
{ name: "taskItem", kind: "node", attrs: ["checked"] },
{ name: "taskList", kind: "node", attrs: [] },
{ name: "text", kind: "node", attrs: [] },
{ name: "textStyle", kind: "mark", attrs: ["color"] },
{ name: "underline", kind: "mark", attrs: [] },
{ name: "video", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "placeholder", "size", "src", "width"] },
{ name: "youtube", kind: "node", attrs: ["align", "height", "src", "width"] },
];
describe("docmost schema surface", () => {
it("matches the committed reference surface (re-verify against @docmost/editor-ext on change)", () => {
expect(deriveSurface()).toEqual(expectedSurface);
});
});

76
packages/git-sync/test/settings.test.ts
View File

@@ -1,76 +0,0 @@
import { describe, expect, it } from 'vitest';
import { parseSettings } from '../src/engine/settings';
// A minimal valid environment with every required variable set. Tests clone and
// mutate this object so process.env is never touched (hermetic).
const baseEnv = {
DOCMOST_API_URL: 'https://docmost.example.com',
DOCMOST_EMAIL: 'you@example.com',
DOCMOST_PASSWORD: 'secret',
DOCMOST_SPACE_ID: 'space-123',
} as NodeJS.ProcessEnv;
describe('parseSettings', () => {
it('maps a full valid env to the camelCase Settings object', () => {
const settings = parseSettings({
...baseEnv,
VAULT_PATH: 'data/custom-vault',
GIT_REMOTE: 'git@github.com:you/vault.git',
POLL_INTERVAL_MS: '5000',
DEBOUNCE_MS: '1000',
LOG_LEVEL: 'debug',
});
expect(settings).toEqual({
docmostApiUrl: 'https://docmost.example.com',
docmostEmail: 'you@example.com',
docmostPassword: 'secret',
docmostSpaceId: 'space-123',
vaultPath: 'data/custom-vault',
gitRemote: 'git@github.com:you/vault.git',
pollIntervalMs: 5000,
debounceMs: 1000,
logLevel: 'debug',
});
});
it('applies defaults when optional vars are omitted', () => {
const settings = parseSettings({ ...baseEnv });
expect(settings.vaultPath).toBe('data/vault');
expect(settings.pollIntervalMs).toBe(15000);
expect(settings.debounceMs).toBe(2000);
expect(settings.logLevel).toBe('info');
expect(settings.gitRemote).toBeUndefined();
});
it('coerces numeric strings to numbers', () => {
const settings = parseSettings({ ...baseEnv, POLL_INTERVAL_MS: '3000' });
expect(settings.pollIntervalMs).toBe(3000);
expect(typeof settings.pollIntervalMs).toBe('number');
});
it('throws when a required var is missing', () => {
const { DOCMOST_API_URL: _omit, ...rest } = baseEnv;
void _omit;
expect(() => parseSettings(rest as NodeJS.ProcessEnv)).toThrow();
});
it('throws on an invalid LOG_LEVEL', () => {
expect(() =>
parseSettings({ ...baseEnv, LOG_LEVEL: 'verbose' }),
).toThrow();
});
it('throws on a non-numeric POLL_INTERVAL_MS', () => {
expect(() =>
parseSettings({ ...baseEnv, POLL_INTERVAL_MS: 'soon' }),
).toThrow();
});
it('treats an empty GIT_REMOTE as undefined', () => {
const settings = parseSettings({ ...baseEnv, GIT_REMOTE: '' });
expect(settings.gitRemote).toBeUndefined();
});
});