maestro-flow 0.1.4 → 0.2.0

package/dashboard/dist-server/dashboard/src/server/wiki/wiki-types.d.ts

@@ -0,0 +1,52 @@
+export type WikiNodeType = 'project' | 'roadmap' | 'spec' | 'phase' | 'issue' | 'lesson' | 'memory' | 'note';
+export type WikiStatus = 'draft' | 'active' | 'completed' | 'blocked' | 'archived';
+export interface WikiSource {
+    kind: 'file' | 'virtual';
+    /** Forward-slash relative path from .workflow/ root. */
+    path: string;
+    /** 1-based line number for virtual JSONL rows. */
+    line?: number;
+}
+export interface WikiEntry {
+    /** Inferred: `<type>-<slug>`. Stable across rebuilds. */
+    id: string;
+    type: WikiNodeType;
+    title: string;
+    summary: string;
+    tags: string[];
+    status: WikiStatus;
+    /** ISO string from fs.stat.birthtimeMs (or JSONL created_at). */
+    created: string;
+    /** ISO string from fs.stat.mtimeMs (or JSONL updated_at). */
+    updated: string;
+    /** Parsed from `phases/(\d+)-` directory pattern. */
+    phaseRef: number | null;
+    /** Normalized wikilink ids declared via frontmatter `related`. */
+    related: string[];
+    source: WikiSource;
+    /** Markdown body (empty string for virtual entries). */
+    body: string;
+    /** Original JSONL row preserved for virtual entries. */
+    raw?: unknown;
+    /**
+     * Preserves non-standard frontmatter fields so existing specs keep their
+     * `category`, `readMode`, `priority`, `keywords` etc. intact.
+     */
+    ext: Record<string, unknown>;
+}
+export interface WikiIndex {
+    entries: WikiEntry[];
+    byId: Record<string, WikiEntry>;
+    byType: Record<WikiNodeType, WikiEntry[]>;
+    /** Map of target entry id -> source entry ids that link to it. */
+    backlinks: Record<string, string[]>;
+    generatedAt: number;
+}
+export interface WikiFilters {
+    type?: WikiNodeType;
+    tag?: string;
+    phase?: number;
+    status?: WikiStatus;
+    /** BM25 query string — tokenized against title + summary + tags + body. */
+    q?: string;
+}

package/dashboard/dist-server/dashboard/src/server/wiki/wiki-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=wiki-types.js.map

package/dashboard/dist-server/dashboard/src/server/wiki/wiki-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-types.js","sourceRoot":"","sources":["../../../../../src/server/wiki/wiki-types.ts"],"names":[],"mappings":""}

package/dashboard/dist-server/dashboard/src/server/wiki/writer-stress.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dashboard/dist-server/dashboard/src/server/wiki/writer-stress.test.js

@@ -0,0 +1,242 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, readFile, rm, symlink, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { WikiIndexer } from './wiki-indexer.js';
+import { WikiWriter, WikiWriteError } from './writer.js';
+// ---------------------------------------------------------------------------
+// Stress tests for WikiWriter: concurrency, security (traversal, symlinks,
+// virtual entries), and edge cases the base unit test doesn't cover.
+// ---------------------------------------------------------------------------
+let tmpRoot;
+async function seed(rel, body) {
+    const abs = join(tmpRoot, rel);
+    await mkdir(join(abs, '..'), { recursive: true });
+    await writeFile(abs, body, 'utf-8');
+}
+beforeEach(async () => {
+    tmpRoot = await mkdtemp(join(tmpdir(), 'wiki-writer-stress-'));
+});
+afterEach(async () => {
+    await rm(tmpRoot, { recursive: true, force: true });
+});
+describe('WikiWriter security — path traversal', () => {
+    it('rejects absolute path slug', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({ type: 'spec', slug: '/etc/passwd', title: 'x', body: 'x' })).rejects.toThrow(WikiWriteError);
+    });
+    it('rejects dot-traversal slug', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({ type: 'spec', slug: '..', title: 'x', body: 'x' })).rejects.toThrow(WikiWriteError);
+    });
+    it('rejects windows-style traversal slug', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({
+            type: 'spec',
+            slug: '..\\..\\windows\\system32',
+            title: 'x',
+            body: 'x',
+        })).rejects.toThrow(WikiWriteError);
+    });
+    it('rejects uppercase slug', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({ type: 'spec', slug: 'UPPERCASE', title: 'x', body: 'x' })).rejects.toThrow(WikiWriteError);
+    });
+    it('rejects slug with spaces', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({ type: 'spec', slug: 'has space', title: 'x', body: 'x' })).rejects.toThrow(WikiWriteError);
+    });
+    it('rejects empty title', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({ type: 'spec', slug: 'ok', title: '   ', body: 'x' })).rejects.toThrow(WikiWriteError);
+    });
+    it('phase requires phaseRef', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({ type: 'phase', slug: 'ok', title: 'T', body: 'x' })).rejects.toThrow(WikiWriteError);
+    });
+    it('phase writes to phases/NN-slug/slug.md', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        const entry = await writer.create({
+            type: 'phase',
+            slug: 'setup',
+            phaseRef: 3,
+            title: 'Setup Phase',
+            body: '# Setup',
+        });
+        expect(entry.source.path).toBe('phases/03-setup/setup.md');
+    });
+    it('memory writes to memory/MEM-slug.md', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        const entry = await writer.create({
+            type: 'memory',
+            slug: 'auth-lessons',
+            title: 'Auth Lessons',
+            body: 'learned',
+        });
+        expect(entry.source.path).toBe('memory/MEM-auth-lessons.md');
+    });
+    it('note writes to memory/TIP-slug.md', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        const entry = await writer.create({
+            type: 'note',
+            slug: 'quick-tip',
+            title: 'Tip',
+            body: 'tip',
+        });
+        expect(entry.source.path).toBe('memory/TIP-quick-tip.md');
+    });
+});
+describe('WikiWriter security — symlink rejection', () => {
+    it('refuses to update a symlinked entry', async () => {
+        // Create a real file outside root, then symlink to it from specs/
+        const outside = join(tmpRoot, '..', `outside-${Date.now()}.md`);
+        await writeFile(outside, '---\ntitle: Outside\n---\n# outside', 'utf-8');
+        await mkdir(join(tmpRoot, 'specs'), { recursive: true });
+        const linkPath = join(tmpRoot, 'specs', 'linked.md');
+        try {
+            await symlink(outside, linkPath);
+        }
+        catch {
+            // Platforms/accounts without symlink permission skip this test
+            return;
+        }
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.update('spec-linked', { body: 'hijacked' })).rejects.toThrow(WikiWriteError);
+        // Ensure the outside file was NOT mutated
+        const raw = await readFile(outside, 'utf-8');
+        expect(raw).toContain('# outside');
+        await rm(outside, { force: true });
+        await rm(linkPath, { force: true });
+    });
+});
+describe('WikiWriter virtual entries — read-only', () => {
+    it('rejects update on virtual issue', async () => {
+        await mkdir(join(tmpRoot, 'issues'), { recursive: true });
+        await writeFile(join(tmpRoot, 'issues', 'current.jsonl'), JSON.stringify({ id: 'I1', title: 'Issue 1', status: 'open' }) + '\n', 'utf-8');
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const index = await indexer.get();
+        const issue = index.entries.find((e) => e.type === 'issue');
+        expect(issue).toBeDefined();
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.update(issue.id, { body: 'x' })).rejects.toMatchObject({ code: 'FORBIDDEN' });
+    });
+    it('rejects remove on virtual lesson', async () => {
+        await mkdir(join(tmpRoot, 'learning'), { recursive: true });
+        await writeFile(join(tmpRoot, 'learning', 'lessons.jsonl'), JSON.stringify({ id: 'L1', title: 'Lesson 1', category: 'pattern' }) + '\n', 'utf-8');
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const index = await indexer.get();
+        const lesson = index.entries.find((e) => e.type === 'lesson');
+        if (!lesson)
+            return; // learning adapter may filter
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.remove(lesson.id)).rejects.toMatchObject({ code: 'FORBIDDEN' });
+    });
+});
+describe('WikiWriter concurrency', () => {
+    it('concurrent PUTs — one wins, others see CONFLICT with stale hash', async () => {
+        await seed('specs/s.md', `---\ntitle: Initial\n---\n# s\nv0`);
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        // Capture the initial hash
+        const raw = await readFile(join(tmpRoot, 'specs', 's.md'));
+        const initialHash = createHash('sha256').update(raw).digest('hex');
+        // Fire 5 concurrent PUTs all providing the SAME stale hash. Each update
+        // serializes through readFile → writeFile, but after the first success the
+        // hash on disk changes, so the remaining 4 must see CONFLICT.
+        const results = await Promise.allSettled(Array.from({ length: 5 }, (_, i) => writer.update('spec-s', {
+            body: `v${i + 1}`,
+            expectedHash: initialHash,
+        })));
+        const ok = results.filter((r) => r.status === 'fulfilled');
+        const conflicts = results.filter((r) => r.status === 'rejected' && r.reason.code === 'CONFLICT');
+        // Exactly one write must have observed the original hash and succeeded.
+        expect(ok.length).toBe(1);
+        expect(conflicts.length).toBe(4);
+    });
+    it('rapid create → update → delete round-trip keeps index consistent', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        const created = await writer.create({
+            type: 'spec',
+            slug: 'rt',
+            title: 'Initial',
+            body: '# body',
+        });
+        expect(created.id).toBe('spec-rt');
+        const updated = await writer.update('spec-rt', {
+            title: 'Updated',
+            body: '# updated',
+        });
+        expect(updated.title).toBe('Updated');
+        await writer.remove('spec-rt');
+        const index = await indexer.get();
+        expect(index.byId['spec-rt']).toBeUndefined();
+        // File should be gone from disk too
+        await expect(stat(join(tmpRoot, 'specs', 'rt.md'))).rejects.toThrow();
+    });
+    it('create with frontmatter serializes arrays and strings correctly', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        const entry = await writer.create({
+            type: 'spec',
+            slug: 'fm',
+            title: 'Frontmatter Test',
+            body: '# fm\nbody',
+            frontmatter: {
+                tags: ['alpha', 'beta'],
+                priority: 'high',
+            },
+        });
+        expect(entry.tags).toEqual(['alpha', 'beta']);
+        expect(entry.ext.priority).toBe('high');
+    });
+    it('update without body preserves existing body', async () => {
+        await seed('specs/s.md', `---\ntitle: Old\n---\n# Old\noriginal body`);
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        const updated = await writer.update('spec-s', { title: 'New Title' });
+        expect(updated.title).toBe('New Title');
+        expect(updated.body).toContain('original body');
+    });
+});
+describe('WikiWriter — invalid id validation', () => {
+    it('rejects update with slash in id', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.update('spec/evil', { body: 'x' })).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+    });
+    it('rejects remove with backslash in id', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.remove('spec\\evil')).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+    });
+    it('remove of non-existent id returns NOT_FOUND', async () => {
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.remove('spec-nope')).rejects.toMatchObject({ code: 'NOT_FOUND' });
+    });
+    it('create fails when target file already exists', async () => {
+        await seed('specs/dup.md', `---\ntitle: Existing\n---\n# dup`);
+        const indexer = new WikiIndexer({ workflowRoot: tmpRoot });
+        const writer = new WikiWriter(tmpRoot, indexer);
+        await expect(writer.create({
+            type: 'spec',
+            slug: 'dup',
+            title: 'New',
+            body: 'x',
+        })).rejects.toMatchObject({ code: 'CONFLICT' });
+    });
+});
+//# sourceMappingURL=writer-stress.test.js.map

package/dashboard/dist-server/dashboard/src/server/wiki/writer-stress.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-stress.test.js","sourceRoot":"","sources":["../../../../../src/server/wiki/writer-stress.test.ts"],"names":[],"mappings":"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"}

package/dashboard/dist-server/dashboard/src/server/wiki/writer.d.ts

@@ -0,0 +1,60 @@
+import type { WikiEntry } from './wiki-types.js';
+import type { WikiIndexer } from './wiki-indexer.js';
+export type WritableType = 'spec' | 'phase' | 'memory' | 'note';
+export interface CreateWikiReq {
+    type: WritableType;
+    slug: string;
+    phaseRef?: number;
+    title: string;
+    body: string;
+    frontmatter?: Record<string, unknown>;
+}
+export interface UpdateWikiReq {
+    title?: string;
+    body?: string;
+    frontmatter?: Record<string, unknown>;
+    /** sha256 of the previous file bytes for optimistic concurrency. */
+    expectedHash?: string;
+}
+export declare class WikiWriteError extends Error {
+    code: 'BAD_REQUEST' | 'NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN';
+    details?: unknown | undefined;
+    constructor(code: 'BAD_REQUEST' | 'NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN', message: string, details?: unknown | undefined);
+}
+/**
+ * WikiWriter — safe CRUD for real markdown wiki entries.
+ *
+ * Scope: only `spec | phase | memory | note` entries backed by real `.md`
+ * files. Virtual entries (issue/lesson), and the top-level `project.md` /
+ * `roadmap.md` narratives are rejected.
+ *
+ * All writes invalidate the indexer cache on success so the next read
+ * rebuilds. fs-watcher will fire its own `wiki:invalidated` event for the
+ * same change; the single-flight guard on `WikiIndexer.rebuild()` prevents
+ * duplicate work.
+ */
+export declare class WikiWriter {
+    private readonly workflowRoot;
+    private readonly indexer;
+    /** Per-path serializer: chains async writes so TOCTOU hash checks are safe. */
+    private readonly pathLocks;
+    constructor(workflowRoot: string, indexer: WikiIndexer);
+    /**
+     * Serialize async operations touching the same `key`. Each caller's fn runs
+     * after the previous one's promise settles, so read-modify-write sequences
+     * don't interleave for a single path.
+     */
+    private withLock;
+    create(req: CreateWikiReq): Promise<WikiEntry>;
+    update(id: string, req: UpdateWikiReq): Promise<WikiEntry>;
+    remove(id: string): Promise<void>;
+    private assertWritableType;
+    private resolveTargetPath;
+    private isInsideRoot;
+    private isWritablePath;
+}
+export declare function serializeFrontmatter(fm: Record<string, unknown>): string;
+export declare function splitFrontmatterAndBody(raw: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};

package/dashboard/dist-server/dashboard/src/server/wiki/writer.js

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, unlink, mkdir, lstat, stat } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { parseFrontmatter } from './frontmatter-util.js';
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const ID_RE = /^[\w.-]+$/;
+export class WikiWriteError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'WikiWriteError';
+    }
+}
+/**
+ * WikiWriter — safe CRUD for real markdown wiki entries.
+ *
+ * Scope: only `spec | phase | memory | note` entries backed by real `.md`
+ * files. Virtual entries (issue/lesson), and the top-level `project.md` /
+ * `roadmap.md` narratives are rejected.
+ *
+ * All writes invalidate the indexer cache on success so the next read
+ * rebuilds. fs-watcher will fire its own `wiki:invalidated` event for the
+ * same change; the single-flight guard on `WikiIndexer.rebuild()` prevents
+ * duplicate work.
+ */
+export class WikiWriter {
+    workflowRoot;
+    indexer;
+    /** Per-path serializer: chains async writes so TOCTOU hash checks are safe. */
+    pathLocks = new Map();
+    constructor(workflowRoot, indexer) {
+        this.workflowRoot = workflowRoot;
+        this.indexer = indexer;
+        this.workflowRoot = resolve(workflowRoot);
+    }
+    /**
+     * Serialize async operations touching the same `key`. Each caller's fn runs
+     * after the previous one's promise settles, so read-modify-write sequences
+     * don't interleave for a single path.
+     */
+    async withLock(key, fn) {
+        const prev = this.pathLocks.get(key) ?? Promise.resolve();
+        const settled = prev.then(() => undefined, () => undefined);
+        const next = settled.then(fn);
+        // Store the error-swallowed tail so later waiters don't inherit rejection.
+        const tail = next.then(() => undefined, () => undefined);
+        this.pathLocks.set(key, tail);
+        try {
+            return await next;
+        }
+        finally {
+            if (this.pathLocks.get(key) === tail) {
+                this.pathLocks.delete(key);
+            }
+        }
+    }
+    async create(req) {
+        this.assertWritableType(req.type);
+        if (!req.slug || !SLUG_RE.test(req.slug)) {
+            throw new WikiWriteError('BAD_REQUEST', `invalid slug '${req.slug}' (expected kebab-case)`);
+        }
+        if (!req.title || !req.title.trim()) {
+            throw new WikiWriteError('BAD_REQUEST', 'title is required');
+        }
+        if (req.type === 'phase' && (req.phaseRef === undefined || !Number.isFinite(req.phaseRef))) {
+            throw new WikiWriteError('BAD_REQUEST', 'phaseRef is required for type=phase');
+        }
+        const targetPath = this.resolveTargetPath(req.type, req.slug, req.phaseRef);
+        if (await pathExists(targetPath)) {
+            throw new WikiWriteError('CONFLICT', `file already exists: ${targetPath}`);
+        }
+        const fm = { title: req.title, ...(req.frontmatter ?? {}) };
+        const serialized = serializeFrontmatter(fm);
+        const content = `${serialized}\n${req.body}`;
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, content, 'utf-8');
+        this.indexer.invalidate(targetPath);
+        const index = await this.indexer.rebuild();
+        const id = `${req.type}-${req.slug}`;
+        const entry = index.byId[id];
+        if (!entry) {
+            throw new WikiWriteError('NOT_FOUND', `created entry not indexed: ${id}`);
+        }
+        return entry;
+    }
+    async update(id, req) {
+        if (!ID_RE.test(id)) {
+            throw new WikiWriteError('BAD_REQUEST', `invalid id '${id}'`);
+        }
+        const index = await this.indexer.get();
+        const current = index.byId[id];
+        if (!current) {
+            throw new WikiWriteError('NOT_FOUND', `entry not found: ${id}`);
+        }
+        if (current.source.kind !== 'file') {
+            throw new WikiWriteError('FORBIDDEN', `cannot write virtual entry: ${id}`);
+        }
+        const absPath = resolve(join(this.workflowRoot, current.source.path));
+        if (!this.isInsideRoot(absPath) || !this.isWritablePath(absPath)) {
+            throw new WikiWriteError('FORBIDDEN', `entry path not writable: ${current.source.path}`);
+        }
+        return this.withLock(absPath, async () => {
+            const ls = await safeLstat(absPath);
+            if (!ls || ls.isSymbolicLink() || !ls.isFile()) {
+                throw new WikiWriteError('NOT_FOUND', `file missing or not a regular file: ${absPath}`);
+            }
+            const prevBytes = await readFile(absPath);
+            const prevHash = sha256(prevBytes);
+            if (req.expectedHash && req.expectedHash !== prevHash) {
+                throw new WikiWriteError('CONFLICT', 'hash mismatch', {
+                    currentHash: prevHash,
+                    currentBody: prevBytes.toString('utf-8'),
+                });
+            }
+            const { frontmatter: currentFm, body: currentBody } = splitFrontmatterAndBody(prevBytes.toString('utf-8'));
+            const nextFm = {
+                ...currentFm,
+                ...(req.frontmatter ?? {}),
+            };
+            if (req.title !== undefined)
+                nextFm.title = req.title;
+            const nextBody = req.body !== undefined ? req.body : currentBody;
+            const content = `${serializeFrontmatter(nextFm)}\n${nextBody}`;
+            await writeFile(absPath, content, 'utf-8');
+            this.indexer.invalidate(absPath);
+            const rebuilt = await this.indexer.rebuild();
+            const entry = rebuilt.byId[id];
+            if (!entry) {
+                throw new WikiWriteError('NOT_FOUND', `updated entry vanished from index: ${id}`);
+            }
+            return entry;
+        });
+    }
+    async remove(id) {
+        if (!ID_RE.test(id)) {
+            throw new WikiWriteError('BAD_REQUEST', `invalid id '${id}'`);
+        }
+        const index = await this.indexer.get();
+        const current = index.byId[id];
+        if (!current) {
+            throw new WikiWriteError('NOT_FOUND', `entry not found: ${id}`);
+        }
+        if (current.source.kind !== 'file') {
+            throw new WikiWriteError('FORBIDDEN', `cannot delete virtual entry: ${id}`);
+        }
+        const absPath = resolve(join(this.workflowRoot, current.source.path));
+        if (!this.isInsideRoot(absPath) || !this.isWritablePath(absPath)) {
+            throw new WikiWriteError('FORBIDDEN', `entry path not writable: ${current.source.path}`);
+        }
+        const ls = await safeLstat(absPath);
+        if (!ls || ls.isSymbolicLink() || !ls.isFile()) {
+            throw new WikiWriteError('NOT_FOUND', `file missing or not a regular file: ${absPath}`);
+        }
+        await unlink(absPath);
+        this.indexer.invalidate(absPath);
+        await this.indexer.rebuild();
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    assertWritableType(type) {
+        if (type !== 'spec' && type !== 'phase' && type !== 'memory' && type !== 'note') {
+            throw new WikiWriteError('BAD_REQUEST', `type '${type}' is not writable`);
+        }
+    }
+    resolveTargetPath(type, slug, phaseRef) {
+        let rel;
+        if (type === 'spec') {
+            rel = `specs/${slug}.md`;
+        }
+        else if (type === 'phase') {
+            const n = String(phaseRef).padStart(2, '0');
+            rel = `phases/${n}-${slug}/${slug}.md`;
+        }
+        else {
+            // memory | note → memory/<PREFIX>-<slug>.md
+            const prefix = type === 'note' ? 'TIP' : 'MEM';
+            rel = `memory/${prefix}-${slug}.md`;
+        }
+        const abs = resolve(join(this.workflowRoot, rel));
+        if (!this.isInsideRoot(abs) || !this.isWritablePath(abs)) {
+            throw new WikiWriteError('BAD_REQUEST', `slug resolves outside allowed subtree: ${rel}`);
+        }
+        return abs;
+    }
+    isInsideRoot(absPath) {
+        const requested = resolve(absPath);
+        return requested === this.workflowRoot || requested.startsWith(this.workflowRoot + sep);
+    }
+    isWritablePath(absPath) {
+        const abs = resolve(absPath);
+        const rel = abs.slice(this.workflowRoot.length + 1);
+        const segs = rel.split(sep);
+        if (segs.length === 0)
+            return false;
+        const top = segs[0];
+        return top === 'specs' || top === 'phases' || top === 'memory';
+    }
+}
+// ---------------------------------------------------------------------------
+// Frontmatter serialization (flat only — matches the lean parser)
+// ---------------------------------------------------------------------------
+export function serializeFrontmatter(fm) {
+    const lines = ['---'];
+    for (const [k, v] of Object.entries(fm)) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            if (v.length === 0) {
+                lines.push(`${k}: []`);
+            }
+            else {
+                lines.push(`${k}:`);
+                for (const item of v) {
+                    lines.push(`  - ${serializeScalar(item)}`);
+                }
+            }
+        }
+        else if (typeof v === 'object') {
+            // Nested objects aren't round-trippable through the lean parser.
+            // eslint-disable-next-line no-console
+            console.warn(`[wiki-writer] dropping non-serializable key '${k}' (nested object)`);
+        }
+        else {
+            lines.push(`${k}: ${serializeScalar(v)}`);
+        }
+    }
+    lines.push('---');
+    return lines.join('\n');
+}
+function serializeScalar(v) {
+    if (typeof v === 'string') {
+        if (/[:#\n"']/.test(v) || v.trim() !== v) {
+            return JSON.stringify(v);
+        }
+        return v;
+    }
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return JSON.stringify(v);
+}
+export function splitFrontmatterAndBody(raw) {
+    const { data, content } = parseFrontmatter(raw);
+    return { frontmatter: data, body: content };
+}
+// ---------------------------------------------------------------------------
+// Small fs helpers
+// ---------------------------------------------------------------------------
+async function pathExists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeLstat(absPath) {
+    try {
+        return await lstat(absPath);
+    }
+    catch {
+        return null;
+    }
+}
+function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+//# sourceMappingURL=writer.js.map