@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/workspace/startup/steps/template-source.ts

@@ -40,9 +40,11 @@ export const TEMPLATE_SOURCE_FALLBACKS: ReadonlyMap<string, string> = new Map([
 ]);
 
 /**
- * Where the managed guide asks for the rules every file tool shares. Not a
- * layout placeholder: the layout renderer lives in `platform-shared`, which
- * the frontend also reads, and the rules are backend text.
+ * Where a template file may ask for the rules every file tool shares. The
+ * packaged template no longer does — the guide is composed in code, see
+ * `modules/agent-guide` — but a distribution's template may. Not a layout
+ * placeholder: the layout renderer lives in `platform-shared`, which the
+ * frontend also reads, and the rules are backend text.
  */
 export const SHARED_FILE_RULES_PLACEHOLDER = '{{sharedFileRules}}';
 

package/src/modules/workspace/workspace.routes.ts

@@ -13,9 +13,13 @@ import {
   canonicalRelativePath,
   folderPlaceholderPath,
   isPlatformFile,
+  isPlatformFolder,
   isPlatformRestoreShape,
+  isRepositoryOwnFile,
+  repositoryOwnFileDeleteRefusal,
   platformFileCreationRefusal,
   platformFileRefusal,
+  platformFolderRefusal,
   reservedRootDirNames,
 } from '@bevel-software/platform-shared';
 import { FolderTooLargeError, type ReadTreeFilter } from './workspace.service.js';
@@ -39,6 +43,7 @@ import { removeEmptyDirs } from './empty-dirs.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 import type { SkillSaveCheck } from './workspace.tools.js';
 import { MAX_UPLOAD_BYTES } from './upload-limits.js';
+import { OCTET_STREAM, rawExtensionOf, rawMimeFor } from './file-readers/raw-mime.js';
 
 /**
  * One file identity from one request field, or `null` when the caller sent
@@ -571,8 +576,11 @@ export function createWorkspaceRoutes(
     res: express.Response,
     workspaceId: string,
     relativePath: string,
+    // A caller that has already resolved the user hands it over, so one
+    // request is not looked up twice.
+    resolvedUser?: { email: string },
   ): Promise<boolean> {
-    const user = await requireUser(req, res);
+    const user = resolvedUser ?? (await requireUser(req, res));
     if (!user) return false;
     let allowed: boolean;
     try {
@@ -852,27 +860,15 @@ export function createWorkspaceRoutes(
         // its own weak ETag and answers a matching If-None-Match with a 304.
         res.setHeader('ETag', `"${at.blobId}"`);
       }
-      const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
-      const mimeTypes: Record<string, string> = {
-        '.png': 'image/png',
-        '.jpg': 'image/jpeg',
-        '.jpeg': 'image/jpeg',
-        '.gif': 'image/gif',
-        '.webp': 'image/webp',
-        '.svg': 'image/svg+xml',
-        '.bmp': 'image/bmp',
-        '.ico': 'image/x-icon',
-        '.pdf': 'application/pdf',
-        '.docx':
-          'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-        '.xlsx':
-          'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-      };
+      // The type from the extension, the one table the embed's raw route
+      // serves from as well (`file-readers/raw-mime.ts`).
+      const ext = rawExtensionOf(filePath);
+      const inlineMime = rawMimeFor(filePath);
       // SVG is active web content (it can carry <script>), and it is active in
       // BOTH directions: a saved-to-disk SVG re-opened later runs its scripts
       // under the file:// origin, so a download is forced to octet-stream.
-      const downloadMime = ext === '.svg' ? 'application/octet-stream' : (mimeTypes[ext] || 'application/octet-stream');
-      res.setHeader('Content-Type', wantsDownload ? downloadMime : (mimeTypes[ext] || 'application/octet-stream'));
+      const downloadMime = ext === '.svg' ? OCTET_STREAM : inlineMime;
+      res.setHeader('Content-Type', wantsDownload ? downloadMime : inlineMime);
       // Block MIME-sniffing so a misdeclared file can't be promoted to
       // active content by the browser.
       res.setHeader('X-Content-Type-Options', 'nosniff');
@@ -978,9 +974,33 @@ export function createWorkspaceRoutes(
       res.status(400).json({ error: 'download=1 is required for folder zip downloads' });
       return;
     }
-    if (!(await requireDownloadPermission(req, res, id, folderPath))) return;
+    const user = await requireUser(req, res);
+    if (!user) return;
+    if (!(await requireDownloadPermission(req, res, id, folderPath, user))) return;
+    // `download` on the folder lets the caller ASK for the zip. What goes in
+    // it is judged file by file, through the two gates the per-file route
+    // runs in the same order: a file the caller may not read is left out, and
+    // so is one they may read but not download. Nothing in the answer names a
+    // left-out file; the count below covers only files the caller could
+    // already see in the tree, so it discloses nothing the tree does not.
+    let withheld = 0;
+    const include = async (paths: string[]): Promise<ReadonlySet<string>> => {
+      const readable = await accessControl.canReadBatch(id, user.email, paths);
+      const visible = paths.filter((p) => readable.get(p) === true);
+      const downloadable = await accessControl.canDownloadBatch(id, user.email, visible);
+      const kept = new Set(visible.filter((p) => downloadable.get(p) === true));
+      withheld = visible.length - kept.size;
+      return kept;
+    };
     try {
-      const buffer = await workspaceService.createFolderZip(id, folderPath);
+      const buffer = await workspaceService.createFolderZip(id, folderPath, include);
+      res.setHeader('X-Withheld-Files', String(withheld));
+      // One caller's archive: which files it holds, and the count beside it,
+      // are that caller's verdicts. `private` keeps a shared cache from
+      // handing it to the next caller; `no-store` because, unlike the single
+      // file, nothing here can be revalidated (no ETag), so a copy is never
+      // worth keeping.
+      res.setHeader('Cache-Control', 'private, no-store');
       // `|| 'folder'` covers the edge case where `folderPath` itself was
       // a single bare slash (`/`) that survived the trim — the service
       // would still reject it as path traversal, but the basename
@@ -999,7 +1019,11 @@ export function createWorkspaceRoutes(
         res.status(413).json({ error: error.message });
         return;
       }
-      if (error instanceof PathTraversalError) {
+      // A traversal refusal (`PathTraversalError`), or the access tree failing
+      // to load while the entries were judged (`AccessConfigError`): both are
+      // domain errors carrying their own status and payload, the same ones
+      // the single-file gate answers with.
+      if (error instanceof WorkflowDomainError) {
         sendError(res, error);
         return;
       }
@@ -1098,6 +1122,16 @@ export function createWorkspaceRoutes(
         // Not on disk — let workspaceService.deleteFile return its own 404.
       }
       if (stat?.isDirectory()) {
+        // A platform folder — the repository root, whose sweep would take the
+        // root's `access.md` and `roles.yaml` with it, or one of the reserved
+        // top-level folders that hold a whole section of the knowledge base —
+        // is refused here as `delete_folder` refuses it, by the same rule.
+        const trimmedFolder = filePath.replace(/\/+$/, '');
+        const folderRel = trimmedFolder === kbDirName ? '' : toKbRelative(trimmedFolder, kbDirName);
+        if (folderRel !== null && isPlatformFolder(folderRel, kb.layout)) {
+          res.status(409).json({ error: platformFolderRefusal(folderRel) });
+          return;
+        }
         const branch = branchForWorkspaceId(id);
         // In the folder's turn: keeping a folder under this one (a file delete
         // racing this one) waits until the sweep is done, and then finds the
@@ -1166,6 +1200,14 @@ export function createWorkspaceRoutes(
         res.json({ status: 'deleted', count: filesInDir.length });
         return;
       }
+      // The root's `access.md` and `roles.yaml` govern the whole repository:
+      // nobody deletes them, here or through the agent tools. A nested
+      // `access.md` is deleted like any file its caller may write.
+      const rel = toKbRelative(filePath, kbDirName);
+      if (rel !== null && isRepositoryOwnFile(rel, kb.layout)) {
+        res.status(409).json({ error: repositoryOwnFileDeleteRefusal(rel) });
+        return;
+      }
       await withLock(id, user, filePath, () => workspaceService.deleteFile(id, filePath));
       // Deleting content is not deleting structure: an emptied folder stays.
       await keepFolderOf(id, user, filePath);

package/src/modules/workspace/workspace.service.ts

@@ -13,13 +13,14 @@ import {
   entryExistsMessage,
   type ExistingEntryKind,
 } from '@bevel-software/platform-shared';
-import { isAbsence, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
+import { isAbsence, type IgnoreRules, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
+import { BevelIgnoreStack } from '../kb-fs/bevel-ignore.js';
 import {
   DestinationTakenError,
   inspectDestination,
   renameNoReplace,
 } from '../../shared/rename-no-replace.js';
-import type { IGitRunner } from '../../shared/git.contract.js';
+import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
@@ -47,6 +48,7 @@ import { setAsideClone, setAsideRootFor, setAsideStamp } from './set-aside-clone
 import {
   cloneCredentialArgs,
   cloneCredentialConfigArgs,
+  credentialHelperValue,
   cloneTrackingConfigArgs,
   SAFE_IMPLICIT_FETCH_ARGS,
 } from '../kb-fs/clone-config.js';
@@ -98,7 +100,20 @@ const UNZIP_MAX_TOTAL_BYTES = 500 * 1024 * 1024; // 500 MB across the whole arch
 // Folder-download cap. The whole zip is built in memory by adm-zip (no
 // streaming) so the cap also bounds peak heap usage for one download.
 // Reuses the unzip total as a single "fits in a workspace" budget.
-const ZIP_DOWNLOAD_MAX_BYTES = UNZIP_MAX_TOTAL_BYTES;
+export const ZIP_DOWNLOAD_MAX_BYTES = UNZIP_MAX_TOTAL_BYTES;
+
+// How many files one agent download request may carry: what one zip may hold
+// for `apply_file_upload` to unzip it back, and a bound on the lists a
+// request builds before anything is judged.
+export const DOWNLOAD_MAX_FILES = UNZIP_MAX_ENTRIES;
+
+/**
+ * Which of a folder's files a zip may pack: handed every file the walk found
+ * (repository-relative, POSIX separators), answers the set to include. The
+ * route builds one from the caller's `read` and `download` verdicts — see
+ * `createFolderZip` for why it is required.
+ */
+export type ZipEntryFilter = (repoRelativePaths: string[]) => Promise<ReadonlySet<string>>;
 
 /**
  * Thrown by `createFolderZip` when the cumulative uncompressed bytes exceed
@@ -429,6 +444,50 @@ export class WorkspaceService implements IWorkspaceService {
     }
   }
 
+  /**
+   * Does `branch` certainly not exist? Asked by the tool handler before a tool
+   * runs, so a call naming a branch nobody ever pushed is answered 404 without
+   * a workspace being created for it.
+   *
+   * Never clones and never creates a directory. A branch this platform has a
+   * clone of, is cloning, or has ever heard of is NOT missing: one that origin
+   * has since deleted is left to the open, which answers its 410. Anything
+   * else is asked of origin with `ls-remote`, and only origin's "no such ref"
+   * makes it missing. A name that is malformed, or a remote that could not be
+   * asked, is `false` too: the open then answers for it, exactly as before.
+   * A storage fault reading what this platform has heard of is NOT read as
+   * either answer: it propagates, the 500 the operator reads.
+   */
+  async isBranchMissing(branch: string): Promise<boolean> {
+    try {
+      assertValidBranchName(branch);
+    } catch {
+      return false;
+    }
+    if (this.branchDirs.has(branch) || this.inFlightBootstraps.has(branch)) return false;
+    if (await this.hasHeardOfBranch(branch)) return false;
+    const helper = credentialHelperValue(this.gitRunner.credentials);
+    try {
+      const { stdout } = await this.gitRunner.run(this.workspacesRoot, [
+        ...(helper ? ['-c', `credential.helper=${helper}`] : []),
+        'ls-remote',
+        '--exit-code',
+        '--heads',
+        '--end-of-options',
+        this.kbRepoUrl(),
+        `refs/heads/${branch}`,
+      ]);
+      // The argument is a PATTERN, matched at any slash boundary: it also
+      // lists `refs/heads/refs/heads/<branch>`. Only the exact ref counts.
+      const ref = `refs/heads/${branch}`;
+      return !stdout.split('\n').some((line) => line.split('\t')[1]?.trim() === ref);
+    } catch (err) {
+      // `--exit-code`: 2 is "the remote answered, and has no matching ref".
+      // Every other failure is a remote we could not ask.
+      return err instanceof GitRunError && err.exitCode === 2;
+    }
+  }
+
   /**
    * Build git clone args. Credentials go in as `clone --config`, which both
    * authenticates this clone and leaves the helper in the new repo's config for
@@ -1309,6 +1368,25 @@ export class WorkspaceService implements IWorkspaceService {
     return fs.readFile(absolutePath);
   }
 
+  /**
+   * Whether a FILE is at `wsPath` — the same guards as a read, without the
+   * read: for a caller that only has to know the file is there (the embed
+   * mint), on a file that may be hundreds of megabytes.
+   */
+  async isFile(workspaceId: string, wsPath: string): Promise<boolean> {
+    const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+    assertNoGitInternalsSegment(relativePath);
+    await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+    await this.assertNotThroughLink(absolutePath, workspaceDir);
+    try {
+      return (await fs.stat(absolutePath)).isFile();
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') return false;
+      throw err;
+    }
+  }
+
   /**
    * Refuse a path that reaches its file through a symbolic link — as the
    * final component, or as any directory between the workspace root and it.
@@ -1406,7 +1484,23 @@ export class WorkspaceService implements IWorkspaceService {
    * size crosses `ZIP_DOWNLOAD_MAX_BYTES`. Buffered in memory (adm-zip has
    * no streaming API); the cap therefore doubles as a peak-heap bound.
    */
-  async createFolderZip(workspaceId: string, wsPath: string): Promise<Buffer> {
+  /**
+   * Zip a folder. `include` is asked, ONCE, which of the folder's files may
+   * go in: it is handed every file the walk found, as repository-relative
+   * paths, and answers the set to pack. Required, not optional, and with no
+   * default that packs everything: the route used to gate `download` on the
+   * folder alone and pack every file under it, so a caller with `download`
+   * on a folder got files whose own rules (frontmatter, a nested access.md)
+   * denied them `read` or `download` — files the per-file route refused and
+   * the file tree never showed. A caller that wants everything says so by
+   * returning everything; it cannot get it by saying nothing.
+   *
+   * Two passes rather than a judgement per file inside the walk: the access
+   * model answers a list in one load, and a folder of a thousand files is
+   * the case a per-file call would make slow. The size cap counts only the
+   * files packed; a withheld file costs nothing and reveals nothing.
+   */
+  async createFolderZip(workspaceId: string, wsPath: string, include: ZipEntryFilter): Promise<Buffer> {
     const { workspaceDir, relativePath, absolutePath: absoluteRoot } = await this.resolveInsideRepo(workspaceId, wsPath);
     assertNoGitInternalsSegment(relativePath);
     await assertNotGitInternals(workspaceDir, relativePath, absoluteRoot);
@@ -1415,36 +1509,101 @@ export class WorkspaceService implements IWorkspaceService {
       throw new Error('Not a directory');
     }
 
+    // `relativePath` is workspace-relative, `<kbDirName>/<folder>`; the
+    // access rules are keyed inside the repository, so the prefix comes off
+    // here (and the repository root itself is the empty prefix).
+    // A trailing slash the caller wrote (`docs/`) survives normalisation and
+    // would key every file as `docs//x.md`, which no verdict matches: the
+    // filter would then withhold the whole folder in silence.
+    const folderInRepo = (relativePath === this.kbDirName ? '' : relativePath.slice(this.kbDirName.length + 1)).replace(/\/+$/, '');
+    const found: { dir: string; name: string; repoRelative: string }[] = [];
+    await this.disk.walk(absoluteRoot, explorerWalk(), [
+      {
+        async onFile(dir, name) {
+          found.push({ dir, name, repoRelative: [folderInRepo, dir, name].filter(Boolean).join('/') });
+        },
+      },
+    ]);
+    const allowed = await include(found.map((f) => f.repoRelative));
+
     const zipRoot = path.basename(absoluteRoot) || 'folder';
     const zip = new AdmZip();
     let totalBytes = 0;
+    for (const { dir, name, repoRelative } of found) {
+      if (!allowed.has(repoRelative)) continue;
+      const childAbs = path.join(absoluteRoot, dir, name);
+      // Check the size cap BEFORE reading the file into memory. Reading
+      // first would let a single hostile 2 GB file allocate the whole
+      // buffer before the throw — defeating the cap as a peak-heap
+      // bound. `stat.size` is an upper bound that we re-verify after
+      // the read in case the file grew between stat and readFile.
+      const stat = await fs.stat(childAbs);
+      if (totalBytes + stat.size > ZIP_DOWNLOAD_MAX_BYTES) {
+        throw new FolderTooLargeError(ZIP_DOWNLOAD_MAX_BYTES);
+      }
+      const data = await fs.readFile(childAbs);
+      if (totalBytes + data.byteLength > ZIP_DOWNLOAD_MAX_BYTES) {
+        throw new FolderTooLargeError(ZIP_DOWNLOAD_MAX_BYTES);
+      }
+      totalBytes += data.byteLength;
+      // Path inside the archive: <folderName>/<relPathUnderFolder>, POSIX
+      // separators regardless of host OS so the zip extracts cleanly
+      // on Windows/Mac/Linux alike.
+      zip.addFile(`${zipRoot}/${dir ? `${dir}/${name}` : name}`, data);
+    }
+    return zip.toBuffer();
+  }
 
-    await this.disk.walk(absoluteRoot, explorerWalk(), [
+  /**
+   * What is at `wsPath`, for an agent download: nothing, one file, or a folder
+   * and every file the explorer shows under it (the folder download's walk —
+   * no `.git/`, no `.gitkeep`, no `.bevelignore`d path, no link). Files come
+   * back repository-relative, with their size on disk; nothing is read, and
+   * nothing is judged — the caller judges every path on its own.
+   *
+   * The `.bevelignore` rules are those in force at the folder, its ancestors'
+   * included, as the explorer's walk from the root has them: a folder an
+   * ancestor's rule hides holds no files. The whole folder is walked, as the
+   * explorer walks it: a cap here would be a cap on files the caller may not
+   * read as much as on the ones they may, and the limit a request is held to
+   * is the caller's own count, judged after the read verdicts.
+   *
+   * A path that reaches its target through a link, or names the git folder,
+   * is refused as the reads refuse it; a path with nothing at it is
+   * `missing`, which the caller answers exactly as a path it may not read.
+   */
+  async downloadCandidatesAt(
+    workspaceId: string,
+    wsPath: string,
+  ): Promise<{ kind: 'missing' } | { kind: 'file' | 'folder'; files: { path: string; bytes: number }[] }> {
+    const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+    assertNoGitInternalsSegment(relativePath);
+    await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+    await this.assertNotThroughLink(absolutePath, workspaceDir);
+    let stat;
+    try {
+      stat = await fs.lstat(absolutePath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT' || (err as NodeJS.ErrnoException).code === 'ENOTDIR') {
+        return { kind: 'missing' };
+      }
+      throw err;
+    }
+    const inRepo = (relativePath === this.kbDirName ? '' : relativePath.slice(this.kbDirName.length + 1)).replace(/\/+$/, '');
+    if (stat.isFile()) return { kind: 'file', files: [{ path: inRepo, bytes: stat.size }] };
+    if (!stat.isDirectory()) return { kind: 'missing' };
+    const files: { path: string; bytes: number }[] = [];
+    const rules = await ignoreRulesAbove(path.join(workspaceDir, this.kbDirName), inRepo);
+    if (!rules) return { kind: 'folder', files };
+    await this.disk.walk(absolutePath, { ...explorerWalk(), ignore: rules }, [
       {
         async onFile(dir, name) {
-          const childAbs = path.join(absoluteRoot, dir, name);
-          // Check the size cap BEFORE reading the file into memory. Reading
-          // first would let a single hostile 2 GB file allocate the whole
-          // buffer before the throw — defeating the cap as a peak-heap
-          // bound. `stat.size` is an upper bound that we re-verify after
-          // the read in case the file grew between stat and readFile.
-          const stat = await fs.stat(childAbs);
-          if (totalBytes + stat.size > ZIP_DOWNLOAD_MAX_BYTES) {
-            throw new FolderTooLargeError(ZIP_DOWNLOAD_MAX_BYTES);
-          }
-          const data = await fs.readFile(childAbs);
-          if (totalBytes + data.byteLength > ZIP_DOWNLOAD_MAX_BYTES) {
-            throw new FolderTooLargeError(ZIP_DOWNLOAD_MAX_BYTES);
-          }
-          totalBytes += data.byteLength;
-          // Path inside the archive: <folderName>/<relPathUnderFolder>, POSIX
-          // separators regardless of host OS so the zip extracts cleanly
-          // on Windows/Mac/Linux alike.
-          zip.addFile(`${zipRoot}/${dir ? `${dir}/${name}` : name}`, data);
+          const size = (await fs.lstat(path.join(absolutePath, dir, name))).size;
+          files.push({ path: [inRepo, dir, name].filter(Boolean).join('/'), bytes: size });
         },
       },
     ]);
-    return zip.toBuffer();
+    return { kind: 'folder', files };
   }
 
   /**
@@ -2514,6 +2673,24 @@ export class WorkspaceService implements IWorkspaceService {
   }
 }
 
+/**
+ * The `.bevelignore` rules in force ABOVE the folder `inRepo` (repository-
+ * relative, `''` for the root) — the root's file and every ancestor's, not
+ * the folder's own, which a walk from the folder layers itself — or null when
+ * one of those rules hides the folder or an ancestor, as the explorer's walk
+ * from the root would never enter it.
+ */
+async function ignoreRulesAbove(repoRoot: string, inRepo: string): Promise<IgnoreRules | null> {
+  let rules: IgnoreRules = BevelIgnoreStack.empty();
+  let dir = repoRoot;
+  for (const segment of inRepo.split('/').filter(Boolean)) {
+    rules = await rules.extendedWith(dir);
+    dir = path.join(dir, segment);
+    if (rules.isIgnored(dir, true)) return null;
+  }
+  return rules;
+}
+
 /**
  * The explorer's walk of a workspace: no git internals (never user content,
  * and listing it would blow up the tree), no `.gitkeep` (the empty-folder