canopycms 0.0.65 → 0.0.66-int.82

package/dist/worker/worker-context.d.ts

@@ -0,0 +1,133 @@
+import type { Octokit } from '@octokit/rest';
+import type { SanitizedBranchName } from '../paths/types.js';
+import type { Task, TaskQueueLogger } from './task-queue.js';
+import type { WorkerStatusReport } from '../types.js';
+/**
+ * The slice of {@link import('./cms-worker.js').CmsWorker} that its extracted
+ * clusters (task-runner.ts, git-sync.ts, rebase.ts, history-rewrite.ts) are
+ * allowed to reach.
+ *
+ * `CmsWorker` used to be 2,949 lines holding four disjoint call trees under one
+ * entry point, sharing six helper methods and a 16-field config. The clusters
+ * now live in their own modules as free functions taking this context, and the
+ * class keeps thin delegating methods. This interface is what makes the sharing
+ * explicit: it is the ONLY channel between the class and the extracted code, so
+ * "what does the rebase loop actually need from the worker?" has an answer you
+ * can read, rather than being whatever `this.` happens to resolve to.
+ *
+ * Each module narrows it further with a `Pick<WorkerContext, ...>` alias, so a
+ * function's signature names its real dependency set rather than the union.
+ *
+ * ## Why the second group are FUNCTIONS, not fields
+ *
+ * Everything below the divider is resolved by CALLING back onto the live
+ * `CmsWorker` instance, never snapshotted into the context object. That is
+ * load-bearing, not stylistic. The worker's eight test files drive it by
+ * reaching through the instance:
+ *
+ * - `cms-worker.test.ts` and `cms-worker-sync-reconcile.test.ts` REPLACE
+ *   `buildGitHubUrl` on the instance to redirect pushes at a local fixture repo
+ *   instead of github.com;
+ * - `cms-worker-merge-poll.test.ts` and `cms-worker.test.ts` ASSIGN a mock over
+ *   the `octokit` field;
+ * - `cms-worker.test.ts` REPLACES `executeTask` (to drive the retry/timeout
+ *   paths without real work) and `pushBranchToGitHub` (to exercise the PR
+ *   actions with no git remote), then asserts on the replacement;
+ * - several set `running` directly instead of calling `start()`;
+ * - `cms-worker-content-lock.test.ts` SUBCLASSES `CmsWorker` to override the two
+ *   `afterConflictDetectedForTesting`/`afterRebaseCompletedForTesting` hooks.
+ *
+ * A context built with `octokit: this.octokit` would capture the real Octokit
+ * before the test ever installs its mock, and a captured `buildGitHubUrl` string
+ * would send a test's push to github.com for real. Writing them as functions
+ * (`ctx.octokit()`, `ctx.buildGitHubUrl()`) makes the late binding visible at
+ * every call site, which a getter would hide. `CmsWorker.ctx()` builds a fresh
+ * context per call for the same reason — there is no long-lived object for a
+ * stale reference to hide in.
+ */
+export interface WorkerContext {
+    /** GitHub owner, e.g. 'safeinsights'. */
+    readonly githubOwner: string;
+    /** GitHub repo name. */
+    readonly githubRepo: string;
+    /**
+     * The base branch's RAW git ref name. Git refs (fetch/rev-list/merge against
+     * it) must use this; filesystem paths must use `sanitizedBaseBranch`.
+     */
+    readonly baseBranch: string;
+    /**
+     * The base branch's workspace DIRECTORY name. Computed once so every
+     * filesystem call site agrees instead of re-deriving it and risking drift.
+     */
+    readonly sanitizedBaseBranch: SanitizedBranchName;
+    /** `{workspacePath}/.tasks` — the task queue and worker-status.json. */
+    readonly taskDir: string;
+    /** `{workspacePath}/remote.git` — the shared bare repo. */
+    readonly remoteGitPath: string;
+    /** `{workspacePath}/content-branches` — the branch workspace root. */
+    readonly contentBranchesPath: string;
+    /** Content root directory name relative to repo root (default: 'content'). */
+    readonly contentRoot: string;
+    /** Per-task timeout in ms; also simple-git's inactivity block timeout. */
+    readonly taskTimeoutMs: number;
+    /** Max tasks to process per `processTaskQueue` cycle. */
+    readonly maxTasksPerCycle: number;
+    /** Default max retries for a failed task that does not carry its own. */
+    readonly maxRetries: number;
+    /** Task-queue debug logger. */
+    readonly log: TaskQueueLogger;
+    /** The worker's Octokit client, read at call time (tests replace it). */
+    octokit(): Octokit;
+    /**
+     * The tokenized GitHub clone URL, read at call time (tests replace this
+     * method to point at a local fixture repo).
+     *
+     * Anything derived from it can embed the bot token, so a message that reaches
+     * worker-status.json, branch.json or a task file must go through
+     * `redactCredentials` first.
+     */
+    buildGitHubUrl(): string;
+    /**
+     * Workspace directory for a branch named by its GIT REF name — the form task
+     * payloads carry. Sanitizes; `feature/x` lives in `feature-x`.
+     */
+    branchWorkspacePath(branchRefName: string): string;
+    /**
+     * Run one task, read at call time.
+     *
+     * Routed back through the instance even though the implementation lives in
+     * task-runner.ts beside its only caller, because cms-worker.test.ts REPLACES
+     * this method on the instance to drive the retry and timeout paths without
+     * doing real work. `executeTaskWithTimeout` must therefore call
+     * `ctx.executeTask(...)`, never the module-level function directly -- doing
+     * the latter silently bypasses the stub and the tests go red.
+     */
+    executeTask(task: Task, signal: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Push a branch from remote.git to GitHub, read at call time.
+     *
+     * Routed through the instance for the same reason as `executeTask`:
+     * cms-worker.test.ts replaces it with a spy so the PR actions can be
+     * exercised with no git remote, and then asserts the spy was NOT called on
+     * the base-branch-refusal path.
+     */
+    pushBranchToGitHub(branch: string): Promise<void>;
+    /** Whether the worker is still running; both poll loops bail when false. */
+    isRunning(): boolean;
+    /** The worker's self-reported status object, lazily initialized. */
+    ensureStatusReport(): WorkerStatusReport;
+    /** This deployment's own settings branch name. Throws on an invalid name. */
+    ensureSettingsBranch(): string;
+    /**
+     * Test hook: fires when the rebase has reported conflicted files and is about
+     * to `checkout --theirs` them. No-op in production; overridden by a subclass
+     * in cms-worker-content-lock.test.ts.
+     */
+    afterConflictDetectedForTesting(): Promise<void>;
+    /**
+     * Test hook: fires after the rebase round loop completes, deliberately
+     * OUTSIDE its try/catch so a throwing hook can never be misread as a rebase
+     * error. No-op in production.
+     */
+    afterRebaseCompletedForTesting(): Promise<void>;
+}

package/dist/worker/worker-context.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.0.65",
+  "version": "0.0.66-int.82",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {