@stravica-ai/digital-operator-pa 0.1.26 → 0.1.28

package/dist/engineering-pa-library-cli/src/config.mjs

@@ -0,0 +1,239 @@
+// config.mjs — read + validate the `library.*` block in
+// operator/config/preferences.json (with the standard preferences.local.json
+// overlay applied on top).
+//
+// Spec §5.1 (remote-library-spec.md):
+//   - mode is EXPLICIT (`library.mode`), never auto-detected
+//   - mode=remote with missing endpoint or key REFUSES to boot; there is
+//     NO silent fallback to SIMPLE (falling back is a data-loss path)
+//
+// Implementation notes:
+//   - The reader mirrors the platform's overlay-aware `readPreferences`
+//     shape (shallow merge; overlay wins; missing/malformed = null)
+//     rather than importing it, so the tool has no runtime coupling to
+//     the installed `@stravica-ai/digital-operator-pa` package layout.
+//   - Consumers pass `{ repoRoot }` or the resolved paths; both surfaces
+//     are seams for tests.
+
+import { readFileSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// operator/extensions/tools/library-cli/src/ → up five levels to the repo root.
+export const DEFAULT_REPO_ROOT = resolve(__dirname, '..', '..', '..', '..', '..');
+
+export class LibraryConfigError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'LibraryConfigError';
+    this.code = code;
+    this.exitCode = 1; // usage / configuration error (tooling exit-code contract)
+  }
+}
+
+const VALID_MODES = new Set(['simple', 'remote']);
+const DEFAULT_MODE = 'simple';
+
+function readJsonObject(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge base + optional device-local overlay preferences, shallow.
+ * Fail-open: missing/malformed either file contributes nothing.
+ *
+ * @param {object} paths
+ * @param {string} paths.base   preferences.json path
+ * @param {string} paths.local  preferences.local.json path
+ * @returns {object}            merged preferences (empty object if both absent)
+ */
+export function readMergedPreferences({ base, local }) {
+  const b = readJsonObject(base) || {};
+  const o = readJsonObject(local) || {};
+  return { ...b, ...o };
+}
+
+/**
+ * Resolve the library subsystem config from a merged preferences object.
+ * Returns `{ mode, remoteEndpoint?, remoteKey? }` on success.
+ * Throws {@link LibraryConfigError} on invalid shape or on
+ * `mode=remote` with missing required fields (spec §5.1 refuse-boot).
+ *
+ * @param {object} preferences  merged preferences (base + overlay)
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}}
+ */
+export function resolveLibraryConfig(preferences) {
+  const raw = preferences && typeof preferences === 'object' ? preferences.library : null;
+  const block = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+
+  const mode = block.mode ?? DEFAULT_MODE;
+
+  if (!VALID_MODES.has(mode)) {
+    throw new LibraryConfigError(
+      `library.mode must be "simple" or "remote", got ${JSON.stringify(mode)}`,
+      'invalid-mode',
+    );
+  }
+
+  if (mode === 'simple') {
+    return { mode };
+  }
+
+  // mode === 'remote'; validate required fields per spec §5.1.
+  const missing = [];
+  const endpoint = block.remoteEndpoint;
+  const key = block.remoteKey;
+  if (typeof endpoint !== 'string' || endpoint.trim() === '') missing.push('library.remoteEndpoint');
+  if (typeof key !== 'string' || key.trim() === '') missing.push('library.remoteKey');
+  if (missing.length > 0) {
+    throw new LibraryConfigError(
+      `library.mode="remote" but required field(s) missing/empty: ${missing.join(', ')}. ` +
+        `Refusing to boot the library subsystem (spec §5.1: no silent fallback to SIMPLE).`,
+      'remote-config-missing',
+    );
+  }
+
+  // Shape check on remoteKey (`<subkeyId>:<secret>`) is cheap and catches
+  // a common paste mistake without over-validating (the server does the
+  // authoritative check).
+  if (!/^[^:\s]+:[^\s]+$/.test(key)) {
+    throw new LibraryConfigError(
+      `library.remoteKey must be of shape "<subkeyId>:<secret>" (no whitespace, colon separator).`,
+      'remote-key-shape',
+    );
+  }
+
+  return { mode, remoteEndpoint: endpoint, remoteKey: key };
+}
+
+/**
+ * Full-scope vault reference form for `library.remoteKey`, per Barry's
+ * ruling on w-2026-07-15-023: `<scope>/<KEY_NAME>` (e.g.
+ * `hq-estate/REMOTE_LIBRARY_SUBKEY_DAVE`). Kept separate from the
+ * literal-subkey shape (`<subkeyId>:<secret>`) so the shape validator
+ * downstream still refuses garbage. Any value that neither matches this
+ * ref shape nor the literal shape is refused by resolveLibraryConfig.
+ */
+const REMOTE_KEY_REF_RE = /^([a-z0-9-]+)\/([A-Z][A-Z0-9_]*)$/;
+
+/**
+ * Resolve a `library.remoteKey` value that is a full-scope vault
+ * reference into the underlying literal `<subkeyId>:<secret>` by calling
+ * the estate `secrets` CLI. Literal values (containing a colon) and
+ * anything else pass through untouched; the caller-side shape validator
+ * is authoritative on shape.
+ *
+ * Canonical stravica-operator-barry cannot carry the literal subkey
+ * (sync-cycle would round-trip a plaintext secret through a git-tracked
+ * file). The reference lives in canonical; the vault holds the value;
+ * this function is the bridge. See w-2026-08-21-005 for the incident
+ * that made this the durable pattern.
+ *
+ * @param {string} refOrLiteral        the raw remoteKey value from preferences
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]     defaults to DEFAULT_REPO_ROOT
+ * @param {(args:{scope:string,key:string,repoRoot:string})=>string} [opts.secretsGet]
+ *                                     injectable resolver (tests)
+ * @returns {string}                   the resolved literal (never printed)
+ */
+export function resolveRemoteKeyRef(
+  refOrLiteral,
+  { repoRoot = DEFAULT_REPO_ROOT, secretsGet = defaultSecretsGet } = {},
+) {
+  if (typeof refOrLiteral !== 'string') return refOrLiteral;
+  const m = REMOTE_KEY_REF_RE.exec(refOrLiteral);
+  if (!m) return refOrLiteral;
+  const [, scope, key] = m;
+  let resolved;
+  try {
+    resolved = secretsGet({ scope, key, repoRoot });
+  } catch (err) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" failed to resolve ` +
+        `(scope=${scope} key=${key}): ${err && err.message ? err.message : err}. ` +
+        `Fix: pnpm exec secrets set ${key} --scope ${scope} <value>`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  if (typeof resolved !== 'string' || resolved.length === 0) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" resolved to empty value ` +
+        `(scope=${scope} key=${key}). ` +
+        `Fix: pnpm exec secrets set ${key} --scope ${scope} <value>`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  // secrets get can leave a trailing newline depending on subshell; strip
+  // whitespace once at the boundary so the shape validator sees the
+  // clean payload.
+  return resolved.replace(/\s+$/, '');
+}
+
+/**
+ * Default vault fetcher: invokes the `secrets` bin from the installed
+ * `@stravica-ai/digital-operator-pa` package under `repoRoot`. Uses
+ * direct `node <bin>` invocation (not `pnpm exec`) to sidestep the
+ * pnpm-11 stdout footgun that has bitten sam-tasks and others.
+ * Value is never logged.
+ */
+function defaultSecretsGet({ scope, key, repoRoot }) {
+  const secretsBin = join(
+    repoRoot,
+    'node_modules',
+    '@stravica-ai',
+    'digital-operator-pa',
+    'bin',
+    'secrets',
+  );
+  const out = execFileSync('node', [secretsBin, 'get', key, '--scope', scope], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return out;
+}
+
+/**
+ * Read + resolve in one call. Returns `{ mode, ...remoteFields, repoRoot,
+ * preferences }` on success or throws {@link LibraryConfigError}. The
+ * `preferences` field is the full merged object so callers can pluck
+ * neighbours (paName, pullClonesRoot, workspacePort) without a second read.
+ *
+ * Also resolves a `library.remoteKey` that carries the full-scope vault
+ * reference form (`<scope>/<KEY_NAME>`) into its underlying literal via
+ * `resolveRemoteKeyRef`. Literal values pass through unchanged.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]  defaults to DEFAULT_REPO_ROOT
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string, repoRoot: string, preferences: object}}
+ */
+export function loadLibraryConfig({ repoRoot = DEFAULT_REPO_ROOT } = {}) {
+  const base = join(repoRoot, 'operator', 'config', 'preferences.json');
+  const local = join(repoRoot, 'operator', 'config', 'preferences.local.json');
+  const preferences = readMergedPreferences({ base, local });
+  // Vault-ref resolution runs BEFORE resolveLibraryConfig's shape check
+  // so a ref value never reaches the `<subkeyId>:<secret>` validator.
+  // The check on the returned literal still fires and refuses garbage.
+  if (
+    preferences &&
+    preferences.library &&
+    preferences.library.mode === 'remote' &&
+    typeof preferences.library.remoteKey === 'string'
+  ) {
+    const original = preferences.library.remoteKey;
+    const resolved = resolveRemoteKeyRef(original, { repoRoot });
+    if (resolved !== original) {
+      preferences.library = { ...preferences.library, remoteKey: resolved };
+    }
+  }
+  const resolved = resolveLibraryConfig(preferences);
+  return { ...resolved, repoRoot, preferences };
+}

package/dist/engineering-pa-library-cli/src/envelope.mjs

@@ -0,0 +1,142 @@
+// envelope.mjs — build an EventInput envelope (spec §3.1) for one file.
+//
+// The server assigns `eventId` and `receivedAt`; the client contributes
+// everything else. `contentSha` is computed over the canonical payload
+// (spec §4.2 idempotency + item-4 build) so a retry of an identical
+// event dedups on `clientEventId` and the sha matches the server's
+// canonical hash.
+//
+// The kind registry from `@stravica-ai/remote-library` is the strict
+// enumeration; unknown kinds are refused at ingest with 422 anyway,
+// but we reject them locally too so an operator gets a clean error
+// without a round-trip.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { relative, isAbsolute } from 'node:path';
+
+import { EVENT_KINDS, canonicalJson } from '@stravica-ai/remote-library';
+
+export const KNOWN_KINDS = new Set(EVENT_KINDS);
+
+/**
+ * Compute the sha256 hash of the canonical JSON form of a payload.
+ * The `sha256:` prefix matches the server's contentSha convention.
+ *
+ * @param {object} payload
+ * @returns {string}  e.g. "sha256:abc123..."
+ */
+export function contentShaOf(payload) {
+  const canonical = canonicalJson(payload);
+  return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}
+
+/**
+ * Guess the event kind from a staging file path when the operator did
+ * not supply one via `--kind`. Falls back to
+ * `knowledge.observation.staged` because the two verbs that need a
+ * guess (`put` on a staging file, `flush`) both target that kind. If
+ * the file lives outside a staging tree the caller must pass an
+ * explicit `--kind` and this function refuses.
+ *
+ * @param {string} sourcePath  absolute or repo-relative
+ * @returns {string|null}
+ */
+export function guessKindFromPath(sourcePath) {
+  if (typeof sourcePath !== 'string') return null;
+  if (/agents\/[^/]+\/staging\//.test(sourcePath)) return 'knowledge.observation.staged';
+  return null;
+}
+
+/**
+ * Build a `knowledge.observation.staged` envelope for a staging file.
+ * The payload carries `path` (destination hint — the worker's apply
+ * function decides the actual write path) and the raw markdown body.
+ * `frontmatter` is left absent; the worker parses it if present in the
+ * body.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string} args.sourcePath   absolute or repo-relative
+ * @param {string} args.content
+ * @param {object} args.producer     { operator, agent, host?, session?, subkeyId }
+ * @param {string} [args.kind]       overrides guess; must be in KNOWN_KINDS
+ * @param {string} [args.tier]       default "auto" sentinel (spec §2.3)
+ * @param {'staging'|'flush'|'role-output'|'manual'|'synthesis'} [args.sourceKind]
+ *   default "manual"; `library flush` passes "flush"
+ * @param {() => Date} [args.clock]  test seam
+ * @returns {object} EventInput ready for POST /events
+ */
+export function buildEnvelope({
+  repoRoot,
+  sourcePath,
+  content,
+  producer,
+  kind,
+  tier = 'auto',
+  sourceKind = 'manual',
+  clock = () => new Date(),
+}) {
+  const relPath = sourcePath
+    ? isAbsolute(sourcePath) ? relative(repoRoot, sourcePath) : sourcePath
+    : undefined;
+
+  const resolvedKind = kind ?? guessKindFromPath(relPath ?? sourcePath ?? '') ?? null;
+  if (!resolvedKind) {
+    const err = new Error(
+      `cannot infer event kind from path ${JSON.stringify(sourcePath)}; pass --kind explicitly.`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+  if (!KNOWN_KINDS.has(resolvedKind)) {
+    const err = new Error(
+      `unknown event kind ${JSON.stringify(resolvedKind)}; known: ${[...KNOWN_KINDS].join(', ')}`,
+    );
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const now = clock();
+  const payload = {
+    path: relPath ?? null,
+    content,
+  };
+
+  const envelope = {
+    clientEventId: randomUUID(),
+    occurredAt: now.toISOString(),
+    producer: {
+      operator: producer.operator,
+      agent: producer.agent,
+      host: producer.host ?? hostname(),
+      subkeyId: producer.subkeyId,
+      ...(producer.session ? { session: producer.session } : {}),
+    },
+    kind: resolvedKind,
+    tier,
+    provenance: {
+      sourceKind,
+      ...(relPath ? { sourcePath: relPath } : {}),
+    },
+    payload,
+    contentSha: contentShaOf(payload),
+  };
+
+  return envelope;
+}
+
+/**
+ * Extract subkeyId from `library.remoteKey` (`<subkeyId>:<secret>`).
+ * @param {string} remoteKey
+ * @returns {string}
+ */
+export function subkeyIdFromRemoteKey(remoteKey) {
+  const idx = remoteKey.indexOf(':');
+  if (idx <= 0) {
+    const err = new Error('library.remoteKey shape invalid; expected "<subkeyId>:<secret>"');
+    err.exitCode = 1;
+    throw err;
+  }
+  return remoteKey.slice(0, idx);
+}

package/dist/engineering-pa-library-cli/src/http.mjs

@@ -0,0 +1,156 @@
+// http.mjs — thin fetch-based ingest client for the remote-library service.
+//
+// Chose to write a local client rather than extract one from the ingest
+// package: the server surface at `Stravica/remote-library` currently
+// exports `createIngestServer` but no client-side helper, and touching
+// that repo is out of scope for item 14 (see the item-14 dispatch brief,
+// §5 Boundaries). Follow-up: consider promoting a shared client into the
+// package's public surface (`@stravica-ai/remote-library`) once the
+// interface stabilises across `put`, `flush`, and any future producers.
+//
+// Auth (spec §3.4, main ruling 2026-08-20 option b):
+//   - `X-Subkey: <subkeyId>:<secret>` — mandatory, from library.remoteKey.
+//   - No `Authorization` header. Ingest authenticates by subkey alone;
+//     the install key is the server-side provisioning root only and
+//     plays no part in wire-side auth. Previous interim env var
+//     `REMOTE_LIBRARY_INSTALL_KEY` was removed by the same ruling.
+//
+// Retry policy (spec §7.7): three attempts, jittered backoff, total
+// budget ~5s. On timeouts and 5xx only — 4xx failures are surfaced
+// immediately so a bad envelope does not burn retry budget.
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BACKOFF_MS = 250;
+const DEFAULT_TIMEOUT_MS = 4000;
+const JSON_CONTENT_TYPE = 'application/json';
+
+/**
+ * Build request headers for the ingest API. Subkey-only auth per
+ * main ruling 2026-08-20 option b.
+ *
+ * @param {string} remoteKey `<subkeyId>:<secret>`
+ * @returns {Record<string, string>}
+ */
+export function buildIngestHeaders(remoteKey) {
+  return {
+    'Content-Type': JSON_CONTENT_TYPE,
+    'X-Subkey': remoteKey,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * POST /events with a single-event or batch body. Returns the parsed
+ * JSON response on any completed request (2xx or 4xx); the caller
+ * inspects the shape. Throws only when every retry attempt failed
+ * with a transport-class error (network unreachable, DNS, timeout).
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint          Full base URL of the ingest API (e.g. https://ops-01.internal)
+ * @param {string} opts.remoteKey
+ * @param {object} opts.body              JSON-serialisable body
+ * @param {number} [opts.attempts]        default 3
+ * @param {number} [opts.backoffMs]       default 250 (jittered)
+ * @param {number} [opts.timeoutMs]       default 4000
+ * @param {typeof fetch} [opts.fetchImpl] test seam
+ * @returns {Promise<{httpStatus: number, body: unknown}>}
+ */
+export async function postEvents({
+  endpoint,
+  remoteKey,
+  body,
+  attempts = DEFAULT_ATTEMPTS,
+  backoffMs = DEFAULT_BACKOFF_MS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchImpl = globalThis.fetch,
+}) {
+  const url = joinUrl(endpoint, '/events');
+  const headers = buildIngestHeaders(remoteKey);
+  const payload = JSON.stringify(body);
+
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, { method: 'POST', headers, body: payload, signal: ac.signal });
+      clearTimeout(timer);
+      // Retry 5xx (server transient); return 2xx and 4xx to caller.
+      if (res.status >= 500 && attempt < attempts) {
+        await sleep(jitter(backoffMs * attempt));
+        continue;
+      }
+      let parsed = null;
+      const text = await res.text();
+      if (text.length > 0) {
+        try { parsed = JSON.parse(text); } catch { parsed = { rawBody: text }; }
+      }
+      return { httpStatus: res.status, body: parsed };
+    } catch (err) {
+      clearTimeout(timer);
+      lastErr = err;
+      if (attempt < attempts) {
+        await sleep(jitter(backoffMs * attempt));
+        continue;
+      }
+    }
+  }
+  const err = new Error(`ingest unreachable at ${url}: ${lastErr?.message ?? lastErr}`);
+  err.cause = lastErr;
+  err.exitCode = 3; // transport / IO failure (tooling exit-code contract)
+  throw err;
+}
+
+/**
+ * GET /status from the service. Returns `{httpStatus, body}` when the
+ * call completes (including 5xx). Throws with exitCode=3 on transport
+ * failure (no retries — status is a read; the caller decides).
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint
+ * @param {string} opts.remoteKey  auth header (server may or may not require)
+ * @param {number} [opts.timeoutMs] default 2000
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<{httpStatus: number, body: unknown}>}
+ */
+export async function getStatus({
+  endpoint,
+  remoteKey,
+  timeoutMs = 2000,
+  fetchImpl = globalThis.fetch,
+}) {
+  const url = joinUrl(endpoint, '/status');
+  const headers = buildIngestHeaders(remoteKey);
+  delete headers['Content-Type']; // GET has no body
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { method: 'GET', headers, signal: ac.signal });
+    clearTimeout(timer);
+    let parsed = null;
+    const text = await res.text();
+    if (text.length > 0) {
+      try { parsed = JSON.parse(text); } catch { parsed = { rawBody: text }; }
+    }
+    return { httpStatus: res.status, body: parsed };
+  } catch (err) {
+    clearTimeout(timer);
+    const e = new Error(`status endpoint unreachable at ${url}: ${err?.message ?? err}`);
+    e.cause = err;
+    e.exitCode = 3;
+    throw e;
+  }
+}
+
+function jitter(ms) {
+  return Math.round(ms * (0.5 + Math.random()));
+}
+
+function joinUrl(base, path) {
+  const b = base.replace(/\/+$/, '');
+  const p = path.startsWith('/') ? path : `/${path}`;
+  return `${b}${p}`;
+}

package/dist/engineering-pa-library-cli/src/pull-clones.mjs

@@ -0,0 +1,74 @@
+// pull-clones.mjs — resolve the local pull-clone root for `library get`
+// and `library search`.
+//
+// Spec §3.3 says "read from the local pulled clone (no service round-
+// trip)" but does NOT pin where the clones live on an operator host.
+// The interim contract is:
+//
+//   1. `LIBRARY_PULL_CLONES_ROOT` env var  (highest precedence — deploy hook)
+//   2. `library.pullClonesRoot` in preferences.json / preferences.local.json
+//   3. `<HOME>/stravica-library-clones/`  (default)
+//
+// Reads accept `<tier-slug>/<relative-path>` — the tier slug matches
+// the git repo names in spec §2.1 (e.g. `stravica-library-hq`,
+// `stravica-operator-barry`), OR a bare relative path if the caller
+// already resolved the tier.
+//
+// FOLLOW-UP (surfaced in the seat return): `library.pullClonesRoot`
+// stretches the "three settled fields" surface from the item-14 brief;
+// main to ratify whether it stays as an operator preference or migrates
+// to environment-only.
+
+import { existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const DEFAULT_PULL_CLONES_ROOT = join(homedir(), 'stravica-library-clones');
+
+/**
+ * Resolve the pull-clones root directory in precedence order.
+ * @param {object} [opts]
+ * @param {object} [opts.preferences]  merged preferences
+ * @param {Record<string,string>} [opts.env]  defaults to process.env
+ * @returns {string}
+ */
+export function resolvePullClonesRoot({ preferences, env = process.env } = {}) {
+  const fromEnv = env.LIBRARY_PULL_CLONES_ROOT;
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return resolve(fromEnv);
+  const fromPrefs = preferences?.library?.pullClonesRoot;
+  if (typeof fromPrefs === 'string' && fromPrefs.trim() !== '') return resolve(fromPrefs);
+  return DEFAULT_PULL_CLONES_ROOT;
+}
+
+/**
+ * Given a caller-supplied path, produce the resolved absolute path
+ * under the pull-clones root. Enforces containment (no `..` escape).
+ *
+ * @param {object} opts
+ * @param {string} opts.root
+ * @param {string} opts.relPath  e.g. "stravica-library-hq/patterns/foo.md"
+ * @returns {string}
+ */
+export function resolveClonePath({ root, relPath }) {
+  const absRoot = resolve(root);
+  const absPath = resolve(absRoot, relPath);
+  if (!absPath.startsWith(absRoot + '/') && absPath !== absRoot) {
+    const err = new Error(`path escapes pull-clones root: ${relPath}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  return absPath;
+}
+
+/**
+ * True iff the pull-clones root exists on disk.
+ * @param {string} root
+ * @returns {boolean}
+ */
+export function pullClonesRootExists(root) {
+  try {
+    return existsSync(root) && statSync(root).isDirectory();
+  } catch {
+    return false;
+  }
+}