canopycms 0.0.67-int.90 → 0.0.67

package/dist/cli/project-root.d.ts

@@ -1,16 +1,9 @@
 /**
- * Project root discovery for CLI commands.
- *
- * Commands that operate on an existing CanopyCMS project (sync, worker,
- * generate-ai-content) resolve the project root by walking up from the
- * current directory to the nearest canopycms.config.ts — like git does
- * with .git — so running from a subdirectory works and never scatters
- * state (e.g. .canopy-dev/) into the wrong directory.
+ * Resolves an existing CanopyCMS project's root for sync/worker/generate-ai-content:
+ * walks up from the given directory to the nearest canopycms.config.ts (like git
+ * and .git), so commands work from any subdirectory without scattering state
+ * (e.g. .canopy-dev/) into the wrong place.
  */
 /** Config file that marks the root of a CanopyCMS project. */
 export declare const PROJECT_MARKER = "canopycms.config.ts";
-/**
- * Walk up from startDir to the nearest directory containing canopycms.config.ts.
- * Returns null when no project root is found.
- */
 export declare function findProjectRoot(startDir: string): Promise<string | null>;

package/dist/cli/project-root.js

@@ -1,20 +1,13 @@
 /**
- * Project root discovery for CLI commands.
- *
- * Commands that operate on an existing CanopyCMS project (sync, worker,
- * generate-ai-content) resolve the project root by walking up from the
- * current directory to the nearest canopycms.config.ts — like git does
- * with .git — so running from a subdirectory works and never scatters
- * state (e.g. .canopy-dev/) into the wrong directory.
+ * Resolves an existing CanopyCMS project's root for sync/worker/generate-ai-content:
+ * walks up from the given directory to the nearest canopycms.config.ts (like git
+ * and .git), so commands work from any subdirectory without scattering state
+ * (e.g. .canopy-dev/) into the wrong place.
  */
 import path from 'node:path';
 import { filePathExists } from '../utils/fs.js';
 /** Config file that marks the root of a CanopyCMS project. */
 export const PROJECT_MARKER = 'canopycms.config.ts';
-/**
- * Walk up from startDir to the nearest directory containing canopycms.config.ts.
- * Returns null when no project root is found.
- */
 export async function findProjectRoot(startDir) {
     let dir = path.resolve(startDir);
     for (;;) {

package/dist/cli/prompt.d.ts

@@ -0,0 +1,10 @@
+/** Stdin prompts for the CLI commands; `stdinEnded` says why they share one module. */
+/** Wait for the operator to continue. Returns at once if stdin has ended. */
+export declare function pressEnter(prompt: string): Promise<void>;
+/** Read one line from the operator. `null` when stdin ended instead. */
+export declare function askLine(prompt: string): Promise<string | null>;
+/**
+ * Reset between tests. Not used by the command itself.
+ * @internal Exported for tests.
+ */
+export declare function resetStdinStateForTesting(): void;

package/dist/cli/prompt.js

@@ -0,0 +1,67 @@
+/** Stdin prompts for the CLI commands; `stdinEnded` says why they share one module. */
+import { createInterface } from 'node:readline';
+/**
+ * Whether stdin has already delivered end-of-input to an earlier prompt.
+ * `process.stdin` can only end ONCE, and a `readline` interface created after
+ * it has ended never emits `'line'` or `'close'`, so a per-prompt interface
+ * is a footgun once a command has two prompts — even when the first WAS
+ * answered, since readline flushes a pending partial line as a final `'line'`
+ * event before `'close'`, so "text then EOF" answers normally while the
+ * stream also ends in that same moment. The flag records whether the STREAM
+ * ended, not whether THIS prompt got an answer.
+ * `readableEnded` is checked unconditionally in the `'close'` handler
+ * below, before the `answered` branch: gating it on `!answered` would miss
+ * the case above and leave the next prompt's readline on an already-ended
+ * stream that never emits, so node would exit 0 silently with no cleanup. Our
+ * OWN `rl.close()` also fires `'close'` but leaves `readableEnded` false,
+ * keeping the two cases apart. Every prompt below consults this first; no
+ * other readline interface on `process.stdin` may exist anywhere in the CLI.
+ */
+let stdinEnded = false;
+function readLineOnce(prompt) {
+    if (stdinEnded) {
+        // Already at EOF: answer immediately rather than waiting for input that can
+        // never arrive.
+        console.log(prompt);
+        return Promise.resolve(null);
+    }
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    return new Promise((resolve) => {
+        console.log(prompt);
+        let answered = false;
+        rl.once('line', (line) => {
+            answered = true;
+            rl.close();
+            resolve(line);
+        });
+        rl.once('close', () => {
+            // Checked FIRST and unconditionally (see `stdinEnded` above): `'close'`
+            // fires both for our own `rl.close()` and for the stream actually
+            // ending, and by the time it fires here the input has already finished
+            // emitting `'end'`, so `readableEnded` is reliable to read now.
+            if (process.stdin.readableEnded) {
+                stdinEnded = true;
+            }
+            if (answered)
+                return;
+            stdinEnded = true;
+            resolve(null);
+        });
+    });
+}
+/** Wait for the operator to continue. Returns at once if stdin has ended. */
+export async function pressEnter(prompt) {
+    await readLineOnce(prompt);
+}
+/** Read one line from the operator. `null` when stdin ended instead. */
+export async function askLine(prompt) {
+    const line = await readLineOnce(prompt);
+    return line === null ? null : line.trim();
+}
+/**
+ * Reset between tests. Not used by the command itself.
+ * @internal Exported for tests.
+ */
+export function resetStdinStateForTesting() {
+    stdinEnded = false;
+}

package/dist/cli/sync.d.ts

@@ -21,14 +21,6 @@ export interface SyncOptions {
     /** Skip confirmation prompts (for testing or scripts). */
     force?: boolean;
 }
-/**
- * Sync precondition failure (missing content dir, unknown branch, …).
- * Thrown so the CLI exits non-zero — scripts/CI must not sail past a
- * push that synced nothing.
- */
-export declare class SyncError extends Error {
-    constructor(message: string);
-}
 /**
  * Run the sync command.
  *

package/dist/cli/sync.js

@@ -26,7 +26,7 @@ import { operatingStrategy } from '../operating-mode/index.js';
  * Thrown so the CLI exits non-zero — scripts/CI must not sail past a
  * push that synced nothing.
  */
-export class SyncError extends Error {
+class SyncError extends Error {
     constructor(message) {
         super(message);
         this.name = 'SyncError';
@@ -49,14 +49,13 @@ async function selectBranch(options, branchesDir) {
     let branches = [];
     if (await filePathExists(branchesDir)) {
         const entries = await fs.readdir(branchesDir, { withFileTypes: true });
-        // Dot-prefixed dirs are never branch workspaces (.canopy-meta, and now
+        // Dot-prefixed dirs are never branch workspaces (.canopy-meta, plus
         // .trash-*/.{dirName}.init.lock from the admin branch-health recovery
-        // surface) -- same skip rule as BranchRegistry.scanBranchDirectories.
+        // surface) — same skip rule as BranchRegistry.scanBranchDirectories.
         branches = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name);
     }
     let branchName = options.branch;
     if (!branchName) {
-        // Default to current git branch
         try {
             branchName = await detectCurrentBranch(options.projectDir);
         }
@@ -96,12 +95,11 @@ async function selectBranch(options, branchesDir) {
             await wsGit.init();
             await wsGit.checkoutLocalBranch(branchName);
             await wsGit.raw(['commit', '--allow-empty', '-m', 'init: workspace created by sync']);
-            // Runtime metadata (.canopy-meta/: branch metadata, comments, the
-            // content-index generation marker) must never be staged by sync's
-            // `add -A`. Fully provisioned workspaces get this exclude from
-            // GitManager.initializeWorkspace; this minimal one needs it too. Sync is
-            // dev-mode-only (see branchesDir), so ask the dev strategy for the
-            // pattern rather than hardcoding it.
+            // Runtime metadata (.canopy-meta/: branch metadata, comments, content-index
+            // marker) must never be staged by sync's `add -A`. Fully provisioned workspaces
+            // get this exclude from GitManager.initializeWorkspace; this minimal one needs it
+            // too. Sync is dev-mode-only (see branchesDir), so this asks the dev strategy for
+            // the pattern rather than hardcoding it.
             await ensureGitExcludePattern(branchPath, operatingStrategy('dev').getGitExcludePattern());
             p.log.info(`Created branch workspace: ${branchName}`);
         }
@@ -133,7 +131,6 @@ async function syncPush(options) {
     const branchPath = path.join(branchesDir, branchName);
     assertWithinDir(branchPath, branchesDir, '--branch');
     const wsGit = simpleGit({ baseDir: branchPath });
-    // Check workspace health
     const status = await wsGit.status();
     if (status.conflicted.length > 0) {
         p.log.error('Branch workspace has unresolved merge conflicts.');
@@ -152,7 +149,6 @@ async function syncPush(options) {
         }
         return { fileCount: 0 };
     }
-    // Warn about uncommitted workspace changes (editor saves)
     if (status.files.length > 0 && !options.force) {
         p.log.warn(`Branch workspace has ${status.files.length} uncommitted change(s) that will be committed to history then overwritten:`);
         for (const file of status.files.slice(0, 10)) {
@@ -264,7 +260,6 @@ async function syncPull(options) {
             return { fileCount: 0 };
         }
     }
-    // Replace the working-tree content with the branch workspace content.
     // Uses backup-rename pattern: if interrupted, at least one copy always exists.
     const tmpDestDir = `${destContentDir}.sync-tmp-${Date.now()}`;
     try {
@@ -276,7 +271,6 @@ async function syncPull(options) {
         await fs.rm(tmpDestDir, { recursive: true, force: true }).catch(() => { });
         throw err;
     }
-    // Show what changed using git status (re-check after copy)
     const postStatus = await sourceGit.status();
     const contentChanges = postStatus.files.filter((f) => f.path.startsWith(contentRoot + '/') || f.path === contentRoot);
     if (contentChanges.length === 0) {
@@ -318,7 +312,6 @@ async function syncBoth(options) {
     const branchPath = path.join(branchesDir, branchName);
     assertWithinDir(branchPath, branchesDir, '--branch');
     const wsGit = simpleGit({ baseDir: branchPath });
-    // Check workspace health
     const status = await wsGit.status();
     if (status.conflicted.length > 0) {
         p.log.error('Branch workspace has unresolved merge conflicts.');
@@ -329,8 +322,6 @@ async function syncBoth(options) {
             });
             if (!p.isCancel(shouldAbort) && shouldAbort) {
                 await wsGit.merge(['--abort']);
-                // The abort rewrote the clone's working tree — tell ContentStore ID
-                // indexes (the dev server is a separate process; on-disk marker).
                 await invalidateBranchContentCaches(branchPath);
                 p.log.success('Merge aborted. Workspace restored to pre-merge state.');
             }
@@ -343,7 +334,6 @@ async function syncBoth(options) {
         await wsGit.commit('sync: save editor state before merge');
         p.log.info('Committed editor changes before merge');
     }
-    // Determine merge base
     let baseRef;
     try {
         await wsGit.raw(['rev-parse', SYNC_BASE_TAG]);
@@ -353,17 +343,14 @@ async function syncBoth(options) {
         // First time: no tag exists. Use current HEAD as base.
         baseRef = 'HEAD';
     }
-    // Remember the current branch to switch back after merge
     const currentBranch = (await wsGit.revparse(['--abbrev-ref', 'HEAD'])).trim();
     // Everything from here mutates the branch clone's working tree (temp-branch
     // checkout, content replace, merge) — whatever the outcome, mark ContentStore
     // ID indexes stale in the finally below. The dev server is a separate
     // process, reached via the on-disk generation marker.
     try {
-        // Create temp branch from the merge base
         const incomingBranch = `sync-incoming-${Date.now()}`;
         await wsGit.raw(['checkout', '-b', incomingBranch, baseRef]);
-        // Replace content on temp branch with working-tree content
         const wsContentDir = path.join(branchPath, contentRoot);
         assertWithinDir(wsContentDir, branchPath, '--content-root');
         const tmpDir = `${wsContentDir}.sync-tmp-${Date.now()}`;
@@ -380,7 +367,6 @@ async function syncBoth(options) {
         }
         await wsGit.add('-A');
         const incomingStatus = await wsGit.status();
-        // No working-tree changes — skip merge, just pull editor changes
         if (incomingStatus.files.length === 0) {
             await wsGit.checkout(currentBranch);
             await wsGit.raw(['branch', '-D', incomingBranch]);
@@ -389,14 +375,12 @@ async function syncBoth(options) {
             return { pushed: 0, pulled: pullResult.fileCount };
         }
         await wsGit.commit('sync: incoming working-tree changes');
-        // Switch back to workspace branch and merge
         await wsGit.checkout(currentBranch);
         p.log.step('Merging working-tree changes with editor changes...');
         try {
             await wsGit.merge([incomingBranch, '--no-edit']);
         }
         catch (mergeError) {
-            // Check if it's a merge conflict
             let mergeStatus;
             try {
                 mergeStatus = await wsGit.status();
@@ -418,7 +402,6 @@ async function syncBoth(options) {
                 await wsGit.raw(['branch', '-D', incomingBranch]).catch(() => { });
                 return { pushed: 0, pulled: 0 };
             }
-            // Not a conflict — clean up and re-throw original error
             await wsGit.raw(['branch', '-D', incomingBranch]).catch(() => { });
             throw mergeError;
         }
@@ -426,7 +409,6 @@ async function syncBoth(options) {
         await wsGit.raw(['branch', '-D', incomingBranch]);
         await wsGit.tag(['-f', SYNC_BASE_TAG]);
         p.log.success('Merged working-tree changes with editor changes');
-        // Pull merged result back to working tree
         const pullResult = await syncPull({ ...options, branch: branchName, force: true });
         return { pushed: incomingStatus.files.length, pulled: pullResult.fileCount };
     }
@@ -453,8 +435,6 @@ async function syncAbort(options) {
         return;
     }
     await wsGit.merge(['--abort']);
-    // The abort rewrote the clone's working tree — tell ContentStore ID indexes
-    // (the dev server is a separate process; on-disk marker).
     await invalidateBranchContentCaches(branchPath);
     p.log.success(`Merge aborted in branch workspace "${branchName}". Workspace restored to pre-merge state.`);
 }

package/dist/cli/template-files/middleware.ts.template

@@ -1,18 +1,26 @@
 import { NextResponse } from 'next/server'
 
-// Protect CMS routes from unauthenticated access.
+// Optional edge protection for /edit and /api/canopycms. This passthrough adds none, and the CMS
+// needs none in any auth mode: the API authenticates every request itself, and the editor shows
+// the auth provider's sign-in screen to signed-out users. It is the same file for every auth mode,
+// so changing CANOPY_AUTH_MODE needs nothing here.
 //
-// For dev auth mode, no middleware protection is needed — this file is a passthrough.
-// If you don't need auth protection, you can delete this file entirely.
-//
-// For Clerk auth, replace this file's contents with:
+// With Clerk you can instead turn signed-out requests away at the edge, before they reach the
+// app. On a deployed CMS Lambda that costs two things:
+//   - CLERK_SECRET_KEY on the Lambda. clerkMiddleware throws on every request it matches unless
+//     it can resolve a secret key (jwtKey doesn't count), which breaks the public-keys-only
+//     Lambda that the Security Model in docs/deploying-to-aws.md describes.
+//   - One image per Clerk instance. It reads the publishable key inlined at image build
+//     (NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY), not the one your ClerkProvider receives, unless you
+//     pass it an options callback that reads both keys at run time.
+// To adopt it anyway, replace this file's contents with:
 //
 //   import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
 //
 //   const isProtectedRoute = createRouteMatcher(['/edit(.*)', '/api/canopycms(.*)'])
 //
-//   // jwtKey avoids a JWKS fetch to api.clerk.com on cold verification --
-//   // the prod CMS Lambda has no internet.
+//   // jwtKey avoids a JWKS fetch to api.clerk.com on cold verification -- the prod CMS Lambda
+//   // has no internet, and the CLERK_JWT_KEY env var alone is never read.
 //   export default clerkMiddleware(
 //     async (auth, req) => {
 //       if (isProtectedRoute(req)) {
@@ -25,30 +33,8 @@ import { NextResponse } from 'next/server'
 //   export const config = {
 //     matcher: ['/edit(.*)', '/api/canopycms(.*)'],
 //   }
-//
-// IMPORTANT: unlike canopy.ts and the edit page, this file does NOT read
-// CANOPY_AUTH_MODE at runtime -- it is frozen at `init` time. If you switch
-// from dev to Clerk auth (or flip CANOPY_AUTH_MODE=clerk), choose what this
-// file becomes. The Clerk middleware above turns signed-out requests away
-// before they reach the app, but needs CLERK_SECRET_KEY wherever it runs.
-// Deleting the file relies on the Clerk auth plugin alone, which rejects
-// unauthenticated API calls on its own (the core also fails closed in prod
-// mode), and keeps the secret off a deployed CMS Lambda -- see "One image for
-// every Clerk tier" in docs/deploying-to-aws.md. Keeping this passthrough with
-// Clerk behaves like deleting it; the warning below is there so that it's a
-// choice rather than an oversight.
-
-let warnedAuthModeMismatch = false
 
 export default function middleware() {
-  if (process.env.CANOPY_AUTH_MODE === 'clerk' && !warnedAuthModeMismatch) {
-    warnedAuthModeMismatch = true
-    console.warn(
-      '[canopycms] CANOPY_AUTH_MODE=clerk is set, but middleware.ts is still the dev ' +
-        'passthrough generated for dev auth. Replace it with the Clerk middleware (see the ' +
-        'comment above), or delete it to rely on the Clerk auth plugin alone.',
-    )
-  }
   return NextResponse.next()
 }
 

package/dist/cli/templates.d.ts

@@ -22,21 +22,11 @@ export declare function aiConfig(): Promise<string>;
 export declare function aiRoute(options: {
     configImport: string;
 }): Promise<string>;
-export declare function middleware(options: {
-    authProvider: 'clerk' | 'dev';
-}): Promise<string>;
+/** One passthrough for every auth mode; it carries the opt-in `clerkMiddleware` as a comment. */
+export declare function middleware(): Promise<string>;
 export declare function nextConfig(options: {
     staticBuild: boolean;
 }): Promise<string>;
-/**
- * CloudFormation stack id used by the scaffolded CDK app.
- *
- * Shared rather than written twice: `infrastructure/bin/app.ts` names the
- * stack, and the deploy workflow deploys it BY NAME (not `--all`, which would
- * also deploy any unrelated stacks an adopter keeps in the same repo). Those
- * two must agree, so they read the same constant.
- */
-export declare const SCAFFOLD_STACK_NAME = "CanopyCms";
 export declare function dockerfileCms(options: {
     copy: string;
     install: string;

package/dist/cli/templates.js

@@ -71,9 +71,9 @@ export async function aiRoute(options) {
     const template = await readTemplate('ai-route.ts.template');
     return template.replace('{{CONFIG_IMPORT}}', options.configImport);
 }
-export async function middleware(options) {
-    const templateName = options.authProvider === 'clerk' ? 'middleware-clerk.ts.template' : 'middleware.ts.template';
-    return readTemplate(templateName);
+/** One passthrough for every auth mode; it carries the opt-in `clerkMiddleware` as a comment. */
+export async function middleware() {
+    return readTemplate('middleware.ts.template');
 }
 export async function nextConfig(options) {
     const templateName = options.staticBuild
@@ -89,7 +89,7 @@ export async function nextConfig(options) {
  * also deploy any unrelated stacks an adopter keeps in the same repo). Those
  * two must agree, so they read the same constant.
  */
-export const SCAFFOLD_STACK_NAME = 'CanopyCms';
+const SCAFFOLD_STACK_NAME = 'CanopyCms';
 export async function dockerfileCms(options) {
     const template = await readTemplate('Dockerfile.cms.template');
     return template

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-export type { CanopyClientConfig } from './config/index.js';
+export type { CanopyClientConfig, EditorSignInProps } from './config/index.js';
 export type { CustomFieldRenderers, CustomFieldRenderProps } from './editor/FormRenderer.js';
 export * from './editor/EditorPanes.js';
 export * from './editor/EntryNavigator.js';

package/dist/comment-store.d.ts

@@ -1,12 +1,5 @@
-/**
- * Error thrown when a concurrent modification is detected.
- * Operations that encounter this error will automatically retry.
- */
-export declare class CommentStoreConflictError extends Error {
-    constructor();
-}
 export type CommentType = 'field' | 'entry' | 'branch';
-export interface Comment {
+interface Comment {
     id: string;
     threadId: string;
     userId: string;
@@ -32,28 +25,23 @@ export interface CommentsFile {
     threads: Record<string, CommentThread>;
 }
 /**
- * Manages comment storage for a branch workspace.
- * Comments are stored in .canopy-meta/comments.json and are NOT committed to git.
+ * Comment storage for a branch workspace, in .canopy-meta/comments.json and
+ * never committed to git.
  *
- * Mutators are protected by three layers, outermost to innermost:
+ * Mutators run under three layers, outermost to innermost:
  *
- * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
- *    path. Serializes concurrent mutators on the SAME process/host
- *    deterministically, so racing `resolveThread`/`deleteThread`/`addComment`
- *    calls against the same store (or two store instances pointed at the
- *    same branch) never race each other's load-modify-write cycle.
- * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
- *    lock (proper-lockfile, mkdir-based). This is the actual fix for lost
- *    comments across two warm Lambda containers on EFS, where rename-based
- *    OCC verification alone is unreliable (see guarantee doc on
- *    `utils/occ-json-write.ts`).
- * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
- *    based optimistic concurrency control. With layers 1-2 in place this is
- *    now a defense-in-depth backstop only (e.g. a stale process from a
- *    rolling deploy writing without the lock), not the primary safety
- *    mechanism.
+ * 1. {@link withLock} — an in-process FIFO mutex keyed by the resolved file
+ *    path, so mutators racing on one host cannot interleave their
+ *    load-modify-write cycles, whether they share a store instance or not.
+ * 2. {@link withOccFileLock} — a server-enforced, cross-process/cross-host lock
+ *    (proper-lockfile, mkdir-based). This is what actually prevents lost
+ *    comments across two warm Lambda containers on EFS, where rename-based OCC
+ *    verification alone is unreliable.
+ * 3. {@link withOccRetry} around {@link writeOccJsonFile} — version/writeId
+ *    optimistic concurrency. With layers 1-2 in place it is defense in depth
+ *    only, for a writer that skips the lock (a stale process mid-deploy).
  *
- * See `utils/occ-json-write.ts` for full guarantee documentation of layers 2-3.
+ * Guarantees for layers 2-3: `utils/occ-json-write.ts`.
  */
 export declare class CommentStore {
     private readonly filePath;
@@ -61,34 +49,30 @@ export declare class CommentStore {
     constructor(branchRoot: string, options?: {
         settleMs?: number;
     });
-    /**
-     * Load comments file for read-only access.
-     */
+    /** Read-only load. */
     load(): Promise<CommentsFile>;
     /**
-     * Load comments file along with the version observed at load time. Used by
-     * mutators, which need the version as a LOCAL value threaded through their
-     * load-modify-write cycle rather than shared mutable instance state (so
-     * concurrent mutate cycles on the same instance never clobber each other's
-     * expected version).
+     * Load, with the version observed at load time. Mutators thread that version
+     * through their load-modify-write cycle as a LOCAL value, never as instance
+     * state, so concurrent cycles cannot clobber each other's expected version.
      */
     private loadWithVersion;
     /**
-     * Write comments file via the shared OCC helper.
+     * Write comments.json via the shared OCC helper.
      *
-     * Throws the helper's raw {@link OccWriteConflictError} so the surrounding
-     * {@link withOccRetry} in withMutation() recognizes and retries it;
-     * translation to the public `CommentStoreConflictError` contract happens at
-     * the withMutation() boundary, after retries are exhausted.
+     * Throws the helper's raw {@link OccWriteConflictError}, which is what the
+     * surrounding {@link withOccRetry} in withMutation() recognizes and retries;
+     * translation to the public `CommentStoreConflictError` happens at the
+     * withMutation() boundary, once retries are exhausted.
      *
-     * Note: comment-store historically wrote without a trailing newline;
-     * `writeOccJsonFile`'s default (`trailingNewline: false`) preserves that.
+     * comments.json is written without a trailing newline (`writeOccJsonFile`'s
+     * default), unlike branch.json.
      */
     private writeData;
     /**
      * Run a mutate cycle (load -> modify -> write) under the full lock +
-     * OCC-retry stack described in the class doc comment. A conflict that
-     * survives every retry surfaces as the public `CommentStoreConflictError`.
+     * OCC-retry stack (class doc). A conflict surviving every retry surfaces as
+     * `CommentStoreConflictError`.
      */
     private withMutation;
     addComment(options: {
@@ -108,16 +92,11 @@ export declare class CommentStore {
     }): Promise<CommentThread[]>;
     getThread(threadId: string): Promise<CommentThread | null>;
     deleteThread(threadId: string): Promise<boolean>;
-    /**
-     * Get all threads for a specific field
-     */
+    /** Threads on one field. */
     getThreadsForField(entryPath: string, canopyPath: string): Promise<CommentThread[]>;
-    /**
-     * Get all threads for a specific entry (not field-specific)
-     */
+    /** Threads on one entry, excluding its field threads. */
     getThreadsForEntry(entryPath: string): Promise<CommentThread[]>;
-    /**
-     * Get all branch-level threads
-     */
+    /** Branch-level threads. */
     getBranchThreads(): Promise<CommentThread[]>;
 }
+export {};