@micacms/runtime 0.6.0 → 0.7.0

package/src/routes/admin-media.ts

@@ -1,14 +1,45 @@
 /**
- * Admin media routes. Media is files in the content repository, and there is no delete endpoint.
- * An upload is written on its own, before the entry save, because the editor needs its path first.
+ * Admin media routes. Media is files in the content repository. An upload is
+ * written on its own, before the entry save, because the editor needs its path
+ * first. A delete is a pending change like any other, and is refused while
+ * something uses the file.
  */
 
+import { contentPath, ContentPathError, MEDIA_DIR } from "@micacms/core";
 import { Hono } from "hono";
+import { z } from "zod";
 
 import { ApiError, badRequest, notFound } from "../lib/errors.js";
 import { isImageType } from "../lib/file-type.js";
 import { MAX_FILES_PER_UPLOAD } from "../middleware/index.js";
-import type { Env } from "../http.js";
+import { editorOf, type Env } from "../http.js";
+import type { Referrer } from "../services/content-store.js";
+
+const deleteSchema = z.object({ paths: z.array(z.string().min(1)).min(1).max(500) });
+
+/** Content paths, or a 400 for one that leaves the content root. */
+function cleanPaths(paths: string[]): string[] {
+  try {
+    return [...new Set(paths.map((path) => contentPath(path)))];
+  } catch (error) {
+    if (error instanceof ContentPathError) throw badRequest(error.message);
+    throw error;
+  }
+}
+
+/** A file in a `media/` folder, as an upload writes it. Nothing else is deleted here. */
+function mediaFilesOnly(paths: string[]): string[] {
+  for (const path of paths) {
+    if (path.split("/").at(-2) !== MEDIA_DIR) throw badRequest(`"${path}" is not a media file.`);
+  }
+  return paths;
+}
+
+function describeUses(path: string, referrers: Referrer[]): string {
+  const names = referrers.map((item) => item.title);
+  const listed = names.slice(0, 3).join(", ") + (names.length > 3 ? ` and ${names.length - 3} more` : "");
+  return `"${path.split("/").at(-1)}" is still used by ${listed}. Remove it there first.`;
+}
 
 export function adminMediaRoutes(): Hono<Env> {
   const app = new Hono<Env>();
@@ -18,6 +49,39 @@ export function adminMediaRoutes(): Hono<Env> {
     return c.json({ items: await media.list() });
   });
 
+  /** Where files are used, before a delete: `?path=a&path=b`. */
+  app.get("/usage", async (c) => {
+    const { content } = c.get("ctx").services;
+    const paths = cleanPaths(c.req.queries("path") ?? []);
+    if (paths.length === 0) throw badRequest("Name at least one file.");
+    return c.json(await content.mediaUses(paths));
+  });
+
+  app.post("/delete", async (c) => {
+    const ctx = c.get("ctx");
+    const parsed = deleteSchema.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw badRequest("Expected a list of file paths.");
+    const paths = mediaFilesOnly(cleanPaths(parsed.data.paths));
+
+    for (const path of paths) {
+      const owner = path.split("/")[0] ?? "";
+      const readOnly = ctx.site.readOnly.get(`collections.${owner}`) ?? ctx.site.readOnly.get(`singletons.${owner}`);
+      if (readOnly) throw new ApiError("conflict", readOnly);
+      if ((await ctx.services.media.read(path)) === null) throw notFound(`There is no file "${path}".`);
+    }
+
+    const { uses, unreadable } = await ctx.services.content.mediaUses(paths);
+    if (unreadable.length > 0) {
+      throw new ApiError("conflict", `Mica cannot read ${unreadable.join(", ")}, so it cannot tell whether these files are used.`);
+    }
+    const used = paths.filter((path) => (uses[path] ?? []).length > 0);
+    if (used.length > 0) throw new ApiError("conflict", used.map((path) => describeUses(path, uses[path]!)).join(" "));
+
+    await ctx.site.contentRepository.apply({ changes: paths.map((path) => ({ type: "delete" as const, path })) });
+    ctx.logger.info("Deleted media", { paths, editor: editorOf(c) });
+    return c.json({ deleted: paths });
+  });
+
   app.post("/", async (c) => {
     const ctx = c.get("ctx");
     const form = await c.req.formData().catch(() => {
@@ -41,6 +105,13 @@ export function adminMediaRoutes(): Hono<Env> {
     const owner = (directory ?? "").replace(/^[/\\]+/, "").split(/[/\\]/)[0] ?? "";
     const readOnly = ctx.site.readOnly.get(`collections.${owner}`) ?? ctx.site.readOnly.get(`singletons.${owner}`);
     if (readOnly) throw new ApiError("conflict", readOnly);
+    // A new entry uploads into the folder of the URL in its form; never into a saved entry's.
+    const folder = /^([^/]+)\/([^/]+)\/media$/.exec((directory ?? "").replace(/^\/+/, ""));
+    if (form.get("newEntry") === "true" && folder && ctx.site.model.collections[folder[1]!]) {
+      if ((await ctx.services.content.revisionOf(folder[1]!, folder[2]!)) !== null) {
+        throw new ApiError("conflict", `Another entry already has the URL “${folder[2]}”. Change the URL, then upload.`);
+      }
+    }
 
     const prepared = await Promise.all(
       files.map((file) =>

package/src/routes/admin-staging.ts

@@ -8,7 +8,7 @@
 import { Hono } from "hono";
 import { z } from "zod";
 
-import { actorOf, type Env } from "../http.js";
+import { actorOf, editorOf, type Env } from "../http.js";
 import { ApiError, badRequest } from "../lib/errors.js";
 import { ConflictError } from "../workspace/files.js";
 
@@ -52,12 +52,17 @@ async function handled<T>(run: () => Promise<T>): Promise<T> {
   }
 }
 
+/** Which model is in use, so that the editor can tell a stale form, and why a newer one is not. */
+function modelState(ctx: Env["Variables"]["ctx"]) {
+  return { revision: ctx.site.schemaRevision, warning: ctx.site.modelWarning?.message ?? null };
+}
+
 export function adminStagingRoutes(): Hono<Env> {
   const app = new Hono<Env>();
 
   app.get("/changes", async (c) => {
-    const { staging } = c.get("ctx").services;
-    return c.json(await staging.status());
+    const ctx = c.get("ctx");
+    return c.json({ ...(await ctx.services.staging.status()), model: modelState(ctx) });
   });
 
   // Raw data before and after one pending change; the editor renders the comparison.
@@ -77,6 +82,15 @@ export function adminStagingRoutes(): Hono<Env> {
   });
 
   app.post("/publish", async (c) => {
+    // Publish validates with the newest model, so a model change never needs a restart first.
+    await c.get("ctx").refreshModel({ force: true });
+    const warning = c.get("ctx").site.modelWarning;
+    if (warning) {
+      throw new ApiError(
+        "conflict",
+        `The website's new content model cannot be read, so Mica cannot publish yet. Tell the developer: ${warning.message}`,
+      );
+    }
     const { staging } = c.get("ctx").services;
     const parsed = publishSchema.safeParse(await jsonBody(c));
     if (!parsed.success) throw badRequest("The publish payload is malformed.");
@@ -87,6 +101,7 @@ export function adminStagingRoutes(): Hono<Env> {
         message: parsed.data.message,
         paths: parsed.data.paths,
         author: actor ? { name: actor.name || actor.email, email: actor.email } : undefined,
+        editor: editorOf(c),
       }),
     );
 
@@ -102,7 +117,7 @@ export function adminStagingRoutes(): Hono<Env> {
   app.post("/sync", async (c) => {
     const { staging } = c.get("ctx").services;
     await staging.sync();
-    return c.json(await staging.status());
+    return c.json({ ...(await staging.status()), model: modelState(c.get("ctx")) });
   });
 
   app.post("/changes/resolve", async (c) => {
@@ -110,8 +125,8 @@ export function adminStagingRoutes(): Hono<Env> {
     const parsed = resolveSchema.safeParse(await jsonBody(c));
     if (!parsed.success) throw badRequest("Expected a group and a choice: mine or website.");
 
-    await handled(() => staging.resolve(parsed.data.group, parsed.data.choice));
-    return c.json(await staging.status());
+    await handled(() => staging.resolve(parsed.data.group, parsed.data.choice, editorOf(c)));
+    return c.json({ ...(await staging.status()), model: modelState(c.get("ctx")) });
   });
 
   app.post("/changes/discard", async (c) => {
@@ -119,7 +134,7 @@ export function adminStagingRoutes(): Hono<Env> {
     const parsed = discardSchema.safeParse(await jsonBody(c));
     if (!parsed.success) throw badRequest("Expected a list of change paths.");
 
-    return c.json(await handled(() => staging.discard(parsed.data.paths)));
+    return c.json(await handled(() => staging.discard(parsed.data.paths, editorOf(c))));
   });
 
   return app;

package/src/routes/admin-system.ts

@@ -41,6 +41,8 @@ export function adminSystemRoutes(): Hono<Env> {
         fields: def.fields,
         readOnly: site.readOnly.get(`singletons.${def.name}`) ?? null,
       })),
+      /** Which model this is, so that a page can tell that a newer one is in use. */
+      revision: site.schemaRevision,
     });
   });
 
@@ -113,6 +115,8 @@ export function adminSystemRoutes(): Hono<Env> {
           entries: counts[item.name] ?? 0,
         })),
         singletons: stats.singletons,
+        /** Why a newer model in the working tree is not in use, or null. */
+        warning: ctx.site.modelWarning?.message ?? null,
       },
       repository: {
         origin: ctx.site.contentRepository.origin,

package/src/services/changes.ts

@@ -28,6 +28,7 @@ import {
 
 import { badRequest } from "../lib/errors.js";
 import type { SyncStatus } from "../workspace/policy.js";
+import type { UnpushedCommits } from "../workspace/tree.js";
 
 /** Where the change happened, in words an editor recognises. */
 export type ChangeOwner =
@@ -51,6 +52,13 @@ export interface AnnotatedChange extends ContentChange {
    * saved after the review is not published unseen.
    */
   revision?: string | null;
+  /** When the file was last saved, for "changed 2 hours ago". Null for a deletion. */
+  savedAt?: string | null;
+  /**
+   * New pending files that this document uses (a linked entry, an image), so
+   * that it cannot be published without them. On the document's data file.
+   */
+  needs?: string[];
 }
 
 /** One thing that would make the staged result unpublishable. */
@@ -74,8 +82,12 @@ export interface StagingStatus {
   head: string | null;
   /** The branch a publication lands on, where the workspace knows it. */
   branch: string | null;
-  /** Commits created and not yet pushed. */
-  ahead: number | null;
+  /**
+   * Commits that no remote has, in the developer's checkout: Mica's waits for a
+   * retry, another one blocks Publish. Null for a clone that Mica keeps, or
+   * without a remote.
+   */
+  unpushed: UnpushedCommits | null;
   changes: AnnotatedChange[];
   validation: StagingValidation;
   /** Where a clone that Mica keeps stands against its remote. Null for the developer's checkout. */
@@ -92,6 +104,8 @@ export interface PublishInput {
    */
   paths: Record<string, string | null>;
   author?: Author;
+  /** Who published, for the log. */
+  editor?: string;
 }
 
 /** What the System page shows about the repository. */
@@ -108,7 +122,8 @@ export interface RepositoryInfo {
 export interface ContentStagingService {
   status(): Promise<StagingStatus>;
   publish(input: PublishInput): Promise<PublishResult>;
-  discard(paths: string[]): Promise<{ discarded: string[] }>;
+  /** `editor` names who discarded, for the log. */
+  discard(paths: string[], editor?: string): Promise<{ discarded: string[] }>;
   /** Retries the push after `committed-pending-push`. */
   push(): Promise<PublishResult>;
   /**
@@ -118,7 +133,7 @@ export interface ContentStagingService {
   compare(target: CompareTarget, against?: "head" | "origin"): Promise<Comparison>;
   /** Brings a clone that Mica keeps up to date now. Refused for the developer's checkout. */
   sync(): Promise<void>;
-  resolve(group: string, choice: "mine" | "website"): Promise<void>;
+  resolve(group: string, choice: "mine" | "website", editor?: string): Promise<void>;
   repository(): Promise<RepositoryInfo>;
 }
 
@@ -240,6 +255,21 @@ export async function analyseChanges(
     await detectRenames(model, published, source, changes, owners, entriesByCollection);
   }
 
+  const created = new Set(changes.filter((change) => change.kind === "create").map((change) => change.path));
+  const needsByPath = new Map<string, string[]>();
+  /** How to read each changed document as the website has it, by its data file. */
+  const publishedOf = new Map<string, () => Promise<Record<string, unknown> | null>>();
+  const addNeeds = (dataPath: string, fields: Collection["fields"], data: Record<string, unknown>): void => {
+    const needed = new Set<string>();
+    for (const reference of collectReferences(fields, data)) {
+      const def = reference.kind === "relation" ? model.collections[reference.collection] : undefined;
+      const path =
+        reference.kind === "media" ? reference.path : def ? entryDataPath(def, reference.collection, reference.slug) : null;
+      if (path && path !== dataPath && created.has(path)) needed.add(path);
+    }
+    if (needed.size > 0) needsByPath.set(dataPath, [...needed]);
+  };
+
   const validated = new Set<string>();
   const targets = createReferenceCheck(model, source, (name) => {
     const entries = entriesByCollection.get(name);
@@ -257,6 +287,11 @@ export async function analyseChanges(
       const data = entriesByCollection.get(owner.collection)?.get(owner.slug);
       if (!data) continue;
 
+      addNeeds(entryDataPath(def, owner.collection, owner.slug), def.fields, data);
+      if (published) {
+        const { collection, slug } = owner;
+        publishedOf.set(entryDataPath(def, collection, slug), () => readCollectionEntry(published, def, collection, slug).catch(() => null));
+      }
       const result = validateFields(def.fields, data);
       const issues = [...(result.ok ? [] : result.issues), ...(await targets.issues(def.fields, data))];
       if (issues.length > 0) {
@@ -277,6 +312,13 @@ export async function analyseChanges(
         const data = await readSingleton(source, def, owner.name);
         if (data === null) continue;
 
+        // The data file, not the folder: a folder-layout singleton's change is `<name>/index.json`.
+        const dataFile = entryLayout(def.fields) === "directory" ? `${dataPath}/index.json` : dataPath;
+        addNeeds(dataFile, def.fields, data);
+        if (published) {
+          const name = owner.name;
+          publishedOf.set(dataFile, () => readSingleton(published, def, name).catch(() => null));
+        }
         const result = validateFields(def.fields, data);
         const issues = [...(result.ok ? [] : result.issues), ...(await targets.issues(def.fields, data))];
         if (issues.length > 0) problems.push({ path: dataPath, label: def.label, issues });
@@ -290,18 +332,47 @@ export async function analyseChanges(
     }
   }
 
+  // A URL change and the links that follow it are published together, both ways. A
+  // document follows when the website's version of it links to the old URL; a new
+  // draft that links to the new URL only needs the change, and does not hold it back.
+  const renamed = new Map(
+    owners.flatMap((owner) =>
+      owner.kind === "entry" && owner.renamedFrom
+        ? [[entryDataPath(model.collections[owner.collection]!, owner.collection, owner.slug), owner] as const]
+        : [],
+    ),
+  );
+  for (const [document, needed] of [...needsByPath]) {
+    for (const path of needed) {
+      const target = renamed.get(path);
+      if (!target || target.kind !== "entry") continue;
+      const before = await publishedOf.get(document)?.();
+      const fields = before && fieldsOfDocument(model, document);
+      const linkedBefore =
+        before &&
+        fields &&
+        collectReferences(fields, before).some(
+          (reference) => reference.kind === "relation" && reference.collection === target.collection && reference.slug === target.renamedFrom,
+        );
+      if (linkedBefore) needsByPath.set(path, [...new Set([...(needsByPath.get(path) ?? []), document])]);
+    }
+  }
+
   problems.push(...(await brokenByRemoval(model, source, changes, owners, entriesByCollection, titles)));
 
   const annotated = changes.map((change, index): AnnotatedChange => {
     const owner = owners[index]!;
+    const needs = needsByPath.get(change.path);
+    const extra = needs ? { needs } : {};
     if (owner.kind === "entry") {
       const def = model.collections[owner.collection]!;
       return {
         ...change,
+        ...extra,
         owner: { ...owner, label: labelEntry(def, owner.slug, titles.get(`${owner.collection}/${owner.slug}`)) },
       };
     }
-    return { ...change, owner };
+    return { ...change, ...extra, owner };
   });
 
   return {
@@ -310,6 +381,14 @@ export async function analyseChanges(
   };
 }
 
+/** The fields of the entry or singleton whose data file is `path`. */
+function fieldsOfDocument(model: Site, path: string): Collection["fields"] | null {
+  const owner = classifyPath(model, path);
+  if (owner.kind === "entry") return model.collections[owner.collection]?.fields ?? null;
+  if (owner.kind === "singleton") return model.singletons[owner.name]?.fields ?? null;
+  return null;
+}
+
 /** Which piece of content a file belongs to, read from the model's path layout. */
 export function classifyPath(model: Site, path: string): ChangeOwner {
   const segments = path.split("/");