@kirchdev/duxt 0.10.1-dev-main.5-62e738f → 0.10.1-dev-main.10-e43ad25

package/app/components/DuxtPageInfo.vue

@@ -42,7 +42,8 @@ const props = defineProps<{
 
 const page = computed(() => props.page);
 
-const { source } = useDuxtCollection();
+const { source, sources } = useDuxtCollection();
+const path = useDuxtPath();
 const { locale, t } = useI18n();
 const duxt = useDuxtConfig();
 
@@ -73,6 +74,52 @@ const link = computed(() =>
     : undefined
 );
 
+/**
+ * Where a reader of a TAG edits this page: the same page on the branch the
+ * source also publishes — see `editableEdition` — and only where that edition
+ * still has it, so a page renamed since the tag gets no form on a 404.
+ *
+ * The stem is read off the branch's own row rather than reused from this one:
+ * a numbered folder can move between the two, and the stem is the only thing
+ * that names the file.
+ *
+ * Nothing is read after the `await` but values captured before it — the rule
+ * `tests/async-data-context.test.ts` holds.
+ */
+const { data: editLink } = useAsyncData(
+  () => `duxt-edit-link-${path.value}`,
+  async () => {
+    const own = source.value;
+    const branch = editableEdition(sources.value, own);
+    if (!own || !branch) return null;
+
+    const counterpart = versionPath(
+      path.value,
+      own.prefix,
+      branch.prefix || '/'
+    );
+    const hit = await queryCollection(branch.collection as DuxtCollectionArg)
+      .path(counterpart)
+      .select('stem')
+      .first();
+    if (!hit) return null;
+
+    const target = branch.generated
+      ? branch.path
+      : sourceFilePath(
+          hit.stem,
+          branch.prefix,
+          branch.originPath ?? branch.path
+        );
+
+    return (
+      sourceLink(branch.repositoryUrl, branch.ref, branch.refKind, target) ??
+      null
+    );
+  },
+  { default: () => null, watch: [path] }
+);
+
 /**
  * The day this page names, where it names one.
  *
@@ -130,6 +177,18 @@ const actions = computed(() => {
     });
   }
 
+  // A tag has no edit form of its own, but its branch may — see `editLink`.
+  // Drawn first, beside the tag's own source rather than instead of it: the
+  // reader may want either the text as released or the place to fix it.
+  if (editLink.value) {
+    entries.push({
+      icon: 'lucide:pencil',
+      label: t('duxt.page.edit'),
+      to: editLink.value.url,
+      external: true
+    });
+  }
+
   // A tag has no edit form — see `sourceLink`. The label follows the kind
   // rather than promising a form that answers with a 404.
   if (link.value) {

package/app/types/duxt.d.ts

@@ -287,7 +287,7 @@ declare global {
      * `duxt-typesense@v0.1.0`. Applies to `latest` and `releases`; plain
      * `vX.Y.Z` tags still count.
      */
-    tagComponent?: string;
+    tagComponent?: string | readonly string[];
     /**
      * The repository a source read off disk lives in, for links back to it.
      * Not `repo`, which is what makes Content download a source.

package/app/utils/source-file.ts

@@ -1,3 +1,5 @@
+import { sameArtefact } from './version-choices';
+
 /**
  * From a page back to the file it was written in.
  *
@@ -82,3 +84,34 @@ export function sourceLink(
 
   return undefined;
 }
+
+/**
+ * The edition a reader of a TAG can edit instead: the branch the same source
+ * also publishes.
+ *
+ * `sourceLink` refuses an edit form on a tag, and rightly — but a reader of the
+ * default version is on a tag nearly always, so the refusal alone left the
+ * whole default edition without an edit link. The branch is where a fix to the
+ * page actually lands. Whether the page still EXISTS there is the caller's
+ * question, answered against that edition's collection before the link is
+ * drawn: a file renamed since the tag would otherwise be an edit form on a 404.
+ *
+ * Same repository, same artefact and same language, so a German page of
+ * v0.9.0 is edited as the German page on `main` and an API reference as the
+ * API reference. The first such branch in manifest order wins.
+ */
+export function editableEdition(
+  sources: DuxtResolvedSource[],
+  current: DuxtResolvedSource | undefined
+): DuxtResolvedSource | undefined {
+  if (current?.refKind !== 'tag' || !current.repositoryUrl) return undefined;
+
+  return sources.find(
+    (source) =>
+      source.refKind === 'branch' &&
+      Boolean(source.ref) &&
+      source.repositoryUrl === current.repositoryUrl &&
+      source.locale === current.locale &&
+      sameArtefact(source, current)
+  );
+}

package/build/sources/sources-git.ts

@@ -159,28 +159,54 @@ function tagsFor(source: DuxtSource, what: string): string[] {
 /**
  * The version tags a source may publish from: every tag that reads as a
  * version and belongs to the source's `tagComponent`, when it names one.
+ *
+ * A family of components shares one version line, so one release is often
+ * tagged once per member — `duxt@v0.10.0` beside `duxt-typesense@v0.10.0`.
+ * Those are one version, kept once, from the member listed first.
  */
 function versionTags(
   tags: string[],
-  component: string | undefined
+  component: string | readonly string[] | undefined
 ): { tag: string; version: DuxtVersionTag }[] {
-  return tags
+  const matching = tags
     .map((tag) => ({ tag, version: parseVersionTag(tag) }))
     .filter(
       (entry): entry is { tag: string; version: DuxtVersionTag } =>
         Boolean(entry.version) && tagBelongsTo(entry.version!, component)
     );
+  if (typeof component === 'string' || !component) return matching;
+
+  const rank = (entry: { version: DuxtVersionTag }) =>
+    entry.version.component
+      ? component.indexOf(entry.version.component)
+      : component.length;
+  const byVersion = new Map<string, { tag: string; version: DuxtVersionTag }>();
+  for (const entry of matching) {
+    const key = versionKey(entry.version);
+    const kept = byVersion.get(key);
+    if (!kept || rank(entry) < rank(kept)) byVersion.set(key, entry);
+  }
+  return [...byVersion.values()];
 }
 
+/** One version regardless of who tagged it or whether it carries a `v`. */
+const versionKey = (version: DuxtVersionTag) =>
+  version.numbers.join('.') + (version.pre ? `-${version.pre}` : '');
+
 /** How a source's tag restriction reads in an error, or nothing without one. */
-const componentClause = (source: DuxtSource) =>
-  source.tagComponent ? ` for the component "${source.tagComponent}"` : '';
+const componentClause = (source: DuxtSource) => {
+  const names = source.tagComponent;
+  if (!names || names.length === 0) return '';
+  return typeof names === 'string'
+    ? ` for the component "${names}"`
+    : ` for the components ${names.map((name) => `"${name}"`).join(', ')}`;
+};
 
 /** Tags selected by a source's explicit release policy, newest first. */
 function releaseTags(
   tags: string[],
   releases: DuxtSourceReleases,
-  component: string | undefined
+  component: string | readonly string[] | undefined
 ): string[] {
   const parsed = versionTags(tags, component)
     .filter((entry) => releases.prereleases || !entry.version.pre)

package/build/sources/sources-resolve.ts

@@ -60,8 +60,13 @@ export interface DuxtSource {
    * component tags, and dropping them would unpublish every earlier release.
    *
    * Unset, every tag that reads as a version is a candidate, prefixed or not.
+   *
+   * A LIST names a family released on one version line — the layer and its
+   * companion layers under `versioning: linked` — so `latest` and `releases`
+   * follow whichever of them released last. One version carried by several
+   * of them is one release, published from the tag of the name listed first.
    */
-  tagComponent?: string;
+  tagComponent?: string | readonly string[];
   /**
    * Languages this source is available in, beyond the one written in `path`.
    *
@@ -964,9 +969,12 @@ export const versionTagName = (tag: string): string =>
  */
 export function tagBelongsTo(
   tag: DuxtVersionTag,
-  component: string | undefined
+  component: string | readonly string[] | undefined
 ): boolean {
-  return !component || !tag.component || tag.component === component;
+  if (!component || !tag.component) return true;
+  return typeof component === 'string'
+    ? tag.component === component
+    : component.includes(tag.component);
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@kirchdev/duxt",
-  "version": "0.10.1-dev-main.5-62e738f",
+  "version": "0.10.1-dev-main.10-e43ad25",
   "description": "duxt is a Nuxt layer: extend it and your docs/ folder becomes a site, with theme, search, API reference and llms.txt included. Point it at other repositories, or at tags of the same one, and each becomes a version.",
   "keywords": [
     "content-v3",

package/server/plugins/content-import-lifetime.ts

@@ -0,0 +1,45 @@
+/**
+ * Keeps a request alive on Cloudflare until it has produced its response, even
+ * after the reader has gone.
+ *
+ * Content restores a collection into D1 the first time a request reads it
+ * after a deploy: it writes the collection's `_content_info` row with
+ * `ready = 0`, replays the dump one statement at a time — about ten seconds a
+ * collection on duxt.app — and flips the row to ready as the last statement.
+ * A Worker CANCELS a request's work the moment its client disconnects. A
+ * reader who gives up, a crawler with a timeout, a prefetch the router drops:
+ * any of them stops that replay halfway, and the row is never flipped. Every
+ * later read of that collection then waits on `ready` for 90 seconds and
+ * fails, on every isolate, until `content-restore-recovery.ts` clears the row —
+ * and a docs page reads every version's collection to draw its version
+ * switcher, so one stuck collection hangs every page of every version.
+ * duxt.app ran into exactly that after the v0.10.0 deploy.
+ *
+ * `waitUntil` is the one thing a Worker lets outlive a disconnect, so every
+ * request hands it a promise that settles when the request is done. Anything
+ * it started — the restore included — then runs to completion inside the
+ * platform's grace period rather than being cut off. Other runtimes do not
+ * cancel on disconnect, so this only arms where `cloudflare` is in the context.
+ */
+const settle = Symbol('duxt.settle');
+
+type Settling = { [settle]?: () => void };
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('request', (event) => {
+    if (!event.context.cloudflare || !event.waitUntil) return;
+
+    event.waitUntil(
+      new Promise<void>((resolve) => {
+        (event.context as Settling)[settle] = resolve;
+      })
+    );
+  });
+
+  const done = (event: { context: Settling } | undefined) => {
+    event?.context[settle]?.();
+  };
+
+  nitroApp.hooks.hook('afterResponse', (event) => done(event));
+  nitroApp.hooks.hook('error', (_error, { event }) => done(event));
+});

package/server/plugins/content-restore-recovery.ts

@@ -0,0 +1,65 @@
+import {
+  duxtRecoverContentRestores,
+  type DuxtD1
+} from '../utils/content-restore';
+
+/**
+ * Clears Content restores a cancelled Worker left half done, from inside the
+ * Worker, on D1.
+ *
+ * `content-import-lifetime.ts` keeps a restore running past a disconnect, but
+ * only for the platform's grace period, and a row that was stranded before it
+ * — or by a deploy that cut a running restore off — stays unready for good:
+ * every read of that collection then waits 90 seconds and fails, and a docs
+ * page reads every version's collection to draw its switcher. duxt.app sat
+ * like that after the v0.10.0 deploy until the row was removed by hand.
+ *
+ * It runs here rather than in the deploy because the Worker is the one thing
+ * that already holds the binding: a cleanup step in CI would need a token with
+ * D1 rights for every repository that reads it, and would help no site but the
+ * one whose workflow carries it.
+ *
+ * At most once a minute per isolate, after the response, so no reader waits on
+ * it. A failure is logged and dropped: this is a repair, and a missing table
+ * on a fresh database is not an error.
+ */
+const INTERVAL_MS = 60_000;
+
+let last = 0;
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('request', (event) => {
+    const env = event.context.cloudflare?.env as
+      | Record<string, unknown>
+      | undefined;
+    if (!env || !event.waitUntil) return;
+
+    const database = useRuntimeConfig(event).content?.database as
+      | { type?: string; bindingName?: string; binding?: string }
+      | undefined;
+    if (database?.type !== 'd1') return;
+
+    const db = env[database.bindingName || database.binding || 'DB'] as
+      | DuxtD1
+      | undefined;
+    if (!db) return;
+
+    const now = Date.now();
+    if (now - last < INTERVAL_MS) return;
+    last = now;
+
+    event.waitUntil(
+      duxtRecoverContentRestores(db, now)
+        .then((removed) => {
+          if (removed.length) {
+            console.warn(
+              `[duxt] cleared abandoned Content restores: ${removed.join(', ')}`
+            );
+          }
+        })
+        .catch((error) => {
+          console.warn('[duxt] Content restore check failed', error);
+        })
+    );
+  });
+});

package/server/utils/content-restore.ts

@@ -0,0 +1,91 @@
+/**
+ * The part of a D1 binding this file uses — written out rather than imported,
+ * because the layer does not depend on Cloudflare's types and no other
+ * runtime ever reaches this code.
+ */
+export interface DuxtD1 {
+  prepare(sql: string): DuxtD1Statement;
+  batch(statements: DuxtD1Statement[]): Promise<unknown>;
+}
+
+export interface DuxtD1Statement {
+  bind(...values: unknown[]): DuxtD1Statement;
+  all<T>(): Promise<{ results: T[] }>;
+  run(): Promise<unknown>;
+}
+
+/**
+ * Twice the 90 seconds Content waits for another restore before giving up.
+ * A restore takes about ten seconds a collection on duxt.app, so a row still
+ * unready after this has nobody left writing it.
+ */
+export const DUXT_STALE_RESTORE_MS = 180_000;
+
+/** Where a row was first seen unready. Content owns `_content_info`; this is ours. */
+const SEEN = '_duxt_content_unready';
+
+/**
+ * Removes every Content restore that was abandoned halfway, so the next read
+ * of that collection restores it again instead of waiting on it forever.
+ *
+ * Content marks a collection `ready = 0` in `_content_info`, replays its dump
+ * and flips the row as the dump's last statement. A Worker cancelled before
+ * that statement leaves the row unready for good, and every later read waits
+ * 90 seconds and fails — see `server/plugins/content-restore-recovery.ts`.
+ *
+ * The row carries no timestamp, and an unready row is also exactly what a
+ * restore IN PROGRESS looks like, so a single look cannot tell the two apart.
+ * Two looks can: the first records when a row was seen unready, and a later
+ * one removes it only if the SAME version is still unready past the threshold.
+ * A new deploy writes a new version, which starts the clock again.
+ *
+ * Returns the ids it removed.
+ */
+export async function duxtRecoverContentRestores(
+  db: DuxtD1,
+  now: number,
+  staleMs = DUXT_STALE_RESTORE_MS
+): Promise<string[]> {
+  const unready = await db
+    .prepare('SELECT id, version FROM _content_info WHERE ready = 0')
+    .all<{ id: string; version: string }>();
+
+  await db.batch([
+    db.prepare(
+      `CREATE TABLE IF NOT EXISTS ${SEEN} (id TEXT PRIMARY KEY, version TEXT NOT NULL, since INTEGER NOT NULL)`
+    ),
+    // A row that finished, or that Content replaced, is forgotten — otherwise
+    // its old clock would condemn the next restore of the same version.
+    db.prepare(
+      `DELETE FROM ${SEEN} WHERE NOT EXISTS (SELECT 1 FROM _content_info AS info WHERE info.id = ${SEEN}.id AND info.version = ${SEEN}.version AND info.ready = 0)`
+    ),
+    ...unready.results.map((row) =>
+      db
+        .prepare(
+          `INSERT INTO ${SEEN} (id, version, since) VALUES (?, ?, ?) ON CONFLICT (id) DO NOTHING`
+        )
+        .bind(row.id, row.version, now)
+    )
+  ]);
+
+  const stale = await db
+    .prepare(`SELECT id, version FROM ${SEEN} WHERE since <= ?`)
+    .bind(now - staleMs)
+    .all<{ id: string; version: string }>();
+  if (!stale.results.length) return [];
+
+  // `ready = 0` and the version in the condition: a restore that finished, or
+  // a deploy that replaced the row, since the look above keeps its row.
+  await db.batch(
+    stale.results.flatMap((row) => [
+      db
+        .prepare(
+          'DELETE FROM _content_info WHERE id = ? AND version = ? AND ready = 0'
+        )
+        .bind(row.id, row.version),
+      db.prepare(`DELETE FROM ${SEEN} WHERE id = ?`).bind(row.id)
+    ])
+  );
+
+  return stale.results.map((row) => row.id);
+}