@nanobpm/urban 0.63.1 → 0.65.0

package/src/context/binding/resolver.ts

@@ -0,0 +1,176 @@
+// Slice S1 (binding) — the resolver: bind → validate → identity → resolved
+// handle, with private-per-app / shared-on-same-name semantics enforced two
+// ways:
+//
+//  1. In-process: a ContextResolver memoises by identity key, so two resolves of
+//     the same name return the SAME handle (and never double-clone), while
+//     distinct names get distinct handles.
+//  2. Across processes/instances: the on-disk location is derived
+//     deterministically from the identity slug under a shared cache root, so two
+//     Nano instances naming the same context share one working copy on disk.
+//     Known first-use limitation (deferred past slice S1): the single-flight in
+//     (1) is in-process only, so concurrent *first* resolves of the same context
+//     across instances can race materialisation (clone/pin). Sharing is reliable
+//     once the substrate exists; a follow-up slice adds an inter-process lock to
+//     make concurrent first-use safe too — see GitSubstrateBackend.materialise.
+
+import { homedir, tmpdir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+import { parseContextBinding } from "./descriptor.ts";
+import { resolveContextIdentity } from "./identity.ts";
+import { GitSubstrateBackend } from "./git-backend.ts";
+import type { ResolvedContextHandle, SubstrateBackend } from "./backend.ts";
+
+/** Options for a {@link ContextResolver}. */
+export interface ContextResolverOptions {
+  /**
+   * Root directory under which per-context working copies are cloned. Two
+   * resolvers sharing a `cacheRoot` share substrates on disk. Defaults to
+   * {@link defaultContextCacheRoot}.
+   */
+  readonly cacheRoot?: string;
+  /**
+   * The substrate backend. Defaults to a git backend ({@link GitSubstrateBackend}).
+   * Injecting a different backend is the seam for a future PII/mutable or
+   * self-hosted substrate.
+   */
+  readonly backend?: SubstrateBackend;
+}
+
+/** Per-resolution overrides. */
+export interface ResolveOptions {
+  /**
+   * Controls whether a re-resolution re-fetches the substrate. Note the
+   * {@link ContextResolver} memoises per identity: once an identity has resolved,
+   * repeat resolves return the cached handle and do **not** re-fetch unless you
+   * explicitly pass `refresh: true`, which forces a fresh materialisation (a
+   * fetch + re-pin on the backend). While a materialisation is still in flight,
+   * concurrent resolves — including `refresh: true` — coalesce onto it rather
+   * than starting a second one. The backend's own default (fetch on an existing
+   * clone) therefore only applies the first time an identity is materialised or
+   * when `refresh: true` is passed. Defaults to `undefined` (reuse the memoised
+   * handle).
+   */
+  readonly refresh?: boolean;
+}
+
+/**
+ * The default cache root for context working copies. Honours
+ * `URBAN_CONTEXT_CACHE_DIR`, then `XDG_CACHE_HOME`, then `~/.cache`, falling
+ * back to the OS temp dir when no home directory is available.
+ */
+export function defaultContextCacheRoot(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  if (env.URBAN_CONTEXT_CACHE_DIR) return env.URBAN_CONTEXT_CACHE_DIR;
+  if (env.XDG_CACHE_HOME) return join(env.XDG_CACHE_HOME, "urban", "context");
+  const home = safeHomedir();
+  if (home) return join(home, ".cache", "urban", "context");
+  return join(tmpdir(), "urban", "context");
+}
+
+/** `os.homedir()`, but tolerant: returns `undefined` if the home dir can't be
+ * determined (Node can throw here) so callers fall back to the temp dir. */
+function safeHomedir(): string | undefined {
+  try {
+    return homedir() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolves context bindings to concrete local working copies. A single resolver
+ * instance enforces shared-on-same-name in-process by memoising per identity
+ * key; distinct names stay private.
+ */
+export class ContextResolver {
+  readonly #cacheRoot: string;
+  readonly #backend: SubstrateBackend;
+  // Per-identity resolution record. Despite serving the single-flight guarantee,
+  // this map is NOT purged once a resolution settles: the settled record is
+  // retained as the long-lived memoisation cache backing shared-on-same-name, so
+  // repeat resolves return the identical handle. Entries are removed only on
+  // rejection (so a failed materialise can be retried); a fulfilled entry lives
+  // for the resolver's lifetime. Do not add "drop settled entries" cleanup here
+  // without also giving up memoisation.
+  readonly #resolutions = new Map<string, { promise: Promise<ResolvedContextHandle>; settled: boolean }>();
+
+  constructor(options: ContextResolverOptions = {}) {
+    // Normalise to an absolute path so a relative `cacheRoot` (or a relative
+    // `URBAN_CONTEXT_CACHE_DIR`) still yields an absolute `localPath`, honouring
+    // `SubstrateResolveOptions.localPath` ("Absolute path…"). Note this resolves
+    // a relative `cacheRoot` against *this* process's CWD, so the cross-process
+    // sharing promised in the module header only holds for an ABSOLUTE
+    // `cacheRoot`; a relative one is shared only among instances that happen to
+    // share a working directory.
+    this.#cacheRoot = resolvePath(options.cacheRoot ?? defaultContextCacheRoot());
+    this.#backend = options.backend ?? new GitSubstrateBackend();
+  }
+
+  /** The cache root this resolver clones into. */
+  get cacheRoot(): string {
+    return this.#cacheRoot;
+  }
+
+  /**
+   * Resolve a binding (validated first) to a {@link ResolvedContextHandle}. Two
+   * bindings that name the same context return the identical handle from this
+   * resolver; distinct names return distinct handles.
+   */
+  async resolve(
+    binding: unknown,
+    options: ResolveOptions = {},
+  ): Promise<ResolvedContextHandle> {
+    const parsed = parseContextBinding(binding);
+    const identity = resolveContextIdentity(parsed);
+    const localPath = join(this.#cacheRoot, identity.slug);
+
+    // Shared-on-same-name: concurrent or repeated resolves of one identity share
+    // a single materialisation. Coalesce onto an in-flight one regardless of
+    // `refresh` — it is already producing a fresh working copy, so starting a
+    // second `materialise()` would double-clone into the same `localPath` and
+    // break the single-in-flight guarantee. Only re-materialise once the prior
+    // resolution has settled AND the caller explicitly asked to `refresh`.
+    const existing = this.#resolutions.get(identity.key);
+    if (existing && (!existing.settled || options.refresh !== true)) {
+      return existing.promise;
+    }
+
+    const record: { promise: Promise<ResolvedContextHandle>; settled: boolean } = {
+      promise: this.#backend
+        .materialise(identity, { localPath, refresh: options.refresh })
+        .catch((error) => {
+          if (this.#resolutions.get(identity.key) === record) {
+            this.#resolutions.delete(identity.key);
+          }
+          throw error;
+        }),
+      settled: false,
+    };
+    this.#resolutions.set(identity.key, record);
+    record.promise.then(
+      () => {
+        record.settled = true;
+      },
+      () => {
+        // Rejection is surfaced to the caller via the returned promise; the map
+        // entry is already removed in the catch above.
+      },
+    );
+    return record.promise;
+  }
+}
+
+/**
+ * One-shot convenience: resolve a single binding with a fresh resolver. Prefer a
+ * long-lived {@link ContextResolver} when resolving many bindings so sharing is
+ * memoised across calls.
+ */
+export function resolveContextBinding(
+  binding: unknown,
+  options: ContextResolverOptions & ResolveOptions = {},
+): Promise<ResolvedContextHandle> {
+  const { cacheRoot, backend, ...resolveOptions } = options;
+  return new ContextResolver({ cacheRoot, backend }).resolve(binding, resolveOptions);
+}

package/src/runtime/browser/runtime.browser.js

@@ -633,6 +633,39 @@ function pageHashHref(page, key) {
   return "#/" + encodeURIComponent(page) + "/" + encodeURIComponent(keyStr);
 }
 
+// SINGLE source of truth for a console process-explorer link. The grid link cell
+// (link kind "processExplorer") and the pipeline locus link (issue #347) both
+// route here so they can't drift on the href or the embedded-vs-standalone
+// navigation. The console path is constructed HERE (never taken from row data)
+// and the trimmed key URL-encoded, so row data can't smuggle a path/scheme.
+// Returns null for a blank key (after trimming) so the caller keeps the node
+// plain. Standalone the anchor opens a new tab (hardened rel); embedded in the
+// console a plain primary click instead routes the host's explorer in place via
+// the nano-navigate bridge (a non-primary/modified click keeps the new-tab
+// behavior).
+/** @param {any} label
+ * @param {any} key
+ * @param {string} cls
+ * @returns {any}
+ */
+function explorerAnchor(label, key, cls) {
+  const keyStr = key == null ? "" : String(key).trim();
+  if (keyStr === "") return null;
+  const href = "/console/explorer?instance=" + encodeURIComponent(keyStr);
+  return el("a", {
+    class: cls,
+    href,
+    target: "_blank",
+    rel: "noopener noreferrer",
+    /** @param {MouseEvent} ev */
+    onclick: (ev) => {
+      if (ev.button !== 0) return;
+      if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+      if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
+    },
+  }, label);
+}
+
 // Coerce a not-in-path value (issue #265) into a Set of stage keys. Accepts an
 // array of keys or a comma/whitespace-separated string; null/undefined → empty
 // set. Used to mark the stages a given row skips (dashed/omitted).
@@ -746,27 +779,13 @@ function gridCell(col, row, role) {
     }
   }
   if (primary === text && col.link && col.link.kind === "processExplorer" && col.link.keyField) {
-    const key = row[col.link.keyField];
-    const keyStr = key == null ? "" : String(key).trim();
-    if (text !== "" && keyStr !== "") {
-      const href = "/console/explorer?instance=" + encodeURIComponent(keyStr);
-      primary = el("a", {
-        class: "pc-link",
-        href,
-        target: "_blank",
-        rel: "noopener noreferrer",
-        // Embedded in the console a plain primary click routes the host's
-        // explorer in place (via the nano-navigate bridge) instead of opening
-        // a new window. A non-primary button (middle/right = new-tab/context
-        // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
-        // any standalone run fall through to the native anchor above.
-        /** @param {MouseEvent} ev */
-        onclick: (ev) => {
-          if (ev.button !== 0) return;
-          if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
-          if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
-        },
-      }, text);
+    // Route through the shared explorerAnchor builder (single source of truth) so
+    // this cell and the pipeline locus link can't drift on the href or the
+    // embedded-in-place / standalone-new-tab navigation. A blank key → null →
+    // the cell stays plain text.
+    const a = explorerAnchor(text, row[col.link.keyField], "pc-link");
+    if (text !== "" && a) {
+      primary = a;
     }
   }
   return cellTd(primary, text, subText, truncate, mob);
@@ -924,13 +943,28 @@ function pipelineCell(col, row, text, subText, truncate, tdAttrs) {
   const badgeText = col.badgeField != null && row[col.badgeField] != null ? String(row[col.badgeField]) : "";
   const badgeTone = state === "failed" || state === "blocked" ? "danger" : "warn";
   // Optional locus out-link: the relevant stage (default the active one, or
-  // locus.stage by key) becomes an in-app page link when the row's locus key is
-  // non-empty. Href comes from the shared pageHashHref builder (safePageId guard,
-  // encodeURIComponent) — a blank key yields "" so the stage stays plain.
+  // locus.stage by key) becomes a link when the row's locus key is non-empty.
+  // Two link kinds are supported, mirroring the grid link cell and built via the
+  // SAME single-source builders so the two can't drift: `page` → an in-app
+  // #/<page>/<key> hash route (pageHashHref, safePageId guard + encodeURIComponent);
+  // `processExplorer` → the console explorer for the row's process instance
+  // (explorerAnchor, embedded-in-place / standalone-new-tab). An unknown kind or
+  // blank key yields no link, so the stage stays plain.
   const locus = col.locus;
   const locusKey = locus && locus.field != null && row[locus.field] != null ? String(row[locus.field]) : "";
-  const locusHref =
-    locus && locus.link && locus.link.kind === "page" && locus.link.page ? pageHashHref(locus.link.page, locusKey) : "";
+  /** @param {any} label
+   * @returns {any} an anchor node for the locus stage, or null (→ plain label). */
+  const locusLabelNode = (label) => {
+    if (!locus || !locus.link || locusKey === "") return null;
+    if (locus.link.kind === "page" && locus.link.page) {
+      const href = pageHashHref(locus.link.page, locusKey);
+      return href === "" ? null : el("a", { class: "pc-link pc-pipe-label", href }, label);
+    }
+    if (locus.link.kind === "processExplorer") {
+      return explorerAnchor(label, locusKey, "pc-link pc-pipe-label");
+    }
+    return null;
+  };
   const track = el("div", {
     class: "pc-pipe",
     role: "list",
@@ -968,11 +1002,10 @@ function pipelineCell(col, row, text, subText, truncate, tdAttrs) {
     } else {
       cls = "pc-pipe-upcoming"; word = "upcoming";
     }
-    const isLocus = locusHref !== "" && (locus.stage != null ? String(s.key) === String(locus.stage) : i === activeIdx);
+    const atLocus = locus != null && (locus.stage != null ? String(s.key) === String(locus.stage) : i === activeIdx);
     const label = labelOf(s);
-    const labelNode = isLocus
-      ? el("a", { class: "pc-link pc-pipe-label", href: locusHref }, label)
-      : el("span", { class: "pc-pipe-label" }, label);
+    const locusNode = atLocus ? locusLabelNode(label) : null;
+    const labelNode = locusNode != null ? locusNode : el("span", { class: "pc-pipe-label" }, label);
     /** @type {Record<string, any>} */
     const attrs = { class: "pc-pipe-stage " + cls, role: "listitem", "aria-label": label + " \u2014 " + word };
     if (current) attrs["aria-current"] = "step";

package/src/runtime/core/modules/pages.test.ts

@@ -1561,7 +1561,26 @@ test("pipeline builds a locus link via the shared pageHashHref route builder, on
   assert.match(js, /const href = pageHashHref\(col\.link\.page, row\[col\.link\.keyField\]\)/);
   // The locus link uses it and the shared .pc-link class; blank key → "" → plain.
   assert.match(js, /pageHashHref\(locus\.link\.page, locusKey\)/);
-  assert.match(js, /el\("a", \{ class: "pc-link pc-pipe-label", href: locusHref \}, label\)/);
+  assert.match(js, /el\("a", \{ class: "pc-link pc-pipe-label", href \}, label\)/);
+});
+
+test("pipeline locus supports a processExplorer link routing to the console explorer via the shared explorerAnchor", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A pipeline column whose locus declares `link:{ kind:"processExplorer" }` links
+  // the locus stage to the console explorer for the row's process instance — via
+  // the SAME single-source explorerAnchor builder the grid link cell uses, so the
+  // href and the embedded-in-place / standalone-new-tab navigation can't drift.
+  assert.match(js, /function explorerAnchor\(label, key, cls\)/);
+  assert.match(js, /"\/console\/explorer\?instance="\s*\+\s*encodeURIComponent\(keyStr\)/);
+  assert.match(js, /hostNavigate\("processExplorer",\s*\{\s*instance:\s*keyStr\s*\}\)/);
+  // The pipeline locus branches to it on the processExplorer kind, reusing the
+  // .pc-pipe-label class; the grid link cell routes through the same builder.
+  assert.match(js, /locus\.link\.kind === "processExplorer"/);
+  assert.match(js, /return explorerAnchor\(label, locusKey, "pc-link pc-pipe-label"\)/);
+  assert.match(js, /explorerAnchor\(text, row\[col\.link\.keyField\], "pc-link"\)/);
+  // Unknown kind / blank key → no link → the stage stays plain (graceful).
+  assert.match(js, /if \(!locus \|\| !locus\.link \|\| locusKey === ""\) return null/);
 });
 
 test("pipeline exposes step semantics to assistive tech (role/list + aria-current)", async () => {