@gmickel/gno 1.24.0 → 1.26.0

package/src/core/capture.ts

@@ -10,6 +10,10 @@
 import { posix as pathPosix } from "node:path";
 
 import { buildUri } from "../app/constants";
+import {
+  browserClipProvenanceSchema,
+  type BrowserClipProvenance,
+} from "./browser-clip-provenance";
 import {
   resolveNoteCreatePlan,
   type NoteCollisionPolicy,
@@ -59,9 +63,13 @@ export interface CaptureSource {
   mime?: string;
   ext?: string;
   author?: string;
+  canonicalUrl?: string;
+  site?: string;
+  publishedAt?: string;
   observedAt?: string;
   capturedAt: string;
   externalId?: string;
+  browserClip?: BrowserClipProvenance;
 }
 
 export interface CaptureIndexStatus {
@@ -117,6 +125,7 @@ export interface CapturePlan {
   source: CaptureSource;
   openedExisting: boolean;
   createdWithSuffix: boolean;
+  provenanceConflict: boolean;
   collisionPolicy: NoteCollisionPolicy;
   collisionPolicyResult: CaptureCollisionPolicyResult;
   overwrite: boolean;
@@ -126,6 +135,7 @@ export interface PlanCaptureOptions {
   input: CaptureInput;
   existingRelPaths: Iterable<string>;
   diskRelPaths?: Iterable<string>;
+  existingProvenanceByRelPath?: ReadonlyMap<string, string>;
   now?: Date;
 }
 
@@ -145,7 +155,7 @@ const VALID_COLLISION_POLICIES = new Set<NoteCollisionPolicy>([
   "open_existing",
   "create_with_suffix",
 ]);
-const URL_SOURCE_FIELDS = new Set(["url", "uri"]);
+const URL_SOURCE_FIELDS = new Set(["url", "uri", "canonicalUrl"]);
 const LEGACY_SOURCE_FIELD_MAP: Record<string, keyof CaptureSource> = {
   gno_source_docid: "docid",
   gno_source_uri: "uri",
@@ -160,6 +170,9 @@ const CAPTURE_SOURCE_STRING_KEYS = new Set([
   "mime",
   "ext",
   "author",
+  "canonicalUrl",
+  "site",
+  "publishedAt",
   "externalId",
 ]);
 
@@ -264,27 +277,46 @@ function normalizeSource(
       continue;
     }
     if (key === "capturedAt") {
-      normalized.capturedAt = normalizeIsoDate(
-        String(value),
-        "source.capturedAt"
-      );
+      if (typeof value !== "string") {
+        throw new Error("source.capturedAt must be a string.");
+      }
+      normalized.capturedAt = normalizeIsoDate(value, "source.capturedAt");
       continue;
     }
     if (key === "observedAt") {
-      normalized.observedAt = normalizeIsoDate(
-        String(value),
-        "source.observedAt"
-      );
+      if (typeof value !== "string") {
+        throw new Error("source.observedAt must be a string.");
+      }
+      normalized.observedAt = normalizeIsoDate(value, "source.observedAt");
+      continue;
+    }
+    if (key === "publishedAt") {
+      if (typeof value !== "string") {
+        throw new Error("source.publishedAt must be a string.");
+      }
+      normalized.publishedAt = /^\d{4}-\d{2}-\d{2}$/.test(value)
+        ? value
+        : normalizeIsoDate(value, "source.publishedAt");
+      continue;
+    }
+    if (key === "browserClip") {
+      normalized.browserClip = browserClipProvenanceSchema.parse(value);
       continue;
     }
     if (URL_SOURCE_FIELDS.has(key)) {
+      if (typeof value !== "string") {
+        throw new Error(`source.${key} must be a string.`);
+      }
       try {
-        new URL(String(value));
+        new URL(value);
       } catch {
         throw new Error(`source.${key} must be a valid URL.`);
       }
     }
     if (CAPTURE_SOURCE_STRING_KEYS.has(key)) {
+      if (typeof value !== "string") {
+        throw new Error(`source.${key} must be a string.`);
+      }
       normalized[
         key as keyof Pick<
           CaptureSource,
@@ -295,9 +327,11 @@ function normalizeSource(
           | "mime"
           | "ext"
           | "author"
+          | "canonicalUrl"
+          | "site"
           | "externalId"
         >
-      ] = String(value);
+      ] = value;
     }
   }
 
@@ -489,6 +523,16 @@ export function extractCaptureSourceFromFrontmatter(
         .trim() as keyof CaptureSource;
       const nestedValue = nested.slice(nestedColon + 1).trim();
       if (nestedValue) {
+        if (nestedKey === "browserClip") {
+          try {
+            const parsed = JSON.parse(nestedValue) as unknown;
+            const provenance = browserClipProvenanceSchema.safeParse(parsed);
+            if (provenance.success) source.browserClip = provenance.data;
+          } catch {
+            // Ignore malformed optional browser provenance.
+          }
+          continue;
+        }
         source[nestedKey] = stripYamlString(nestedValue) as never;
       }
     }
@@ -664,6 +708,13 @@ export function planCapture(options: PlanCaptureOptions): CapturePlan {
     overwrite ? [] : existing
   );
   const overwritten = overwrite && existing.has(createPlan.relPath);
+  const clipIdentity = source.browserClip?.clipIdentity;
+  const provenanceConflict =
+    createPlan.openedExisting &&
+    clipIdentity !== undefined &&
+    options.existingProvenanceByRelPath?.get(createPlan.relPath) !==
+      clipIdentity;
+  const openedExisting = createPlan.openedExisting && !provenanceConflict;
 
   return {
     collection: options.input.collection,
@@ -675,16 +726,19 @@ export function planCapture(options: PlanCaptureOptions): CapturePlan {
     title,
     tags: contentTags,
     source,
-    openedExisting: createPlan.openedExisting,
+    openedExisting,
     createdWithSuffix: createPlan.createdWithSuffix,
+    provenanceConflict,
     collisionPolicy,
     collisionPolicyResult: overwritten
       ? "overwritten"
-      : createPlan.openedExisting
-        ? "opened_existing"
-        : createPlan.createdWithSuffix
-          ? "created_with_suffix"
-          : "created",
+      : provenanceConflict
+        ? "conflict"
+        : openedExisting
+          ? "opened_existing"
+          : createPlan.createdWithSuffix
+            ? "created_with_suffix"
+            : "created",
     overwrite,
   };
 }
@@ -705,7 +759,10 @@ export function buildCaptureReceipt(input: {
     collection: input.plan.collection,
     relPath: input.plan.relPath,
     absPath: input.absPath,
-    created: !input.plan.openedExisting && !overwritten,
+    created:
+      !input.plan.openedExisting &&
+      !input.plan.provenanceConflict &&
+      !overwritten,
     openedExisting: input.plan.openedExisting,
     createdWithSuffix: input.plan.createdWithSuffix,
     overwritten,

package/src/core/config-mutation.ts

@@ -1,5 +1,5 @@
 /**
- * Config mutation helper shared by Web UI and MCP.
+ * Canonical config mutation helper shared by every config writer.
  *
  * @module src/core/config-mutation
  */
@@ -9,27 +9,42 @@ import type { SqliteAdapter } from "../store/sqlite/adapter";
 
 import {
   formatConfigWarnings,
+  getConfigPaths,
   loadConfig,
   normalizeConfigContentTypes,
   saveConfig,
 } from "../config";
+import { resolveConfigWriteTarget } from "./config-write-lock";
 import { withWriteLock } from "./file-lock";
 
-export interface ConfigMutationContext {
-  store: SqliteAdapter;
+export interface ConfigFileMutationContext {
   configPath?: string;
-  onConfigUpdated: (config: Config) => void;
   /**
-   * Optional cross-process serialization boundary. The in-memory mutex remains
-   * authoritative within one process; callers sharing a config across
-   * processes must additionally share this OS-backed lock path.
+   * Optional first-run config factory. Callers must opt in explicitly; existing
+   * mutation surfaces keep treating a missing config as an error.
+   */
+  createConfigIfMissing?: () => Config;
+  onConfigUpdated?: (config: Config) => void;
+}
+
+export interface ConfigMutationContext extends ConfigFileMutationContext {
+  store: SqliteAdapter;
+  /**
+   * Optional targeted store projection. The default reconciles the complete
+   * config. Create/update-only callers can project a bounded subset without
+   * deleting DB-only recovery state.
    */
-  writeLockPath?: string;
+  projectStore?: (
+    store: SqliteAdapter,
+    config: Config
+  ) => Promise<{ ok: true } | { ok: false; error: string }>;
   /**
    * Runs after the selected config is durably present and before store projection.
    * Setup recovery uses this boundary to persist a truthful resumable receipt.
    */
   afterConfigSaved?: (config: Config) => Promise<void> | void;
+  /** Runs after config projection succeeds while the write lock is still held. */
+  afterStoreSynced?: (config: Config) => Promise<void> | void;
 }
 
 export type MutationResult<T = void> =
@@ -40,68 +55,130 @@ export type ApplyConfigResult<T = void> =
   | { ok: true; config: Config; value?: T }
   | { ok: false; error: string; code: string };
 
-/**
- * In-memory mutex for serializing config mutations.
- * Prevents lost updates when multiple requests try to modify config concurrently.
- */
-let configMutex: Promise<void> = Promise.resolve();
+export interface ConfigMutationState {
+  created: boolean;
+}
 
-export async function applyConfigChange<T = void>(
-  ctx: ConfigMutationContext,
-  mutate: (config: Config) => Promise<MutationResult<T>> | MutationResult<T>
+type PersistedConfigHook = (
+  config: Config
+) => Promise<{ ok: true } | { ok: false; error: string; code: string }>;
+
+async function applySerializedConfigChange<T>(
+  ctx: ConfigFileMutationContext,
+  mutate: (
+    config: Config,
+    state: ConfigMutationState
+  ) => Promise<MutationResult<T>> | MutationResult<T>,
+  afterPersist?: PersistedConfigHook
 ): Promise<ApplyConfigResult<T>> {
-  const previousMutex = configMutex;
-  let resolveMutex: () => void = () => {
-    /* no-op until assigned */
-  };
-
-  configMutex = new Promise((resolve) => {
-    resolveMutex = resolve;
-  });
-
-  try {
-    await previousMutex;
-
-    const applyFreshConfigChange = async (): Promise<ApplyConfigResult<T>> => {
-      const loadResult = await loadConfig(ctx.configPath);
-      if (!loadResult.ok) {
-        return {
-          ok: false,
-          error: loadResult.error.message,
-          code: "LOAD_ERROR",
-        };
-      }
+  const requestedConfigPath = ctx.configPath ?? getConfigPaths().configFile;
+  const writeTarget = await resolveConfigWriteTarget(requestedConfigPath);
+  const selectedConfigPath = writeTarget.configPath;
+  const applyFreshConfigChange = async (): Promise<ApplyConfigResult<T>> => {
+    const loadResult = await loadConfig(selectedConfigPath);
+    if (
+      !loadResult.ok &&
+      !(loadResult.error.code === "NOT_FOUND" && ctx.createConfigIfMissing)
+    ) {
+      return {
+        ok: false,
+        error: loadResult.error.message,
+        code: "LOAD_ERROR",
+      };
+    }
+    if (loadResult.ok) {
       for (const warning of formatConfigWarnings(loadResult.warnings)) {
         console.warn(warning);
       }
+    }
+
+    const currentConfig = loadResult.ok
+      ? loadResult.value
+      : ctx.createConfigIfMissing?.();
+    if (!currentConfig) {
+      return {
+        ok: false,
+        error: "Config file is missing",
+        code: "LOAD_ERROR",
+      };
+    }
+    const mutationResult = await mutate(currentConfig, {
+      created: !loadResult.ok,
+    });
+    if (!mutationResult.ok) {
+      return {
+        ok: false,
+        error: mutationResult.error,
+        code: mutationResult.code,
+      };
+    }
 
-      const mutationResult = await mutate(loadResult.value);
-      if (!mutationResult.ok) {
+    const normalized = normalizeConfigContentTypes(mutationResult.config);
+    for (const warning of formatConfigWarnings(normalized.warnings)) {
+      console.warn(warning);
+    }
+    const newConfig = normalized.config;
+    if (!mutationResult.skipSave) {
+      const saveResult = await saveConfig(newConfig, selectedConfigPath);
+      if (!saveResult.ok) {
         return {
           ok: false,
-          error: mutationResult.error,
-          code: mutationResult.code,
+          error: saveResult.error.message,
+          code: "SAVE_ERROR",
         };
       }
+    }
 
-      const normalized = normalizeConfigContentTypes(mutationResult.config);
-      for (const warning of formatConfigWarnings(normalized.warnings)) {
-        console.warn(warning);
-      }
-      const newConfig = normalized.config;
-      if (!mutationResult.skipSave) {
-        const saveResult = await saveConfig(newConfig, ctx.configPath);
-        if (!saveResult.ok) {
-          return {
-            ok: false,
-            error: saveResult.error.message,
-            code: "SAVE_ERROR",
-          };
-        }
-      }
+    const persisted = await afterPersist?.(newConfig);
+    if (persisted && !persisted.ok) return persisted;
+    ctx.onConfigUpdated?.(newConfig);
+
+    return { ok: true, config: newConfig, value: mutationResult.value };
+  };
+
+  try {
+    return await withWriteLock(writeTarget.lockPath, applyFreshConfigChange);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("LOCKED:")) {
+      return { ok: false, error: error.message, code: "LOCKED" };
+    }
+    throw error;
+  }
+}
 
-      await ctx.afterConfigSaved?.(newConfig);
+/** Mutate only the selected config file under the canonical shared lock. */
+export async function applyConfigFileChange<T = void>(
+  ctx: ConfigFileMutationContext,
+  mutate: (
+    config: Config,
+    state: ConfigMutationState
+  ) => Promise<MutationResult<T>> | MutationResult<T>
+): Promise<ApplyConfigResult<T>> {
+  return applySerializedConfigChange(ctx, mutate);
+}
+
+/** Mutate config and project it to the selected store in one locked boundary. */
+export async function applyConfigChange<T = void>(
+  ctx: ConfigMutationContext,
+  mutate: (
+    config: Config,
+    state: ConfigMutationState
+  ) => Promise<MutationResult<T>> | MutationResult<T>
+): Promise<ApplyConfigResult<T>> {
+  return applySerializedConfigChange(ctx, mutate, async (newConfig) => {
+    await ctx.afterConfigSaved?.(newConfig);
 
+    if (ctx.projectStore) {
+      const projection = await ctx.projectStore(ctx.store, newConfig);
+      if (!projection.ok) {
+        console.warn(`Config saved but DB sync failed: ${projection.error}`);
+        return {
+          ok: false,
+          error: `DB sync failed: ${projection.error}`,
+          code: "SYNC_ERROR",
+        };
+      }
+    } else {
       const syncCollResult = await ctx.store.syncCollections(
         newConfig.collections
       );
@@ -129,24 +206,9 @@ export async function applyConfigChange<T = void>(
           code: "SYNC_ERROR",
         };
       }
-
-      ctx.onConfigUpdated(newConfig);
-
-      return { ok: true, config: newConfig, value: mutationResult.value };
-    };
-
-    if (!ctx.writeLockPath) {
-      return await applyFreshConfigChange();
-    }
-    try {
-      return await withWriteLock(ctx.writeLockPath, applyFreshConfigChange);
-    } catch (error) {
-      if (error instanceof Error && error.message.startsWith("LOCKED:")) {
-        return { ok: false, error: error.message, code: "LOCKED" };
-      }
-      throw error;
     }
-  } finally {
-    resolveMutex();
-  }
+
+    await ctx.afterStoreSynced?.(newConfig);
+    return { ok: true };
+  });
 }

package/src/core/config-write-lock.ts

@@ -0,0 +1,89 @@
+/**
+ * Canonical cross-process lock identity for all config writers.
+ *
+ * @module src/core/config-write-lock
+ */
+
+// node:fs/promises provides symlink-aware path operations; Bun has no equivalent for canonical path identity.
+import { lstat, readlink, realpath } from "node:fs/promises";
+// node:path provides structural path operations; Bun has no path utilities.
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+
+import { expandPath } from "../config/paths";
+
+const MISSING_PATH_ERROR_CODES = new Set(["ENOENT", "ENOTDIR"]);
+
+function isMissingPathError(cause: unknown): boolean {
+  return (
+    cause instanceof Error &&
+    "code" in cause &&
+    typeof cause.code === "string" &&
+    MISSING_PATH_ERROR_CODES.has(cause.code)
+  );
+}
+
+async function canonicalizeProspectivePath(
+  absolutePath: string,
+  seenLinks: Set<string>
+): Promise<string> {
+  const unresolved: string[] = [];
+  let candidate = absolutePath;
+
+  while (true) {
+    try {
+      const info = await lstat(candidate);
+      if (info.isSymbolicLink()) {
+        if (seenLinks.has(candidate)) {
+          throw new Error(`Config path contains a symlink loop: ${candidate}`);
+        }
+        seenLinks.add(candidate);
+
+        const linkTarget = await readlink(candidate);
+        const absoluteTarget = isAbsolute(linkTarget)
+          ? linkTarget
+          : resolve(dirname(candidate), linkTarget);
+        const canonicalTarget = await canonicalizeProspectivePath(
+          absoluteTarget,
+          seenLinks
+        );
+        return resolve(canonicalTarget, ...unresolved.reverse());
+      }
+
+      const canonicalAncestor = await realpath(candidate);
+      return resolve(canonicalAncestor, ...unresolved.reverse());
+    } catch (cause) {
+      if (!isMissingPathError(cause)) throw cause;
+
+      const parent = dirname(candidate);
+      if (parent === candidate) return absolutePath;
+      unresolved.push(basename(candidate));
+      candidate = parent;
+    }
+  }
+}
+
+/**
+ * Resolve an existing path, or resolve its nearest existing ancestor while
+ * retaining unresolved path components. This makes aliases of the same config
+ * file converge before the file exists and after it is created.
+ */
+export async function canonicalOperationalPath(path: string): Promise<string> {
+  return canonicalizeProspectivePath(resolve(expandPath(path)), new Set());
+}
+
+/** One stable sibling lock for every writer of the selected config file. */
+export async function resolveConfigWriteTarget(
+  configPath: string
+): Promise<{ configPath: string; lockPath: string }> {
+  const canonicalConfigPath = await canonicalOperationalPath(configPath);
+  return {
+    configPath: canonicalConfigPath,
+    lockPath: `${canonicalConfigPath}.write.lock`,
+  };
+}
+
+export async function getConfigWriteLockPath(
+  configPath: string
+): Promise<string> {
+  return (await resolveConfigWriteTarget(configPath)).lockPath;
+}

package/src/core/context-identity.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical identity helpers for persisted context records.
+ *
+ * @module src/core/context-identity
+ */
+
+const BYTE_ORDER_MARK_PATTERN = /^\uFEFF/u;
+const CARRIAGE_RETURN_PATTERN = /\r\n?/g;
+
+export function normalizePersistedContextText(text: string): string {
+  return text
+    .replace(BYTE_ORDER_MARK_PATTERN, "")
+    .replace(CARRIAGE_RETURN_PATTERN, "\n")
+    .normalize("NFC")
+    .trim();
+}

package/src/core/context-resolver.ts

@@ -1,9 +1,7 @@
 import type { ContextRow, StorePort } from "../store/types";
 
 import { parseUri } from "../app/constants";
-
-const CARRIAGE_RETURN_PATTERN = /\r\n?/g;
-const BYTE_ORDER_MARK_PATTERN = /^\uFEFF/u;
+import { normalizePersistedContextText } from "./context-identity";
 
 export interface ContextDocumentIdentity {
   collection: string;
@@ -73,14 +71,6 @@ function normalizeIdentity(
   return { collection, relPath };
 }
 
-function normalizeText(text: string): string {
-  return text
-    .replace(BYTE_ORDER_MARK_PATTERN, "")
-    .replace(CARRIAGE_RETURN_PATTERN, "\n")
-    .normalize("NFC")
-    .trim();
-}
-
 function byteKey(text: string): string {
   return [...new TextEncoder().encode(text)].join(",");
 }
@@ -95,7 +85,7 @@ function normalizeContext(
   context: ContextRow,
   identity: NormalizedIdentity
 ): MatchingContext | null {
-  const text = normalizeText(context.text);
+  const text = normalizePersistedContextText(context.text);
   if (!text) {
     return null;
   }

package/src/core/file-lock.ts

@@ -36,6 +36,7 @@ function resolveLockCommand(): LockCommand | null {
     return {
       path: lockfPath,
       args: (lockPath, timeoutSeconds, holdCommand) => [
+        "-k",
         "-t",
         String(timeoutSeconds),
         lockPath,
@@ -51,6 +52,7 @@ function resolveLockCommand(): LockCommand | null {
     return {
       path: flockPath,
       args: (lockPath, timeoutSeconds, holdCommand) => [
+        "--no-fork",
         "-w",
         String(timeoutSeconds),
         lockPath,
@@ -93,6 +95,21 @@ async function waitForReady(
   }
 }
 
+async function terminateLockProcess(
+  proc: ReturnType<typeof Bun.spawn>
+): Promise<void> {
+  if (process.platform === "win32") {
+    if (proc.exitCode === null) proc.kill();
+  } else {
+    try {
+      process.kill(-proc.pid, "SIGTERM");
+    } catch {
+      if (proc.exitCode === null) proc.kill();
+    }
+  }
+  await proc.exited.catch(() => undefined);
+}
+
 function sqliteLockPath(lockPath: string): string {
   return `${lockPath}${SQLITE_LOCK_SUFFIX}`;
 }
@@ -163,6 +180,7 @@ export async function acquireWriteLock(
   const proc = Bun.spawn(
     [cmd.path, ...cmd.args(lockPath, timeoutSeconds, holdCommand)],
     {
+      detached: true,
       stdout: "pipe",
       stderr: "pipe",
     }
@@ -170,16 +188,12 @@ export async function acquireWriteLock(
 
   const ready = await waitForReady(proc);
   if (!ready) {
-    proc.kill();
-    await proc.exited.catch(() => undefined);
+    await terminateLockProcess(proc);
     return null;
   }
 
   return {
-    release: async () => {
-      proc.kill();
-      await proc.exited.catch(() => undefined);
-    },
+    release: () => terminateLockProcess(proc),
   };
 }