@nanobpm/urban 0.64.0 → 0.66.0

package/src/context/binding/backend.ts

@@ -0,0 +1,79 @@
+// Slice S1 (binding) — the resolution seam: types shared by the resolver and
+// any substrate backend.
+//
+// Resolution turns a validated binding into a concrete local working copy of
+// the substrate, returning a **resolved handle** (local path + repo/ref
+// identity). Downstream slices consume the handle: S3 (git substrate /
+// governance) writes append-via-commit into `localPath`, and S4 (retrieval)
+// reads from it. S1 owns clone/pull wiring ONLY — it exposes a clean handle and
+// deliberately contains no commit/PR/write or governance logic.
+//
+// The `SubstrateBackend` interface is the seam that keeps resolution from
+// hard-coding "the substrate is exclusively a public git repo": the default
+// backend is git, but a future PII/mutable or self-hosted backend can implement
+// the same interface without touching the resolver or callers.
+
+import type { ContextIdentity } from "./identity.ts";
+
+/**
+ * A concrete, resolved handle to a context substrate: a local working copy
+ * pinned to `ref`, plus its repo/ref identity. This is the value S3 and S4
+ * build on.
+ */
+export interface ResolvedContextHandle {
+  /** Canonical identity of the bound context (see {@link ContextIdentity}). */
+  readonly identity: ContextIdentity;
+  /** Absolute path to the local working copy of the substrate. */
+  readonly localPath: string;
+  /** The concrete substrate repo URL/path that was cloned. */
+  readonly repo: string;
+  /**
+   * The ref the working copy is pinned to. This records the *intended* pin
+   * (`identity.ref`). It is a re-verified fact only when the working copy was
+   * just cloned or refreshed; on the `refresh: false` reuse path the existing
+   * working copy is trusted as-is and NOT re-pinned, so `ref` reflects the
+   * requested pin rather than a freshly-validated checkout (see
+   * {@link SubstrateResolveOptions.refresh}).
+   */
+  readonly ref: string;
+}
+
+/** Options passed to a backend when materialising a substrate working copy. */
+export interface SubstrateResolveOptions {
+  /**
+   * Absolute path the working copy MUST live at. The resolver derives this
+   * deterministically from the identity so that the same name maps to the same
+   * on-disk substrate (shared-on-same-name). A backend rejects a relative path
+   * (see {@link SubstrateBackend.materialise}).
+   */
+  readonly localPath: string;
+  /**
+   * When `true`, refresh an already-present working copy (fetch + re-pin to
+   * `ref`). When `false`, an existing working copy is reused as-is without
+   * touching the network AND without running git at all — it is trusted as the
+   * requested substrate; no fetch, pin, or checkout validation is enforced, so
+   * the returned handle's `ref` reflects the intended pin rather than a
+   * re-verified checkout. Defaults to `true`.
+   */
+  readonly refresh?: boolean;
+}
+
+/**
+ * A pluggable substrate backend. The default is git (see `./git-backend.ts`),
+ * but this interface is the seam for a future PII/mutable or self-hosted
+ * backend — the resolver and its callers depend only on this contract.
+ */
+export interface SubstrateBackend {
+  /**
+   * Materialise (clone on first use, refresh thereafter) the substrate for
+   * `identity` at `options.localPath`, pinned to `identity.ref`, and return the
+   * resolved handle. The pin is enforced on the clone and `refresh: true` paths;
+   * `refresh: false` reuses an existing working copy as-is without re-pinning
+   * (see {@link SubstrateResolveOptions.refresh}). `options.localPath` must be
+   * absolute; a relative path is rejected before any git command runs.
+   */
+  materialise(
+    identity: ContextIdentity,
+    options: SubstrateResolveOptions,
+  ): Promise<ResolvedContextHandle>;
+}

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

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  ContextBindingError,
+  isContextBinding,
+  parseContextBinding,
+} from "./descriptor.ts";
+
+test("parseContextBinding accepts a well-formed { repo, ref } and trims", () => {
+  const binding = parseContextBinding({ repo: "  owner/name  ", ref: "  main  " });
+  assert.deepEqual(binding, { repo: "owner/name", ref: "main" });
+});
+
+test("parseContextBinding ignores unknown extra fields (forward-compatible)", () => {
+  const binding = parseContextBinding({ repo: "owner/name", ref: "v1", future: 42 });
+  assert.deepEqual(binding, { repo: "owner/name", ref: "v1" });
+});
+
+test("parseContextBinding rejects non-objects with a clear message", () => {
+  assert.throws(() => parseContextBinding(null), ContextBindingError);
+  assert.throws(() => parseContextBinding("owner/name#main"), /must be an object/);
+  assert.throws(() => parseContextBinding(undefined), ContextBindingError);
+});
+
+test("parseContextBinding rejects arrays as not-an-object (typeof [] === 'object')", () => {
+  assert.throws(() => parseContextBinding([]), /must be an object/);
+  assert.throws(() => parseContextBinding(["owner/name", "main"]), /must be an object/);
+  assert.equal(isContextBinding([]), false);
+});
+
+test("parseContextBinding names arrays as 'array', not 'object', in the error message", () => {
+  assert.throws(() => parseContextBinding([]), /received array/);
+  assert.throws(() => parseContextBinding(["owner/name", "main"]), /received array/);
+});
+
+test("parseContextBinding rejects a missing or empty repo", () => {
+  assert.throws(() => parseContextBinding({ ref: "main" }), /"repo" is required/);
+  assert.throws(() => parseContextBinding({ repo: "   ", ref: "main" }), /"repo" is required/);
+  assert.throws(() => parseContextBinding({ repo: 5, ref: "main" }), /"repo" is required/);
+});
+
+test("parseContextBinding rejects a missing or empty ref", () => {
+  assert.throws(() => parseContextBinding({ repo: "owner/name" }), /"ref" is required/);
+  assert.throws(() => parseContextBinding({ repo: "owner/name", ref: "" }), /"ref" is required/);
+});
+
+test("isContextBinding is a total type guard", () => {
+  assert.equal(isContextBinding({ repo: "owner/name", ref: "main" }), true);
+  assert.equal(isContextBinding({ repo: "owner/name" }), false);
+  assert.equal(isContextBinding(42), false);
+});

package/src/context/binding/descriptor.ts

@@ -0,0 +1,108 @@
+// Slice S1 (binding) — the binding *descriptor*: the manifest shape
+// `uses: context: { repo, ref }`.
+//
+// This is one half of the published contract that the consumer repo
+// (nanobpm/nano-workforce#291) builds against, so the shape and the exported
+// type name are deliberately **minimal and version-friendly**: a context is
+// named by the substrate `repo` it lives in and the `ref` it is pinned to, and
+// nothing more is required to bind it. Additional, backward-compatible fields
+// may be layered on later without breaking existing manifests.
+
+/**
+ * A declared binding to an Urban **context** resource — the manifest shape
+ * authored under `uses: { context: { repo, ref } }`.
+ *
+ * A context is a git-backed, governed memory substrate (see ADR 0051 — a
+ * context behaves like an Urban datasource: a declared, bindable resource). The
+ * pair `(repo, ref)` is the *name* of the context: two apps that declare the
+ * same pair bind the same shared substrate; a different pair is a different,
+ * private context (see {@link contextIdentityKey} in `./identity.ts`).
+ *
+ * The type is intentionally small and additive-friendly — treat it as a stable
+ * contract. Unknown extra fields on input are tolerated by the validator but
+ * are not part of the guaranteed shape.
+ */
+export interface ContextBinding {
+  /**
+   * The substrate repository that stores the context.
+   *
+   * Accepts an `owner/name` GitHub shorthand (resolved to
+   * `https://github.com/owner/name.git`), a full git URL
+   * (`https://…`, `ssh://…`, `git@host:owner/name.git`), or a local/`file://`
+   * path (used chiefly for tests and self-hosted substrates). A local path must
+   * be spelled unambiguously so it is not mistaken for the `owner/name`
+   * shorthand: use an absolute path, a `file://…` URL, or a `./`- or
+   * `../`-prefixed relative path. A bare relative path such as `subdir/repo`
+   * matches the shorthand and is treated as GitHub, not a local path. The MVP
+   * substrate is git-only, but resolution does not hard-code *public* git — see
+   * the backend seam in `./resolver.ts`.
+   */
+  readonly repo: string;
+
+  /**
+   * The ref the context is **pinned** to: a branch, tag, or commit SHA. First
+   * resolution clones the substrate; later resolutions refresh it to this ref.
+   */
+  readonly ref: string;
+}
+
+/** Error thrown when an untrusted value is not a valid {@link ContextBinding}. */
+export class ContextBindingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ContextBindingError";
+  }
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate an untrusted value as a {@link ContextBinding}, throwing a
+ * {@link ContextBindingError} with a clear, field-scoped message on failure.
+ *
+ * Returns a *normalised* binding: `repo` and `ref` are trimmed. Extra fields on
+ * the input object are ignored (forward-compatible) — only `repo` and `ref` are
+ * carried through.
+ */
+export function parseContextBinding(value: unknown): ContextBinding {
+  if (!isObjectRecord(value)) {
+    throw new ContextBindingError(
+      `context binding must be an object of the form { repo, ref }, received ${describe(value)}`,
+    );
+  }
+  const record = value;
+  if (!("repo" in record) || !isNonEmptyString(record.repo)) {
+    throw new ContextBindingError(
+      `context binding "repo" is required and must be a non-empty string, received ${describe(record.repo)}`,
+    );
+  }
+  if (!("ref" in record) || !isNonEmptyString(record.ref)) {
+    throw new ContextBindingError(
+      `context binding "ref" is required and must be a non-empty string, received ${describe(record.ref)}`,
+    );
+  }
+  return { repo: record.repo.trim(), ref: record.ref.trim() };
+}
+
+/** Type guard: `true` iff `value` is a valid {@link ContextBinding}. */
+export function isContextBinding(value: unknown): value is ContextBinding {
+  try {
+    parseContextBinding(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function describe(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

package/src/context/binding/git-backend.ts

@@ -0,0 +1,368 @@
+// Slice S1 (binding) — the default git substrate backend: clone on first use,
+// fetch + re-pin to `ref` thereafter. No write/commit/PR logic lives here (that
+// is S3); this only materialises a working copy pinned to the requested ref.
+
+import { execFile } from "node:child_process";
+import { lstat, mkdir, readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import type { ContextIdentity } from "./identity.ts";
+import type {
+  ResolvedContextHandle,
+  SubstrateBackend,
+  SubstrateResolveOptions,
+} from "./backend.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** Runs a git subcommand. Injectable so tests can stub git without a network. */
+export type GitRunner = (args: readonly string[], cwd?: string) => Promise<string>;
+
+/** Error thrown when a git operation fails during resolution. */
+export class SubstrateResolveError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "SubstrateResolveError";
+  }
+}
+
+/**
+ * Redact URL userinfo (`scheme://user:pass@host` → `scheme://***@host`) from a
+ * single git argv token. A manifest-supplied remote URL can embed credentials
+ * (e.g. `https://x-access-token:TOKEN@github.com/owner/repo`); scrubbing them
+ * before the argv is placed in an error message keeps secrets out of logs,
+ * telemetry, and user-facing errors. The raw, unredacted args stay on the
+ * error's `cause` for local debugging only.
+ */
+export const redactUrlUserinfo = (arg: string): string =>
+  arg.replace(/(\/\/)[^/@\s]+@/g, "$1***@");
+
+/**
+ * `git` runs against a working copy that lives in a shared, potentially
+ * tampered-with cache. Commands like `fetch` and especially `checkout` execute
+ * local hooks (e.g. `post-checkout`, `post-merge`) from the working copy's
+ * `.git/hooks` if they exist — so a planted hook in a poisoned cache entry is a
+ * code-execution vector. Pinning `core.hooksPath` to a path that cannot contain
+ * an executable hook (`/dev/null` is not a directory, so `<hooksPath>/<hook>`
+ * never resolves) disables hooks entirely for every automated invocation, so
+ * resolution can never execute a script from the cached substrate. Single
+ * source of truth for the flag: prepended by {@link hardenedGitArgs} to every
+ * argv the default runner spawns. `-c <name>=<value>` must precede the
+ * subcommand, so it is prepended (not appended).
+ */
+export const GIT_SAFETY_CONFIG: readonly string[] = ["-c", "core.hooksPath=/dev/null"];
+
+/** Prepend the hook-disabling safety config to a git argv (single source of truth). */
+export const hardenedGitArgs = (args: readonly string[]): string[] => [
+  ...GIT_SAFETY_CONFIG,
+  ...args,
+];
+
+const defaultGitRunner: GitRunner = async (args, cwd) => {
+  const hardened = hardenedGitArgs(args);
+  try {
+    const { stdout } = await execFileAsync("git", hardened, {
+      cwd,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    return stdout;
+  } catch (cause) {
+    const label = `git ${hardened.map(redactUrlUserinfo).join(" ")}`;
+    throw new SubstrateResolveError(`substrate git command failed: ${label}`, { cause });
+  }
+};
+
+/**
+ * True iff `path` exists as any filesystem entry. Uses `lstat` (not `stat`) so
+ * the entry itself is inspected without following symlinks — a symlink counts as
+ * a pre-existing entry even when its target is missing (a dangling symlink),
+ * which `git clone` would otherwise fail on with an opaque error.
+ *
+ * Only a genuine "not there" (`ENOENT`/`ENOTDIR`) counts as absent; any other
+ * error (e.g. `EACCES`/`EPERM` on an existing-but-unreadable entry) is
+ * re-thrown rather than silently reported as "missing", so an unreadable path
+ * is never mistaken for a clean slate to clone into.
+ */
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (cause) {
+    if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+      return false;
+    }
+    throw new SubstrateResolveError(`substrate path is not accessible: ${path}`, { cause });
+  }
+}
+
+function isNodeErrno(error: unknown, code: string): boolean {
+  return (
+    error instanceof Error && "code" in error && error.code === code
+  );
+}
+
+/**
+ * True iff `path` exists and is itself a symlink (inspected with `lstat`, so the
+ * link — not its target — is examined). A missing entry (`ENOENT`/`ENOTDIR`) is
+ * not a symlink; any other error is re-thrown rather than silently swallowed.
+ */
+async function isSymlink(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isSymbolicLink();
+  } catch (cause) {
+    if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+      return false;
+    }
+    throw new SubstrateResolveError(`substrate path is not accessible: ${path}`, { cause });
+  }
+}
+
+/**
+ * True iff `path` exists and is a real directory (inspected with `lstat`, so a
+ * symlink to a directory does not count). A missing entry (`ENOENT`/`ENOTDIR`)
+ * is not a directory; any other error is re-thrown rather than silently
+ * swallowed, so an unreadable path is never mistaken for "not a directory".
+ */
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isDirectory();
+  } catch (cause) {
+    if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+      return false;
+    }
+    throw new SubstrateResolveError(`substrate path is not accessible: ${path}`, { cause });
+  }
+}
+
+/** True iff `child` is `root` itself or nested within it (no `..`/absolute escape). */
+function isWithin(root: string, child: string): boolean {
+  const rel = relative(root, child);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+/**
+ * A `.git` *file* (git worktree/submodule marker) points at the real gitdir via
+ * a `gitdir: <path>` line rather than being a `.git` directory. Trusting such a
+ * working copy as "already cloned" is only safe when that gitdir stays inside
+ * the cache root: a marker whose `gitdir:` resolves OUTSIDE the cache root would
+ * make every subsequent `git fetch`/`checkout` operate on an out-of-cache
+ * repository — a cache escape of the same class as a `.git` symlink.
+ *
+ * A string-only containment check is insufficient: an in-cache `gitdir:` path
+ * can itself be a *symlink* to an out-of-cache repository (git follows it), and a
+ * broken/missing `gitdir:` target must not be trusted as a clone either. So the
+ * resolved target is canonicalised through `realpath` (collapsing every symlink
+ * along the path — including the gitdir itself) and the cache root is likewise
+ * canonicalised, before checking containment. Resolves when the marker is
+ * well-formed AND its fully-resolved gitdir is a real directory within the
+ * canonical `cacheRoot`. Otherwise it throws a `SubstrateResolveError` whose
+ * message names the *actual* reason — a malformed marker (no `gitdir:` line), a
+ * missing/broken target, one resolving to a non-directory, or one that genuinely
+ * escapes the cache root — rather than collapsing every rejection into a single
+ * "points outside the cache root" message that would mislead incident triage.
+ */
+async function assertGitFileMarkerWithinRoot(
+  gitFile: string,
+  localPath: string,
+  cacheRoot: string,
+): Promise<void> {
+  // Read the marker file through the same error-wrapping discipline as the rest
+  // of this module's access guards: a filesystem failure (e.g. EACCES/EPERM on
+  // an unreadable marker, or a race that removes it) surfaces as a
+  // SubstrateResolveError rather than leaking a raw Node error to the caller.
+  let content: string;
+  try {
+    content = await readFile(gitFile, "utf8");
+  } catch (cause) {
+    throw new SubstrateResolveError(`substrate .git marker is not readable: ${gitFile}`, { cause });
+  }
+  const match = content.match(/^gitdir:[ \t]*(.+?)[ \t]*$/m);
+  if (match === null) {
+    throw new SubstrateResolveError(
+      `substrate .git marker is malformed (no \`gitdir:\` line): ${gitFile}`,
+    );
+  }
+  // A relative `gitdir:` is interpreted by git relative to the working copy, so
+  // resolve it against `localPath` before checking cache-root containment.
+  const target = resolve(localPath, match[1]);
+  // Canonicalise both sides through `realpath` so any symlink along the path —
+  // notably an in-cache `gitdir:` symlinked to an out-of-cache repository that a
+  // string check would wrongly trust — is collapsed before the comparison. A
+  // missing/broken target (ENOENT/ENOTDIR) is not a real gitdir and is rejected.
+  let realTarget: string;
+  let realRoot: string;
+  try {
+    realTarget = await realpath(target);
+    realRoot = await realpath(cacheRoot);
+  } catch (cause) {
+    if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+      throw new SubstrateResolveError(
+        `substrate .git gitdir target is missing or broken: ${target}`,
+        { cause },
+      );
+    }
+    throw new SubstrateResolveError(`substrate .git target is not accessible: ${target}`, { cause });
+  }
+  if (!isWithin(realRoot, realTarget)) {
+    throw new SubstrateResolveError(
+      `substrate .git points outside the cache root and would escape it: ${gitFile}`,
+    );
+  }
+  if (!(await isDirectory(realTarget))) {
+    throw new SubstrateResolveError(
+      `substrate .git gitdir target is not a directory: ${realTarget}`,
+    );
+  }
+}
+
+/**
+ * The default, git-only substrate backend. Clones the substrate on first use
+ * and, on subsequent resolutions, fetches and re-pins the working copy to the
+ * requested ref (branch tip, tag, or SHA) without clobbering unrelated state.
+ */
+export class GitSubstrateBackend implements SubstrateBackend {
+  readonly #git: GitRunner;
+
+  constructor(gitRunner: GitRunner = defaultGitRunner) {
+    this.#git = gitRunner;
+  }
+
+  /**
+   * Materialise the working copy at `options.localPath`: clone on first use,
+   * fetch + re-pin thereafter. `refresh: false` reuses an already-present
+   * working copy as-is — no fetch, no re-pin, no git invocation — so the
+   * returned handle's `ref` records the intended pin rather than a re-validated
+   * checkout (see {@link SubstrateResolveOptions.refresh}).
+   *
+   * Known limitation (deferred past slice S1): materialisation is NOT guarded by
+   * an inter-process lock. The resolver's single-flight coalescing only
+   * serialises resolves *within one process*, so two Nano instances that share a
+   * `cacheRoot` and resolve the same context concurrently can race the
+   * first-use `mkdir → clone → pin` (or `fetch → pin`) sequence for the same
+   * `localPath` — one process may observe the path as absent or
+   * partially-initialised while the other is still cloning, surfacing a spurious
+   * "not a git working copy" error or (worse) a half-written working copy.
+   * Cross-process sharing is therefore reliable only once the substrate is
+   * already materialised; the concurrent *first-use* case is a documented gap. A
+   * follow-up slice will add a per-`localPath` inter-process lock (bounded retry
+   * + stale-lock reclamation) to close it. See PR #309 / nano-ide binding notes.
+   */
+  async materialise(
+    identity: ContextIdentity,
+    options: SubstrateResolveOptions,
+  ): Promise<ResolvedContextHandle> {
+    const { localPath } = options;
+    const refresh = options.refresh ?? true;
+    // `SubstrateResolveOptions.localPath` is contractually absolute — the resolver
+    // derives it that way. Enforce it here too: a relative `localPath` from a
+    // direct backend caller would run clone/fetch/checkout relative to the process
+    // CWD, at an unpredictable location that also sidesteps the cache-root
+    // containment guards below. Reject it before any git command runs.
+    if (!isAbsolute(localPath)) {
+      throw new SubstrateResolveError(
+        `substrate localPath must be absolute: ${localPath}`,
+      );
+    }
+    // A symlink AT `localPath` would make every subsequent `join(localPath, …)`
+    // and git invocation operate on the link's target — which can point outside
+    // the cache root at an arbitrary pre-existing working copy. Reject it before
+    // it is ever trusted as a clone, so resolution can never escape the cache
+    // root via a planted symlink.
+    if (await isSymlink(localPath)) {
+      throw new SubstrateResolveError(
+        `substrate path is a symlink and would escape the cache root: ${localPath}`,
+      );
+    }
+    // Likewise, a `.git` symlink *inside* an otherwise-legitimate `localPath`
+    // would make git treat an arbitrary out-of-cache gitdir as this working
+    // copy's repository (cache escape). A real clone never has a symlinked
+    // `.git`, so reject one before it is trusted as "already cloned".
+    const gitDir = join(localPath, ".git");
+    if (await isSymlink(gitDir)) {
+      throw new SubstrateResolveError(
+        `substrate .git is a symlink and would escape the cache root: ${gitDir}`,
+      );
+    }
+    // A genuine clone's `.git` is a *directory*. A `.git` that exists as
+    // anything else is a git worktree/submodule marker *file* pointing at a real
+    // gitdir elsewhere, which must be validated before it is trusted — an
+    // out-of-cache gitdir would be a cache escape of the same class as the
+    // `.git`-symlink case above.
+    let alreadyCloned = await isDirectory(gitDir);
+    if (!alreadyCloned && (await pathExists(gitDir))) {
+      // `.git` exists but is not a directory: a git worktree/submodule marker
+      // *file* pointing at a real gitdir elsewhere. Trust it as "already cloned"
+      // only when that gitdir is well-formed and stays inside the cache root;
+      // otherwise this throws a precise error naming the actual reason (malformed
+      // marker, missing/broken target, non-directory, or genuine cache escape).
+      await assertGitFileMarkerWithinRoot(gitDir, localPath, dirname(localPath));
+      alreadyCloned = true;
+    }
+
+    if (!alreadyCloned) {
+      // A pre-existing entry at `localPath` that is not a git working copy — a
+      // non-git directory, or a file/symlink — would make `git clone` fail with
+      // an opaque wrapped error. Detect any such entry and report it clearly.
+      if (await pathExists(localPath)) {
+        throw new SubstrateResolveError(
+          `substrate path already exists but is not a git working copy: ${localPath}`,
+        );
+      }
+      await mkdir(dirname(localPath), { recursive: true });
+      // `--` separates options from operands so a `repo` starting with `-`
+      // (untrusted manifest input) can't be parsed as a git option.
+      await this.#git(["clone", "--", identity.repo, localPath]);
+      await this.#pin(localPath, identity.ref);
+    } else if (refresh) {
+      // Cache reuse must NOT trust the recorded `origin`: an equivalent repo
+      // spelling with different auth (e.g. SSH vs HTTPS/token) won't take effect
+      // once the entry exists, and a tampered cache entry could point `origin`
+      // at an attacker-chosen remote that the resolver would then fetch from.
+      // Re-point `origin` at the manifest's `identity.repo` before every fetch
+      // so refreshes always operate on the expected remote. `--` separates
+      // options from the operand so a `repo` starting with `-` (untrusted
+      // manifest input) can't be parsed as a git option.
+      await this.#git(["remote", "set-url", "origin", "--", identity.repo], localPath);
+      await this.#git(["fetch", "--tags", "--prune", "--force", "origin"], localPath);
+      await this.#pin(localPath, identity.ref);
+    }
+
+    // On the `alreadyCloned && !refresh` path neither branch above ran, so the
+    // existing working copy is returned untouched (no fetch/pin). `ref` here is
+    // therefore the *requested* pin, not a re-verified checkout — the documented
+    // `refresh: false` contract (trust the existing working copy as-is).
+    return { identity, localPath, repo: identity.repo, ref: identity.ref };
+  }
+
+  /**
+   * Pin the working copy to `ref`. If `ref` names a remote branch, pin to the
+   * fetched remote tip (so a refresh moves the branch forward); otherwise treat
+   * `ref` as a tag or SHA and check it out detached.
+   */
+  async #pin(cwd: string, ref: string): Promise<void> {
+    const remoteBranch = await this.#hasRef(cwd, `origin/${ref}`);
+    if (remoteBranch) {
+      await this.#git(["checkout", "--force", "-B", ref, `origin/${ref}`], cwd);
+    } else {
+      // `--detach` pins to the exact commit rather than attaching to any local
+      // branch that happens to share `ref`'s name; `--end-of-options` stops an
+      // option-style `ref` from being parsed as a git flag.
+      await this.#git(["checkout", "--force", "--detach", "--end-of-options", ref], cwd);
+    }
+  }
+
+  async #hasRef(cwd: string, ref: string): Promise<boolean> {
+    try {
+      // `--end-of-options` stops an option-style `ref` (manifest-controlled)
+      // from being parsed as a git flag — the same injection guard used by the
+      // `clone`/`checkout` paths.
+      await this.#git(
+        ["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`],
+        cwd,
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}