canopycms 0.0.67 → 0.0.68-int.100

package/dist/editor/preview-bridge.js

@@ -1,13 +1,20 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { toSameOriginPath } from '../utils/url-prefix.js';
 import { formatCanopyPath } from './canopy-path.js';
+import { setPreviewAssetBase } from './preview-asset-base.js';
+import { isSamePreviewPath } from './preview-path.js';
 export const __CANOPY_PREVIEW_CLIENT__ = true;
 export const CANOPY_PREVIEW_MESSAGE = 'canopycms:draft:update';
 export const CANOPY_PREVIEW_FOCUS = 'canopycms:preview:focus';
 export const CANOPY_PREVIEW_HIGHLIGHT = 'canopycms:preview:highlight';
 export const CANOPY_PREVIEW_READY = 'canopycms:preview:ready';
 export const CANOPY_PREVIEW_ERROR = 'canopycms:preview:error';
+/** `assetBase` from a draft, only if it is a same-origin path: nothing else may steer `<img>`s. */
+const readAssetBase = (value) => typeof value === 'string' && value.startsWith('/') && toSameOriginPath(value) === value
+    ? value
+    : undefined;
 /**
  * Resolve a (possibly relative) URL to an origin for postMessage targeting.
  * Falls back to the page's own origin, so same-origin editor/preview setups
@@ -116,8 +123,12 @@ export const usePreviewData = (path, initialData, opts) => {
             if (!isTrustedEditorMessage(event, editorOrigin))
                 return;
             const msg = event.data;
-            if (!msg || msg.type !== CANOPY_PREVIEW_MESSAGE || msg.path !== path)
+            if (!msg || msg.type !== CANOPY_PREVIEW_MESSAGE)
                 return;
+            if (typeof msg.path !== 'string' || !isSamePreviewPath(msg.path, path))
+                return;
+            // Before setData, so the render the draft triggers already reads it.
+            setPreviewAssetBase(readAssetBase(msg.assetBase));
             setData(msg.data);
             if (msg.isLoading !== undefined) {
                 setIsLoading(msg.isLoading);
@@ -208,7 +219,7 @@ export const usePreviewFocusEmitter = (entryPath, opts) => {
  * Lightweight iframe wrapper to keep the preview in sync with form state.
  * It posts the latest draft data to the iframe after load and when data changes.
  */
-export const PreviewFrame = ({ src, path, data, isLoading, className, style, highlightEnabled, onPreviewError, }) => {
+export const PreviewFrame = ({ src, path, data, isLoading, className, style, highlightEnabled, onPreviewError, assetBase, }) => {
     const iframeRef = useRef(null);
     // Pin the preview origin from the src prop: outbound messages target it (never '*'),
     // and inbound messages must come from it. An iframe that navigates cross-origin
@@ -235,11 +246,13 @@ export const PreviewFrame = ({ src, path, data, isLoading, className, style, hig
     const post = () => {
         if (data === undefined)
             return;
+        const sameOrigin = previewOrigin === window.location.origin;
         sendDraftUpdate(iframeRef.current, {
             type: CANOPY_PREVIEW_MESSAGE,
             path,
             data,
             isLoading,
+            ...(assetBase !== undefined && sameOrigin ? { assetBase } : {}),
         }, previewOrigin);
     };
     const postHighlight = () => {

package/dist/editor/preview-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reduces a preview URL to what identifies the page, its path and query, with no origin,
+ * fragment or trailing slash. The editor names a page by the `src` it built and the framed page
+ * by its own location. An absolute `src`, or a host redirect that adds or drops a trailing slash,
+ * spells the same page two ways, and the bridge must still match them.
+ * @internal Exported for tests.
+ */
+export declare const normalizePreviewPath: (url: string) => string;
+/** Whether two preview URLs name the same page; see `normalizePreviewPath`. */
+export declare const isSamePreviewPath: (a: string, b: string) => boolean;

package/dist/editor/preview-path.js

@@ -0,0 +1,20 @@
+import { stripTrailingSlashes } from '../utils/url-prefix.js';
+/**
+ * Reduces a preview URL to what identifies the page, its path and query, with no origin,
+ * fragment or trailing slash. The editor names a page by the `src` it built and the framed page
+ * by its own location. An absolute `src`, or a host redirect that adds or drops a trailing slash,
+ * spells the same page two ways, and the bridge must still match them.
+ * @internal Exported for tests.
+ */
+export const normalizePreviewPath = (url) => {
+    let parsed;
+    try {
+        parsed = new URL(url, 'http://preview.invalid');
+    }
+    catch {
+        return url;
+    }
+    return `${stripTrailingSlashes(parsed.pathname) || '/'}${parsed.search}`;
+};
+/** Whether two preview URLs name the same page; see `normalizePreviewPath`. */
+export const isSamePreviewPath = (a, b) => normalizePreviewPath(a) === normalizePreviewPath(b);

package/dist/editor/theme.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
-import { DEFAULT_THEME, MantineProvider, createTheme, } from '@mantine/core';
+import { DEFAULT_THEME, MantineProvider, getDefaultZIndex, createTheme, } from '@mantine/core';
 import { Notifications } from '@mantine/notifications';
 import { ModalsProvider } from '@mantine/modals';
 import { generateColors } from '@mantine/colors-generator';
@@ -62,5 +62,5 @@ export const createCanopyTheme = (options) => {
 };
 export const CanopyCMSProvider = ({ children, colors, colorScheme = 'light', themeOverride, withNotifications = true, }) => {
     const theme = useMemo(() => createCanopyTheme({ colors, themeOverride }), [colors, themeOverride]);
-    return (_jsx(MantineProvider, { theme: theme, defaultColorScheme: colorScheme, children: _jsxs(ModalsProvider, { children: [withNotifications ? _jsx(Notifications, { position: "bottom-left" }) : null, children] }) }));
+    return (_jsx(MantineProvider, { theme: theme, defaultColorScheme: colorScheme, children: _jsxs(ModalsProvider, { modalProps: { zIndex: getDefaultZIndex('popover') }, children: [withNotifications ? _jsx(Notifications, { position: "bottom-left" }) : null, children] }) }));
 };

package/dist/entry-schema-registry.d.ts

@@ -12,10 +12,10 @@ import type { EntrySchemaRegistry } from './schema/types.js';
  * interface to maintain. Keyed any other way, the derived map is keyed by that
  * string instead and will not plug into `TEntryTypes`.
  *
- * Rejected at call time: an empty registry; a schema that is not a non-empty
- * `EntrySchema` array; more than one `isTitle` per schema, or one on a non-string
- * field or inside a list; more than one `isBody`, or one on a field that is not
- * markdown/mdx or is named one of `RESOLVED_REFERENCE_KEYS`. This is also the one
+ * Rejected at call time: an empty registry; a schema that is not a non-empty `EntrySchema`
+ * array; more than one `isTitle` per schema, or one on a non-string field or inside a list;
+ * more than one `isBody`, or one on a field that is not markdown/mdx or is named one of
+ * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups
  * inside object/block fields, no field-name collisions after group flattening.

package/dist/entry-schema-registry.js

@@ -1,8 +1,8 @@
 import { countTitleFields, findInvalidTitleFields, findTitleFieldsInLists, } from './utils/title-field.js';
 import { countBodyFields, findInvalidBodyFields, findReservedBodyFieldName, } from './utils/body-field.js';
-import { RESOLVED_REFERENCE_KEYS } from './entry-schema.js';
+import { RESOLVED_REFERENCE_KEYS, RESTRICTED_REFERENCE_MARKER } from './entry-schema.js';
 import { flattenGroupFields } from './utils/flatten-group-fields.js';
-import { ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, } from './config/validation.js';
+import { ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureItemTitleFieldsExist, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, } from './config/validation.js';
 /** Look up a field's type by dotted path (e.g., "meta.order").
  * Groups are transparent — their children are searched at the same path level. */
 function findFieldType(fields, dottedPath) {
@@ -35,10 +35,10 @@ function findFieldType(fields, dottedPath) {
  * interface to maintain. Keyed any other way, the derived map is keyed by that
  * string instead and will not plug into `TEntryTypes`.
  *
- * Rejected at call time: an empty registry; a schema that is not a non-empty
- * `EntrySchema` array; more than one `isTitle` per schema, or one on a non-string
- * field or inside a list; more than one `isBody`, or one on a field that is not
- * markdown/mdx or is named one of `RESOLVED_REFERENCE_KEYS`. This is also the one
+ * Rejected at call time: an empty registry; a schema that is not a non-empty `EntrySchema`
+ * array; more than one `isTitle` per schema, or one on a non-string field or inside a list;
+ * more than one `isBody`, or one on a field that is not markdown/mdx or is named one of
+ * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups
  * inside object/block fields, no field-name collisions after group flattening.
@@ -92,8 +92,12 @@ export function createEntrySchemaRegistry(registry) {
         if (reservedBodyField) {
             throw new Error(`Entry schema registry entry "${key}": field "${reservedBodyField}" has isBody: true but "${reservedBodyField}" is reserved — reference resolution sets ${RESOLVED_REFERENCE_KEYS.map((k) => `"${k}"`).join(', ')} on a resolved reference, and a body field with one of those names would overwrite it. Rename the field (the body's field name is yours to choose; only these four are reserved).`);
         }
+        if (flattenGroupFields(schema).some((f) => f.name === RESTRICTED_REFERENCE_MARKER)) {
+            throw new Error(`Entry schema registry entry "${key}": field "${RESTRICTED_REFERENCE_MARKER}" is reserved — a resolved reference carries "${RESTRICTED_REFERENCE_MARKER}: true" only when the reader may not read its target, so a field with that name cannot be delivered on a reference to this entry type. Rename the field.`);
+        }
         ensureSelectFieldsHaveOptions(schema);
         ensureReferenceFieldsHaveScope(schema);
+        ensureItemTitleFieldsExist(schema);
         ensureNoGroupsInsideComplexFields(schema);
         ensureNoFlattenedFieldNameCollisions(schema, `entry schema "${key}"`);
     }

package/dist/entry-schema.d.ts

@@ -81,9 +81,6 @@ export interface ResolvedReferenceMeta {
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
  * embed it, then the reserved metadata.
  *
- * Exists so the two places that construct one — the server resolver in content-store.ts and
- * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift.
- *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
  * `value.id` (`referenceValueId`) — a shadowed id makes a re-save persist the wrong value and
@@ -95,6 +92,30 @@ export declare function buildResolvedReference(data: Record<string, unknown>, me
     fieldName: string;
     value: string | undefined;
 }): Record<string, unknown>;
+/**
+ * The key that marks a `RestrictedReference`. Reserved as an entry field name, at the top level
+ * of any schema, because any schema can be a reference target.
+ */
+export declare const RESTRICTED_REFERENCE_MARKER = "unavailable";
+/**
+ * What a reference resolves to when the reader may not read its target: enough to render a
+ * link (a title and the URL, which a denied reader can follow to a sign-in page) and nothing
+ * else of the target's data.
+ *
+ * `unavailable: true` is the marker a renderer branches on, so a denied target never arrives
+ * looking like a full one with its fields `undefined`; `reason` says why, leaving room for
+ * other reasons a target cannot be shown. A reference the reader may see in full never carries
+ * `unavailable`. `id` is always present, so a save of the referring entry writes the reference
+ * back unchanged (`normalizeReferenceValues` recovers it from `value.id`).
+ */
+export type RestrictedReference = Simplify<ResolvedReferenceMeta & {
+    /** The target's display title, by `resolveEntryTitle`'s fallback chain. */
+    title: string;
+    unavailable: true;
+    reason: 'restricted';
+}>;
+/** Assemble a {@link RestrictedReference}. Takes no target data, so none can leak into it. */
+export declare function buildRestrictedReference(meta: ResolvedReferenceMeta, title: string): RestrictedReference;
 /**
  * Recursively flatten inline groups (type: 'group') out of a field tuple: they contribute
  * no key to the content shape, so their children merge into the parent level and
@@ -205,7 +226,9 @@ type FieldValue<F extends InferableField> = F extends {
 } ? ScalarValue<F, SelectValue<F>> : F extends {
     type: 'reference';
     resolvedSchema: infer S;
-} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta) | null> : F extends {
+} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta & {
+    unavailable?: undefined;
+}) | RestrictedReference | null> : F extends {
     type: 'reference';
 } ? ScalarValue<F, string | null> : F extends {
     type: 'image';

package/dist/entry-schema.js

@@ -14,9 +14,6 @@ export const RESOLVED_REFERENCE_KEYS = ['id', 'slug', 'collection', 'urlPath'];
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
  * embed it, then the reserved metadata.
  *
- * Exists so the two places that construct one — the server resolver in content-store.ts and
- * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift.
- *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
  * `value.id` (`referenceValueId`) — a shadowed id makes a re-save persist the wrong value and
@@ -35,8 +32,28 @@ export function buildResolvedReference(data, meta, body) {
     resolved.slug = meta.slug;
     resolved.collection = meta.collection;
     resolved.urlPath = meta.urlPath;
+    // Backstop for the registry's rejection of a field with this name (entry-schema-registry.ts):
+    // a full reference carrying the marker would read as one the reader may not see.
+    delete resolved[RESTRICTED_REFERENCE_MARKER];
     return resolved;
 }
+/**
+ * The key that marks a `RestrictedReference`. Reserved as an entry field name, at the top level
+ * of any schema, because any schema can be a reference target.
+ */
+export const RESTRICTED_REFERENCE_MARKER = 'unavailable';
+/** Assemble a {@link RestrictedReference}. Takes no target data, so none can leak into it. */
+export function buildRestrictedReference(meta, title) {
+    return {
+        id: meta.id,
+        slug: meta.slug,
+        collection: meta.collection,
+        urlPath: meta.urlPath,
+        title,
+        unavailable: true,
+        reason: 'restricted',
+    };
+}
 /** Define an entry schema's field array with literal inference, without sprinkling `as const`. */
 export const defineEntrySchema = (fields) => fields;
 /**

package/dist/git-manager.d.ts

@@ -1,7 +1,64 @@
 import { type SimpleGitOptions, type StatusResult } from 'simple-git';
 import type { OperatingMode } from './operating-mode/index.js';
+import type { ProvisionLog } from './utils/provision-log.js';
 export declare function gitChildEnv(overrides: Record<string, string>): Record<string, string>;
 export declare function gitNetworkChildEnv(): Record<string, string>;
+/**
+ * Settings written into every bare `remote.git` CanopyCMS creates: the worker's (prod) and the
+ * simulated remote (dev). A push runs `receive-pack` with remote.git's own config and none of the
+ * pusher's: git unsets `GIT_CONFIG_PARAMETERS` before spawning it for a local-path push. Unset, a
+ * push starts auto-housekeeping there (detached, or inside a Lambda that is frozen mid-run) that
+ * repacks while another process clones, and pushes under the default `unpackLimit` (100) leave
+ * loose objects that every local clone copies one NFS round trip at a time.
+ *
+ * Never an `extensions.*` key: once a repo is at `repositoryformatversion` 1, a git that does not
+ * know the key refuses it, and Lambda runs git 2.39.
+ * @internal Exported for tests.
+ */
+export declare const REMOTE_GIT_CONFIG: ReadonlyArray<readonly [key: string, value: string]>;
+/** Write each of {@link REMOTE_GIT_CONFIG} into the bare repo `gitDir` only where it differs. */
+export declare function ensureRemoteGitConfig(gitDir: string): Promise<void>;
+interface BareRemoteObjectCounts {
+    loose: number;
+    packs: number;
+}
+export type BareRemoteRepackResult = {
+    repacked: false;
+    before: BareRemoteObjectCounts;
+} | {
+    repacked: true;
+    before: BareRemoteObjectCounts;
+    after: BareRemoteObjectCounts;
+    ms: number;
+};
+/**
+ * Repack the bare repo `gitDir` once it holds more than {@link REMOTE_GIT_MAX_LOOSE_OBJECTS}
+ * loose objects or {@link REMOTE_GIT_MAX_PACKS} packs, then pack its refs. Under
+ * {@link REMOTE_GIT_CONFIG} every push adds a pack, and nothing else ever compacts them.
+ *
+ * Safe beside concurrent pushes and clones, which is why it is `--cruft` with no expiry:
+ * unreachable objects move into a cruft pack rather than being dropped, so a push that read an
+ * old object before the repack still finds it, and a repack only deletes packs it listed when it
+ * began. A clone that hardlinked a pack keeps that inode when the repack unlinks the remote's
+ * name for it, and packs are never modified in place. `repack -d` also removes the loose objects
+ * it packed and their emptied fan-out directories.
+ */
+export declare function repackBareRemoteIfNeeded(gitDir: string): Promise<BareRemoteRepackResult>;
+/**
+ * Config every workspace clone writes into its own `.git/config`: the managed
+ * marker that ensureRemote's guard checks, and a fallback author for internal
+ * commits such as the orphan settings init (ensureAuthor() sets the real one
+ * before user-facing commits).
+ */
+export declare function managedWorkspaceConfig(gitBotAuthorName: string, gitBotAuthorEmail: string): Record<string, string>;
+export interface CloneRepoOptions {
+    /** The clone's remote name; git's default is `origin`. */
+    remoteName?: string;
+    /** Leave the working tree unpopulated for the caller to check out. */
+    noCheckout?: boolean;
+    /** Written into the new repo's own config by the clone (`git clone -c`). */
+    config?: Record<string, string>;
+}
 /**
  * Remote-tracking namespace that `syncGit()`'s GitHub fetch lands refs in
  * (`+refs/heads/*:${GITHUB_TRACKING_REF_PREFIX}*`), instead of writing
@@ -69,6 +126,17 @@ export declare class GitRemoteRefMissingError extends Error {
      */
     gitError?: unknown | undefined);
 }
+/**
+ * No git remote is configured and the one the strategy auto-detects does not
+ * exist yet: in prod, the EC2 worker creates `{workspaceRoot}/remote.git` on
+ * its first boot, so until then every request that needs a workspace fails
+ * here. Usually transient, unlike a missing remote in a mode with nothing to wait for.
+ * The HTTP layer maps it to a 503 (`http/worker-not-ready.ts`).
+ */
+export declare class RemoteNotReadyError extends Error {
+    readonly expectedRemotePath: string;
+    constructor(expectedRemotePath: string);
+}
 export interface ResolveRemoteUrlOptions {
     mode: OperatingMode;
     remoteUrl?: string;
@@ -108,6 +176,8 @@ export interface InitializeWorkspaceOptions {
      * only; settings workspaces commit by explicit path and don't need it.
      */
     gitExcludePattern?: string;
+    /** Times each provisioning step; no step lines are printed without one. */
+    provisionLog?: ProvisionLog;
 }
 export declare class GitManager {
     private readonly git;
@@ -116,7 +186,13 @@ export declare class GitManager {
     private readonly remote;
     private readonly skipIndexMarker;
     constructor(options: GitManagerOptions, gitOptions?: Partial<SimpleGitOptions>);
-    static cloneRepo(remoteUrl: string, targetPath: string, baseBranch?: string): Promise<void>;
+    /**
+     * Single-branch clone of `baseBranch`, retried once: a clone can lose a race
+     * with the worker's repack of `remote.git` deleting a pack it had just
+     * listed. Before the retry it clears only what it created itself, so a
+     * target that held files beforehand is never touched.
+     */
+    static cloneRepo(remoteUrl: string, targetPath: string, baseBranch?: string, options?: CloneRepoOptions): Promise<void>;
     /**
      * Initializes a local bare git repository to simulate a remote for dev mode,
      * seeded with the current state of baseBranch. Idempotent: an existing remote
@@ -173,7 +249,7 @@ export declare class GitManager {
      * deleteBranchHandler: a head left in `remote.git` forever makes the
      * create -> publish -> squash-merge -> delete -> reuse-the-name cycle reject
      * the reused branch's first publish non-fast-forward against the stale head
-     * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip is
+     * (`GitManager.push()` pushes the branch to the same name, and a squash-merged old tip is
      * not an ancestor of the new branch), and a retried submit then skips the
      * local push on a clean tree and enqueues the worker push of the STALE head,
      * resurrecting the deleted branch's content on GitHub as an apparent success.
@@ -223,6 +299,8 @@ export declare class GitManager {
      * @param source - Where `url` came from, for the thrown error message only.
      */
     private static assertRemoteUrlAllowedInMode;
+    /** The not-ready error for a mode whose remote is auto-detected, or `undefined` for other modes. */
+    private static remoteNotReadyError;
     /**
      * Resolves the remote URL for git operations following the priority:
      * 1. Explicit remoteUrl parameter
@@ -239,6 +317,17 @@ export declare class GitManager {
      * @returns Remote URL or undefined if no remote is needed
      */
     static resolveRemoteUrl(options: ResolveRemoteUrlOptions): Promise<string | undefined>;
+    /**
+     * {@link resolveRemoteUrl} for a workspace about to be cloned, which needs a
+     * remote: none resolving is the worker-not-ready error in a mode whose
+     * remote the worker creates, and a configuration error otherwise.
+     */
+    static resolveCloneRemoteUrl(options: ResolveRemoteUrlOptions): Promise<string>;
+    /**
+     * {@link cloneRepo} for a workspace, failing with one message that names the
+     * workspace, the remote and the base branch, which git's own error mixes.
+     */
+    static cloneWorkspace(remoteUrl: string, workspacePath: string, baseBranch: string, options: CloneRepoOptions): Promise<void>;
     /**
      * Check whether a git repository is already initialized at `workspacePath`.
      *
@@ -275,6 +364,14 @@ export declare class GitManager {
      */
     private invalidateContentIndexes;
     checkoutBranch(branch: string): Promise<void>;
+    /**
+     * The one checkout of a `--no-checkout` clone, which has the base branch
+     * and its remote-tracking ref and nothing else, so neither the branch
+     * listing nor the fetch that {@link checkoutBranch} starts with is needed.
+     * The missing index makes git populate the whole tree, even for the base
+     * branch HEAD already names.
+     */
+    checkoutFreshClone(branch: string): Promise<void>;
     private checkoutBranchInner;
     pullBase(): Promise<void>;
     private pullBaseInner;
@@ -282,9 +379,22 @@ export declare class GitManager {
     private pullCurrentBranchInner;
     rebaseOntoBase(): Promise<void>;
     private rebaseOntoBaseInner;
+    /** `--sparse` stages a named path outside a sparse clone's cone (branch-sparse.ts). */
     add(files: string | string[]): Promise<void>;
+    /**
+     * Restrict the working tree to `dirs` in cone mode, which always keeps the root-level files.
+     * Runs before a `--no-checkout` clone's one checkout, which invalidates the content caches.
+     */
+    setSparseCone(dirs: readonly string[]): Promise<void>;
+    /** Stage every working-tree change except canopycms's own state. See {@link stageAllExceptCanopyState}. */
+    addAllExceptCanopyState(): Promise<void>;
     commit(message: string): Promise<void>;
     push(branch?: string): Promise<void>;
+    /**
+     * The checked-out branch's plain name. `rev-parse --abbrev-ref HEAD` prints
+     * `heads/<name>` when a same-named tag exists, which is not a branch name.
+     */
+    private currentBranchName;
     /**
      * Whether the local branch has commits the remote mirror doesn't -- i.e.
      * whether push() would move the remote ref forward.
@@ -303,10 +413,19 @@ export declare class GitManager {
      * ("couldn't find remote ref"); that counts as "ahead", not an error.
      */
     hasUnpushedCommits(branch?: string): Promise<boolean>;
+    /**
+     * Repo-relative paths that differ between HEAD and its merge base with the
+     * base branch: everything the branch changes, across all of its commits.
+     * Diffs against the just-fetched base tip pinned to a SHA — the pullBaseInner
+     * constraint.
+     */
+    listChangedPathsSinceBase(): Promise<string[]>;
     ensureAuthor(author: {
         name: string;
         email: string;
     }): Promise<void>;
+    /** Writes each key into this repo's own config only where it differs. */
+    ensureLocalConfig(values: Record<string, string>): Promise<void>;
     ensureRemote(remoteUrl: string): Promise<void>;
     hasUncommittedChanges(): Promise<boolean>;
     getUncommittedFiles(): Promise<string[]>;
@@ -317,11 +436,59 @@ export declare class GitManager {
      */
     ensureGitExclude(pattern: string): Promise<void>;
     /**
-     * Create an orphan branch (no shared history) for settings, so
-     * deployment-specific settings never pollute content history. It holds only
-     * settings files committed by explicit path (permissions.json, groups.json at
-     * the workspace root).
+     * Put the workspace on the settings branch: an orphan (no shared history),
+     * so deployment-specific settings never pollute content history. It holds
+     * only settings files committed by explicit path (permissions.json,
+     * groups.json at the workspace root).
+     *
+     * The remote is the settings branch's durable copy, and the workspace clone
+     * is `--single-branch` at the base branch, so the remote is asked first:
+     * - no local branch: check out the remote's, or create an empty orphan only
+     *   when the remote has none. An unreadable remote throws
+     *   {@link SettingsRemoteUnreadableError} rather than guess "none".
+     * - local branch present: a history unrelated to the remote's is repaired
+     *   onto the remote's when the local branch is still its empty initial
+     *   commit with a clean working tree, and otherwise throws
+     *   {@link SettingsBranchDivergedError}; local commits are never discarded.
+     *   An unreadable remote throws only for that empty branch, since one that
+     *   holds settings can serve them and the next save surfaces the remote error.
+     * Either way a remote branch holding content is never adopted:
+     * {@link SettingsBranchHasContentHistoryError}.
      */
     createOrphanSettingsBranch(branchName: string, initialFiles: Record<string, string>): Promise<void>;
     private createOrphanSettingsBranchInner;
+    /**
+     * Compares the checked-out local settings branch with the remote's tip.
+     * Related histories are left for the next settings pull to reconcile; only
+     * an unrelated one is acted on here.
+     */
+    private reconcileLocalSettingsBranch;
+    /**
+     * The remote's tip for `branch`, or `undefined` when the remote has no such
+     * branch. A remote that cannot be read throws: `ls-remote` exits 0 with no
+     * output only for a reachable remote without the ref.
+     */
+    private remoteBranchTip;
+    /**
+     * Fetch `branch` from the remote and return the fetched commit, pinned as
+     * pullBaseInner explains. The full ref: a bare name resolves to a
+     * same-named tag first.
+     */
+    private fetchBranchTip;
+    /**
+     * Refuse to adopt a remote settings branch that holds content: its tip has a file other than
+     * the settings files, or its roots include the base branch's (a settings branch is an orphan).
+     * Neither alone suffices: a base can have a root of its own, and a content tree can be pruned.
+     * The base comes from the remote when the clone lacks it (it was cloned at an earlier base).
+     */
+    private assertNotContentHistory;
+    private baseBranchRev;
+    private rootCommits;
+    /**
+     * Whether `branch` is a single parentless commit with an empty tree, as
+     * orphan creation leaves it. Full refs throughout: a bare name resolves to a
+     * same-named tag first, and clones fetch tags.
+     */
+    private isEmptyInitialBranch;
 }
+export {};