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

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