@bevel-software/platform-shared 0.4.1 → 0.5.1

package/src/git/types.ts

@@ -113,7 +113,20 @@ export interface IGitService {
     user: AuthUser,
     req: ShareChangesRequest,
   ): Promise<CommitAttribution>;
-  push(workspaceId: string, user: AuthUser): Promise<void>;
+  push(
+    workspaceId: string,
+    user: AuthUser,
+    opts?: {
+      /**
+       * Skip the per-user protected-branch access gate for THIS push. Only
+       * for system-authorized flows whose endpoint is itself the
+       * authorization (group provisioning: any signed-in user may claim an
+       * unused name under `Groups/`, and the seeded access.md governs
+       * everything after). Never thread a raw user request into this.
+       */
+      systemAuthorized?: boolean;
+    },
+  ): Promise<void>;
   fetch(workspaceId: string): Promise<void>;
   pull(workspaceId: string): Promise<void>;
   diffStat(workspaceId: string, base?: string): Promise<string[]>;
@@ -130,11 +143,6 @@ export interface IGitService {
    * count. Returns null if no protected branch can be reached.
    */
   resolveForkBase(workspaceId: string, branch: string): Promise<string | null>;
-  revertCommit(
-    workspaceId: string,
-    user: AuthUser,
-    sha: string,
-  ): Promise<CommitAttribution>;
   logForFile(
     workspaceId: string,
     relativePath: string,

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './chat/types.js';
 export * from './workspace/types.js';
 export * from './workspace/filename.js';
 export * from './workspace/kb-layout.js';
+export * from './workspace/join-request.js';
 export * from './workspace/frontmatter.js';
 
 // Git

package/src/workflow/interface.ts

@@ -151,12 +151,6 @@ export interface IWorkflowService {
   ): Promise<Change | null>;
   /** Per-file history. Newest first; clamps to ≤ 100 entries. */
   listChangesForFile(workspaceId: string, path: string, limit?: number): Promise<Change[]>;
-  /**
-   * Revert a single change by creating a new change that undoes it.
-   * Refused on protected branches; refused without write permission on the
-   * touched paths.
-   */
-  revertChange(workspaceId: string, user: AuthUser, sha: string): Promise<Change>;
   /**
    * Diff of one file between two branches. Both names must resolve to a
    * known branch on this workspace (local head or remote-tracking). Returns
@@ -175,6 +169,17 @@ export interface IWorkflowService {
    * Used by the File viewer's History tab.
    */
   showFileAtChange(workspaceId: string, path: string, sha: string): Promise<string>;
+  /**
+   * Full file contents on both sides of one change: `baseline` at `<sha>^`
+   * (null when the file — or the parent commit — doesn't exist there),
+   * `current` at `<sha>` (null when absent). Used by the File viewer's
+   * History tab to render markdown changes as a rendered-markdown diff.
+   */
+  fileAtChange(
+    workspaceId: string,
+    path: string,
+    sha: string,
+  ): Promise<{ baseline: string | null; current: string | null }>;
 
   // ── File locks (new — currently NotImplementedWorkflowError) ──────────────
 
@@ -255,8 +260,11 @@ export interface IWorkflowService {
   // ── Change Requests ───────────────────────────────────────────────────────
 
   listChangeRequests(opts?: { fresh?: boolean }): Promise<ChangeRequest[]>;
-  /** Change requests authored by the caller (hash-matched against the body marker). */
-  listChangeRequestsAuthoredBy(emailOrLogin: string): Promise<ChangeRequest[]>;
+  /** Change requests authored by the given user (matched on stored author identity). */
+  listChangeRequestsAuthoredBy(
+    emailOrLogin: string,
+    opts?: { fresh?: boolean },
+  ): Promise<ChangeRequest[]>;
   /** Change requests touching files the user has write permission on. */
   listChangeRequestsForUser(
     workspaceId: string,
@@ -323,6 +331,33 @@ export interface IWorkflowService {
     workspaceId: string,
   ): Promise<FileApproval[]>;
 
+  /**
+   * Decline ONE file of an open change request: restore its merge-base
+   * version on the source branch so it drops out of the request's diff.
+   * Same permission as approving the file. When the last file is declined
+   * the request closes itself and its source branch is retired
+   * (`closed: true` in the result).
+   */
+  revertChangeRequestFile(
+    number: number,
+    user: AuthUser,
+    repoRelPath: string,
+  ): Promise<{ closed: boolean; remainingPaths: string[] }>;
+
+  /**
+   * Close an OPEN change request whose diff has emptied (authoritatively
+   * re-verified; a failed diff never closes) and retire its source branch.
+   * Returns true when this call closed it.
+   */
+  closeEmptyChangeRequest(number: number, user: AuthUser): Promise<boolean>;
+
+  /**
+   * Delete a change request outright: close it and retire its source branch.
+   * Admin-only (write on `roles.yaml` at `origin/<base>`); refuses a merged
+   * request.
+   */
+  deleteChangeRequest(number: number, user: AuthUser): Promise<void>;
+
   /**
    * Reject a change request without merging. Authorized for the author or
    * for users with write permission to every changed file on the target

package/src/workspace/join-request.ts

@@ -0,0 +1,108 @@
+/**
+ * The join-request naming convention — how "asking to join a group" rides on
+ * plain change requests with zero new backend state.
+ *
+ * A join request IS a change request: a draft branch carrying one commit that
+ * adds the requester to the group's `access.md` body `read:` list, opened
+ * against the default branch. What makes it recognisable — to the `Requested`
+ * chip, to the manager-side proposals surface, to idempotency — is only this
+ * branch-name convention. Both sides (backend, frontend) read it from here so
+ * they can never drift.
+ *
+ *   <email-localpart>/join-<group-kebab>-<groupTag>-<requesterTag>
+ *
+ * follows the workspace's existing `<email-localpart>/<kebab-slug>` draft
+ * convention, so join branches sort with the requester's other drafts and
+ * the branch-authorship delete rule applies unchanged.
+ *
+ * WHY TWO TAGS: the localpart and the kebab slug are both LOSSY, and each
+ * loss has its own failure:
+ *
+ *  - `groupTag` — over the EXACT group name, recomputable by anyone who
+ *    knows the group. `Finance!` and `finance` share the slug `finance`;
+ *    without this tag, listing one group's requests would match the other's
+ *    branches, read the wrong `access.md` (unchanged on that branch), see an
+ *    empty diff and SETTLE the request — closing a change request and
+ *    deleting a branch that belong to a different group. The settle decision
+ *    is "the diff is empty", so group identity must be exact BEFORE the diff
+ *    is consulted, and `isJoinBranchFor` recomputes this tag to make it so.
+ *  - `requesterTag` — over the full email (+ group), NOT recomputable by a
+ *    reader (a manager listing requests does not know each requester's
+ *    email; `isJoinBranchFor` matches its shape only). It exists so
+ *    `ali@bevel.software` and `ali@other.com` never share a branch — else
+ *    the second requester's commit lands on the first one's branch.
+ *
+ * The tags are collision-avoidance devices, not a security boundary —
+ * nothing grants access based on a branch name. Grants happen through the
+ * ordinary access mutation path, and settling only ever closes a request
+ * whose file adds nothing over the default branch.
+ */
+
+/** Group name → the kebab slug used in the join branch (lossy by design). */
+export function kebabGroupName(group: string): string {
+  return group
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/** Length of each branch-name tag, in base-36 characters. */
+const TAG_LENGTH = 7;
+
+/**
+ * Short deterministic tag over an exact string (FNV-1a, base36).
+ *
+ * Synchronous and dependency-free so the same value is derivable in the
+ * browser and on the server; `crypto.subtle` is async and would force this
+ * whole convention to become promise-shaped for no benefit. Not a hash in the
+ * security sense and does not need to be — see the module note.
+ */
+function shortTag(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    // FNV prime, via shifts so the whole thing stays in 32-bit int math.
+    hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+  }
+  return hash.toString(36).padStart(TAG_LENGTH, '0').slice(-TAG_LENGTH);
+}
+
+/** The exact-group tag — recomputable from the group name alone. */
+function groupTag(group: string): string {
+  return shortTag(`g:${group}`);
+}
+
+/** The deterministic join branch for (requester, group). */
+export function joinBranchFor(email: string, group: string): string {
+  const normalizedEmail = email.trim().toLowerCase();
+  const localpart = normalizedEmail.split('@')[0] || normalizedEmail;
+  const slug = kebabGroupName(group);
+  const requester = shortTag(`u:${normalizedEmail}\n${group}`);
+  // A group whose name has no alphanumerics at all (`!!!`) kebabs to '' — the
+  // tags alone still yield a valid, matchable branch.
+  const middle = slug ? `${slug}-` : '';
+  return `${localpart}/join-${middle}${groupTag(group)}-${requester}`;
+}
+
+/**
+ * Does `branch` look like SOMEBODY's join branch for EXACTLY `group`?
+ *
+ * The group half (slug + `groupTag`) is recomputed and must match — this is
+ * what keeps slug-colliding groups (`Finance!` vs `finance`) from seeing,
+ * and worse settling, each other's requests. The requester half cannot be
+ * recomputed (the reader has no email) and matches by shape; the requester's
+ * identity comes from the change request's own attribution.
+ */
+export function isJoinBranchFor(branch: string, group: string): boolean {
+  const slug = kebabGroupName(group);
+  const middle = slug ? `${escapeRegExp(slug)}-` : '';
+  const requester = `[0-9a-z]{${TAG_LENGTH}}`;
+  return new RegExp(`^[^/]+/join-${middle}${groupTag(group)}-${requester}$`).test(branch);
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/workspace/kb-layout.ts

@@ -1,3 +1,5 @@
+import { branchSegment } from '../git/branchAuthor.js';
+
 /**
  * Top-level layout of the KB repo (inside the `KB_DIR_NAME` clone).
  *
@@ -6,19 +8,25 @@
  *
  *   <kbDirName>/
  *   ├── KnowledgeBase/   ← all team ontologies live here (the knowledge graph)
+ *   ├── Groups/          ← one folder per group; each holds BOTH skills and tools
  *   ├── Data/            ← agent-produced records; parsed like KnowledgeBase/
  *   ├── Agents/          ← .agent files — agent role configurations (not the graph)
  *   ├── Pipelines/       ← .pipeline files — execution-layer processes (not the graph)
- *   ├── Skills/          ← reusable agent skills (NOT part of the graph)
- *   ├── Tools/           ← user-authored tool manuals (*.tool; not the graph)
  *   ├── roles.yaml       ← identity → role mapping
  *   └── access.md        ← repo-root access-control rules
  *
+ * RESERVED IS NOT THE SAME AS CREATED. Core seeds the first two only
+ * (`CORE_REQUIRED_DIRS`); `Data/`, `Agents/` and `Pipelines/` scaffold an
+ * agentic execution layer that a distribution layers on. Their names stay here
+ * regardless, because reserving a name is what stops a KB that HAS the folder
+ * from having it treated as ordinary content — the file tree would otherwise
+ * fold it into Knowledge as a stray directory.
+ *
  * These names are the single source of truth for both sides of the app:
  *  - Backend: the graph parser discovers ontologies under the
- *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Skills/`,
- *    `Tools/`, `Agents/`, `Pipelines/` (and anything else at the root) are
- *    ignored by parsing, validation, and the diagram.
+ *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Groups/`,
+ *    `Agents/`, `Pipelines/` (and anything else at the root) are ignored by
+ *    parsing, validation, and the diagram.
  *  - Frontend: the file tree renders these root folders as distinct
  *    top-level sections.
  *
@@ -28,16 +36,76 @@
 /** Folder under the repo root that contains all team ontologies. */
 export const KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
 
-/** Folder under the repo root that holds reusable agent skills (not graph nodes). */
-export const SKILLS_DIR = 'Skills';
+/**
+ * Folder under the repo root that holds the groups.
+ *
+ *   Groups/<Group>/<skill>/SKILL.md   a skill
+ *   Groups/<Group>/<name>.tool        a tool manual
+ *   Groups/<Group>/access.md          who can read/write the whole group
+ *
+ * One folder is one group. Skills and tools live TOGETHER inside it because
+ * they share a single access boundary: a tool a group cannot read is a skill
+ * that group cannot run, so splitting them across two roots meant maintaining
+ * the same permission twice and letting them drift.
+ *
+ * A group is not a registry of unique names — it is a folder. The same
+ * integration may exist in several groups as separate files (`Everyone/
+ * notion.tool` and `Finance/notion.tool`), each with its own credentials and
+ * its own access rule. That duplication is the design, not an accident.
+ */
+export const GROUPS_DIR = 'Groups';
 
 /**
- * Folder under the repo root that holds user-authored tool manuals (`*.tool`
- * files). Each `.tool` is a UTCP manual (inline / http / mcp) that the MCP/UTCP
- * endpoint loads for any user who can read it (access-controlled like Skills).
- * Not part of the knowledge graph.
+ * The reserved name prefix marking a personal folder under `Groups/` —
+ * `Groups/personal-<user-id>/` is where a person's own skills live: created
+ * implicitly on their first personal skill, private by default (its seeded
+ * `access.md` names only its owner), and never listed as a group.
+ *
+ * The marker is STRUCTURAL on purpose: every surface that enumerates groups
+ * (catalog scan, sidebar, counts) filters on the name alone, with no access
+ * lookup needed, and the group-creation endpoint refuses names carrying the
+ * prefix — so a regular group can never squat on someone's personal folder.
+ */
+export const PERSONAL_GROUP_PREFIX = 'personal-';
+
+/**
+ * The one personal folder name for a user — keyed to the STABLE user id, not
+ * the email: emails change, and a folder keyed to one would be orphaned the
+ * day it does. Ids are opaque, so the name carries no PII into git history
+ * (which this platform never rewrites). `branchSegment` is THE segment
+ * sanitizer — the id lands in the folder name exactly as it lands in the
+ * user's suggestion-branch names, so the two spellings can never disagree.
+ */
+export function personalGroupFolderName(userId: string): string {
+  return `${PERSONAL_GROUP_PREFIX}${branchSegment(userId)}`;
+}
+
+/** Whether a `Groups/` child is somebody's personal folder. */
+export function isPersonalGroupFolder(folderName: string): boolean {
+  return folderName.startsWith(PERSONAL_GROUP_PREFIX);
+}
+
+/**
+ * The group a repo-root-relative path belongs to, or `null` for content that
+ * sits outside any group.
+ *
+ *   Groups/GTM/heyreach-campaign/SKILL.md → 'GTM'
+ *   Groups/GTM/heyreach.tool              → 'GTM'
+ *   Groups/loose-skill/SKILL.md           → null    (no group folder)
+ *   KnowledgeBase/Product/…               → null    (not a group root)
+ *
+ * Returns null rather than throwing because a group is a property SOME paths
+ * have. Callers bucket by it; nothing requires it. An ungrouped skill is a
+ * real, supported state — the prototype calls those "yours alone".
  */
-export const TOOLS_DIR = 'Tools';
+export function groupOfPath(repoRelativePath: string): string | null {
+  const segments = repoRelativePath.split('/').filter(Boolean);
+  if (segments[0] !== GROUPS_DIR) return null;
+  // Needs a segment for the group AND at least one below it, otherwise
+  // `Groups/GTM` (the folder itself) would report itself as being in a group,
+  // and a loose `Groups/slack.tool` would report a group named "slack.tool".
+  return segments.length >= 3 ? (segments[1] ?? null) : null;
+}
 
 /**
  * Folder under the repo root for agent-produced records (pipeline instances,
@@ -69,7 +137,7 @@ export const ONTOLOGY_MARKERS = new Set([KNOWLEDGE_DIR, NODETYPE_DIR]);
 
 /**
  * A named ontology id, or `null` for the neutral bucket — content that belongs
- * to no named ontology (root config, `Skills/`, root-level `Knowledge/`, etc.).
+ * to no named ontology (root config, `Groups/`, root-level `Knowledge/`, etc.).
  * The named id is the repo-root-relative path of the ontology directory,
  * e.g. `KnowledgeBase/Product` or `KnowledgeBase/IT Architecture`.
  */