canopycms 0.0.65 → 0.0.66-int.82

package/dist/paths/branch-name.js

@@ -27,7 +27,7 @@ export function sanitizeBranchName(branchName) {
  * operating-mode/deployment-name.ts's `resolveDeploymentName`). Exported from
  * this dependency-free module -- not constructed ad hoc at each call site --
  * so every consumer that needs to recognize the settings-branch namespace
- * agrees on the exact string: worker/cms-worker.ts's `pushSettingsBranches`
+ * agrees on the exact string: worker/git-sync.ts's `pushSettingsBranches`
  * (never push a `canopycms-settings-*` branch this deployment doesn't own),
  * and api/branch.ts's `createBranchHandler` (reject a user-requested branch
  * whose SANITIZED name falls in this namespace).

package/dist/schema/index.d.ts

@@ -7,7 +7,7 @@
  *
  * @example
  * ```ts
- * import { resolveSchema } from 'canopycms/schema'
+ * import { resolveSchema } from 'canopycms/server'
  *
  * const { schema, sources } = await resolveSchema(contentRoot, entrySchemaRegistry)
  * ```

package/dist/schema/index.js

@@ -7,7 +7,7 @@
  *
  * @example
  * ```ts
- * import { resolveSchema } from 'canopycms/schema'
+ * import { resolveSchema } from 'canopycms/server'
  *
  * const { schema, sources } = await resolveSchema(contentRoot, entrySchemaRegistry)
  * ```

package/dist/schema/meta-loader.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import chokidar from 'chokidar';
 import { getErrorMessage } from '../utils/error.js';
 // canopyLogError/canopyLogWarn, not console.*: this module sits in the
-// worker's runtime import closure (worker/cms-worker.ts ->
+// worker's runtime import closure (worker/git-sync.ts and worker/rebase.ts ->
 // content-index-generation.ts -> branch-schema-cache.ts -> schema/resolver.ts
 // -> here), so a bare console line would land in worker.log without the
 // ISO-8601 prefix the CloudWatch agent's multi_line_start_pattern needs (see

package/dist/services.d.ts

@@ -1,3 +1,25 @@
+/**
+ * `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 (`commitFiles`, `submitBranch`,
+ * `commitToSettingsBranch`, `getSettingsBranchRoot`).
+ *
+ * SCOPE WARNING: this is a service locator with 15 members, reached by every one of
+ * the 26 api modules, so adding a field is free and therefore constant — and no handler's
+ * signature reveals what it actually touches. Prefer giving a new capability its
+ * own narrow interface over a 23rd field here.
+ *
+ * Not to be confused with `context.ts`, which is the per-REQUEST facade built on
+ * top of this.
+ *
+ * `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 } from './types.js';

package/dist/types.d.ts

@@ -140,7 +140,7 @@ export interface WorkerStatusReport {
         }[];
         /**
          * Outcome of reconciling remote.git's `refs/heads/*` against GitHub's
-         * fetched tips (worker/cms-worker.ts's `reconcileTrackedBranches`) --
+         * fetched tips (worker/git-sync.ts's `reconcileTrackedBranches`) --
          * the non-destructive replacement for the old fetch refspec that used
          * to write GitHub's refs directly into `refs/heads/*`.
          */

package/dist/url-exclusivity-fixtures.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The one-URL-per-entry invariant, as a reusable probe + report.
+ *
+ * `listEntries` assigns every entry exactly one `urlPath` and documents the round trip through
+ * `readByUrlPath` as safe. The reverse direction has repeatedly been the looser of the two: it
+ * has answered at URLs no forward surface emits, and those extra URLs were found one at a time,
+ * a release apart, by adopters (see
+ * `.claude/future-tasks/resolved/url-resolver-index-entry-extra-url.md`, then
+ * `resolved/readbyurlpath-entry-type-candidate-phantom-url.md`). This module exists so the whole
+ * invariant is asserted at once instead: enumerate, then probe every ADJACENT URL the resolver
+ * would try and require it to be a miss.
+ *
+ * Deliberately free of `vitest` -- this is a plain `src` module in the shape of
+ * `operating-mode/deployment-name-fixtures.ts`, so more than one test file can import it without
+ * dragging that file's `vi.mock` calls and `describe` blocks along. It therefore ASSERTS NOTHING:
+ * it returns a report and the caller does the expecting, which also puts the offending URLs in
+ * the assertion message rather than behind a boolean.
+ *
+ * Scope of the invariant it checks: entries written in the `{type}.{slug}.{id}.{ext}` grammar
+ * with a type their collection declares -- i.e. exactly the set `listEntries` can see. A legacy
+ * untyped file (`overview.json`) is invisible to enumeration and is deliberately NOT probed here;
+ * see `.claude/future-tasks/legacy-untyped-files-url-addressable.md`.
+ */
+import { type RootCollectionConfig } from './config/index.js';
+import type { ListEntriesItem } from './content-listing.js';
+import type { CanopyContext } from './context.js';
+import { type DuplicateUrlPath } from './static/index.js';
+/**
+ * Every URL adjacent to the published set that the resolver would actually attempt.
+ *
+ * Three families, each one a shape that HAS resolved at some point in this package's history:
+ *
+ * 1. `/<collection>/<entryTypeName>` -- `resolveUrlPathCandidates`' index-fallback candidate lands
+ *    on a registered entry-TYPE schema item, which `ContentStore.buildPaths` delegates to the
+ *    parent collection with slug `index`, resolving that collection's index entry.
+ * 2. `/<collection>/<entryTypeName>/<slug>` -- the same delegation reached through the
+ *    DIRECT-entry candidate instead, resolving the collection's entry `<slug>`. Wider than family
+ *    1: it needs no index entry at all, so it applies to every listed entry.
+ * 3. `/<publishedUrl>/index`, and its case variants -- an index entry answering at the literal
+ *    spelling its collapsed URL replaced.
+ *
+ * Entry-type names are appended VERBATIM, after `computeEntryUrl` has lowercased the collection
+ * part. That asymmetry is real, not sloppiness: `flattenSchema` puts `entryType.name` into the
+ * logical path unchanged and `normalizeFilesystemPath` does not lowercase, so only the declared
+ * spelling can reach the entry-type schema item at all. A lowercased probe would miss the schema
+ * item, return null for the wrong reason, and pass vacuously.
+ */
+export declare const buildProbeUrls: (schema: RootCollectionConfig, items: readonly ListEntriesItem[], contentRoot?: string) => string[];
+export interface UrlExclusivityReport {
+    /** Every `urlPath` the listing published, sorted. */
+    published: string[];
+    /** URLs claimed by more than one entry. A precondition failure, not a resolver finding. */
+    duplicates: DuplicateUrlPath[];
+    /** Published URLs `readByUrlPath` did NOT resolve -- the round trip broken going forward. */
+    unresolved: string[];
+    /** Published URLs that resolved to some OTHER entry than the one that published them. */
+    mismatched: Array<{
+        urlPath: string;
+        expectedEntryId?: string;
+        actualEntryId?: string;
+    }>;
+    /** Every adjacent URL probed, sorted. */
+    probes: string[];
+    /** Probes that resolved despite not being published -- the phantom URLs. Must be empty. */
+    phantoms: string[];
+}
+/**
+ * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for what each field means and
+ * `buildProbeUrls` for which URLs are probed.
+ *
+ * A probe whose LOWERCASED form is published is skipped rather than asserted on: a collection
+ * literally named `index` publishes `/docs/index`, which family 3 also generates, and whether
+ * `/docs/Index` should resolve is a separate, pre-existing question about collection-path case
+ * sensitivity that this invariant does not speak to.
+ */
+export declare const collectUrlExclusivityReport: (ctx: Pick<CanopyContext, "listEntries" | "readByUrlPath">, schema: RootCollectionConfig, contentRoot?: string) => Promise<UrlExclusivityReport>;

package/dist/url-exclusivity-fixtures.js

@@ -0,0 +1,119 @@
+/**
+ * The one-URL-per-entry invariant, as a reusable probe + report.
+ *
+ * `listEntries` assigns every entry exactly one `urlPath` and documents the round trip through
+ * `readByUrlPath` as safe. The reverse direction has repeatedly been the looser of the two: it
+ * has answered at URLs no forward surface emits, and those extra URLs were found one at a time,
+ * a release apart, by adopters (see
+ * `.claude/future-tasks/resolved/url-resolver-index-entry-extra-url.md`, then
+ * `resolved/readbyurlpath-entry-type-candidate-phantom-url.md`). This module exists so the whole
+ * invariant is asserted at once instead: enumerate, then probe every ADJACENT URL the resolver
+ * would try and require it to be a miss.
+ *
+ * Deliberately free of `vitest` -- this is a plain `src` module in the shape of
+ * `operating-mode/deployment-name-fixtures.ts`, so more than one test file can import it without
+ * dragging that file's `vi.mock` calls and `describe` blocks along. It therefore ASSERTS NOTHING:
+ * it returns a report and the caller does the expecting, which also puts the offending URLs in
+ * the assertion message rather than behind a boolean.
+ *
+ * Scope of the invariant it checks: entries written in the `{type}.{slug}.{id}.{ext}` grammar
+ * with a type their collection declares -- i.e. exactly the set `listEntries` can see. A legacy
+ * untyped file (`overview.json`) is invisible to enumeration and is deliberately NOT probed here;
+ * see `.claude/future-tasks/legacy-untyped-files-url-addressable.md`.
+ */
+import { flattenSchema } from './config/index.js';
+import { findDuplicateUrlPaths } from './static/index.js';
+import { computeEntryUrl } from './utils/entry-url.js';
+/** Append raw segments to a URL base, without normalizing their case (see buildProbeUrls). */
+const joinUrl = (base, ...segments) => (base === '/' ? '' : base) + segments.map((s) => `/${s}`).join('');
+/**
+ * Every URL adjacent to the published set that the resolver would actually attempt.
+ *
+ * Three families, each one a shape that HAS resolved at some point in this package's history:
+ *
+ * 1. `/<collection>/<entryTypeName>` -- `resolveUrlPathCandidates`' index-fallback candidate lands
+ *    on a registered entry-TYPE schema item, which `ContentStore.buildPaths` delegates to the
+ *    parent collection with slug `index`, resolving that collection's index entry.
+ * 2. `/<collection>/<entryTypeName>/<slug>` -- the same delegation reached through the
+ *    DIRECT-entry candidate instead, resolving the collection's entry `<slug>`. Wider than family
+ *    1: it needs no index entry at all, so it applies to every listed entry.
+ * 3. `/<publishedUrl>/index`, and its case variants -- an index entry answering at the literal
+ *    spelling its collapsed URL replaced.
+ *
+ * Entry-type names are appended VERBATIM, after `computeEntryUrl` has lowercased the collection
+ * part. That asymmetry is real, not sloppiness: `flattenSchema` puts `entryType.name` into the
+ * logical path unchanged and `normalizeFilesystemPath` does not lowercase, so only the declared
+ * spelling can reach the entry-type schema item at all. A lowercased probe would miss the schema
+ * item, return null for the wrong reason, and pass vacuously.
+ */
+export const buildProbeUrls = (schema, items, contentRoot = 'content') => {
+    const collections = flattenSchema(schema, contentRoot).filter((i) => i.type === 'collection');
+    const probes = new Set();
+    for (const collection of collections) {
+        const base = computeEntryUrl(collection.logicalPath, '', contentRoot);
+        for (const entryType of collection.entries ?? []) {
+            // Family 1.
+            probes.add(joinUrl(base, entryType.name));
+            // Family 2 -- every listed entry of this collection, under every type name the collection
+            // declares (not just the entry's OWN type: the directory scan `buildPaths` runs matches on
+            // slug alone, so any declared name reaches any entry).
+            for (const item of items) {
+                if (String(item.collectionPath) !== String(collection.logicalPath))
+                    continue;
+                probes.add(joinUrl(base, entryType.name, item.slug));
+            }
+        }
+    }
+    // Family 3.
+    for (const item of items) {
+        for (const spelling of ['index', 'Index', 'INDEX']) {
+            probes.add(joinUrl(item.urlPath, spelling));
+        }
+    }
+    return [...probes];
+};
+/**
+ * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for what each field means and
+ * `buildProbeUrls` for which URLs are probed.
+ *
+ * A probe whose LOWERCASED form is published is skipped rather than asserted on: a collection
+ * literally named `index` publishes `/docs/index`, which family 3 also generates, and whether
+ * `/docs/Index` should resolve is a separate, pre-existing question about collection-path case
+ * sensitivity that this invariant does not speak to.
+ */
+export const collectUrlExclusivityReport = async (ctx, schema, contentRoot = 'content') => {
+    const items = await ctx.listEntries();
+    const unresolved = [];
+    const mismatched = [];
+    for (const item of items) {
+        const result = await ctx.readByUrlPath(item.urlPath);
+        if (!result) {
+            unresolved.push(item.urlPath);
+            continue;
+        }
+        if (result.meta.entryId !== item.entryId) {
+            mismatched.push({
+                urlPath: item.urlPath,
+                expectedEntryId: item.entryId,
+                actualEntryId: result.meta.entryId,
+            });
+        }
+    }
+    const publishedLower = new Set(items.map((i) => i.urlPath.toLowerCase()));
+    const probes = buildProbeUrls(schema, items, contentRoot);
+    const phantoms = [];
+    for (const probe of probes) {
+        if (publishedLower.has(probe.toLowerCase()))
+            continue;
+        if (await ctx.readByUrlPath(probe))
+            phantoms.push(probe);
+    }
+    return {
+        published: items.map((i) => i.urlPath).sort(),
+        duplicates: findDuplicateUrlPaths(items),
+        unresolved: unresolved.sort(),
+        mismatched,
+        probes: [...probes].sort(),
+        phantoms: phantoms.sort(),
+    };
+};

package/dist/url-path-resolver.js

@@ -34,10 +34,14 @@ export function resolveUrlPathCandidates(urlPath, contentRoot) {
     // `index` is not a contrived segment either — it is the slug the index convention requires on
     // disk, so the collision was structural rather than accidental.
     //
-    // This closes the `.../index` spelling, NOT every extra URL: candidate 2 below still resolves an
-    // index entry at `/<collection>/<entryTypeName>`, because that path is a registered entry-TYPE
-    // schema item which `buildPaths` delegates to the parent collection. Open, and tracked in
-    // .claude/future-tasks/readbyurlpath-entry-type-candidate-phantom-url.md.
+    // This closes the `.../index` spelling only. The other extra URLs an entry answered at —
+    // `/<collection>/<entryTypeName>` via candidate 2, and `/<collection>/<entryTypeName>/<slug>`
+    // via candidate 1 — are closed DOWNSTREAM instead, by `readByUrlPath` requiring every
+    // candidate's `entryPath` to be a collection (`ReadContentInput.urlAddressableOnly`). They have
+    // to be: telling those apart needs the branch's schema, and this module is deliberately pure
+    // and schema-free so that the candidate shapes stay a fact about URLs rather than about
+    // content. The consequence to keep in mind when reading this file: the candidates below are
+    // what is ATTEMPTED, not what can resolve.
     //
     // Compared case-INSENSITIVELY, through the shared `isIndexSlug`. This function is the one
     // consumer that sees a raw, un-normalized URL segment — everything downstream lowercases

package/dist/utils/content-write-lock.d.ts

@@ -5,7 +5,8 @@
  * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
  * `ContentStore`'s write/delete/rename critical sections were guarded only by
  * the in-process mutex (`utils/async-mutex`), which does not cross that
- * boundary, while `CmsWorker.rebaseActiveBranches()` rewrites the very same
+ * boundary, while the worker's rebase loop (`rebaseOneBranch` in
+ * worker/rebase.ts) rewrites the very same
  * working tree. A write landing after `git rebase` started is destroyed two
  * ways -- `git checkout --theirs <file>` overwrites it with the branch's
  * committed version (and the rebase then SUCCEEDS, logging nothing), and

package/dist/utils/content-write-lock.js

@@ -5,7 +5,8 @@
  * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
  * `ContentStore`'s write/delete/rename critical sections were guarded only by
  * the in-process mutex (`utils/async-mutex`), which does not cross that
- * boundary, while `CmsWorker.rebaseActiveBranches()` rewrites the very same
+ * boundary, while the worker's rebase loop (`rebaseOneBranch` in
+ * worker/rebase.ts) rewrites the very same
  * working tree. A write landing after `git rebase` started is destroyed two
  * ways -- `git checkout --theirs <file>` overwrites it with the branch's
  * committed version (and the rebase then SUCCEEDS, logging nothing), and

package/dist/utils/error.d.ts

@@ -35,6 +35,23 @@ export declare function getErrorMessage(err: unknown): string;
  * (CMS-internal layout like `.canopy-dev/remote.git` is useful for debugging
  * and not sensitive); absolute paths outside it are replaced with `<path>`.
  */
+/**
+ * TAG: `[REDACT]`
+ *
+ * Grep `[REDACT]` to find every site that persists or surfaces raw error text on
+ * a path that reaches a browser — worker task errors folded into
+ * `worker-status.json`, `branch.json` parse failures served by the admin
+ * branch-health endpoint, rebase-failure messages, and their tests.
+ *
+ * Those sites carried the tag `[HIGH-1]`/`[MEDIUM-2]` until 2026-08-23, IDs from
+ * a review pass whose findings list was never committed — 13 occurrences across
+ * 6 files resolving to nothing. Renamed rather than deleted because the
+ * underlying rule is real and genuinely cross-file: a Node error embeds absolute
+ * paths, and a git remote URL can embed a token, so anything on that path is
+ * redacted through the function below.
+ *
+ * The tag is a grep aid, not the rule. The rule is stated at each site.
+ */
 export declare function sanitizeErrorMessage(message: string): string;
 /**
  * Redact only credential material from a message, leaving filesystem paths

package/dist/utils/error.js

@@ -43,6 +43,23 @@ export function getErrorMessage(err) {
  * (CMS-internal layout like `.canopy-dev/remote.git` is useful for debugging
  * and not sensitive); absolute paths outside it are replaced with `<path>`.
  */
+/**
+ * TAG: `[REDACT]`
+ *
+ * Grep `[REDACT]` to find every site that persists or surfaces raw error text on
+ * a path that reaches a browser — worker task errors folded into
+ * `worker-status.json`, `branch.json` parse failures served by the admin
+ * branch-health endpoint, rebase-failure messages, and their tests.
+ *
+ * Those sites carried the tag `[HIGH-1]`/`[MEDIUM-2]` until 2026-08-23, IDs from
+ * a review pass whose findings list was never committed — 13 occurrences across
+ * 6 files resolving to nothing. Renamed rather than deleted because the
+ * underlying rule is real and genuinely cross-file: a Node error embeds absolute
+ * paths, and a git remote URL can embed a token, so anything on that path is
+ * redacted through the function below.
+ *
+ * The tag is a grep aid, not the rule. The rule is stated at each site.
+ */
 export function sanitizeErrorMessage(message) {
     let result = redactCredentials(message);
     // Paths under the project root become relative (split/join avoids regex

package/dist/utils/git.d.ts

@@ -27,7 +27,7 @@ export declare function isNetworkRemoteUrl(url: string): boolean;
  *
  * Deliberately narrow: ordinary transient push failures -- network drops,
  * auth/permission denial, lock contention -- must keep retrying with backoff
- * (see worker/cms-worker.ts's `isPermanentTaskFailure`, which treats git
+ * (see worker/task-runner.ts's `isPermanentTaskFailure`, which treats git
  * failures as transient precisely so those cases still get retried). Only
  * this specific, structurally-unretryable shape should fail fast (worker) or
  * return 409 (API) instead.

package/dist/utils/git.js

@@ -79,7 +79,7 @@ const REJECTION_HINT = 'Updates were rejected because';
  *
  * Deliberately narrow: ordinary transient push failures -- network drops,
  * auth/permission denial, lock contention -- must keep retrying with backoff
- * (see worker/cms-worker.ts's `isPermanentTaskFailure`, which treats git
+ * (see worker/task-runner.ts's `isPermanentTaskFailure`, which treats git
  * failures as transient precisely so those cases still get retried). Only
  * this specific, structurally-unretryable shape should fail fast (worker) or
  * return 409 (API) instead.

package/dist/utils/occ-json-write.js

@@ -227,7 +227,7 @@ export async function withOccFileLock(filePath, fn) {
         // process's lockfile heartbeat stops (crash) or the lock naturally
         // expires, so this is logged rather than rethrown.
         //
-        // [NIT-1] ENOENT specifically is expected, not an error: the lock
+        // ENOENT specifically is expected, not an error: the lock
         // marker's target directory legitimately vanishes when an admin purge
         // (see api/admin-branch-health.ts) renames the branch tree out from
         // under a held lock. Every other release failure still warns.