canopycms 0.0.67-int.90 → 0.0.67

package/dist/authorization/validation.d.ts

@@ -1,27 +1,5 @@
-/**
- * Authorization validation utilities.
- *
- * SECURITY CRITICAL: These functions validate permission paths
- * to prevent path traversal attacks.
- */
 import type { PermissionPath } from './types.js';
-/**
- * Parse and validate a PermissionPath.
- *
- * SECURITY: Prevents path traversal attacks in permission rules.
- *
- * @param path - The permission path to validate
- * @returns Object with success flag and either the typed path or an error
- *
- * @example
- * ```ts
- * const result = parsePermissionPath(rule.path)
- * if (!result.ok) {
- *   throw new Error(`Invalid permission path: ${result.error}`)
- * }
- * const permissionPath: PermissionPath = result.path
- * ```
- */
+/** Parse a PermissionPath. SECURITY: rejects path traversal in permission rules. */
 export declare function parsePermissionPath(path: string): {
     ok: true;
     path: PermissionPath;

package/dist/authorization/validation.js

@@ -1,27 +1,5 @@
-/**
- * Authorization validation utilities.
- *
- * SECURITY CRITICAL: These functions validate permission paths
- * to prevent path traversal attacks.
- */
 import { hasTraversalSequence } from '../paths/normalize.js';
-/**
- * Parse and validate a PermissionPath.
- *
- * SECURITY: Prevents path traversal attacks in permission rules.
- *
- * @param path - The permission path to validate
- * @returns Object with success flag and either the typed path or an error
- *
- * @example
- * ```ts
- * const result = parsePermissionPath(rule.path)
- * if (!result.ok) {
- *   throw new Error(`Invalid permission path: ${result.error}`)
- * }
- * const permissionPath: PermissionPath = result.path
- * ```
- */
+/** Parse a PermissionPath. SECURITY: rejects path traversal in permission rules. */
 export function parsePermissionPath(path) {
     if (!path || typeof path !== 'string') {
         return { ok: false, error: 'Permission path is required' };
@@ -35,7 +13,6 @@ export function parsePermissionPath(path) {
     }
     // Normalize separators to prevent bypass via backslashes
     const normalized = path.replace(/\\/g, '/');
-    // Additional security checks
     if (normalized.startsWith('/') || normalized.endsWith('/')) {
         return {
             ok: false,

package/dist/branch-health.d.ts

@@ -1,21 +1,18 @@
 import type { BranchMetadata } from './types.js';
 import { type DuplicateContentId } from './content-id-index.js';
 /**
- * Admin-facing health classification of every directory under a branches
- * root (`baseRoot`), including ones the {@link BranchRegistry} quarantines
- * out of normal listings. Two stuck states have no in-product recovery
- * without this: a branch dir whose `.canopy-meta/branch.json` is corrupt
- * (registry now silently drops it — see branch-registry.ts's
- * `scanBranchDirectories` quarantine), and an orphan dir with no
- * `branch.json` at all (left behind by a partial delete crash — see
- * `api/branch.ts`'s delete handler). Both are invisible to admins in prod,
- * who have no filesystem access.
+ * Admin-facing health classification of every directory under a branches root,
+ * including the ones {@link BranchRegistry} quarantines out of normal listings.
+ * Without it two stuck states have no in-product recovery, and prod admins have
+ * no filesystem access to see them: a branch dir whose `.canopy-meta/branch.json`
+ * is corrupt (the registry drops it silently) and an orphan dir with no
+ * `branch.json` at all (a partial delete crash — see `api/branch.ts`).
  *
- * `scanBranchHealth` mirrors the registry's own directory-listing rules
- * (skip non-directories and dot-prefixed names) so its classification never
- * disagrees with what the registry itself would show as "missing".
+ * `scanBranchHealth` mirrors the registry's own directory-listing rules (skip
+ * non-directories and dot-prefixed names) so the two never disagree about what
+ * counts as missing.
  */
-export type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
+type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
 export interface BranchHealthEntry {
     dirName: string;
     kind: BranchHealthKind;
@@ -24,34 +21,29 @@ export interface BranchHealthEntry {
     /** healthy only */
     branch?: BranchMetadata;
     /**
-     * healthy only, and only when non-empty: duplicate content IDs found in
-     * this branch's content tree (see content-id-index.ts's "Duplicate-ID
-     * quarantine" section). The branch itself stays fully usable -- content
-     * operations degrade only for the specific quarantined ID(s), which are
-     * excluded from ID-based lookups, and whose entries refuse saves
-     * (`DuplicateContentIdError`, a 409 naming this repair action) rather than
-     * mutate an ambiguous target, until repaired via the
-     * repair-content-duplicates admin action.
+     * healthy only, non-empty only: duplicate content IDs in this branch's
+     * content tree (see content-id-index.ts). The branch stays usable — only the
+     * quarantined IDs degrade, dropping out of ID-based lookups and refusing
+     * saves (`DuplicateContentIdError`, a 409 naming the repair action) rather
+     * than mutating an ambiguous target.
      */
     duplicateContentIds?: DuplicateContentId[];
     /**
-     * healthy only, and only when true: this clone has an interrupted rebase on
-     * disk (`.git/rebase-merge` / `.git/rebase-apply`).
+     * healthy only, true only: this clone has an interrupted rebase on disk
+     * (`.git/rebase-merge` / `.git/rebase-apply`).
      *
-     * Deliberately an advisory flag on `healthy` rather than its own
-     * `BranchHealthKind`, for the same reason `duplicateContentIds` is: the
-     * branch's metadata is intact and the state is USUALLY transient -- the
-     * worker's sync loop aborts an interrupted rebase at the top of its next
-     * per-branch pass. What this flag buys is visibility in the window BEFORE
-     * that pass runs, where the branch otherwise scanned as unqualified
-     * `healthy` while being skipped as dirty every cycle.
+     * Advisory on `healthy` rather than its own `BranchHealthKind`, like
+     * `duplicateContentIds`: the metadata is intact and the state is usually
+     * transient, since the worker's sync loop aborts an interrupted rebase at the
+     * top of its next per-branch pass. The flag buys visibility in the window
+     * before that, where the branch otherwise scans as plain `healthy` while
+     * being skipped as dirty every cycle.
      *
-     * NOT self-recovering in every case, so a persisting value is the real
-     * signal and needs an operator. Two ways it sticks: the abort itself keeps
-     * failing, or the branch's status moved off `editing` after it wedged --
-     * the rebase loop filters by status BEFORE reaching the recovery step, so a
-     * clone that crashed mid-rebase and was then submitted or archived is never
-     * revisited, and this flag is the only thing that surfaces it.
+     * A value that persists is the real signal and needs an operator, because
+     * recovery is not guaranteed: the abort can keep failing, or the status can
+     * move off `editing` after the branch wedged — the rebase loop filters by
+     * status BEFORE the recovery step, so a clone that crashed mid-rebase and was
+     * then submitted or archived is never revisited, and only this flag shows it.
      */
     rebaseInProgress?: boolean;
     /** corrupt-metadata only: message describing why the file failed to load. */
@@ -65,12 +57,11 @@ export interface BranchHealthEntry {
     /** orphan only: age of the directory's mtime in ms, clamped to >= 0. */
     ageMs?: number;
     /**
-     * [H1] Present iff the dir's provisioning init-lock marker exists on disk,
-     * for orphan and corrupt-metadata entries only. Presence alone means
-     * nothing -- a crashed provisioner's lock lingers forever (proper-lockfile
-     * stale locks are only reaped by a later acquisition attempt, and a health
-     * scan never acquires). Freshness (`ageMs`) is the actual signal admin
-     * actions gate on.
+     * [H1] Present iff the dir's provisioning init-lock marker is on disk, for orphan
+     * and corrupt-metadata entries only. Presence alone means nothing: a crashed
+     * provisioner's lock lingers forever, since proper-lockfile reaps a stale
+     * lock only on a later acquisition and a health scan never acquires.
+     * Freshness (`ageMs`) is what admin actions gate on.
      */
     provisioningLock?: {
         mtime: string;
@@ -78,33 +69,14 @@ export interface BranchHealthEntry {
     };
 }
 /**
- * The on-disk path of the cross-process provisioning lock marker for a
- * given branch directory, matching `branch-workspace.ts`'s
- * `ensureGitWorkspace()` exactly:
- *
- * ```ts
- * acquireProvisioningLock(
- *   path.dirname(branchRoot),         // === baseRoot
- *   `.${path.basename(branchRoot)}.init.lock`,
- * )
- * ```
- *
- * `acquireProvisioningLock` passes this name as `lockfilePath`, which
- * overrides proper-lockfile's default `${target}.lock` naming, so the lock
- * marker itself (a directory, mkdir-based) lives at exactly this path -- no
- * extra `.lock` suffix.
- */
-export declare function provisioningLockPath(baseRoot: string, dirName: string): string;
-/**
- * Scan every directory under `baseRoot` and classify it as healthy,
- * corrupt-metadata, or orphan. Never throws for a single bad directory --
- * one dir's unreadable/unparseable metadata must not take down the whole
- * scan (same rationale as the registry's own quarantine behavior).
- *
- * Tolerates a missing `baseRoot` (returns `[]`) so the admin endpoint can
- * call this unconditionally without a pre-existence check.
+ * Classify every directory under `baseRoot` as healthy, corrupt-metadata, or
+ * orphan. Never throws for a single bad directory — one dir's unreadable
+ * metadata must not take down the whole scan, as in the registry's quarantine.
+ * A missing `baseRoot` returns `[]`, so the admin endpoint can call this
+ * without a pre-existence check.
  */
 export declare function scanBranchHealth(baseRoot: string, opts: {
     baseBranchName: string;
     contentRootName?: string;
 }): Promise<BranchHealthEntry[]>;
+export {};

package/dist/branch-health.js

@@ -6,23 +6,14 @@ import { sanitizeBranchName } from './paths/branch-name.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from './utils/error.js';
 import { isRebaseInProgress } from './utils/git.js';
 /**
- * The on-disk path of the cross-process provisioning lock marker for a
- * given branch directory, matching `branch-workspace.ts`'s
- * `ensureGitWorkspace()` exactly:
+ * The provisioning lock marker's path for a branch directory, matching what
+ * `branch-workspace.ts`'s `ensureGitWorkspace()` passes exactly.
  *
- * ```ts
- * acquireProvisioningLock(
- *   path.dirname(branchRoot),         // === baseRoot
- *   `.${path.basename(branchRoot)}.init.lock`,
- * )
- * ```
- *
- * `acquireProvisioningLock` passes this name as `lockfilePath`, which
- * overrides proper-lockfile's default `${target}.lock` naming, so the lock
- * marker itself (a directory, mkdir-based) lives at exactly this path -- no
- * extra `.lock` suffix.
+ * `acquireProvisioningLock` passes the name as `lockfilePath`, overriding
+ * proper-lockfile's default `${target}.lock`, so the marker (a mkdir-based
+ * directory) sits at exactly this path — no extra `.lock` suffix.
  */
-export function provisioningLockPath(baseRoot, dirName) {
+function provisioningLockPath(baseRoot, dirName) {
     return path.join(baseRoot, `.${dirName}.init.lock`);
 }
 /** Stat the provisioning lock marker, if present. Never throws. */
@@ -32,8 +23,8 @@ async function readProvisioningLock(baseRoot, dirName) {
         return { mtime: stat.mtime.toISOString(), ageMs: Math.max(0, Date.now() - stat.mtimeMs) };
     }
     catch {
-        // Missing, or unreadable for some other reason -- either way, "no signal"
-        // is the safe default rather than failing the whole scan.
+        // Missing or unreadable: "no signal" is the safe default, rather than
+        // failing the whole scan.
         return undefined;
     }
 }
@@ -48,13 +39,11 @@ async function readMetaMtime(branchRoot) {
     }
 }
 /**
- * Scan a healthy branch's content tree for duplicate-embedded-ID pairs (see
- * content-id-index.ts's "Duplicate-ID quarantine" section). Never throws --
- * one branch's unreadable/unusual content tree must not take down the whole
- * health scan (same rationale as the corrupt-metadata handling below). Costs
- * a full recursive readdir of the content tree, same class of cost as the
- * lazy warm-up every ContentStore already pays on first access -- acceptable
- * for an admin-triggered scan, not a hot path.
+ * Scan a healthy branch's content tree for duplicate embedded IDs (see
+ * content-id-index.ts). Never throws: one branch's unreadable content tree must
+ * not take down the whole health scan. Costs a full recursive readdir — the
+ * same class of cost as a ContentStore's first-access warm-up, fine for an
+ * admin-triggered scan and not for a hot path.
  */
 async function scanDuplicateContentIds(branchRoot, contentRootName) {
     try {
@@ -67,13 +56,11 @@ async function scanDuplicateContentIds(branchRoot, contentRootName) {
     }
 }
 /**
- * Scan every directory under `baseRoot` and classify it as healthy,
- * corrupt-metadata, or orphan. Never throws for a single bad directory --
- * one dir's unreadable/unparseable metadata must not take down the whole
- * scan (same rationale as the registry's own quarantine behavior).
- *
- * Tolerates a missing `baseRoot` (returns `[]`) so the admin endpoint can
- * call this unconditionally without a pre-existence check.
+ * Classify every directory under `baseRoot` as healthy, corrupt-metadata, or
+ * orphan. Never throws for a single bad directory — one dir's unreadable
+ * metadata must not take down the whole scan, as in the registry's quarantine.
+ * A missing `baseRoot` returns `[]`, so the admin endpoint can call this
+ * without a pre-existence check.
  */
 export async function scanBranchHealth(baseRoot, opts) {
     const resolvedRoot = path.resolve(baseRoot);
@@ -107,19 +94,16 @@ export async function scanBranchHealth(baseRoot, opts) {
             loadErr = err;
         }
         if (loadErr) {
-            // Both the documented BranchMetadataCorruptError (bad JSON) and any
-            // other loadOnly failure (EACCES, EISDIR from a directory named
-            // branch.json, etc.) land here: all are "needs admin attention",
-            // and none may throw out of the scan.
+            // Every loadOnly failure lands here — BranchMetadataCorruptError for bad
+            // JSON, EACCES/EISDIR and the rest for everything else — since all of
+            // them need admin attention and none may throw out of the scan.
             //
-            // [REDACT] parseError is served to the browser via the admin
-            // branch-health endpoint, so it must never leak the absolute
-            // workspace path. BranchMetadataCorruptError carries `parseCause`
-            // (the raw JSON.parse message, path-free) for exactly this --
-            // `message` embeds branchRoot and is for server logs only. Other node
-            // errors (EISDIR from a directory named branch.json, EACCES, etc.)
-            // embed the path in their `message`, so only their `code` is safe to
-            // surface; non-node errors fall back to getErrorMessage.
+            // [REDACT] parseError reaches the browser through the admin branch-health
+            // endpoint, so it must never carry the absolute workspace path.
+            // BranchMetadataCorruptError's `parseCause` is the path-free JSON.parse
+            // message for exactly this, while its `message` embeds branchRoot and is
+            // for server logs only. Node errors embed the path in `message` too, so
+            // only their `code` is safe to surface.
             const parseError = loadErr instanceof BranchMetadataCorruptError
                 ? loadErr.parseCause
                 : isNodeError(loadErr)

package/dist/branch-metadata-file.d.ts

@@ -1,20 +1,10 @@
 /**
  * Reading `branch.json` — the file format, nothing else.
  *
- * Deliberately a LEAF: it imports only node built-ins, a type, and the error
- * helper. That is the whole point of the file.
- *
- * `branch-registry.ts` scans every branch directory and reads each one's
- * `branch.json`; `branch-metadata.ts` owns writing it and, after a write,
- * invalidates the registry cache. Both of those are correct, but together they
- * were a runtime import cycle (`branch-metadata` -> `branch-registry` ->
- * `branch-metadata`), with value imports on both edges — the only cycle in the
- * package when `no-circular` was first turned on, 2026-08-23.
- *
- * Hoisting the READ here breaks it without changing either module's behavior:
- * the registry gets its reader from a leaf, and the metadata manager keeps its
- * invalidation edge. `BranchMetadataFileManager.loadOnly` stays as a thin
- * delegate so its ~16 existing call sites are untouched.
+ * Deliberately a LEAF, importing only node built-ins, a type, and the error
+ * helper. That is what keeps `branch-registry.ts` (which reads every branch's
+ * `branch.json`) out of a runtime import cycle with `branch-metadata.ts` (which
+ * writes it and then invalidates the registry cache).
  */
 import type { BranchMetadata } from './types.js';
 export declare const BRANCH_META_DIR = ".canopy-meta";
@@ -26,33 +16,27 @@ export interface BranchMetadataFile {
     branch: BranchMetadata;
 }
 /**
- * branch.json exists but its content is not valid JSON. Distinguished from
- * provisioning/IO failures so callers can degrade instead of failing hard:
- * the registry scan quarantines the branch, and the request handler keeps
- * serving (with empty internal groups) when the BASE branch is the corrupt
- * one — otherwise the admin recovery surface would be unreachable exactly
- * when it is needed.
+ * branch.json exists but is not valid JSON. Distinguished from provisioning and
+ * IO failures so callers can degrade instead of failing hard: the registry scan
+ * quarantines the branch, and the request handler keeps serving (with empty
+ * internal groups) when the BASE branch is the corrupt one — otherwise the
+ * admin recovery surface is unreachable exactly when it is needed.
  */
 export declare class BranchMetadataCorruptError extends Error {
     readonly branchRoot: string;
     /**
-     * [REDACT] The raw JSON.parse failure message (e.g. "Unexpected token
-     * ..."), with no embedded path. `message` above deliberately keeps the
-     * full `branchRoot`-qualified text for server logs; `parseCause` is what
-     * callers should surface to clients (see branch-health.ts's `parseError`)
-     * so the admin branch-health scan never leaks the absolute workspace path.
+     * [REDACT] The raw JSON.parse failure message, with no embedded path.
+     * `message` above keeps the `branchRoot`-qualified text for server logs;
+     * `parseCause` is the one callers surface to clients (branch-health.ts's
+     * `parseError`), so no scan leaks the absolute workspace path.
      */
     readonly parseCause: string;
     constructor(branchRoot: string, cause: string);
 }
-/** Absolute path to a branch workspace's `branch.json`. */
-export declare const branchMetadataFilePath: (branchRoot: string) => string;
 /**
  * Read and parse `branch.json`, with no locking, no OCC and no side effects.
- *
- * Returns `null` when the file does not exist (an un-provisioned or
- * non-branch directory), throws `BranchMetadataCorruptError` on malformed
- * JSON, and rethrows every other IO failure unchanged — callers distinguish
- * all three.
+ * Callers distinguish three outcomes: `null` when the file does not exist (an
+ * un-provisioned or non-branch directory), `BranchMetadataCorruptError` on
+ * malformed JSON, and every other IO failure rethrown unchanged.
  */
 export declare function readBranchMetadataFile(branchRoot: string): Promise<BranchMetadataFile | null>;

package/dist/branch-metadata-file.js

@@ -1,20 +1,10 @@
 /**
  * Reading `branch.json` — the file format, nothing else.
  *
- * Deliberately a LEAF: it imports only node built-ins, a type, and the error
- * helper. That is the whole point of the file.
- *
- * `branch-registry.ts` scans every branch directory and reads each one's
- * `branch.json`; `branch-metadata.ts` owns writing it and, after a write,
- * invalidates the registry cache. Both of those are correct, but together they
- * were a runtime import cycle (`branch-metadata` -> `branch-registry` ->
- * `branch-metadata`), with value imports on both edges — the only cycle in the
- * package when `no-circular` was first turned on, 2026-08-23.
- *
- * Hoisting the READ here breaks it without changing either module's behavior:
- * the registry gets its reader from a leaf, and the metadata manager keeps its
- * invalidation edge. `BranchMetadataFileManager.loadOnly` stays as a thin
- * delegate so its ~16 existing call sites are untouched.
+ * Deliberately a LEAF, importing only node built-ins, a type, and the error
+ * helper. That is what keeps `branch-registry.ts` (which reads every branch's
+ * `branch.json`) out of a runtime import cycle with `branch-metadata.ts` (which
+ * writes it and then invalidates the registry cache).
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -22,12 +12,11 @@ import { isNotFoundError } from './utils/error.js';
 export const BRANCH_META_DIR = '.canopy-meta';
 export const BRANCH_META_FILE = 'branch.json';
 /**
- * branch.json exists but its content is not valid JSON. Distinguished from
- * provisioning/IO failures so callers can degrade instead of failing hard:
- * the registry scan quarantines the branch, and the request handler keeps
- * serving (with empty internal groups) when the BASE branch is the corrupt
- * one — otherwise the admin recovery surface would be unreachable exactly
- * when it is needed.
+ * branch.json exists but is not valid JSON. Distinguished from provisioning and
+ * IO failures so callers can degrade instead of failing hard: the registry scan
+ * quarantines the branch, and the request handler keeps serving (with empty
+ * internal groups) when the BASE branch is the corrupt one — otherwise the
+ * admin recovery surface is unreachable exactly when it is needed.
  */
 export class BranchMetadataCorruptError extends Error {
     constructor(branchRoot, cause) {
@@ -38,14 +27,12 @@ export class BranchMetadataCorruptError extends Error {
     }
 }
 /** Absolute path to a branch workspace's `branch.json`. */
-export const branchMetadataFilePath = (branchRoot) => path.join(path.resolve(branchRoot), BRANCH_META_DIR, BRANCH_META_FILE);
+const branchMetadataFilePath = (branchRoot) => path.join(path.resolve(branchRoot), BRANCH_META_DIR, BRANCH_META_FILE);
 /**
  * Read and parse `branch.json`, with no locking, no OCC and no side effects.
- *
- * Returns `null` when the file does not exist (an un-provisioned or
- * non-branch directory), throws `BranchMetadataCorruptError` on malformed
- * JSON, and rethrows every other IO failure unchanged — callers distinguish
- * all three.
+ * Callers distinguish three outcomes: `null` when the file does not exist (an
+ * un-provisioned or non-branch directory), `BranchMetadataCorruptError` on
+ * malformed JSON, and every other IO failure rethrown unchanged.
  */
 export async function readBranchMetadataFile(branchRoot) {
     const resolvedRoot = path.resolve(branchRoot);