@parall/cli 1.34.0 → 1.36.0

package/dist/lib/wiki.js

@@ -2,17 +2,28 @@ import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { ApiError, } from '@parall/sdk';
+import { structuredPatch } from 'diff';
+import { hasFrontMatter, parseFrontMatter } from './wiki-frontmatter.js';
+// Re-exported so consumers (and tests) can reach the frontmatter parser via the
+// wiki module surface alongside detectFrontMatterEnd.
+export { parseFrontMatter } from './wiki-frontmatter.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const MARKDOWN_HEADING_RE = /^\s{0,3}(#{1,6})[ \t]+(.+?)\s*$/;
 const TRAILING_FENCE_RE = /\s+#+\s*$/;
-const LOCAL_NODE_SECTION_ARTIFACT_VERSION = 2;
+// Bumped 2 → 3 for the frontmatter (type/description/tags) fields: invalidates
+// caches built before frontmatter parsing so existing local mounts re-parse and
+// pick up the metadata even when a file's size / mtime is unchanged.
+const LOCAL_NODE_SECTION_ARTIFACT_VERSION = 3;
 const LOCAL_MANIFEST_FILE = 'manifest.json';
 const PRLL_WIKI_DIR = '.parall-wiki';
 const CONFLICTS_DIR = 'conflicts';
+const OBJECTS_DIR = 'objects';
 const REMOTE_CONFLICT_SUFFIX = '.remote';
 const REMOTE_DELETED_MARKER_SUFFIX = '.remote-deleted';
+/** Server-side text ceiling for changeset file content (mirrors filetype.TextMaxBytes). */
+export const TEXT_MAX_BYTES = 10 * 1024 * 1024;
 // ---------------------------------------------------------------------------
 // Wiki resolution helpers
 // ---------------------------------------------------------------------------
@@ -34,7 +45,10 @@ export async function resolveWikiRef(ctx, wikiRef) {
     if (fuzzy) {
         return fuzzy;
     }
-    throw new Error(`wiki not found: ${wikiRef}`);
+    const available = wikis.length > 0
+        ? ` Available wikis: ${wikis.map((w) => w.slug).join(', ')}`
+        : ' This organization has no wikis yet.';
+    throw new Error(`wiki not found: ${wikiRef}.${available}`);
 }
 /**
  * Resolve wiki reference. If wikiRef is omitted or empty, auto-resolves to
@@ -70,22 +84,55 @@ export async function getWikiTree(ctx, wikiRef, options = {}) {
 }
 export async function getWikiBlob(ctx, wikiRef, options) {
     const wiki = await resolveWikiRef(ctx, wikiRef);
+    const normalizedPath = normalizeRequiredWikiPath(options.path);
+    // Local mount first (same data source as search/section/outline) so reads
+    // reflect the agent's own in-progress edits. Files absent locally AND
+    // absent from the manifest (never synced, or ACL-filtered) fall through to
+    // the API; files in the manifest but missing on disk are pending local
+    // deletes — surfacing the server copy there would make a delete look like
+    // it failed.
+    if (!options.remote) {
+        const mount = await resolveLocalWikiMount(ctx, wiki);
+        if (mount) {
+            const target = resolvePathInsideRoot(mount.root, normalizedPath);
+            const stat = await fs.stat(target).catch(() => null);
+            if (stat?.isFile()) {
+                const content = await fs.readFile(target);
+                if (looksBinary(content)) {
+                    throw new Error(`wiki file is binary, not printable text: ${normalizedPath}. ` +
+                        'Binary files are viewable in the web UI.');
+                }
+                return {
+                    wiki,
+                    content: content.toString('utf8'),
+                    size: content.length,
+                    source: 'local_mount',
+                };
+            }
+            const manifest = await readLocalManifest(mount.root);
+            if (manifest.files[normalizedPath]) {
+                throw new Error(`${normalizedPath} is deleted in your local workspace (pending delete). ` +
+                    'Run `parall wiki changeset create` to propose the deletion, ' +
+                    '`parall wiki reset` to restore it, or `parall wiki cat --remote` to read the server version.');
+            }
+        }
+    }
     const blob = await ctx.client.getWikiBlob(ctx.orgId, wiki.id, {
-        path: normalizeRequiredWikiPath(options.path),
+        path: normalizedPath,
     });
     // Phase 2 widened WikiBlob to allow encoding='signed_url' (binary served
     // via preview URL) and still admits the legacy 'base64' inline shape,
     // both of which omit or encode `content` in ways the CLI's string surface
-    // cannot use. Only utf-8 text is safe to return verbatim; anything else
-    // gets a clear error — callers that want bytes should fetch via the
-    // signed_url flow.
+    // cannot use. Only utf-8 text is safe to return verbatim.
     if (blob.encoding !== 'utf-8' || blob.content == null) {
-        throw new Error(`wiki blob is not inline utf-8 (encoding=${blob.encoding}): ${options.path}`);
+        throw new Error(`wiki file is binary, not printable text (encoding=${blob.encoding}): ${normalizedPath}. ` +
+            'Binary files are viewable in the web UI.');
     }
     return {
         wiki,
         content: blob.content,
         size: blob.size,
+        source: 'api',
     };
 }
 // ---------------------------------------------------------------------------
@@ -259,20 +306,17 @@ export async function getAfcsStatus(ctx, wikiRef) {
     catch {
         // Changesets API may fail — non-fatal for status
     }
-    const permissions = {
-        readable_prefixes: ['(all — server ACL)'],
-        writable_prefixes: ['(server ACL)'],
-    };
+    // No permissions block: per-path access is queryable via `parall wiki
+    // access <path>`; a whole-tree writability summary needs the path-scope
+    // semantics still moving in the restriction-layer work.
     return {
         wiki_id: wiki.id,
         wiki_slug: wiki.slug,
         wiki_name: wiki.name,
         mount_path: mount.root,
-        mode: 'read_write',
         default_ref: wiki.default_branch,
         local_changes: localChanges,
         changesets,
-        permissions,
     };
 }
 export async function getAfcsDiff(ctx, wikiRef) {
@@ -295,7 +339,7 @@ export async function getAfcsDiff(ctx, wikiRef) {
 // ---------------------------------------------------------------------------
 export async function proposeWikiChangeset(ctx, wikiRef, options) {
     const wiki = await resolveWikiRef(ctx, wikiRef);
-    const mount = await requireLocalWikiMount(ctx, wiki, { requireWrite: true });
+    const mount = await requireLocalWikiMount(ctx, wiki);
     const title = options.title.trim();
     if (!title) {
         throw new Error('title is required');
@@ -303,7 +347,38 @@ export async function proposeWikiChangeset(ctx, wikiRef, options) {
     const manifest = await readLocalManifest(mount.root);
     const diff = await computeLocalDiff(mount, manifest);
     if (diff.changedPaths.length === 0) {
-        throw new Error(`no changes to propose for wiki ${wiki.slug}`);
+        throw new Error(`no changes to propose for wiki ${wiki.slug} — edit files under ${mount.root} first, ` +
+            'then run `parall wiki diff` to confirm what will be proposed');
+    }
+    // Stale-base precheck (fail-closed): compare each changed path's sync
+    // baseline against the server's CURRENT manifest. Proposing from a stale
+    // baseline would upload full content that silently rolls back concurrent
+    // edits. The server re-validates via base_sha (authoritative — this check
+    // just fails earlier with the complete file list).
+    const serverManifest = (await wikiServiceFetch(mount.manifestUrl, requireMountToken(mount)));
+    const serverShaByPath = new Map(serverManifest.data.map((e) => [e.path, e.sha]));
+    const staleLines = [];
+    for (const filePath of diff.changedPaths) {
+        const baseSha = diff.baseShaByPath.get(filePath);
+        const serverSha = serverShaByPath.get(filePath);
+        if (baseSha === undefined) {
+            // Locally created file — stale if the server got one in the meantime.
+            if (serverSha !== undefined) {
+                staleLines.push(`${filePath} (created on the server since your last sync)`);
+            }
+        }
+        else if (serverSha === undefined) {
+            staleLines.push(`${filePath} (deleted on the server since your last sync)`);
+        }
+        else if (serverSha !== baseSha) {
+            staleLines.push(`${filePath} (modified on the server since your last sync)`);
+        }
+    }
+    if (staleLines.length > 0) {
+        throw new Error(`cannot propose: ${staleLines.length} file(s) changed on the server since your last sync:\n` +
+            staleLines.map((l) => `  ${l}`).join('\n') +
+            '\nRun `parall wiki sync` to pull the latest content (your local edits are preserved; ' +
+            'conflicting files get a marker under .parall-wiki/conflicts/), resolve if needed, then propose again.');
     }
     // Build file_changes for the changeset API
     const fileChanges = [];
@@ -316,25 +391,43 @@ export async function proposeWikiChangeset(ctx, wikiRef, options) {
             fileChanges.push({
                 path: filePath,
                 action: 'delete',
+                base_sha: baseEntry?.sha,
             });
         }
         else {
             const content = await fs.readFile(localPath);
+            // The changeset API is text-only (the server rejects binary with 422
+            // USE_UPLOAD, pointing at an endpoint the CLI does not wrap). Reject
+            // locally with a clear boundary statement instead.
+            if (looksBinary(content)) {
+                throw new Error(`cannot propose ${filePath}: wiki changesets support text files only. ` +
+                    'Remove the binary from the workspace (binary uploads go through the web UI).');
+            }
+            if (content.length > TEXT_MAX_BYTES) {
+                throw new Error(`cannot propose ${filePath}: file is ${content.length} bytes, ` +
+                    `over the ${TEXT_MAX_BYTES}-byte changeset limit. Split the file or remove it from the workspace.`);
+            }
             fileChanges.push({
                 path: filePath,
                 action: baseEntry ? 'update' : 'create',
                 content_base64: content.toString('base64'),
+                base_sha: baseEntry?.sha,
             });
         }
     }
     let changeset;
     const existingChangesetId = normalizeOptionalString(options.changesetId);
     if (existingChangesetId) {
-        // Re-propose existing changeset with updated file_changes
+        // Re-propose: replace_files makes the workspace diff define the
+        // changeset's FULL content — the server resets the feature branch to
+        // default HEAD first, so a change withdrawn locally (file reverted to
+        // baseline) actually disappears from the proposal instead of silently
+        // surviving on the branch.
         changeset = await ctx.client.updateWikiChangeset(ctx.orgId, wiki.id, existingChangesetId, {
             title,
             message: normalizeOptionalString(options.message),
             file_changes: fileChanges,
+            replace_files: true,
         });
     }
     else {
@@ -407,34 +500,52 @@ function describeProposeNextAction(changeset, postMergeSync, postMergeSyncError)
 // ---------------------------------------------------------------------------
 /**
  * Discard all local changes and restore files to the last synced state.
- * Reads the local manifest and restores all files from the server.
+ * Restores from the local baseline object store (network only as a
+ * SHA-verified fallback for pre-objects mounts), so the workspace lands
+ * exactly on the manifest baseline — `wiki status` reports clean afterwards.
  */
 export async function resetWikiWorkspace(ctx, wikiRef) {
     const wiki = await resolveWikiRef(ctx, wikiRef);
     const mount = await requireLocalWikiMount(ctx, wiki);
     const manifest = await readLocalManifest(mount.root);
-    // Count changes before reset
+    // Only touch files that actually diverged from the baseline.
     const changes = await computeLocalChanges(mount);
-    const changedCount = changes.length;
-    if (changedCount === 0) {
-        return { wiki_id: wiki.id, wiki_slug: wiki.slug, files_restored: 0 };
-    }
-    // Re-download all manifest files and overwrite local state
-    const manifestPaths = Object.keys(manifest.files);
-    if (manifestPaths.length > 0) {
-        const downloaded = await bulkDownloadFiles(mount.bulkDownloadUrl, requireMountToken(mount), manifestPaths);
-        for (const entry of downloaded) {
-            const fullPath = resolvePathInsideRoot(mount.root, entry.path);
-            await fs.mkdir(path.dirname(fullPath), { recursive: true });
-            await fs.writeFile(fullPath, Buffer.from(entry.content_base64, 'base64'));
+    if (changes.length === 0) {
+        return { wiki_id: wiki.id, wiki_slug: wiki.slug, files_restored: 0, unrestorable_paths: [] };
+    }
+    let restored = 0;
+    const unrestorable = [];
+    for (const change of changes) {
+        const entry = manifest.files[change.path];
+        const fullPath = resolvePathInsideRoot(mount.root, change.path);
+        if (!entry) {
+            // Locally created file — discard.
+            await fs.rm(fullPath, { force: true });
+            await removeEmptyParents(mount.root, path.dirname(fullPath));
+            restored++;
+            continue;
         }
+        const baseline = await loadBaselineContent(mount, change.path, entry.sha);
+        if (!baseline) {
+            // No baseline available (pre-objects mount, server moved on). Leave the
+            // local file untouched rather than overwriting it with non-baseline
+            // content; `parall wiki sync` is the path that reconciles this state.
+            unrestorable.push(change.path);
+            continue;
+        }
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, baseline);
+        restored++;
+    }
+    if (unrestorable.length > 0) {
+        console.warn(`[wiki reset] ${unrestorable.length} file(s) had no recoverable baseline and were left as-is: ` +
+            `${unrestorable.join(', ')} — run \`parall wiki sync\` to reconcile`);
     }
-    // Remove any local file not in manifest
-    await removeFilesNotInManifest(mount.root, manifest);
     return {
         wiki_id: wiki.id,
         wiki_slug: wiki.slug,
-        files_restored: changedCount,
+        files_restored: restored,
+        unrestorable_paths: unrestorable,
     };
 }
 export async function listWikiChangesets(ctx, wikiRef) {
@@ -495,10 +606,32 @@ export async function requestWikiAccess(ctx, wikiRef, targetPath, reason) {
         message: 'Access request submitted. Waiting for approval.',
     };
 }
+/**
+ * Wiki history. Without a path: recent wiki operations (audit log). With a
+ * path: that file's commit history from the default branch.
+ */
 export async function getWikiLog(ctx, wikiRef, filePath) {
     const wiki = await resolveWikiRef(ctx, wikiRef);
-    if (filePath?.trim()) {
-        throw new Error('Per-file wiki history is not implemented yet. Omit the path to see org-wide operations.');
+    // Same normalization as every other path entry point — `./docs/a.md` or
+    // `/docs/a.md` would otherwise reach the server un-normalized and read
+    // back as an empty history.
+    const normalizedPath = filePath?.trim() ? normalizeRequiredWikiPath(filePath) : undefined;
+    if (normalizedPath) {
+        const commits = await ctx.client.getWikiFileCommits(ctx.orgId, wiki.id, normalizedPath);
+        return {
+            wiki_id: wiki.id,
+            wiki_slug: wiki.slug,
+            wiki_name: wiki.name,
+            path: normalizedPath,
+            entries: commits.data.map((c) => ({
+                type: 'commit',
+                id: c.sha,
+                path: normalizedPath,
+                action: c.title,
+                author_name: c.author_name,
+                created_at: c.date,
+            })),
+        };
     }
     const ops = await ctx.client.getWikiOperations(ctx.orgId, wiki.id);
     const entries = ops.data.map((op) => ({
@@ -516,12 +649,16 @@ export async function getWikiLog(ctx, wikiRef, filePath) {
     };
 }
 /**
- * List accessible wikis for this org, sync each via REST
- * (manifest comparison + bulk download), and remove stale directories.
+ * Sync wiki workspaces via REST (manifest comparison + bulk download).
+ * Without `wikiRef`: every accessible wiki is synced and stale mount
+ * directories are pruned. With `wikiRef`: only that wiki is synced and
+ * pruning is skipped — other wikis' workspaces must survive a scoped sync.
  * Mount path is determined client-side: {mountRoot}/{slug}/
  */
-export async function syncAllMounts(ctx) {
-    const wikis = await ctx.client.getWikis(ctx.orgId);
+export async function syncAllMounts(ctx, wikiRef) {
+    const allWikis = await ctx.client.getWikis(ctx.orgId);
+    const target = wikiRef?.trim() ? await resolveWikiRef(ctx, wikiRef) : undefined;
+    const wikis = target ? allWikis.filter((w) => w.id === target.id) : allWikis;
     const mountRoot = ctx.mountRoot?.trim() || process.env.PRLL_WIKI_MOUNT_ROOT?.trim();
     const activeMountPaths = new Set();
     const synced = [];
@@ -538,7 +675,9 @@ export async function syncAllMounts(ctx) {
             failed: outcome.failed,
         });
     }
-    await pruneStaleMounts(mountRoot, activeMountPaths);
+    if (!target) {
+        await pruneStaleMounts(mountRoot, activeMountPaths);
+    }
     const ok = synced.every((s) => s.failed.length === 0);
     return { ok, mounts: wikis.length, synced };
 }
@@ -623,10 +762,7 @@ export async function syncSingleWiki(ctx, wiki, mountPath) {
     const metaDir = path.join(mountPath, PRLL_WIKI_DIR);
     await fs.mkdir(metaDir, { recursive: true });
     const token = resolveApiToken(ctx);
-    const baseUrl = (ctx.baseUrl ??
-        process.env.PRLL_WIKI_URL ??
-        process.env.PRLL_API_URL ??
-        '').replace(/\/+$/, '');
+    const baseUrl = resolveWikiServiceBaseUrl(ctx);
     const manifestUrl = `${baseUrl}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}/manifest`;
     const bulkDownloadUrl = `${baseUrl}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}/files/bulk-download`;
     // 1. Fetch server manifest + read local manifest.
@@ -695,6 +831,7 @@ export async function syncSingleWiki(ctx, wiki, mountPath) {
     }
     // 5. Apply actions and start with the previous manifest, mutating per action.
     const newFiles = { ...localManifest.files };
+    const downloadedBySha = new Map();
     const conflicts = [];
     const failed = [];
     let applied = 0;
@@ -763,6 +900,7 @@ export async function syncSingleWiki(ctx, wiki, mountPath) {
                 await fs.mkdir(path.dirname(fullPath), { recursive: true });
                 await fs.writeFile(fullPath, buf);
                 newFiles[action.path] = { sha: action.remoteSha, size: action.remoteSize };
+                downloadedBySha.set(action.remoteSha, buf);
                 applied++;
                 break;
             }
@@ -853,13 +991,16 @@ export async function syncSingleWiki(ctx, wiki, mountPath) {
             }
         }
     }
-    // 6. Persist new manifest.
+    // 6. Persist new manifest + refresh the baseline object store so diff and
+    // reset can always reproduce the exact synced content locally.
     const newManifest = {
         wiki_id: wiki.id,
         synced_at: new Date().toISOString(),
         files: newFiles,
     };
     await writeLocalManifest(mountPath, newManifest);
+    await ensureBaselineObjects(mountPath, newFiles, downloadedBySha);
+    await gcBaselineObjects(mountPath, newFiles);
     if (conflicts.length > 0) {
         for (const c of conflicts) {
             const where = c.remoteCopyPath ? ` → ${path.relative(mountPath, c.remoteCopyPath)}` : '';
@@ -949,15 +1090,125 @@ async function writeLocalManifest(mountRoot, manifest) {
     await fs.writeFile(path.join(metaDir, LOCAL_MANIFEST_FILE), JSON.stringify(manifest, null, 2), 'utf8');
 }
 // ---------------------------------------------------------------------------
+// Baseline object store (.parall-wiki/objects/<sha>)
+//
+// Content-addressed copies of the last-synced version of every manifest file.
+// diff/status/reset read the true sync baseline from here instead of fetching
+// the server's CURRENT content (which is the wrong base whenever the server
+// has moved past the local sync point).
+// ---------------------------------------------------------------------------
+function baselineObjectPath(mountRoot, sha) {
+    return path.join(mountRoot, PRLL_WIKI_DIR, OBJECTS_DIR, sha);
+}
+async function readBaselineObject(mountRoot, sha) {
+    try {
+        return await fs.readFile(baselineObjectPath(mountRoot, sha));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeBaselineObject(mountRoot, sha, content) {
+    const target = baselineObjectPath(mountRoot, sha);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, content);
+}
+/**
+ * Make sure every manifest entry has its baseline object on disk.
+ * Content sources, in order: bytes downloaded during this sync
+ * (`contentBySha`), then the local working-tree file when its blob SHA still
+ * matches the manifest (clean file — typical for pre-objects mounts being
+ * upgraded). Files that are locally dirty AND missing an object stay absent;
+ * diff falls back per-file (see loadBaselineContent).
+ */
+async function ensureBaselineObjects(mountRoot, files, contentBySha) {
+    for (const [relPath, entry] of Object.entries(files)) {
+        if (await pathExists(baselineObjectPath(mountRoot, entry.sha))) {
+            continue;
+        }
+        const downloaded = contentBySha?.get(entry.sha);
+        if (downloaded) {
+            await writeBaselineObject(mountRoot, entry.sha, downloaded);
+            continue;
+        }
+        const probe = await probeLocalGitBlob(mountRoot, relPath);
+        if (probe.kind === 'file' && probe.sha === entry.sha) {
+            const fullPath = resolvePathInsideRoot(mountRoot, relPath);
+            await writeBaselineObject(mountRoot, entry.sha, await fs.readFile(fullPath));
+        }
+    }
+}
+/** Drop baseline objects no longer referenced by any manifest entry. */
+async function gcBaselineObjects(mountRoot, files) {
+    const objectsDir = path.join(mountRoot, PRLL_WIKI_DIR, OBJECTS_DIR);
+    let names;
+    try {
+        names = await fs.readdir(objectsDir);
+    }
+    catch {
+        return;
+    }
+    const live = new Set(Object.values(files).map((e) => e.sha));
+    for (const name of names) {
+        if (!live.has(name)) {
+            await fs.rm(path.join(objectsDir, name), { force: true });
+        }
+    }
+}
+/**
+ * Load the baseline (last-synced) content for a manifest entry. Objects store
+ * first; when absent (mount predates the objects store and the file is
+ * locally dirty), fall back to downloading the server's current content and
+ * accept it ONLY if its blob SHA matches the manifest base — otherwise the
+ * server has moved and no true baseline is available (returns null).
+ */
+async function loadBaselineContent(mount, relPath, expectedSha) {
+    const cached = await readBaselineObject(mount.root, expectedSha);
+    if (cached) {
+        return cached;
+    }
+    if (!mount.token) {
+        return null;
+    }
+    try {
+        const entries = await bulkDownloadFiles(mount.bulkDownloadUrl, mount.token, [relPath]);
+        const entry = entries[0];
+        if (!entry || entry.error) {
+            return null;
+        }
+        const content = Buffer.from(entry.content_base64, 'base64');
+        if (computeGitBlobSHA(content) !== expectedSha) {
+            return null;
+        }
+        await writeBaselineObject(mount.root, expectedSha, content);
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
 // REST helpers for wiki-service
 // ---------------------------------------------------------------------------
-function resolveApiToken(ctx) {
+// Exported so the binary-file raw-byte download (wiki-files.ts) authenticates
+// the same way as sync/bulk-download — bearer from the client or PRLL_API_KEY.
+export function resolveApiToken(ctx) {
     const token = ctx?.client.getToken()?.trim() || process.env.PRLL_API_KEY?.trim();
     if (!token) {
         throw new Error('API token is required via ctx.client.getToken() or PRLL_API_KEY for wiki operations');
     }
     return token;
 }
+/**
+ * Resolve the wiki-service base URL (trailing slashes trimmed): explicit ctx
+ * override, then PRLL_WIKI_URL, then PRLL_API_URL. SSOT for the raw-fetch wiki
+ * endpoints (sync / bulk-download / binary file download). Hosted/staging/prod
+ * collapse these to one gateway host; local dev can split api (:8080) and wiki
+ * (:8090). Returns '' when none is set — callers decide whether that's fatal.
+ */
+export function resolveWikiServiceBaseUrl(ctx) {
+    return (ctx.baseUrl ?? process.env.PRLL_WIKI_URL ?? process.env.PRLL_API_URL ?? '').replace(/\/+$/, '');
+}
 function tryResolveApiToken(ctx) {
     return ctx?.client.getToken()?.trim() || process.env.PRLL_API_KEY?.trim() || undefined;
 }
@@ -1011,54 +1262,92 @@ export function computeGitBlobSHA(content) {
     const header = Buffer.from(`blob ${content.length}\0`, 'utf8');
     return createHash('sha1').update(header).update(content).digest('hex');
 }
-/** Compute list of changed files by comparing local disk to local manifest. */
-async function computeLocalChanges(mount) {
-    const manifest = await readLocalManifest(mount.root);
-    const diffFiles = [];
-    const visited = new Set();
-    // Walk local files to find modified/added
-    await walkLocalFiles(mount.root, mount.root, async (fullPath, relativePath) => {
-        if (!matchesAllowedPrefix(relativePath, [])) {
-            return;
-        }
-        visited.add(relativePath);
-        const localContent = await fs.readFile(fullPath);
-        const localSha = computeGitBlobSHA(localContent);
-        const manifestEntry = manifest.files[relativePath];
-        if (!manifestEntry) {
-            // New file
-            const lines = localContent.toString('utf8').split('\n').length;
-            diffFiles.push({ path: relativePath, additions: lines, deletions: 0 });
-        }
-        else if (localSha !== manifestEntry.sha) {
-            // Modified file — compute line diff estimate
-            const localLines = localContent.toString('utf8').split('\n');
-            const additions = localLines.length;
-            const deletions = estimateLines(manifestEntry.size);
-            diffFiles.push({ path: relativePath, additions, deletions });
+// Exact mirror of the magic signatures where the server's classifier
+// (filetype.IsText → Go http.DetectContentType → isBinaryContentType)
+// rejects content that could still be NUL-free, UTF-8-decodable bytes.
+// Signatures whose match requires NUL or non-UTF-8 bytes (PNG, JPEG, OGG,
+// MIDI, ICO, …) are deliberately omitted — the UTF-8 + NUL checks below
+// already cover them. Keep this table in lockstep with the Go sniffing
+// rules; test/testdata/text-classifier-cases.json is the shared contract
+// both sides verify against.
+const BINARY_MAGIC_PREFIXES = [
+    Buffer.from('GIF87a'), // image/gif
+    Buffer.from('GIF89a'), // image/gif
+    Buffer.from('%PDF-'), // application/pdf
+    Buffer.from('BM'), // image/bmp (yes, bare "BM" — Go sniffs it as BMP)
+    Buffer.from('ID3'), // audio/mpeg
+    Buffer.from([0x50, 0x4b, 0x03, 0x04]), // application/zip
+    Buffer.from([0x1f, 0x8b, 0x08]), // application/x-gzip
+];
+// Container formats Go sniffs via offset-masked signatures: 4-byte container
+// tag at offset 0, format tag at offset 8.
+const BINARY_CONTAINER_SIGS = [
+    { head: 'RIFF', at8: 'WAVE' }, // audio/wave
+    { head: 'RIFF', at8: 'AVI ' }, // video/avi
+    { head: 'RIFF', at8: 'WEBPVP' }, // image/webp
+    { head: 'FORM', at8: 'AIFF' }, // audio/aiff
+];
+const utf8Strict = new TextDecoder('utf-8', { fatal: true });
+/**
+ * Mirror of the server's text classifier (filetype.IsText): content-type
+ * magic sniff, valid UTF-8, and no NUL bytes — kept aligned so content the
+ * CLI accepts cannot bounce off the server's 422 USE_UPLOAD later. The
+ * shared fixture table (test/testdata/text-classifier-cases.json) is
+ * verified by both this implementation's tests and the Go package's tests.
+ */
+export function isWikiTextContent(content) {
+    for (const magic of BINARY_MAGIC_PREFIXES) {
+        if (content.subarray(0, magic.length).equals(magic)) {
+            return false;
         }
-    });
-    // Find deleted files (in manifest but not on disk)
-    for (const [filePath, entry] of Object.entries(manifest.files)) {
-        if (!visited.has(filePath)) {
-            const deletions = estimateLines(entry.size);
-            diffFiles.push({ path: filePath, additions: 0, deletions });
+    }
+    for (const sig of BINARY_CONTAINER_SIGS) {
+        if (content.subarray(0, 4).equals(Buffer.from(sig.head)) &&
+            content.subarray(8, 8 + sig.at8.length).equals(Buffer.from(sig.at8))) {
+            return false;
         }
     }
-    diffFiles.sort((a, b) => a.path.localeCompare(b.path));
-    return diffFiles;
+    if (content.includes(0)) {
+        return false;
+    }
+    try {
+        utf8Strict.decode(content);
+    }
+    catch {
+        return false;
+    }
+    return true;
 }
-/** Compute diff including unified patch by comparing local files vs manifest base content. */
+function looksBinary(content) {
+    return !isWikiTextContent(content);
+}
+/** Compute list of changed files by comparing local disk to local manifest. */
+async function computeLocalChanges(mount) {
+    const manifest = await readLocalManifest(mount.root);
+    const diff = await computeLocalDiff(mount, manifest);
+    return diff.diffFiles;
+}
+/**
+ * Compute the local workspace diff against the last-synced baseline. Base
+ * content comes from the local objects store (with a SHA-verified network
+ * fallback for pre-objects mounts), so the diff base is always the true sync
+ * point — never the server's current content.
+ */
 async function computeLocalDiff(mount, manifest) {
     const diffFiles = [];
     const patchParts = [];
     const visited = new Set();
-    const token = requireMountToken(mount);
+    const baseShaByPath = new Map();
+    const loadBase = async (relPath, entry) => {
+        const base = await loadBaselineContent(mount, relPath, entry.sha);
+        // A missing baseline (pre-objects mount with a locally dirty file and a
+        // server that has since moved) degrades to an empty base: the patch shows
+        // the full local content as additions. propose() still carries the right
+        // base_sha, so staleness is caught server-side regardless.
+        return base ? base.toString('utf8') : '';
+    };
     // Walk local files to find modified/added
     await walkLocalFiles(mount.root, mount.root, async (fullPath, relativePath) => {
-        if (!matchesAllowedPrefix(relativePath, [])) {
-            return;
-        }
         visited.add(relativePath);
         const localContent = await fs.readFile(fullPath);
         const localSha = computeGitBlobSHA(localContent);
@@ -1066,83 +1355,62 @@ async function computeLocalDiff(mount, manifest) {
         if (!manifestEntry) {
             // New file
             const localText = localContent.toString('utf8');
-            const localLines = localText.split('\n');
-            diffFiles.push({ path: relativePath, additions: localLines.length, deletions: 0 });
-            patchParts.push(buildUnifiedDiff(relativePath, '', localText));
+            appendFileDiff(diffFiles, patchParts, relativePath, '', localText, 'create');
         }
         else if (localSha !== manifestEntry.sha) {
-            // Modified file — fetch base content from server for diff
-            const localText = localContent.toString('utf8');
-            let baseText = '';
-            try {
-                const baseEntries = await bulkDownloadFiles(mount.bulkDownloadUrl, token, [relativePath]);
-                if (baseEntries.length > 0) {
-                    baseText = Buffer.from(baseEntries[0].content_base64, 'base64').toString('utf8');
-                }
-            }
-            catch {
-                // If we can't fetch base, treat as full addition
-            }
-            const localLines = localText.split('\n');
-            const baseLines = baseText.split('\n');
-            diffFiles.push({
-                path: relativePath,
-                additions: localLines.length,
-                deletions: baseLines.length,
-            });
-            patchParts.push(buildUnifiedDiff(relativePath, baseText, localText));
+            // Modified file
+            baseShaByPath.set(relativePath, manifestEntry.sha);
+            const baseText = await loadBase(relativePath, manifestEntry);
+            appendFileDiff(diffFiles, patchParts, relativePath, baseText, localContent.toString('utf8'), 'update');
         }
     });
     // Find deleted files
     for (const [filePath, entry] of Object.entries(manifest.files)) {
         if (!visited.has(filePath)) {
-            let baseText = '';
-            try {
-                const baseEntries = await bulkDownloadFiles(mount.bulkDownloadUrl, token, [filePath]);
-                if (baseEntries.length > 0) {
-                    baseText = Buffer.from(baseEntries[0].content_base64, 'base64').toString('utf8');
-                }
-            }
-            catch {
-                // Estimate
-            }
-            const baseLines = baseText.split('\n');
-            diffFiles.push({ path: filePath, additions: 0, deletions: baseLines.length });
-            patchParts.push(buildUnifiedDiff(filePath, baseText, ''));
+            baseShaByPath.set(filePath, entry.sha);
+            const baseText = await loadBase(filePath, entry);
+            appendFileDiff(diffFiles, patchParts, filePath, baseText, '', 'delete');
         }
     }
     diffFiles.sort((a, b) => a.path.localeCompare(b.path));
     const changedPaths = diffFiles.map((f) => f.path);
     const patch = patchParts.join('');
-    return { changedPaths, diffFiles, patch };
-}
-/** Build a minimal unified diff between two text strings. */
-function buildUnifiedDiff(filePath, oldText, newText) {
-    const oldLines = oldText ? oldText.split('\n') : [];
-    const newLines = newText ? newText.split('\n') : [];
-    const aPath = oldText ? `a/${filePath}` : '/dev/null';
-    const bPath = newText ? `b/${filePath}` : '/dev/null';
+    return { changedPaths, diffFiles, patch, baseShaByPath };
+}
+/** Append one file's real (Myers) unified diff and +/- counts. */
+function appendFileDiff(diffFiles, patchParts, filePath, oldText, newText, action) {
+    const hunks = structuredPatch(filePath, filePath, oldText, newText, undefined, undefined, {
+        context: 3,
+    }).hunks;
+    let additions = 0;
+    let deletions = 0;
     const parts = [`diff --git a/${filePath} b/${filePath}\n`];
-    if (!oldText) {
+    if (action === 'create') {
         parts.push('new file mode 100644\n');
     }
-    else if (!newText) {
+    else if (action === 'delete') {
         parts.push('deleted file mode 100644\n');
     }
-    parts.push(`--- ${aPath}\n`);
-    parts.push(`+++ ${bPath}\n`);
-    parts.push(`@@ -1,${oldLines.length} +1,${newLines.length} @@\n`);
-    for (const line of oldLines) {
-        parts.push(`-${line}\n`);
+    parts.push(`--- ${action === 'create' ? '/dev/null' : `a/${filePath}`}\n`);
+    parts.push(`+++ ${action === 'delete' ? '/dev/null' : `b/${filePath}`}\n`);
+    for (const hunk of hunks) {
+        parts.push(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@\n`);
+        for (const line of hunk.lines) {
+            parts.push(`${line}\n`);
+            if (line.startsWith('+'))
+                additions++;
+            else if (line.startsWith('-'))
+                deletions++;
+        }
     }
-    for (const line of newLines) {
-        parts.push(`+${line}\n`);
+    diffFiles.push({ path: filePath, action, additions, deletions });
+    // An empty-file create/delete produces zero hunks but is still a real
+    // change — emit the header-only entry so the patch lists every changed
+    // path. Only a hunk-less UPDATE (identical content, e.g. mode-only noise)
+    // is genuinely nothing to show.
+    if (hunks.length > 0 || action !== 'update') {
+        patchParts.push(parts.join(''));
     }
-    return parts.join('');
-}
-/** Estimate number of lines from file size (rough: ~40 bytes per line). */
-function estimateLines(sizeBytes) {
-    return Math.max(1, Math.round(sizeBytes / 40));
 }
 // ---------------------------------------------------------------------------
 // File system helpers
@@ -1229,10 +1497,7 @@ async function resolveLocalWikiMount(ctx, wiki) {
     if (!(await pathExists(root))) {
         return null;
     }
-    const baseUrl = (ctx.baseUrl ??
-        process.env.PRLL_WIKI_URL ??
-        process.env.PRLL_API_URL ??
-        '').replace(/\/+$/, '');
+    const baseUrl = resolveWikiServiceBaseUrl(ctx);
     const wikiBase = `${baseUrl}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}`;
     return {
         root,
@@ -1244,13 +1509,11 @@ async function resolveLocalWikiMount(ctx, wiki) {
         changesetsUrl: `${wikiBase}/changesets`,
     };
 }
-async function requireLocalWikiMount(ctx, wiki, options = {}) {
+async function requireLocalWikiMount(ctx, wiki) {
     const mount = await resolveLocalWikiMount(ctx, wiki);
     if (!mount) {
-        throw new Error(`wiki ${wiki.slug} is not available in a local agent mount`);
-    }
-    if (options.requireWrite && 'read_write' !== 'read_write') {
-        throw new Error(`wiki ${wiki.slug} mount is read-only`);
+        throw new Error(`wiki ${wiki.slug} has no local workspace yet — run \`parall wiki sync\` to download it ` +
+            '(the sync output prints the workspace path)');
     }
     return mount;
 }
@@ -1539,14 +1802,21 @@ function stripNodeSectionContent(section) {
 }
 function buildIndexNodes(sections) {
     const nodes = [];
+    // File-level frontmatter folds into only the first section of each file
+    // (matching the indexed search-indexer's section-0 gating) so a
+    // frontmatter-only query returns one hit per document, not one per section.
+    const seenFile = new Set();
     for (const section of sections) {
-        nodes.push(buildIndexedNode(section));
+        const includeFrontmatter = !seenFile.has(section.path);
+        seenFile.add(section.path);
+        nodes.push(buildIndexedNode(section, includeFrontmatter));
     }
     return nodes;
 }
 function parseMarkdownFile(wiki, file) {
     const lines = file.content.split('\n');
     const frontMatterEnd = detectFrontMatterEnd(lines);
+    const fm = parseFrontMatter(lines, frontMatterEnd);
     const headings = extractMarkdownHeadings(lines, frontMatterEnd);
     const fileTitle = defaultFileTitle(file.path);
     if (headings.length === 0) {
@@ -1560,7 +1830,11 @@ function parseMarkdownFile(wiki, file) {
             endLine: lines.length,
             content: lines.slice(frontMatterEnd).join('\n').trim(),
         });
-        return !docNode.content ? [] : [docNode];
+        // Keep an empty-body doc node when it carries frontmatter, so a
+        // frontmatter-only page still exposes its metadata — matching the Go
+        // parser, which always returns the doc section for a no-heading file.
+        const keep = !!docNode.content || hasFrontMatter(fm);
+        return applyFrontMatter(keep ? [docNode] : [], fm);
     }
     const nodes = [];
     const firstHeadingLine = headings[0].line;
@@ -1597,7 +1871,24 @@ function parseMarkdownFile(wiki, file) {
                 .trim(),
         }));
     }
-    return nodes;
+    return applyFrontMatter(nodes, fm);
+}
+// applyFrontMatter copies file-level frontmatter onto every section parsed from
+// the file (frontmatter is a document-level property in OKF). Mirrors the Go
+// implementation in server/pkg/markdown/section.go. No-op when empty.
+function applyFrontMatter(sections, fm) {
+    if (!hasFrontMatter(fm)) {
+        return sections;
+    }
+    for (const section of sections) {
+        if (fm.type !== undefined)
+            section.type = fm.type;
+        if (fm.description !== undefined)
+            section.description = fm.description;
+        if (fm.tags !== undefined)
+            section.tags = fm.tags;
+    }
+    return sections;
 }
 function buildNodeSection(wiki, input) {
     const content = input.content.trim();
@@ -1617,11 +1908,14 @@ function buildNodeSection(wiki, input) {
         content,
     };
 }
-function buildIndexedNode(section) {
+function buildIndexedNode(section, includeFrontmatter) {
     const searchText = [
         section.path,
         section.title,
         section.heading_path?.join(' ') ?? '',
+        ...(includeFrontmatter
+            ? [section.type ?? '', section.description ?? '', section.tags?.join(' ') ?? '']
+            : []),
         section.content,
     ]
         .join('\n')
@@ -1965,16 +2259,22 @@ function extractMarkdownHeadings(lines, startIndex) {
     }
     return headings;
 }
-function detectFrontMatterEnd(lines) {
+// Exported for unit testing; mirrors server/pkg/markdown/section.go.
+export function detectFrontMatterEnd(lines) {
     if (lines.length === 0) {
         return 0;
     }
-    const first = lines[0].trim();
+    // Fences must sit at the line start; only trailing spaces / tabs / CR are
+    // allowed (right-trim, NOT trim). An indented `  ---` is legal content — e.g.
+    // inside a YAML block scalar — and must not open or close the block. Mirrors
+    // server/pkg/markdown/section.go and the micromark frontmatter grammar.
+    const rtrim = (s) => s.replace(/[ \t\r]+$/, '');
+    const first = rtrim(lines[0]);
     if (first !== '---' && first !== '+++') {
         return 0;
     }
     for (let i = 1; i < lines.length; i += 1) {
-        if (lines[i].trim() === first) {
+        if (rtrim(lines[i]) === first) {
             return i + 1;
         }
     }
@@ -2043,7 +2343,9 @@ function normalizeWikiPath(value) {
         .replace(/^\/+/, '');
     return normalized === '.' ? '' : normalized.replace(/\/+$/, '');
 }
-function normalizeRequiredWikiPath(value) {
+// Exported so the binary-file helpers (wiki-files.ts) normalize repo paths
+// through the exact same rules as every other CLI path entry point.
+export function normalizeRequiredWikiPath(value) {
     const normalized = normalizeWikiPath(value);
     if (!normalized) {
         throw new Error('path is required');