orbitmap 0.3.0 → 0.4.1

package/dist/adapters/local/store.js

@@ -0,0 +1,665 @@
+/**
+ * Local file store (spec §4).
+ *
+ * All file I/O for local mode lives here: frontmatter+body parsing, atomic writes,
+ * advisory locking, the workspace scaffold, entity-number counters and lookups.
+ * It knows nothing about the Agent API envelopes (that is `shapes.ts`) and nothing
+ * about domain validation (that is `rules.ts`).
+ *
+ * Everything is async and every path is built with `node:path`, so the store behaves
+ * identically on Windows and POSIX.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { OrbitMapAPIError } from '../../errors.js';
+import { AREA_SCOPED_KINDS, ENTITY_PREFIXES, KIND_BY_PREFIX, LOCAL_SCHEMA_VERSION, WORKSPACE_SCOPED_KINDS, } from './types.js';
+// ── Error codes ─────────────────────────────────────────────────────────────
+/** Unexpected/corrupt state on disk (unreadable file, bad frontmatter, failed write). */
+export const LOCAL_STORE_ERROR = 'LOCAL_STORE_ERROR';
+/** The advisory lock could not be acquired within the retry budget. */
+export const LOCK_TIMEOUT = 'LOCK_TIMEOUT';
+/** A referenced entity/area/document does not exist on disk. */
+export const NOT_FOUND = 'NOT_FOUND';
+// ── Layout constants (spec §4.1) ────────────────────────────────────────────
+export const WORKSPACE_FILE_NAME = 'workspace.yml';
+export const AREA_FILE_NAME = 'area.yml';
+export const LOCK_FILE_NAME = '.lock';
+export const AREAS_DIR = 'areas';
+export const DOCUMENTS_DIR = 'documents';
+/** Workspace-level directories created by the scaffold. */
+export const WORKSPACE_DIRS = [
+    'missions',
+    'intents',
+    'ideas',
+    'documents',
+    'issues',
+];
+/** Per-area directories created by the scaffold. */
+export const AREA_DIRS = ['tasks', 'issues', 'vibes'];
+/** Directory name (relative to the workspace root) for a workspace-scoped kind. */
+const WORKSPACE_DIR_BY_KIND = {
+    task: 'tasks',
+    issue: 'issues',
+    idea: 'ideas',
+    vibe: 'vibes',
+    intent: 'intents',
+    mission: 'missions',
+};
+// ── Frontmatter parsing / serialisation ─────────────────────────────────────
+const OPEN_DELIMITER = /^---[ \t]*\r?\n/;
+const CLOSE_DELIMITER = /^---[ \t]*(?:\r?\n|$)/m;
+/**
+ * Split a Markdown file into its YAML frontmatter object and its body.
+ *
+ * The delimiter is `---` on line 1. The *whole* YAML mapping is returned, so unknown
+ * keys survive a read → modify → write round trip.
+ */
+export function parseFrontmatter(raw, source) {
+    const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const opening = OPEN_DELIMITER.exec(text);
+    if (!opening) {
+        throw storeError(`Missing YAML frontmatter (expected \`---\` on the first line)${where(source)}.`);
+    }
+    const rest = text.slice(opening[0].length);
+    const closing = CLOSE_DELIMITER.exec(rest);
+    if (!closing) {
+        throw storeError(`Unterminated YAML frontmatter${where(source)}.`);
+    }
+    const yamlText = rest.slice(0, closing.index);
+    const body = rest.slice(closing.index + closing[0].length);
+    let parsed;
+    try {
+        parsed = yamlText.trim().length > 0 ? parseYaml(yamlText) : {};
+    }
+    catch (err) {
+        throw storeError(`Invalid YAML frontmatter${where(source)}: ${err.message}`);
+    }
+    if (parsed === null || parsed === undefined)
+        parsed = {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw storeError(`YAML frontmatter must be a mapping${where(source)}.`);
+    }
+    return { frontmatter: parsed, body: normaliseBody(body) };
+}
+/** Render a frontmatter object + body back into a Markdown file. */
+export function serialiseFrontmatter(frontmatter, body = '') {
+    let yamlText;
+    try {
+        yamlText = stringifyYaml(frontmatter, { lineWidth: 0 });
+    }
+    catch (err) {
+        throw storeError(`Could not serialise frontmatter: ${err.message}`);
+    }
+    if (!yamlText.endsWith('\n'))
+        yamlText += '\n';
+    const normalised = normaliseBody(body);
+    return normalised.length > 0
+        ? `---\n${yamlText}---\n\n${normalised}\n`
+        : `---\n${yamlText}---\n`;
+}
+/** Strip leading blank lines and trailing whitespace so round trips are stable. */
+function normaliseBody(body) {
+    return body.replace(/^(?:[ \t]*\r?\n)+/, '').replace(/\s+$/, '');
+}
+// ── Entity numbers (spec §4.4) ──────────────────────────────────────────────
+/** `prefix + '-' + counter.toString(36).padStart(6, '0')`, e.g. `TS-000001`. */
+export function formatEntityNumber(kind, counter) {
+    return `${ENTITY_PREFIXES[kind]}-${counter.toString(36).padStart(6, '0')}`;
+}
+/** The entity kind an entity number belongs to, or `undefined` if not a number. */
+export function kindOfEntityNumber(ref) {
+    const match = /^([A-Za-z]{2})-([0-9a-zA-Z]+)$/.exec(ref.trim());
+    if (!match)
+        return undefined;
+    return KIND_BY_PREFIX[match[1].toUpperCase()];
+}
+/** True when `ref` looks like `TS-…`/`IS-…`/… rather than a uuid or slug. */
+export function isEntityNumber(ref) {
+    return kindOfEntityNumber(ref) !== undefined;
+}
+/** In-process serialisation of lock acquisition, keyed by absolute lock path. */
+const inProcessLocks = new Map();
+/** Lock paths held by the current async execution context (makes `withLock` reentrant). */
+const heldLocks = new AsyncLocalStorage();
+export class LocalStore {
+    /** Absolute path of the workspace root directory. */
+    root;
+    lockRetries;
+    lockRetryDelayMs;
+    constructor(workspacePath, options = {}) {
+        this.root = resolve(workspacePath);
+        this.lockRetries = options.lockRetries ?? 10;
+        this.lockRetryDelayMs = options.lockRetryDelayMs ?? 100;
+    }
+    // ── Paths ────────────────────────────────────────────────────────────────
+    get workspaceFile() {
+        return join(this.root, WORKSPACE_FILE_NAME);
+    }
+    get lockFile() {
+        return join(this.root, LOCK_FILE_NAME);
+    }
+    /** `<root>/areas/<slug>`. */
+    areaDir(slug) {
+        return join(this.root, AREAS_DIR, slug);
+    }
+    /** `<root>/areas/<slug>/area.yml`. */
+    areaFile(slug) {
+        return join(this.areaDir(slug), AREA_FILE_NAME);
+    }
+    /**
+     * Directory holding entities of `kind`. Area-scoped kinds require `area`;
+     * issues live in the area dir when `area` is given and in `<root>/issues` otherwise.
+     */
+    entityDir(kind, area) {
+        const dirName = WORKSPACE_DIR_BY_KIND[kind];
+        if (area) {
+            if (kind === 'task' || kind === 'vibe' || kind === 'issue') {
+                return join(this.areaDir(area), dirName);
+            }
+            // Workspace-scoped kinds ignore the area argument.
+            return join(this.root, dirName);
+        }
+        if (AREA_SCOPED_KINDS.includes(kind)) {
+            throw storeError(`${kind} entities are area-scoped — an area slug is required.`);
+        }
+        return join(this.root, dirName);
+    }
+    /** Absolute path of an entity file. */
+    entityPath(kind, entityNumber, area) {
+        return join(this.entityDir(kind, area), `${entityNumber}.md`);
+    }
+    /** `<root>/documents/<slug>.md`. */
+    documentPath(slug) {
+        return join(this.root, DOCUMENTS_DIR, `${slug}.md`);
+    }
+    // ── Scaffold ─────────────────────────────────────────────────────────────
+    /** True when `<root>/workspace.yml` exists. */
+    async isWorkspace() {
+        return pathExists(this.workspaceFile);
+    }
+    /**
+     * Create the full directory layout of §4.1 plus `workspace.yml`, and optionally the
+     * first area. Idempotent: re-scaffolding an existing workspace only fills in gaps and
+     * leaves `workspace.yml` (and its counters) untouched.
+     */
+    async scaffold(options) {
+        await mkdir(this.root, { recursive: true });
+        for (const dir of WORKSPACE_DIRS) {
+            await mkdir(join(this.root, dir), { recursive: true });
+        }
+        await mkdir(join(this.root, AREAS_DIR), { recursive: true });
+        // The first area becomes the workspace's own default (spec §3.3) so that an
+        // in-project workspace outranks the machine-wide `area` of the global config.
+        const defaultArea = options.area
+            ? (options.area.slug ?? slugify(options.area.name))
+            : undefined;
+        let workspace;
+        if (await this.isWorkspace()) {
+            workspace = await this.readWorkspace();
+            // Fill in — never clobber: a workspace scaffolded by an older CLI gains its
+            // `default_area` on the next `init`, one that already declares an area keeps it.
+            if (defaultArea && !workspace.default_area) {
+                workspace.default_area = defaultArea;
+                await this.writeWorkspace(workspace);
+            }
+        }
+        else {
+            workspace = {
+                schema_version: LOCAL_SCHEMA_VERSION,
+                workspace_id: options.workspaceId ?? randomUUID(),
+                name: options.name,
+                slug: options.slug ?? slugify(options.name),
+                description: options.description ?? '',
+                settings: {},
+                created_at: nowIso(),
+                counters: emptyCounters(),
+                ...(defaultArea ? { default_area: defaultArea } : {}),
+            };
+            await this.writeWorkspace(workspace);
+        }
+        if (options.area)
+            await this.scaffoldArea(options.area);
+        return workspace;
+    }
+    /**
+     * Create `areas/<slug>/` with its `tasks/`, `issues/`, `vibes/` subdirectories and
+     * `area.yml`. Returns the existing `area.yml` untouched when the area already exists.
+     */
+    async scaffoldArea(input) {
+        const slug = input.slug ?? slugify(input.name);
+        const dir = this.areaDir(slug);
+        await mkdir(dir, { recursive: true });
+        for (const sub of AREA_DIRS) {
+            await mkdir(join(dir, sub), { recursive: true });
+        }
+        const existing = await this.tryReadArea(slug);
+        if (existing)
+            return existing;
+        const area = {
+            area_id: input.areaId ?? randomUUID(),
+            name: input.name,
+            slug,
+            description: input.description ?? '',
+            git_url: input.gitUrl ?? null,
+            default_branch: input.defaultBranch ?? 'main',
+            agent_instructions_template: input.agentInstructionsTemplate ?? null,
+            settings: {},
+            created_at: nowIso(),
+        };
+        await this.writeArea(area);
+        return area;
+    }
+    // ── workspace.yml / area.yml ─────────────────────────────────────────────
+    async readWorkspace() {
+        const raw = await readTextFile(this.workspaceFile);
+        if (raw === undefined) {
+            throw OrbitMapAPIError.workspaceNotFound(`No \`${WORKSPACE_FILE_NAME}\` found in ${this.root}. Run \`orbitmap init\` to create a workspace.`);
+        }
+        const parsed = parseYamlObject(raw, this.workspaceFile);
+        if (!parsed.counters)
+            parsed.counters = emptyCounters();
+        return parsed;
+    }
+    async writeWorkspace(workspace) {
+        await writeAtomic(this.workspaceFile, toYamlDocument(workspace));
+    }
+    async readArea(slug) {
+        const area = await this.tryReadArea(slug);
+        if (!area) {
+            throw new OrbitMapAPIError(`Area \`${slug}\` was not found in this workspace.`, NOT_FOUND, 404);
+        }
+        return area;
+    }
+    async tryReadArea(slug) {
+        const raw = await readTextFile(this.areaFile(slug));
+        if (raw === undefined)
+            return undefined;
+        return parseYamlObject(raw, this.areaFile(slug));
+    }
+    async writeArea(area) {
+        await writeAtomic(this.areaFile(area.slug), toYamlDocument(area));
+    }
+    /** Every area in the workspace, ordered by slug. */
+    async listAreas() {
+        const slugs = await listDirNames(join(this.root, AREAS_DIR));
+        const areas = [];
+        for (const slug of slugs.sort()) {
+            const area = await this.tryReadArea(slug);
+            if (area)
+                areas.push(area);
+        }
+        return areas;
+    }
+    /** Look an area up by slug; `undefined` when it does not exist. */
+    async findAreaBySlug(slug) {
+        return this.tryReadArea(slug);
+    }
+    // ── Locking (spec §4.12) ─────────────────────────────────────────────────
+    /**
+     * Run `fn` while holding the workspace's advisory `.lock` file.
+     *
+     * Guards multi-file operations (counter bump + entity write) against concurrent CLI
+     * invocations. Reentrant within one async context, serialised within one process, and
+     * retried `lockRetries` × `lockRetryDelayMs` against other processes before failing.
+     * The lock is always released in a `finally`.
+     */
+    async withLock(fn) {
+        const key = this.lockFile;
+        const held = heldLocks.getStore();
+        if (held?.has(key))
+            return fn();
+        const previous = inProcessLocks.get(key) ?? Promise.resolve();
+        let release;
+        const mine = new Promise((res) => {
+            release = res;
+        });
+        const chained = previous.then(() => mine);
+        inProcessLocks.set(key, chained);
+        await previous.catch(() => undefined);
+        try {
+            await this.acquireLockFile();
+            const nested = new Set(held ?? []);
+            nested.add(key);
+            try {
+                return await heldLocks.run(nested, fn);
+            }
+            finally {
+                await this.releaseLockFile();
+            }
+        }
+        finally {
+            release();
+            if (inProcessLocks.get(key) === chained)
+                inProcessLocks.delete(key);
+        }
+    }
+    async acquireLockFile() {
+        await mkdir(this.root, { recursive: true });
+        for (let attempt = 0; attempt <= this.lockRetries; attempt += 1) {
+            try {
+                const handle = await open(this.lockFile, 'wx');
+                try {
+                    await handle.writeFile(`${process.pid}\n${nowIso()}\n`, 'utf8');
+                }
+                finally {
+                    await handle.close();
+                }
+                return;
+            }
+            catch (err) {
+                if (!isErrnoCode(err, 'EEXIST')) {
+                    throw storeError(`Could not create the workspace lock at ${this.lockFile}: ${err.message}`);
+                }
+                if (attempt < this.lockRetries)
+                    await delay(this.lockRetryDelayMs);
+            }
+        }
+        throw new OrbitMapAPIError(`The OrbitMap workspace is locked by another process (${this.lockFile}). ` +
+            `Waited ${this.lockRetries * this.lockRetryDelayMs}ms. ` +
+            'If no other `orbitmap` command is running, delete that file and retry.', LOCK_TIMEOUT, 409);
+    }
+    async releaseLockFile() {
+        await rm(this.lockFile, { force: true });
+    }
+    // ── Counters (spec §4.4) ─────────────────────────────────────────────────
+    /**
+     * Bump the counter for `kind` in `workspace.yml` and return the new entity number.
+     * Runs under the advisory lock, so concurrent creates never collide.
+     */
+    async nextEntityNumber(kind) {
+        return this.withLock(async () => {
+            const workspace = await this.readWorkspace();
+            const counters = workspace.counters ?? emptyCounters();
+            const next = (Number(counters[kind]) || 0) + 1;
+            counters[kind] = next;
+            workspace.counters = counters;
+            await this.writeWorkspace(workspace);
+            return formatEntityNumber(kind, next);
+        });
+    }
+    // ── Entity read / write ──────────────────────────────────────────────────
+    /**
+     * Allocate the next entity number and write the file in a single locked operation.
+     * `build` receives the freshly allocated number and returns the record to persist.
+     */
+    async createEntity(kind, build, options = {}) {
+        return this.withLock(async () => {
+            const entityNumber = await this.nextEntityNumber(kind);
+            const { frontmatter, body } = build(entityNumber);
+            const path = this.entityPath(kind, entityNumber, options.area);
+            await writeAtomic(path, serialiseFrontmatter(frontmatter, body ?? ''));
+            return {
+                kind,
+                area: options.area ?? null,
+                path,
+                frontmatter,
+                body: normaliseBody(body ?? ''),
+            };
+        });
+    }
+    /** Read an entity file by kind + number. Throws `NOT_FOUND` when missing. */
+    async readEntity(kind, entityNumber, options = {}) {
+        const found = await this.tryReadEntity(kind, entityNumber, options);
+        if (!found) {
+            throw new OrbitMapAPIError(`${entityNumber} was not found in this workspace.`, NOT_FOUND, 404);
+        }
+        return found;
+    }
+    /** Read an entity file by kind + number, or `undefined` when it does not exist. */
+    async tryReadEntity(kind, entityNumber, options = {}) {
+        if (options.area !== undefined && options.area !== null) {
+            return this.readEntityAt(this.entityPath(kind, entityNumber, options.area), kind, options.area);
+        }
+        for (const candidate of await this.candidatePaths(kind, entityNumber)) {
+            const file = await this.readEntityAt(candidate.path, kind, candidate.area);
+            if (file)
+                return file;
+        }
+        return undefined;
+    }
+    /** Persist an entity file that was previously read (or built) by the store. */
+    async writeEntity(file) {
+        await writeAtomic(file.path, serialiseFrontmatter(file.frontmatter, file.body));
+    }
+    /** Write a raw frontmatter+body pair to an explicit path (atomic). */
+    async writeFileRecord(path, frontmatter, body = '') {
+        await writeAtomic(path, serialiseFrontmatter(frontmatter, body));
+    }
+    // ── Lookups ──────────────────────────────────────────────────────────────
+    /**
+     * Locate any entity by its entity number (`TS-000001`) or by its uuid.
+     *
+     * Entity numbers resolve directly from the prefix + directory layout; uuids require a
+     * scan of the workspace (small by construction). Returns `undefined` when not found.
+     */
+    async findEntity(ref) {
+        const trimmed = ref.trim();
+        const kind = kindOfEntityNumber(trimmed);
+        if (kind) {
+            const upper = `${trimmed.slice(0, 2).toUpperCase()}${trimmed.slice(2)}`;
+            return this.tryReadEntity(kind, upper);
+        }
+        for (const candidate of Object.keys(ENTITY_PREFIXES)) {
+            const matches = await this.listEntities(candidate);
+            const hit = matches.find((file) => file.frontmatter.id === trimmed);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    }
+    /** Like {@link findEntity} but throws `NOT_FOUND` instead of returning `undefined`. */
+    async requireEntity(ref) {
+        const found = await this.findEntity(ref);
+        if (!found) {
+            throw new OrbitMapAPIError(`\`${ref}\` was not found in this workspace.`, NOT_FOUND, 404);
+        }
+        return found;
+    }
+    /**
+     * All entities of one kind.
+     *
+     * - Area-scoped kinds (`task`, `vibe`): `area` restricts to that area; omitting it
+     *   walks every area.
+     * - `issue`: `area` restricts to that area; omitting it returns workspace-level issues
+     *   *and* every area's issues.
+     * - Workspace-scoped kinds: `area` is ignored.
+     *
+     * Results are sorted by entity number for stable output.
+     */
+    async listEntities(kind, options = {}) {
+        const scopes = await this.scopesFor(kind, options.area);
+        const files = [];
+        for (const scope of scopes) {
+            const dir = this.entityDir(kind, scope);
+            for (const name of await listMarkdownFiles(dir)) {
+                const file = await this.readEntityAt(join(dir, name), kind, scope);
+                if (file)
+                    files.push(file);
+            }
+        }
+        files.sort((a, b) => basename(a.path).localeCompare(basename(b.path)));
+        return files;
+    }
+    // ── Documents ────────────────────────────────────────────────────────────
+    /** Read `documents/<slug>.md`, or `undefined` when it does not exist. */
+    async findDocumentBySlug(slug) {
+        const path = this.documentPath(slug);
+        const raw = await readTextFile(path);
+        if (raw === undefined)
+            return undefined;
+        const { frontmatter, body } = parseFrontmatter(raw, path);
+        return { path, frontmatter, body };
+    }
+    /** Like {@link findDocumentBySlug} but throws `NOT_FOUND` when missing. */
+    async readDocument(slug) {
+        const doc = await this.findDocumentBySlug(slug);
+        if (!doc) {
+            throw new OrbitMapAPIError(`Document \`${slug}\` was not found in this workspace.`, NOT_FOUND, 404);
+        }
+        return doc;
+    }
+    /** Every document in `documents/`, ordered by slug. */
+    async listDocuments() {
+        const dir = join(this.root, DOCUMENTS_DIR);
+        const docs = [];
+        for (const name of await listMarkdownFiles(dir)) {
+            const path = join(dir, name);
+            const raw = await readTextFile(path);
+            if (raw === undefined)
+                continue;
+            const { frontmatter, body } = parseFrontmatter(raw, path);
+            docs.push({ path, frontmatter, body });
+        }
+        docs.sort((a, b) => basename(a.path).localeCompare(basename(b.path)));
+        return docs;
+    }
+    /** Write `documents/<slug>.md` atomically. */
+    async writeDocument(frontmatter, body) {
+        const path = this.documentPath(frontmatter.slug);
+        await mkdir(dirname(path), { recursive: true });
+        await writeAtomic(path, serialiseFrontmatter(frontmatter, body));
+        return { path, frontmatter, body: normaliseBody(body) };
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    /** Area slugs (or `null` for workspace scope) to search for `kind`. */
+    async scopesFor(kind, area) {
+        if (WORKSPACE_SCOPED_KINDS.includes(kind))
+            return [null];
+        if (area)
+            return [area];
+        const areaSlugs = (await listDirNames(join(this.root, AREAS_DIR))).sort();
+        return kind === 'issue' ? [null, ...areaSlugs] : areaSlugs;
+    }
+    /** Every path an entity number could occupy, in search order. */
+    async candidatePaths(kind, entityNumber) {
+        const scopes = await this.scopesFor(kind, null);
+        return scopes.map((area) => ({
+            path: this.entityPath(kind, entityNumber, area),
+            area,
+        }));
+    }
+    async readEntityAt(path, kind, area) {
+        const raw = await readTextFile(path);
+        if (raw === undefined)
+            return undefined;
+        const { frontmatter, body } = parseFrontmatter(raw, path);
+        return { kind, area, path, frontmatter, body };
+    }
+}
+// ── Free functions ──────────────────────────────────────────────────────────
+/**
+ * Atomic write: serialise to `<file>.tmp` in the same directory, then rename over the
+ * target. The temp file is removed on any failure, so no `.tmp` litter is left behind.
+ */
+export async function writeAtomic(path, content) {
+    const target = resolve(path);
+    await mkdir(dirname(target), { recursive: true });
+    const tmp = `${target}.tmp`;
+    try {
+        await writeFile(tmp, content, 'utf8');
+        await rename(tmp, target);
+    }
+    catch (err) {
+        await rm(tmp, { force: true }).catch(() => undefined);
+        throw storeError(`Could not write ${target}: ${err.message}`);
+    }
+}
+/** Fresh counters, all at zero. */
+export function emptyCounters() {
+    return { task: 0, issue: 0, idea: 0, vibe: 0, intent: 0, mission: 0 };
+}
+/** ISO-8601 UTC, second precision — the timestamp format used across the format. */
+export function nowIso() {
+    return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+/** Lowercase, dash-separated slug — used for workspace/area defaults. */
+export function slugify(value) {
+    return (value
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'workspace');
+}
+// ── Small helpers ───────────────────────────────────────────────────────────
+function storeError(message) {
+    return new OrbitMapAPIError(message, LOCAL_STORE_ERROR, 500);
+}
+function where(source) {
+    return source ? ` in ${source}` : '';
+}
+function parseYamlObject(raw, source) {
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (err) {
+        throw storeError(`Invalid YAML in ${source}: ${err.message}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw storeError(`Expected a YAML mapping in ${source}.`);
+    }
+    return parsed;
+}
+function toYamlDocument(value) {
+    let text = stringifyYaml(value, { lineWidth: 0 });
+    if (!text.endsWith('\n'))
+        text += '\n';
+    return text;
+}
+async function readTextFile(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (isErrnoCode(err, 'ENOENT') || isErrnoCode(err, 'EISDIR'))
+            return undefined;
+        throw storeError(`Could not read ${path}: ${err.message}`);
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listMarkdownFiles(dir) {
+    const entries = await safeReaddir(dir);
+    return entries
+        .filter((entry) => entry.isFile() && extname(entry.name).toLowerCase() === '.md')
+        .map((entry) => entry.name);
+}
+async function listDirNames(dir) {
+    const entries = await safeReaddir(dir);
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+async function safeReaddir(dir) {
+    try {
+        return await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isErrnoCode(err, 'ENOENT') || isErrnoCode(err, 'ENOTDIR'))
+            return [];
+        throw storeError(`Could not list ${dir}: ${err.message}`);
+    }
+}
+function isErrnoCode(err, code) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        err.code === code);
+}
+function delay(ms) {
+    return new Promise((res) => {
+        setTimeout(res, ms);
+    });
+}
+//# sourceMappingURL=store.js.map