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

package/dist/shared/logger.contract.js

@@ -0,0 +1,126 @@
+/**
+ * The contract for LOGGING. Nothing here writes anywhere — the one default
+ * implementation is the console sink in `shared/logging.ts`, and a deployment's
+ * shell installs whatever it runs in production (the server shell installs
+ * pino). Modules never import a sink; they ask for a tagged logger and log.
+ *
+ * WHY A PORT. The backend logged through 294 bare `console.*` calls with no
+ * level a filter could act on, no request or workspace a line could be
+ * grouped by, and no shape a machine could parse. When something fails at
+ * three in the morning the log cannot be reduced to one request or one
+ * severity. A library would have fixed that in the published package — and
+ * imposed a logging stack on every npm consumer, the enterprise overlay
+ * included, which very likely logs its own way already; two loggers
+ * interleaved is worse than either. So the package owns the contract and a
+ * dependency-free default, and the shell that actually runs owns the choice.
+ *
+ * WHAT A LINE CARRIES. A message, for a person; fields, for a machine; and
+ * the bindings of the logger it came from — at least `module`, the tag every
+ * call used to spell by hand in square brackets. Bindings and fields are one
+ * flat set on the line: a `child`'s bindings override its parent's under the
+ * same key, and a call's fields override the bindings — except `module`,
+ * which is the tag: the default sink fixes the `[tag]` from the logger's own
+ * bindings when it is made, and a call-time `module` is printed as an
+ * ordinary field beside it. Leave that key to the tag.
+ * An error goes under `err`, by that name: it is the key both the default
+ * sink and pino recognise as an error, and render with its stack. Put an
+ * `Error` there, not a string: the type cannot insist, and a string under
+ * `err` is logged as text — one line, escaped, but with no stack to show.
+ */
+/**
+ * C0 and C1 control characters (U+009B among them: the one-byte CSI that
+ * starts an ANSI sequence by itself) and the JS line separators. The rule
+ * against control characters in a regex guards against accidental ones; these
+ * are the point.
+ */
+const CONTROL_CHARS = new RegExp(`[\x00-\x1F\x7F-\x9F${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+const NAMED = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+/**
+ * `text` as one terminal-safe line. A message often carries text the process
+ * did not write — a branch name from a request, a path from a plugin, git's
+ * stderr — and written raw, a newline in it starts a forged line and an
+ * escape sequence paints the terminal. Every sink applies this, so the rule
+ * "one event, one line" is kept in one place rather than by each call site
+ * remembering `printable`. Shared with the shell's sink through this contract
+ * module because pino's JSON escapes only the C0 range: a C1 control or a
+ * line separator would pass through it to the terminal that tails the log.
+ */
+export function oneLine(text) {
+    return text.replace(CONTROL_CHARS, (c) => NAMED[c] ?? `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+/**
+ * `err` with the text it carries made terminal-safe, its frames untouched.
+ *
+ * An error's message is very often not the process's own words: it quotes a
+ * path, a branch name, git's stderr, a file's contents. Its stack frames ARE
+ * the process's own and read best as the lines they are, so only the
+ * message — and the head of the stack, which repeats it — is escaped. A
+ * `cause` that is itself an error is treated the same way, since the console
+ * prints it too (a chain that loops back on itself is cut where it loops).
+ * The original is never mutated: an error is often rethrown or inspected
+ * after it was logged.
+ */
+export function oneLineError(err) {
+    return escapedCopy(err, new Set());
+}
+function escapedCopy(err, seen) {
+    seen.add(err);
+    const message = oneLine(err.message);
+    const copy = Object.create(Object.getPrototypeOf(err));
+    Object.defineProperty(copy, 'message', { value: message, enumerable: false, writable: true, configurable: true });
+    Object.defineProperty(copy, 'name', { value: err.name, enumerable: false, writable: true, configurable: true });
+    if (typeof err.stack === 'string') {
+        // Node's stack is the error's own `toString()` — `<name>: <message>` —
+        // followed by `\n    at …` frames. The frames are looked for AFTER that
+        // header, not from the top: a message that itself holds a line shaped
+        // like a frame would otherwise move the boundary up and pass the rest of
+        // itself through raw. A stack that does not open with the header is not
+        // one this code knows the shape of, and is escaped whole.
+        // The frames keep their lines; each is still escaped within its line, for
+        // a stack that is not Node's own (a foreign runtime's, a hand-built one)
+        // and carries a control character after a frame-shaped line.
+        const head = Error.prototype.toString.call(err);
+        const frames = err.stack.startsWith(head) ? err.stack.indexOf('\n    at ', head.length) : -1;
+        const stack = frames === -1
+            ? oneLine(err.stack)
+            : `${oneLine(err.stack.slice(0, frames))}\n${err.stack
+                .slice(frames + 1)
+                .split('\n')
+                .map(oneLine)
+                .join('\n')}`;
+        Object.defineProperty(copy, 'stack', { value: stack, enumerable: false, writable: true, configurable: true });
+    }
+    const nested = (value) => value instanceof Error
+        ? seen.has(value)
+            ? '[circular]'
+            : escapedCopy(value, seen)
+        : typeof value === 'string'
+            ? oneLine(value)
+            : value;
+    const cause = err.cause;
+    if (cause !== undefined) {
+        Object.defineProperty(copy, 'cause', { value: nested(cause), enumerable: false, writable: true, configurable: true });
+    }
+    // An `AggregateError`'s failures — non-enumerable there, and the whole
+    // point of it; kept as enumerable as the source had it, so an ordinary
+    // error that carries an `errors` list of its own still shows it.
+    const errors = err.errors;
+    if (Array.isArray(errors)) {
+        Object.defineProperty(copy, 'errors', {
+            value: errors.map(nested),
+            enumerable: Object.prototype.propertyIsEnumerable.call(err, 'errors'),
+            writable: true,
+            configurable: true,
+        });
+    }
+    // Own enumerable fields (a `code`, a `status`) travel with the error.
+    for (const [key, value] of Object.entries(err)) {
+        if (!(key in copy))
+            copy[key] = typeof value === 'string' ? oneLine(value) : value;
+    }
+    // `seen` is the path down, not everything met: one failure listed twice
+    // under an AggregateError is copied twice, and only a true loop is cut.
+    seen.delete(err);
+    return copy;
+}
+//# sourceMappingURL=logger.contract.js.map

package/dist/shared/logger.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.contract.js","sourceRoot":"","sources":["../../src/shared/logger.contract.ts"],"names":[],"mappings":"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"}

package/dist/shared/logging.d.ts

@@ -0,0 +1,31 @@
+import { type ILogger, type LogFields } from './logger.contract.js';
+/** Install the process's logger. Returns the previous one, for a suite to restore. */
+export declare function setLogger(impl: ILogger): ILogger;
+/**
+ * The logger a module logs through, carrying `module: tag` on every line — the
+ * `[tag]` every call used to spell by hand.
+ */
+export declare function logger(tag: string): ILogger;
+/**
+ * The default sink: `console`, in the shape the backend has always written —
+ * `[module] message`, and the fields after it. Dependency-free, so the
+ * published package logs sensibly with nothing installed, and human-shaped,
+ * because a terminal is where that case is read. A deployment that wants
+ * machine-shaped lines installs a sink that emits them; the server shell
+ * installs pino.
+ *
+ * Fields are passed to `console` as a second argument rather than folded into
+ * the string, so an object stays inspectable and an error keeps its stack.
+ * When `err` is the only field it is passed bare: that is the shape a person
+ * at a terminal wants, and the shape the suites that watch the console have
+ * always asserted on.
+ *
+ * An error field is passed as a copy whose message is one line (see
+ * `oneLineError`): the stack the console prints is the process's own text,
+ * but the message at its head is very often not — it quotes git's stderr, a
+ * path, a request's branch name — and unescaped it would forge a line or
+ * paint the terminal exactly as a string field would. Every call site that
+ * logs `{ err }` is covered here, so none of them has to remember it.
+ */
+export declare function createConsoleLogger(bindings?: LogFields): ILogger;
+//# sourceMappingURL=logging.d.ts.map

package/dist/shared/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/shared/logging.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyB,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAwB3F,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAIhD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3C;AAYD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,SAAc,GAAG,OAAO,CAqBrE"}

package/dist/shared/logging.js

@@ -0,0 +1,92 @@
+// This file IS the console sink; every other file logs through it. The lint
+// rule that forbids `console` elsewhere in the backend exempts exactly this
+// file (see eslint.config.js).
+import { oneLine, oneLineError } from './logger.contract.js';
+/**
+ * Where the backend's logging goes, and how a module gets a logger.
+ *
+ * ONE SLOT, INSTALLED ONCE. The composition root — or a shell before it —
+ * calls {@link setLogger} with the implementation the process runs on, and
+ * every module obtains a tagged child through {@link logger}. The slot is
+ * process-wide on purpose: the `console` it replaces was, and threading a
+ * logger through some sixty constructors (and the several hundred places
+ * tests construct them) would spend a great deal to make a cross-cutting
+ * concern look like a per-object dependency. It remains injectable: a suite
+ * that wants to see what was logged installs a capturing logger through the
+ * same setter.
+ *
+ * CHILDREN RESOLVE LATE. `logger('tag')` is called at module load, before any
+ * root has run, so what it returns is a handle that looks the slot up on
+ * every call rather than a child of whatever happened to be installed then.
+ * Installing pino after a module loaded therefore still routes that module's
+ * lines through pino.
+ */
+let current = createConsoleLogger();
+/** Install the process's logger. Returns the previous one, for a suite to restore. */
+export function setLogger(impl) {
+    const previous = current;
+    current = impl;
+    return previous;
+}
+/**
+ * The logger a module logs through, carrying `module: tag` on every line — the
+ * `[tag]` every call used to spell by hand.
+ */
+export function logger(tag) {
+    return lateBound({ module: tag });
+}
+function lateBound(bindings) {
+    return {
+        debug: (message, fields) => current.child(bindings).debug(message, fields),
+        info: (message, fields) => current.child(bindings).info(message, fields),
+        warn: (message, fields) => current.child(bindings).warn(message, fields),
+        error: (message, fields) => current.child(bindings).error(message, fields),
+        child: (more) => lateBound({ ...bindings, ...more }),
+    };
+}
+/**
+ * The default sink: `console`, in the shape the backend has always written —
+ * `[module] message`, and the fields after it. Dependency-free, so the
+ * published package logs sensibly with nothing installed, and human-shaped,
+ * because a terminal is where that case is read. A deployment that wants
+ * machine-shaped lines installs a sink that emits them; the server shell
+ * installs pino.
+ *
+ * Fields are passed to `console` as a second argument rather than folded into
+ * the string, so an object stays inspectable and an error keeps its stack.
+ * When `err` is the only field it is passed bare: that is the shape a person
+ * at a terminal wants, and the shape the suites that watch the console have
+ * always asserted on.
+ *
+ * An error field is passed as a copy whose message is one line (see
+ * `oneLineError`): the stack the console prints is the process's own text,
+ * but the message at its head is very often not — it quotes git's stderr, a
+ * path, a request's branch name — and unescaped it would forge a line or
+ * paint the terminal exactly as a string field would. Every call site that
+ * logs `{ err }` is covered here, so none of them has to remember it.
+ */
+export function createConsoleLogger(bindings = {}) {
+    // The tag is a binding like any other and goes through the same rule: a
+    // module name is the code's own today, but the contract lets a caller bind
+    // one, and a tag is written at the head of every line it tags.
+    const prefix = typeof bindings.module === 'string' ? `[${oneLine(bindings.module)}] ` : '';
+    const rest = Object.fromEntries(Object.entries(bindings).filter(([k]) => k !== 'module'));
+    const safe = (v) => (typeof v === 'string' ? oneLine(v) : v instanceof Error ? oneLineError(v) : v);
+    const extra = (fields) => {
+        const merged = Object.fromEntries(Object.entries({ ...rest, ...fields }).map(([k, v]) => [k, safe(v)]));
+        const keys = Object.keys(merged);
+        if (keys.length === 0)
+            return [];
+        if (keys.length === 1 && keys[0] === 'err')
+            return [merged.err];
+        return [merged];
+    };
+    return {
+        debug: (message, fields) => console.debug(`${prefix}${oneLine(message)}`, ...extra(fields)),
+        info: (message, fields) => console.log(`${prefix}${oneLine(message)}`, ...extra(fields)),
+        warn: (message, fields) => console.warn(`${prefix}${oneLine(message)}`, ...extra(fields)),
+        error: (message, fields) => console.error(`${prefix}${oneLine(message)}`, ...extra(fields)),
+        child: (more) => createConsoleLogger({ ...bindings, ...more }),
+    };
+}
+//# sourceMappingURL=logging.js.map

package/dist/shared/logging.js.map

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

package/dist/shared/path-containment.d.ts

@@ -0,0 +1,21 @@
+/**
+ * THE containment check for ABSOLUTE paths: is `absolutePath` the directory
+ * `dir`, or something under it?
+ *
+ * Three surfaces carried a copy of this — the workspace service, the diff
+ * ledger and the delete route — and each threw a bare `Error` whose MESSAGE
+ * five catch sites then matched to decide on a 403. A reworded message would
+ * have turned every one of those into a 500, which is to say into a silently
+ * unblocked traversal in the log. So the refusal is a TYPE now
+ * ({@link PathTraversalError}, 403 with a `path-traversal` payload), and the
+ * route layers read the status off the class like every other domain error.
+ *
+ * LEXICAL, deliberately: it compares resolved spellings and follows no links,
+ * so it is safe to call before anything touches the disk. It is therefore not
+ * the whole rule — a path may be contained by its spelling and still reach
+ * outside through a symlink, which is `assertNotThroughLink`'s job, and a
+ * workspace-RELATIVE spelling is `canonicalFileIdentity`'s. This is the first
+ * of those three, and the only one every caller needs.
+ */
+export declare function assertWithinDirectory(absolutePath: string, dir: string): void;
+//# sourceMappingURL=path-containment.d.ts.map

package/dist/shared/path-containment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-containment.d.ts","sourceRoot":"","sources":["../../src/shared/path-containment.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAW7E"}

package/dist/shared/path-containment.js

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { PathTraversalError } from './domain-errors.js';
+/**
+ * THE containment check for ABSOLUTE paths: is `absolutePath` the directory
+ * `dir`, or something under it?
+ *
+ * Three surfaces carried a copy of this — the workspace service, the diff
+ * ledger and the delete route — and each threw a bare `Error` whose MESSAGE
+ * five catch sites then matched to decide on a 403. A reworded message would
+ * have turned every one of those into a 500, which is to say into a silently
+ * unblocked traversal in the log. So the refusal is a TYPE now
+ * ({@link PathTraversalError}, 403 with a `path-traversal` payload), and the
+ * route layers read the status off the class like every other domain error.
+ *
+ * LEXICAL, deliberately: it compares resolved spellings and follows no links,
+ * so it is safe to call before anything touches the disk. It is therefore not
+ * the whole rule — a path may be contained by its spelling and still reach
+ * outside through a symlink, which is `assertNotThroughLink`'s job, and a
+ * workspace-RELATIVE spelling is `canonicalFileIdentity`'s. This is the first
+ * of those three, and the only one every caller needs.
+ */
+export function assertWithinDirectory(absolutePath, dir) {
+    const resolved = path.resolve(absolutePath);
+    const root = path.resolve(dir);
+    // The separator is what makes this a containment check rather than a prefix
+    // match — without it `/srv/ws-backup` passes as "inside" `/srv/ws`. A root
+    // that already ends in one (the filesystem root, `/` or `C:\`) must not get
+    // a second, or every descendant fails to match the doubled prefix.
+    const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+    if (resolved !== root && !resolved.startsWith(prefix)) {
+        throw new PathTraversalError();
+    }
+}
+//# sourceMappingURL=path-containment.js.map

package/dist/shared/path-containment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-containment.js","sourceRoot":"","sources":["../../src/shared/path-containment.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB,EAAE,GAAW;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,4EAA4E;IAC5E,2EAA2E;IAC3E,4EAA4E;IAC5E,mEAAmE;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC;IAChE,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/shared/pending-proposals.d.ts

@@ -0,0 +1,71 @@
+import { type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import type { IAccessControl } from '../modules/access/access-control.interface.js';
+/**
+ * The mechanics every "proposed, not released" surface shares.
+ *
+ * Skills and tools both have a half of their catalog that is NOT on the default
+ * branch: a change request that ADDS a declaration has nothing on the default
+ * branch to hang itself off, so until it merged the proposal was invisible to
+ * its author and to the people who had to approve it. Both surfaces answer that
+ * the same way — walk the OPEN change requests, keep the touched paths that
+ * look like the declaration in question, decide who may see each one, and read
+ * the file at the request's own branch — and only the "looks like" predicate and
+ * the parsing differ.
+ *
+ * Kept in one place so the two cannot drift on the part that matters most: WHO
+ * MAY SEE A PROPOSAL. It is narrower than who may see the catalog — the author,
+ * and whoever could approve it. "Could approve it" is not re-stated as an
+ * admin check; it is `canWrite` on the very path the request would create,
+ * resolved on the DEFAULT branch. The new file carries no `access.md` of its
+ * own, so that verdict inherits from the plugin folder, which IS the plugin's
+ * admin; asking the access tree keeps these surfaces and the merge gate
+ * answering with one voice. The branch's own copy of the tree is written by the
+ * proposer and must not get a say in who reviews them.
+ */
+export interface ProposalSources {
+    workspaceService: Pick<WorkspaceService, 'ensureRemotesFetched' | 'readFileAtRef'>;
+    accessControl: Pick<IAccessControl, 'canWriteBatch'>;
+    workflow: Pick<IWorkflowService, 'listChangeRequests'>;
+}
+/** One file an open change request proposes, already read at that request's branch. */
+export interface ProposedFile {
+    /** The open change request that would release it. */
+    cr: ChangeRequest;
+    /** Repo-root-relative path of the proposed file. */
+    path: string;
+    /** The file's content at the request's branch. */
+    content: string;
+    /** True when the caller opened the request themselves. */
+    isAuthor: boolean;
+}
+/**
+ * Every file matching `matches` that an OPEN change request proposes and this
+ * caller is entitled to see, with its branch content in hand.
+ *
+ * Never throws: these surfaces hang off the library's list load, and a review
+ * shelf that cannot answer must not take the shelf down with it. Everything
+ * degrades to "nothing pending".
+ *
+ * `matches` is where a surface states what it is looking for — and, because it
+ * runs BEFORE the access batch, also where it drops what it already serves from
+ * the default branch, so the batch stays as small as the answer.
+ *
+ * Order follows the change requests as the workflow service listed them; a
+ * caller that wants a stable reading order sorts the result itself.
+ */
+export declare function visibleProposedFiles(sources: ProposalSources, userEmail: string, matches: (repoRelPath: string) => boolean): Promise<ProposedFile[]>;
+/**
+ * The file at a branch, or null when it is not there.
+ *
+ * `readFileAtRef` ALREADY answers `null` for genuine absence (a `git show` that
+ * finds no such blob), so everything reaching the catch below is an infra
+ * failure instead — an unresolvable workspace, a rejected ref, a git call that
+ * timed out. The contract of this module is "never throws", so those still
+ * become `null` and the card still drops; what they must not do is drop
+ * SILENTLY, which is how a fetch problem reads as "the proposer withdrew it".
+ * The warning is the difference between a shelf that degraded and a shelf that
+ * lied.
+ */
+export declare function readAt(workspaceService: Pick<WorkspaceService, 'readFileAtRef'>, wsId: string, branch: string, repoRelPath: string): Promise<string | null>;
+//# sourceMappingURL=pending-proposals.d.ts.map

package/dist/shared/pending-proposals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-proposals.d.ts","sourceRoot":"","sources":["../../src/shared/pending-proposals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAC5G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAElF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+CAA+C,CAAC;AAOpF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,GAAG,eAAe,CAAC,CAAC;IACnF,aAAa,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IACrD,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,CAAC;CACxD;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,EAAE,EAAE,aAAa,CAAC;IAClB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,GACxC,OAAO,CAAC,YAAY,EAAE,CAAC,CA0DzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,EACzD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAcxB"}

package/dist/shared/pending-proposals.js

@@ -0,0 +1,98 @@
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from './workspace-id.js';
+import { canonicalEmail, hashEmail } from './email-identity.js';
+import { printable } from './printable.js';
+import { logger } from './logging.js';
+const log = logger('pending-proposals');
+/**
+ * Every file matching `matches` that an OPEN change request proposes and this
+ * caller is entitled to see, with its branch content in hand.
+ *
+ * Never throws: these surfaces hang off the library's list load, and a review
+ * shelf that cannot answer must not take the shelf down with it. Everything
+ * degrades to "nothing pending".
+ *
+ * `matches` is where a surface states what it is looking for — and, because it
+ * runs BEFORE the access batch, also where it drops what it already serves from
+ * the default branch, so the batch stays as small as the answer.
+ *
+ * Order follows the change requests as the workflow service listed them; a
+ * caller that wants a stable reading order sorts the result itself.
+ */
+export async function visibleProposedFiles(sources, userEmail, matches) {
+    const email = canonicalEmail(userEmail);
+    if (!email)
+        return [];
+    let crs;
+    try {
+        // Open, and aimed at the DEFAULT BRANCH. Everything downstream is written
+        // in terms of that branch — the released set that decides "added", and the
+        // access tree that decides who may review — so a request targeting some
+        // other branch is not a proposal these surfaces can speak about: merging it
+        // puts nothing in the catalog, and the card would never resolve.
+        crs = (await sources.workflow.listChangeRequests()).filter((c) => c.state === 'open' && c.base === DEFAULT_BRANCH);
+    }
+    catch {
+        return [];
+    }
+    if (crs.length === 0)
+        return [];
+    const candidates = crs.flatMap((cr) => cr.touchedNodePaths.filter(matches).map((path) => ({ cr, path })));
+    if (candidates.length === 0)
+        return [];
+    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    const authorHash = hashEmail(email);
+    // One access load for every candidate, resolved on the DEFAULT branch — see
+    // the note on {@link ProposalSources}.
+    const writable = await sources.accessControl
+        .canWriteBatch(wsId, email, candidates.map((c) => c.path))
+        .catch(() => new Map());
+    // The branch copies are read through the default branch's clone at
+    // `origin/<branch>`, so a proposal never needs a clone of its own. Refresh
+    // first, best-effort: a request pushed seconds ago is worth one fetch, and a
+    // failed fetch should degrade to "read what we have".
+    await sources.workspaceService.ensureRemotesFetched(wsId).catch(() => undefined);
+    const out = [];
+    for (const { cr, path } of candidates) {
+        const isAuthor = !!cr.authorId && cr.authorId === authorHash;
+        // Fail closed, matching the catalog: only an explicit `true` admits a
+        // reviewer. A missing entry (the batch skipped the path, the tree could not
+        // be read) means denied, never shown.
+        if (!isAuthor && writable.get(path) !== true)
+            continue;
+        const content = await readAt(sources.workspaceService, wsId, cr.branch, path);
+        // Nothing to describe: the request touched the path but the file is gone at
+        // its head (proposed then withdrawn within the branch), or unreadable.
+        if (content === null)
+            continue;
+        out.push({ cr, path, content, isAuthor });
+    }
+    return out;
+}
+/**
+ * The file at a branch, or null when it is not there.
+ *
+ * `readFileAtRef` ALREADY answers `null` for genuine absence (a `git show` that
+ * finds no such blob), so everything reaching the catch below is an infra
+ * failure instead — an unresolvable workspace, a rejected ref, a git call that
+ * timed out. The contract of this module is "never throws", so those still
+ * become `null` and the card still drops; what they must not do is drop
+ * SILENTLY, which is how a fetch problem reads as "the proposer withdrew it".
+ * The warning is the difference between a shelf that degraded and a shelf that
+ * lied.
+ */
+export async function readAt(workspaceService, wsId, branch, repoRelPath) {
+    try {
+        return await workspaceService.readFileAtRef(wsId, `origin/${branch}`, repoRelPath);
+    }
+    catch (err) {
+        // Every interpolated value is attacker-shaped: the path and the branch come
+        // off a change request somebody else opened, and the reason comes off git.
+        // A raw newline or an escape sequence in any of them forges a log line or
+        // steers the operator's terminal, so all three go through `printable`.
+        log.warn(`could not read ${printable(repoRelPath)} at origin/${printable(branch)} in ${printable(wsId)}; ` +
+            `dropping it from the review shelf: ${printable(err instanceof Error ? err.message : String(err))}`);
+        return null;
+    }
+}
+//# sourceMappingURL=pending-proposals.js.map

package/dist/shared/pending-proposals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-proposals.js","sourceRoot":"","sources":["../../src/shared/pending-proposals.ts"],"names":[],"mappings":"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"}

package/dist/shared/printable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Re-export, so this backend's ~20 call sites keep their short import while
+ * the function itself lives where BOTH MCP surfaces can reach it.
+ *
+ * The local server (`@bevel-software/hexis-mcp`) is published standalone and
+ * cannot import this package, but it logs the same kind of text — a reason
+ * string that came off the network — to the same kind of operator log. Two
+ * copies of an escaper is two escapers that drift, so it moved to the one
+ * package both already depend on. See `printable` there for what it escapes
+ * and why.
+ */
+export { printable } from '@bevel-software/platform-mcp-core';
+export declare function sanitizedPath(text: string): string;
+/**
+ * JSON text as a terminal can show it: `JSON.stringify` escapes the C0
+ * controls inside strings and leaves the C1 range and the line separators
+ * raw, so those are escaped here — still the same JSON to any reader of it,
+ * since they can only occur inside a string. For a document, not a path:
+ * the JSON's own line breaks (pretty-printing) are left alone.
+ */
+export declare function terminalSafeJson(json: string): string;
+//# sourceMappingURL=printable.d.ts.map

package/dist/shared/printable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printable.d.ts","sourceRoot":"","sources":["../../src/shared/printable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AA2C9D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/shared/printable.js

@@ -0,0 +1,65 @@
+/**
+ * Re-export, so this backend's ~20 call sites keep their short import while
+ * the function itself lives where BOTH MCP surfaces can reach it.
+ *
+ * The local server (`@bevel-software/hexis-mcp`) is published standalone and
+ * cannot import this package, but it logs the same kind of text — a reason
+ * string that came off the network — to the same kind of operator log. Two
+ * copies of an escaper is two escapers that drift, so it moved to the one
+ * package both already depend on. See `printable` there for what it escapes
+ * and why.
+ */
+export { printable } from '@bevel-software/platform-mcp-core';
+/**
+ * A path (or any short text) as it may be interpolated into a ONE-LINE
+ * message: every character a caller can put in a filename that RENDERS as a
+ * line break is escaped, so a refusal naming the path stays one line and
+ * cannot forge a second.
+ *
+ * That is every C0 and C1 control character — CR and LF, the other mandatory
+ * breaks (vertical tab, form feed, NEL), and the one-byte escapes a terminal
+ * obeys (U+009B starts an ANSI sequence on its own) — and the Unicode line
+ * separators U+2028/U+2029 with them: `JSON.stringify` leaves the C1 range
+ * and the separators raw, so a path that carries one survives being carried
+ * — in the `path` field of a not-found body, in a log line — and breaks or
+ * steers the line wherever it is finally rendered. {@link printable} escapes
+ * the same set for exactly that reason; the spelling is the same too (`\n`,
+ * `\t`, else `\uXXXX`), so a path reads alike in a refusal and in a log.
+ *
+ * Unquoted, unlike {@link printable}: this text is read by a person or an
+ * agent inside a sentence that already quotes it, not by an operator scanning
+ * a log. THE spelling for that job — `displayPath` in the file readers is this
+ * function, and the missing-path refusals use it too, so a path reads the same
+ * however it is refused.
+ */
+// The names JSON gives its escapes — and so what `printable`, which is
+// `JSON.stringify` underneath, writes for the same characters; every other
+// control is `\uXXXX` in both, so a path reads the same in a refusal and
+// in a log. (JSON has no name for vertical tab, so neither does this.)
+const NAMED_ESCAPES = new Map([
+    ['\b', '\\b'],
+    ['\t', '\\t'],
+    ['\n', '\\n'],
+    ['\f', '\\f'],
+    ['\r', '\\r'],
+]);
+// Built rather than written: the lint rule against control characters in a
+// regex literal guards against accidental ones, and these are the point.
+const CONTROL_OR_SEPARATOR = new RegExp(`[\\x00-\\x1F\\x7F-\\x9F${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+/** The characters `JSON.stringify` leaves raw: the C1 range and the two line separators. */
+const RAW_AFTER_JSON = new RegExp(`[\\x7F-\\x9F${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+const uEscape = (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`;
+export function sanitizedPath(text) {
+    return text.replace(CONTROL_OR_SEPARATOR, (c) => NAMED_ESCAPES.get(c) ?? uEscape(c));
+}
+/**
+ * JSON text as a terminal can show it: `JSON.stringify` escapes the C0
+ * controls inside strings and leaves the C1 range and the line separators
+ * raw, so those are escaped here — still the same JSON to any reader of it,
+ * since they can only occur inside a string. For a document, not a path:
+ * the JSON's own line breaks (pretty-printing) are left alone.
+ */
+export function terminalSafeJson(json) {
+    return json.replace(RAW_AFTER_JSON, uEscape);
+}
+//# sourceMappingURL=printable.js.map

package/dist/shared/printable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"printable.js","sourceRoot":"","sources":["../../src/shared/printable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,uEAAuE;AACvE,2EAA2E;AAC3E,yEAAyE;AACzE,uEAAuE;AACvE,MAAM,aAAa,GAAgC,IAAI,GAAG,CAAC;IACzD,CAAC,IAAI,EAAE,KAAK,CAAC;IACb,CAAC,IAAI,EAAE,KAAK,CAAC;IACb,CAAC,IAAI,EAAE,KAAK,CAAC;IACb,CAAC,IAAI,EAAE,KAAK,CAAC;IACb,CAAC,IAAI,EAAE,KAAK,CAAC;CACd,CAAC,CAAC;AACH,2EAA2E;AAC3E,yEAAyE;AACzE,MAAM,oBAAoB,GAAG,IAAI,MAAM,CAAC,0BAA0B,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAC/G,4FAA4F;AAC5F,MAAM,cAAc,GAAG,IAAI,MAAM,CAAC,eAAe,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAE9F,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAE7F,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}