canopycms 0.5.0 → 0.7.0

package/dist/cli/github-app-output.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What `init-github-app` says to the operator, as strings. Each stream gets
+ * its own palette, on only when that stream is a TTY (or FORCE_COLOR asks for
+ * it) and NO_COLOR is unset. picocolors' own default also turns colour on for
+ * `CI` and on Windows whatever the stream is, which would put escape codes in
+ * a piped log.
+ */
+import pc from 'picocolors';
+type Palette = ReturnType<typeof pc.createColors>;
+/** For anything printed with `console.log`. */
+export declare const outColors: import("picocolors/types").Colors;
+/** For anything printed with `console.error`. */
+export declare const errColors: import("picocolors/types").Colors;
+export declare const tick: (text: string) => string;
+export declare const failMark: string;
+export declare const cross: (text: string) => string;
+/** `palette` is the stream the line goes to. */
+export declare const link: (url: string, palette?: Palette) => string;
+export declare const step: (n: number, text: string) => string;
+/** Printed before the browser opens, so it survives a terminal that is gone by the time it matters. */
+export declare function recoveryPreamble(): string;
+export type RegistrationMessageInput = {
+    name: string;
+    owner: string;
+    repo: string;
+    /** `describeDestination`'s wording of where the key is going. */
+    destination: string;
+    formFile: string;
+    callbackPort: number;
+    timeoutMinutes: number;
+};
+export declare function registrationMessage(input: RegistrationMessageInput): string;
+export declare function deploymentSettingsMessage(appId: number, installationId: number | null): string;
+export {};

package/dist/cli/github-app-output.js

@@ -0,0 +1,85 @@
+/**
+ * What `init-github-app` says to the operator, as strings. Each stream gets
+ * its own palette, on only when that stream is a TTY (or FORCE_COLOR asks for
+ * it) and NO_COLOR is unset. picocolors' own default also turns colour on for
+ * `CI` and on Windows whatever the stream is, which would put escape codes in
+ * a piped log.
+ */
+import pc from 'picocolors';
+import { CANOPY_APP_PERMISSIONS } from './github-app-manifest.js';
+function colorsFor(stream) {
+    const { NO_COLOR, FORCE_COLOR, TERM } = process.env;
+    if (NO_COLOR)
+        return pc.createColors(false);
+    if (FORCE_COLOR)
+        return pc.createColors(FORCE_COLOR !== '0' && FORCE_COLOR !== 'false');
+    return pc.createColors(Boolean(stream.isTTY) && TERM !== 'dumb');
+}
+/** For anything printed with `console.log`. */
+export const outColors = colorsFor(process.stdout);
+/** For anything printed with `console.error`. */
+export const errColors = colorsFor(process.stderr);
+export const tick = (text) => `${outColors.green('✓')} ${text}`;
+export const failMark = errColors.red('✗');
+export const cross = (text) => `${failMark} ${text}`;
+/** `palette` is the stream the line goes to. */
+export const link = (url, palette = outColors) => palette.cyan(palette.underline(url));
+export const step = (n, text) => outColors.bold(outColors.cyan(`${n}.`) + ` ${text}`);
+/** Printed before the browser opens, so it survives a terminal that is gone by the time it matters. */
+export function recoveryPreamble() {
+    return [
+        outColors.bold(outColors.yellow('If this goes wrong after you click Create')),
+        '  The App will exist, but this command will not have its private key. To recover, either:',
+        '    • delete the App in its settings and re-run this command, or',
+        '    • open the App, scroll to "Private keys" and click "Generate a private key". The',
+        '      .pem it downloads is your only chance to save it.',
+        outColors.dim('  (Not the "client secret" a few sections above: that is for OAuth user flows, is unused\n' +
+            '  by this App, and fails confusingly when used to sign.)'),
+        '',
+    ].join('\n');
+}
+export function registrationMessage(input) {
+    const width = Math.max(...Object.keys(CANOPY_APP_PERMISSIONS).map((name) => name.length));
+    const permissions = Object.entries(CANOPY_APP_PERMISSIONS).map(([name, level]) => `  ${name.padEnd(width)}  ${outColors.bold(level)}`);
+    return [
+        outColors.bold(`Registering "${input.name}" for ${input.owner}/${input.repo}`),
+        '',
+        `${outColors.bold('Permissions')} ${outColors.dim('(the part that matters)')}`,
+        ...permissions,
+        '',
+        `${outColors.bold('Private key')} goes to ${input.destination}`,
+        outColors.dim('  If that fails you are asked for somewhere else before the key is discarded.'),
+        '',
+        step(1, 'Open this file in a browser:'),
+        '',
+        `   ${link(input.formFile)}`,
+        '',
+        '   The browser matters, twice over. It must be:',
+        `     • ${outColors.bold('logged in to GitHub')} as an owner of ${input.owner}`,
+        `     • running ${outColors.bold('on this machine')}: the redirect returns to 127.0.0.1:${input.callbackPort}, which only a local browser can reach`,
+        outColors.dim('   An embedded or app-internal browser bounces off the GitHub login wall and appears\n' +
+            '   to do nothing when you click Create.'),
+        '',
+        '   The page posts the manifest to GitHub, which shows the App pre-filled with exactly',
+        '   those permissions. Review them and click Create.',
+        '',
+        outColors.dim(`Waiting for GitHub to redirect back (up to ${input.timeoutMinutes} minutes)...`),
+    ].join('\n');
+}
+export function deploymentSettingsMessage(appId, installationId) {
+    return [
+        '',
+        outColors.bold('Set these on your deployment'),
+        '',
+        `  GITHUB_APP_ID=${appId}`,
+        `  GITHUB_APP_INSTALLATION_ID=${installationId ?? '<run `verify` to read it>'}`,
+        `  GITHUB_APP_PRIVATE_KEY_SECRET_ARN=<wherever you just put the key>`,
+        '',
+        outColors.dim('  Both ids are numeric. The App ID is NOT the "Client ID" (`Iv1.…`) shown beside it,\n' +
+            '  and the installation id is NOT the App ID: an App installed twice has one App ID\n' +
+            '  and two installation ids.'),
+        '',
+        outColors.bold('Re-check this any time, without creating anything'),
+        `  canopycms init-github-app verify --app-id ${appId} --key-file <path>`,
+    ].join('\n');
+}

package/dist/cli/init-github-app.d.ts

@@ -43,6 +43,24 @@ type KeyDestination = {
     kind: 'file';
     filePath: string;
 };
+/**
+ * The App's own settings page.
+ * @internal Exported for tests.
+ */
+export declare function appSettingsUrl(target: AppTarget, slug: string): string;
+/**
+ * The recovery note printed when the key could not be stored.
+ * @internal Exported for tests.
+ */
+export declare function keyNotStoredMessage(target: AppTarget, created: {
+    id: number;
+    slug: string;
+}): string;
+/**
+ * Step 2 of `create`: where to install the App.
+ * @internal Exported for tests.
+ */
+export declare function installStepMessage(target: AppTarget, slug: string): string;
 /**
  * Where the manifest form posts: user-owned and organisation repositories use
  * different URLs, and posting the wrong one fails at the form.

package/dist/cli/init-github-app.js

@@ -33,20 +33,56 @@ import { Readable } from 'node:stream';
 import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.js';
 import { normalizeGitHubAppPrivateKey } from '../worker/github-auth.js';
 import { APP_NAME_MAX_LENGTH, CANOPY_APP_PERMISSIONS, appDescription, appName, appSlug, readbackVerdict, } from './github-app-manifest.js';
+import { cross, deploymentSettingsMessage, errColors, failMark, link, outColors, recoveryPreamble, registrationMessage, step, tick, } from './github-app-output.js';
 import { askLine, pressEnter } from './prompt.js';
 /** How long `create` waits for the browser round trip before giving up. */
 const CALLBACK_TIMEOUT_MS = 10 * 60 * 1000;
 /** How long any single call to api.github.com may take. */
 const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Organisation-owned and user-owned Apps live under different paths, and each
+ * form 404s or fails for the other's. Every App URL the command builds starts here.
+ */
+function appsBaseUrl(target) {
+    return target.isOrganization
+        ? `https://github.com/organizations/${encodeURIComponent(target.owner)}/settings/apps`
+        : 'https://github.com/settings/apps';
+}
+/**
+ * The App's own settings page.
+ * @internal Exported for tests.
+ */
+export function appSettingsUrl(target, slug) {
+    return `${appsBaseUrl(target)}/${encodeURIComponent(slug)}`;
+}
+/**
+ * The recovery note printed when the key could not be stored.
+ * @internal Exported for tests.
+ */
+export function keyNotStoredMessage(target, created) {
+    return (`\n${errColors.bold(errColors.red('Stopping here:'))} the App exists but its key was not stored, so installing it now\n` +
+        '  would achieve nothing. To recover, open the App and generate a private key from\n' +
+        '  its "Private keys" section, then run `verify`; or delete the App and start again.\n\n' +
+        `  GITHUB_APP_ID=${created.id}\n` +
+        `  App settings: ${link(appSettingsUrl(target, created.slug), errColors)}`);
+}
+/**
+ * Step 2 of `create`: where to install the App.
+ * @internal Exported for tests.
+ */
+export function installStepMessage(target, slug) {
+    return (`\n${step(2, `Install it on ${target.owner}/${target.repo}:`)}\n\n` +
+        `   ${link(`${appSettingsUrl(target, slug)}/installations`)}\n\n` +
+        '   That page shows an Install button first — the repository picker only appears after\n' +
+        '   you click it. Choose "Only select repositories" and pick that one repository.\n');
+}
 /**
  * Where the manifest form posts: user-owned and organisation repositories use
  * different URLs, and posting the wrong one fails at the form.
  * @internal Exported for tests.
  */
 export function manifestPostUrl(target, state) {
-    const base = target.isOrganization
-        ? `https://github.com/organizations/${encodeURIComponent(target.owner)}/settings/apps/new`
-        : 'https://github.com/settings/apps/new';
+    const base = `${appsBaseUrl(target)}/new`;
     // The `state` rides on the ACTION URL, not inside the manifest body: it is a
     // query parameter GitHub echoes back on the redirect, and putting it in the
     // JSON would look implemented while protecting nothing.
@@ -582,7 +618,7 @@ export async function handOffWithRetry(pem, destination) {
     for (;;) {
         const result = await handOffKey(pem, attempt);
         if (result.stored) {
-            console.log(`\n  private key: ${result.detail}`);
+            console.log(`\n${tick(`Private key: ${result.detail}`)}`);
             return true;
         }
         console.error(`\n  THE PRIVATE KEY WAS NOT STORED: ${result.detail}\n\n` +
@@ -718,17 +754,17 @@ async function readBackInstallation(appId, privateKey, target) {
         return { ok: false, installationId: null };
     }
     const installation = found.body;
-    console.log(`\n  installation ${installation.id} on ${target.owner}/${target.repo}`);
+    console.log(`\n${outColors.bold(`Installation ${installation.id}`)} on ${target.owner}/${target.repo}`);
     const findings = readbackVerdict(installation);
     if (findings.length === 0) {
-        console.log('  grant matches exactly what this package needs:');
+        console.log('  The grant matches exactly what this package needs:');
         for (const [name, level] of Object.entries(CANOPY_APP_PERMISSIONS)) {
-            console.log(`    ✓ ${name}: ${level}`);
+            console.log(`    ${tick(`${name}: ${level}`)}`);
         }
     }
     else {
         for (const finding of findings) {
-            console.error(`    ✗ ${finding.message}`);
+            console.error(`    ${cross(finding.message)}`);
         }
     }
     // The one-App-per-site invariant, observed not asserted: EXACTLY one
@@ -737,30 +773,30 @@ async function readBackInstallation(appId, privateKey, target) {
     let installationsOk = false;
     const installations = await installationCount(jwt);
     if (installations === null) {
-        console.error('    ✗ could not list this App\'s installations, so "installed once" is UNCHECKED.\n' +
+        console.error(`    ${failMark} could not list this App's installations, so "installed once" is UNCHECKED.\n` +
             '      Reported as a failure rather than passed over: this is the check that observes\n' +
             '      the one-App-per-site rule, and an unread check is not a satisfied one.');
     }
     else if (installations === 1) {
         installationsOk = true;
-        console.log('    ✓ installed once, so this key reaches no other account');
+        console.log(`    ${tick('installed once, so this key reaches no other account')}`);
     }
     else if (installations > 1) {
-        console.error(`    ✗ this App is installed ${installations} times, and should be installed ONCE.\n` +
+        console.error(`    ${failMark} this App is installed ${installations} times, and should be installed ONCE.\n` +
             '      Its private key is App-level: whoever holds it can mint a token for any of\n' +
             '      those installations. Register a separate App per site instead, and remove\n' +
             '      the installations that do not belong to this one.');
     }
     else {
-        console.error(`    ✗ GitHub reports ${installations} installations of this App, yet one was just read\n` +
+        console.error(`    ${failMark} GitHub reports ${installations} installations of this App, yet one was just read\n` +
             '      back for this repository. Something is inconsistent; re-run before trusting it.');
     }
     const mint = await proveTokenMint(jwt, installation.id, target.repo);
     if (mint.ok) {
-        console.log(`    ✓ installation token ${mint.detail}`);
+        console.log(`    ${tick(`installation token ${mint.detail}`)}`);
     }
     else {
-        console.error(`    ✗ could not mint an installation token — ${mint.detail}\n` +
+        console.error(`    ${failMark} could not mint an installation token — ${mint.detail}\n` +
             '      If that message says the requested permissions are not granted to this\n' +
             '      installation, that is a GitHub behaviour rather than a bug here: adding a\n' +
             '      permission to an App does NOT apply to existing installations until an account\n' +
@@ -854,14 +890,7 @@ async function createCommand(options) {
     // PRINTED BEFORE THE BROWSER OPENS, not on failure: if the redirect never
     // arrives, the App HAS still been created with no key held, and printing
     // the recovery only then could target a terminal that is already gone.
-    console.log('IF THIS GOES WRONG AFTER YOU CLICK CREATE, read this first:\n' +
-        '  The App will exist and this command will not have its private key. That is\n' +
-        '  recoverable. Either:\n' +
-        '    - delete the App in its settings and re-run this command, or\n' +
-        '    - open the App, scroll to "Private keys", and click "Generate a private key".\n' +
-        '      It downloads a .pem and that is the only chance to save it. This is NOT the\n' +
-        '      "client secret" listed a few sections above: that is for OAuth user flows, is\n' +
-        '      unused by this App, and fails confusingly when used to sign.\n');
+    console.log(recoveryPreamble());
     const state = randomUUID();
     let formDir;
     let callback;
@@ -890,21 +919,15 @@ async function createCommand(options) {
         formDir = await mkdtemp(path.join(tmpdir(), 'canopycms-app-'));
         const formFile = path.join(formDir, `create-${slug}.html`);
         await writeFile(formFile, creationForm(postUrl, manifest), { mode: 0o600, flag: 'wx' });
-        console.log(`Registering "${name}" for ${target.owner}/${target.repo}.\n\n` +
-            'Its permissions, which is the part that matters:\n\n' +
-            `${JSON.stringify(CANOPY_APP_PERMISSIONS, null, 2)}\n\n` +
-            `The key will go to ${describeDestination(destination)} — and if that fails you will\n` +
-            `be asked for somewhere else before it is discarded.\n\n` +
-            '1. Open this file in a browser:\n\n' +
-            `     ${formFile}\n\n` +
-            '   The browser matters, twice over. It must be LOGGED IN TO GITHUB as an owner of\n' +
-            `   ${target.owner}, and it must be running on THIS machine — the redirect comes back to\n` +
-            `   127.0.0.1:${callback.port}, which only a local browser can reach. An embedded or\n` +
-            '   app-internal browser bounces off the GitHub login wall and simply appears to do\n' +
-            '   nothing when you click Create.\n\n' +
-            '   The page posts the manifest to GitHub, which shows you the App pre-filled with\n' +
-            '   exactly those permissions. Review them and click Create.\n\n' +
-            `Waiting for GitHub to redirect back (up to ${CALLBACK_TIMEOUT_MS / 60000} minutes)...`);
+        console.log(registrationMessage({
+            name,
+            owner: target.owner,
+            repo: target.repo,
+            destination: describeDestination(destination),
+            formFile,
+            callbackPort: callback.port,
+            timeoutMinutes: CALLBACK_TIMEOUT_MS / 60000,
+        }));
         let code;
         try {
             code = await callback.code;
@@ -918,7 +941,7 @@ async function createCommand(options) {
                 '  See the recovery note printed above if the App was in fact created.');
             return 1;
         }
-        console.log('  got the manifest code; exchanging it for the App credentials');
+        console.log(`\n${tick('Got the manifest code; exchanging it for the App credentials')}`);
         const created = await convertManifest(code);
         if (!created) {
             console.error('  the exchange failed, so this command never received the private key.\n\n' +
@@ -929,8 +952,8 @@ async function createCommand(options) {
                 '  start over.');
             return 1;
         }
-        console.log(`  created App ${created.slug} (id ${created.id}) — private key captured; sending it to` +
-            ` ${describeDestination(destination)}`);
+        console.log(tick(`Created App ${outColors.bold(created.slug)} (id ${created.id}); private key captured, sending it to` +
+            ` ${describeDestination(destination)}`));
         // THE KEY IS HANDED OFF FIRST, before the install prompt and the readback,
         // because until it returns this process holds the ONLY copy of the key
         // while the install step waits on a human indefinitely and the readback
@@ -939,17 +962,10 @@ async function createCommand(options) {
         if (!stored) {
             // No point installing an App whose key was just discarded. Say what IS
             // still actionable — the App id, the handle for a replacement key.
-            console.error(`\nStopping here: the App exists but its key was not stored, so installing it now\n` +
-                '  would achieve nothing. To recover, open the App and generate a private key from\n' +
-                '  its "Private keys" section, then run `verify`; or delete the App and start again.\n\n' +
-                `  GITHUB_APP_ID=${created.id}\n` +
-                `  App settings: https://github.com/settings/apps/${created.slug}`);
+            console.error(keyNotStoredMessage(target, created));
             return 1;
         }
-        console.log(`\n2. Install it on ${target.owner}/${target.repo}:\n\n` +
-            `     https://github.com/settings/apps/${created.slug}/installations\n\n` +
-            '   That page shows an Install button first — the repository picker only appears after\n' +
-            '   you click it. Choose "Only select repositories" and pick that one repository.\n');
+        console.log(installStepMessage(target, created.slug));
         await pressEnter('   Press Enter once it is installed.');
         // Wrapped so a rejection here cannot change what was already reported about
         // the key: by this point it is stored (or deliberately not), and a
@@ -963,15 +979,7 @@ async function createCommand(options) {
                 '  This says nothing about the App or the key — re-run `canopycms init-github-app verify`.');
             readback = { ok: false, installationId: null };
         }
-        console.log('\nSet these on your deployment:\n\n' +
-            `  GITHUB_APP_ID=${created.id}\n` +
-            `  GITHUB_APP_INSTALLATION_ID=${readback.installationId ?? '<run `verify` to read it>'}\n` +
-            '  GITHUB_APP_PRIVATE_KEY_SECRET_ARN=<wherever you just put the key>\n\n' +
-            '  Both ids are numeric. The App ID is NOT the "Client ID" (`Iv1.…`) shown beside it,\n' +
-            '  and the installation id is NOT the App ID — an App installed twice has one App ID\n' +
-            '  and two installation ids.\n\n' +
-            'Re-check this any time, without creating anything:\n' +
-            `  canopycms init-github-app verify --app-id ${created.id} --key-file <path>`);
+        console.log(deploymentSettingsMessage(created.id, readback.installationId));
         return stored && readback.ok ? 0 : 1;
     }
     finally {

package/dist/cli/init.js

@@ -391,7 +391,7 @@ var init_sanitize_href = __esm({
 
 // dist/config/schemas/url.js
 import { z as z3 } from "zod";
-var uploadTargetUrlSchema, previewPrefixSchema;
+var uploadTargetUrlSchema, previewPrefixSchema, editorUrlSchema;
 var init_url = __esm({
   "dist/config/schemas/url.js"() {
     "use strict";
@@ -402,6 +402,14 @@ var init_url = __esm({
     previewPrefixSchema = z3.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value), {
       message: 'editor.previewPrefix must be an absolute http(s) URL or a site-relative path beginning with a single "/", with no query or fragment'
     });
+    editorUrlSchema = z3.string().trim().refine((value) => {
+      if (!isHttpUrlOrSameOriginPath(value) || !/^https?:\/\//i.test(value))
+        return false;
+      const url = new URL(value);
+      return !url.username && !url.password;
+    }, {
+      message: "editorUrl must be an absolute http(s) URL with no credentials, query or fragment"
+    });
   }
 });
 
@@ -552,6 +560,7 @@ var init_config = __esm({
       contentRoot: contentRootSchema.default("content"),
       sourceRoot: sourceRootSchema.optional(),
       basePath: basePathSchema,
+      editorUrl: editorUrlSchema.optional(),
       unauthenticatedStatus: z5.union([z5.literal(401), z5.literal(419)]).optional(),
       danglingReferences: z5.enum(["error", "warn"]).optional(),
       editor: editorConfigSchema.optional(),
@@ -657,9 +666,13 @@ async function canopyContext(options) {
     "// authenticated request instead of silently falling back to unauthenticated dev auth.",
     "// CLERK_SECRET_KEY is read only where Clerk's backend API is called: the auth-cache",
     "// refresh (the worker in prod, lazily on the dev server in dev).",
+    "// useOrganizationsAsGroups needs Organizations enabled on the Clerk instance and offers",
+    "// every organization in the instance as a group. In an AWS deployment the worker reads",
+    "// the setting from `clerkOrganizationsAsGroups` in the CDK stack, which governs there;",
+    "// keep the two equal.",
     "const authPlugin =",
     "  config.server.mode === 'prod' || process.env.CANOPY_AUTH_MODE === 'clerk'",
-    "    ? createClerkAuthPlugin({ useOrganizationsAsGroups: true })",
+    "    ? createClerkAuthPlugin({ useOrganizationsAsGroups: false })",
     "    : createDevAuthPlugin()"
   ].join("\n") : "const authPlugin = createDevAuthPlugin()";
   return template.replace("{{AUTH_IMPORTS}}", authImports).replace("{{AUTH_PLUGIN_SETUP}}", authPluginSetup).replace("{{CONFIG_IMPORT}}", options.configImport);

package/dist/cli/template-files/cms-stack.ts.template

@@ -172,6 +172,9 @@ export class CmsStack extends Stack {
       ].filter((arn): arn is string => arn !== undefined),
       githubTokenSecretArn: githubToken?.secretArn,
       clerkSecretKeySecretArn: clerkSecretKey.secretArn,
+      // Whether the worker maps Clerk Organizations onto Canopy groups. It needs Organizations
+      // enabled on the Clerk instance; keep it equal to useOrganizationsAsGroups in canopy.ts.
+      clerkOrganizationsAsGroups: false,
       // GitHub App auth, when configured instead of the token above. Undefined
       // unless the adopter set all three; CanopyCmsService refuses a partial
       // set, and refuses an App alongside githubTokenSecretArn.

package/dist/cli/templates.js

@@ -41,9 +41,13 @@ export async function canopyContext(options) {
             '// authenticated request instead of silently falling back to unauthenticated dev auth.',
             "// CLERK_SECRET_KEY is read only where Clerk's backend API is called: the auth-cache",
             '// refresh (the worker in prod, lazily on the dev server in dev).',
+            '// useOrganizationsAsGroups needs Organizations enabled on the Clerk instance and offers',
+            '// every organization in the instance as a group. In an AWS deployment the worker reads',
+            '// the setting from `clerkOrganizationsAsGroups` in the CDK stack, which governs there;',
+            '// keep the two equal.',
             'const authPlugin =',
             "  config.server.mode === 'prod' || process.env.CANOPY_AUTH_MODE === 'clerk'",
-            '    ? createClerkAuthPlugin({ useOrganizationsAsGroups: true })',
+            '    ? createClerkAuthPlugin({ useOrganizationsAsGroups: false })',
             '    : createDevAuthPlugin()',
         ].join('\n')
         : 'const authPlugin = createDevAuthPlugin()';

package/dist/comment-store.d.ts

@@ -60,6 +60,11 @@ export declare class CommentStore {
     constructor(branchRoot: string, options?: {
         settleMs?: number;
     });
+    /**
+     * Every thread, for a summary that must not mistake a failed read for no comments: only a
+     * missing file reads as none, and an unreadable or malformed one throws, unlike load().
+     */
+    listThreadsStrict(): Promise<CommentThread[]>;
     /** Read-only load. */
     load(): Promise<CommentsFile>;
     /**

package/dist/comment-store.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { withLock } from './utils/async-mutex.js';
+import { isNotFoundError } from './utils/error.js';
 import { writeOccJsonFile, withOccRetry, withOccFileLock, OccWriteConflictError, } from './utils/occ-json-write.js';
 /** A concurrent modification that survived every OCC retry. */
 class CommentStoreConflictError extends Error {
@@ -45,6 +46,29 @@ export class CommentStore {
         this.filePath = path.join(path.resolve(branchRoot), '.canopy-meta', 'comments.json');
         this.settleMs = options?.settleMs;
     }
+    /**
+     * Every thread, for a summary that must not mistake a failed read for no comments: only a
+     * missing file reads as none, and an unreadable or malformed one throws, unlike load().
+     */
+    async listThreadsStrict() {
+        let content;
+        try {
+            content = await fs.readFile(this.filePath, 'utf-8');
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                return [];
+            throw err;
+        }
+        const parsed = JSON.parse(content);
+        const threads = typeof parsed === 'object' && parsed !== null
+            ? parsed.threads
+            : undefined;
+        if (typeof threads !== 'object' || threads === null) {
+            throw new Error('comments.json has no threads object');
+        }
+        return Object.values(threads);
+    }
     /** Read-only load. */
     async load() {
         const { data } = await this.loadWithVersion();

package/dist/config/helpers.js

@@ -33,11 +33,9 @@ export function defineCanopyConfig(config) {
         server: validated,
         // Client config helper - extracts safe subset and merges overrides
         client: (clientOverrides) => {
-            const { defaultBaseBranch, defaultActiveBranch, contentRoot, editor, mode, entryLinkUrl, basePath, mdxAllow, } = validated;
+            const { contentRoot, editor, mode, entryLinkUrl, basePath, mdxAllow } = validated;
             // flatSchema is loaded dynamically by the editor via API (from .collection.json files)
             const clientConfig = {
-                defaultBaseBranch,
-                defaultActiveBranch,
                 contentRoot,
                 editor,
                 mode,

package/dist/config/schemas/collection.d.ts

@@ -13,7 +13,7 @@ export declare const entryTypeSchema: z.ZodObject<{
     maxItems: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    format: "mdx" | "md" | "json" | "yaml";
+    format: "md" | "mdx" | "json" | "yaml";
     schema: any[];
     description?: string | undefined;
     default?: boolean | undefined;
@@ -21,7 +21,7 @@ export declare const entryTypeSchema: z.ZodObject<{
     maxItems?: number | undefined;
 }, {
     name: string;
-    format: "mdx" | "md" | "json" | "yaml";
+    format: "md" | "mdx" | "json" | "yaml";
     schema: any[];
     description?: string | undefined;
     default?: boolean | undefined;

package/dist/config/schemas/config.d.ts

@@ -71,6 +71,7 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     contentRoot: z.ZodDefault<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>>>;
     sourceRoot: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     basePath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    editorUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     unauthenticatedStatus: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<401>, z.ZodLiteral<419>]>>;
     danglingReferences: z.ZodOptional<z.ZodEnum<["error", "warn"]>>;
     editor: z.ZodOptional<z.ZodObject<{
@@ -201,6 +202,7 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     deploymentName?: string | undefined;
     sourceRoot?: string | undefined;
     basePath?: string | undefined;
+    editorUrl?: string | undefined;
     unauthenticatedStatus?: 401 | 419 | undefined;
     danglingReferences?: "error" | "warn" | undefined;
     editor?: {
@@ -268,6 +270,7 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     contentRoot?: string | undefined;
     sourceRoot?: string | undefined;
     basePath?: string | undefined;
+    editorUrl?: string | undefined;
     unauthenticatedStatus?: 401 | 419 | undefined;
     danglingReferences?: "error" | "warn" | undefined;
     editor?: {

package/dist/config/schemas/config.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
 import { relativePathSchema } from './collection.js';
 import { mdxAllowlistSchema } from './field.js';
 import { mediaSchema } from './media.js';
-import { previewPrefixSchema } from './url.js';
+import { editorUrlSchema, previewPrefixSchema } from './url.js';
 const defaultBranchAccessSchema = z.enum(['allow', 'deny']).default('deny');
 const defaultPathAccessLevelSchema = z.enum(['allow', 'deny']);
 // Per-level object form: an omitted level stays undefined after parse (no per-field
@@ -123,6 +123,7 @@ export const CanopyConfigSchema = z
     contentRoot: contentRootSchema.default('content'),
     sourceRoot: sourceRootSchema.optional(),
     basePath: basePathSchema,
+    editorUrl: editorUrlSchema.optional(),
     unauthenticatedStatus: z.union([z.literal(401), z.literal(419)]).optional(),
     danglingReferences: z.enum(['error', 'warn']).optional(),
     editor: editorConfigSchema.optional(),

package/dist/config/schemas/url.d.ts

@@ -19,3 +19,9 @@ import { z } from 'zod';
 export declare const uploadTargetUrlSchema: z.ZodEffects<z.ZodString, string, string>;
 /** `editor.previewPrefix`, by `uploadTargetUrlSchema`'s rule: `//host` leaves the scheme open. */
 export declare const previewPrefixSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * `editorUrl`: the absolute http(s) URL of the page that mounts the Editor, by
+ * `uploadTargetUrlSchema`'s rule plus a scheme and no credentials, since it is written into
+ * pull request bodies as a link.
+ */
+export declare const editorUrlSchema: z.ZodEffects<z.ZodString, string, string>;

package/dist/config/schemas/url.js

@@ -30,3 +30,19 @@ export const previewPrefixSchema = z
     .refine((value) => isHttpUrlOrSameOriginPath(value), {
     message: 'editor.previewPrefix must be an absolute http(s) URL or a site-relative path beginning with a single "/", with no query or fragment',
 });
+/**
+ * `editorUrl`: the absolute http(s) URL of the page that mounts the Editor, by
+ * `uploadTargetUrlSchema`'s rule plus a scheme and no credentials, since it is written into
+ * pull request bodies as a link.
+ */
+export const editorUrlSchema = z
+    .string()
+    .trim()
+    .refine((value) => {
+    if (!isHttpUrlOrSameOriginPath(value) || !/^https?:\/\//i.test(value))
+        return false;
+    const url = new URL(value);
+    return !url.username && !url.password;
+}, {
+    message: 'editorUrl must be an absolute http(s) URL with no credentials, query or fragment',
+});

package/dist/config/types.d.ts

@@ -478,6 +478,8 @@ export interface CanopyConfig {
     sourceRoot?: SourceRoot;
     /** Deployment prefix the host app is served under — see {@link CanopyConfigInput.basePath}. */
     basePath?: string;
+    /** The editor page's public URL — see {@link CanopyConfigInput.editorUrl}. */
+    editorUrl?: string;
     /** HTTP status of an unauthenticated API response — see {@link CanopyConfigInput.unauthenticatedStatus}. */
     unauthenticatedStatus?: 401 | 419;
     /** What a production build does on a dangling reference — see {@link CanopyConfigInput.danglingReferences}. */
@@ -554,6 +556,13 @@ export interface CanopyConfigInput {
      * silently filter out every entry (zero static params, a build that goes green with no pages).
      */
     basePath?: string;
+    /**
+     * The absolute URL of the page that mounts the Editor (e.g. `https://cms.example.org/edit`),
+     * for the editor links in pull request bodies. Unset, the URL the editor reports on submit is
+     * used when its host is the one the request was addressed to (`X-Forwarded-Host`, else `Host`);
+     * set this when a proxy in front of the CMS sets neither to the editor's public host.
+     */
+    editorUrl?: string;
     /**
      * HTTP status of an API response to a request with no accepted session. Default 401.
      *
@@ -634,8 +643,10 @@ export type FlatSchemaItem = {
  * Client config - subset safe for browser (DRY - derived from CanopyConfig)
  * Use flatSchema for O(1) cached access to the flattened schema structure.
  * Schema is loaded from .collection.json files on the server and provided as flatSchema.
+ * It names no branch: the config evaluated in the browser lacks the server's environment, so an
+ * editor no `?branch=` or `branchName` pins adopts the branches API's `defaultBranch`.
  */
-export type CanopyClientConfig = Pick<CanopyConfig, 'defaultBaseBranch' | 'defaultActiveBranch' | 'contentRoot' | 'editor' | 'mode' | 'entryLinkUrl' | 'basePath' | 'mdxAllow'> & {
+export type CanopyClientConfig = Pick<CanopyConfig, 'contentRoot' | 'editor' | 'mode' | 'entryLinkUrl' | 'basePath' | 'mdxAllow'> & {
     flatSchema: FlatSchemaItem[];
 };
 export interface ClientOnlyFields {