canopycms 0.0.68-int.98 → 0.1.0

package/dist/entry-schema.d.ts

@@ -116,6 +116,45 @@ export type RestrictedReference = Simplify<ResolvedReferenceMeta & {
 }>;
 /** Assemble a {@link RestrictedReference}. Takes no target data, so none can leak into it. */
 export declare function buildRestrictedReference(meta: ResolvedReferenceMeta, title: string): RestrictedReference;
+/**
+ * What a reference resolves to when its id names no readable entry: a deleted target, an id a
+ * merge or hand edit left behind, or one naming a collection. It carries the id and nothing else,
+ * so a save of the referring entry writes the id back rather than erasing it, and a renderer can
+ * say which entry is missing. The production build fails on one (`static/index.ts`,
+ * `assertNoDanglingReferences`).
+ */
+export type MissingReference = {
+    id: string;
+    unavailable: true;
+    reason: 'missing';
+};
+/** Assemble a {@link MissingReference}. */
+export declare function buildMissingReference(id: string): MissingReference;
+/**
+ * Every reference value that is not the target's data. Narrow on `unavailable`, then on `reason`:
+ * only a `'restricted'` one carries a title and URL.
+ */
+export type UnavailableReference = RestrictedReference | MissingReference;
+/**
+ * The resolved-target member of a reference field's value type `T`: the object members that
+ * are not marked `unavailable`. When `T` has none (`unknown`, or `string | null` for a reference
+ * without `resolvedSchema`), any resolved reference.
+ */
+export type ResolvedReferenceOf<T> = unknown extends T ? AnyResolvedReference : [Exclude<Extract<T, object>, {
+    unavailable: true;
+}>] extends [never] ? AnyResolvedReference : Exclude<Extract<T, object>, {
+    unavailable: true;
+}>;
+type AnyResolvedReference = Record<string, unknown> & ResolvedReferenceMeta;
+/**
+ * Whether a reference field's value is its resolved target, narrowing it to that target's type.
+ *
+ * True for a record carrying a string `id` and not marked `unavailable`. False for everything
+ * else a reference can hold: `null` or `undefined` (empty, or in live preview, still resolving),
+ * a bare id string (a reference that was not resolved), and a reference marked `unavailable` (a
+ * target the reader may not see, or one that no longer exists).
+ */
+export declare function isResolvedReference<T>(value: T): value is T & ResolvedReferenceOf<T>;
 /**
  * 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
@@ -171,9 +210,16 @@ type SelectOptionValue<O> = O extends {
 type SelectValue<F extends InferableField> = F extends {
     options: infer O extends readonly unknown[];
 } ? [O[number]] extends [never] ? string : SelectOptionValue<O[number]> : string;
+/**
+ * The key a list item or block carries (`ITEM_KEY` in item-keys.ts), spelled out as `ImageValue`
+ * is. Every canopy read returns it; optional so data built by hand, such as a write, needn't.
+ */
+type ItemKeyed = {
+    _key?: string;
+};
 type ObjectValue<F extends InferableField & {
     fields: readonly InferableField[];
-}> = F['list'] extends true ? Array<InferContentShape<F['fields']>> : InferContentShape<F['fields']>;
+}> = F['list'] extends true ? Array<InferContentShape<F['fields']> & ItemKeyed> : InferContentShape<F['fields']>;
 /**
  * Distributes over each member of a block-templates union to produce a discriminated union. The
  * bare type parameter `T` is what makes the conditional distribute: `{ name: 'hero'; ... } |
@@ -185,7 +231,7 @@ type DistributeBlockTemplate<T> = T extends {
 } ? {
     template: N & string;
     value: InferContentShape<Extract<Fields, readonly InferableField[]>>;
-} : never;
+} & ItemKeyed : never;
 type BlockValue<F extends InferableField & {
     templates: ReadonlyArray<{
         name: string;
@@ -228,7 +274,7 @@ type FieldValue<F extends InferableField> = F extends {
     resolvedSchema: infer S;
 } ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta & {
     unavailable?: undefined;
-}) | RestrictedReference | null> : F extends {
+}) | UnavailableReference | null> : F extends {
     type: 'reference';
 } ? ScalarValue<F, string | null> : F extends {
     type: 'image';

package/dist/entry-schema.js

@@ -54,6 +54,24 @@ export function buildRestrictedReference(meta, title) {
         reason: 'restricted',
     };
 }
+/** Assemble a {@link MissingReference}. */
+export function buildMissingReference(id) {
+    return { id, unavailable: true, reason: 'missing' };
+}
+/**
+ * Whether a reference field's value is its resolved target, narrowing it to that target's type.
+ *
+ * True for a record carrying a string `id` and not marked `unavailable`. False for everything
+ * else a reference can hold: `null` or `undefined` (empty, or in live preview, still resolving),
+ * a bare id string (a reference that was not resolved), and a reference marked `unavailable` (a
+ * target the reader may not see, or one that no longer exists).
+ */
+export function isResolvedReference(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.id === 'string' && record[RESTRICTED_REFERENCE_MARKER] !== true;
+}
 /** 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,79 @@
-import { type SimpleGitOptions, type StatusResult } from 'simple-git';
+import { type SimpleGit, type SimpleGitOptions, type StatusResult } from 'simple-git';
+import type { CanopyConfig } from './config/index.js';
 import type { OperatingMode } from './operating-mode/index.js';
+import type { WorkerStartupFailure } from './task-queue/worker-status.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. `git`
+ * is how the worker passes the instance it runs every shared repository with.
+ */
+export declare function ensureRemoteGitConfig(gitDir: string, git?: SimpleGit): 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. `git` as for `ensureRemoteGitConfig`.
+ */
+export declare function repackBareRemoteIfNeeded(gitDir: string, git?: SimpleGit): Promise<BareRemoteRepackResult>;
+/**
+ * simple-git reads a git that exited by signal (exit code null, often with no stderr) as success,
+ * so a clone or checkout the OOM killer stopped would pass for complete. Given as `errors` to a
+ * GitManager's own instance, to `cloneRepo`'s, and to the worker's ref probes of an existing
+ * remote.git (worker/cms-worker.ts); its static helpers and the bare-remote functions do not pass
+ * it yet (safeinsights/canopycms#845).
+ */
+export declare function failOnSignalExit(error: Buffer | Error | undefined, result: {
+    exitCode: number;
+}): Buffer | Error | undefined;
+/**
+ * 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
@@ -17,8 +89,8 @@ export declare function gitNetworkChildEnv(): Record<string, string>;
  * next push no-ops and the editor's commit never arrives while the branch still
  * reports `synced`. Confining `+`/`--prune` to this namespace keeps them off
  * those local heads; `reconcileTrackedBranches()` (worker/git-sync.ts) is what
- * subsequently, and non-destructively, brings `refs/heads/*` toward what is
- * tracked here.
+ * then brings `refs/heads/*` toward GitHub's branches, never moving a head it
+ * finds editor work in.
  */
 export declare const GITHUB_TRACKING_REF_PREFIX = "refs/remotes/github/";
 /**
@@ -78,7 +150,13 @@ export declare class GitRemoteRefMissingError extends Error {
  */
 export declare class RemoteNotReadyError extends Error {
     readonly expectedRemotePath: string;
-    constructor(expectedRemotePath: string);
+    readonly workerStartupFailure?: WorkerStartupFailure | undefined;
+    /**
+     * @param workerStartupFailure - The startup failure the worker recorded, if it recorded one;
+     *   a current one means the worker is not coming without an admin's fix.
+     * @param configured - `expectedRemotePath` is a configured local remote, not the auto-detected one.
+     */
+    constructor(expectedRemotePath: string, workerStartupFailure?: WorkerStartupFailure | undefined, configured?: boolean);
 }
 export interface ResolveRemoteUrlOptions {
     mode: OperatingMode;
@@ -93,6 +171,10 @@ export interface ResolveRemoteUrlOptions {
      */
     allowNetworkRemoteInProd?: boolean;
 }
+/** Where prod reads an unset base branch from: the remote a workspace would clone. */
+type BaseBranchRemoteOptions = Pick<CanopyConfig, 'defaultRemoteUrl' | 'sourceRoot' | 'allowNetworkRemoteInProd'> & {
+    remoteUrl?: string;
+};
 export interface InitializeWorkspaceOptions {
     workspacePath: string;
     branchName: string;
@@ -119,6 +201,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;
@@ -127,7 +211,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
@@ -178,10 +268,10 @@ export declare class GitManager {
      * Delete `refs/heads/<branch>` from a bare local mirror, if present. A
      * no-op (not an error) when the ref doesn't exist.
      *
-     * The explicit path for removing a deleted branch's local head, which the
-     * sync loop deliberately is not (reconcileTrackedBranches never deletes a
-     * head — see GITHUB_TRACKING_REF_PREFIX). Called by api/branch.ts's
-     * deleteBranchHandler: a head left in `remote.git` forever makes the
+     * The path that removes a deleted branch's local head at once; the sync
+     * loop's reconcileTrackedBranches removes one only after GitHub no longer
+     * has the branch. Called by api/branch.ts's deleteBranchHandler: a head
+     * left in `remote.git` 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 the branch to the same name, and a squash-merged old tip is
@@ -234,7 +324,10 @@ 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. */
+    /**
+     * The not-ready error for a mode whose remote is auto-detected, carrying the worker's recorded
+     * startup failure, or `undefined` for other modes.
+     */
     private static remoteNotReadyError;
     /**
      * Resolves the remote URL for git operations following the priority:
@@ -252,6 +345,38 @@ 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>;
+    /**
+     * Prod's base branch when `defaultBaseBranch` is unset: the branch named by the HEAD of the
+     * remote the workspaces clone from, read locally because the Lambda has no internet. That
+     * remote is the bare `remote.git` the worker keeps, whose HEAD it sets to the base branch it
+     * uses (worker/cms-worker.ts `recordBaseBranchInRemoteHead`), so the two agree.
+     *
+     * While that remote does not exist yet, whether auto-detected or configured as a local path,
+     * `'pending'` resolves `undefined` and `'throw'` rejects with {@link RemoteNotReadyError}. A network remote, or a HEAD that names no branch, throws
+     * `BaseBranchUnresolvedError`.
+     */
+    static detectBaseBranch(config: BaseBranchRemoteOptions, whenNoRemote: 'pending'): Promise<string | undefined>;
+    static detectBaseBranch(config: BaseBranchRemoteOptions, whenNoRemote: 'throw'): Promise<string>;
+    /**
+     * The base branch a workspace about to be provisioned forks from: the configured one, else
+     * dev's git HEAD (resolveBaseBranch), else prod's remote HEAD ({@link detectBaseBranch}), which
+     * rejects with RemoteNotReadyError while the worker has not created the remote.
+     */
+    static resolveWorkspaceBaseBranch(options: BaseBranchRemoteOptions & {
+        mode: OperatingMode;
+        baseBranch?: string;
+    }): 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`.
      *
@@ -288,6 +413,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;
@@ -295,10 +428,25 @@ 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>;
+    /** The checked-out commit's SHA. */
+    headSha(): Promise<string>;
+    /**
+     * Move the checked-out branch back to `sha`, leaving everything after it unstaged in the
+     * working tree (`reset --mixed`). Takes a SHA the caller read itself, never a relative ref:
+     * a commit call that committed nothing still resolves, so "the last commit" is not always
+     * the caller's.
+     */
+    resetKeepingChanges(sha: string): Promise<void>;
     push(branch?: string): Promise<void>;
     /**
      * The checked-out branch's plain name. `rev-parse --abbrev-ref HEAD` prints
@@ -330,10 +478,23 @@ export declare class GitManager {
      * constraint.
      */
     listChangedPathsSinceBase(): Promise<string[]>;
+    /**
+     * Repo-relative paths of every file in the base branch's just-fetched tip or in its merge base
+     * with HEAD, limited to `under` (a repo-relative directory) when given. The merge base counts
+     * because a file the base deleted after the fork is still the base's on a branch not yet
+     * rebased. Reads commits, never the working tree, so a sparse clone lists the whole base.
+     */
+    listBaseFiles(under?: string): Promise<string[]>;
+    /** Fetch the base branch and return its tip, pinned as pullBaseInner explains. */
+    private fetchBaseTip;
+    /** Repo-relative paths of every file in `rev`'s tree, under `under` when given. */
+    private listTreeFiles;
     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[]>;
@@ -399,3 +560,4 @@ export declare class GitManager {
      */
     private isEmptyInitialBranch;
 }
+export {};