@nanobpm/urban 0.63.1 → 0.65.0

package/dist/context/binding/identity.js

@@ -0,0 +1,159 @@
+// Slice S1 (binding) — context *identity*: the private-per-app /
+// shared-on-same-name semantics.
+//
+// A context is named by its `(repo, ref)` pair. Two apps (or two Nano
+// instances) that name the SAME context — the same normalised repo and the same
+// ref — resolve to the SAME shared substrate; a distinct name stays private.
+// This module turns a binding into a stable, canonical **identity key** that
+// the resolver uses both to memoise in-process and to derive an on-disk
+// location, so "same name ⇒ same substrate" holds within a process AND across
+// processes/instances that share a cache root.
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+const SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
+const SCHEME_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+const SCP_LIKE = /^[\w.-]+@([\w.-]+):(.+)$/; // git@github.com:owner/name.git
+function stripGitSuffix(value) {
+    // Trim trailing slashes BEFORE stripping `.git` so a trailing-slash spelling
+    // (`owner/name.git/`, a URL pathname ending `.git/`) still has its `.git`
+    // suffix removed — otherwise `.git$` would not match and equivalent repo
+    // spellings would canonicalise to different identities (different substrates).
+    // Trim once more afterwards to drop any slash exposed by removing the suffix.
+    return value.replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
+}
+// A URL's scheme-default port is equivalent to omitting the port, so it must not
+// split identity. `URL` already strips the default port for the web schemes it
+// knows (http/https/ws/…), but NOT for git transports like ssh:// and git://, so
+// their defaults are normalised here explicitly.
+const DEFAULT_PORTS = {
+    "http:": "80",
+    "https:": "443",
+    "ssh:": "22",
+    "git:": "9418",
+    "ftp:": "21",
+};
+/**
+ * The canonical authority (`host` or `host:port`) for a scheme URL identity.
+ * Excludes any `user:pass@` userinfo (uses `hostname`, never `host`) so
+ * credentials never affect identity, and drops a scheme's DEFAULT port while
+ * retaining any NON-default port as a distinguishing factor.
+ */
+function canonicalAuthority(parsed) {
+    const host = parsed.hostname.toLowerCase();
+    const defaultPort = DEFAULT_PORTS[parsed.protocol.toLowerCase()];
+    if (parsed.port && parsed.port !== defaultPort) {
+        return `${host}:${parsed.port}`;
+    }
+    return host;
+}
+/**
+ * Resolve a `file://` URL to an absolute filesystem path, honouring the host
+ * component and percent-encoding. Falls back to naive `file://` stripping for a
+ * malformed URL so identity stays stable rather than throwing.
+ */
+function fileUrlToAbsPath(raw) {
+    try {
+        return resolvePath(fileURLToPath(raw));
+    }
+    catch {
+        return resolvePath(raw.slice("file://".length));
+    }
+}
+/**
+ * Classify a binding `repo` field into a concrete clone URL plus a normalised
+ * canonical form for identity. Public git is NOT hard-coded: local/`file://`
+ * paths and arbitrary git hosts are first-class, leaving a seam for a future
+ * PII/mutable or self-hosted substrate backend.
+ */
+function classifyRepo(repo) {
+    const raw = repo.trim();
+    // Local filesystem path or file:// URL — used for tests and self-hosted
+    // substrates. Canonicalised by absolute path so two spellings of one path
+    // share identity. `file://` URLs are parsed via `fileURLToPath` so the host
+    // component (e.g. `file://localhost/…`) and percent-encoding are handled and
+    // equivalent spellings map to one identity.
+    if (raw.startsWith("file://")) {
+        const abs = fileUrlToAbsPath(raw);
+        return { url: raw, canonical: `file:${abs}` };
+    }
+    if (raw.startsWith(".") || isAbsolute(raw)) {
+        const abs = resolvePath(raw);
+        return { url: abs, canonical: `file:${abs}` };
+    }
+    // owner/name shorthand ⇒ GitHub HTTPS clone URL.
+    if (SHORTHAND.test(raw)) {
+        const canonical = `github.com/${stripGitSuffix(raw).toLowerCase()}`;
+        return { url: `https://github.com/${stripGitSuffix(raw)}.git`, canonical };
+    }
+    // scp-like git URL: git@host:owner/name(.git)
+    const scp = SCP_LIKE.exec(raw);
+    if (scp) {
+        const host = scp[1].toLowerCase();
+        const path = stripGitSuffix(scp[2]).toLowerCase();
+        return { url: raw, canonical: `${host}/${path}` };
+    }
+    // scheme URL: https://, ssh://, git://, http://
+    if (SCHEME_URL.test(raw)) {
+        try {
+            const parsed = new URL(raw);
+            // Build the authority from `hostname` (never `host`) so any `user:pass@`
+            // userinfo is excluded — credentials never affect identity. The port is
+            // *normalised*, not dropped: a scheme's DEFAULT port collapses to the
+            // portless spelling (so `https://h:443/o/n` ≡ `https://h/o/n` and
+            // `ssh://h:22/o/n` ≡ `ssh://h/o/n`), but a NON-default port is retained as
+            // a distinguishing factor — two remotes on the same host but different
+            // ports are genuinely different repos and MUST NOT share a substrate.
+            const host = canonicalAuthority(parsed);
+            const path = stripGitSuffix(parsed.pathname).replace(/^\/+/, "").toLowerCase();
+            return { url: raw, canonical: `${host}/${path}` };
+        }
+        catch {
+            // Fall through to the opaque case below.
+        }
+    }
+    // Anything else: treat opaquely but still stable.
+    return { url: raw, canonical: stripGitSuffix(raw).toLowerCase() };
+}
+function toSlug(canonical, ref, hash) {
+    const readable = `${canonical}@${ref}`
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    // Suffix with the FULL identity key (sha256 hex), not a truncated prefix: the
+    // on-disk location is derived from the slug, so a truncated suffix would make
+    // two distinct keys collide onto one `localPath` (breaking "distinct names
+    // stay private") far sooner than the key itself collides. Deriving the suffix
+    // from the whole key keeps on-disk uniqueness exactly as strong as the
+    // in-process sharing key — a single source of truth, distinct keys ⇒ distinct
+    // slugs.
+    return `${readable || "context"}-${hash}`;
+}
+/**
+ * Compute the canonical {@link ContextIdentity} for a binding. Deterministic and
+ * pure: equal `(repo, ref)` names (after normalisation) always produce an equal
+ * `key` and `slug`. Distinct names are collision-resistant, not collision-proof:
+ * both `key` and `slug` are sha256-derived, so two distinct names collide only on
+ * a full sha256 collision (the `slug` embeds the whole `key`, so it is exactly as
+ * strong as the `key`).
+ */
+export function resolveContextIdentity(binding) {
+    const { url, canonical } = classifyRepo(binding.repo);
+    const ref = binding.ref.trim();
+    const canonicalName = `${canonical}#${ref}`;
+    const key = createHash("sha256").update(canonicalName, "utf8").digest("hex");
+    return { key, repo: url, ref, slug: toSlug(canonical, ref, key) };
+}
+/**
+ * The stable identity key of a binding — the sharing primitive. Two bindings
+ * resolve to the same shared substrate iff this returns the same value for
+ * both.
+ */
+export function contextIdentityKey(binding) {
+    return resolveContextIdentity(binding).key;
+}
+/** `true` iff two bindings name the same shared context (same substrate). */
+export function sameContext(a, b) {
+    return contextIdentityKey(a) === contextIdentityKey(b);
+}

package/dist/context/binding/index.d.ts

@@ -1 +1,5 @@
-export {};
+export { type ContextBinding, ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.ts";
+export { type ContextIdentity, contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.ts";
+export { type ResolvedContextHandle, type SubstrateBackend, type SubstrateResolveOptions, } from "./backend.ts";
+export { GitSubstrateBackend, type GitRunner, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.ts";
+export { ContextResolver, type ContextResolverOptions, type ResolveOptions, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.ts";

package/dist/context/binding/index.js

@@ -1 +1,14 @@
-export {};
+// @nanobpm/urban/context/binding — slice S1.
+//
+// The bindable `context` resource: the binding descriptor (`uses: context:
+// { repo, ref }`) plus local↔remote resolution to a resolved handle, with
+// private-per-app / shared-on-same-name identity semantics. This is one half of
+// the published contract nanobpm/nano-workforce#291 builds against.
+//
+// Downstream: S3 (git substrate/governance) and S4 (retrieval) consume the
+// ResolvedContextHandle; the SubstrateBackend interface is the seam for a
+// future PII/mutable or self-hosted backend.
+export { ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.js";
+export { contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.js";
+export { GitSubstrateBackend, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.js";
+export { ContextResolver, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.js";

package/dist/context/binding/resolver.d.ts

@@ -0,0 +1,61 @@
+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 declare function defaultContextCacheRoot(env?: Record<string, string | undefined>): string;
+/**
+ * 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 declare class ContextResolver {
+    #private;
+    constructor(options?: ContextResolverOptions);
+    /** The cache root this resolver clones into. */
+    get cacheRoot(): string;
+    /**
+     * 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.
+     */
+    resolve(binding: unknown, options?: ResolveOptions): Promise<ResolvedContextHandle>;
+}
+/**
+ * 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 declare function resolveContextBinding(binding: unknown, options?: ContextResolverOptions & ResolveOptions): Promise<ResolvedContextHandle>;

package/dist/context/binding/resolver.js

@@ -0,0 +1,125 @@
+// 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.js";
+import { resolveContextIdentity } from "./identity.js";
+import { GitSubstrateBackend } from "./git-backend.js";
+/**
+ * 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 = process.env) {
+    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() {
+    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 {
+    #cacheRoot;
+    #backend;
+    // 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.
+    #resolutions = new Map();
+    constructor(options = {}) {
+        // 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() {
+        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, options = {}) {
+        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: 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, options = {}) {
+    const { cacheRoot, backend, ...resolveOptions } = options;
+    return new ContextResolver({ cacheRoot, backend }).resolve(binding, resolveOptions);
+}