canopycms 0.0.67-int.90 → 0.0.67

package/dist/api/assets.d.ts

@@ -48,31 +48,6 @@ declare const finalizeAssetBodySchema: z.ZodObject<{
     stagingKey: string;
 }>;
 export type FinalizeAssetBody = z.infer<typeof finalizeAssetBodySchema>;
-/**
- * Declared as `params` (not just parsed ad hoc from req.query) so the client
- * generator (scripts/generate-client.ts) sees a paramsSchema and emits a
- * method that accepts and forwards `cursor`/`limit` (API-H4) instead of a
- * no-arg `assets.list()` that can never pass them.
- */
-declare const listAssetsParamsSchema: z.ZodObject<{
-    cursor: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    cursor?: string | undefined;
-    limit?: number | undefined;
-}, {
-    cursor?: string | undefined;
-    limit?: number | undefined;
-}>;
-export type ListAssetsParams = z.infer<typeof listAssetsParamsSchema>;
-declare const deleteAssetParamsSchema: z.ZodObject<{
-    key: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    key: string;
-}, {
-    key: string;
-}>;
-export type DeleteAssetParams = z.infer<typeof deleteAssetParamsSchema>;
 /**
  * Exported routes for router registration and client codegen.
  */

package/dist/api/assets.js

@@ -23,9 +23,6 @@ const MOCK_ASSET_RECORD = {
     uploadedAt: '2024-01-01T00:00:00.000Z',
     src: '/assets/t/orig/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/sample.png',
 };
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const filenameSchema = z.string().min(1).max(255);
 const presignAssetBodySchema = z.object({
     filename: filenameSchema,
@@ -51,13 +48,10 @@ const hash32Schema = z
     .string()
     .regex(/^[a-f0-9]{32}$/, 'key must be a 32-character lowercase hex string');
 const deleteAssetParamsSchema = z.object({ key: hash32Schema });
-// ============================================================================
-// Handlers
-// ============================================================================
 /**
  * Presign a direct (or proxied) upload target. Any authenticated user - there
  * is no finer "editor" role, and upload needs to work for every non-admin
- * user too (see guard semantics in .claude/future-tasks/assets-media-system.md).
+ * user too (see guard semantics in .claude/future-tasks/resolved/assets-media-system.md).
  */
 const presignAssetHandler = async (ctx, _req, body) => {
     if (!ctx.assetStore)
@@ -93,13 +87,11 @@ const finalizeAssetHandler = async (ctx, req, body) => {
     return { ok: true, status: 200, data: { asset: toAssetRecord(result.meta) } };
 };
 /**
- * Proxied upload for stores that don't support direct-to-storage presigning
- * (LocalAssetStore in dev). Reads a multipart/form-data body (a `file` part,
- * plus an optional `filename` field overriding `file.name`) rather than JSON -
- * this route sets `bodyFormat: 'multipart'` below so the core handler skips
- * its default `req.json()` parsing, since the body stream can only be read
- * once (see http/handler.ts). Any authenticated user (same rationale as
- * presign/finalize).
+ * Proxied upload for stores that don't support direct-to-storage presigning (LocalAssetStore in
+ * dev). Reads multipart/form-data (a `file` part, optional `filename` override) instead of JSON;
+ * this route sets `bodyFormat: 'multipart'` so the core handler skips its default `req.json()`
+ * parse, since the body stream can only be read once (see http/handler.ts). Any authenticated
+ * user (same rationale as presign/finalize).
  */
 const uploadProxiedHandler = async (ctx, req) => {
     if (!ctx.assetStore)
@@ -118,15 +110,11 @@ const uploadProxiedHandler = async (ctx, req) => {
             error: 'This server adapter does not support multipart form-data uploads',
         };
     }
-    // Early size guard from the Content-Length header, BEFORE the multipart
-    // body is ever read - `formData()`/`filePart.arrayBuffer()` below fully
-    // buffer the upload into memory, so without this an over-cap request still
-    // pays the full read cost before the (correct, but too-late) post-read
-    // check further down rejects it. `beginUpload()` is the store-agnostic way
-    // to learn "the store's max" (mirrors presignAssetHandler's own use of it)
-    // - filename/contentType are placeholders here since only `.maxBytes` is
-    // read; the real `beginUpload()` call below (with the actual filename)
-    // still runs after the body is read to build the real staging target.
+    // Early size guard from Content-Length, before the multipart body is read - `formData()`/
+    // `arrayBuffer()` below fully buffer the upload into memory, so without this an over-cap
+    // request still pays the full read cost before the post-read check further down rejects it.
+    // `beginUpload()` is the store-agnostic way to learn the store's max; filename/contentType here
+    // are placeholders since only `.maxBytes` is read.
     const contentLengthHeader = req.rawRequest.header('content-length');
     if (contentLengthHeader !== null) {
         const contentLength = Number(contentLengthHeader);
@@ -179,7 +167,7 @@ const uploadProxiedHandler = async (ctx, req) => {
 };
 /**
  * List assets - any authenticated user can list assets (key enumeration is
- * accepted: unlisted != private, see assets-media-system.md).
+ * accepted: unlisted != private, see .claude/future-tasks/resolved/assets-media-system.md).
  */
 const listAssetsHandler = async (ctx, _req, params) => {
     if (!ctx.assetStore)
@@ -191,31 +179,26 @@ const listAssetsHandler = async (ctx, _req, params) => {
     return { ok: true, status: 200, data: { assets: items.map(toAssetRecord), nextCursor } };
 };
 /**
- * Delete asset - an Admin may delete any asset; anyone else may delete only an
- * asset whose recorded `uploadedBy` is them. `key` is the asset's hash32 and is
- * validated (32 lowercase hex chars) by `deleteAssetParamsSchema` before this
- * handler ever runs. Deletes the meta sidecar only - blobs are immortal until
- * a future GC worker task (see assets-media-system.md).
+ * Delete asset - an Admin may delete any asset; anyone else may delete only an asset whose
+ * recorded `uploadedBy` is them. `key` (hash32) is pre-validated by `deleteAssetParamsSchema`.
+ * Deletes the meta sidecar only - blobs are immortal until a future GC worker task (see
+ * .claude/future-tasks/resolved/assets-media-system.md).
  *
- * The ownership check lives here rather than in a declarative guard because it
- * needs the asset itself: guards run before the handler and cannot read meta.
+ * The ownership check lives here, not in a declarative guard, because it needs the asset's meta,
+ * which guards can't read. Two fail-closed choices:
+ * - Meta with no `uploadedBy` (the field is optional) is admin-only — defaulting to "anyone may
+ *   delete" would open every legacy asset to everyone.
+ * - A missing asset returns the same 403 as an unowned one for non-admins, so the endpoint isn't
+ *   an existence oracle over a content-addressed keyspace.
  *
- * Two deliberate choices, both fail-closed:
- * - Meta with no `uploadedBy` (the field is optional) is admin-only. Falling
- *   back to "anyone may delete" would open every legacy asset to everyone.
- * - A missing asset returns the same 403 as an unowned one for non-admins, so
- *   the endpoint isn't an existence oracle over a content-addressed keyspace.
+ * `uploadedBy` records the FIRST uploader only: finalizeAsset dedups on content hash, so a second
+ * person uploading an identical file gains no delete rights over it — benign (a 403 where they
+ * expected success, never the reverse; see
+ * .claude/future-tasks/asset-listing-cross-branch-exposure.md).
  *
- * Note `uploadedBy` records the FIRST uploader only: finalizeAsset dedups on
- * the content hash and returns the existing meta, so a second person uploading
- * an identical file gains no delete rights over it. Benign (a 403 where they
- * expected success, never the reverse) - see
- * .claude/future-tasks/asset-listing-cross-branch-exposure.md.
- *
- * COUPLED to the blob-GC follow-up in asset-review-followups.md: this
- * permission is safe because delete is a de-list, not a destroy - nothing that
- * another branch references breaks. If GC ever makes delete destroy the
- * underlying blob, revisit this (it would then need a reference check).
+ * Coupled to the blob-GC follow-up in asset-review-followups.md: this permission is safe because
+ * delete is a de-list, not a destroy — nothing another branch references breaks. If GC ever makes
+ * delete destroy the blob, this needs a reference check too.
  */
 const deleteAssetHandler = async (ctx, req, params) => {
     if (!ctx.assetStore)
@@ -232,16 +215,13 @@ const deleteAssetHandler = async (ctx, req, params) => {
 /** Cache-Control applied to every transform output this route writes/serves - matches finalize.ts's PUBLIC_CACHE_CONTROL for static public objects. */
 const TRANSFORM_CACHE_CONTROL = 'public, max-age=31536000, immutable';
 /**
- * Lazy dev-mode emulation of the prod transform Lambda (which reuses
- * `parseTransformPath`/`formatDirectives`/`applyTransform` unchanged): parse
- * the request, load the original, transform it, write the result back under
- * its CANONICAL key (so a non-canonically-ordered directive string still
- * dedupes with any equivalent request), then serve the bytes just computed
- * (no re-read from the store).
+ * Lazy dev-mode emulation of the prod transform Lambda (reuses `parseTransformPath`/
+ * `formatDirectives`/`applyTransform` unchanged): parse, load the original, transform, write the
+ * result back under its CANONICAL key (so a non-canonically-ordered directive string still
+ * dedupes with any equivalent request), then serve the bytes just computed.
  *
- * `key` here is the full store key already confirmed to start with the
- * `assets/t/` prefix and to have missed the cache-hit `readPublicObject`
- * check in `rawAssetHandler`.
+ * `key` here already starts with `assets/t/` and already missed `rawAssetHandler`'s cache-hit
+ * `readPublicObject` check.
  */
 async function serveLazyTransform(assetStore, key) {
     const rest = key.slice(ASSET_PREFIXES.transform.length + 1);
@@ -256,12 +236,10 @@ async function serveLazyTransform(assetStore, key) {
     if (meta.kind !== 'raster') {
         return { ok: false, status: 400, error: 'Not a raster asset - svg/pdf are served statically' };
     }
-    // The slug is decorative in the URL but load-bearing in the stored key, so
-    // it must equal the asset's real slug: `[a-z0-9-]+` is all the parser can
-    // enforce, and every other string that passes it aliases the same image into
-    // a new cache key and a new stored object. Canopy's own URLs always carry
-    // `meta.slug` (assets/asset-url.ts). Mirrors the prod transform Lambda's
-    // handler.ts check - the two paths must agree, or dev accepts URLs prod 404s.
+    // The slug is decorative in the URL but load-bearing in the stored key, so it must equal the
+    // asset's real slug — the parser only enforces `[a-z0-9-]+`, and any other string that passes
+    // it aliases the same image into a new cache key. Mirrors the prod transform Lambda's check
+    // (assets/asset-url.ts); the two paths must agree, or dev accepts URLs prod 404s.
     if (parsed.slug !== meta.slug) {
         return { ok: false, status: 404, error: 'Not found' };
     }
@@ -279,11 +257,9 @@ async function serveLazyTransform(assetStore, key) {
     }
     const transformed = await applyTransform({ data: original.data, ext: original.ext }, parsed.directives);
     if (!transformed.ok) {
-        // Pass the real status through rather than flattening every rejection to
-        // 502 - `applyTransform` already distinguishes client-input errors (400
-        // unsupported format, 413 oversized output) from a genuine decode
-        // failure (422), none of which are "this server failed" (502). Mirrors
-        // the prod transform Lambda's own handler.ts, which makes the same fix.
+        // Pass the real status through instead of flattening every rejection to 502:
+        // `applyTransform` already distinguishes client-input errors (400/413) from a genuine decode
+        // failure (422), none of which are "this server failed." Mirrors the prod transform Lambda.
         return { ok: false, status: transformed.status, error: transformed.error };
     }
     const canonicalKey = `${ASSET_PREFIXES.transform}/${formatDirectives(parsed.directives)}/${parsed.hash32}/${parsed.slug}.${parsed.ext}`;
@@ -301,19 +277,15 @@ async function serveLazyTransform(assetStore, key) {
     };
 }
 /**
- * Serve a public asset object (sanitized svg/pdf finalize wrote, or a
- * previously-computed transform output) for dev-mode `/assets/*` rewrites.
- * Hand-built (not `defineEndpoint`) rather than registered in
- * `ASSET_ROUTES`/the client generator: this route returns raw bytes
- * (`CanopyBinaryResponse`), not a JSON envelope, so a generated client
- * method that calls `response.json()` would be actively wrong. Consumers hit
- * this route directly (an `<img>`/`<a>` src, or a framework rewrite), never
- * through `client.ts`.
+ * Serve a public asset object (sanitized svg/pdf finalize wrote, or a cached transform output)
+ * for dev-mode `/assets/*` rewrites. Hand-built (not `defineEndpoint`), not registered in
+ * `ASSET_ROUTES`/the client generator: this returns raw bytes (`CanopyBinaryResponse`), not a
+ * JSON envelope, so a generated `response.json()` client method would be wrong. Consumers hit
+ * this route directly (`<img>`/`<a>` src, or a framework rewrite), never through `client.ts`.
  *
- * Transform outputs (`assets/t/...`) are cache-checked exactly like any
- * other public object first - only a MISS under the `assets/t/` prefix falls
- * through to `serveLazyTransform`, which computes and caches the bytes. This
- * mirrors the prod design (CloudFront origin-group -> S3 -> Lambda on miss).
+ * Transform outputs (`assets/t/...`) are cache-checked like any other public object first — only
+ * a MISS under `assets/t/` falls through to `serveLazyTransform`. Mirrors prod (CloudFront
+ * origin-group -> S3 -> Lambda on miss).
  */
 const rawAssetHandler = async (ctx, _req, params) => {
     if (!ctx.assetStore)
@@ -346,16 +318,9 @@ const rawAssetHandler = async (ctx, _req, params) => {
     }
     return serveLazyTransform(ctx.assetStore, key);
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
-//
 // Deliberately no 'writableBranch' guard on any endpoint below: none take a
 // :branch param -- the asset store is branch-agnostic (a single global store,
 // see assets/factory.ts), so the protected-base-branch predicate doesn't apply.
-/**
- * POST /assets/presign
- */
 const presignAsset = defineEndpoint({
     namespace: 'assets',
     name: 'presign',
@@ -370,9 +335,6 @@ const presignAsset = defineEndpoint({
     },
     handler: presignAssetHandler,
 });
-/**
- * POST /assets/finalize
- */
 const finalizeAsset = defineEndpoint({
     namespace: 'assets',
     name: 'finalize',
@@ -399,9 +361,6 @@ const uploadProxied = defineEndpoint({
     defaultMockData: { asset: MOCK_ASSET_RECORD },
     handler: uploadProxiedHandler,
 });
-/**
- * GET /assets
- */
 const listAssets = defineEndpoint({
     namespace: 'assets',
     name: 'list',

package/dist/api/branch-merge.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
+/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
 export interface MarkAsMergedParams {
     branch: string;
 }
@@ -12,7 +13,6 @@ export type BranchMergeResponse = ApiResponse<{
 }>;
 /**
  * Mark a branch as merged and archived after PR is merged on GitHub
- * POST /:branch/mark-merged
  *
  * Deliberately no 'submittableBranch' guard: needs no new guard because the
  * handler above already requires status === 'submitted' AND a recorded

package/dist/api/branch-merge.js

@@ -27,7 +27,6 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
             error: 'Cannot mark as merged: no pull request associated with this branch',
         };
     }
-    // Optionally verify PR is actually merged via GitHub API
     if (ctx.services.githubService) {
         try {
             const pr = await ctx.services.githubService.getPullRequest(branchContext.branch.pullRequestNumber);
@@ -70,7 +69,6 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
 };
 /**
  * Mark a branch as merged and archived after PR is merged on GitHub
- * POST /:branch/mark-merged
  *
  * Deliberately no 'submittableBranch' guard: needs no new guard because the
  * handler above already requires status === 'submitted' AND a recorded

package/dist/api/branch-review.d.ts

@@ -1,9 +1,5 @@
 import { z } from 'zod';
 import type { BranchResponse } from './branch.js';
-/**
- * Request changes on a submitted branch (reviewer action)
- * POST /:branch/request-changes
- */
 export declare const requestChanges: import("./route-builder.js").RouteDefinition<z.ZodObject<{
     branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
 }, "strip", z.ZodTypeAny, {
@@ -15,10 +11,6 @@ export declare const requestChanges: import("./route-builder.js").RouteDefinitio
         readonly __brand: "BranchName";
     };
 }>, undefined, BranchResponse>;
-/**
- * Approve a branch (optional for v1)
- * POST /:branch/approve
- */
 export declare const approveBranch: import("./route-builder.js").RouteDefinition<z.ZodObject<{
     branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
 }, "strip", z.ZodTypeAny, {

package/dist/api/branch-review.js

@@ -4,7 +4,6 @@ import { defineEndpoint } from './route-builder.js';
 import { syncConvertToDraft } from './github-sync.js';
 const requestChangesHandler = async (gc, ctx, _req, _params) => {
     const { branchContext } = gc;
-    // Verify branch is submitted
     if (branchContext.branch.status !== 'submitted') {
         return {
             ok: false,
@@ -12,9 +11,7 @@ const requestChangesHandler = async (gc, ctx, _req, _params) => {
             error: `Cannot request changes on branch with status '${branchContext.branch.status}'. Only 'submitted' branches can have changes requested.`,
         };
     }
-    // Convert PR to draft (sync via githubService, or async via task queue)
     await syncConvertToDraft(ctx, branchContext);
-    // Update branch status to 'editing'
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     const updated = await meta.save({
         branch: { name: branchContext.branch.name, status: 'editing' },
@@ -24,7 +21,6 @@ const requestChangesHandler = async (gc, ctx, _req, _params) => {
 };
 const approveBranchHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
-    // Verify branch is submitted
     if (branchContext.branch.status !== 'submitted') {
         return {
             ok: false,
@@ -32,7 +28,6 @@ const approveBranchHandler = async (gc, _ctx, _req, _params) => {
             error: `Cannot approve branch with status '${branchContext.branch.status}'. Only 'submitted' branches can be approved.`,
         };
     }
-    // Update branch status to 'approved'
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     const updated = await meta.save({
         branch: { name: branchContext.branch.name, status: 'approved' },
@@ -40,10 +35,6 @@ const approveBranchHandler = async (gc, _ctx, _req, _params) => {
     // TODO: Optionally call githubService.approvePullRequest() when GitHub integration is needed
     return { ok: true, status: 200, data: { branch: updated.branch } };
 };
-/**
- * Request changes on a submitted branch (reviewer action)
- * POST /:branch/request-changes
- */
 export const requestChanges = defineEndpoint({
     namespace: 'workflow',
     name: 'requestChanges',
@@ -67,10 +58,6 @@ export const requestChanges = defineEndpoint({
     guards: ['reviewer', 'branch'],
     handler: requestChangesHandler,
 });
-/**
- * Approve a branch (optional for v1)
- * POST /:branch/approve
- */
 export const approveBranch = defineEndpoint({
     namespace: 'workflow',
     name: 'approve',

package/dist/api/branch-status.d.ts

@@ -1,9 +1,6 @@
 import { z } from 'zod';
 import type { BranchResponse } from './branch.js';
 export type { BranchMergeResponse } from './branch-merge.js';
-/**
- * Exported routes for router registration
- */
 export declare const WORKFLOW_ROUTES: {
     readonly getStatus: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;

package/dist/api/branch-status.js

@@ -29,26 +29,15 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
             error: 'Only the branch creator or users with explicit branch access can submit this branch',
         };
     }
-    // Only an 'editing' branch may be submitted. This mirrors
-    // getBranchWriteProtection's rule exactly -- writes are blocked on any branch
-    // whose status has left 'editing' -- so "can I edit this?" and "can I submit
-    // this?" stay one question. Submitting a branch you are not allowed to edit
-    // is incoherent: its content cannot have changed since the last submit.
+    // Only an 'editing' branch may be submitted, mirroring
+    // getBranchWriteProtection's status gate exactly so "can I edit this?" and
+    // "can I submit this?" stay one question. Without this, an archived
+    // (merged) branch could be re-submitted by its creator, re-stamping it
+    // 'submitted' and overwriting the merged PR's title/body.
     //
-    // The 'submittableBranch' guard above answers a different question (is this
-    // the protected base branch?) and reads no status at all, so without this the
-    // submit path had no status gate anywhere -- unlike withdraw, approve and
-    // request-changes, which have always had one. An archived (merged) branch
-    // could therefore be re-submitted by its creator: the working tree is clean so
-    // nothing is committed, but it re-stamped the branch 'submitted', overwrote
-    // the merged PR's title/body via syncSubmitPr's update path, and in prod (no
-    // direct githubService) enqueued a worker task that 422s on pulls.create,
-    // since createOrUpdatePullRequest finds no OPEN PR to update.
-    //
-    // Fails closed on a missing status: branch.json is read with a bare
-    // JSON.parse (branch-metadata.ts) with no schema validation, so a damaged or
-    // hand-repaired file can yield `undefined` at runtime. Same reasoning, and
-    // same wording, as runWritableBranchGuard's unreadable-status arm.
+    // Fails closed on a missing status (branch.json is read with a bare
+    // JSON.parse, no schema validation, so a damaged file can yield
+    // `undefined`) -- same as runWritableBranchGuard's unreadable-status arm.
     const status = branchContext.branch.status;
     if (status !== 'editing') {
         return {
@@ -120,13 +109,6 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     });
     return { ok: true, status: 200, data: { branch: updated.branch } };
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
-/**
- * Get branch status
- * GET /:branch/status
- */
 const getBranchStatus = defineEndpoint({
     namespace: 'workflow',
     name: 'getStatus',
@@ -148,10 +130,6 @@ const getBranchStatus = defineEndpoint({
     guards: ['branchAccess'],
     handler: getBranchStatusHandler,
 });
-/**
- * Submit branch for merge/review
- * POST /:branch/submit
- */
 const submitBranchForMerge = defineEndpoint({
     namespace: 'workflow',
     name: 'submit',
@@ -176,9 +154,6 @@ const submitBranchForMerge = defineEndpoint({
     guards: ['branch', 'submittableBranch'],
     handler: submitBranchForMergeHandler,
 });
-/**
- * Exported routes for router registration
- */
 export const WORKFLOW_ROUTES = {
     getStatus: getBranchStatus,
     submit: submitBranchForMerge,

package/dist/api/branch-withdraw.d.ts

@@ -2,7 +2,6 @@ import { z } from 'zod';
 import type { BranchResponse } from './branch.js';
 /**
  * Withdraw a submitted branch, converting the PR to draft and unlocking editing
- * POST /:branch/withdraw
  *
  * Deliberately no 'submittableBranch' guard: withdraw is the only self-serve
  * recovery path for a base branch wrongly stuck in 'submitted' (e.g. a failed

package/dist/api/branch-withdraw.js

@@ -21,8 +21,6 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
             error: 'Only the branch creator or users with explicit branch access can withdraw this branch',
         };
     }
-    // Verify branch is in a withdrawable status.
-    //
     // 'approved' is accepted alongside 'submitted' because withdraw is its only
     // non-destructive exit. Every non-'editing' status blocks content writes, and
     // request-changes requires 'submitted' -- so before this, an approved branch
@@ -40,16 +38,16 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
             error: `Cannot withdraw branch with status '${status}'. Only 'submitted' or 'approved' branches can be withdrawn.`,
         };
     }
-    // Convert PR to draft (sync via githubService, or async via task queue) --
-    // but a PR closed on GitHub without merging can't be converted to draft.
-    // Withdraw (back to 'editing') is the deliberate recovery path for a
-    // closed-unmerged PR, and a later resubmit opens a fresh PR via
-    // createOrUpdatePullRequest, so skip the conversion in that case.
+    // syncConvertToDraft converts the PR to draft, but a PR closed on GitHub
+    // without merging can't be converted. Withdraw (back to 'editing') is the
+    // deliberate recovery path for a closed-unmerged PR; a later resubmit
+    // opens a fresh PR via createOrUpdatePullRequest, so skip the conversion
+    // in that case.
     const wasClosed = branchContext.branch.pullRequestState === 'closed';
     if (!wasClosed) {
         await syncConvertToDraft(ctx, branchContext);
     }
-    // Update branch status to 'editing'. A closed PR is dead after withdraw
+    // A closed PR is dead after withdraw
     // (resubmit opens a fresh one), so drop its metadata rather than leaving a
     // stale PR chip on an editing branch; a drafted PR is still live, so keep it.
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
@@ -66,7 +64,6 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
 };
 /**
  * Withdraw a submitted branch, converting the PR to draft and unlocking editing
- * POST /:branch/withdraw
  *
  * Deliberately no 'submittableBranch' guard: withdraw is the only self-serve
  * recovery path for a base branch wrongly stuck in 'submitted' (e.g. a failed

package/dist/api/branch.d.ts

@@ -113,11 +113,11 @@ declare const updateBranchAccessBodySchema: z.ZodObject<{
 import type { PathPermission } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 /**
- * Check if a user can create branches.
  * Returns true if:
  * - User is Admin or Reviewer (privileged)
  * - User has edit access to at least one path via pathPermissions rules
  * - No path permissions are defined (open access)
+ * @internal Exported for tests.
  */
 export declare const canCreateBranch: (user: CanopyUser, pathPermissions: PathPermission[]) => {
     allowed: boolean;
@@ -129,33 +129,28 @@ export interface CreateBranchBody {
     description?: string;
     access?: BranchMetadata['access'];
 }
+/** @internal Exported for tests. */
 export declare const createBranchHandler: (ctx: ApiContext, req: ApiRequest, body: z.infer<typeof createBranchBodySchema>) => Promise<BranchResponse>;
+/** @internal Exported for tests. */
 export declare const listBranchesHandler: (ctx: ApiContext, req: ApiRequest) => Promise<BranchListResponse>;
-/**
- * Check if a user can delete a specific branch.
- * Returns true if user is Admin or the branch creator.
- */
+/** @internal Exported for tests. */
 export declare const canDeleteBranch: (user: CanopyUser, branchContext: BranchContext) => {
     allowed: boolean;
     reason: string;
 };
+/** @internal Exported for tests. */
 export declare const deleteBranchHandler: (ctx: ApiContext, req: ApiRequest, params: z.infer<typeof branchParamSchema>) => Promise<BranchDeleteResponse>;
 export interface UpdateBranchAccessBody {
     allowedUsers?: string[];
     allowedGroups?: string[];
 }
-/**
- * Check if a user can modify branch access.
- * Returns true if user is Admin or the branch creator.
- */
+/** @internal Exported for tests. */
 export declare const canModifyBranchAccess: (user: CanopyUser, branchContext: BranchContext) => {
     allowed: boolean;
     reason: string;
 };
+/** @internal Exported for tests. */
 export declare const updateBranchAccessHandler: (ctx: ApiContext, req: ApiRequest, params: z.infer<typeof branchParamSchema>, body: z.infer<typeof updateBranchAccessBodySchema>) => Promise<BranchResponse>;
-/**
- * Exported routes for router registration
- */
 export declare const BRANCH_ROUTES: {
     readonly list: import("./route-builder.js").RouteDefinition<undefined, undefined, BranchListResponse>;
     readonly create: import("./route-builder.js").RouteDefinition<undefined, z.ZodObject<{