@nanobpm/urban 0.63.1 → 0.65.0

package/src/context/binding/identity.test.ts

@@ -0,0 +1,165 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolve as resolvePath } from "node:path";
+import {
+  contextIdentityKey,
+  resolveContextIdentity,
+  sameContext,
+} from "./identity.ts";
+
+test("same repo+ref ⇒ same identity key (shared-on-same-name)", () => {
+  const a = { repo: "owner/name", ref: "main" };
+  const b = { repo: "owner/name", ref: "main" };
+  assert.equal(contextIdentityKey(a), contextIdentityKey(b));
+  assert.equal(sameContext(a, b), true);
+});
+
+test("a different ref is a distinct, private context", () => {
+  const a = { repo: "owner/name", ref: "main" };
+  const b = { repo: "owner/name", ref: "release" };
+  assert.notEqual(contextIdentityKey(a), contextIdentityKey(b));
+  assert.equal(sameContext(a, b), false);
+});
+
+test("a different repo is a distinct, private context", () => {
+  const a = { repo: "owner/name", ref: "main" };
+  const b = { repo: "owner/other", ref: "main" };
+  assert.equal(sameContext(a, b), false);
+});
+
+test("shorthand and equivalent HTTPS URL normalise to the same identity", () => {
+  const shorthand = resolveContextIdentity({ repo: "Owner/Name", ref: "main" });
+  const url = resolveContextIdentity({
+    repo: "https://github.com/owner/name.git",
+    ref: "main",
+  });
+  assert.equal(shorthand.key, url.key);
+});
+
+test("a trailing slash after .git does not fork identity (canonical drift guard)", () => {
+  // `stripGitSuffix` must remove `.git` even when a trailing slash follows it,
+  // or `…/name.git/` canonicalises to a different substrate than `…/name`.
+  const plain = resolveContextIdentity({ repo: "https://github.com/owner/name", ref: "main" });
+  const dotGitSlash = resolveContextIdentity({
+    repo: "https://github.com/owner/name.git/",
+    ref: "main",
+  });
+  const scpSlash = resolveContextIdentity({ repo: "git@github.com:owner/name.git/", ref: "main" });
+  assert.equal(dotGitSlash.key, plain.key);
+  assert.equal(scpSlash.key, plain.key);
+});
+
+test("shorthand resolves to a concrete GitHub HTTPS clone URL", () => {
+  const identity = resolveContextIdentity({ repo: "owner/name", ref: "main" });
+  assert.equal(identity.repo, "https://github.com/owner/name.git");
+});
+
+test("scp-like and https URLs for the same repo share identity", () => {
+  const scp = resolveContextIdentity({ repo: "git@github.com:owner/name.git", ref: "v2" });
+  const https = resolveContextIdentity({ repo: "https://github.com/owner/name", ref: "v2" });
+  assert.equal(scp.key, https.key);
+});
+
+test("ssh://, scp-like and https URLs for one repo all share identity", () => {
+  const ssh = resolveContextIdentity({ repo: "ssh://git@github.com/owner/name.git", ref: "v2" });
+  const scp = resolveContextIdentity({ repo: "git@github.com:owner/name.git", ref: "v2" });
+  const https = resolveContextIdentity({ repo: "https://github.com/owner/name", ref: "v2" });
+  assert.equal(ssh.key, scp.key);
+  assert.equal(ssh.key, https.key);
+});
+
+test("embedded credentials and explicit default port do not affect identity", () => {
+  const plain = resolveContextIdentity({ repo: "https://github.com/owner/name.git", ref: "main" });
+  const creds = resolveContextIdentity({
+    repo: "https://user:token@github.com/owner/name.git",
+    ref: "main",
+  });
+  const port = resolveContextIdentity({
+    repo: "https://github.com:443/owner/name.git",
+    ref: "main",
+  });
+  assert.equal(creds.key, plain.key);
+  assert.equal(port.key, plain.key);
+});
+
+test("ssh:// explicit default port (22) does not affect identity", () => {
+  const plain = resolveContextIdentity({ repo: "ssh://git@github.com/owner/name.git", ref: "main" });
+  const port = resolveContextIdentity({
+    repo: "ssh://git@github.com:22/owner/name.git",
+    ref: "main",
+  });
+  assert.equal(port.key, plain.key);
+});
+
+test("non-default ports produce DISTINCT identities (no cross-repo collision)", () => {
+  const plain = resolveContextIdentity({ repo: "https://host.example/owner/name.git", ref: "main" });
+  const alt = resolveContextIdentity({
+    repo: "https://host.example:8443/owner/name.git",
+    ref: "main",
+  });
+  const other = resolveContextIdentity({
+    repo: "https://host.example:9443/owner/name.git",
+    ref: "main",
+  });
+  assert.notEqual(alt.key, plain.key);
+  assert.notEqual(alt.key, other.key);
+  // ssh non-default ports must distinguish too.
+  const ssh = resolveContextIdentity({ repo: "ssh://git@host.example/owner/name.git", ref: "main" });
+  const sshPort = resolveContextIdentity({
+    repo: "ssh://git@host.example:2222/owner/name.git",
+    ref: "main",
+  });
+  assert.notEqual(ssh.key, sshPort.key);
+});
+
+test("local file paths canonicalise by absolute path", () => {
+  const relative = resolveContextIdentity({ repo: "./sub/../sub/repo", ref: "main" });
+  const absolute = resolveContextIdentity({
+    repo: resolvePath("sub/repo"),
+    ref: "main",
+  });
+  const fileUrl = resolveContextIdentity({
+    repo: `file://${resolvePath("sub/repo")}`,
+    ref: "main",
+  });
+  assert.equal(relative.key, absolute.key);
+  assert.equal(absolute.key, fileUrl.key);
+});
+
+test("file:// host component and percent-encoding canonicalise to one identity", () => {
+  const abs = resolvePath("sub/repo");
+  const plain = resolveContextIdentity({ repo: `file://${abs}`, ref: "main" });
+  // `file://localhost/…` (explicit localhost host) is equivalent to `file:///…`.
+  const localhost = resolveContextIdentity({ repo: `file://localhost${abs}`, ref: "main" });
+  assert.equal(plain.key, localhost.key);
+});
+
+test("percent-encoded file:// path canonicalises to the decoded path identity", () => {
+  const dir = resolvePath("with space/repo");
+  const decoded = resolveContextIdentity({ repo: `file://${dir}`, ref: "main" });
+  const encoded = resolveContextIdentity({
+    repo: `file://${dir.replace(/ /g, "%20")}`,
+    ref: "main",
+  });
+  assert.equal(decoded.key, encoded.key);
+});
+
+test("slug is filesystem-safe and identity-stable", () => {
+  const a = resolveContextIdentity({ repo: "owner/name", ref: "feature/x" });
+  const b = resolveContextIdentity({ repo: "owner/name", ref: "feature/x" });
+  assert.equal(a.slug, b.slug);
+  assert.match(a.slug, /^[a-z0-9-]+$/);
+});
+
+test("slug suffix is the full identity key ⇒ distinct keys never share a localPath", () => {
+  // The on-disk working copy is `join(cacheRoot, slug)`, so the slug's uniqueness
+  // must be exactly as strong as the identity key — a truncated hash suffix would
+  // let two distinct keys collide onto one directory. Guard that the slug embeds
+  // the whole sha256 key (64 hex chars), not a truncated prefix.
+  const identity = resolveContextIdentity({ repo: "owner/name", ref: "main" });
+  assert.match(identity.key, /^[0-9a-f]{64}$/);
+  assert.ok(
+    identity.slug.endsWith(`-${identity.key}`),
+    "slug must be suffixed with the full identity key",
+  );
+});

package/src/context/binding/identity.ts

@@ -0,0 +1,206 @@
+// 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";
+import type { ContextBinding } from "./descriptor.ts";
+
+/**
+ * The resolved, canonical identity of a context binding.
+ *
+ * `key` is a stable, collision-resistant string: two bindings share a substrate
+ * **iff** their `key`s are equal. `repo` is the concrete clone URL derived from
+ * the binding's (possibly shorthand) `repo`, and `ref` is the pinned ref.
+ */
+export interface ContextIdentity {
+  /**
+   * Stable canonical identity key. Equal keys ⇒ same shared substrate; distinct
+   * keys ⇒ private substrates. Safe to use as a map key.
+   */
+  readonly key: string;
+  /** The concrete clone URL (or local/`file://` path) for the substrate. */
+  readonly repo: string;
+  /** The pinned ref (branch / tag / SHA). */
+  readonly ref: string;
+  /**
+   * Filesystem-safe directory name derived deterministically from {@link key}.
+   * Two identities with the same key yield the same directory name, so a shared
+   * cache root gives them the same on-disk working copy.
+   */
+  readonly slug: string;
+}
+
+const SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
+const SCHEME_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+const SCP_LIKE = /^[\w.-]+@([\w.-]+):(.+)$/; // git@github.com:owner/name.git
+
+interface ClassifiedRepo {
+  /** URL/path git can clone from. */
+  readonly url: string;
+  /** Normalised canonical string used for identity (never the clone URL). */
+  readonly canonical: string;
+}
+
+function stripGitSuffix(value: string): string {
+  // 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: Record<string, string> = {
+  "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: URL): string {
+  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: string): string {
+  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: string): ClassifiedRepo {
+  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: string, ref: string, hash: string): string {
+  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: ContextBinding): ContextIdentity {
+  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: ContextBinding): string {
+  return resolveContextIdentity(binding).key;
+}
+
+/** `true` iff two bindings name the same shared context (same substrate). */
+export function sameContext(a: ContextBinding, b: ContextBinding): boolean {
+  return contextIdentityKey(a) === contextIdentityKey(b);
+}

package/src/context/binding/index.ts

@@ -1,2 +1,46 @@
-// Slice S1 (binding) — owner replaces this placeholder barrel.
-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 {
+  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";