@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/dist/modules/workspace/file-readers/text-reader.js

@@ -1,7 +1,12 @@
 import { isUtf8 } from 'node:buffer';
 import { fileExtension } from './doc-extract.types.js';
 import { displayPath } from './file-reader.js';
-/** Minimal extension→mime map for the binary-read notice (fallback: octet-stream). */
+/**
+ * Extension→mime for the binary-read notice and for the `mime` `file_stat`
+ * reports (fallback: octet-stream, or text/plain for sniffed text). Every
+ * extension a reader registers must name its mime here or in that reader's
+ * own `mimeFor` — the registry test enforces it.
+ */
 const MIME_BY_EXT = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -10,8 +15,13 @@ const MIME_BY_EXT = {
     '.webp': 'image/webp',
     '.bmp': 'image/bmp',
     '.ico': 'image/x-icon',
+    '.tif': 'image/tiff',
+    '.tiff': 'image/tiff',
+    '.heic': 'image/heic',
+    '.avif': 'image/avif',
     '.zip': 'application/zip',
     '.gz': 'application/gzip',
+    '.tgz': 'application/gzip',
     '.tar': 'application/x-tar',
     '.7z': 'application/x-7z-compressed',
     '.rar': 'application/vnd.rar',
@@ -20,15 +30,35 @@ const MIME_BY_EXT = {
     '.xls': 'application/vnd.ms-excel',
     '.mp3': 'audio/mpeg',
     '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.m4a': 'audio/mp4',
     '.mp4': 'video/mp4',
     '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
     '.woff': 'font/woff',
     '.woff2': 'font/woff2',
     '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
     '.pdf': 'application/pdf',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.odt': 'application/vnd.oasis.opendocument.text',
+    '.odp': 'application/vnd.oasis.opendocument.presentation',
+    '.ods': 'application/vnd.oasis.opendocument.spreadsheet',
+    '.eml': 'message/rfc822',
+    '.msg': 'application/vnd.ms-outlook',
     '.wasm': 'application/wasm',
     '.exe': 'application/vnd.microsoft.portable-executable',
+    '.dll': 'application/vnd.microsoft.portable-executable',
+    '.so': 'application/x-sharedlib',
+    // `.bin` itself names raw bytes: an extension-given type, not the fallback.
+    '.bin': 'application/octet-stream',
 };
+/** The mime `path`'s extension names, or undefined when the table has none. */
+export function extensionMime(path) {
+    return MIME_BY_EXT[fileExtension(path)];
+}
 /**
  * Text is what the fallback reader may hand to the text tools: no NUL byte
  * AND valid UTF-8. A NUL-free file that does not decode as UTF-8 is still
@@ -36,7 +66,7 @@ const MIME_BY_EXT = {
  * round-trip the original bytes. Checked on the raw bytes, so a large binary
  * is refused without allocating its full decoded string first.
  */
-function isTextBytes(bytes) {
+export function isTextBytes(bytes) {
     return !bytes.includes(0) && isUtf8(bytes);
 }
 /**
@@ -52,6 +82,7 @@ export class TextReader {
     /** Fallback reader: matched by the registry's default, not by extension. */
     extensions = [];
     textEditable = true;
+    fileKind = 'text';
     async read(bytes, path) {
         return isTextBytes(bytes)
             ? { kind: 'text', text: bytes.toString('utf8') }
@@ -73,10 +104,13 @@ export class TextReader {
     async greppableText(bytes) {
         return isTextBytes(bytes) ? bytes.toString('utf8') : null; // skip binary (NUL / invalid UTF-8)
     }
+    mimeFor(path) {
+        return extensionMime(path);
+    }
     /** The honest one-line notice returned INSTEAD of raw bytes for unreadable binary content. */
     binaryNotice(path, sizeBytes) {
         const ext = fileExtension(path);
-        const mime = MIME_BY_EXT[ext] ?? 'application/octet-stream';
+        const mime = extensionMime(path) ?? 'application/octet-stream';
         const zipHint = ext === '.zip' ? ' Use the unzip tool to extract its contents.' : '';
         return `[${displayPath(path)} is a binary file (${mime}, ${sizeBytes} bytes) — not readable as text.${zipHint}]`;
     }
@@ -98,6 +132,7 @@ const MODERN_BY_LEGACY = { '.doc': '.docx', '.ppt': '.pptx', '.xls': '.xlsx' };
 export class LegacyOfficeReader extends TextReader {
     extensions = ['.doc', '.ppt', '.xls'];
     textEditable = false;
+    fileKind = 'document';
     /** The write-refusal for the agent text-editing tools (see `assertNotDocumentEdit`). */
     editRefusal(path) {
         const ext = fileExtension(path);
@@ -114,4 +149,23 @@ export class LegacyOfficeReader extends TextReader {
             'uploading a new version.]');
     }
 }
+/**
+ * Extensions that name bytes no text tool may produce: archives, media, fonts,
+ * executables, and the image formats read_file does not return as pictures.
+ * Reads and greps stay the text reader's (a mislabeled `.zip` that holds text
+ * still reads as text, and binary content still gets the one-line notice), but
+ * the write tools refuse them by name — text written to `bundle.zip` can only
+ * ever be a broken archive. Bytes of these kinds arrive through upload, or
+ * travel with copy_file/move_file.
+ */
+export class BinaryReader extends TextReader {
+    extensions;
+    fileKind;
+    textEditable = false;
+    constructor(extensions, fileKind) {
+        super();
+        this.extensions = extensions;
+        this.fileKind = fileKind;
+    }
+}
 //# sourceMappingURL=text-reader.js.map

package/dist/modules/workspace/file-readers/text-reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"text-reader.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/text-reader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"text-reader.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/text-reader.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/git-internals.middleware.d.ts

@@ -0,0 +1,28 @@
+import express from 'express';
+import '../auth/auth.middleware.js';
+/** Every workspace path a request names, array-shaped queries included. */
+export declare function gitGuardedInputs(req: express.Request): string[];
+/**
+ * The git folder is never reachable through the `/workspace/:id` surface (see
+ * `shared/git-internals.ts`). Checked once, ahead of every route, on each
+ * input that names a workspace path: before the read gate, which would
+ * otherwise answer differently for a path that exists, and before any lock is
+ * taken. The resolved form is judged too, so a link in the repository that
+ * points into the folder gets the same refusal.
+ *
+ * Every spelling is refused whether or not the caller is authenticated — the
+ * lexical rule reads the caller's own string and touches no disk, so it
+ * answers nothing about the workspace. Only the RESOLVED check waits for
+ * `req.userId`: it resolves a workspace directory, which an unauthenticated
+ * request must not make the server do.
+ *
+ * Mounted at the app, ahead of every router under that prefix — the file
+ * routes, the review routes, the workflow and access ones, and whatever an
+ * extension mounts — so a router added later is covered by the fact of its
+ * prefix rather than by remembering this. The services underneath refuse
+ * again on their own; this is what keeps the refusal ahead of the gates.
+ */
+export declare function createGitInternalsRouteGuard(workspaceService: {
+    getWorkspacePath(workspaceId: string): Promise<string>;
+}): express.RequestHandler;
+//# sourceMappingURL=git-internals.middleware.d.ts.map

package/dist/modules/workspace/git-internals.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-internals.middleware.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/git-internals.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAI9B,OAAO,4BAA4B,CAAC;AAgBpC,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,MAAM,EAAE,CAa/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAC,gBAAgB,EAAE;IAC7D,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD,GAAG,OAAO,CAAC,cAAc,CA2BzB"}

package/dist/modules/workspace/git-internals.middleware.js

@@ -0,0 +1,93 @@
+import { GitInternalsError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
+import { assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+/** The query and body fields through which a workspace route names a path. */
+const GIT_GUARDED_QUERY_KEYS = ['path', 'toDir'];
+// `paths` is the access batch's list; `ancestor` is the folder a
+// remove-from-parent cascades up to. Both name workspace paths, so both are
+// judged — a field that names a path and is not here is a way around this.
+const GIT_GUARDED_BODY_KEYS = ['path', 'oldPath', 'newPath', 'destination', 'paths', 'ancestor'];
+/**
+ * `from` names a PATH on the prospective-access route (`?from=<file>&toDir=…`)
+ * and a BRANCH on the workflow comparison (`?from=<branch>`), so it is judged
+ * only where it is a path — a branch called after the git folder is refused
+ * by the branch-name rule, not by this one.
+ */
+const PATH_FROM_ROUTE = /\/access\/prospective\/?$/;
+/** Every workspace path a request names, array-shaped queries included. */
+export function gitGuardedInputs(req) {
+    const out = [];
+    const add = (value) => {
+        for (const v of Array.isArray(value) ? value : [value])
+            if (typeof v === 'string' && v.length > 0)
+                out.push(v);
+    };
+    const query = req.query;
+    for (const key of GIT_GUARDED_QUERY_KEYS)
+        add(query[key]);
+    if (PATH_FROM_ROUTE.test(req.path))
+        add(query.from);
+    const body = req.body;
+    if (body && typeof body === 'object' && !Buffer.isBuffer(body)) {
+        for (const key of GIT_GUARDED_BODY_KEYS)
+            add(body[key]);
+    }
+    return out;
+}
+/**
+ * The git folder is never reachable through the `/workspace/:id` surface (see
+ * `shared/git-internals.ts`). Checked once, ahead of every route, on each
+ * input that names a workspace path: before the read gate, which would
+ * otherwise answer differently for a path that exists, and before any lock is
+ * taken. The resolved form is judged too, so a link in the repository that
+ * points into the folder gets the same refusal.
+ *
+ * Every spelling is refused whether or not the caller is authenticated — the
+ * lexical rule reads the caller's own string and touches no disk, so it
+ * answers nothing about the workspace. Only the RESOLVED check waits for
+ * `req.userId`: it resolves a workspace directory, which an unauthenticated
+ * request must not make the server do.
+ *
+ * Mounted at the app, ahead of every router under that prefix — the file
+ * routes, the review routes, the workflow and access ones, and whatever an
+ * extension mounts — so a router added later is covered by the fact of its
+ * prefix rather than by remembering this. The services underneath refuse
+ * again on their own; this is what keeps the refusal ahead of the gates.
+ */
+export function createGitInternalsRouteGuard(workspaceService) {
+    return async (req, res, next) => {
+        const inputs = gitGuardedInputs(req);
+        if (inputs.length === 0)
+            return next();
+        // Only the git refusal reaches here, and it carries its own 403 and its
+        // one sanitized message — nothing else about the path is answered.
+        const refuse = (err) => void res.status(err.status).json(domainErrorBody(err));
+        if (inputs.some(hasGitInternalsSegment))
+            return refuse(new GitInternalsError());
+        // The resolved check resolves a workspace on disk, which an
+        // unauthenticated request must not make the server do; its route answers
+        // that request with its own 401.
+        if (!req.userId)
+            return next();
+        let workspaceDir;
+        try {
+            workspaceDir = await workspaceService.getWorkspacePath(req.params.id);
+        }
+        catch {
+            // The route resolves the workspace again and reports its own failure.
+            return next();
+        }
+        try {
+            for (const input of inputs)
+                await assertNotGitInternals(workspaceDir, input);
+        }
+        catch (err) {
+            if (err instanceof GitInternalsError)
+                return refuse(err);
+            throw err;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=git-internals.middleware.js.map

package/dist/modules/workspace/git-internals.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-internals.middleware.js","sourceRoot":"","sources":["../../../src/modules/workspace/git-internals.middleware.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/not-found.d.ts

@@ -0,0 +1,80 @@
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { NOT_FOUND_NEXT_STEP } from '../../shared/domain-errors.js';
+/**
+ * ONE answer for "there is nothing at that path", for every file tool.
+ *
+ * A path that is not there is an ordinary answer, not a failure of the server:
+ * the caller spelled a name nothing holds, and the fix is theirs. Each tool
+ * used to reach that conclusion its own way — some with a 404, most by letting
+ * the filesystem's own `ENOENT` escape as a 500 — so an agent could not tell
+ * "your path is wrong" from "this deployment is broken", and had no stable
+ * field to branch on either way.
+ *
+ * So the mapping lives here and nowhere else. Every tool wraps the call that
+ * can meet absence in {@link orNotFound}, and every one of them then answers:
+ *
+ *   - **404**, because the path is the caller's to correct;
+ *   - `kind: 'not_found'`, the stable discriminator beside the prose (the same
+ *     `kind` convention `write-denied` and `git-internals` already use);
+ *   - the REQUESTED path, sanitized — echoed back so a chained caller can see
+ *     which of its arguments was wrong, never the path on disk;
+ *   - one sentence of next steps, always the same one.
+ *
+ * What is NOT absence stays a 500. ENOENT and ENOTDIR are the disk's own
+ * definition of "nothing is there" ({@link isAbsence}); a permission error, an
+ * I/O error or a symlink loop means the path could not be READ, and answering
+ * those 404 would tell a caller to go and fix a name that is perfectly fine
+ * while an outage went unreported. Their raw code goes to the operator log —
+ * the caller gets the 500 it has always got.
+ *
+ * ORDER MATTERS: a tool that gates reads must let the gate answer FIRST. A 404
+ * on a path the caller may not read would confirm the path is absent, and the
+ * absence of a name is as much a disclosure as its presence. Every read tool
+ * here calls `assertCanRead` before it touches the disk, and this helper is
+ * only ever reached past that point.
+ */
+/**
+ * The next step, in one sentence — identical on every tool, so it is written
+ * once. Defined beside {@link PathNotFoundError} in `shared/domain-errors`,
+ * which raises the same 404 from the service and HTTP side and so needs the
+ * same sentence; re-exported here because this is where the file tools read
+ * it from.
+ */
+export { NOT_FOUND_NEXT_STEP };
+/** The machine-readable body of a missing-path refusal. */
+export interface NotFoundDetails {
+    kind: 'not_found';
+    /** The path the caller asked for, sanitized for a one-line message. */
+    path: string;
+}
+/**
+ * The 404 every file tool answers for a path that is not there.
+ *
+ * `lead` replaces the default opening clause for a tool whose missing path is
+ * not simply "the file you named" — grep's search root, a move's source — so
+ * the caller learns WHICH argument was wrong. The path, the `kind` and the
+ * next step never vary.
+ */
+export declare function notFound(path: string, lead?: string): ToolError;
+/**
+ * Run `work`, and answer {@link notFound} if it turns out `path` is not there.
+ *
+ * Absence arrives in two shapes and both are absence: a filesystem error
+ * carrying `ENOENT`/`ENOTDIR` (raw Node errors and Mastra's `FileNotFoundError`
+ * alike), and a {@link PathNotFoundError} a service raised because it probed
+ * the path itself. Anything else is rethrown untouched, with its raw code
+ * logged for the operator and nothing new added to what the caller sees.
+ */
+export declare function orNotFound<T>(path: string, work: () => Promise<T>, lead?: string): Promise<T>;
+/**
+ * {@link orNotFound} for work that probes the path ITSELF and says so with a
+ * {@link PathNotFoundError} — unzip's service, which must open the archive to
+ * answer at all.
+ *
+ * Only that declared answer maps. A raw `ENOENT` from deep inside such work is
+ * NOT the named path being absent: an extraction that fails part-way through
+ * is a failure of the extraction, and calling it "your .zip is not there"
+ * would send the caller to re-spell a path that was never wrong.
+ */
+export declare function orDeclaredNotFound<T>(work: () => Promise<T>, lead?: string): Promise<T>;
+//# sourceMappingURL=not-found.d.ts.map

package/dist/modules/workspace/not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/not-found.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAE7D,OAAO,EAAE,mBAAmB,EAAqB,MAAM,+BAA+B,CAAC;AAMvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAE/B,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAO/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAenG;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAO7F"}

package/dist/modules/workspace/not-found.js

@@ -0,0 +1,112 @@
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { NOT_FOUND_NEXT_STEP, PathNotFoundError } from '../../shared/domain-errors.js';
+import { sanitizedPath } from '../../shared/printable.js';
+import { logger } from '../../shared/logging.js';
+const log = logger('not-found');
+/**
+ * ONE answer for "there is nothing at that path", for every file tool.
+ *
+ * A path that is not there is an ordinary answer, not a failure of the server:
+ * the caller spelled a name nothing holds, and the fix is theirs. Each tool
+ * used to reach that conclusion its own way — some with a 404, most by letting
+ * the filesystem's own `ENOENT` escape as a 500 — so an agent could not tell
+ * "your path is wrong" from "this deployment is broken", and had no stable
+ * field to branch on either way.
+ *
+ * So the mapping lives here and nowhere else. Every tool wraps the call that
+ * can meet absence in {@link orNotFound}, and every one of them then answers:
+ *
+ *   - **404**, because the path is the caller's to correct;
+ *   - `kind: 'not_found'`, the stable discriminator beside the prose (the same
+ *     `kind` convention `write-denied` and `git-internals` already use);
+ *   - the REQUESTED path, sanitized — echoed back so a chained caller can see
+ *     which of its arguments was wrong, never the path on disk;
+ *   - one sentence of next steps, always the same one.
+ *
+ * What is NOT absence stays a 500. ENOENT and ENOTDIR are the disk's own
+ * definition of "nothing is there" ({@link isAbsence}); a permission error, an
+ * I/O error or a symlink loop means the path could not be READ, and answering
+ * those 404 would tell a caller to go and fix a name that is perfectly fine
+ * while an outage went unreported. Their raw code goes to the operator log —
+ * the caller gets the 500 it has always got.
+ *
+ * ORDER MATTERS: a tool that gates reads must let the gate answer FIRST. A 404
+ * on a path the caller may not read would confirm the path is absent, and the
+ * absence of a name is as much a disclosure as its presence. Every read tool
+ * here calls `assertCanRead` before it touches the disk, and this helper is
+ * only ever reached past that point.
+ */
+/**
+ * The next step, in one sentence — identical on every tool, so it is written
+ * once. Defined beside {@link PathNotFoundError} in `shared/domain-errors`,
+ * which raises the same 404 from the service and HTTP side and so needs the
+ * same sentence; re-exported here because this is where the file tools read
+ * it from.
+ */
+export { NOT_FOUND_NEXT_STEP };
+/**
+ * The 404 every file tool answers for a path that is not there.
+ *
+ * `lead` replaces the default opening clause for a tool whose missing path is
+ * not simply "the file you named" — grep's search root, a move's source — so
+ * the caller learns WHICH argument was wrong. The path, the `kind` and the
+ * next step never vary.
+ */
+export function notFound(path, lead) {
+    const safe = sanitizedPath(path);
+    const details = { kind: 'not_found', path: safe };
+    const opening = lead === undefined
+        ? `There is no file or directory at "${safe}" in this workspace.`
+        : `${lead}: there is no file or directory at "${safe}" in this workspace.`;
+    return new ToolError(`${opening} ${NOT_FOUND_NEXT_STEP}`, 404, { ...details });
+}
+/**
+ * Run `work`, and answer {@link notFound} if it turns out `path` is not there.
+ *
+ * Absence arrives in two shapes and both are absence: a filesystem error
+ * carrying `ENOENT`/`ENOTDIR` (raw Node errors and Mastra's `FileNotFoundError`
+ * alike), and a {@link PathNotFoundError} a service raised because it probed
+ * the path itself. Anything else is rethrown untouched, with its raw code
+ * logged for the operator and nothing new added to what the caller sees.
+ */
+export async function orNotFound(path, work, lead) {
+    try {
+        return await work();
+    }
+    catch (err) {
+        if (err instanceof PathNotFoundError)
+            throw notFound(err.path, lead);
+        if (isAbsence(err))
+            throw notFound(path, lead);
+        // Not absence: the path could not be READ, which is a 500 and an operator's
+        // problem. The raw errno is logged here — the one place that saw it — and
+        // the error travels on unchanged.
+        const code = err?.code;
+        if (typeof code === 'string') {
+            log.error('filesystem failure that is not absence:', { code, path: sanitizedPath(path) });
+        }
+        throw err;
+    }
+}
+/**
+ * {@link orNotFound} for work that probes the path ITSELF and says so with a
+ * {@link PathNotFoundError} — unzip's service, which must open the archive to
+ * answer at all.
+ *
+ * Only that declared answer maps. A raw `ENOENT` from deep inside such work is
+ * NOT the named path being absent: an extraction that fails part-way through
+ * is a failure of the extraction, and calling it "your .zip is not there"
+ * would send the caller to re-spell a path that was never wrong.
+ */
+export async function orDeclaredNotFound(work, lead) {
+    try {
+        return await work();
+    }
+    catch (err) {
+        if (err instanceof PathNotFoundError)
+            throw notFound(err.path, lead);
+        throw err;
+    }
+}
+//# sourceMappingURL=not-found.js.map

package/dist/modules/workspace/not-found.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.js","sourceRoot":"","sources":["../../../src/modules/workspace/not-found.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAS/B;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,IAAa;IAClD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,OAAO,GAAoB,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACnE,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS;QAChC,CAAC,CAAC,qCAAqC,IAAI,sBAAsB;QACjE,CAAC,CAAC,GAAG,IAAI,uCAAuC,IAAI,sBAAsB,CAAC;IAC7E,OAAO,IAAI,SAAS,CAAC,GAAG,OAAO,IAAI,mBAAmB,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAI,IAAY,EAAE,IAAsB,EAAE,IAAa;IACrF,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,iBAAiB;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrE,IAAI,SAAS,CAAC,GAAG,CAAC;YAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/C,4EAA4E;QAC5E,0EAA0E;QAC1E,kCAAkC;QAClC,MAAM,IAAI,GAAI,GAAiC,EAAE,IAAI,CAAC;QACtD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,GAAG,CAAC,KAAK,CAAC,yCAAyC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAI,IAAsB,EAAE,IAAa;IAC/E,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,iBAAiB;YAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/modules/workspace/session-ontology.gate.d.ts

@@ -38,7 +38,7 @@ export declare const SESSION_ID_INPUT: JsonSchema;
  * knows the restriction before it calls one. Action-then-why phrasing per
  * docs/glossary.md.
  */
-export declare const ONTOLOGY_BOUNDARY_NOTE = " Stay within one KnowledgeBase ontology per conversation: once this run has read or written files in two different ontologies, every later content write (write_file/edit_file/mkdir/unzip, and both endpoints of move_file/copy_file) is blocked with a 403 and no override. Reads and delete_file never block \u2014 but each one records the ontology it touched and can poison a later content write, so do broad cross-ontology exploration only when you do not intend to write. Note move_file/copy_file are blocked outright when source and destination are different ontologies, since they would carry content across.";
+export declare const ONTOLOGY_BOUNDARY_NOTE = " Stay within one KnowledgeBase ontology per conversation: once this run has read or written files in two different ontologies, every later content write (write_file/edit_file/mkdir/unzip, and both endpoints of move_file/copy_file) is blocked with a 403 and no override. Reads, delete_file and delete_folder never block \u2014 but each one records the ontology it touched and can poison a later content write, so do broad cross-ontology exploration only when you do not intend to write. Note move_file/copy_file are blocked outright when source and destination are different ontologies, since they would carry content across.";
 /** Thrown when a write is refused because the session has crossed ontologies. */
 export declare class OntologyWriteBlockedError extends ToolError {
     constructor(touched: string[], attempted: string, reason: 'multi-ontology' | 'different-ontology');

package/dist/modules/workspace/session-ontology.gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-ontology.gate.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/session-ontology.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAI9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,smBAC6jB,CAAC;AAEjmB,iFAAiF;AACjF,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,OAAO,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,oBAAoB;CAQlG;AAED,uFAAuF;AACvF,qBAAa,mBAAoB,SAAQ,SAAS;;CAQjD;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,KAAK,EAAE,aAAa,CAAC;CACtB;AA4BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gCAAgC,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjH"}
+{"version":3,"file":"session-ontology.gate.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/session-ontology.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAI9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,qnBAC4kB,CAAC;AAEhnB,iFAAiF;AACjF,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,OAAO,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,oBAAoB;CAQlG;AAED,uFAAuF;AACvF,qBAAa,mBAAoB,SAAQ,SAAS;;CAQjD;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,KAAK,EAAE,aAAa,CAAC;CACtB;AA4BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gCAAgC,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjH"}

package/dist/modules/workspace/session-ontology.gate.js

@@ -39,7 +39,7 @@ export const SESSION_ID_INPUT = {
  * knows the restriction before it calls one. Action-then-why phrasing per
  * docs/glossary.md.
  */
-export const ONTOLOGY_BOUNDARY_NOTE = ' Stay within one KnowledgeBase ontology per conversation: once this run has read or written files in two different ontologies, every later content write (write_file/edit_file/mkdir/unzip, and both endpoints of move_file/copy_file) is blocked with a 403 and no override. Reads and delete_file never block — but each one records the ontology it touched and can poison a later content write, so do broad cross-ontology exploration only when you do not intend to write. Note move_file/copy_file are blocked outright when source and destination are different ontologies, since they would carry content across.';
+export const ONTOLOGY_BOUNDARY_NOTE = ' Stay within one KnowledgeBase ontology per conversation: once this run has read or written files in two different ontologies, every later content write (write_file/edit_file/mkdir/unzip, and both endpoints of move_file/copy_file) is blocked with a 403 and no override. Reads, delete_file and delete_folder never block — but each one records the ontology it touched and can poison a later content write, so do broad cross-ontology exploration only when you do not intend to write. Note move_file/copy_file are blocked outright when source and destination are different ontologies, since they would carry content across.';
 /** Thrown when a write is refused because the session has crossed ontologies. */
 export class OntologyWriteBlockedError extends ToolError {
     constructor(touched, attempted, reason) {

package/dist/modules/workspace/session-ontology.gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-ontology.gate.js","sourceRoot":"","sources":["../../../src/modules/workspace/session-ontology.gate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-ontology.gate.js","sourceRoot":"","sources":["../../../src/modules/workspace/session-ontology.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAoB,MAAM,kCAAkC,CAAC;AAI/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,QAAQ;IACd,WAAW,EACT,mVAAmV;CACtV,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,6mBAA6mB,CAAC;AAEhnB,iFAAiF;AACjF,MAAM,OAAO,yBAA0B,SAAQ,SAAS;IACtD,YAAY,OAAiB,EAAE,SAAiB,EAAE,MAA+C;QAC/F,MAAM,GAAG,GACP,MAAM,KAAK,gBAAgB;YACzB,CAAC,CAAC,kEAAkE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,6EAA6E,SAAS,IAAI;YAChL,CAAC,CAAC,mCAAmC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,iDAAiD,SAAS,4CAA4C,SAAS,IAAI,CAAC;QAC/K,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD;QACE,KAAK,CACH,uQAAuQ,EACvQ,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAkBD,kGAAkG;AAClG,SAAS,aAAa,CAAC,GAAgB;IACrC,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,IAAyB,EAAE,GAAgB,EAAE,MAAc;IACtF,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC;IACjC,wEAAwE;IACxE,IAAI,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC/D,yEAAyE;IACzE,8BAA8B;IAC9B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IACvC,6EAA6E;IAC7E,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,gBAAgB;QAAE,OAAO,MAAM,CAAC;IAC1E,+EAA+E;IAC/E,IAAI,CAAC,GAAG,CAAC,SAAS;QAAE,MAAM,IAAI,mBAAmB,EAAE,CAAC;IACpD,OAAO,GAAG,CAAC,SAAS,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAyB,EAAE,GAAgB,EAAE,MAAc;IAClG,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACzD,IAAI,SAAS,KAAK,MAAM;QAAE,OAAO;IACjC,qEAAqE;IACrE,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,IAAyB,EACzB,GAAgB,EAChB,MAAc;IAEd,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACzD,IAAI,SAAS,KAAK,MAAM;QAAE,OAAO;IACjC,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IACxE,wEAAwE;IACxE,2EAA2E;IAC3E,yBAAyB;IACzB,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,gCAAgC,CAAC,IAAyB,EAAE,GAAgB;IAChG,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO;IAC1B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,OAAO;IAChC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,gBAAgB;QAAE,OAAO;IACnE,IAAI,CAAC,GAAG,CAAC,SAAS;QAAE,OAAO;IAE3B,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/dist/modules/workspace/startup/beside-checkout.d.ts

@@ -0,0 +1,42 @@
+/** The opening of the boot note, so a test and an operator's grep agree on it. */
+export declare const BESIDE_CHECKOUT_NOTE = "Beside the checkout, not in the repository:";
+/**
+ * Name whatever is sitting in a workspace directory other than the checkout —
+ * and touch none of it.
+ *
+ * A workspace directory holds the repository as one folder (`<kbDirName>/`).
+ * Anything else in there is in a location git never sees: never committed,
+ * never pushed, never shared, and invisible in the app once the explorer reads
+ * its roots from the checkout. Nothing the platform accepts can write there any
+ * more — every path goes through the normaliser now — but deployments that ran
+ * the older code already have such files, and the only way anyone learns of
+ * them is if the platform says so. So it says so, once per start, per workspace.
+ *
+ * DELETES NOTHING, MOVES NOTHING, on purpose. The platform cannot prove it
+ * wrote any of it: a stray may be an operator's own scratch file beside a
+ * clone, and a boot that quietly removed it would be a data loss nobody asked
+ * for. The operator cleans up, and the note stops on the next start.
+ *
+ * EVERYTHING other than the checkout folder is named, the platform's own
+ * transient `tmp/` scratch included on the rare start that finds one (a run
+ * clears it when it finishes). That is deliberate: the note's claim is about
+ * what is not in the repository, and a note that quietly kept exceptions would
+ * be a note an operator could not trust.
+ *
+ * NOT a `OnServerStart` step, and deliberately outside the KB startup phase.
+ * That phase is gated — it does nothing until the branch model and the
+ * repository URL are configured, and it is retried on setup completion and
+ * again whenever the remote comes back. A note that lived inside it would be
+ * silent on exactly the deployments most likely to hold strays (setup never
+ * finished, remote unreachable) and would repeat itself on every retry. This
+ * runs ONCE per boot, from the server builder, before that phase, and needs
+ * no remote and no clone: what it reads is already on disk.
+ *
+ * Reads the workspaces root directly rather than through a branch handle: it
+ * needs the directories that are ALREADY on disk, not the branches this build
+ * would clone, and a read-only scan must not be the thing that clones a branch.
+ */
+export declare function noteBesideCheckout(workspacesRoot: string, kbDirName: string, 
+/** Where the note goes. Injected so a test can read it without a log sink. */
+note?: (line: string) => void): Promise<void>;
+//# sourceMappingURL=beside-checkout.d.ts.map

package/dist/modules/workspace/startup/beside-checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beside-checkout.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/beside-checkout.ts"],"names":[],"mappings":"AAQA,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,gDAAgD,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,kBAAkB,CACtC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM;AACjB,8EAA8E;AAC9E,IAAI,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAA+B,GACtD,OAAO,CAAC,IAAI,CAAC,CA8Bf"}