canopycms 0.5.0 → 0.7.0

package/dist/schema/schema-store.d.ts

@@ -74,14 +74,14 @@ declare const entryTypeInputSchema: z.ZodObject<{
     maxItems: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    format: "mdx" | "md" | "json" | "yaml";
+    format: "md" | "mdx" | "json" | "yaml";
     schema: string;
     default?: boolean | undefined;
     label?: string | undefined;
     maxItems?: number | undefined;
 }, {
     name: string;
-    format: "mdx" | "md" | "json" | "yaml";
+    format: "md" | "mdx" | "json" | "yaml";
     schema: string;
     default?: boolean | undefined;
     label?: string | undefined;
@@ -100,14 +100,14 @@ declare const createCollectionInputSchema: z.ZodObject<{
         maxItems: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         name: string;
-        format: "mdx" | "md" | "json" | "yaml";
+        format: "md" | "mdx" | "json" | "yaml";
         schema: string;
         default?: boolean | undefined;
         label?: string | undefined;
         maxItems?: number | undefined;
     }, {
         name: string;
-        format: "mdx" | "md" | "json" | "yaml";
+        format: "md" | "mdx" | "json" | "yaml";
         schema: string;
         default?: boolean | undefined;
         label?: string | undefined;
@@ -117,7 +117,7 @@ declare const createCollectionInputSchema: z.ZodObject<{
     name: string;
     entries: {
         name: string;
-        format: "mdx" | "md" | "json" | "yaml";
+        format: "md" | "mdx" | "json" | "yaml";
         schema: string;
         default?: boolean | undefined;
         label?: string | undefined;
@@ -129,7 +129,7 @@ declare const createCollectionInputSchema: z.ZodObject<{
     name: string;
     entries: {
         name: string;
-        format: "mdx" | "md" | "json" | "yaml";
+        format: "md" | "mdx" | "json" | "yaml";
         schema: string;
         default?: boolean | undefined;
         label?: string | undefined;
@@ -162,13 +162,13 @@ declare const updateEntryTypeInputSchema: z.ZodObject<{
     maxItems: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     default?: boolean | undefined;
-    format?: "mdx" | "md" | "json" | "yaml" | undefined;
+    format?: "md" | "mdx" | "json" | "yaml" | undefined;
     label?: string | undefined;
     maxItems?: number | undefined;
     schema?: string | undefined;
 }, {
     default?: boolean | undefined;
-    format?: "mdx" | "md" | "json" | "yaml" | undefined;
+    format?: "md" | "mdx" | "json" | "yaml" | undefined;
     label?: string | undefined;
     maxItems?: number | undefined;
     schema?: string | undefined;

package/dist/services.d.ts

@@ -1,20 +1,3 @@
-/**
- * `CanopyServices` — the long-lived, per-deployment service container, built
- * once by `createCanopyServices` and threaded through `ApiContext.services` to
- * every API handler. Holds config, the schema registry and cache, the ACL
- * checkers, the git-manager factory, the branch registry, the GitHub service,
- * and four branch-workflow operations. Not `context.ts`, which is the
- * per-REQUEST facade built on top of this.
- *
- * SCOPE WARNING: a service locator every api module reaches, so adding a field
- * is free and therefore constant, and no handler's signature reveals what it
- * touches. Give a new capability its own narrow interface instead.
- *
- * `createTestCanopyServices` is test-only despite living in a production
- * module; it reaches the published surface through a wildcard re-export.
- *
- * Module map: ./AGENTS.md.
- */
 import type { CanopyConfig } from './config/index.js';
 import type { EntrySchemaRegistry } from './schema/types.js';
 import type { BranchContext, BranchPaths } from './types.js';
@@ -44,6 +27,8 @@ export interface SubmitBranchResult {
     changedPaths: string[];
     /** Every recorded editor of the branch, for the PR body. */
     editors: SubmissionEditor[];
+    /** The entry logical path of each changed path that is an entry, for its editor link. */
+    entryPaths: Map<string, string>;
     /** The entries this submit stamped (stamp-on-publish.ts), for the editor's open forms. */
     stamped: StampedEntry[];
 }

package/dist/services.js

@@ -1,3 +1,22 @@
+/**
+ * `CanopyServices` — the long-lived, per-deployment service container, built
+ * once by `createCanopyServices` and threaded through `ApiContext.services` to
+ * every API handler. Holds config, the schema registry and cache, the ACL
+ * checkers, the git-manager factory, the branch registry, the GitHub service,
+ * and four branch-workflow operations. Not `context.ts`, which is the
+ * per-REQUEST facade built on top of this.
+ *
+ * SCOPE WARNING: a service locator every api module reaches, so adding a field
+ * is free and therefore constant, and no handler's signature reveals what it
+ * touches. Give a new capability its own narrow interface instead.
+ *
+ * `createTestCanopyServices` is test-only despite living in a production
+ * module; it reaches the published surface through a wildcard re-export.
+ *
+ * Module map: ./AGENTS.md.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { getConfigDefaults } from './config/index.js';
 import { createCheckBranchAccess, createCheckContentAccess, createContentAccessChecker, loadPathPermissions, } from './authorization/index.js';
 import { GitManager, GitRemoteRefMissingError } from './git-manager.js';
@@ -13,12 +32,13 @@ import { baseBranchOf } from './utils/base-branch.js';
 import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
 import { timeRequestPhase } from './utils/request-timing.js';
-import { appendTrailers, buildEditorTrailers, describeEditors, } from './submission-attribution.js';
+import { appendTrailers, buildEditorTrailers, describeEditors, MAX_LISTED_ENTRIES, } from './submission-attribution.js';
 import { getBranchMetadataFileManager, recordBranchEditor } from './branch-metadata.js';
 import { readBranchMetadataFile } from './branch-metadata-file.js';
 import { getErrorMessage, redactCredentials } from './utils/error.js';
 import { withContentWriteLock } from './utils/content-write-lock.js';
 import { ContentStore } from './content-store.js';
+import { entryLogicalPathOfFile } from './content-id-index.js';
 import { stampNewEntries } from './stamp-on-publish.js';
 /**
  * A per-instance active-branch detector with its own 5s TTL cache, in priority
@@ -217,6 +237,22 @@ async function _createCanopyServicesInternal(config, options) {
             return [];
         }
     };
+    /** The entries among `paths` that still exist, for their editor links. */
+    const existingEntryPaths = async (context, paths) => {
+        const contentRoot = services.config.contentRoot || 'content';
+        const entryPaths = new Map();
+        // Only the paths the PR body lists can carry a link.
+        await Promise.all([...new Set(paths)].slice(0, MAX_LISTED_ENTRIES).map(async (relativePath) => {
+            const entryPath = entryLogicalPathOfFile(relativePath, contentRoot);
+            if (!entryPath)
+                return;
+            // A deleted entry's link would open the editor on some other entry.
+            const stat = await fs.stat(path.join(context.branchRoot, relativePath)).catch(() => null);
+            if (stat?.isFile())
+                entryPaths.set(relativePath, entryPath);
+        }));
+        return entryPaths;
+    };
     const submitBranch = async (options) => {
         // Defense-in-depth: refuse to push the base branch to itself even if the
         // 'submittableBranch' guard was somehow bypassed. Prefer the recorded fork
@@ -316,6 +352,7 @@ async function _createCanopyServicesInternal(config, options) {
         return {
             changedPaths: submitted,
             editors: await describeEditors(editorIds, lookupEditor),
+            entryPaths: await existingEntryPaths(options.context, submitted),
             stamped,
         };
     };

package/dist/settings-workspace.d.ts

@@ -21,6 +21,10 @@ export interface EnsureSettingsWorkspaceOptions {
     mode: OperatingMode;
     remoteUrl?: string;
 }
+export interface SettingsWorkspaceManagerOptions {
+    /** @internal How long {@link SettingsWorkspaceManager} waits for another process's build. */
+    buildWaitMs?: number;
+}
 /**
  * The settings filesystem workspace and its git operations. Settings live on an
  * orphan git branch, sharing no history with content, and unlike
@@ -29,16 +33,17 @@ export interface EnsureSettingsWorkspaceOptions {
  *
  * A first clone follows [PROV-1] (branch-provisioning.ts): it is built in a
  * staging sibling and renamed into place, so a process killed mid-clone never
- * leaves a half-made workspace at the settings root. Never sparse: the orphan
- * init's `git rm -rf .` would leave out-of-cone base files in the tree.
+ * leaves a half-made workspace at the settings root.
  *
- * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
- * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
- * across processes and hosts around the publish and every in-place init.
+ * Locking: an in-memory promise lock within the process; across processes and
+ * hosts, the build lock electing one first-clone builder (`provisionStaged`),
+ * then the init lock around the publish and every in-place init. Order: build,
+ * then init.
  */
 export declare class SettingsWorkspaceManager {
     private readonly config;
-    constructor(config: CanopyConfig);
+    private readonly buildWaitMs;
+    constructor(config: CanopyConfig, options?: SettingsWorkspaceManagerOptions);
     ensureGitWorkspace(options: EnsureSettingsWorkspaceOptions): Promise<void>;
     private initOptions;
     /**
@@ -49,10 +54,19 @@ export declare class SettingsWorkspaceManager {
     private withInitLock;
     /** Re-init an existing workspace where it is; false when, under the lock, there is none. */
     private ensureInPlace;
+    /**
+     * A first clone, built once for all cold starts that arrive together: the build lock's holder
+     * builds, and the others wait for it and find the workspace published. The wait is bounded,
+     * because a builder killed mid-build keeps its marker live until it goes stale; past the bound
+     * a waiter builds its own copy, which the publish step reconciles like any race.
+     */
+    private provisionStaged;
+    /** The build lock's release, or `undefined` once the wait for another builder ran out. */
+    private claimBuild;
     /**
      * Clone and set up the settings branch in a staging sibling, then publish it under the init
      * lock, moving an interrupted first init aside to `.trash-settings-*`. A workspace someone
      * else published meanwhile wins and the staging copy is dropped.
      */
-    private provisionStaged;
+    private buildAndPublish;
 }

package/dist/settings-workspace.js

@@ -6,7 +6,7 @@ import { createDebugLogger } from './utils/debug.js';
 import { getErrorMessage, isNodeError } from './utils/error.js';
 import { canopyLogWarn } from './utils/logger.js';
 import { ProvisionLog } from './utils/provision-log.js';
-import { acquireProvisioningLock } from './utils/provisioning-lock.js';
+import { acquireProvisioningLock, acquireProvisioningLockWithin } from './utils/provisioning-lock.js';
 import { RESERVED_SETTINGS_BRANCH_PREFIX } from './paths/index.js';
 const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
 // In-memory lock against concurrent init within one process. One lock suffices,
@@ -25,9 +25,8 @@ let settingsInitLock = null;
  * dev, a hit also skips re-seeding a deleted `.canopy-dev/remote.git`; a dev-server restart
  * re-seeds it.
  *
- * A hit still reads `.git/HEAD`, so a workspace removed, re-cloned onto another branch, or
- * caught mid-clone by another process (HEAD still on the base branch) misses and runs the full
- * path, guard and lock included.
+ * A hit still reads `.git/HEAD`, so a workspace removed or re-cloned onto another branch misses
+ * and runs the full path, guard and lock included.
  */
 const ensuredSettingsWorkspaces = new Set();
 function ensuredKey(options) {
@@ -58,6 +57,14 @@ async function hasLocalBranch(settingsRoot, branchName) {
 }
 const SETTINGS_INIT_LOCK_DIR = '.settings-init';
 const SETTINGS_INIT_LOCK_NAME = 'lock';
+const SETTINGS_BUILD_LOCK_NAME = 'build';
+/**
+ * How long a cold start waits for another process's settings build before building its own.
+ * Well under the CMS Lambda's 60 s default timeout (canopycms-cdk's
+ * DEFAULT_CMS_LAMBDA_TIMEOUT) with room for the fallback build, and far under
+ * PROVISIONING_LOCK_STALE_MS, so a builder killed mid-build costs waiters this, not 90 s.
+ */
+const SETTINGS_BUILD_WAIT_MS = 15_000;
 /**
  * Directory the cross-process init lock is anchored on — a dedicated sibling of
  * the settings root, NOT the settings root itself.
@@ -105,9 +112,24 @@ async function settingsFilesPresent(settingsRoot) {
  * `config.lock` that fails every later git config write.
  */
 async function settingsRootState(options) {
+    // Listing the parent opens it, which makes NFS revalidate it (as branch-provisioning.ts's
+    // `inspectBlocking` relies on), so another host's publish is seen even where this client
+    // cached the name's absence before that publish.
+    const settingsRoot = path.resolve(options.settingsRoot);
+    let siblings;
+    try {
+        siblings = await fs.readdir(path.dirname(settingsRoot));
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return 'vacant';
+        throw err;
+    }
+    if (!siblings.includes(path.basename(settingsRoot)))
+        return 'vacant';
     let entries;
     try {
-        entries = await fs.readdir(options.settingsRoot);
+        entries = await fs.readdir(settingsRoot);
     }
     catch (err) {
         if (isNodeError(err) && err.code === 'ENOENT')
@@ -137,7 +159,7 @@ async function settingsRootState(options) {
  *
  * Without it, GitManager.initializeWorkspace sees an existing .git, skips the
  * clone, and calls createOrphanSettingsBranch(branchName); for a name neither the
- * workspace nor its remote has, git then runs `checkout --orphan <name>` + `rm -rf .` + an empty commit.
+ * workspace nor its remote has, git then runs `switch --orphan <name>` + `git rm` + an empty commit.
  * Orphan branches share no history, so that is not a migration — it
  * PERMANENTLY WIPES permissions.json/groups.json with nothing to recover from.
  * The trigger is almost always deploymentName / settingsBranch /
@@ -179,7 +201,7 @@ async function assertSettingsWorkspaceIdentity(options) {
                 : `Its current branch could not be read (${readError ?? 'unknown error'}), but it ` +
                     `holds settings files, and this deployment resolved settings branch ` +
                     `'${options.branchName}'.`) +
-            ` Proceeding would run \`git checkout --orphan\` + \`rm -rf .\` on this workspace, ` +
+            ` Proceeding would run \`git switch --orphan\` + \`git rm\` on this workspace, ` +
             `which PERMANENTLY WIPES permissions.json/groups.json (orphan branches share no ` +
             `history — there is nothing to migrate from). This almost always means ` +
             `deploymentName, settingsBranch, or CANOPYCMS_DEPLOYMENT_NAME changed on a ` +
@@ -198,16 +220,17 @@ async function assertSettingsWorkspaceIdentity(options) {
  *
  * A first clone follows [PROV-1] (branch-provisioning.ts): it is built in a
  * staging sibling and renamed into place, so a process killed mid-clone never
- * leaves a half-made workspace at the settings root. Never sparse: the orphan
- * init's `git rm -rf .` would leave out-of-cone base files in the tree.
+ * leaves a half-made workspace at the settings root.
  *
- * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
- * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
- * across processes and hosts around the publish and every in-place init.
+ * Locking: an in-memory promise lock within the process; across processes and
+ * hosts, the build lock electing one first-clone builder (`provisionStaged`),
+ * then the init lock around the publish and every in-place init. Order: build,
+ * then init.
  */
 export class SettingsWorkspaceManager {
-    constructor(config) {
+    constructor(config, options = {}) {
         this.config = config;
+        this.buildWaitMs = options.buildWaitMs ?? SETTINGS_BUILD_WAIT_MS;
     }
     async ensureGitWorkspace(options) {
         const key = ensuredKey(options);
@@ -299,12 +322,50 @@ export class SettingsWorkspaceManager {
             return true;
         });
     }
+    /**
+     * A first clone, built once for all cold starts that arrive together: the build lock's holder
+     * builds, and the others wait for it and find the workspace published. The wait is bounded,
+     * because a builder killed mid-build keeps its marker live until it goes stale; past the bound
+     * a waiter builds its own copy, which the publish step reconciles like any race.
+     */
+    async provisionStaged(options) {
+        const releaseBuild = await this.claimBuild(options);
+        try {
+            if ((await settingsRootState(options)) === 'in-use') {
+                // Another process published it; the guard decides whether it is this deployment's.
+                await assertSettingsWorkspaceIdentity(options);
+                return;
+            }
+            await this.buildAndPublish(options);
+        }
+        finally {
+            try {
+                await releaseBuild?.();
+            }
+            catch (err) {
+                log.debug('workspace', 'Failed to release settings-build lock', { err });
+            }
+        }
+    }
+    /** The build lock's release, or `undefined` once the wait for another builder ran out. */
+    async claimBuild(options) {
+        try {
+            return await acquireProvisioningLockWithin(settingsInitLockTarget(options.settingsRoot), SETTINGS_BUILD_LOCK_NAME, this.buildWaitMs);
+        }
+        catch (err) {
+            if (!isNodeError(err) || err.code !== 'ELOCKED')
+                throw err;
+            canopyLogWarn(`[canopy] Another process's settings workspace build did not finish within ` +
+                `${this.buildWaitMs} ms; building one here`);
+            return undefined;
+        }
+    }
     /**
      * Clone and set up the settings branch in a staging sibling, then publish it under the init
      * lock, moving an interrupted first init aside to `.trash-settings-*`. A workspace someone
      * else published meanwhile wins and the staging copy is dropped.
      */
-    async provisionStaged(options) {
+    async buildAndPublish(options) {
         const settingsRoot = path.resolve(options.settingsRoot);
         const workspaceRoot = path.dirname(settingsRoot);
         await fs.mkdir(workspaceRoot, { recursive: true });
@@ -318,14 +379,28 @@ export class SettingsWorkspaceManager {
             });
             published = await provisionLog.step('publish', () => this.withInitLock(options, async () => {
                 const state = await settingsRootState(options);
-                if (state === 'in-use')
+                if (state === 'in-use') {
+                    // The guard above may have missed a workspace this fresher read sees.
+                    await assertSettingsWorkspaceIdentity(options);
                     return false;
+                }
                 if (state === 'interrupted') {
                     const trashName = settingsTrashDirName();
                     await fs.rename(settingsRoot, path.join(workspaceRoot, trashName));
                     canopyLogWarn(`[canopy] Moved an unfinished settings workspace clone aside as ${trashName}`);
                 }
-                await fs.rename(stagingPath, settingsRoot);
+                try {
+                    await fs.rename(stagingPath, settingsRoot);
+                }
+                catch (err) {
+                    // The server refuses the rename when the root holds what the state read above
+                    // missed; a fresh read decides whether that is a published workspace.
+                    const occupied = isNodeError(err) && (err.code === 'ENOTEMPTY' || err.code === 'EEXIST');
+                    if (!occupied || (await settingsRootState(options)) !== 'in-use')
+                        throw err;
+                    await assertSettingsWorkspaceIdentity(options);
+                    return false;
+                }
                 return true;
             }));
         }

package/dist/submission-attribution.d.ts

@@ -1,5 +1,6 @@
 import type { UserSearchResult } from './auth/types.js';
 import type { CanopyUser } from './user.js';
+import type { CommentThread } from './comment-store.js';
 /**
  * Who submitted (and edited) a branch, recorded in the submit commit's trailers
  * and the pull request body. The bot stays the commit author; these records are
@@ -14,6 +15,8 @@ export interface SubmissionEditor {
     name?: string;
     email?: string;
 }
+/** How many changed paths the PR body lists. */
+export declare const MAX_LISTED_ENTRIES = 100;
 /**
  * The PR body region canopycms owns. On update only the text between these
  * markers is replaced, so anything a human wrote around it survives.
@@ -22,6 +25,14 @@ export interface SubmissionEditor {
 export declare const PR_SECTION_START = "<!-- canopycms:submission:start -->";
 /** @internal Exported for tests. */
 export declare const PR_SECTION_END = "<!-- canopycms:submission:end -->";
+/**
+ * The editor-comment summary, nested in the section so a comment change can replace it alone:
+ * the rest of the section is built from the submit (mergeCommentsBlock).
+ * @internal Exported for tests.
+ */
+export declare const PR_COMMENTS_START = "<!-- canopycms:comments:start -->";
+/** @internal Exported for tests. */
+export declare const PR_COMMENTS_END = "<!-- canopycms:comments:end -->";
 /**
  * A display name safe for a single line of git trailer or Markdown, or undefined.
  * @internal Exported for tests.
@@ -68,8 +79,27 @@ export interface PrSectionInput {
     editors?: readonly SubmissionEditor[];
     /** Repo-relative paths changed on the branch. */
     changedPaths: readonly string[];
+    /** The submitted branch and the editor page URL (editor-url.ts); together they enable links. */
+    branch?: string;
+    editorUrl?: string;
+    /** The entry logical path of each changed path that is an entry, for its deep link. */
+    entryPaths?: ReadonlyMap<string, string>;
+    /** The branch's editor comment threads (comments.json), or null when they could not be read. */
+    threads?: readonly CommentThread[] | null;
 }
-/** The canopycms-owned PR body section, including its start and end markers. */
+/**
+ * The editor-comment summary between its markers: the unresolved threads, oldest first, or
+ * that every thread is resolved, or that there are none, or that they could not be read.
+ * comments.json is read without validation, so an entry that is not an object is skipped.
+ */
+export declare function buildCommentsBlock(threads: readonly CommentThread[] | null, branch?: string, editorUrl?: string): string;
+/**
+ * The canopycms-owned PR body section, including its start and end markers. GitHub refuses a
+ * body over 65,536 characters and the rest of the body is a human's, so a section whose text
+ * apart from the comment block is over MAX_SECTION_LENGTH loses its entry links, then the
+ * description's end, then entries from the end of the list. The attribution lines themselves
+ * are never cut. The comment block, rendered now or re-rendered later, has MAX_COMMENTS_LENGTH.
+ */
 export declare function buildPrSection(input: PrSectionInput): string;
 /**
  * `existing` with its canopycms section replaced by `section`, keeping every
@@ -79,3 +109,10 @@ export declare function buildPrSection(input: PrSectionInput): string;
  * removed and `section` is appended after the human text.
  */
 export declare function mergePrSection(existing: string | null | undefined, section: string): string;
+/**
+ * `existing` with the comment block inside its canopycms section replaced by `block`, or
+ * undefined when the section or its block is missing (a PR body written before the block
+ * existed, or edited by hand): the next submit writes both. Only markers inside the section
+ * count, and the description in it cannot spell one (neutralizeComments).
+ */
+export declare function mergeCommentsBlock(existing: string | null | undefined, block: string): string | undefined;