canopycms 0.7.1 → 0.8.0

package/dist/worker/task-runner.js

@@ -114,10 +114,9 @@ function isRateLimitSignal403(err) {
 }
 // Payload validation helpers — fail fast with clear errors instead of silent `as` casts
 /**
- * Whether `branch` carries the reserved settings-branch prefix. Matching on the prefix
- * alone, never on a configured name, is what keeps a content branch out: branch creation
- * rejects the prefix, while a configured name the worker and API disagree on could be a
- * content branch's.
+ * Whether `branch` carries the reserved settings-branch prefix, which routes a submit to a push
+ * with no pull request. A configured settings name without the prefix is not matched here; the
+ * gateway refuses its pull request (`BranchPolicy.assertPullRequestHeadAllowed`).
  */
 function isSettingsBranch(branch) {
     return branch.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX);
@@ -290,7 +289,7 @@ export async function executeTask(ctx, task, signal) {
             const pr = await ctx.github().createPullRequest({
                 head: branch,
                 base: optionalString(payload, 'baseBranch', ctx.baseBranch),
-                title: optionalString(payload, 'title', `Submit ${branch}`),
+                title: optionalString(payload, 'title', `Submit ${editorBranchOf(payload, branch)}`),
                 body: optionalString(payload, 'body', ''),
             }, signal);
             workerLog(`Created PR #${pr.number} for ${branch}`);
@@ -301,7 +300,7 @@ export async function executeTask(ctx, task, signal) {
             const prNumber = requireNumber(payload, 'pullRequestNumber');
             await ctx.pushBranchToGitHub(branch, signal);
             await ctx.github().updatePullRequest(prNumber, {
-                title: optionalString(payload, 'title', `Submit ${branch}`),
+                title: optionalString(payload, 'title', `Submit ${editorBranchOf(payload, branch)}`),
                 body: optionalString(payload, 'body', ''),
             }, signal);
             workerLog(`Updated PR #${prNumber} for ${branch}`);
@@ -337,7 +336,7 @@ export async function executeTask(ctx, task, signal) {
             const body = mergeSectionIntoBody
                 ? await refreshCommentsBlock({
                     branchRoot: ctx.branchWorkspacePath(branch),
-                    branch,
+                    branch: editorBranchOf(payload, branch),
                     editorUrl: typeof payload.editorUrl === 'string' ? payload.editorUrl : undefined,
                     section: queuedBody,
                     warn: workerLogWarn,
@@ -348,7 +347,7 @@ export async function executeTask(ctx, task, signal) {
                 result = await ctx.github().createOrUpdatePullRequest({
                     head: branch,
                     base,
-                    title: optionalString(payload, 'title', `Submit ${branch}`),
+                    title: optionalString(payload, 'title', `Submit ${editorBranchOf(payload, branch)}`),
                     body,
                     // Content submits (api/github-sync.ts) set both.
                     markReadyIfDraft: payload.markReadyIfDraft === true,
@@ -447,27 +446,39 @@ export async function executeTask(ctx, task, signal) {
             const pr = await ctx.github().getPullRequest(prNumber, signal);
             if (pr.state !== 'open')
                 return { updated: false, skipped: 'not-open' };
-            // A comments.json that does not parse stays so until a comment write rewrites it.
+            // Withheld: GitHub reports a head the gateway would not update the pull request of
+            // (`LocalGitHubGateway.getPullRequest`): a settings branch, one outside the namespace and not a
+            // `legacyBranches` entry, a protected one, or one in another repository.
+            if (pr.body === null) {
+                workerLog(`Not updating PR #${prNumber} for ${branch}: the gateway withholds its body`);
+                return { updated: false, skipped: 'body-withheld' };
+            }
+            // A corrupt file leaves its block as it is and the other block still updates; any other read
+            // error throws, so the task is retried.
             const body = await renderPrCommentsBody({
                 branchRoot: branchPath,
-                branch,
+                branch: editorBranchOf(payload, branch),
                 editorUrl,
                 body: pr.body,
-            }).catch((err) => {
-                if (err instanceof SyntaxError)
-                    throw new PermanentTaskError(getErrorMessage(err));
-                throw err;
+                warn: workerLogWarn,
             });
             if (body === undefined)
                 return { updated: false, skipped: 'unchanged' };
             await ctx.github().updatePullRequest(prNumber, { body }, signal);
-            workerLog(`Updated the editor comments on PR #${prNumber} for ${branch}`);
+            workerLog(`Updated the comment and review blocks of PR #${prNumber} for ${branch}`);
             return { updated: true };
         }
         default:
             throw new PermanentTaskError(`Unknown task action: ${action}`);
     }
 }
+/**
+ * The name links and a fallback title give the branch: the short name the API queued
+ * (branch-param.ts), else the ref, which the editor resolves too.
+ */
+function editorBranchOf(payload, branch) {
+    return optionalString(payload, 'editorBranch', branch);
+}
 /**
  * The branch whose metadata records a task's outcome, or null when none does. A
  * delete-remote-branch task names a branch already deleted here, so a workspace under that
@@ -479,7 +490,17 @@ function metadataBranchOf(task) {
     return typeof task.payload.branch === 'string' ? task.payload.branch : null;
 }
 /**
- * Update branch metadata after successful task completion.
+ * Logs an outcome write skipped because `branch`'s workspace has no branch.json whose `name` is
+ * `branch`: none at all, or another branch's that shares its key.
+ */
+function noMetadataToRecord(branch, what) {
+    workerLogWarn(`Not recording the ${what} for ${branch}: its workspace has no branch.json for it`);
+}
+/**
+ * Update branch metadata after successful task completion. Like every outcome write here, it
+ * updates only a branch.json whose `name` is the task's ref: a workspace without one is not a
+ * branch whose name could be recorded, and one naming another ref is that branch's
+ * (`noMetadataToRecord`).
  */
 export async function updateBranchMetadata(ctx, task, result) {
     const branch = metadataBranchOf(task);
@@ -494,32 +515,36 @@ export async function updateBranchMetadata(ctx, task, result) {
     }
     try {
         const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
-        const updates = {
-            name: branch,
-            syncStatus: 'synced',
-            // save()'s merge only overwrites keys present in this update, so a prior
-            // syncFailureReason would survive this successful sync forever unless
-            // cleared explicitly (same pattern as rebaseFailure elsewhere).
-            syncFailureReason: undefined,
-        };
-        if (result.prUrl)
-            updates.pullRequestUrl = result.prUrl;
-        if (result.prNumber) {
-            updates.pullRequestNumber = result.prNumber;
-            // As soon as the PR exists the field reads 'open', rather than staying
-            // absent until the next poll cycle observes it. Exception: the git-sync
-            // loop may have archived this branch (PR merged/closed) while the task
-            // was in flight, and a late completion must not downgrade that terminal
-            // state back to 'open'.
-            const current = await BranchMetadataFileManager.loadOnly(branchPath);
-            const terminal = current?.branch.status === 'archived' ||
-                current?.branch.pullRequestState === 'merged' ||
-                current?.branch.pullRequestState === 'closed';
-            if (!terminal) {
-                updates.pullRequestState = 'open';
+        const saved = await meta.update((existing) => {
+            if (existing?.branch.name !== branch)
+                return null;
+            const updates = {
+                syncStatus: 'synced',
+                // save()'s merge only overwrites keys present in this update, so a prior
+                // syncFailureReason would survive this successful sync forever unless
+                // cleared explicitly (same pattern as rebaseFailure elsewhere).
+                syncFailureReason: undefined,
+            };
+            if (result.prUrl)
+                updates.pullRequestUrl = result.prUrl;
+            if (result.prNumber) {
+                updates.pullRequestNumber = result.prNumber;
+                // As soon as the PR exists the field reads 'open', rather than staying
+                // absent until the next poll cycle observes it. Exception: the git-sync
+                // loop may have archived this branch (PR merged/closed) while the task
+                // was in flight, and a late completion must not downgrade that terminal
+                // state back to 'open'.
+                const terminal = existing.branch.status === 'archived' ||
+                    existing.branch.pullRequestState === 'merged' ||
+                    existing.branch.pullRequestState === 'closed';
+                if (!terminal) {
+                    updates.pullRequestState = 'open';
+                }
             }
-        }
-        await meta.save({ branch: updates });
+            return { branch: updates };
+        });
+        if (saved === null)
+            noMetadataToRecord(branch, `${task.action} outcome`);
     }
     catch (err) {
         workerLogError(`Failed to update metadata for ${branch}:`, err instanceof Error ? err.message : err);
@@ -548,7 +573,7 @@ async function updateBranchMetadataOnFailure(ctx, task, error, options) {
     }
     try {
         const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
-        const failed = { name: branch, syncStatus: 'sync-failed', syncFailureReason: error };
+        const failed = { syncStatus: 'sync-failed', syncFailureReason: error };
         const submittedAt = task.payload.submittedAt;
         const unlocked = options.unlock &&
             typeof submittedAt === 'string' &&
@@ -558,11 +583,15 @@ async function updateBranchMetadataOnFailure(ctx, task, error, options) {
                     status: 'editing',
                     syncFailureReason: `${error} The branch is unlocked for editing; save a change, then submit again.`,
                 },
-            }, (existing) => existing?.branch.status === 'submitted' &&
+            }, (existing) => existing?.branch.name === branch &&
+                existing.branch.status === 'submitted' &&
                 existing.branch.pullRequestNumber === undefined &&
                 existing.branch.submittedAt === submittedAt)) !== null;
-        if (!unlocked)
-            await meta.save({ branch: failed });
+        if (!unlocked) {
+            const saved = await meta.saveIf({ branch: failed }, (existing) => existing?.branch.name === branch);
+            if (saved === null)
+                noMetadataToRecord(branch, `${task.action} failure`);
+        }
     }
     catch (err) {
         workerLogError(`Failed to update failure metadata for ${branch}:`, err instanceof Error ? err.message : err);
@@ -708,9 +737,9 @@ async function recordPushedToGitHub(ctx, branchPath, branch) {
         return;
     }
     try {
-        await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).save({
-            branch: { name: branch, pushedToGitHubAt: new Date().toISOString() },
-        });
+        const saved = await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).saveIf({ branch: { pushedToGitHubAt: new Date().toISOString() } }, (existing) => existing?.branch.name === branch);
+        if (saved === null)
+            noMetadataToRecord(branch, 'GitHub push');
     }
     catch (err) {
         workerLogError(`Failed to record the GitHub push for ${branch}:`, getErrorMessage(err));

package/dist/worker/unpublishable-branches.d.ts

@@ -0,0 +1,34 @@
+import type { UnpublishableBranchesReport, WorkerStatusReport } from '../types.js';
+import { type BranchPolicyDescription } from './branch-policy.js';
+import type { WorkerContext } from './worker-context.js';
+/**
+ * The most branches a report lists; its `count` says how many there are.
+ * @internal Exported for tests.
+ */
+export declare const MAX_UNPUBLISHABLE_LISTED = 50;
+/**
+ * The editor branches the gateway that described its policy as `policy` would refuse to push.
+ * Each is the `name` its branch.json records, the git ref: the directory holding it is only the
+ * ref sanitized, and `cms/prod/x` and a legacy `cms-prod-x` share one. Only a directory can be a
+ * branch: a regular file, such as `branches.json` or a registry write's temp file, or a symlink,
+ * is skipped. A directory with no branch.json, or a corrupt one, is no branch. Throws when the
+ * branches directory or a branch directory's branch.json cannot be read, so the caller keeps the
+ * last report.
+ */
+export declare function findUnpublishableBranches(ctx: Pick<WorkerContext, 'contentBranchesPath' | 'sanitizedBaseBranch'>, policy: BranchPolicyDescription): Promise<Omit<UnpublishableBranchesReport, 'at'>>;
+/**
+ * The report in the status file a previous worker process left, so a restarted worker shows it
+ * until its first sync can ask the gateway. Tolerant: an unreadable or malformed file carries
+ * nothing.
+ */
+export declare function readCarriedUnpublishableBranches(taskDir: string): Promise<UnpublishableBranchesReport | undefined>;
+/**
+ * The gateway's namespace and protected names from the status file a previous worker process
+ * left, so branch creation, which waits for the namespace, keeps working across a restart until
+ * the first sync asks the gateway again. The Lambda can write the status file, so they are carried
+ * only in the shape git sync writes: a namespace `branchNamespaceProblem` takes, and at most one
+ * more name than `protectedBranches` holds, each exact and no longer than a branch name. Tolerant:
+ * no namespace, or one in any other shape, carries nothing, and a list in any other shape
+ * carries the namespace alone.
+ */
+export declare function readCarriedGatewayPolicy(taskDir: string): Promise<Pick<WorkerStatusReport, 'gatewayBranchNamespace' | 'gatewayProtectedBranches'>>;

package/dist/worker/unpublishable-branches.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { BranchMetadataCorruptError, BranchMetadataFileManager } from '../branch-metadata.js';
+import { branchNamespaceProblem } from '../operating-mode/branch-namespace.js';
+import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
+import { isNodeError } from '../utils/error.js';
+import { MAX_BRANCH_NAME_LENGTH, MAX_PROTECTED_BRANCHES, legacyBranchProblem, publishesBranch, } from './branch-policy.js';
+/**
+ * The most branches a report lists; its `count` says how many there are.
+ * @internal Exported for tests.
+ */
+export const MAX_UNPUBLISHABLE_LISTED = 50;
+/**
+ * Why a `legacyBranches` entry would not publish `name` in `namespace`, or undefined when one
+ * would. The ancestor test is the `BranchPolicy` constructor's and `namespaceBlocker`'s.
+ */
+function reasonFor(name, namespace) {
+    if (namespace.startsWith(`${name}/`))
+        return 'blocks-namespace';
+    if (legacyBranchProblem(name) !== null)
+        return 'unlistable';
+    return undefined;
+}
+/**
+ * The editor branches the gateway that described its policy as `policy` would refuse to push.
+ * Each is the `name` its branch.json records, the git ref: the directory holding it is only the
+ * ref sanitized, and `cms/prod/x` and a legacy `cms-prod-x` share one. Only a directory can be a
+ * branch: a regular file, such as `branches.json` or a registry write's temp file, or a symlink,
+ * is skipped. A directory with no branch.json, or a corrupt one, is no branch. Throws when the
+ * branches directory or a branch directory's branch.json cannot be read, so the caller keeps the
+ * last report.
+ */
+export async function findUnpublishableBranches(ctx, policy) {
+    let entries;
+    try {
+        entries = await fs.readdir(ctx.contentBranchesPath, { withFileTypes: true });
+    }
+    catch (err) {
+        // `withFileTypes` may lstat each entry, so an entry removed mid-listing rejects with its own
+        // ENOENT: only the branches directory's absence means no branches.
+        if (!isNodeError(err) || err.code !== 'ENOENT')
+            throw err;
+        if (typeof err.path !== 'string' ||
+            path.resolve(err.path) !== path.resolve(ctx.contentBranchesPath)) {
+            throw err;
+        }
+        entries = [];
+    }
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    const branches = [];
+    for (const dir of dirs.sort()) {
+        // The base branch is protected and never published; the `.trash-*` directories purged
+        // branches wait in are not branches.
+        if (dir.startsWith('.') || dir === ctx.sanitizedBaseBranch)
+            continue;
+        let meta;
+        try {
+            meta = await BranchMetadataFileManager.loadOnly(path.join(ctx.contentBranchesPath, dir));
+        }
+        catch (err) {
+            // Corrupt metadata is no branch, and a directory removed since the listing holds none.
+            const notABranch = err instanceof BranchMetadataCorruptError || (isNodeError(err) && err.code === 'ENOENT');
+            if (!notABranch)
+                throw err;
+            meta = null;
+        }
+        const branch = meta?.branch;
+        if (!branch || branch.status === 'archived')
+            continue;
+        if (publishesBranch(policy, branch.name))
+            continue;
+        const reason = reasonFor(branch.name, policy.namespace);
+        branches.push(reason ? { name: branch.name, reason } : { name: branch.name });
+    }
+    return { branches: branches.slice(0, MAX_UNPUBLISHABLE_LISTED), count: branches.length };
+}
+const REASONS = new Set([
+    'blocks-namespace',
+    'unlistable',
+]);
+function isReason(value) {
+    return REASONS.has(value);
+}
+/** The most branches a carried report may claim to hold; a real workspace has far fewer. */
+const MAX_CARRIED_COUNT = 100_000;
+/** The longest timestamp a carried report's `at` may be; an ISO 8601 instant is 24. */
+const MAX_CARRIED_AT_LENGTH = 32;
+/**
+ * The report `value` holds, rebuilt from the fields `findUnpublishableBranches` writes, or
+ * undefined when `value` is not one it could have made: at most MAX_UNPUBLISHABLE_LISTED names,
+ * none longer than a branch name can be, a whole `count` no smaller than the list and at most
+ * MAX_CARRIED_COUNT, and an `at` that parses as a date within MAX_CARRIED_AT_LENGTH characters.
+ * The Lambda can write the status file, so nothing else it holds is carried.
+ */
+function carriedReport(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (!('branches' in value) || !('count' in value) || !('at' in value))
+        return undefined;
+    const { branches, count, at } = value;
+    if (typeof at !== 'string' ||
+        at.length > MAX_CARRIED_AT_LENGTH ||
+        !Number.isFinite(Date.parse(at)) ||
+        !Array.isArray(branches) ||
+        branches.length > MAX_UNPUBLISHABLE_LISTED ||
+        typeof count !== 'number' ||
+        !Number.isInteger(count) ||
+        count < branches.length ||
+        count > MAX_CARRIED_COUNT) {
+        return undefined;
+    }
+    const carried = [];
+    for (const entry of branches) {
+        if (typeof entry !== 'object' ||
+            entry === null ||
+            !('name' in entry) ||
+            typeof entry.name !== 'string' ||
+            entry.name.length > MAX_BRANCH_NAME_LENGTH) {
+            return undefined;
+        }
+        if (!('reason' in entry)) {
+            carried.push({ name: entry.name });
+        }
+        else if (isReason(entry.reason)) {
+            carried.push({ name: entry.name, reason: entry.reason });
+        }
+        else {
+            return undefined;
+        }
+    }
+    return { branches: carried, count, at };
+}
+/**
+ * The report in the status file a previous worker process left, so a restarted worker shows it
+ * until its first sync can ask the gateway. Tolerant: an unreadable or malformed file carries
+ * nothing.
+ */
+export async function readCarriedUnpublishableBranches(taskDir) {
+    const parsed = await readStatusObject(taskDir);
+    if (parsed === undefined || !('unpublishableBranches' in parsed))
+        return undefined;
+    return carriedReport(parsed.unpublishableBranches);
+}
+/**
+ * The gateway's namespace and protected names from the status file a previous worker process
+ * left, so branch creation, which waits for the namespace, keeps working across a restart until
+ * the first sync asks the gateway again. The Lambda can write the status file, so they are carried
+ * only in the shape git sync writes: a namespace `branchNamespaceProblem` takes, and at most one
+ * more name than `protectedBranches` holds, each exact and no longer than a branch name. Tolerant:
+ * no namespace, or one in any other shape, carries nothing, and a list in any other shape
+ * carries the namespace alone.
+ */
+export async function readCarriedGatewayPolicy(taskDir) {
+    const parsed = await readStatusObject(taskDir);
+    if (parsed === undefined || !('gatewayBranchNamespace' in parsed))
+        return {};
+    const namespace = parsed.gatewayBranchNamespace;
+    if (typeof namespace !== 'string' || branchNamespaceProblem(namespace) !== null)
+        return {};
+    const names = 'gatewayProtectedBranches' in parsed ? parsed.gatewayProtectedBranches : undefined;
+    return isExactNameList(names)
+        ? { gatewayBranchNamespace: namespace, gatewayProtectedBranches: names }
+        : { gatewayBranchNamespace: namespace };
+}
+function isExactNameList(value) {
+    return (Array.isArray(value) &&
+        value.length <= MAX_PROTECTED_BRANCHES + 1 &&
+        value.every((name) => typeof name === 'string' &&
+            name.length > 0 &&
+            name.length <= MAX_BRANCH_NAME_LENGTH &&
+            !name.includes('*')));
+}
+/** The status file's top-level object, or undefined when it is missing, unreadable or not one. */
+async function readStatusObject(taskDir) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path.join(taskDir, WORKER_STATUS_FILE), 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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.7.1",
+  "version": "0.8.0",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {
@@ -126,6 +126,7 @@
     "content-disposition": "^2.0.1",
     "dataloader": "^2.2.3",
     "dayjs": "1.11.21",
+    "diff": "9.0.0",
     "fast-deep-equal": "^3.1.3",
     "file-type": "^21.3.2",
     "gray-matter": "^4.0.3",