@jant/core 0.6.14 → 0.6.15

package/src/lib/api-settings.ts

@@ -1,31 +1,258 @@
-import { CONFIG_FIELDS, type ConfigKey } from "../types.js";
+import {
+  CONFIG_FIELDS,
+  type Bindings,
+  type ConfigEditorDefinition,
+  type ConfigEditorFieldState,
+  type ConfigEditorKey,
+  type ConfigEditorResettableKey,
+  type ConfigEditorVisibleKey,
+  type ConfigKey,
+} from "../types.js";
+import { getSupportedLocaleEntries } from "../i18n/supported-locales.js";
 import { SETTINGS_KEYS } from "./constants.js";
-import { normalizeTimeZone } from "./timezones.js";
+import { getEnvString } from "./env.js";
+import { normalizeEditableSettingValue } from "./schemas.js";
+import { getTimeZoneOptions } from "./timezones.js";
 
 export const demoLockedSettingKeys = new Set<ConfigKey>(["NOINDEX"]);
 
-/** Config keys that can be modified via the settings API */
+/** Config keys explicitly approved for runtime editing. */
 export const editableSettingKeys = Object.entries(CONFIG_FIELDS)
+  .filter(([, field]) => "editor" in field)
+  .map(([key]) => key as ConfigEditorKey);
+
+/** Safe settings shown in Config Editor, including dedicated-page links. */
+export const configEditorVisibleKeys = Object.entries(CONFIG_FIELDS)
+  .filter(([, field]) => "editor" in field || "configEditorLink" in field)
+  .map(([key]) => key as ConfigEditorVisibleKey);
+
+/** Config Editor keys whose DB override can be safely removed directly. */
+export const resettableConfigEditorKeys = Object.entries(CONFIG_FIELDS)
   .filter(
-    ([, field]) => !field.envOnly && !("internal" in field && field.internal),
+    ([, field]) =>
+      "editor" in field ||
+      ("configEditorLink" in field &&
+        "resettable" in field.configEditorLink &&
+        field.configEditorLink.resettable === true),
   )
-  .map(([key]) => key as ConfigKey);
+  .map(([key]) => key as ConfigEditorResettableKey);
+
+export function isEditableSettingKey(key: string): key is ConfigEditorKey {
+  return editableSettingKeys.includes(key as ConfigEditorKey);
+}
+
+export function isResettableConfigEditorKey(
+  key: string,
+): key is ConfigEditorResettableKey {
+  return resettableConfigEditorKeys.includes(key as ConfigEditorResettableKey);
+}
+
+function tryNormalizeResolvedSettingValue(
+  key: ConfigEditorKey,
+  value: string,
+): string | undefined {
+  try {
+    return normalizeEditableSettingValue(key, value);
+  } catch {
+    return undefined;
+  }
+}
+
+export function getEditableSettingFallbackValue(
+  key: ConfigEditorKey,
+  env?: Bindings,
+  allSettings: Record<string, string> = {},
+): string {
+  const field = CONFIG_FIELDS[key];
+  const envKeys = "envKeys" in field ? field.envKeys : undefined;
+  const envValue = env ? getEnvString(env, ...(envKeys ?? [])) : undefined;
+  if (envValue) {
+    const normalizedEnv = tryNormalizeResolvedSettingValue(key, envValue);
+    if (normalizedEnv !== undefined) return normalizedEnv;
+  }
+
+  const normalizedDefault = tryNormalizeResolvedSettingValue(
+    key,
+    field.defaultValue,
+  );
+  if (normalizedDefault !== undefined) return normalizedDefault;
+
+  if ("fallbackKey" in field && field.fallbackKey) {
+    return getEditableSettingValue(allSettings, field.fallbackKey, env);
+  }
+
+  throw new Error(`Missing valid Config Editor fallback for ${key}`);
+}
 
 export function getEditableSettingValue(
   allSettings: Record<string, string>,
-  key: ConfigKey,
+  key: ConfigEditorKey,
+  env?: Bindings,
 ): string {
-  const value = allSettings[key] ?? CONFIG_FIELDS[key].defaultValue;
-  return key === SETTINGS_KEYS.TIME_ZONE ? normalizeTimeZone(value) : value;
+  const fallbackValue = getEditableSettingFallbackValue(key, env, allSettings);
+  const value = Object.hasOwn(allSettings, key)
+    ? allSettings[key]
+    : fallbackValue;
+  return (
+    tryNormalizeResolvedSettingValue(key, value ?? fallbackValue) ??
+    fallbackValue
+  );
+}
+
+function getEditorConstraints(
+  key: ConfigEditorKey,
+  definition: ConfigEditorDefinition,
+  value: string,
+  fallbackValue: string,
+): Pick<
+  ConfigEditorFieldState,
+  "maxLength" | "min" | "max" | "step" | "options"
+> {
+  switch (definition.type) {
+    case "boolean":
+      return {};
+    case "string":
+      return { maxLength: definition.maxLength };
+    case "number":
+      return {
+        min: definition.min,
+        max: definition.max,
+        step: definition.step,
+      };
+    case "enum":
+      if (definition.options) return { options: definition.options };
+      if (definition.optionsSource === "contentLanguage") {
+        const options = getSupportedLocaleEntries().map((entry) => entry.tag);
+        for (const candidate of [fallbackValue, value]) {
+          if (candidate && !options.includes(candidate))
+            options.push(candidate);
+        }
+        return { options };
+      }
+      if (definition.optionsSource === "timeZone") {
+        const options = getTimeZoneOptions(value).map((entry) => entry.value);
+        for (const candidate of [fallbackValue, value]) {
+          if (candidate && !options.includes(candidate))
+            options.push(candidate);
+        }
+        return { options };
+      }
+      return { options: [value] };
+  }
+}
+
+function buildLinkedConfigEditorField(
+  allSettings: Record<string, string>,
+  env: Bindings,
+  key: ConfigEditorVisibleKey,
+): ConfigEditorFieldState {
+  const field = CONFIG_FIELDS[key];
+  if (!("configEditorLink" in field)) {
+    throw new Error(`Missing Config Editor link metadata for ${key}`);
+  }
+  const definition = field.configEditorLink;
+  const resettable =
+    "resettable" in definition && definition.resettable === true;
+  const modified = Object.hasOwn(allSettings, key);
+  const storedValue = allSettings[key] ?? "";
+
+  if (definition.display === "configured") {
+    const envKeys = "envKeys" in field ? field.envKeys : [];
+    const fallbackRawValue =
+      getEnvString(env, ...envKeys) || field.defaultValue;
+    const effectiveValue = modified ? storedValue : fallbackRawValue;
+    return {
+      key,
+      mode: "link",
+      type: definition.type,
+      value: effectiveValue.trim() ? "true" : "false",
+      fallbackValue: fallbackRawValue.trim() ? "true" : "false",
+      modified,
+      locked: false,
+      settingsPath: definition.settingsPath,
+      display: definition.display,
+      ...(resettable && { resettable: true }),
+    };
+  }
+
+  const fieldEnvKeys = "envKeys" in field ? field.envKeys : [];
+  let fallbackValue: string =
+    ("fallbackValue" in definition ? definition.fallbackValue : undefined) ??
+    getEnvString(env, ...fieldEnvKeys) ??
+    field.defaultValue;
+  if ("fallbackKey" in definition && definition.fallbackKey) {
+    const fallbackField = CONFIG_FIELDS[definition.fallbackKey];
+    const envKeys = "envKeys" in fallbackField ? fallbackField.envKeys : [];
+    fallbackValue = getEnvString(env, ...envKeys) || fallbackField.defaultValue;
+  }
+  const value = storedValue.trim() || fallbackValue;
+
+  return {
+    key,
+    mode: "link",
+    type: definition.type,
+    value: definition.type === "boolean" ? String(value === "true") : value,
+    fallbackValue,
+    modified,
+    locked: false,
+    settingsPath: definition.settingsPath,
+    display: definition.display,
+    ...(resettable && { resettable: true }),
+  };
+}
+
+export function buildConfigEditorFields(
+  allSettings: Record<string, string>,
+  env: Bindings,
+  demoMode: boolean,
+): ConfigEditorFieldState[] {
+  return configEditorVisibleKeys.map((key) => {
+    if ("configEditorLink" in CONFIG_FIELDS[key]) {
+      return buildLinkedConfigEditorField(allSettings, env, key);
+    }
+
+    if (!isEditableSettingKey(key)) {
+      throw new Error(`Missing Config Editor metadata for ${key}`);
+    }
+
+    const definition: ConfigEditorDefinition = CONFIG_FIELDS[key].editor;
+    const fallbackValue = getEditableSettingFallbackValue(
+      key,
+      env,
+      allSettings,
+    );
+    const value =
+      demoMode && key === SETTINGS_KEYS.NOINDEX
+        ? "true"
+        : getEditableSettingValue(allSettings, key, env);
+    const fallbackKey = (CONFIG_FIELDS[key] as { fallbackKey?: "PAGE_SIZE" })
+      .fallbackKey;
+    const base = {
+      key,
+      mode: "edit" as const,
+      type: definition.type,
+      value,
+      fallbackValue,
+      modified: Object.hasOwn(allSettings, key),
+      locked: demoMode && demoLockedSettingKeys.has(key),
+      ...(fallbackKey ? { fallbackKey } : {}),
+    };
+
+    return {
+      ...base,
+      ...getEditorConstraints(key, definition, value, fallbackValue),
+    };
+  });
 }
 
 export function buildEditableSettingsResponse(
   allSettings: Record<string, string>,
   demoMode: boolean,
+  env?: Bindings,
 ): Record<string, string> {
   const result: Record<string, string> = {};
   for (const key of editableSettingKeys) {
-    result[key] = getEditableSettingValue(allSettings, key);
+    result[key] = getEditableSettingValue(allSettings, key, env);
   }
   if (demoMode) {
     result.NOINDEX = "true";
@@ -38,14 +265,14 @@ export function partitionEditableSettingUpdates(
   updates: Record<string, string>,
   demoMode: boolean,
 ): {
-  filteredUpdates: Partial<Record<ConfigKey, string>>;
+  filteredUpdates: Partial<Record<ConfigEditorKey, string>>;
   rejectedKeys: string[];
 } {
-  const filteredUpdates: Partial<Record<ConfigKey, string>> = {};
+  const filteredUpdates: Partial<Record<ConfigEditorKey, string>> = {};
   const rejectedKeys: string[] = [];
 
   for (const [key, value] of Object.entries(updates)) {
-    const configKey = key as ConfigKey;
+    const configKey = key as ConfigEditorKey;
 
     if (
       demoMode &&

package/src/lib/collection-sort.ts

@@ -18,9 +18,9 @@ export function isRatingSortOrder(
 }
 
 /**
- * Returns true when a collection has enough rated posts to make rating sort useful.
+ * Returns true when a collection has enough rated Threads to make rating sort useful.
  *
- * @param ratedPostCount - Number of posts in the collection with a rating
+ * @param ratedThreadCount - Number of Threads with at least one rating
  * @returns Whether rating sort should be shown to readers
  *
  * @example
@@ -28,13 +28,15 @@ export function isRatingSortOrder(
  * supportsCollectionRatingSort(2);
  * ```
  */
-export function supportsCollectionRatingSort(ratedPostCount: number): boolean {
-  return ratedPostCount > 1;
+export function supportsCollectionRatingSort(
+  ratedThreadCount: number,
+): boolean {
+  return ratedThreadCount > 1;
 }
 
 /**
  * Resolves the sort order for a collection page, falling back when rating
- * sorting is requested but the collection does not have enough rated posts.
+ * sorting is requested but the collection does not have enough rated Threads.
  *
  * @param requestedSort - Sort order from the request query
  * @param defaultSort - Collection default sort order

package/src/lib/constants.ts

@@ -22,12 +22,14 @@ export const RESERVED_PATHS = [
   "reset",
   "collections",
   "compose",
+  "preview",
   "new",
   "static",
   "assets",
   "_assets",
   "healthz",
   "readyz",
+  "skill.md",
 ] as const;
 
 export type ReservedPath = (typeof RESERVED_PATHS)[number];

package/src/lib/feed-path.ts

@@ -0,0 +1,25 @@
+const NON_FEED_PATH_PREFIXES = ["/api", "/settings", "/compose", "/_"];
+
+function hasPathPrefix(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+/**
+ * Check whether an internal application path is an Atom feed endpoint.
+ *
+ * @param path - Request pathname after any configured site prefix is removed
+ * @returns Whether the path is a canonical or legacy feed URL
+ * @example
+ * ```ts
+ * isRssFeedPath("/reading/feed"); // true
+ * isRssFeedPath("/api/posts"); // false
+ * ```
+ */
+export function isRssFeedPath(path: string): boolean {
+  if (path === "/feed" || path.startsWith("/feed/")) return true;
+  if (NON_FEED_PATH_PREFIXES.some((prefix) => hasPathPrefix(path, prefix))) {
+    return false;
+  }
+
+  return path.endsWith("/feed") || path.endsWith("/feed/atom.xml");
+}

package/src/lib/feed-policy.ts

@@ -0,0 +1,64 @@
+import type { Post } from "../types.js";
+import { now, toISOString } from "./time.js";
+
+/** Cache policy for dynamic Atom feed responses. */
+export const RSS_FEED_CACHE_CONTROL = "public, max-age=60";
+
+/**
+ * Convert an RSS publication delay into the exclusive upper bound expected by
+ * Post service queries.
+ *
+ * Posts published exactly `delaySeconds` ago are eligible. Because publication
+ * timestamps use whole seconds while `publishedBefore` is exclusive, the bound
+ * is one second after the latest eligible timestamp.
+ *
+ * @param delaySeconds - Non-negative publication delay in seconds
+ * @param currentTime - Current Unix timestamp, injectable for deterministic use
+ * @returns Exclusive `publishedBefore` timestamp for RSS queries
+ * @example
+ * ```ts
+ * getRssPublishedBefore(300, 1_000); // 701, so publishedAt <= 700 is eligible
+ * ```
+ */
+export function getRssPublishedBefore(
+  delaySeconds: number,
+  currentTime = now(),
+): number {
+  return currentTime - delaySeconds + 1;
+}
+
+/**
+ * Resolve the Atom `updated` timestamp for a Thread entry from content that is
+ * actually present in the feed.
+ *
+ * @param root - Thread root used as a fallback when no Thread rows are loaded
+ * @param thread - Eligible Thread Posts included in the Atom entry
+ * @param additionalTimestamps - Other entry updates, such as Collection membership
+ * @returns Latest update timestamp as an ISO 8601 string
+ * @example
+ * ```ts
+ * getFeedEntryUpdatedAt(root, [root, reply], [collectedAt]);
+ * ```
+ */
+export function getFeedEntryUpdatedAt(
+  root: Pick<Post, "publishedAt" | "updatedAt">,
+  thread: readonly Pick<Post, "publishedAt" | "updatedAt">[] | undefined,
+  additionalTimestamps: readonly (number | null | undefined)[] = [],
+): string {
+  let updatedAt = Math.max(root.updatedAt, root.publishedAt ?? root.updatedAt);
+
+  for (const post of thread ?? []) {
+    updatedAt = Math.max(
+      updatedAt,
+      post.updatedAt,
+      post.publishedAt ?? post.updatedAt,
+    );
+  }
+  for (const timestamp of additionalTimestamps) {
+    if (timestamp !== null && timestamp !== undefined) {
+      updatedAt = Math.max(updatedAt, timestamp);
+    }
+  }
+
+  return toISOString(updatedAt);
+}

package/src/lib/footnotes.ts

@@ -18,6 +18,16 @@ export interface FootnoteDefinitionTokenData {
   contentMarkdown: string;
 }
 
+export interface LegacyFootnoteUpgradeResult {
+  doc: JSONContent;
+  upgraded: boolean;
+}
+
+interface LegacyFootnoteReference {
+  label: string;
+  node: JSONContent;
+}
+
 export function normalizeFootnoteLabel(label: unknown): string {
   if (typeof label !== "string") return "";
   return label.trim().replace(/\s+/g, " ");
@@ -82,6 +92,260 @@ export function normalizeFootnoteArtifacts(doc: JSONContent): JSONContent {
   return content.length === doc.content.length ? doc : { ...doc, content };
 }
 
+function getLinkHref(node: JSONContent): string {
+  const linkMarks = (node.marks ?? []).filter((mark) => mark.type === "link");
+  if (linkMarks.length !== 1) return "";
+
+  const href = linkMarks[0]?.attrs?.href;
+  return typeof href === "string" ? href.trim() : "";
+}
+
+function decodeHashTarget(href: string): string {
+  if (!href.startsWith("#")) return "";
+
+  try {
+    return decodeURIComponent(href.slice(1));
+  } catch {
+    return href.slice(1);
+  }
+}
+
+function normalizeLegacyTargetId(value: string): string {
+  return value.replace(/^user-content-/i, "").toLowerCase();
+}
+
+function getLegacyReferenceLabel(node: JSONContent): string {
+  if (node.type !== "text" || typeof node.text !== "string") return "";
+
+  const text = node.text.trim();
+  const displayMatch = text.match(/^\[\^?([^\]\n]+)\]$/);
+  const label = normalizeFootnoteLabel(displayMatch?.[1] ?? text);
+  if (!label) return "";
+
+  const targetId = normalizeLegacyTargetId(decodeHashTarget(getLinkHref(node)));
+  const expectedTargetId = `fn-${getFootnoteDomId(label)}`.toLowerCase();
+  return targetId === expectedTargetId ? label : "";
+}
+
+function collectLegacyReferences(
+  node: JSONContent,
+  references: LegacyFootnoteReference[],
+): void {
+  const label = getLegacyReferenceLabel(node);
+  if (label) {
+    references.push({ label, node });
+    return;
+  }
+
+  for (const child of node.content ?? []) {
+    collectLegacyReferences(child, references);
+  }
+}
+
+function isBacklinkText(value: string | undefined): boolean {
+  return /^(?:↩(?:︎)?|↵)(?:\s*\d+)?$/.test(value?.trim() ?? "");
+}
+
+function getLegacyBacklinkLabel(
+  node: JSONContent,
+  labels: readonly string[],
+): string {
+  if (node.type !== "text" || !isBacklinkText(node.text)) return "";
+
+  const targetId = normalizeLegacyTargetId(decodeHashTarget(getLinkHref(node)));
+  if (!targetId.startsWith("fnref-")) return "";
+
+  for (const label of labels) {
+    const base = `fnref-${getFootnoteDomId(label)}`.toLowerCase();
+    const occurrence = targetId.startsWith(`${base}-`)
+      ? targetId.slice(base.length + 1)
+      : "";
+    if (targetId === base || /^\d+$/.test(occurrence)) {
+      return label;
+    }
+  }
+
+  return "";
+}
+
+function collectLegacyBacklinkLabels(
+  node: JSONContent,
+  labels: readonly string[],
+  found: Set<string>,
+): void {
+  const label = getLegacyBacklinkLabel(node, labels);
+  if (label) {
+    found.add(getFootnoteLabelKey(label));
+    return;
+  }
+
+  for (const child of node.content ?? []) {
+    collectLegacyBacklinkLabels(child, labels, found);
+  }
+}
+
+function removeLegacyBacklinks(
+  node: JSONContent,
+  label: string,
+): JSONContent | null {
+  if (
+    getFootnoteLabelKey(getLegacyBacklinkLabel(node, [label])) ===
+    getFootnoteLabelKey(label)
+  ) {
+    return null;
+  }
+
+  if (!node.content) return node;
+
+  const content = node.content.flatMap((child) => {
+    const normalized = removeLegacyBacklinks(child, label);
+    return normalized ? [normalized] : [];
+  });
+
+  if (content.length === node.content.length) {
+    const unchanged = content.every(
+      (child, index) => child === node.content?.[index],
+    );
+    if (unchanged) return node;
+  }
+
+  return content.length > 0 ? { ...node, content } : { ...node, content: [] };
+}
+
+function replaceLegacyReferences(
+  node: JSONContent,
+  labelsByNode: Map<JSONContent, string>,
+): JSONContent {
+  const label = labelsByNode.get(node);
+  if (label) {
+    return { type: "footnoteReference", attrs: { label } };
+  }
+
+  if (!node.content) return node;
+
+  const content = node.content.map((child) =>
+    replaceLegacyReferences(child, labelsByNode),
+  );
+  const unchanged = content.every(
+    (child, index) => child === node.content?.[index],
+  );
+  return unchanged ? node : { ...node, content };
+}
+
+function hasCanonicalFootnoteNode(node: JSONContent): boolean {
+  if (node.type === "footnoteReference" || node.type === "footnoteDefinition") {
+    return true;
+  }
+
+  return (node.content ?? []).some(hasCanonicalFootnoteNode);
+}
+
+/**
+ * Upgrades the historical footnote shape that old rich-text pastes stored as
+ * ordinary fragment links plus a trailing ordered list.
+ *
+ * Conversion is deliberately all-or-nothing. The document must end in an
+ * `hr` and ordered list, every definition item must contain a matching
+ * `#fnref-*` backlink, and every `#fn-*` reference must have exactly one
+ * definition label. This keeps normal fragment links and numbered lists
+ * untouched.
+ *
+ * @param doc - Parsed TipTap document
+ * @returns The canonical document and whether a legacy footnote set changed
+ * @example
+ * ```ts
+ * const result = upgradeLegacyFootnotes({
+ *   type: "doc",
+ *   content: [],
+ * });
+ * // { doc: { type: "doc", content: [] }, upgraded: false }
+ * ```
+ */
+export function upgradeLegacyFootnotes(
+  doc: JSONContent,
+): LegacyFootnoteUpgradeResult {
+  if (
+    doc.type !== "doc" ||
+    !Array.isArray(doc.content) ||
+    doc.content.length < 3 ||
+    hasCanonicalFootnoteNode(doc)
+  ) {
+    return { doc, upgraded: false };
+  }
+
+  const definitionList = doc.content.at(-1);
+  const separator = doc.content.at(-2);
+  if (
+    definitionList?.type !== "orderedList" ||
+    separator?.type !== "horizontalRule" ||
+    !Array.isArray(definitionList.content) ||
+    definitionList.content.length === 0 ||
+    definitionList.content.some((item) => item.type !== "listItem")
+  ) {
+    return { doc, upgraded: false };
+  }
+
+  const bodyNodes = doc.content.slice(0, -2);
+  const references: LegacyFootnoteReference[] = [];
+  for (const node of bodyNodes) collectLegacyReferences(node, references);
+  if (references.length === 0) return { doc, upgraded: false };
+
+  const labelsByKey = new Map<string, string>();
+  for (const reference of references) {
+    const key = getFootnoteLabelKey(reference.label);
+    if (!labelsByKey.has(key)) labelsByKey.set(key, reference.label);
+  }
+  const labels = [...labelsByKey.values()].sort(
+    (left, right) =>
+      getFootnoteDomId(right).length - getFootnoteDomId(left).length,
+  );
+  if (labels.length !== definitionList.content.length) {
+    return { doc, upgraded: false };
+  }
+
+  const definitions: JSONContent[] = [];
+  const definedLabels = new Set<string>();
+  for (const item of definitionList.content) {
+    const backlinkLabels = new Set<string>();
+    collectLegacyBacklinkLabels(item, labels, backlinkLabels);
+    if (backlinkLabels.size !== 1) return { doc, upgraded: false };
+
+    const key = [...backlinkLabels][0];
+    if (!key) return { doc, upgraded: false };
+    const label = labelsByKey.get(key);
+    if (!label || definedLabels.has(key)) return { doc, upgraded: false };
+
+    definedLabels.add(key);
+    const content = (item.content ?? []).flatMap((child) => {
+      const normalized = removeLegacyBacklinks(child, label);
+      return normalized ? [normalized] : [];
+    });
+    definitions.push({
+      type: "footnoteDefinition",
+      attrs: { label },
+      content: content.length > 0 ? content : [{ type: "paragraph" }],
+    });
+  }
+
+  if (definedLabels.size !== labelsByKey.size) {
+    return { doc, upgraded: false };
+  }
+
+  const labelsByNode = new Map(
+    references.map((reference) => [reference.node, reference.label] as const),
+  );
+  return {
+    doc: {
+      ...doc,
+      content: [
+        ...bodyNodes.map((node) => replaceLegacyReferences(node, labelsByNode)),
+        ...definitions,
+      ],
+    },
+    upgraded: true,
+  };
+}
+
 /**
  * Parses one Markdown footnote definition from the start of `src`.
  *