canopycms 0.0.67-int.90 → 0.0.67

package/dist/github-service.d.ts

@@ -3,47 +3,44 @@ import type { CanopyConfig } from './config/index.js';
 /**
  * Retry primary rate limits at most twice and only for short waits; beyond
  * that, task-level retry/backoff (worker) or the caller's error path takes
- * over. The worker's task timeout would abort a longer in-request wait
- * anyway.
+ * over, since the worker's task timeout would abort a longer in-request wait.
+ * @internal Exported for tests.
  */
 export declare const shouldRetryRateLimit: (retryAfter: number, retryCount: number) => boolean;
 /**
  * Secondary (abuse-detection) rate limits are stricter to trip and usually
  * signal we're hammering the API too fast — retry at most once, and only for
  * a short wait.
+ * @internal Exported for tests.
  */
 export declare const shouldRetrySecondaryRateLimit: (retryAfter: number, retryCount: number) => boolean;
 /**
  * Octokit's pluggable-auth options, typed STRUCTURALLY.
  *
- * `@octokit/core` calls `authStrategy(…)` once in its constructor and wraps
- * the returned object's `.hook` into its request chain, so handing it a
- * strategy is the whole of "authenticate every request some other way".
+ * `@octokit/core` calls `authStrategy(…)` once in its constructor and wraps the
+ * returned object's `.hook` into its request chain, so handing it a strategy is
+ * the whole of "authenticate every request some other way".
  *
- * Declared as a shape rather than imported because this module is reachable
- * from `services.ts` and therefore lands in every adopter's Next.js server
- * bundle: an `import { createAppAuth } from '@octokit/auth-app'` here would
- * put that package (and its `universal-github-app-jwt` dependency) into the
- * bundle of every adopter, including the overwhelming majority who
- * authenticate with a personal access token and will never register a GitHub
- * App. `pnpm lint:bundle` guards the *client* boundary only and would not
- * catch that, so the structural typing is the guard.
+ * The shape is declared, never imported: this module is reachable from
+ * `services.ts` and so lands in every adopter's Next.js server bundle, and
+ * importing `@octokit/auth-app` here would pull that package (plus
+ * `universal-github-app-jwt`) into the bundle of every adopter, including the
+ * majority who authenticate with a personal access token and never register a
+ * GitHub App. `pnpm lint:bundle` guards the *client* boundary only and would
+ * not catch it, so the structural typing IS the guard.
  *
- * A deployment that does use an App constructs the strategy and passes it
- * through here. That is the seam `packages/canopycms-cdk/worker/index.ts`
- * already uses for `refreshAuthCache`, and its App wiring goes through the same
- * one — see `packages/canopycms-cdk/worker/github-app-auth.ts`, with
- * `docs/adopter-migration.md` carrying the shape for a hand-written entrypoint.
+ * A deployment using an App constructs the strategy and passes it through here
+ * — see `packages/canopycms-cdk/worker/github-app-auth.ts` and
+ * `docs/adopter-migration.md` for a hand-written entrypoint.
  */
 export interface OctokitAuthStrategyOptions {
     /**
-     * Octokit calls this with `{ request, log, octokit, octokitOptions }`, with
-     * the fields of `auth` below merged over them, and expects an object
-     * carrying a `.hook`.
-     * `createAppAuth(…)`'s return value satisfies that; so does a closure
-     * returning an already-constructed one, which is how a single auth instance
-     * (and therefore a single installation-token cache) can be shared with a
-     * caller that also needs to mint tokens outside Octokit.
+     * Octokit calls this with `{ request, log, octokit, octokitOptions }`, the
+     * fields of `auth` below merged over them, and expects an object carrying a
+     * `.hook`. `createAppAuth(…)`'s return value satisfies that; so does a
+     * closure returning an already-constructed one, which is how one auth
+     * instance — and so one installation-token cache — is shared with a caller
+     * that also mints tokens outside Octokit.
      */
     authStrategy: (options: Record<string, unknown>) => unknown;
     /** Merged into the strategy's options by Octokit. */
@@ -94,15 +91,11 @@ export interface CreateOrUpdatePullRequestParams {
     signal?: AbortSignal;
 }
 /**
- * Create or update a pull request (idempotent — GIT-H1).
- *
- * If an open PR already exists from head to base, update it and return its
- * number/url instead of erroring. This makes PR submission safely
- * retryable: if a caller crashes after GitHub creates the PR but before it
- * persists the returned PR number, calling this again recovers the
- * existing PR instead of hitting the 422 that a blind create would throw on
- * a duplicate, which previously wedged the branch in 'sync-failed'
- * permanently.
+ * Create or update a pull request, idempotently: an open PR from head to base
+ * is updated and returned rather than erroring. That keeps PR submission
+ * retryable — a caller that crashes after GitHub creates the PR but before it
+ * persists the number recovers the existing PR instead of hitting the 422 a
+ * blind create throws on a duplicate, which wedges the branch in 'sync-failed'.
  *
  * Shared by `GitHubService.createOrUpdatePR` (direct-API callers) and the
  * worker's `push-and-create-or-update-pr` task, so the list->tiebreak->
@@ -113,33 +106,20 @@ export declare function createOrUpdatePullRequest(params: CreateOrUpdatePullRequ
     url: string;
     created: boolean;
 }>;
-/**
- * Service for interacting with GitHub API (pull requests, branches, etc.)
- */
 export declare class GitHubService {
     private octokit;
     private owner;
     private repo;
     private baseBranch;
     constructor(options: GitHubServiceOptions);
-    /**
-     * Create a new pull request
-     */
     createPullRequest(options: PullRequestOptions): Promise<{
         number: number;
         url: string;
     }>;
-    /**
-     * Update an existing pull request
-     */
     updatePullRequest(prNumber: number, options: Partial<Pick<PullRequestOptions, 'title' | 'body'>>): Promise<void>;
     /**
-     * Create or update a pull request (idempotent — GIT-H1).
-     *
-     * Thin delegate to the module-level `createOrUpdatePullRequest` helper
-     * (shared with the worker's `push-and-create-or-update-pr` task) bound to
-     * this instance's octokit/owner/repo. See that function's doc comment for
-     * the idempotency rationale.
+     * Idempotent create-or-update, bound to this instance's octokit/owner/repo.
+     * See {@link createOrUpdatePullRequest}.
      */
     createOrUpdatePR(options: {
         head: string;
@@ -152,37 +132,16 @@ export declare class GitHubService {
         number: number;
         url: string;
     }>;
-    /**
-     * Get pull request details
-     */
     getPullRequest(prNumber: number): Promise<PullRequestDetails>;
-    /**
-     * Convert a pull request to draft
-     */
     convertToDraft(prNumber: number): Promise<void>;
-    /**
-     * Convert a draft pull request to ready for review
-     */
     convertToReady(prNumber: number): Promise<void>;
-    /**
-     * Close a pull request
-     */
     closePullRequest(prNumber: number): Promise<void>;
-    /**
-     * Delete a remote branch
-     */
     deleteBranch(branchName: string): Promise<void>;
-    /**
-     * Get the GraphQL node ID for a pull request (needed for draft operations)
-     */
     private getPullRequestNodeId;
     /**
-     * Parse GitHub remote URL to extract owner and repo
-     * Supports both HTTPS and SSH formats:
-     * - https://github.com/owner/repo.git
-     * - https://github.com/owner/repo
-     * - git@github.com:owner/repo.git
-     * - git@github.com:owner/repo
+     * Extract owner and repo from a GitHub remote URL, in either HTTPS
+     * (`https://github.com/owner/repo[.git]`) or SSH
+     * (`git@github.com:owner/repo[.git]`) form.
      */
     static parseRemoteUrl(remoteUrl: string): {
         owner: string;
@@ -190,7 +149,7 @@ export declare class GitHubService {
     };
 }
 /**
- * Create a GitHub service instance from config and remote URL
- * Returns null if not applicable (missing token, not GitHub, etc.)
+ * A GitHub service for this config and remote URL, or null when one cannot be
+ * built (mode without PR support, missing token, unparseable remote).
  */
 export declare const createGitHubService: (config: CanopyConfig, remoteUrl?: string) => GitHubService | null;

package/dist/github-service.js

@@ -2,24 +2,24 @@ import { Octokit } from '@octokit/rest';
 import { throttling } from '@octokit/plugin-throttling';
 import { operatingStrategy } from './operating-mode/index.js';
 import { getErrorMessage } from './utils/error.js';
-// canopyLogWarn, not console.warn: this module runs inside the WORKER process
-// (its Octokit is the worker's own, and the PR create/update path below is a
-// worker task), where every line must carry worker/log.ts's ISO-8601 prefix or
-// CloudWatch folds it into the previous event. Under Lambda/dev the helper is
-// plain console. See utils/logger.ts.
+// canopyLogWarn, not console.warn: the PR create/update path below runs as a
+// worker task, and every worker line must carry worker/log.ts's ISO-8601 prefix
+// or CloudWatch folds it into the previous event. Under Lambda/dev the helper
+// is plain console. See utils/logger.ts.
 import { canopyLogWarn } from './utils/logger.js';
 const ThrottledOctokit = Octokit.plugin(throttling);
 /**
  * Retry primary rate limits at most twice and only for short waits; beyond
  * that, task-level retry/backoff (worker) or the caller's error path takes
- * over. The worker's task timeout would abort a longer in-request wait
- * anyway.
+ * over, since the worker's task timeout would abort a longer in-request wait.
+ * @internal Exported for tests.
  */
 export const shouldRetryRateLimit = (retryAfter, retryCount) => retryCount < 2 && retryAfter <= 60;
 /**
  * Secondary (abuse-detection) rate limits are stricter to trip and usually
  * signal we're hammering the API too fast — retry at most once, and only for
  * a short wait.
+ * @internal Exported for tests.
  */
 export const shouldRetrySecondaryRateLimit = (retryAfter, retryCount) => retryCount < 1 && retryAfter <= 60;
 /**
@@ -30,12 +30,10 @@ export const shouldRetrySecondaryRateLimit = (retryAfter, retryCount) => retryCo
  * errors the plugin never sees, like non-403 network failures).
  */
 export function createCanopyOctokit(options) {
-    // The two auth fields are picked out EXPLICITLY rather than spread. A spread
-    // would forward anything else the caller's object happened to carry --
-    // `baseUrl`, `request`, `log`, `userAgent` are all live `OctokitOptions`,
-    // and a non-literal argument (a widened variable, not an inline object)
-    // slips past TypeScript's excess-property check. This function's contract is
-    // "our Octokit, authenticated the way you say", not "our Octokit, configured
+    // Pick the two auth fields out EXPLICITLY, never spread: `baseUrl`,
+    // `request`, `log` and `userAgent` are all live `OctokitOptions`, and a
+    // non-literal argument slips past TypeScript's excess-property check. The
+    // contract is "our Octokit, authenticated the way you say", not "configured
     // however you like".
     const auth = 'authStrategy' in options
         ? { authStrategy: options.authStrategy, auth: options.auth }
@@ -57,15 +55,11 @@ export function createCanopyOctokit(options) {
     });
 }
 /**
- * Create or update a pull request (idempotent — GIT-H1).
- *
- * If an open PR already exists from head to base, update it and return its
- * number/url instead of erroring. This makes PR submission safely
- * retryable: if a caller crashes after GitHub creates the PR but before it
- * persists the returned PR number, calling this again recovers the
- * existing PR instead of hitting the 422 that a blind create would throw on
- * a duplicate, which previously wedged the branch in 'sync-failed'
- * permanently.
+ * Create or update a pull request, idempotently: an open PR from head to base
+ * is updated and returned rather than erroring. That keeps PR submission
+ * retryable — a caller that crashes after GitHub creates the PR but before it
+ * persists the number recovers the existing PR instead of hitting the 422 a
+ * blind create throws on a duplicate, which wedges the branch in 'sync-failed'.
  *
  * Shared by `GitHubService.createOrUpdatePR` (direct-API callers) and the
  * worker's `push-and-create-or-update-pr` task, so the list->tiebreak->
@@ -73,11 +67,9 @@ export function createCanopyOctokit(options) {
  */
 export async function createOrUpdatePullRequest(params) {
     const { octokit, owner, repo, head, base, title, body, markReadyIfDraft, signal } = params;
-    // CONDITIONAL spread: when no signal is passed, request objects below are
-    // byte-identical to the pre-refactor call sites (exact toHaveBeenCalledWith
-    // assertions in github-service.test.ts depend on this).
+    // CONDITIONAL spread: with no signal, the request objects below carry no
+    // `request` key at all (github-service.test.ts asserts on their exact shape).
     const requestOption = signal ? { request: { signal } } : {};
-    // Check if an open PR already exists for this head/base
     const existingPRs = await octokit.pulls.list({
         owner,
         repo,
@@ -87,11 +79,9 @@ export async function createOrUpdatePullRequest(params) {
         ...requestOption,
     });
     if (existingPRs.data.length > 0) {
-        // GIT-M5: GitHub disallows more than one open PR for a given
-        // head+base pair, so this should always be a single match. Guard
-        // against blindly trusting array order anyway — if more than one is
-        // ever returned, warn and prefer the most recently updated instead of
-        // an arbitrary one.
+        // GitHub disallows more than one open PR for a head+base pair, so this is
+        // normally a single match. Don't trust array order anyway: if more than one
+        // comes back, warn and take the most recently updated.
         let existing = existingPRs.data[0];
         if (existingPRs.data.length > 1) {
             existing = [...existingPRs.data].sort((a, b) => new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime())[0];
@@ -109,19 +99,16 @@ export async function createOrUpdatePullRequest(params) {
         // above is never called with draft: true, so a newly created PR is
         // never draft and needs no conversion.
         if (markReadyIfDraft && existing.draft) {
-            // Use GraphQL API for draft conversion (not available in REST API).
-            // Read the node id straight off the list payload — no extra pulls.get.
+            // GraphQL: draft conversion has no REST equivalent. The node id comes
+            // straight off the list payload — no extra pulls.get.
             //
-            // Best-effort: the push + pulls.update above already succeeded, so the
-            // submit itself is done. A fine-grained token that can update PRs but
-            // lacks this mutation's scope throws a GraphqlResponseError, which
-            // carries no numeric HTTP status (the GraphQL endpoint responds 200
-            // even for a mutation-level failure) — the worker's
-            // isPermanentTaskFailure would classify that as transient and retry
-            // the whole re-push until the retry cap, wedging the branch in
-            // 'sync-failed' even though the PR already exists and is current.
-            // Warn and continue instead of letting this sink an already-succeeded
-            // submit.
+            // Best-effort, because the push and pulls.update above already succeeded:
+            // a fine-grained token lacking this mutation's scope throws a
+            // GraphqlResponseError with no numeric HTTP status (GraphQL answers 200
+            // even for a mutation-level failure), which the worker's
+            // isPermanentTaskFailure reads as transient and retries the whole re-push
+            // to the cap, wedging the branch in 'sync-failed' even though the PR
+            // exists and is current.
             try {
                 await octokit.graphql(`
           mutation($pullRequestId: ID!) {
@@ -142,7 +129,6 @@ export async function createOrUpdatePullRequest(params) {
         }
         return { number: existing.number, url: existing.html_url, created: false };
     }
-    // Create new PR
     const pr = await octokit.pulls.create({
         owner,
         repo,
@@ -154,9 +140,6 @@ export async function createOrUpdatePullRequest(params) {
     });
     return { number: pr.data.number, url: pr.data.html_url, created: true };
 }
-/**
- * Service for interacting with GitHub API (pull requests, branches, etc.)
- */
 export class GitHubService {
     constructor(options) {
         this.octokit = createCanopyOctokit({ auth: options.token });
@@ -164,9 +147,6 @@ export class GitHubService {
         this.repo = options.repo;
         this.baseBranch = options.baseBranch ?? 'main';
     }
-    /**
-     * Create a new pull request
-     */
     async createPullRequest(options) {
         const response = await this.octokit.pulls.create({
             owner: this.owner,
@@ -182,9 +162,6 @@ export class GitHubService {
             url: response.data.html_url,
         };
     }
-    /**
-     * Update an existing pull request
-     */
     async updatePullRequest(prNumber, options) {
         await this.octokit.pulls.update({
             owner: this.owner,
@@ -195,12 +172,8 @@ export class GitHubService {
         });
     }
     /**
-     * Create or update a pull request (idempotent — GIT-H1).
-     *
-     * Thin delegate to the module-level `createOrUpdatePullRequest` helper
-     * (shared with the worker's `push-and-create-or-update-pr` task) bound to
-     * this instance's octokit/owner/repo. See that function's doc comment for
-     * the idempotency rationale.
+     * Idempotent create-or-update, bound to this instance's octokit/owner/repo.
+     * See {@link createOrUpdatePullRequest}.
      */
     async createOrUpdatePR(options) {
         const result = await createOrUpdatePullRequest({
@@ -215,9 +188,6 @@ export class GitHubService {
         });
         return { number: result.number, url: result.url };
     }
-    /**
-     * Get pull request details
-     */
     async getPullRequest(prNumber) {
         const response = await this.octokit.pulls.get({
             owner: this.owner,
@@ -232,9 +202,6 @@ export class GitHubService {
             draft: response.data.draft ?? false,
         };
     }
-    /**
-     * Convert a pull request to draft
-     */
     async convertToDraft(prNumber) {
         // Use GraphQL API for draft conversion (not available in REST API)
         await this.octokit.graphql(`
@@ -249,9 +216,6 @@ export class GitHubService {
             pullRequestId: await this.getPullRequestNodeId(prNumber),
         });
     }
-    /**
-     * Convert a draft pull request to ready for review
-     */
     async convertToReady(prNumber) {
         // Use GraphQL API for draft conversion (not available in REST API)
         await this.octokit.graphql(`
@@ -266,9 +230,6 @@ export class GitHubService {
             pullRequestId: await this.getPullRequestNodeId(prNumber),
         });
     }
-    /**
-     * Close a pull request
-     */
     async closePullRequest(prNumber) {
         await this.octokit.pulls.update({
             owner: this.owner,
@@ -277,9 +238,6 @@ export class GitHubService {
             state: 'closed',
         });
     }
-    /**
-     * Delete a remote branch
-     */
     async deleteBranch(branchName) {
         await this.octokit.git.deleteRef({
             owner: this.owner,
@@ -287,9 +245,6 @@ export class GitHubService {
             ref: `heads/${branchName}`,
         });
     }
-    /**
-     * Get the GraphQL node ID for a pull request (needed for draft operations)
-     */
     async getPullRequestNodeId(prNumber) {
         const response = await this.octokit.pulls.get({
             owner: this.owner,
@@ -299,17 +254,12 @@ export class GitHubService {
         return response.data.node_id;
     }
     /**
-     * Parse GitHub remote URL to extract owner and repo
-     * Supports both HTTPS and SSH formats:
-     * - https://github.com/owner/repo.git
-     * - https://github.com/owner/repo
-     * - git@github.com:owner/repo.git
-     * - git@github.com:owner/repo
+     * Extract owner and repo from a GitHub remote URL, in either HTTPS
+     * (`https://github.com/owner/repo[.git]`) or SSH
+     * (`git@github.com:owner/repo[.git]`) form.
      */
     static parseRemoteUrl(remoteUrl) {
-        // Remove .git suffix if present
         const urlWithoutGit = remoteUrl.replace(/\.git$/, '');
-        // Try HTTPS format first
         const httpsMatch = urlWithoutGit.match(/https?:\/\/github\.com\/([^/]+)\/([^/]+)/);
         if (httpsMatch) {
             return {
@@ -333,28 +283,24 @@ export class GitHubService {
     }
 }
 /**
- * Create a GitHub service instance from config and remote URL
- * Returns null if not applicable (missing token, not GitHub, etc.)
+ * A GitHub service for this config and remote URL, or null when one cannot be
+ * built (mode without PR support, missing token, unparseable remote).
  */
 export const createGitHubService = (config, remoteUrl) => {
-    // Only create service for modes that support pull requests
     const mode = config.mode;
     if (!operatingStrategy(mode).supportsPullRequests()) {
         return null;
     }
-    // Get token from environment
     const tokenEnvVar = config.githubTokenEnvVar ?? 'GITHUB_BOT_TOKEN';
     const token = process.env[tokenEnvVar] ?? process.env.CANOPYCMS_GITHUB_TOKEN;
     if (!token) {
         canopyLogWarn(`CanopyCMS: GitHub token not found in ${tokenEnvVar} or CANOPYCMS_GITHUB_TOKEN`);
         return null;
     }
-    // Need remote URL to determine owner/repo
     if (!remoteUrl) {
         canopyLogWarn('CanopyCMS: GitHub service requires remoteUrl to determine repository');
         return null;
     }
-    // Parse remote URL
     try {
         const { owner, repo } = GitHubService.parseRemoteUrl(remoteUrl);
         return new GitHubService({

package/dist/http/handler.d.ts

@@ -4,11 +4,7 @@ import { type AuthPlugin } from '../auth/plugin.js';
 import { type CanopyServices } from '../services.js';
 import type { CanopyConfig } from '../config/index.js';
 import type { BranchContext } from '../types.js';
-/**
- * Options for creating a Canopy request handler.
- * This is framework-agnostic - adapters convert their framework's
- * request/response types to/from CanopyRequest/CanopyResponse.
- */
+/** Framework-agnostic: adapters convert to and from CanopyRequest/Response. */
 export interface CanopyHandlerOptions {
     services?: CanopyServices;
     config?: CanopyConfig;
@@ -17,43 +13,16 @@ export interface CanopyHandlerOptions {
     authPlugin: AuthPlugin;
 }
 /**
- * Core request handler result type.
- * Widened to include `CanopyBinaryResponse` so routes that stream bytes
- * (e.g. asset serving) can flow through this handler untouched alongside
- * ordinary JSON routes - see `isCanopyBinaryResponse` usage below.
+ * Includes `CanopyBinaryResponse` so byte-streaming routes (asset serving) flow
+ * through untouched alongside JSON ones — see `isCanopyBinaryResponse` below.
  */
 export type CanopyRequestHandler = (req: CanopyRequest, pathSegments: string[]) => Promise<CanopyResponse<ApiResponse> | CanopyBinaryResponse>;
 /**
- * Create a framework-agnostic Canopy request handler.
- *
- * This is the core handler that processes all Canopy API requests.
- * Framework adapters (Next.js, Express, Hono, etc.) should:
- * 1. Convert their framework's request to CanopyRequest
- * 2. Extract path segments from the URL
- * 3. Call this handler
- * 4. Convert the CanopyResponse to their framework's response
- *
- * @example
- * ```ts
- * // In a framework adapter
- * const coreHandler = createCanopyRequestHandler({
- *   config: myConfig,
- *   authPlugin: myAuthPlugin,
- * })
- *
- * // Framework-specific handler
- * async function handleRequest(frameworkReq) {
- *   const canopyReq = convertToCanopyRequest(frameworkReq)
- *   const segments = extractPathSegments(frameworkReq)
- *   const response = await coreHandler(canopyReq, segments)
- *   return convertToFrameworkResponse(response)
- * }
- * ```
+ * The core handler behind every Canopy API request. A framework adapter
+ * (Next.js, Express, Hono) converts its request to a CanopyRequest, extracts
+ * the path segments, calls this, and converts the CanopyResponse back.
  */
 export declare function createCanopyRequestHandler(options: CanopyHandlerOptions): CanopyRequestHandler;
-/**
- * Create a handler with pre-built services from config.
- */
 export declare function createCanopyRequestHandlerFromConfig(options: {
     config: CanopyConfig;
 } & Omit<CanopyHandlerOptions, 'services' | 'config'>): Promise<CanopyRequestHandler>;