@micacms/runtime 0.5.0-rc.2 → 0.6.0-rc.1

package/src/workspace/files.ts

@@ -0,0 +1,243 @@
+/**
+ * The content files of a working tree: the port everything reads and saves
+ * through, and its implementation. It extends `ContentSource`, so the Astro
+ * build and Mica share the same content reading code. `apply` is atomic: an
+ * entry is several files, and half of one is corruption.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import { contentPath, type ContentSource } from "@micacms/core";
+import { isMissing, within } from "@micacms/core/node";
+
+export class FilesError extends Error {
+  override name = "FilesError";
+}
+
+/** A file changed under an editor. The editor can recover: reload and apply again. */
+export class ConflictError extends FilesError {
+  override name = "ConflictError";
+  constructor(
+    message: string,
+    /** Paths whose revision no longer matched. */
+    readonly paths: string[],
+  ) {
+    super(message);
+  }
+}
+
+/** Who a commit names. */
+export interface Author {
+  name: string;
+  email: string;
+}
+
+export type FileChange =
+  | { type: "write"; path: string; contents: string | Uint8Array }
+  | { type: "delete"; path: string }
+  /** Deletes every file under `path`. Removing an entry removes its directory. */
+  | { type: "deleteTree"; path: string };
+
+export interface FileChanges {
+  changes: FileChange[];
+  /**
+   * Revisions the edit was based on, per path, so editors of different entries
+   * never block each other. Null asserts that the path does not exist. Omitted,
+   * the write is unconditional.
+   */
+  expect?: Record<string, string | null>;
+}
+
+export interface ContentFiles extends ContentSource {
+  /** Bytes of a file, for media. Null when there is no such file. */
+  readBinary(path: string): Promise<Uint8Array | null>;
+
+  /**
+   * An opaque token for the current state of `path`, or null when it is absent.
+   * Compare only for equality.
+   */
+  revision(path: string): Promise<string | null>;
+
+  /**
+   * Applies every change, or none of them. Throws `ConflictError` when any
+   * `expect` no longer holds.
+   */
+  apply(input: FileChanges): Promise<void>;
+}
+
+/**
+ * Refuses, before any write, a change or expectation that names the content
+ * root or a path outside it.
+ */
+export function checkChangePaths(input: FileChanges): void {
+  for (const change of input.changes) contentPath(change.path);
+  for (const path of Object.keys(input.expect ?? {})) contentPath(path);
+}
+
+export interface ContentFilesOptions {
+  root: string;
+}
+
+export function contentFiles(options: ContentFilesOptions): ContentFiles {
+  const base = resolve(options.root);
+  const full = (path: string, allowRoot = false) => within(base, path, { allowRoot });
+
+  const readBytes = async (path: string): Promise<Uint8Array | null> => {
+    try {
+      return await readFile(full(path));
+    } catch (error) {
+      if (isMissing(error)) return null;
+      throw error;
+    }
+  };
+
+  return {
+    origin: base,
+
+    async read(path) {
+      const bytes = await readBytes(path);
+      return bytes === null ? null : Buffer.from(bytes).toString("utf8");
+    },
+
+    readBinary: readBytes,
+
+    async list(path) {
+      let items;
+      try {
+        items = await readdir(full(path, true), { withFileTypes: true });
+      } catch (error) {
+        if (isMissing(error)) return [];
+        throw error;
+      }
+
+      return items
+        .filter((item) => item.isFile() || item.isDirectory())
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((item) => ({ name: item.name, type: item.isFile() ? ("file" as const) : ("directory" as const) }));
+    },
+
+    /**
+     * A content hash, not an mtime: a checkout that rewrites identical bytes
+     * must not cause a conflict.
+     */
+    async revision(path) {
+      const bytes = await readBytes(path);
+      if (bytes === null) return null;
+      return createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+    },
+
+    async apply(input: FileChanges): Promise<void> {
+      checkChangePaths(input);
+      await assertExpected(this, input);
+
+      // In-memory undo of every overwrite and removal. Content trees are small,
+      // so no journal is necessary.
+      const undo: Array<() => Promise<void>> = [];
+      const staging: string[] = [];
+
+      try {
+        for (const change of input.changes) {
+          if (change.type === "write") {
+            const target = full(change.path);
+            const previous = await readBytes(change.path);
+
+            undo.push(async () => {
+              if (previous === null) await rm(target, { force: true });
+              else await writeFile(target, previous);
+            });
+
+            await mkdir(dirname(target), { recursive: true });
+            // Write beside the target and rename, so a reader (the Astro dev
+            // server) never sees a partial file.
+            const staged = `${target}.mica-${process.pid}-${staging.length}`;
+            staging.push(staged);
+            await writeFile(staged, change.contents);
+            await rename(staged, target);
+            continue;
+          }
+
+          const target = full(change.path);
+
+          if (change.type === "delete") {
+            const previous = await readBytes(change.path);
+            if (previous === null) continue;
+
+            undo.push(async () => {
+              await mkdir(dirname(target), { recursive: true });
+              await writeFile(target, previous);
+            });
+            await unlink(target);
+            continue;
+          }
+
+          const saved = await snapshotTree(this, change.path);
+          undo.push(async () => {
+            for (const [path, bytes] of saved) {
+              const restored = full(path);
+              await mkdir(dirname(restored), { recursive: true });
+              await writeFile(restored, bytes);
+            }
+          });
+          await rm(target, { recursive: true, force: true });
+        }
+      } catch (error) {
+        // Reverse order, so a path written and then deleted comes back in its first state.
+        for (const step of undo.reverse()) {
+          // The original failure is what matters, not a rollback failure.
+          await step().catch(() => {});
+        }
+        for (const staged of staging) await rm(staged, { force: true }).catch(() => {});
+
+        throw error instanceof FilesError
+          ? error
+          : new FilesError(
+              `Could not apply changes to ${base}: ${(error as Error).message}`,
+            );
+      }
+    },
+  };
+}
+
+async function assertExpected(
+  files: ContentFiles,
+  input: FileChanges,
+): Promise<void> {
+  if (!input.expect) return;
+
+  const stale: string[] = [];
+  for (const [path, expected] of Object.entries(input.expect)) {
+    if ((await files.revision(path)) !== expected) stale.push(path);
+  }
+
+  if (stale.length > 0) {
+    throw new ConflictError(
+      "This content changed after you opened it. Reload to see the current version.",
+      stale,
+    );
+  }
+}
+
+/** Every file under `path`, so a tree deletion can be undone. */
+async function snapshotTree(
+  files: ContentFiles,
+  path: string,
+): Promise<Array<[string, Uint8Array]>> {
+  const saved: Array<[string, Uint8Array]> = [];
+
+  const walk = async (at: string): Promise<void> => {
+    for (const item of await files.list(at)) {
+      const child = `${at}/${item.name}`;
+      if (item.type === "directory") {
+        await walk(child);
+        continue;
+      }
+      const bytes = await files.readBinary(child);
+      if (bytes !== null) saved.push([child, bytes]);
+    }
+  };
+
+  await walk(path);
+  return saved;
+}

package/src/workspace/git.ts

@@ -0,0 +1,108 @@
+/**
+ * Spawns the `git` binary, so the developer's SSH agent, credential helper and
+ * remote configuration apply. A server-owned clone passes its own environment
+ * instead (`GitRunnerOptions.env`).
+ */
+
+import { execFile } from "node:child_process";
+
+export class GitError extends Error {
+  override name = "GitError";
+  constructor(
+    message: string,
+    readonly stderr: string,
+    readonly exitCode: number | null,
+    /** What Git printed before it failed. A rejected push puts its porcelain lines here. */
+    readonly stdout = "",
+  ) {
+    super(message);
+  }
+}
+
+export interface GitCallOptions {
+  /** Written to Git's stdin, for `--pathspec-from-file=-` and similar. */
+  input?: string;
+  /** Added to the runner's environment for this call only. */
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface GitRunner {
+  /** Runs `git` in the runner's directory. Trimmed stdout, or a `GitError`. */
+  run(args: string[], call?: GitCallOptions): Promise<string>;
+  /** Like `run`, but null instead of a throw — for questions Git may say no to. */
+  tryRun(args: string[], call?: GitCallOptions): Promise<string | null>;
+}
+
+export interface GitRunnerOptions {
+  /**
+   * The whole environment of every `git` call. Defaults to the developer's
+   * (`developerEnvironment`).
+   */
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  maxBuffer?: number;
+}
+
+/**
+ * The developer's own environment. `GIT_TERMINAL_PROMPT=0`: a credential prompt
+ * must fail, not hang the request.
+ */
+export function developerEnvironment(): NodeJS.ProcessEnv {
+  return { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+}
+
+export function gitRunner(cwd: string, options: GitRunnerOptions = {}): GitRunner {
+  const env = options.env ?? developerEnvironment();
+  const run = (args: string[], call: GitCallOptions = {}): Promise<string> =>
+    new Promise((resolve, reject) => {
+      const child = execFile(
+        "git",
+        args,
+        {
+          cwd,
+          env: call.env ? { ...env, ...call.env } : env,
+          timeout: options.timeoutMs ?? 60_000,
+          maxBuffer: options.maxBuffer ?? 10 * 1024 * 1024,
+        },
+        (error, stdout, stderr) => {
+          if (error) {
+            const missing = (error as NodeJS.ErrnoException).code === "ENOENT";
+            reject(
+              new GitError(
+                missing
+                  ? "Git is not installed, or not on the PATH."
+                  : firstLine(stderr) || error.message,
+                stderr,
+                missing ? null : ((error as { code?: number }).code ?? null),
+                stdout,
+              ),
+            );
+            return;
+          }
+          resolve(stdout.replace(/\n$/, ""));
+        },
+      );
+      if (call.input !== undefined) child.stdin?.end(call.input);
+    });
+
+  return {
+    run,
+    async tryRun(args, call) {
+      try {
+        return await run(args, call);
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/** The first non-empty line, where Git puts its verdict. */
+export function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line !== "") ?? ""
+  );
+}

package/src/workspace/locks.ts

@@ -0,0 +1,103 @@
+/**
+ * The two locks of a shared working tree: `remote` (fetch and push, one at a
+ * time) and `tree` (read/write; saves, discards, commits and fast-forwards
+ * write). A save during a commit could otherwise put half an entry into the
+ * commit, and a read during a fast-forward could see a half-written file.
+ *
+ * Both wait, they do not refuse. Take `remote` first, then `tree`, so two
+ * operations never wait on each other. No network call may run while `tree` is
+ * held: a slow push must not block autosave.
+ */
+
+import type { ContentFiles } from "./files.js";
+
+/** Runs one function at a time, in arrival order. */
+export interface Mutex {
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/** Many readers or one writer, in arrival order. A waiting writer holds back later readers. */
+export interface ReadWriteLock {
+  read<T>(fn: () => Promise<T>): Promise<T>;
+  write<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+export interface WorkspaceLocks {
+  remote: Mutex;
+  tree: ReadWriteLock;
+}
+
+export function createWorkspaceLocks(): WorkspaceLocks {
+  return { remote: createMutex(), tree: createReadWriteLock() };
+}
+
+export function createMutex(): Mutex {
+  const lock = createReadWriteLock();
+  return { run: (fn) => lock.write(fn) };
+}
+
+export function createReadWriteLock(): ReadWriteLock {
+  let readers = 0;
+  let writing = false;
+  const queue: Array<{ kind: "read" | "write"; start: () => void }> = [];
+
+  const admit = (): void => {
+    while (queue.length > 0) {
+      const next = queue[0]!;
+      if (next.kind === "write") {
+        if (writing || readers > 0) return;
+        queue.shift();
+        writing = true;
+        next.start();
+        return;
+      }
+      if (writing) return;
+      queue.shift();
+      readers += 1;
+      next.start();
+    }
+  };
+
+  const acquire = (kind: "read" | "write"): Promise<void> =>
+    new Promise((resolve) => {
+      queue.push({ kind, start: resolve });
+      admit();
+    });
+
+  const release = (kind: "read" | "write"): void => {
+    if (kind === "write") writing = false;
+    else readers -= 1;
+    admit();
+  };
+
+  const hold =
+    (kind: "read" | "write") =>
+    async <T>(fn: () => Promise<T>): Promise<T> => {
+      await acquire(kind);
+      try {
+        return await fn();
+      } finally {
+        release(kind);
+      }
+    };
+
+  return { read: hold("read"), write: hold("write") };
+}
+
+/**
+ * Files behind the tree lock. The staging service does not use it: it holds the
+ * lock around whole operations.
+ */
+export function lockedFiles(
+  files: ContentFiles,
+  tree: ReadWriteLock,
+): ContentFiles {
+  return {
+    origin: files.origin,
+    read: (path) => tree.read(() => files.read(path)),
+    list: (path) => tree.read(() => files.list(path)),
+    readBinary: (path) => tree.read(() => files.readBinary(path)),
+    revision: (path) => tree.read(() => files.revision(path)),
+    apply: (input) => tree.write(() => files.apply(input)),
+  };
+}

package/src/workspace/policy.ts

@@ -0,0 +1,77 @@
+/**
+ * What changes with the owner of a working tree: whether Publish may run and
+ * how a commit reaches the remote. The app that keeps a managed clone supplies
+ * its policy; `developer.ts` is the developer's.
+ */
+
+import type { PublishResult } from "@micacms/core";
+
+import type { Author } from "./files.js";
+
+import type { GitTree } from "./tree.js";
+
+export type PublishAvailability = { enabled: true } | { enabled: false; reason: string };
+
+/** One piece of content that an editor changed and the website changed too. */
+export interface SyncConflict {
+  /** Identifies the group in `resolve`. */
+  group: string;
+  label: string;
+  /** Content-relative paths of the group, on either side. */
+  paths: string[];
+  upstream: "changed" | "deleted" | "added";
+  /** What the comparison shows, when the group is one document. */
+  target?: { kind: "entry"; collection: string; slug: string } | { kind: "singleton"; name: string } | { kind: "order"; collection: string };
+}
+
+/** Where a clone that Mica keeps stands against its remote. Managed owners only. */
+export interface SyncStatus {
+  lastSyncAt: string | null;
+  /** Upstream commits not yet in the clone. */
+  behind: number;
+  error: { code: string; message: string; since: string } | null;
+  /** The content model changed upstream; a restart applies it. */
+  restartRequired: boolean;
+  /** A publication committed and not yet pushed. Mica retries it. */
+  pendingPush: { revision: string; reason: string } | null;
+  /** The last publication the host refused; it is a draft again. */
+  refused: { reason: string; at: string } | null;
+  conflicts: SyncConflict[];
+}
+
+/** What the System page says about the repository, beyond what the runtime knows. */
+export interface RepositoryDescription {
+  /** The remote URL, without credentials. */
+  url: string;
+  branch: string;
+  /** Bytes the clone takes on the data volume. */
+  cloneBytes: number | null;
+}
+
+export interface OwnerPolicy {
+  readonly owner: "developer" | "managed";
+  publishAvailability(): PublishAvailability;
+  /**
+   * Runs with the remote lock held, before the tree lock. A managed clone syncs
+   * here and must not take the remote lock again. Throws an `ApiError` when
+   * Publish must wait.
+   */
+  prepare(tree: GitTree): Promise<void>;
+  /** Who a commit names as its author, given the signed-in editor. Undefined leaves it to Git. */
+  commitAuthor(editor: Author | undefined): Author | undefined;
+  /**
+   * Sends HEAD to the remote. A failure returns `committed-pending-push`, not
+   * an exception: the commit is real.
+   */
+  push(tree: GitTree, revision: string): Promise<PublishResult>;
+
+  /* A clone that Mica keeps answers these; the developer's checkout does not. */
+
+  syncStatus?(): SyncStatus;
+  sync?(): Promise<void>;
+  /** Keeps the editor's version of a conflicting group, or takes the website's. */
+  resolve?(group: string, choice: "mine" | "website"): Promise<void>;
+  /** The ref that holds the website's version, for a conflict's comparison. */
+  upstreamRef?: string;
+  describe?(): Promise<RepositoryDescription>;
+}