@bevel-software/platform-shared 0.15.1 → 0.20.0

package/dist/workspace/platform-files.d.ts

@@ -0,0 +1,105 @@
+import { type KbLayout } from './kb-layout.js';
+/**
+ * The files the platform reads as configuration, not content. `access.md`
+ * governs the folder it sits in and `.bevelignore` layers like `.gitignore`,
+ * so both count at any depth; `roles.yaml` and the agent guide are read from
+ * the repository root only, so a nested file of either name is ordinary
+ * content. Moving one changes what the platform enforces, so moves refuse them.
+ *
+ * A FUNCTION, not a constant, and that is the whole of the configurable-guide
+ * change on this side: the guide's name is a deployment setting, so the fourth
+ * platform file is `HEXIS.md` on one deployment and `AGENTS.md` on the next —
+ * and on the first, a root `AGENTS.md` is the CUSTOMER'S own conventions file,
+ * which has to move and delete like any page. Every gate asks this rather than
+ * reading a list captured at module load.
+ */
+export declare function platformFileNames(layout?: KbLayout): readonly string[];
+/**
+ * The platform file names under the DEFAULT layout — what they were before the
+ * guide could be renamed. Kept for callers that want the default answer rather
+ * than this deployment's; anything judging a real path asks
+ * {@link platformFileNames}, which knows what this deployment called its guide.
+ */
+export declare const PLATFORM_FILE_NAMES: readonly string[];
+/**
+ * Whether the repository-relative `repoRelativePath` is a platform file.
+ * Exact spelling, as the platform reads it: `Access.md` is content. A caller
+ * on a case-insensitive disk passes the path's on-disk spelling.
+ */
+export declare function isPlatformFile(repoRelativePath: string): boolean;
+/** The one sentence every surface refuses a platform-file move with. */
+export declare function platformFileRefusal(pathOrName: string): string;
+/**
+ * The sentence a move is refused with when the DESTINATION would be a platform
+ * file — a note renamed to `access.md`, or dragged onto the one that is there.
+ * The other refusal keeps a platform file where the platform reads it; this one
+ * keeps everything else from becoming one, which a rename on disk would
+ * otherwise do silently: the folder would come back governed by rules nobody
+ * wrote as rules.
+ */
+export declare function platformFileCreationRefusal(pathOrName: string): string;
+/**
+ * Whether `repoRelativeDir` is a folder the platform owns rather than content:
+ * the repository root itself, or one of its reserved top-level folders
+ * (`KnowledgeBase/`, `Skills/`, `Plugins/`, `Data/`, …). Deleting or moving
+ * one takes a whole section of the knowledge base with it. Exact spelling; a
+ * caller on a case-insensitive disk passes the path's on-disk spelling.
+ */
+export declare function isPlatformFolder(repoRelativeDir: string): boolean;
+/** The sentence a delete or move of a platform folder is refused with. */
+export declare function platformFolderRefusal(repoRelativeDir: string): string;
+/**
+ * Whether the platform file at `repoRelativePath` sits directly in the
+ * repository root — the copy every one of the four is read from there, and so
+ * never the misplaced one: it is the copy a restore puts back. A nested
+ * `access.md` or `.bevelignore` is a platform file too, but it layers on top
+ * of the root's rather than standing in for it, which is why moving the
+ * ROOT's copy into a folder is a move out and not a restore.
+ */
+export declare function isRootPlatformFile(repoRelativePath: string): boolean;
+/**
+ * The place a misplaced platform file is allowed to be put back, when
+ * `repoRelativeDestination` names one, and null when it does not.
+ *
+ * `roles.yaml` and the agent guide are read from the repository root and
+ * nowhere else, so their one required location is the root. A nested `.bevelignore` is
+ * read too (it layers, see `BevelIgnoreStack`), yet a restore of one lands at
+ * the root only — a deliberate narrowing of the exception, not a claim about
+ * where the file is read: the root's copy is the one whose absence breaks the
+ * workspace, and a folder that never had a `.bevelignore` is not missing one.
+ * `access.md` governs whatever folder it sits in, so a folder that has none
+ * is a place one is missing from — WHETHER the folder has one is a fact about
+ * the disk, which this pure predicate does not know and the caller checks
+ * (see `AccessControlService.canRestorePlatformFile`).
+ */
+export type PlatformRestoreDestination = {
+    name: string;
+    kind: 'root';
+} | {
+    name: string;
+    kind: 'folder-without-access-md';
+    dir: string;
+};
+export declare function platformRestoreDestination(repoRelativeDestination: string): PlatformRestoreDestination | null;
+/**
+ * Whether moving `repoRelativeSource` to `repoRelativeDestination` has the
+ * SHAPE of a platform-file restore — an admin putting a misplaced copy back.
+ * Who is asking is not part of the shape; `canRestorePlatformFile` answers
+ * that, and the state of the disk with it.
+ *
+ * Three things make the shape, and all three are about the move rather than
+ * about the source's current standing:
+ *
+ *  - the source is NAMED like a platform file. A nested `roles.yaml`, or a
+ *    nested copy of the agent guide, is ordinary content where it sits
+ *    (`isPlatformFile` says so, and moving it needs no exception), but it is
+ *    still the copy a restore carries back to the root — judging the shape on
+ *    `isPlatformFile` would skip the exception for exactly the two files the
+ *    root can lose;
+ *  - the source is not the root's own copy, which is the copy a restore puts
+ *    back, never the one it takes out;
+ *  - the destination is a required location for that same name, so the file
+ *    lands under the name the platform reads rather than beside it.
+ */
+export declare function isPlatformRestoreShape(repoRelativeSource: string, repoRelativeDestination: string): boolean;
+//# sourceMappingURL=platform-files.d.ts.map

package/dist/workspace/platform-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-files.d.ts","sourceRoot":"","sources":["../../src/workspace/platform-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,QAA4B,GAAG,SAAS,MAAM,EAAE,CAEzF;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAC;AA2BF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAKhE;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,0BAA0B,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,0BAA0B,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,wBAAgB,0BAA0B,CACxC,uBAAuB,EAAE,MAAM,GAC9B,0BAA0B,GAAG,IAAI,CAUnC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,kBAAkB,EAAE,MAAM,EAC1B,uBAAuB,EAAE,MAAM,GAC9B,OAAO,CAOT"}

package/dist/workspace/platform-files.js

@@ -0,0 +1,147 @@
+import { DEFAULT_KB_LAYOUT, FIXED_PLATFORM_FILE_NAMES, agentsFileOf, currentKbLayout, reservedRootDirNames, } from './kb-layout.js';
+/**
+ * The files the platform reads as configuration, not content. `access.md`
+ * governs the folder it sits in and `.bevelignore` layers like `.gitignore`,
+ * so both count at any depth; `roles.yaml` and the agent guide are read from
+ * the repository root only, so a nested file of either name is ordinary
+ * content. Moving one changes what the platform enforces, so moves refuse them.
+ *
+ * A FUNCTION, not a constant, and that is the whole of the configurable-guide
+ * change on this side: the guide's name is a deployment setting, so the fourth
+ * platform file is `HEXIS.md` on one deployment and `AGENTS.md` on the next —
+ * and on the first, a root `AGENTS.md` is the CUSTOMER'S own conventions file,
+ * which has to move and delete like any page. Every gate asks this rather than
+ * reading a list captured at module load.
+ */
+export function platformFileNames(layout = currentKbLayout()) {
+    return [...FIXED_PLATFORM_FILE_NAMES, agentsFileOf(layout)];
+}
+/**
+ * The platform file names under the DEFAULT layout — what they were before the
+ * guide could be renamed. Kept for callers that want the default answer rather
+ * than this deployment's; anything judging a real path asks
+ * {@link platformFileNames}, which knows what this deployment called its guide.
+ */
+export const PLATFORM_FILE_NAMES = Object.freeze(platformFileNames(DEFAULT_KB_LAYOUT));
+/** The platform files that are read wherever they sit, not only at the root. */
+const PLATFORM_FILES_AT_ANY_DEPTH = new Set(['access.md', '.bevelignore']);
+/** The names in effect, as a set — rebuilt per call, because the guide's is configurable. */
+const platformFiles = () => new Set(platformFileNames());
+const normalize = (path) => path.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+const baseName = (path) => {
+    const trimmed = normalize(path);
+    return trimmed.slice(trimmed.lastIndexOf('/') + 1);
+};
+/**
+ * A path that walks out of the repository (`..`) or stands still (`.`). The
+ * restore exception is the one write allowed past a destination that denies
+ * it, so it answers on the spelling it was handed and refuses anything whose
+ * meaning depends on resolving it: `KnowledgeBase/../access.md` names the
+ * root's file to a resolver and a nested one to a reader of segments. The
+ * move's own path-safety check refuses these too — this gate does not lean on
+ * that one.
+ */
+const hasTraversal = (path) => normalize(path).split('/').some((segment) => segment === '..' || segment === '.');
+/**
+ * Whether the repository-relative `repoRelativePath` is a platform file.
+ * Exact spelling, as the platform reads it: `Access.md` is content. A caller
+ * on a case-insensitive disk passes the path's on-disk spelling.
+ */
+export function isPlatformFile(repoRelativePath) {
+    const norm = normalize(repoRelativePath);
+    const name = baseName(norm);
+    if (!platformFiles().has(name))
+        return false;
+    return PLATFORM_FILES_AT_ANY_DEPTH.has(name) || norm === name;
+}
+/** The one sentence every surface refuses a platform-file move with. */
+export function platformFileRefusal(pathOrName) {
+    return `${baseName(pathOrName)} is a platform file and stays in its folder.`;
+}
+/**
+ * The sentence a move is refused with when the DESTINATION would be a platform
+ * file — a note renamed to `access.md`, or dragged onto the one that is there.
+ * The other refusal keeps a platform file where the platform reads it; this one
+ * keeps everything else from becoming one, which a rename on disk would
+ * otherwise do silently: the folder would come back governed by rules nobody
+ * wrote as rules.
+ */
+export function platformFileCreationRefusal(pathOrName) {
+    return `${baseName(pathOrName)} is a platform file name; a move cannot create a platform file.`;
+}
+/**
+ * Whether `repoRelativeDir` is a folder the platform owns rather than content:
+ * the repository root itself, or one of its reserved top-level folders
+ * (`KnowledgeBase/`, `Skills/`, `Plugins/`, `Data/`, …). Deleting or moving
+ * one takes a whole section of the knowledge base with it. Exact spelling; a
+ * caller on a case-insensitive disk passes the path's on-disk spelling.
+ */
+export function isPlatformFolder(repoRelativeDir) {
+    const norm = normalize(repoRelativeDir);
+    if (norm === '')
+        return true;
+    return !norm.includes('/') && reservedRootDirNames().has(norm);
+}
+/** The sentence a delete or move of a platform folder is refused with. */
+export function platformFolderRefusal(repoRelativeDir) {
+    const norm = normalize(repoRelativeDir);
+    return norm === ''
+        ? 'The repository root is a platform folder and cannot be moved or deleted.'
+        : `${norm}/ is a platform folder and cannot be moved or deleted.`;
+}
+/**
+ * Whether the platform file at `repoRelativePath` sits directly in the
+ * repository root — the copy every one of the four is read from there, and so
+ * never the misplaced one: it is the copy a restore puts back. A nested
+ * `access.md` or `.bevelignore` is a platform file too, but it layers on top
+ * of the root's rather than standing in for it, which is why moving the
+ * ROOT's copy into a folder is a move out and not a restore.
+ */
+export function isRootPlatformFile(repoRelativePath) {
+    return platformFiles().has(normalize(repoRelativePath));
+}
+export function platformRestoreDestination(repoRelativeDestination) {
+    const norm = normalize(repoRelativeDestination);
+    if (hasTraversal(norm))
+        return null;
+    const name = baseName(norm);
+    if (!platformFiles().has(name))
+        return null;
+    if (name === 'access.md') {
+        const slash = norm.lastIndexOf('/');
+        return { name, kind: 'folder-without-access-md', dir: slash === -1 ? '' : norm.slice(0, slash) };
+    }
+    return norm === name ? { name, kind: 'root' } : null;
+}
+/**
+ * Whether moving `repoRelativeSource` to `repoRelativeDestination` has the
+ * SHAPE of a platform-file restore — an admin putting a misplaced copy back.
+ * Who is asking is not part of the shape; `canRestorePlatformFile` answers
+ * that, and the state of the disk with it.
+ *
+ * Three things make the shape, and all three are about the move rather than
+ * about the source's current standing:
+ *
+ *  - the source is NAMED like a platform file. A nested `roles.yaml`, or a
+ *    nested copy of the agent guide, is ordinary content where it sits
+ *    (`isPlatformFile` says so, and moving it needs no exception), but it is
+ *    still the copy a restore carries back to the root — judging the shape on
+ *    `isPlatformFile` would skip the exception for exactly the two files the
+ *    root can lose;
+ *  - the source is not the root's own copy, which is the copy a restore puts
+ *    back, never the one it takes out;
+ *  - the destination is a required location for that same name, so the file
+ *    lands under the name the platform reads rather than beside it.
+ */
+export function isPlatformRestoreShape(repoRelativeSource, repoRelativeDestination) {
+    if (hasTraversal(repoRelativeSource))
+        return false;
+    const name = baseName(repoRelativeSource);
+    if (!platformFiles().has(name))
+        return false;
+    if (isRootPlatformFile(repoRelativeSource))
+        return false;
+    const target = platformRestoreDestination(repoRelativeDestination);
+    return target !== null && target.name === name;
+}
+//# sourceMappingURL=platform-files.js.map

package/dist/workspace/platform-files.js.map

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

package/dist/workspace/types.d.ts

@@ -25,6 +25,14 @@ export interface FileTreeEntry {
     relativePath: string;
     type: 'file' | 'directory';
     children?: FileTreeEntry[];
+    /**
+     * Set on a DIRECTORY of a read-filtered listing, and only when non-zero:
+     * how many entries the caller's read rules kept out of that directory's
+     * subtree — on the root, out of the whole listing. A number, never names —
+     * it lets the explorer tell "nothing is shared with you" apart from "this
+     * folder is empty" without saying what exists.
+     */
+    withheld?: number;
 }
 import type { AuthUser } from '../auth/types.js';
 export interface IWorkspaceService {

package/dist/workspace/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5E,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAChE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5E,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAChE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-shared",
-  "version": "0.15.1",
+  "version": "0.20.0",
   "description": "Shared types and pure domain utilities of the Bevel core platform (auth, workspace, git/workflow contracts, branch registry).",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/src/auth/types.ts

@@ -11,6 +11,18 @@ export interface AuthUser {
    * absent field must never resurrect the welcome flow.
    */
   onboardingDone?: boolean;
+  /**
+   * Is this the deployment admin — the account whose password is set in the
+   * deployment environment (`ADMIN_EMAIL` while `ADMIN_PASSWORD` is set)
+   * rather than stored as a hash? That credential is the platform's rescue
+   * path into a deployment, so this account's password cannot be changed from
+   * the Account page. Derived from configuration on every read rather than
+   * stored, and it carries no part of the credential itself. Optional for the
+   * same reason as `onboardingDone` above — pre-existing fixtures and cached
+   * user objects stay valid — and only an explicit `true` means "deployment
+   * admin".
+   */
+  isEnvAdmin?: boolean;
 }
 
 export interface LoginRequest {

package/src/git/pr.types.ts

@@ -44,7 +44,39 @@ export interface PullRequestSummary {
   /** Relative paths within `knowledge-base/`. Empty if not yet computed. */
   touchedNodePaths: string[];
   review: PullRequestReviewStatus;
+  /**
+   * Link to the change request: absolute (`<public frontend address>/change-requests/<number>`)
+   * when the deployment has a public address configured, else the in-app relative path.
+   */
   url: string;
+  /** Present when `url` is relative — says how to get absolute links. */
+  urlNote?: string;
+  /**
+   * The most recent apply attempt that did not land, while the request is
+   * still open — so its author and every other viewer see the refusal the
+   * person who clicked Apply saw. Replaced by a newer refusal; null or
+   * absent when there is nothing to report.
+   */
+  lastApplyFailure?: ChangeRequestApplyFailure | null;
+}
+
+/**
+ * What refused an apply: the merge gate (approvals it still waits on), git
+ * (conflicts with the target), or anything else (a push, the roles.yaml guard,
+ * an internal error). Decides which later change makes the refusal obsolete.
+ */
+export type ChangeRequestApplyFailureKind = 'gate' | 'conflicts' | 'error';
+
+/** Why the last apply of a change request failed, as persisted on the request. */
+export interface ChangeRequestApplyFailure {
+  /** Human-readable reason, credentials already redacted. */
+  reason: string;
+  /** True when git refused the merge on conflicts with the target. */
+  conflicts: boolean;
+  /** ISO timestamp of the failed attempt. */
+  at: string;
+  /** Display name of whoever attempted the apply. */
+  byName: string;
 }
 
 export type PrFileStatus =
@@ -145,16 +177,31 @@ export interface FileApprovalState {
     users: { name: string; email: string }[];
   };
   approvedBy: FileApprovalEntry[];
+  /**
+   * True only when `eligibleApprovers` is the access tree's actual answer for
+   * this file. False (or absent) when it could not be resolved — no workspace,
+   * no usable access config on the base, a failed lookup — in which case the
+   * empty approver set means "unknown", not "outside the gate", and anything
+   * granted on the strength of that emptiness must fail closed.
+   */
+  eligibilityResolved?: boolean;
   /**
    * True iff at least one eligible approver has submitted a non-stale
    * approval. Always `false` when `eligibleApprovers` is empty — with no
    * eligible set, nobody can satisfy the check.
    * Whether the gate *cares* about this file is a separate concern handled
-   * by the merge-gate logic: non-md files and files with no eligible
-   * approvers are silently excluded from the gate, so `isApproved: false`
+   * by the merge-gate logic: files with no eligible approvers, whatever
+   * their type, are silently excluded from the gate, so `isApproved: false`
    * on one of them does not block merge.
    */
   isApproved: boolean;
+  /**
+   * Whether the merge gate binds this file at all — the backend's one
+   * relevance rule, stamped per file so clients read the verdict instead of
+   * re-deriving it. False files neither warn nor block a merge, so no surface
+   * should count them as pending or name anyone to wait on.
+   */
+  inMergeGate: boolean;
   /**
    * Pre-computed for the requesting viewer: would `approveFile` accept their
    * click? True iff their email resolves to `write` on this path under the
@@ -184,21 +231,21 @@ export interface PullRequestDetail extends PullRequestSummary {
    */
   approvals: FileApprovalState[];
   /**
-   * True iff no *hard* block applies — the PR is open, has files, and isn't
-   * merged/closed. Soft warnings (missing owner approvals on md files) do
-   * **not** set this to false; the UI handles them via the bypass dialog.
-   * The button is disabled only when this is false.
+   * True iff no blocking reason remains — the PR is open, has files, isn't
+   * merged/closed, and every file with an eligible approver (of any file
+   * type) holds a current approval. False while any approval is missing; an
+   * admin may still merge past missing approvals with the bypass flag.
    */
   mergeableInBevel: boolean;
   /**
-   * Hard-block reasons — merging is impossible until these resolve (PR state,
-   * no files, etc.). Empty when the PR can be merged (possibly after bypass).
+   * Blocking reasons — hard blocks (PR state, no files) followed by each
+   * missing approval. Empty exactly when `mergeableInBevel` is true.
    */
   mergeBlockedReasons: string[];
   /**
-   * Soft warnings — md files with an owner who hasn't approved (or whose
-   * approval is stale). Merging is allowed but the UI asks for an explicit
-   * bypass confirmation first. Non-md files and ownerless md files are silent.
+   * The missing approvals alone — files of any type with an eligible approver
+   * who hasn't approved (or whose approval is stale). An admin bypass merges
+   * past exactly these and records them. Files nobody can approve are silent.
    */
   mergeWarnings: string[];
   /**
@@ -221,6 +268,25 @@ export interface PullRequestDetail extends PullRequestSummary {
    * tree can't be resolved.
    */
   viewerCanCancel: boolean;
+  /**
+   * The commit this request forked from its target (merge base of `headSha`
+   * and `baseSha`). Every file diff in the request reads its "before" side
+   * here, never at the target tip — an edit made on the target after the
+   * proposal must not look like something the proposal deletes. `null` when
+   * the branches share no history (or no workspace could resolve them).
+   */
+  mergeBaseSha: string | null;
+  /**
+   * True iff the target holds commits the proposal does not contain — the
+   * request needs updating. False for anything not open.
+   */
+  behind: boolean;
+  /**
+   * True iff the viewer may Update the request (merge its target into it):
+   * the request is open AND the viewer is its author or may apply it. A UX
+   * hint — the update route re-checks the same predicate server-side.
+   */
+  viewerCanUpdate: boolean;
 }
 
 /**

package/src/git/types.ts

@@ -249,6 +249,40 @@ export interface IGitService {
    * Just the repo-relative paths a change request touches (three-dot diff,
    * no statuses, no patches): the cheap form behind change-request list
    * summaries and owner routing.
+   *
+   * `fetch: false` skips the per-request fetch of the two refs — for a caller
+   * that has just refreshed the whole clone's remote-tracking refs in one
+   * round trip, which is what a LIST does rather than paying one fetch per
+   * request. Pass it only when that is true; otherwise the diff can describe
+   * a stale head. It is a skip, not a promise: a branch the clone does not
+   * have yet is fetched anyway, since there is nothing to diff without it —
+   * so a list's first sight of a new request still costs one round trip.
+   */
+  changedPathsForPr(
+    workspaceId: string,
+    baseBranch: string,
+    headBranch: string,
+    opts?: { fetch?: boolean },
+  ): Promise<string[]>;
+
+  /**
+   * A change request's fork point (merge base of the two resolved commits)
+   * and whether the target has commits the proposal does not contain. No
+   * fetch: `at` is what `resolvePrShas` just returned.
    */
-  changedPathsForPr(workspaceId: string, baseBranch: string, headBranch: string): Promise<string[]>;
+  forkPointForPr(
+    workspaceId: string,
+    at: { baseSha: string; headSha: string },
+  ): Promise<{ mergeBaseSha: string | null; behind: boolean }>;
+
+  /**
+   * A file's content at a change request's fork point — a commit that must
+   * be on `baseBranch`'s history. `null` when the path did not exist there.
+   */
+  readFileAtForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    sha: string,
+    relativePath: string,
+  ): Promise<string | null>;
 }

package/src/index.ts

@@ -6,10 +6,16 @@ export * from './chat/types.js';
 
 // Workspace
 export * from './workspace/types.js';
+export * from './workspace/agent-preamble.js';
 export * from './workspace/filename.js';
+export * from './workspace/entry-exists.js';
 export * from './workspace/kb-layout.js';
 export * from './workspace/join-request.js';
 export * from './workspace/frontmatter.js';
+export * from './workspace/placeholder.js';
+export * from './workspace/frontmatter-carriers.js';
+export * from './workspace/platform-files.js';
+export * from './workspace/access-verbs.js';
 
 // Git
 export * from './git/types.js';

package/src/workflow/events.ts

@@ -221,6 +221,28 @@ export interface ChangeRequestRejectedEvent {
   number: number;
 }
 
+/**
+ * An apply did NOT land, announced to EVERY session — the counterpart of the
+ * user-scoped `change-request-merge-failed` below, which only the clicker gets.
+ *
+ * The request stays open, so everyone who can see it (its author waiting on
+ * the verdict, another owner, another admin) needs to learn that the attempt
+ * failed and why. The reason is deliberately NOT carried here: it is persisted
+ * on the request (`PullRequestSummary.lastApplyFailure`) and read back through
+ * the list and detail endpoints the viewer already uses, so the broadcast puts
+ * no error text in front of every session, and a session that missed the event
+ * reads the same answer on its next fetch.
+ *
+ * Also sent when a recorded refusal is CLEARED because a change made it
+ * obsolete (an approval for a gate refusal, a moved source head for any):
+ * either way the request's `lastApplyFailure` changed, and every viewer
+ * re-reads it.
+ */
+export interface ChangeRequestApplyFailedEvent {
+  kind: 'change-request-apply-failed';
+  number: number;
+}
+
 /**
  * A merge the caller triggered did NOT land — either the gate refused it, the
  * branch needs conflict resolution, or `gh pr merge` failed. The merge route
@@ -228,9 +250,10 @@ export interface ChangeRequestRejectedEvent {
  * gateway timeout), so this is how the failure reaches the UI that kicked it
  * off. Success travels on `change-request-merged` instead.
  *
- * User-scoped (`forUserId`, no `workspaceId`) — a failed merge changes no
- * shared state; only the user who clicked needs the reason, so we don't
- * broadcast the error string to every session.
+ * User-scoped (`forUserId`, no `workspaceId`) — the clicker's immediate
+ * answer, which also routes a conflict into the resolution flow. Everyone else
+ * learns of the failure from `change-request-apply-failed`, which carries no
+ * error string; the reason itself is persisted on the request.
  */
 export interface ChangeRequestMergeFailedEvent {
   kind: 'change-request-merge-failed';
@@ -243,6 +266,12 @@ export interface ChangeRequestMergeFailedEvent {
    * The UI routes to the agent resolution flow instead of showing an error.
    */
   conflicts: boolean;
+  /**
+   * When the attempt failed (ISO) — the same instant persisted as
+   * `lastApplyFailure.at` when the refusal is recorded, so the clicker's tab
+   * can tell its own refusal from a later one somebody else's attempt made.
+   */
+  at?: string;
 }
 
 /**
@@ -296,6 +325,7 @@ export type WorkflowEventPayload =
   | ChangeRequestMergedEvent
   | ChangeRequestRejectedEvent
   | ChangeRequestMergeFailedEvent
+  | ChangeRequestApplyFailedEvent
   | ApprovalChangedEvent
   | HeartbeatEvent
   | ResyncEvent;