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

feat(git-sync): native-Obsidian format — phase 1 = page-file (frontmatter gitmost_id)

Browse Source 
Pivot the thin-meta design to "the vault IS a native Obsidian vault": clean
markdown + a minimal YAML frontmatter `gitmost_id:` (the durable pageId, travels
with the file so identity survives any move); folders mirror the page tree with
the parent's body as a folder-note `<Folder>/<Folder>.md` (LostPaul Folder Notes
convention); links as `[[wikilinks]]` (basename-resolved → reparent never breaks a
link, only retitle does); collisions disambiguated Obsidian-style; `.obsidian/`
and non-page files left untouched (no .gitignore). Verified the conventions
against the Obsidian/Folder-Notes docs.

Replaces the abandoned `.gitmost/index.json` sidecar (path-keyed → fragile to
git-undetected renames; the in-file id is self-sufficient): removes vault-index.ts.
Adds lib/page-file.ts — parsePageFile/serializePageFile (frontmatter id + clean
body) with a LEGACY `docmost:meta` fallback for migration. 6 unit tests; engine
suite green. Not yet wired into pull/push — no behavior change. Design doc
rewritten to the native-Obsidian format.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
claude code agent 227
2026-06-24 04:25:04 +03:00
parent 1ace904221
commit 074ef25db5
7 changed files with 226 additions and 389 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
packages/git-sync/src/engine/vault-index.ts
View File

@@ -1,154 +0,0 @@
/**
* The vault SIDECAR index — `.gitmost/index.json`. It holds the ONLY service
* metadata that is not derivable from the vault itself: a page's stable identity
* (`pageId`) and its collision-disambiguation token (`slugId`), keyed by the
* file's vault-relative (forward-slash) path. Everything else is derived:
* - title -> the file/folder name (stem),
* - parentPageId-> the enclosing folder's `index.md` (path-as-truth),
* - spaceId -> the vault is the space,
* - updatedAt -> git history.
*
* Keeping identity here (not in a `docmost:meta` block inside every file) lets
* the `.md` files stay CLEAN markdown that any third-party editor (Obsidian, …)
* reads and writes directly. This module is PURE (parse/serialize/lookup); all
* file IO is the caller's (injected), matching the rest of the engine.
*/
/** Where the sidecar lives inside a space vault (vault-relative, forward-slash). */
export const VAULT_INDEX_PATH = ".gitmost/index.json";
/** Per-file identity record. `slugId` is optional (a freshly adopted file has
* none until Docmost assigns one on create). */
export interface VaultIndexEntry {
pageId: string;
slugId?: string;
}
export interface VaultIndex {
version: number;
/** The space this vault mirrors (one repo per space). Informational. */
spaceId?: string;
/** file path (forward-slash, vault-relative) -> identity. */
pages: Map<string, VaultIndexEntry>;
}
const CURRENT_VERSION = 1;
export function emptyVaultIndex(spaceId?: string): VaultIndex {
return { version: CURRENT_VERSION, spaceId, pages: new Map() };
}
/**
* Parse `.gitmost/index.json`. TOLERANT by construction — a missing file
* (`null`), invalid JSON, or a malformed entry must never crash a sync cycle, so
* those degrade to an empty index / skipped entries (the engine then treats the
* affected files as un-tracked and re-derives identity, rather than losing data).
*/
export function parseVaultIndex(text: string | null | undefined): VaultIndex {
if (text == null || text.trim() === "") return emptyVaultIndex();
let raw: unknown;
try {
raw = JSON.parse(text);
} catch {
return emptyVaultIndex();
}
if (typeof raw !== "object" || raw === null) return emptyVaultIndex();
const obj = raw as Record<string, unknown>;
const index = emptyVaultIndex(
typeof obj.spaceId === "string" ? obj.spaceId : undefined,
);
if (typeof obj.version === "number") index.version = obj.version;
const pages = obj.pages;
if (typeof pages === "object" && pages !== null) {
for (const [path, value] of Object.entries(pages as Record<string, unknown>)) {
if (typeof value !== "object" || value === null) continue;
const entry = value as Record<string, unknown>;
if (typeof entry.pageId !== "string" || entry.pageId === "") continue;
index.pages.set(path, {
pageId: entry.pageId,
...(typeof entry.slugId === "string" ? { slugId: entry.slugId } : {}),
});
}
}
return index;
}
/**
* Serialize to STABLE JSON: object keys sorted so the file produces minimal,
* deterministic git diffs (a re-sync that changes nothing yields byte-identical
* output — no churn, which the loop-guard relies on). Trailing newline.
*/
export function serializeVaultIndex(index: VaultIndex): string {
const pages: Record<string, VaultIndexEntry> = {};
for (const path of [...index.pages.keys()].sort()) {
const e = index.pages.get(path)!;
pages[path] = e.slugId
? { pageId: e.pageId, slugId: e.slugId }
: { pageId: e.pageId };
}
const out: Record<string, unknown> = { version: index.version };
if (index.spaceId) out.spaceId = index.spaceId;
out.pages = pages;
return JSON.stringify(out, null, 2) + "\n";
}
// --- lookups (pure) --------------------------------------------------------
/** The pageId tracked at `path`, or undefined. */
export function pageIdAt(index: VaultIndex, path: string): string | undefined {
return index.pages.get(path)?.pageId;
}
/** The slugId tracked at `path`, or undefined. */
export function slugIdAt(index: VaultIndex, path: string): string | undefined {
return index.pages.get(path)?.slugId;
}
/**
* Reverse lookup: the CURRENT path of a pageId, or undefined. Used by push to
* decide identity — a vanished file whose pageId still resolves to a (different)
* tracked path is a MOVE, not a delete.
*/
export function pathForPageId(
index: VaultIndex,
pageId: string,
): string | undefined {
for (const [path, entry] of index.pages) {
if (entry.pageId === pageId) return path;
}
return undefined;
}
/** The set of all pageIds currently tracked in the index. */
export function trackedPageIds(index: VaultIndex): Set<string> {
const ids = new Set<string>();
for (const entry of index.pages.values()) ids.add(entry.pageId);
return ids;
}
// --- mutations (in place; the index is a builder during a cycle) -----------
export function setEntry(
index: VaultIndex,
path: string,
entry: VaultIndexEntry,
): void {
index.pages.set(path, entry);
}
export function removeAt(index: VaultIndex, path: string): void {
index.pages.delete(path);
}
/** Move a tracked entry from one path to another (a rename/reparent), keeping
* its identity. No-op if `fromPath` is not tracked. */
export function moveEntry(
index: VaultIndex,
fromPath: string,
toPath: string,
): void {
const entry = index.pages.get(fromPath);
if (!entry) return;
index.pages.delete(fromPath);
index.pages.set(toPath, entry);
}