@bevel-software/platform-shared 0.1.0

package/dist/git/protected.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Authoritative, env-overridable registry of the default branch + the set of
+ * protected branch slugs in the KB repo, plus their user-visible display names.
+ *
+ * Single source of truth for BOTH sides of the app:
+ *  - Backend (Node) reads `process.env.*` at runtime — the values are populated
+ *    from the environment / the `.env` loaded by `config.ts`, which runs before
+ *    this module is first evaluated (see `backend/src/index.ts` import order).
+ *  - Frontend (browser) can't read `process.env` at runtime, so Vite statically
+ *    replaces the `process.env.DEFAULT_BRANCH` / `process.env.PROTECTED_BRANCHES`
+ *    references at build time via `define` in `frontend/vite.config.ts`. Keep
+ *    those references written as the literal `process.env.<NAME>` member access
+ *    so the static replacement keeps matching.
+ *
+ * Both the backend (server-side enforcement — refusing commit/push/revert and
+ * rejecting `createBranch` on protected names) and the frontend (disabling UI
+ * actions, showing the protected-branch banner, branch sort order) consume this
+ * single table so the two can never drift. Don't re-declare or hard-code the
+ * names elsewhere.
+ *
+ * Env vars (both REQUIRED — no fallback; the module throws at load if either is
+ * missing/empty, so a misconfigured deploy fails fast instead of silently
+ * defaulting to the wrong branches). Note the frontend needs them present at
+ * BUILD time (Vite `define`), the backend at runtime:
+ *  - `DEFAULT_BRANCH`      — the branch a user lands on / the default propose
+ *                            target.
+ *  - `PROTECTED_BRANCHES`  — comma/space-separated list of protected slugs.
+ *                            Display names are auto-derived from each slug
+ *                            (`target-company-state` → "Target company state").
+ */
+/**
+ * The branch a logged-in user lands on when they don't explicitly pick one, and
+ * the default destination for shared drafts. Env-overridable via `DEFAULT_BRANCH`.
+ */
+export declare const DEFAULT_BRANCH: string;
+export declare const PROTECTED_BRANCH_DISPLAY_NAMES: Readonly<Record<string, string>>;
+export declare const PROTECTED_BRANCHES: ReadonlySet<string>;
+export declare function isProtectedBranch(name: string | null | undefined): boolean;
+/**
+ * Capitalised, human-readable name for a protected branch — e.g.
+ * `current-company-state` → "Current company state".
+ *
+ * Use this everywhere the branch name appears in user-visible body copy
+ * (banners, tooltips, button labels). The raw kebab slug is fine in small
+ * monospace badges for power users / debug surfaces, but body copy should
+ * never read "merge into current-company-state" to a non-developer.
+ *
+ * Returns `null` for unknown / non-protected names so the caller can decide
+ * whether to fall back to the raw string or hide the affordance.
+ */
+export declare function protectedBranchDisplayName(name: string | null | undefined): string | null;
+//# sourceMappingURL=protected.d.ts.map

package/dist/git/protected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected.d.ts","sourceRoot":"","sources":["../../src/git/protected.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA4BH;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAkD,CAAC;AA0BhF,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzE,CAAC;AAEJ,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAkC,CAAC;AAEtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAK1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,MAAM,GAAG,IAAI,CAGf"}

package/dist/git/protected.js

@@ -0,0 +1,92 @@
+/**
+ * Authoritative, env-overridable registry of the default branch + the set of
+ * protected branch slugs in the KB repo, plus their user-visible display names.
+ *
+ * Single source of truth for BOTH sides of the app:
+ *  - Backend (Node) reads `process.env.*` at runtime — the values are populated
+ *    from the environment / the `.env` loaded by `config.ts`, which runs before
+ *    this module is first evaluated (see `backend/src/index.ts` import order).
+ *  - Frontend (browser) can't read `process.env` at runtime, so Vite statically
+ *    replaces the `process.env.DEFAULT_BRANCH` / `process.env.PROTECTED_BRANCHES`
+ *    references at build time via `define` in `frontend/vite.config.ts`. Keep
+ *    those references written as the literal `process.env.<NAME>` member access
+ *    so the static replacement keeps matching.
+ *
+ * Both the backend (server-side enforcement — refusing commit/push/revert and
+ * rejecting `createBranch` on protected names) and the frontend (disabling UI
+ * actions, showing the protected-branch banner, branch sort order) consume this
+ * single table so the two can never drift. Don't re-declare or hard-code the
+ * names elsewhere.
+ *
+ * Env vars (both REQUIRED — no fallback; the module throws at load if either is
+ * missing/empty, so a misconfigured deploy fails fast instead of silently
+ * defaulting to the wrong branches). Note the frontend needs them present at
+ * BUILD time (Vite `define`), the backend at runtime:
+ *  - `DEFAULT_BRANCH`      — the branch a user lands on / the default propose
+ *                            target.
+ *  - `PROTECTED_BRANCHES`  — comma/space-separated list of protected slugs.
+ *                            Display names are auto-derived from each slug
+ *                            (`target-company-state` → "Target company state").
+ */
+function parseBranchList(raw) {
+    return (raw ?? '')
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Human-readable name derived from a kebab/snake slug: lowercase words joined by
+ * spaces with only the first letter capitalised — e.g. `target-company-state` →
+ * "Target company state". Matches the historical hand-written display names.
+ */
+function deriveDisplayName(slug) {
+    const spaced = slug.replace(/[-_]+/g, ' ').trim();
+    if (!spaced)
+        return slug;
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * The branch a logged-in user lands on when they don't explicitly pick one, and
+ * the default destination for shared drafts. Env-overridable via `DEFAULT_BRANCH`.
+ */
+export const DEFAULT_BRANCH = (process.env.DEFAULT_BRANCH ?? '').trim();
+if (!DEFAULT_BRANCH) {
+    throw new Error('DEFAULT_BRANCH env var is required (no fallback). Set it on the backend ' +
+        'runtime and at the frontend build (Vite reads it via define).');
+}
+const PROTECTED_BRANCH_LIST = parseBranchList(process.env.PROTECTED_BRANCHES);
+if (PROTECTED_BRANCH_LIST.length === 0) {
+    throw new Error('PROTECTED_BRANCHES env var is required (no fallback). Provide a ' +
+        'comma/space-separated list of protected branch slugs.');
+}
+// The default branch is where users land and the default propose target — it
+// must itself be protected, or `isProtectedBranch(DEFAULT_BRANCH)` is false and
+// the protected-branch guards silently don't apply to it. Fail fast on a
+// misconfigured pair rather than shipping that inconsistency.
+if (!PROTECTED_BRANCH_LIST.includes(DEFAULT_BRANCH)) {
+    throw new Error(`DEFAULT_BRANCH ("${DEFAULT_BRANCH}") must be one of PROTECTED_BRANCHES ` +
+        `(${PROTECTED_BRANCH_LIST.join(', ')}).`);
+}
+export const PROTECTED_BRANCH_DISPLAY_NAMES = Object.freeze(Object.fromEntries(PROTECTED_BRANCH_LIST.map((slug) => [slug, deriveDisplayName(slug)])));
+export const PROTECTED_BRANCHES = new Set(PROTECTED_BRANCH_LIST);
+export function isProtectedBranch(name) {
+    return !!name && Object.prototype.hasOwnProperty.call(PROTECTED_BRANCH_DISPLAY_NAMES, name);
+}
+/**
+ * Capitalised, human-readable name for a protected branch — e.g.
+ * `current-company-state` → "Current company state".
+ *
+ * Use this everywhere the branch name appears in user-visible body copy
+ * (banners, tooltips, button labels). The raw kebab slug is fine in small
+ * monospace badges for power users / debug surfaces, but body copy should
+ * never read "merge into current-company-state" to a non-developer.
+ *
+ * Returns `null` for unknown / non-protected names so the caller can decide
+ * whether to fall back to the raw string or hide the affordance.
+ */
+export function protectedBranchDisplayName(name) {
+    if (!name)
+        return null;
+    return PROTECTED_BRANCH_DISPLAY_NAMES[name] ?? null;
+}
+//# sourceMappingURL=protected.js.map

package/dist/git/protected.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected.js","sourceRoot":"","sources":["../../src/git/protected.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAUH,SAAS,eAAe,CAAC,GAAuB;IAC9C,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;SACf,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAW,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAChF,IAAI,CAAC,cAAc,EAAE,CAAC;IACpB,MAAM,IAAI,KAAK,CACb,0EAA0E;QACxE,+DAA+D,CAClE,CAAC;AACJ,CAAC;AAED,MAAM,qBAAqB,GAAa,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AACxF,IAAI,qBAAqB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IACvC,MAAM,IAAI,KAAK,CACb,kEAAkE;QAChE,uDAAuD,CAC1D,CAAC;AACJ,CAAC;AACD,6EAA6E;AAC7E,gFAAgF;AAChF,yEAAyE;AACzE,8DAA8D;AAC9D,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;IACpD,MAAM,IAAI,KAAK,CACb,oBAAoB,cAAc,uCAAuC;QACvE,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC3C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,8BAA8B,GACzC,MAAM,CAAC,MAAM,CACX,MAAM,CAAC,WAAW,CAChB,qBAAqB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CACrE,CACF,CAAC;AAEJ,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAEtF,MAAM,UAAU,iBAAiB,CAAC,IAA+B;IAC/D,OAAO,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CACnD,8BAA8B,EAC9B,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAA+B;IAE/B,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,8BAA8B,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACtD,CAAC"}

package/dist/git/review.types.d.ts

@@ -0,0 +1,49 @@
+export type ChangeKind = 'added' | 'modified' | 'deleted' | 'renamed';
+/**
+ * A single pending change — the diff between the on-disk backup ledger
+ * (the user's last-confirmed state) and the current working tree for one path.
+ */
+export interface PendingChange {
+    /** Current path (for added/modified/renamed) or original path (for deleted). */
+    path: string;
+    /** Populated only when kind === 'renamed' — the pre-rename path. */
+    oldPath?: string;
+    kind: ChangeKind;
+    isBinary: boolean;
+    /**
+     * Line counts from an LCS diff. Null in two cases:
+     * - the file is binary (no line concept), or
+     * - the text diff exceeds the backend's LCS cap and exact counts were
+     *   skipped to avoid OOM. Consumers should treat null as "not computed".
+     */
+    linesAdded: number | null;
+    linesRemoved: number | null;
+}
+/**
+ * Pending-changes envelope returned by the review API. Backed by the
+ * on-disk backup ledger (a sibling-to-workspaces folder containing each
+ * diffable file's last-confirmed contents). `baselineRef` is retained for
+ * wire-shape compatibility but is empty under the backup-folder model;
+ * the frontend reads `changes` and `branchName` only.
+ */
+export interface ReviewSession {
+    branchName: string;
+    /** Always empty in the backup-folder model — kept for wire compatibility. */
+    baselineRef: string;
+    createdAt: string;
+    changes: PendingChange[];
+}
+/**
+ * Full before/after content for one path in an active session. The UI renders
+ * this through a line-level LCS diff.
+ */
+export interface FileDiffPayload {
+    path: string;
+    kind: ChangeKind;
+    /** Content at the baseline. Null for `added` or binary files. */
+    baseline: string | null;
+    /** Current working-tree content. Null for `deleted` or binary files. */
+    current: string | null;
+    isBinary: boolean;
+}
+//# sourceMappingURL=review.types.d.ts.map

package/dist/git/review.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.types.d.ts","sourceRoot":"","sources":["../../src/git/review.types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB"}

package/dist/git/review.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=review.types.js.map

package/dist/git/review.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.types.js","sourceRoot":"","sources":["../../src/git/review.types.ts"],"names":[],"mappings":""}

package/dist/git/types.d.ts

@@ -0,0 +1,107 @@
+import type { AuthUser } from '../auth/types.js';
+export interface BranchInfo {
+    name: string;
+    isProtected: boolean;
+    ahead: number | null;
+    behind: number | null;
+    /**
+     * True iff `refs/remotes/origin/<name>` exists after the last `fetch --prune`.
+     * False means the branch is local-only — either never pushed, or its remote
+     * counterpart was deleted (typically after a PR merged + branch cleanup on
+     * GitHub). The UI uses this to offer a "delete local branch" affordance.
+     */
+    hasRemote: boolean;
+}
+/**
+ * Per-workspace branch sync state. Slimmed down from the legacy
+ * "one workspace, many branches via checkout" model: fields like `isDirty`,
+ * `unpushedCommits`, and `conflicted` are gone because save=share guarantees
+ * the working tree is never dirty, there are no committed-but-unpushed
+ * commits, and conflicts are resolved before lock release. What's left is
+ * the upstream-sync signal that drives the auto-update flow + the branch
+ * name (kept as a server-side cross-check against the URL-derived branch).
+ */
+export interface WorkingTreeStatus {
+    branch: string;
+    hasUpstream: boolean;
+    unmergedFromUpstream: boolean;
+}
+export interface CommitAttribution {
+    authorName: string;
+    authorEmail: string;
+    sha: string;
+    subject: string;
+    committedAt: string;
+}
+export interface ShareChangesRequest {
+    summary: string;
+    description?: string;
+}
+export interface ValidationReport {
+    ok: boolean;
+    mustFix: string[];
+    warnings: string[];
+    rawOutput: string;
+}
+export interface IGitService {
+    status(workspaceId: string): Promise<WorkingTreeStatus>;
+    listBranches(workspaceId: string, opts?: {
+        freshFetch?: boolean;
+    }): Promise<BranchInfo[]>;
+    createBranch(workspaceId: string, name: string, fromBase?: string): Promise<BranchInfo>;
+    /**
+     * Delete a branch. Removes the local ref (if present) AND the origin ref
+     * (if present); both sides go in one call so the picker's "discard draft"
+     * affordance leaves no orphan behind.
+     *
+     * Authorisation: the branch's author OR an admin can delete it. Authorship
+     * is inferred from the `<email-localpart>/...` naming convention — see
+     * `isBranchAuthoredBy`. Admins (per the workspace's `roles.yaml`) can
+     * additionally remove unprefixed CLI-created branches that have no
+     * recognisable author.
+     *
+     * `onlyIfNoRemote: true` is the legacy orphan-cleanup path used after a
+     * PR merge prunes the remote head: it BYPASSES the author/admin check
+     * (callers prune any orphan they encounter) and REFUSES if origin still
+     * has the ref (the safety property the flag has always provided).
+     * Protected branches and the currently-checked-out branch are always
+     * rejected.
+     */
+    deleteBranch(workspaceId: string, name: string, user: AuthUser, opts?: {
+        onlyIfNoRemote?: boolean;
+    }): Promise<void>;
+    commit(workspaceId: string, user: AuthUser, req: ShareChangesRequest): Promise<CommitAttribution>;
+    push(workspaceId: string, user: AuthUser): Promise<void>;
+    fetch(workspaceId: string): Promise<void>;
+    pull(workspaceId: string): Promise<void>;
+    diffStat(workspaceId: string, base?: string): Promise<string[]>;
+    /**
+     * Paths in the working tree that the next commit would include — the set
+     * `git add -A` would stage: modified + deleted + renamed + untracked files
+     * (honouring `.gitignore`). Use this for share-dialog previews; for the
+     * committed delta vs a base ref (e.g. PR owner lookup), use `diffStat`.
+     */
+    pendingChanges(workspaceId: string): Promise<string[]>;
+    /**
+     * Best-fit protected branch a feature branch was forked from, resolved by
+     * picking whichever protected branch on origin yields the smallest "ahead"
+     * 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, limit?: number): Promise<CommitAttribution[]>;
+    diffFileAtCommit(workspaceId: string, relativePath: string, sha: string): Promise<string>;
+    /**
+     * Unified diff of a single file between two branches. Both names must
+     * resolve to a known branch on this workspace (local head or
+     * `refs/remotes/origin/<name>`); arbitrary refspecs and SHAs are
+     * rejected upstream. Returns the raw `git diff` output — empty string
+     * when the file is identical on both sides, a unified-diff body
+     * otherwise (including the "new file mode" / "deleted file mode"
+     * headers when the file only exists on one side).
+     *
+     * Read-only: nothing is checked out, fetched, or written.
+     */
+    diffFileBetweenBranches(workspaceId: string, relativePath: string, fromBranch: string, toBranch: string): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/git/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/git/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/git/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './auth/types.js';
+export * from './chat/types.js';
+export * from './workspace/types.js';
+export * from './workspace/filename.js';
+export * from './workspace/kb-layout.js';
+export * from './workspace/frontmatter.js';
+export * from './git/types.js';
+export * from './git/pr.types.js';
+export * from './git/protected.js';
+export * from './git/branchAuthor.js';
+export * from './git/review.types.js';
+export * from './workflow/types.js';
+export * from './workflow/interface.js';
+export * from './workflow/events.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+// Auth
+export * from './auth/types.js';
+// Chat
+export * from './chat/types.js';
+// Workspace
+export * from './workspace/types.js';
+export * from './workspace/filename.js';
+export * from './workspace/kb-layout.js';
+export * from './workspace/frontmatter.js';
+// Git
+export * from './git/types.js';
+export * from './git/pr.types.js';
+export * from './git/protected.js';
+export * from './git/branchAuthor.js';
+export * from './git/review.types.js';
+// Workflow — abstraction layer over git/PR/review-workflow. See PLAN.md.
+export * from './workflow/types.js';
+export * from './workflow/interface.js';
+export * from './workflow/events.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO;AACP,cAAc,iBAAiB,CAAC;AAEhC,OAAO;AACP,cAAc,iBAAiB,CAAC;AAEhC,YAAY;AACZ,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAE3C,MAAM;AACN,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AAEtC,yEAAyE;AACzE,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC"}

package/dist/workflow/events.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Workflow event bus types — what the backend pushes over SSE to keep the
+ * frontend in sync with state changes, including those triggered by other
+ * users on the same branch or by the agent acting server-side.
+ *
+ * **Scope model** — events have one of three scopes, set by the variant:
+ *
+ *   - **Workspace-scoped** (`workspaceId` field). Pushed to every connected
+ *     session whose current focus is `workspaceId`. Examples: a file changed
+ *     on this branch, someone took the lock on a file. Anyone editing this
+ *     branch cares.
+ *
+ *   - **User-scoped** (`forUserId` field, no `workspaceId`). Pushed only to
+ *     sessions opened by `forUserId`, regardless of their current focus.
+ *     Examples: an agent turn called a tool on your behalf, your view should
+ *     navigate to a different branch. Other users on the same branch don't
+ *     care.
+ *
+ *   - **Global** (no `workspaceId`, no `forUserId`). Pushed to every
+ *     authenticated session. Examples: change requests opening / merging /
+ *     being rejected — any user with access to the repo might care.
+ *
+ * **Identity + replay** — every event carries an `id` (monotonic int) and an
+ * ISO `ts`. Clients reconnecting with `Last-Event-ID: <id>` get the buffered
+ * tail replayed (server's ring buffer is finite — see `WorkflowEventBus`).
+ * If `id` is older than what the buffer still has, the server sends a
+ * `{ kind: 'resync' }` instead so the client refetches the world cleanly.
+ *
+ * **Idempotency over exactly-once** — clients tolerate duplicates and
+ * out-of-order delivery: every payload carries enough state for the UI to
+ * reach the right end state regardless of how many times it sees the event
+ * (e.g. `file-changed` includes the new SHA — UI only refreshes if the open
+ * tab's SHA differs).
+ */
+export interface WorkflowEventEnvelope {
+    /** Monotonic, process-local. Used for `Last-Event-ID` replay. */
+    id: number;
+    /** ISO timestamp the event was emitted on the backend. */
+    ts: string;
+}
+/**
+ * A file's content changed on disk — fires for ANY write that lands bytes
+ * for `(workspaceId, branch, path)`, whether or not a commit followed.
+ *
+ *   - **`newSha` set** → a commit landed. The disk write came through the
+ *     full lock-release pipeline (acquire → write → commitFile → push).
+ *     History views should refetch.
+ *
+ *   - **`newSha === null`** → disk bytes changed but no commit yet, i.e.
+ *     the writer is mid-edit (lock still held — e.g. the editor's Ctrl+S
+ *     autosave-to-disk before the final Save click). Watchers should
+ *     refetch content but NOT history (nothing new in git log).
+ *
+ * Emitted from both the human PUT/PATCH/DELETE routes and the agent's
+ * LockingFilesystem so anyone tailing the file sees changes immediately.
+ */
+export interface FileChangedEvent {
+    kind: 'file-changed';
+    workspaceId: string;
+    branch: string;
+    path: string;
+    /** Commit sha if a commit landed; null if this was a disk-only write. */
+    newSha: string | null;
+    /** The user whose write caused the change. */
+    byUserId: string;
+    byUserName: string;
+}
+/** Someone (`holderUserId`) just acquired the lock on `(branch, path)`. */
+export interface LockAcquiredEvent {
+    kind: 'lock-acquired';
+    workspaceId: string;
+    branch: string;
+    path: string;
+    holderUserId: string;
+    holderName: string;
+}
+/** The lock on `(branch, path)` was released — file is free for the next caller. */
+export interface LockReleasedEvent {
+    kind: 'lock-released';
+    workspaceId: string;
+    branch: string;
+    path: string;
+}
+/**
+ * The file tree for `(workspaceId, branch)` changed in a way that's not
+ * captured by a single `file-changed` event — typically a recursive delete,
+ * a move, or an unzip extracting many files. Emitted alongside per-file
+ * `file-changed` events, but lets the file explorer refresh once instead of
+ * N times.
+ */
+export interface FsTreeChangedEvent {
+    kind: 'fs-tree-changed';
+    workspaceId: string;
+    branch: string;
+}
+/**
+ * Agent called `switch_branch` mid-turn and the target validated +
+ * pre-warmed successfully. Tells the frontend to navigate to the new draft
+ * once the in-flight chat turn completes — navigation mid-stream would tear
+ * down the chat connection. The chat hook stashes the latest pending
+ * destination and consumes it in `onFinish`. The native chat path stamps the
+ * `threadId`; the registry `switch_branch` tool (called over the internal
+ * loopback, which carries no threadId) omits it, so the frontend keys the
+ * pending destination on `forUserId` — a user has one active chat stream.
+ *
+ * User-scoped (no `workspaceId`) — only the user whose agent ran the tool
+ * should follow; other users on the same branch don't care.
+ */
+export interface BranchSwitchedEvent {
+    kind: 'branch-switched';
+    forUserId: string;
+    threadId?: string;
+    branch: string;
+    workspaceId: string;
+}
+/**
+ * Agent (running on `forUserId`'s behalf) is about to call a tool — used by
+ * the file explorer to highlight files the agent is touching and by the
+ * chat sidebar to show a live activity feed without parsing the chat
+ * stream's data parts.
+ *
+ * Fired BEFORE the tool runs; the resulting `file-changed` /
+ * `change-request-opened` / etc. events arrive after.
+ */
+export interface AgentToolCallEvent {
+    kind: 'agent-tool-call';
+    forUserId: string;
+    threadId: string;
+    tool: string;
+    /**
+     * Free-form summary of what the tool is about to do (e.g. `"writing
+     * Knowledge/Foo.md"`, `"opening change request Foo → target-company-state"`).
+     * Optional — purely informational, never load-bearing.
+     */
+    summary?: string;
+}
+export interface ChangeRequestOpenedEvent {
+    kind: 'change-request-opened';
+    number: number;
+    source: string;
+    target: string;
+    /** Hash of the author's email (matches the marker in the CR body); null when unattributable. */
+    authorIdHash: string | null;
+    title: string;
+}
+export interface ChangeRequestMergedEvent {
+    kind: 'change-request-merged';
+    number: number;
+}
+export interface ChangeRequestRejectedEvent {
+    kind: 'change-request-rejected';
+    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
+ * is async (returns 202 immediately so a large PR's merge can't outlive the
+ * 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.
+ */
+export interface ChangeRequestMergeFailedEvent {
+    kind: 'change-request-merge-failed';
+    forUserId: string;
+    number: number;
+    /** Human-readable reason for the error banner (tokens already redacted). */
+    reason: string;
+    /**
+     * True when the merge failed because the branch needs conflict resolution.
+     * The UI routes to the agent resolution flow instead of showing an error.
+     */
+    conflicts: boolean;
+}
+/**
+ * Per-file approval on a change request was added or removed (e.g. via the
+ * Approve / Withdraw confirmation buttons, or auto-invalidated by a new
+ * commit). The UI re-fetches the CR detail to get the updated approval set.
+ */
+export interface ApprovalChangedEvent {
+    kind: 'approval-changed';
+    number: number;
+    path: string;
+    approverUserId: string;
+    change: 'added' | 'removed';
+}
+/**
+ * Sent every ~25 s on the SSE stream to keep proxies / load balancers from
+ * killing idle connections. Carries no payload state — the client ignores it
+ * apart from the keepalive effect.
+ */
+export interface HeartbeatEvent {
+    kind: 'heartbeat';
+}
+/**
+ * Server told the client to discard its cached state and refetch from
+ * scratch — sent when a reconnecting client's `Last-Event-ID` is older than
+ * the server's ring buffer still has, so we can't trust an event replay to
+ * catch them up.
+ */
+export interface ResyncEvent {
+    kind: 'resync';
+    /** Human-readable reason for logs / debugging. */
+    reason: string;
+}
+export type WorkflowEventPayload = FileChangedEvent | LockAcquiredEvent | LockReleasedEvent | FsTreeChangedEvent | BranchSwitchedEvent | AgentToolCallEvent | ChangeRequestOpenedEvent | ChangeRequestMergedEvent | ChangeRequestRejectedEvent | ChangeRequestMergeFailedEvent | ApprovalChangedEvent | HeartbeatEvent | ResyncEvent;
+export type WorkflowEvent = WorkflowEventEnvelope & WorkflowEventPayload;
+/** True for events scoped to a workspace — the focus filter applies. */
+export declare function isWorkspaceScoped(e: WorkflowEventPayload): e is WorkflowEventPayload & {
+    workspaceId: string;
+};
+/** True for events scoped to a specific user — the user filter applies. */
+export declare function isUserScoped(e: WorkflowEventPayload): e is WorkflowEventPayload & {
+    forUserId: string;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/workflow/events.d.ts.map

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