@bevel-software/platform-shared 0.1.0

package/src/workflow/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Workflow vocabulary — the abstraction our app speaks instead of raw git/gh.
+ *
+ * Most types here alias existing engineering types in `@bevel-software/platform-shared/git/*` so
+ * the workflow layer is a single source of truth without duplicating the
+ * payload shapes our backend already produces. The point of the aliases is the
+ * *name*: callers depend on `Change` / `ChangeRequest` / `Branch`, never on
+ * `Commit` / `PullRequest` / `Branch` from the git module. When we eventually
+ * collapse `modules/git` and `modules/review-workflow` into `modules/workflow`,
+ * the alias targets move with the implementation; the consumer-facing names
+ * don't need to.
+ *
+ * New types that have no git counterpart (file locks, change-request open
+ * inputs, conflict-resolution payloads) live here directly.
+ */
+
+import type {
+  BranchInfo,
+  CommitAttribution,
+  ShareChangesRequest,
+  WorkingTreeStatus,
+} from '../git/types.js';
+import type {
+  CancelPrResult,
+  FileApprovalState,
+  MergePrResult,
+  PullRequestDetail,
+  PullRequestState,
+  PullRequestSummary,
+  PostPrCommentInput,
+  PrReviewComment,
+  PullRequestFile,
+} from '../git/pr.types.js';
+
+// ── Branches ─────────────────────────────────────────────────────────────────
+
+/** A variation of the ontology. Protected or not. */
+export type Branch = BranchInfo;
+
+/**
+ * Snapshot of the workspace tied to a branch — currently-checked-out branch,
+ * dirty bit, unshared commit count. Mirrors `WorkingTreeStatus` from the git
+ * module. Renames to `BranchWorkspaceStatus` in the workflow domain to signal
+ * "this describes the branch's workspace state", not raw git plumbing.
+ */
+export type BranchWorkspaceStatus = WorkingTreeStatus;
+
+// ── Changes ──────────────────────────────────────────────────────────────────
+
+/**
+ * A change is the atomic unit of history. Each change affects exactly one file.
+ * Creating an empty folder is modeled as a change creating a `.gitkeep` in it.
+ * Renames are a single change touching one path with the old path removed in
+ * the same atomic operation. Aliases `CommitAttribution` because that's
+ * exactly the shape the backend already returns for a single commit.
+ */
+export type Change = CommitAttribution;
+
+/**
+ * Input shape for committing a change. `summary` is required and single-line;
+ * `description` is optional and supports a multi-line body. Aliases
+ * `ShareChangesRequest` for now — once the workflow module owns the validator
+ * gate end-to-end, this shape may grow workflow-specific fields (lock token,
+ * forced single-path scope).
+ */
+export type ChangeInput = ShareChangesRequest;
+
+// ── File locks (new — no git counterpart) ────────────────────────────────────
+
+/**
+ * A live edit lock on one (branch, path). Per the workflow spec:
+ *   - acquired on first edit in edit mode, or on agent write
+ *   - per-(branch, path); the same file on another branch is independently lockable
+ *   - autosave checkpoint timer extends the lock and produces intermediate changes
+ *   - stale locks (no heartbeat past TTL) auto-release so a disconnected client
+ *     can't hold a file hostage
+ *
+ * Holder identity carries both `userId` (the join key against the users table)
+ * and `holderName` (display name, denormalised so consumers can render a
+ * "locked by Alice" badge without an extra round-trip). For agent-driven
+ * writes the holder is the user driving the agent.
+ */
+export interface FileLock {
+  branch: string;
+  path: string;
+  holderUserId: string;
+  holderName: string;
+  /** ISO timestamp when the lock was first acquired. */
+  acquiredAt: string;
+  /** ISO timestamp of the most recent heartbeat — the autosave/keepalive ping. */
+  lastHeartbeatAt: string;
+  /** ISO timestamp after which a non-heartbeated lock is considered stale and may be reclaimed. */
+  expiresAt: string;
+}
+
+/**
+ * Result of attempting to acquire a lock. `acquired: false` carries the
+ * current holder so the UI can render "Locked by X" without a follow-up call.
+ */
+export type AcquireLockResult =
+  | { acquired: true; lock: FileLock }
+  | { acquired: false; lock: FileLock };
+
+// ── Change Requests ──────────────────────────────────────────────────────────
+
+/**
+ * A change request is the reconciliation of two branches. In the current
+ * implementation this is backed by a GitHub pull request; the alias hides
+ * that from callers. `state` values map 1:1 (`open`/`merged`/`closed`).
+ *
+ * Opening a change request is defined in the spec as auto-merging target →
+ * source first; that part isn't yet implemented in the backing services, so
+ * `openChangeRequest` on `IWorkflowService` currently throws
+ * `NotImplementedWorkflowError`.
+ */
+export type ChangeRequest = PullRequestSummary;
+export type ChangeRequestDetail = PullRequestDetail;
+export type ChangeRequestState = PullRequestState;
+export type ChangedFile = PullRequestFile;
+
+export type FileApproval = FileApprovalState;
+export type MergeChangeRequestResult = MergePrResult;
+export type CancelChangeRequestResult = CancelPrResult;
+export type ChangeRequestComment = PrReviewComment;
+export type PostChangeRequestCommentInput = PostPrCommentInput;
+
+/**
+ * Input for opening a new change request. The workflow auto-merges
+ * `targetBranch` into `sourceBranch` as part of opening, so callers don't
+ * pass a head SHA — the workflow resolves the head itself.
+ *
+ * `title` + `description` are the change request's metadata; the description
+ * is plain text (no GitHub-flavoured markdown affordances exposed at this
+ * layer). The implementation may still render this as the PR body when the
+ * underlying GitHub PR is created.
+ */
+export interface OpenChangeRequestInput {
+  sourceBranch: string;
+  targetBranch: string;
+  title: string;
+  description?: string;
+}
+
+/**
+ * Result of asking the workflow to merge a change request. Mirrors
+ * `MergePrResult` — caller learns the resulting change (commit) sha and the
+ * timestamp the merge landed.
+ *
+ * When the merge attempt hits conflicts the workflow falls back to an
+ * agent-driven resolution path; the caller does NOT get a `MergeChangeRequestResult`
+ * back in that case — they get a `ConflictPending` shape instead so the UI
+ * can route into the resolution flow.
+ */
+export type MergeChangeRequestOutcome =
+  | { kind: 'merged'; result: MergeChangeRequestResult }
+  | { kind: 'conflicts-need-resolution'; conflictedPaths: string[] };

package/src/workspace/filename.ts

@@ -0,0 +1,102 @@
+/**
+ * Cross-platform filename validation. A name that passes here must be writable
+ * as-is on Windows (NTFS), macOS (APFS), and Linux (ext4) — so the same
+ * workspace can round-trip between dev machines, the backend container, and
+ * any user's local clone without `git checkout` failing on a forbidden name.
+ *
+ * Used by:
+ *  - frontend: gate the create / rename inputs in FileExplorer
+ *  - backend: reject API requests at the workspace service boundary
+ *  - agent prompt: the same rules are described to the LLM so it picks valid
+ *    names when authoring KB files
+ *
+ * Keep this file dependency-free — both bundle targets import it directly.
+ */
+
+/** Windows-reserved device names. Case-insensitive; the bare name AND
+ *  `<name>.<ext>` are both reserved (e.g. `NUL.txt` is invalid on Windows). */
+const WINDOWS_RESERVED_NAMES = new Set([
+  'CON', 'PRN', 'AUX', 'NUL',
+  'COM0', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+  'LPT0', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+]);
+
+/** Characters Windows forbids in any filename component. `/` is the path
+ *  separator on Unix, included for the same reason. `\` is also a path
+ *  separator on Windows. Control chars (0x00–0x1F) are rejected separately. */
+// eslint-disable-next-line no-control-regex
+const FORBIDDEN_CHARS = /[<>:"/\\|?*\x00-\x1F]/;
+
+/** Per-component byte limit: NTFS = 255 UTF-16 units, ext4 = 255 bytes,
+ *  APFS = 255 UTF-8 bytes. Use UTF-8 bytes — the strictest of the three. */
+const MAX_NAME_BYTES = 255;
+
+const utf8 = new TextEncoder();
+
+/**
+ * Validate a single path component (file or folder name — no `/`, no `\`).
+ * Returns `null` if valid, or a short reason string suitable for surfacing
+ * in a UI error or API 400 body.
+ */
+export function validateFilename(name: string): string | null {
+  if (typeof name !== 'string') return 'Name is required';
+  if (name.length === 0) return 'Name cannot be empty';
+  if (name !== name.trim()) return 'Name cannot start or end with whitespace';
+  if (name === '.' || name === '..') return 'Name cannot be "." or ".."';
+
+  if (FORBIDDEN_CHARS.test(name)) {
+    return 'Name cannot contain any of these characters: < > : " / \\ | ? *';
+  }
+
+  // Windows trims trailing dots and spaces silently — a name ending in either
+  // becomes a different filename on disk, breaking sync between OSes.
+  if (name.endsWith('.') || name.endsWith(' ')) {
+    return 'Name cannot end with a "." or a space';
+  }
+
+  // Windows reserved device names — match `NAME` and `NAME.ext`, case-insensitive.
+  const stem = name.split('.')[0].toUpperCase();
+  if (WINDOWS_RESERVED_NAMES.has(stem)) {
+    return `"${name}" is a reserved system name on Windows`;
+  }
+
+  if (utf8.encode(name).length > MAX_NAME_BYTES) {
+    return `Name is too long (max ${MAX_NAME_BYTES} bytes)`;
+  }
+
+  return null;
+}
+
+/**
+ * Validate a workspace-relative path: a `/`-separated string of components.
+ * Each component is checked with {@link validateFilename}. Backslashes are
+ * rejected outright — the workspace API uses `/` everywhere and accepting
+ * `\` would round-trip differently on Windows vs the Linux container.
+ */
+export function validateRelativePath(relativePath: string): string | null {
+  if (typeof relativePath !== 'string' || relativePath.length === 0) {
+    return 'Path is required';
+  }
+  if (relativePath.includes('\\')) {
+    return 'Path cannot contain "\\" — use "/" as the separator';
+  }
+  // Strip a single leading `./` so callers that build paths from a base dir
+  // (`./<name>`) don't get a spurious "." segment rejection.
+  const normalized = relativePath.replace(/^\.\//, '');
+  const segments = normalized.split('/').filter((s) => s.length > 0);
+  if (segments.length === 0) return 'Path is required';
+  for (const segment of segments) {
+    const reason = validateFilename(segment);
+    if (reason) return `Invalid path segment "${segment}": ${reason}`;
+  }
+  return null;
+}
+
+/**
+ * Throwing wrapper for the backend service layer — keeps call sites a single
+ * line and produces a clear `Error` the route handler can surface as a 400.
+ */
+export function assertValidRelativePath(relativePath: string): void {
+  const reason = validateRelativePath(relativePath);
+  if (reason) throw new Error(`Invalid path: ${reason}`);
+}

package/src/workspace/frontmatter.ts

@@ -0,0 +1,45 @@
+/**
+ * The ONE `---` frontmatter splitter, shared by backend and frontend so no file
+ * type grows its own regex. Splits a leading `---`-fenced YAML block from the
+ * body; null when the text doesn't open with a fence. Parsing the YAML inside is
+ * the caller's concern (the access-control resolver deliberately keeps its own
+ * hardened line-based reader — see `modules/access/access-splice.ts`).
+ */
+export function extractFrontmatter(text: string): { frontmatter: string; body: string } | null {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return null;
+  return { frontmatter: m[1], body: m[2] };
+}
+
+/**
+ * Set a top-level scalar key in a file's `---` frontmatter, LINE-based: replace an
+ * existing `<key>:` line's value, else insert `<key>: <value>` at the top of the
+ * block (creating a `---` block if the file has none). Deliberately NOT a
+ * parse-and-re-serialize — a KB node's `nodeType:` quoted-markdown-link and access
+ * lines are read by a hand-rolled regex parser that a full YAML re-emit would
+ * corrupt, so every other line is preserved byte-for-byte. `value` is emitted as a
+ * bare scalar; callers pass simple id/name strings (no quoting/escaping needed for
+ * the `[a-z0-9_-]` id grammar).
+ */
+export function setFrontmatterField(text: string, key: string, value: string): string {
+  const fm = extractFrontmatter(text);
+  const line = `${key}: ${value}`;
+  // Escape the key before interpolating — callers pass plain `id`/`name`, but a
+  // metacharacter must never silently change what the line-matcher matches.
+  const keyRe = new RegExp(`^(\\s*)${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:.*$`);
+  // Preserve the file's own line-ending convention: rebuilding a CRLF file with
+  // bare `\n` would dirty every frontmatter line, breaking the byte-for-byte
+  // guarantee this helper exists for. Judged from the FIRST line ending (the
+  // fence line's own), so a stray CRLF deep in the body can't flip the block.
+  const firstNl = text.indexOf('\n');
+  const eol = firstNl > 0 && text[firstNl - 1] === '\r' ? '\r\n' : '\n';
+  if (!fm) {
+    // No frontmatter — prepend a fresh block, keeping the original body intact.
+    return `---${eol}${line}${eol}---${eol}${text}`;
+  }
+  const fmLines = fm.frontmatter.split(/\r?\n/);
+  const idx = fmLines.findIndex((l) => keyRe.test(l));
+  if (idx >= 0) fmLines[idx] = line;
+  else fmLines.unshift(line);
+  return `---${eol}${fmLines.join(eol)}${eol}---${eol}${fm.body}`;
+}

package/src/workspace/kb-layout.ts

@@ -0,0 +1,81 @@
+/**
+ * Top-level layout of the KB repo (inside the `KB_DIR_NAME` clone).
+ *
+ * The repo root holds a small, fixed set of special folders that the app
+ * treats distinctly:
+ *
+ *   <kbDirName>/
+ *   ├── KnowledgeBase/   ← all team ontologies live here (the knowledge graph)
+ *   ├── 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
+ *
+ * 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.
+ *  - Frontend: the file tree renders these root folders as distinct
+ *    top-level sections.
+ *
+ * Don't hard-code these strings elsewhere — import them from here.
+ */
+
+/** 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 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.
+ */
+export const TOOLS_DIR = 'Tools';
+
+/**
+ * Folder under the repo root for agent-produced records (pipeline instances,
+ * work items, intermediate outputs). Parsed exactly like `KnowledgeBase/`:
+ * its direct subfolders are self-contained ontologies.
+ */
+export const DATA_DIR = 'Data';
+
+/** Folder under the repo root that holds `.agent` files — agent role configurations (not graph nodes). */
+export const AGENTS_DIR = 'Agents';
+
+/** Folder under the repo root that holds `.pipeline` files — execution-layer processes (not graph nodes). */
+export const PIPELINES_DIR = 'Pipelines';
+
+/**
+ * The roots whose subfolders are discovered as ontologies by the graph parser
+ * (each subfolder with both `NodeTypes/` and `Knowledge/` is an ontology).
+ */
+export const ONTOLOGY_ROOTS: readonly string[] = [KNOWLEDGE_BASE_DIR, DATA_DIR];
+
+/** The `Knowledge/` marker subfolder of an ontology (holds the graph nodes). */
+export const KNOWLEDGE_DIR = 'Knowledge';
+
+/** The `NodeTypes/` marker subfolder of an ontology (holds the type definitions). */
+export const NODETYPE_DIR = 'NodeTypes';
+
+/** The marker subfolders that make a directory an ontology (it needs BOTH). */
+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.).
+ * The named id is the repo-root-relative path of the ontology directory,
+ * e.g. `KnowledgeBase/Product` or `KnowledgeBase/IT Architecture`.
+ */
+export type Ontology = string | null;
+
+// The implementation that resolves a path to its `Ontology` (`ontologyOf`) is
+// backend-only — it lives in `packages/backend/src/shared/kb-layout.ts`, built
+// from the `KNOWLEDGE_BASE_DIR` / `ONTOLOGY_MARKERS` constants above. This
+// package holds only the cross-cutting constants and types, not logic.

package/src/workspace/types.ts

@@ -0,0 +1,59 @@
+export interface WorkspaceInfo {
+  /**
+   * Workspace id = `encodeURIComponent(branch)`. Stable across users — a
+   * branch's workspace is shared by everyone editing it (PLAN §3).
+   * Decoding rule: callers can derive the branch via
+   * `decodeURIComponent(id)` without a backend round-trip.
+   */
+  id: string;
+  /** Display name. Currently the branch name verbatim. */
+  name: string;
+  /** Absolute path on the backend's filesystem (debug / log surface only). */
+  absolutePath: string;
+  /** ISO timestamp. Per-branch workspaces have no meaningful creation time; epoch is fine. */
+  createdAt: string;
+  /**
+   * Directory name (relative to `absolutePath`) where the KB clone lives.
+   * Configured via `KB_DIR_NAME` on the backend; surfaced to the frontend
+   * so renderers and chat cards can build correct KB-relative paths
+   * without hardcoding the repo name.
+   */
+  kbDirName: string;
+}
+
+export interface FileTreeEntry {
+  name: string;
+  relativePath: string;
+  type: 'file' | 'directory';
+  children?: FileTreeEntry[];
+}
+
+import type { AuthUser } from '../auth/types.js';
+
+export interface IWorkspaceService {
+  /**
+   * Get-or-create the workspace for a branch. Workspaces are per-branch
+   * (PLAN §3) — every user editing `branch` shares the same on-disk clone,
+   * coordinated by the file-lock service.
+   */
+  getOrCreateForBranch(branch: string): Promise<WorkspaceInfo>;
+  /**
+   * Convenience wrapper that defaults to the configured default branch
+   * (`DEFAULT_BRANCH`) when no branch is provided. Kept on the interface so route handlers that
+   * receive a logged-in user but no explicit branch can still bootstrap a
+   * workspace.
+   */
+  getOrCreateForUser(user: AuthUser, branch?: string): Promise<WorkspaceInfo>;
+  getMetadata(workspaceId: string): Promise<WorkspaceInfo | null>;
+  deleteWorkspace(workspaceId: string): Promise<void>;
+  listFiles(workspaceId: string): Promise<FileTreeEntry>;
+  readFile(workspaceId: string, relativePath: string): Promise<string>;
+  writeFile(workspaceId: string, relativePath: string, content: string): Promise<void>;
+  createDirectory(workspaceId: string, relativePath: string): Promise<void>;
+  writeFileBinary(workspaceId: string, relativePath: string, data: Uint8Array): Promise<void>;
+  deleteFile(workspaceId: string, relativePath: string): Promise<void>;
+  moveEntry(workspaceId: string, oldRelativePath: string, newRelativePath: string): Promise<void>;
+  getWorkspacePath(workspaceId: string): Promise<string>;
+  /** Remove the workspace's transient `tmp/` dir (staged docs, tool-chain spills). */
+  clearTmp(workspaceId: string): Promise<void>;
+}