@parall/cli 1.34.0 → 1.36.0

package/dist/commands/wiki.js

@@ -1,5 +1,7 @@
+import { promises as fs } from 'node:fs';
 import { resolveCredentials, resolveRuntimeContext } from '../lib/client.js';
 import { printError, printJson } from '../lib/output.js';
+import { deleteWikiFile, downloadWikiFile, uploadWikiFile } from '../lib/wiki-files.js';
 import { getAfcsDiff, getAfcsStatus, getWikiBlob, getWikiChangesetDetail, getWikiChangesetDiff, getWikiLog, getWikiOutline, getWikiSection, getWikiTree, listWikiChangesets, queryWiki, requestWikiAccess, resetWikiWorkspace, listWikis, proposeWikiChangeset, searchWiki, syncAllMounts, watchMounts, } from '../lib/wiki.js';
 export function registerWikiCommands(program) {
     const wiki = program.command('wiki').description('Parall Wiki — read, edit, and propose changes');
@@ -33,10 +35,10 @@ export function registerWikiCommands(program) {
         .command('sync')
         .description('Sync wiki files to local workspace. First run downloads all files; subsequent runs pull updates.')
         .argument('[wiki]', 'Wiki ID or slug (omit to sync all wikis)')
-        .action(async (_wiki) => {
+        .action(async (wikiRef) => {
         try {
             const ctx = resolveCredentials();
-            const result = await syncAllMounts(ctx);
+            const result = await syncAllMounts(ctx, wikiRef);
             for (const entry of result.synced) {
                 process.stderr.write(`wiki ${entry.slug} synced → ${entry.path}\n`);
             }
@@ -55,22 +57,21 @@ export function registerWikiCommands(program) {
     });
     wiki
         .command('status')
-        .description('Show local changes, pending changesets, and permission summary.')
+        .description('Show local changes and pending changesets.')
         .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
         .action(async (wikiRef) => {
         try {
             const ctx = resolveCredentials();
             const result = await getAfcsStatus(ctx, wikiRef);
             process.stderr.write(`Wiki: ${result.wiki_name} (${result.wiki_slug})\n`);
-            process.stderr.write(`Mount: ${result.mount_path}\n`);
-            process.stderr.write(`Mode: ${result.mode}\n\n`);
+            process.stderr.write(`Mount: ${result.mount_path}\n\n`);
             if (result.local_changes.length === 0) {
                 process.stderr.write('Local changes: none\n');
             }
             else {
                 process.stderr.write('Local changes:\n');
                 for (const file of result.local_changes) {
-                    const s = file.additions > 0 && file.deletions > 0 ? 'M' : file.additions > 0 ? 'A' : 'D';
+                    const s = file.action === 'create' ? 'A' : file.action === 'delete' ? 'D' : 'M';
                     process.stderr.write(`  ${s} ${file.path} (+${file.additions} -${file.deletions})\n`);
                 }
             }
@@ -87,11 +88,6 @@ export function registerWikiCommands(program) {
                     }
                 }
             }
-            if (result.permissions) {
-                process.stderr.write('\nPermissions:\n');
-                process.stderr.write(`  Read:  ${result.permissions.readable_prefixes.join(', ')}\n`);
-                process.stderr.write(`  Write: ${result.permissions.writable_prefixes.join(', ') || 'none'}\n`);
-            }
             printJson(result);
         }
         catch (error) {
@@ -121,7 +117,7 @@ export function registerWikiCommands(program) {
     });
     wiki
         .command('reset')
-        .description('Discard all local changes and restore files to the last synced state (re-downloads from server).')
+        .description('Discard all local changes and restore files to the last synced state.')
         .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
         .action(async (wikiRef) => {
         try {
@@ -134,6 +130,23 @@ export function registerWikiCommands(program) {
             printError(error);
         }
     });
+    wiki
+        .command('access')
+        .description('Show your access level (read / maintain / admin) for a wiki path')
+        .argument('<path>', 'Path to check (e.g. docs/ops/)')
+        .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
+        .action(async (targetPath, wikiRef) => {
+        try {
+            const ctx = resolveCredentials();
+            const { resolveWikiRefOrDefault } = await import('../lib/wiki.js');
+            const wiki = await resolveWikiRefOrDefault(ctx, wikiRef);
+            const result = await ctx.client.getWikiAccessStatus(ctx.orgId, wiki.id, targetPath);
+            printJson(result);
+        }
+        catch (error) {
+            printError(error);
+        }
+    });
     wiki
         .command('request-access')
         .description('Request read/write access to a locked wiki path. Creates an approval card for a maintainer.')
@@ -153,9 +166,9 @@ export function registerWikiCommands(program) {
     });
     wiki
         .command('log')
-        .description('Show version history. With a path: per-file history. Without: recent operations.')
+        .description("Show history. With a path: that file's commit history. Without: recent wiki operations.")
         .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
-        .argument('[path]', 'File path for per-file history')
+        .argument('[path]', 'File path for per-file commit history')
         .action(async (wikiRef, filePath) => {
         try {
             const ctx = resolveCredentials();
@@ -166,7 +179,8 @@ export function registerWikiCommands(program) {
             else {
                 for (const entry of result.entries) {
                     const pathSuffix = entry.path ? ` ${entry.path}` : '';
-                    process.stderr.write(`${entry.id.slice(0, 8)}  ${entry.created_at}  ${entry.action}${pathSuffix}\n`);
+                    const who = entry.author_name ?? entry.actor_id ?? '';
+                    process.stderr.write(`${entry.id.slice(0, 8)}  ${entry.created_at}  ${entry.action}${who ? `  (${who})` : ''}${pathSuffix}\n`);
                 }
             }
             printJson(result);
@@ -342,10 +356,98 @@ export function registerWikiCommands(program) {
             printError(error);
         }
     });
+    // ---- Binary files (upload / get / delete) ----
+    const file = wiki
+        .command('file')
+        .description('Upload, download, and delete binary wiki files (images, PDFs, archives)');
+    file
+        .command('upload')
+        .description('Upload a binary file. Direct-commits to the default branch (maintain); with --changeset, writes into a proposal branch (read + author). Text files go through changesets, not uploads.')
+        .argument('<localPath>', 'Local file to upload')
+        .argument('<repoPath>', 'Destination path inside the wiki (e.g. assets/diagram.png)')
+        .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
+        .option('--changeset <changesetId>', "Upload into this changeset's feature branch instead of the default branch")
+        .option('--message <message>', 'Commit message (default: "Upload <path>")')
+        .action(async (localPath, repoPath, wikiRef, options) => {
+        try {
+            const ctx = resolveCredentials();
+            const content = await fs.readFile(localPath);
+            const result = await uploadWikiFile(ctx, wikiRef, {
+                content,
+                toPath: repoPath,
+                changesetId: options.changeset,
+                message: options.message,
+            });
+            const where = result.target === 'changeset' ? `changeset ${result.changeset_id}` : 'default branch';
+            process.stderr.write(`Uploaded ${result.path} (${result.size} bytes, ${result.stored_as}) → ${where}\n`);
+            printJson(result);
+        }
+        catch (error) {
+            printError(error);
+        }
+    });
+    file
+        .command('get')
+        .description('Download a wiki file as raw bytes (LFS pointers are smudged to real bytes). Writes to stdout, or to --output. Use --ref to read a specific commit / changeset branch.')
+        .argument('<repoPath>', 'File path inside the wiki')
+        .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
+        .option('--ref <ref>', 'Branch, commit SHA, or changeset branch ref (default: wiki default branch)')
+        .option('-o, --output <localPath>', 'Write bytes to this local file instead of stdout')
+        .action(async (repoPath, wikiRef, options) => {
+        try {
+            const ctx = resolveCredentials();
+            const result = await downloadWikiFile(ctx, wikiRef, {
+                path: repoPath,
+                ref: options.ref,
+            });
+            if (options.output) {
+                await fs.writeFile(options.output, result.content);
+                process.stderr.write(`Wrote ${result.size} bytes → ${options.output}\n`);
+                // Buffer is omitted from JSON output; report metadata + where it went.
+                printJson({
+                    wiki_id: result.wiki_id,
+                    wiki_slug: result.wiki_slug,
+                    path: result.path,
+                    ref: result.ref,
+                    size: result.size,
+                    output: options.output,
+                });
+            }
+            else {
+                // Raw bytes to stdout (binary-safe); metadata to stderr. No JSON on
+                // stdout here — it would corrupt the byte stream.
+                process.stderr.write(`${result.path}  (${result.size} bytes${result.ref ? `, ref: ${result.ref}` : ''})\n`);
+                process.stdout.write(result.content);
+            }
+        }
+        catch (error) {
+            printError(error);
+        }
+    });
+    file
+        .command('delete')
+        .description('Delete a binary file from the wiki default branch (maintain). Text deletes must go through a changeset. The blob stays reachable in git history.')
+        .argument('<repoPath>', 'File path inside the wiki')
+        .argument('[wiki]', 'Wiki ID or slug (auto-resolves if org has one wiki)')
+        .option('--message <message>', 'Commit message (default: "Delete <path>")')
+        .action(async (repoPath, wikiRef, options) => {
+        try {
+            const ctx = resolveCredentials();
+            const result = await deleteWikiFile(ctx, wikiRef, {
+                path: repoPath,
+                message: options.message,
+            });
+            process.stderr.write(`Deleted ${result.path}\n`);
+            printJson(result);
+        }
+        catch (error) {
+            printError(error);
+        }
+    });
     // ---- Content browsing (search, query, outline, section) ----
     wiki
         .command('search')
-        .description('Search wiki content by keyword')
+        .description('Keyword search over wiki sections. Searches your local workspace copy when synced; otherwise fetches from the server.')
         .argument('<query>', 'Search query')
         .argument('[wiki]', 'Wiki ID or slug')
         .option('--path <path>', 'Restrict to a path prefix')
@@ -377,8 +479,8 @@ export function registerWikiCommands(program) {
     });
     wiki
         .command('query')
-        .description('Tree-aware structured query over wiki sections')
-        .argument('<query>', 'Natural-language query')
+        .description('Heading-aware keyword search that also ranks whole documents. Same lexical scoring as `search` (not semantic), better for multi-word questions.')
+        .argument('<query>', 'Query keywords (multi-word supported)')
         .argument('[wiki]', 'Wiki ID or slug')
         .option('--path <path>', 'Restrict to a path prefix')
         .option('--limit <n>', 'Max results (default 5)')
@@ -453,14 +555,18 @@ export function registerWikiCommands(program) {
     });
     wiki
         .command('cat')
-        .description('Read a wiki page by file path (raw markdown content)')
+        .description('Print a wiki file. Reads your local workspace copy when synced (includes your unproposed edits); falls back to the server.')
         .argument('<path>', 'File path (e.g. docs/auth.md)')
         .argument('[wiki]', 'Wiki ID or slug')
-        .action(async (filePath, wikiRef) => {
+        .option('--remote', 'Read the server version even when a local workspace copy exists')
+        .action(async (filePath, wikiRef, options) => {
         try {
             const ctx = resolveCredentials();
-            const result = await getWikiBlob(ctx, wikiRef, { path: filePath });
-            process.stderr.write(`${filePath}  (${result.size} bytes)\n\n`);
+            const result = await getWikiBlob(ctx, wikiRef, {
+                path: filePath,
+                remote: options.remote,
+            });
+            process.stderr.write(`${filePath}  (${result.size} bytes, source: ${result.source})\n\n`);
             process.stdout.write(result.content);
             if (result.content && !result.content.endsWith('\n'))
                 process.stdout.write('\n');

package/dist/index.js

@@ -10,6 +10,7 @@ import { registerTaskCommands } from './commands/tasks.js';
 import { registerCommentCommands } from './commands/comments.js';
 import { registerProjectCommands } from './commands/projects.js';
 import { registerScheduleCommands } from './commands/schedules.js';
+import { registerExternalTriggerCommands } from './commands/external-triggers.js';
 import { registerUserCommands } from './commands/users.js';
 import { registerWikiCommands } from './commands/wiki.js';
 import { registerMcpCommands } from './commands/mcp.js';
@@ -34,6 +35,7 @@ registerTaskCommands(program);
 registerCommentCommands(program);
 registerProjectCommands(program);
 registerScheduleCommands(program);
+registerExternalTriggerCommands(program);
 registerUserCommands(program);
 registerWikiCommands(program);
 registerMcpCommands(program);

package/dist/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAiCtD;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CAwBxD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAiCtD;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CA8BxD"}

package/dist/lib/client.js

@@ -59,6 +59,12 @@ export function resolveCredentials() {
     return {
         client: new ParallClient({
             baseUrl: url,
+            // Wiki endpoints (/wiki/v1) are served by wiki-service. Staging/prod front
+            // both behind one gateway (PRLL_WIKI_URL unset → falls back to the api URL,
+            // unchanged); local dev runs them on separate ports, so PRLL_WIKI_URL routes
+            // wiki calls (changeset, upload, file get, …) to :8090 while chat/task/
+            // comment/ref calls stay on PRLL_API_URL.
+            wikiBaseUrl: process.env.PRLL_WIKI_URL?.trim() || url,
             token: apiKey,
             swimlaneName: process.env.PRLL_SWIMLANE_NAME,
         }),

package/dist/lib/wiki-files.d.ts

@@ -0,0 +1,76 @@
+import type { WikiStoredAs } from '@parall/sdk';
+import { type ParallContext } from './wiki.js';
+/** Hard upload ceiling — mirrors server `handler.MaxWikiUploadBytes` (100 MiB). */
+export declare const MAX_WIKI_UPLOAD_BYTES: number;
+export type WikiFileUploadResult = {
+    wiki_id: string;
+    wiki_slug: string;
+    wiki_name: string;
+    path: string;
+    size: number;
+    stored_as: WikiStoredAs;
+    commit_sha: string;
+    content_sha: string;
+    /** Where the write landed: the default branch (direct) or a changeset branch. */
+    target: 'default_branch' | 'changeset';
+    /** Present only when uploaded into a changeset's feature branch. */
+    changeset_id?: string;
+};
+export type WikiFileDownloadResult = {
+    wiki_id: string;
+    wiki_slug: string;
+    wiki_name: string;
+    path: string;
+    /** The ref that was read (omitted when defaulting to the wiki's default branch). */
+    ref?: string;
+    size: number;
+    /** Raw file bytes (LFS pointers are smudged server-side — these are the real bytes). */
+    content: Buffer;
+};
+export type WikiFileDeleteResult = {
+    wiki_id: string;
+    wiki_slug: string;
+    wiki_name: string;
+    path: string;
+};
+export type UploadWikiFileOptions = {
+    /** Destination path inside the wiki repo, e.g. "assets/diagram.png". */
+    toPath: string;
+    /** Raw file bytes to upload. */
+    content: Buffer;
+    /** When set, write into this changeset's feature branch (read + author) instead
+     * of direct-committing to the default branch (maintain). */
+    changesetId?: string;
+    /** Optional commit message (server defaults to "Upload {path}"). */
+    message?: string;
+};
+/**
+ * Upload a binary file to a wiki. With `changesetId`, writes into that
+ * changeset's feature branch (the reader "propose with an image" path);
+ * without it, direct-commits to the default branch (maintain). Text content is
+ * rejected locally with a pointer to the changeset flow so the agent doesn't
+ * round-trip into a 422.
+ */
+export declare function uploadWikiFile(ctx: ParallContext, wikiRef: string | undefined, options: UploadWikiFileOptions): Promise<WikiFileUploadResult>;
+/**
+ * Download a wiki file's raw bytes via the bearer-authenticated
+ * `GET /files/{path}?ref=` endpoint. The server smudges LFS pointers, so the
+ * agent gets the real binary — never the few-line pointer that lands on disk
+ * from a plain `wiki sync` (the runtime image has no git-lfs). `ref` reads any
+ * branch / commit (including a changeset feature branch); it defaults to the
+ * wiki's default branch.
+ */
+export declare function downloadWikiFile(ctx: ParallContext, wikiRef: string | undefined, options: {
+    path: string;
+    ref?: string;
+}): Promise<WikiFileDownloadResult>;
+/**
+ * Delete a binary file from the wiki's default branch (maintain). Text deletes
+ * must go through a changeset; the server returns 422 USE_CHANGESET for those.
+ * The blob stays reachable via git history — this only removes it from HEAD.
+ */
+export declare function deleteWikiFile(ctx: ParallContext, wikiRef: string | undefined, options: {
+    path: string;
+    message?: string;
+}): Promise<WikiFileDeleteResult>;
+//# sourceMappingURL=wiki-files.d.ts.map

package/dist/lib/wiki-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-files.d.ts","sourceRoot":"","sources":["../../src/lib/wiki-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAGL,KAAK,aAAa,EAKnB,MAAM,WAAW,CAAC;AAoBnB,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,YAAY,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAAC;IACvC,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB;gEAC4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CA4D/B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,sBAAsB,CAAC,CAsCjC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CAa/B"}

package/dist/lib/wiki-files.js

@@ -0,0 +1,169 @@
+import { isWikiTextContent, normalizeRequiredWikiPath, resolveApiToken, resolveWikiRef, resolveWikiServiceBaseUrl, TEXT_MAX_BYTES, } from './wiki.js';
+// ---------------------------------------------------------------------------
+// Wiki binary file CRUD (Phase 4 of wiki-file-storage-design).
+//
+// Text files keep flowing through the changeset workspace (sync → edit →
+// propose); this module is the agent-facing surface for *binary* assets —
+// images, PDFs, archives — that can't be diffed and must not be base64-inlined
+// into changeset JSON. It wraps the wiki-service endpoints:
+//   - POST   /uploads                  (maintain, direct-commit default branch)
+//   - POST   /changesets/{csId}/files  (read + author, into a feature branch)
+//   - GET    /files/{path}?ref=        (read, raw bytes — bearer auth, never a
+//                                       browser <img> which can't send a token)
+//   - DELETE /files?path=              (maintain)
+//
+// Routing/size/text classification is the server's authority; the local
+// pre-checks here just turn the common mistakes into instant, actionable CLI
+// errors instead of a wasted upload that bounces off a 422/413.
+// ---------------------------------------------------------------------------
+/** Hard upload ceiling — mirrors server `handler.MaxWikiUploadBytes` (100 MiB). */
+export const MAX_WIKI_UPLOAD_BYTES = 100 * 1024 * 1024;
+/**
+ * Upload a binary file to a wiki. With `changesetId`, writes into that
+ * changeset's feature branch (the reader "propose with an image" path);
+ * without it, direct-commits to the default branch (maintain). Text content is
+ * rejected locally with a pointer to the changeset flow so the agent doesn't
+ * round-trip into a 422.
+ */
+export async function uploadWikiFile(ctx, wikiRef, options) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const toPath = normalizeRequiredWikiPath(options.toPath);
+    const content = options.content;
+    const changesetId = options.changesetId?.trim() || undefined;
+    if (content.length === 0) {
+        throw new Error(`cannot upload ${toPath}: file is empty`);
+    }
+    if (content.length > MAX_WIKI_UPLOAD_BYTES) {
+        throw new Error(`cannot upload ${toPath}: file is ${content.length} bytes, ` +
+            `over the ${MAX_WIKI_UPLOAD_BYTES}-byte (100 MiB) upload limit`);
+    }
+    // LFS pointer text is a server-generated artifact; uploading it directly
+    // would commit a dangling pointer. Reject before the text check (a pointer
+    // is valid UTF-8 and would otherwise be misrouted to "use a changeset").
+    if (looksLikeLfsPointer(content)) {
+        throw new Error(`cannot upload ${toPath}: this is a Git-LFS pointer, not real bytes. ` +
+            'Upload the underlying binary and the server generates the pointer.');
+    }
+    // Mirror the server's text gate (filetype: len <= TextMaxBytes && IsText):
+    // text goes through changesets so the diff stays reviewable.
+    if (content.length <= TEXT_MAX_BYTES && isWikiTextContent(content)) {
+        throw new Error(`cannot upload ${toPath}: it looks like a text file, and text changes go ` +
+            'through changesets (sync → edit → `parall wiki changeset create`), not uploads. ' +
+            'Uploads are for binary assets (images, PDFs, archives).');
+    }
+    // Node Buffer is a Uint8Array (a valid BlobPart); Blob copies the bytes.
+    const blob = new Blob([content]);
+    const resp = changesetId
+        ? await ctx.client.uploadWikiFileToChangeset(ctx.orgId, wiki.id, changesetId, {
+            path: toPath,
+            file: blob,
+            message: options.message,
+        })
+        : await ctx.client.uploadWikiFile(ctx.orgId, wiki.id, {
+            path: toPath,
+            file: blob,
+            message: options.message,
+        });
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        path: resp.path,
+        size: resp.size,
+        stored_as: resp.stored_as,
+        commit_sha: resp.commit_sha,
+        content_sha: resp.content_sha,
+        target: changesetId ? 'changeset' : 'default_branch',
+        ...(changesetId ? { changeset_id: changesetId } : {}),
+    };
+}
+/**
+ * Download a wiki file's raw bytes via the bearer-authenticated
+ * `GET /files/{path}?ref=` endpoint. The server smudges LFS pointers, so the
+ * agent gets the real binary — never the few-line pointer that lands on disk
+ * from a plain `wiki sync` (the runtime image has no git-lfs). `ref` reads any
+ * branch / commit (including a changeset feature branch); it defaults to the
+ * wiki's default branch.
+ */
+export async function downloadWikiFile(ctx, wikiRef, options) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const filePath = normalizeRequiredWikiPath(options.path);
+    const ref = options.ref?.trim() || undefined;
+    const token = resolveApiToken(ctx);
+    const base = wikiServiceBaseUrl(ctx);
+    // Encode each path segment so spaces / unicode in the path don't break the
+    // URL; the server's chi `/files/*` wildcard decodes them back.
+    const encodedPath = filePath.split('/').map(encodeURIComponent).join('/');
+    let url = `${base}/wiki/v1/orgs/${ctx.orgId}/wikis/${wiki.id}/files/${encodedPath}`;
+    if (ref) {
+        url += `?ref=${encodeURIComponent(ref)}`;
+    }
+    const headers = { Authorization: `Bearer ${token}` };
+    if (process.env.PRLL_SWIMLANE_NAME) {
+        headers['X-Prll-Swimlane'] = process.env.PRLL_SWIMLANE_NAME;
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`wiki-service GET ${url}: ${response.status} ${response.statusText}${text ? ` — ${text}` : ''}`);
+    }
+    const content = Buffer.from(await response.arrayBuffer());
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        path: filePath,
+        ref,
+        size: content.length,
+        content,
+    };
+}
+/**
+ * Delete a binary file from the wiki's default branch (maintain). Text deletes
+ * must go through a changeset; the server returns 422 USE_CHANGESET for those.
+ * The blob stays reachable via git history — this only removes it from HEAD.
+ */
+export async function deleteWikiFile(ctx, wikiRef, options) {
+    const wiki = await resolveWikiRef(ctx, wikiRef);
+    const filePath = normalizeRequiredWikiPath(options.path);
+    await ctx.client.deleteWikiFile(ctx.orgId, wiki.id, {
+        path: filePath,
+        message: options.message?.trim() || undefined,
+    });
+    return {
+        wiki_id: wiki.id,
+        wiki_slug: wiki.slug,
+        wiki_name: wiki.name,
+        path: filePath,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Wiki-service base URL for the raw-byte download, reusing the shared resolver
+ * (SSOT in wiki.ts, same chain as sync/bulk-download) and turning a missing
+ * base into an actionable error instead of a malformed-URL fetch failure.
+ */
+function wikiServiceBaseUrl(ctx) {
+    const base = resolveWikiServiceBaseUrl(ctx);
+    if (!base) {
+        throw new Error('wiki-service base URL is required (set PRLL_WIKI_URL or PRLL_API_URL) to download wiki files');
+    }
+    return base;
+}
+/**
+ * Pre-check mirror of the server's `gitea.IsLFSPointer` first-line gate. A
+ * full parse isn't needed — matching the version line is enough to give the
+ * LFS-specific message and avoid the changeset↔upload loop the design warns
+ * about. Anything pointer-shaped but malformed falls through to the server's
+ * authoritative classifier.
+ */
+function looksLikeLfsPointer(content) {
+    if (content.length === 0 || content.length > 1024) {
+        return false;
+    }
+    const nl = content.indexOf(0x0a);
+    const firstLine = content.subarray(0, nl >= 0 ? nl : content.length).toString('utf8');
+    return firstLine.startsWith('version https://git-lfs.github.com/spec/v1');
+}

package/dist/lib/wiki-frontmatter.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedFrontMatter {
+    type?: string;
+    description?: string;
+    tags?: string[];
+}
+/** True when any OKF field was extracted. */
+export declare function hasFrontMatter(fm: ParsedFrontMatter): boolean;
+export declare function parseFrontMatter(lines: string[], frontMatterEnd: number): ParsedFrontMatter;
+//# sourceMappingURL=wiki-frontmatter.d.ts.map

package/dist/lib/wiki-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-frontmatter.d.ts","sourceRoot":"","sources":["../../src/lib/wiki-frontmatter.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAE7D;AAQD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM,GAAG,iBAAiB,CAyB3F"}

package/dist/lib/wiki-frontmatter.js

@@ -0,0 +1,64 @@
+// Frontmatter (OKF-inspired) parsing for wiki markdown files.
+//
+// This mirrors the Go implementation in server/pkg/markdown/section.go — keep
+// the two behaviorally consistent. It lives in its own module (rather than
+// growing the already-oversized wiki.ts) per the repo's file-size discipline.
+import { load as loadYaml } from 'js-yaml';
+/** True when any OKF field was extracted. */
+export function hasFrontMatter(fm) {
+    return fm.type !== undefined || fm.description !== undefined || fm.tags !== undefined;
+}
+// parseFrontMatter extracts the optional OKF fields (type, description, tags)
+// from the leading YAML frontmatter block. Permissive by design: only
+// `---`-delimited YAML is parsed (a `+++` TOML block is detected for section
+// boundaries by detectFrontMatterEnd but its fields are not extracted); any
+// parse error / missing field / wrong-typed value degrades to undefined so a
+// malformed field never discards a valid one.
+export function parseFrontMatter(lines, frontMatterEnd) {
+    // frontMatterEnd is one past the closing fence; opening fence is line 0 and
+    // the closing fence is line frontMatterEnd-1, so a block needs >= 2 lines.
+    if (frontMatterEnd < 2 || lines.length === 0) {
+        return {};
+    }
+    if (lines[0].trim() !== '---') {
+        return {}; // only YAML frontmatter carries OKF fields
+    }
+    const body = lines.slice(1, frontMatterEnd - 1).join('\n');
+    let raw;
+    try {
+        raw = loadYaml(body);
+    }
+    catch {
+        return {};
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {};
+    }
+    const obj = raw;
+    return {
+        type: frontMatterString(obj.type),
+        description: frontMatterString(obj.description),
+        tags: frontMatterTags(obj.tags),
+    };
+}
+function frontMatterString(v) {
+    if (typeof v !== 'string') {
+        return undefined;
+    }
+    const s = v.trim();
+    return s === '' ? undefined : s;
+}
+function frontMatterTags(v) {
+    if (typeof v === 'string') {
+        const s = v.trim();
+        return s === '' ? undefined : [s];
+    }
+    if (Array.isArray(v)) {
+        const out = v
+            .filter((e) => typeof e === 'string')
+            .map((e) => e.trim())
+            .filter((e) => e !== '');
+        return out.length > 0 ? out : undefined;
+    }
+    return undefined;
+}

package/dist/lib/wiki-tools.d.ts

@@ -26,8 +26,9 @@ export type WikiToolDefinition = {
 /**
  * Build the full wiki native tool registry bound to a Parall context (credentials,
  * agent env, local mount). Returns one definition per wiki capability (list, tree,
- * status, diff, blob, search, query, outline, section, changeset diff, propose),
- * each finalized with input validation. Shared by the MCP server and the eval harness.
+ * status, diff, blob, search, query, outline, section, changeset diff, propose,
+ * binary file upload/get/delete), each finalized with input validation. Shared by
+ * the MCP server and the eval harness.
  */
 export declare function buildWikiTools(ctx: ParallContext): WikiToolDefinition[];
 //# sourceMappingURL=wiki-tools.d.ts.map

package/dist/lib/wiki-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiki-tools.d.ts","sourceRoot":"","sources":["../../src/lib/wiki-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,EASL,KAAK,aAAa,EAInB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;GASG;AAEH,MAAM,MAAM,uBAAuB,GAAG;IACpC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,YAAY,EAAE,CAAC,CAAC,WAAW,CAAC;IAC5B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC9E,CAAC;AAoBF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,kBAAkB,EAAE,CAiiBvE"}
+{"version":3,"file":"wiki-tools.d.ts","sourceRoot":"","sources":["../../src/lib/wiki-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,OAAO,EASL,KAAK,aAAa,EAInB,MAAM,WAAW,CAAC;AAUnB;;;;;;;;;GASG;AAEH,MAAM,MAAM,uBAAuB,GAAG;IACpC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,YAAY,EAAE,CAAC,CAAC,WAAW,CAAC;IAC5B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC9E,CAAC;AAmCF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,kBAAkB,EAAE,CAwrBvE"}