@bevel-software/platform-core-backend 0.23.0 → 0.25.0

package/src/modules/workspace/startup/steps/__tests__/steps.test.ts

@@ -18,12 +18,9 @@ import { mergeGroupsIntoRoles, parseRolesYaml } from '../../../../access-model/a
 import { TemplateFilesStep } from '../template-files.step.js';
 import { buildSeedTree } from '../seed-tree.js';
 import { defaultKbTemplateDir } from '../../../../../assets.js';
-import {
-  DEFAULT_KB_LAYOUT,
-  agentsFilePointerSentence,
-  renderKbLayoutPlaceholders,
-} from '@bevel-software/platform-shared';
-import { PLATFORM_HEADER, TOOL_PREFIX_LINE, composeAgentInstructions } from '../../../../agent-instructions/index.js';
+import { DEFAULT_KB_LAYOUT, agentsFilePointerSentence } from '@bevel-software/platform-shared';
+import { renderTemplateText } from '../template-source.js';
+import { TOOL_PREFIX_LINE, composeAgentInstructions, platformInstructions } from '../../../../agent-instructions/index.js';
 import { testKbContext } from '../../../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
@@ -148,7 +145,10 @@ const PREAMBLE_IGNORE_BLOCK =
 
 /** The template as the step writes it under the default layout — placeholders rendered. */
 async function template(name: string): Promise<string> {
-  return renderKbLayoutPlaceholders(await fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8'), DEFAULT_KB_LAYOUT);
+  // `renderTemplateText`, not the layout renderer alone: the managed guide also
+  // asks for the shared file rules, and a fixture rendered with half the
+  // placeholders filled would read as drifted on every boot.
+  return renderTemplateText(await fs.readFile(path.join(TEMPLATE_DIR, name), 'utf8'), DEFAULT_KB_LAYOUT);
 }
 
 /** Every required file + reserved root already present, from the real template. */
@@ -695,7 +695,7 @@ describe('TemplateFilesStep', () => {
     expect((await git(dir, ['rev-list', '--count', 'HEAD'])).trim()).toBe('1');
   });
 
-  it('ships a template that composes to the platform header alone: one comment, nothing broadcast', async () => {
+  it('ships a template that composes to the platform text alone: one comment, nothing broadcast', async () => {
     const shipped = await template('mcp-description.md');
     expect(shipped.trimStart().startsWith('<!--')).toBe(true);
     expect(shipped.trimEnd().endsWith('-->')).toBe(true);
@@ -705,7 +705,7 @@ describe('TemplateFilesStep', () => {
     expect(shipped).toContain('first paragraph under about 220');
     expect(shipped).not.toContain('{{');
     const composed = composeAgentInstructions(shipped);
-    expect(composed.instructions).toBe(PLATFORM_HEADER);
+    expect(composed.instructions).toBe(platformInstructions(DEFAULT_KB_LAYOUT));
     expect(composed.toolPrefix).toBe(TOOL_PREFIX_LINE);
     expect(composed.unterminatedComment).toBe(false);
     expect(composed.preambleChars).toBe(0);

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -1,14 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import {
-  LEGACY_AGENTS_FILE,
-  renderKbLayoutPlaceholders,
-} from '@bevel-software/platform-shared';
+import { LEGACY_AGENTS_FILE } from '@bevel-software/platform-shared';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
 import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
 import { reservedRootDirs } from './template-files.step.js';
-import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource } from './template-source.js';
+import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource, renderTemplateText } from './template-source.js';
 import { assertNotGitInternals, hasGitInternalsSegment } from '../../../../shared/git-internals.js';
 import { GitInternalsError } from '../../../../shared/domain-errors.js';
 
@@ -192,7 +189,7 @@ class KbSeedTree {
     if (text === null) {
       await fs.copyFile(from, to);
     } else {
-      await fs.writeFile(to, renderKbLayoutPlaceholders(text, this.kb.layout), 'utf8');
+      await fs.writeFile(to, renderTemplateText(text, this.kb.layout), 'utf8');
     }
     await fs.chmod(to, (await fs.stat(from)).mode & 0o777);
   }

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

@@ -1,8 +1,10 @@
 import path from 'node:path';
-import { gitignoreLiteral, renderKbLayoutPlaceholders } from '@bevel-software/platform-shared';
+import { gitignoreLiteral, renderKbLayoutPlaceholders, type KbLayout } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type EntryStat, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
+
 import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
+import { sharedFileRulesSection } from '../../../agent-instructions/shared-file-rules.js';
 import { defaultKbTemplateDir } from '../../../../assets.js';
 import { logger } from '../../../../shared/logging.js';
 
@@ -37,6 +39,42 @@ export const TEMPLATE_SOURCE_FALLBACKS: ReadonlyMap<string, string> = new Map([
   ['.gitignore', 'gitignore.template'],
 ]);
 
+/**
+ * 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.
+ */
+export const SHARED_FILE_RULES_PLACEHOLDER = '{{sharedFileRules}}';
+
+/**
+ * Every placeholder a template file carries, filled: the layout's names on the
+ * text an author wrote, THEN the shared file rules dropped into the hole they
+ * left. ONE function, because the two writers of template content — the top-up
+ * step through {@link TemplateSource.read} and the empty-remote seeder, which
+ * streams files itself — must render identically or a freshly seeded knowledge
+ * base would carry a guide with a literal `{{sharedFileRules}}` in it.
+ *
+ * THAT ORDER, not the other one: the rules are already rendered for this
+ * layout (`sharedFileRulesSection` takes it), so running the layout renderer
+ * over them again would only reach text they STATE rather than contain — a
+ * folder a deployment really named `{{skillsDir}}` would come back as some
+ * other folder's name, and the rule would then point at a folder that is not
+ * the one it refuses a move out of. Injecting last leaves the section byte for
+ * byte what both channels carry, and costs nothing:
+ * `renderKbLayoutPlaceholders` touches only its own four tokens, so the
+ * placeholder for the rules survives the first pass untouched.
+ *
+ * A replacer FUNCTION for the rules: they carry dollar sequences (a `${VAR}`
+ * a template writes) that a string replacement would read as capture-group
+ * syntax.
+ */
+export function renderTemplateText(text: string, layout: KbLayout): string {
+  return renderKbLayoutPlaceholders(text, layout).replaceAll(
+    SHARED_FILE_RULES_PLACEHOLDER,
+    () => sharedFileRulesSection(layout),
+  );
+}
+
 /**
  * ONE template directory, read through ONE disk port — what both readers of
  * the KB template share.
@@ -112,6 +150,16 @@ export class TemplateSource {
    * placeholders the template carries (`{{pluginsDir}}` …) are filled with
    * the names in effect. Every required file is text; a template without
    * placeholders passes through unchanged.
+   *
+   * `{{sharedFileRules}}` is filled from the ONE source text the MCP handshake
+   * also sends (see `shared-file-rules.ts`), so the rules every file tool
+   * shares are stated in the guide and in the instructions without being
+   * written twice. Filled AFTER the layout pass (see
+   * {@link renderTemplateText}): the rules come back already rendered for this
+   * layout, so a layout pass over them could only misread a name they STATE as
+   * a placeholder. The two passes do not collide — the layout renderer touches
+   * only its own four tokens, so `{{sharedFileRules}}` reaches the second pass
+   * untouched.
    */
   async read(relPath: string): Promise<string> {
     let raw: string;
@@ -134,13 +182,13 @@ export class TemplateSource {
     // reads as syntax (`#Guide.md`, `!Guide.md`, brackets) would hide nothing
     // written bare. Escaped there, and only there: everywhere else the
     // placeholder is prose. ONE render, with the escaped name as the layout's
-    // — a second pass over the rendered text would read a name that happens
-    // to contain a placeholder as one.
+    // — rendering twice over text already rendered would read a name that
+    // happens to contain a placeholder as one.
     const layout = this.kb.layout;
     if (relPath === IGNORE_FILENAME) {
-      return renderKbLayoutPlaceholders(raw, { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) });
+      return renderTemplateText(raw, { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) });
     }
-    return renderKbLayoutPlaceholders(raw, layout);
+    return renderTemplateText(raw, layout);
   }
 
   /**

package/src/modules/workspace/upload-limits.ts

@@ -0,0 +1,12 @@
+/**
+ * The deployment's own upload ceiling, in bytes.
+ *
+ * ONE number for every surface that accepts bytes: the app's
+ * `POST /workspace/:id/upload` (a person dropping a file in the explorer) and
+ * the agent upload route (`POST /agent/uploads/:token`). They used to be the
+ * same number written twice, which is the shape a limit drifts in — an agent
+ * refused at 50 MB by one route and accepted by the other would have no way to
+ * read which limit applied. The refusal NAMES this value, so a caller can size
+ * its next attempt from the answer rather than by bisection.
+ */
+export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB

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

@@ -38,8 +38,7 @@ import { createGitInternalsRouteGuard } from './git-internals.middleware.js';
 import { removeEmptyDirs } from './empty-dirs.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 import type { SkillSaveCheck } from './workspace.tools.js';
-
-const MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
+import { MAX_UPLOAD_BYTES } from './upload-limits.js';
 
 /**
  * One file identity from one request field, or `null` when the caller sent

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

@@ -8,7 +8,6 @@ import type { AuthUser, IWorkspaceService, WorkspaceInfo, FileTreeEntry } from '
 import { AsyncLocalStorage } from 'node:async_hooks';
 import {
   validateRelativePath,
-  validateFilename,
   FOLDER_PLACEHOLDER,
   isFolderPlaceholder,
   entryExistsMessage,
@@ -26,6 +25,7 @@ import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
 import { assertRepoRootNameFree, normalizeWorkspacePath } from '../kb-fs/repo-path.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { isZipNoiseEntry, readZipEntry, zipEntryName, zipEntryNameRefusal, zipEntrySegments } from './zip-entry-rules.js';
 import {
   GitInternalsError,
   PathNotFoundError,
@@ -495,6 +495,19 @@ export class WorkspaceService implements IWorkspaceService {
    * a conventional default branch isn't on the remote) just to run a global op.
    * Scans disk rather than the in-memory `branchDirs` map so clones that
    * survived a process restart are still found.
+   *
+   * INTERCHANGEABLE ONLY ONCE IT CAN REACH THE REMOTE. The clone handed back
+   * is one this process may never have opened, and opening a branch is the
+   * only other place a clone's credential helper is brought into line with the
+   * deployment's (`getOrCreateForBranch`). A clone made before the helper was
+   * persisted, or before a token was configured, has none — and it is exactly
+   * the kind that sorts first on disk, because it is old. Every repo-global
+   * operation then ran its fetches in a working copy that could not
+   * authenticate: the fetch failed, quietly, and each change request whose
+   * branch that clone had never seen was reported as `unknown branch`, list
+   * after list, while the branches sat on the remote. So the helper is stamped
+   * here too, before the clone is offered. A no-op for a clone already stamped
+   * in this process, and it never throws (see `stampCredentialHelper`).
    */
   async findAnyWorkspaceId(): Promise<string | null> {
     let entries: Array<{ name: string; isDirectory: () => boolean }>;
@@ -505,12 +518,15 @@ export class WorkspaceService implements IWorkspaceService {
     }
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
+      const repoDir = path.join(this.workspacesRoot, entry.name, this.kbDirName);
       try {
-        await fs.access(path.join(this.workspacesRoot, entry.name, this.kbDirName, '.git'));
-        return entry.name;
+        await fs.access(path.join(repoDir, '.git'));
       } catch {
         // No `.git` — half-built or unrelated dir; keep looking.
+        continue;
       }
+      await this.refreshCredentialHelperIfStale(branchForWorkspaceId(entry.name), repoDir);
+      return entry.name;
     }
     return null;
   }
@@ -688,6 +704,15 @@ export class WorkspaceService implements IWorkspaceService {
       const startedMeanwhile = this.inFlightSetAsides.get(branch);
       if (startedMeanwhile) {
         await startedMeanwhile;
+      } else if (this.discardsOf(id) !== discardsAtAdoption) {
+        // The copy whose address this call read is no longer there: a move
+        // began AND ended while it was being read. An in-flight entry is
+        // cleared the moment its move ends, so a caller that comes back after
+        // that finds nobody to wait for — and its answer is about a copy that
+        // has already been set aside. Acting on it would set aside whatever is
+        // at this path NOW, which is the fresh clone the first caller is in
+        // the middle of making. Nothing is left to move; the bootstrap below
+        // waits for that clone.
       } else {
         const kept = path.join(setAsideRootFor(this.workspacesRoot, this.setAsideRoot), setAsideStamp(), id);
         // What surrounds the move may wait, and the startup phase may set
@@ -698,6 +723,11 @@ export class WorkspaceService implements IWorkspaceService {
           if (this.discardsOf(id) !== discardsAtAdoption) return;
           await setAsideClone(repoDir, kept);
           moved = true;
+          // Said the way the startup phase says it: the copy at this path was
+          // taken away. That is what the check above reads, so every caller
+          // that looked at the old copy before this line knows its answer is
+          // stale, however late it comes back.
+          this.forgetClone(id);
         }).finally(() => {
           this.inFlightSetAsides.delete(branch);
         });
@@ -1997,43 +2027,22 @@ export class WorkspaceService implements IWorkspaceService {
         continue;
       }
       processedCount++;
-      const rawName = entry.entryName.replace(/\\/g, '/');
-
-      if (
-        rawName.startsWith('__MACOSX/') ||
-        rawName === '__MACOSX' ||
-        rawName.endsWith('/.DS_Store') ||
-        rawName === '.DS_Store' ||
-        /(^|\/)\._/.test(rawName)
-      ) {
-        continue;
-      }
+      const rawName = zipEntryName(entry.entryName);
 
-      if (!rawName || rawName.startsWith('/') || /(^|\/)\.\.($|\/)/.test(rawName)) {
-        skipped.push({ path: rawName || '(empty)', reason: 'Invalid path' });
-        continue;
-      }
+      if (isZipNoiseEntry(rawName)) continue;
 
-      // An archive never writes into the git folder, whatever the entry's spelling.
-      if (hasGitInternalsSegment(rawName)) {
-        skipped.push({ path: rawName, reason: new GitInternalsError().message });
+      // What an entry's NAME may be — invalid path, the git folder in any
+      // spelling, a segment no filesystem keeps intact — is `zip-entry-rules`,
+      // so `apply_file_upload` judges the same names by the same rules rather
+      // than by a second copy of them.
+      const nameRefusal = zipEntryNameRefusal(rawName);
+      if (nameRefusal !== null) {
+        skipped.push({ path: rawName || '(empty)', reason: nameRefusal });
         continue;
       }
 
       const trimmed = rawName.replace(/\/+$/, '');
-      const segments = trimmed.split('/').filter((s) => s.length > 0);
-      let invalidReason: string | null = null;
-      for (const segment of segments) {
-        const reason = validateFilename(segment);
-        if (reason) {
-          invalidReason = reason;
-          break;
-        }
-      }
-      if (invalidReason) {
-        skipped.push({ path: rawName, reason: invalidReason });
-        continue;
-      }
+      const segments = zipEntrySegments(rawName);
 
       const targetAbsolute = path.resolve(destAbsolute, ...segments);
       const destRoot = path.resolve(destAbsolute);
@@ -2114,14 +2123,31 @@ export class WorkspaceService implements IWorkspaceService {
         continue;
       }
 
-      const data = entry.getData();
-      if (data.byteLength > UNZIP_MAX_ENTRY_BYTES) {
+      // Read through the one bounded reader (`readZipEntry`), never with the
+      // declared size above as the only bound: an entry that declares ZERO is
+      // inflated with no cap at all by the archive reader, so a few kilobytes
+      // could expand to whatever memory there is before the checks below ran.
+      // Capped at what is left of both limits, and a read that fails is this
+      // entry's refusal rather than the whole archive's.
+      const read = readZipEntry(
+        entry,
+        Math.min(UNZIP_MAX_ENTRY_BYTES, UNZIP_MAX_TOTAL_BYTES - totalUncompressed),
+      );
+      if (!read.ok && read.reason === 'unreadable') {
+        skipped.push({ path: rawName, reason: `Entry could not be read: ${read.detail}` });
+        continue;
+      }
+      if (!read.ok) {
         skipped.push({
           path: rawName,
-          reason: `Entry exceeds ${UNZIP_MAX_ENTRY_BYTES} byte per-file limit`,
+          reason:
+            totalUncompressed + UNZIP_MAX_ENTRY_BYTES > UNZIP_MAX_TOTAL_BYTES
+              ? `Archive exceeds ${UNZIP_MAX_TOTAL_BYTES} byte total uncompressed limit`
+              : `Entry exceeds ${UNZIP_MAX_ENTRY_BYTES} byte per-file limit`,
         });
         continue;
       }
+      const data = read.data;
       if (totalUncompressed + data.byteLength > UNZIP_MAX_TOTAL_BYTES) {
         skipped.push({
           path: rawName,