agent-hitch 0.1.1 → 0.2.1

package/dist/src/foundation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/foundation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5I,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC7G,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE5J,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/foundation/line-stream.js

@@ -0,0 +1,20 @@
+export function consumeLines(stream, onLine) {
+    let buffer = "";
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => {
+        buffer += chunk;
+        for (;;) {
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline).replace(/\r$/, "");
+            buffer = buffer.slice(newline + 1);
+            onLine(line);
+        }
+    });
+    stream.on("end", () => {
+        if (buffer.length > 0)
+            onLine(buffer.replace(/\r$/, ""));
+    });
+}
+//# sourceMappingURL=line-stream.js.map

package/dist/src/foundation/line-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-stream.js","sourceRoot":"","sources":["../../../src/foundation/line-stream.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAAC,MAAgB,EAAE,MAA8B;IAC3E,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;QAC3C,MAAM,IAAI,KAAK,CAAC;QAChB,SAAS,CAAC;YACR,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,OAAO,GAAG,CAAC;gBAAE,MAAM;YACvB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACzD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;QACpB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/foundation/locks.js

@@ -0,0 +1,114 @@
+import { randomBytes } from "node:crypto";
+import { open, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { HitchError } from "./errors.js";
+import { delay } from "./process.js";
+import { ensureDir, readJSON, removeIfExists } from "./fs.js";
+// Serializes stale-lock reclamation so an observation about an old owner can
+// never be used to remove a lock that a new owner has just acquired.
+export async function reclaimStaleLock(file, isStale) {
+    const guard = `${file}.reclaim`;
+    const owner = randomBytes(12).toString("hex");
+    let handle;
+    try {
+        handle = await open(guard, "wx", 0o600);
+    }
+    catch (error) {
+        if (error?.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    try {
+        await handle.writeFile(`${JSON.stringify({ owner, pid: process.pid, created_at: new Date().toISOString() })}\n`);
+        await handle.sync();
+        if (!await isStale(file))
+            return false;
+        await rm(file, { force: true });
+        return true;
+    }
+    finally {
+        await handle.close().catch(() => { });
+        let current;
+        try {
+            current = JSON.parse(await readFile(guard, "utf8"));
+        }
+        catch {
+            current = null;
+        }
+        if (current?.owner === owner)
+            await rm(guard, { force: true });
+    }
+}
+export async function withFileLock(directory, key, operation, { timeoutCode = "prepare_locked", timeoutExitCode = 5, signal } = {}) {
+    await ensureDir(directory);
+    const file = path.join(directory, `${key.replace("sha256:", "")}.lock`);
+    const owner = randomBytes(12).toString("hex");
+    let handle;
+    for (let attempt = 0; attempt < 3_000; attempt += 1) {
+        if (signal?.aborted)
+            throw cancelledError();
+        try {
+            handle = await open(file, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify({ owner, pid: process.pid, created_at: new Date().toISOString() })}\n`);
+            }
+            catch (error) {
+                await handle.close().catch(() => { });
+                handle = undefined;
+                await removeIfExists(file);
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST")
+                throw error;
+            if (await staleLock(file)) {
+                if (!await reclaimStaleLock(file, staleLock))
+                    await delay(100);
+                continue;
+            }
+            await delay(100);
+        }
+    }
+    if (!handle)
+        throw new HitchError("timed out waiting for Hitch state lock", { code: timeoutCode, exitCode: timeoutExitCode });
+    try {
+        if (signal?.aborted)
+            throw cancelledError();
+        return await operation();
+    }
+    finally {
+        await handle.close().catch(() => { });
+        const current = await readJSON(file, null).catch(() => null);
+        if (current?.owner === owner)
+            await removeIfExists(file);
+    }
+}
+async function staleLock(file) {
+    let lock;
+    try {
+        lock = await readJSON(file);
+    }
+    catch {
+        try {
+            return Date.now() - (await stat(file)).mtimeMs > 2_000;
+        }
+        catch {
+            return true;
+        }
+    }
+    if (!Number.isInteger(lock?.pid))
+        return true;
+    try {
+        process.kill(lock.pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error?.code === "ESRCH";
+    }
+}
+function cancelledError() {
+    return new HitchError("operation cancelled", { code: "cancelled", exitCode: 9 });
+}
+//# sourceMappingURL=locks.js.map

package/dist/src/foundation/locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.js","sourceRoot":"","sources":["../../../src/foundation/locks.ts"],"names":[],"mappings":"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"}

package/dist/src/foundation/package-root.js

@@ -0,0 +1,41 @@
+/**
+ * Resolve the Hitch package root and version from the module location,
+ * tolerating both the source layout (`src/foundation/package-root.ts`) and the
+ * compiled layout (`dist/src/foundation/package-root.js`). Walks up until a
+ * `package.json` with a `name` is found.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedRoot;
+let cachedVersion;
+export function packageRoot() {
+    if (cachedRoot)
+        return cachedRoot;
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(directory, "package.json");
+        try {
+            const metadata = JSON.parse(readFileSync(candidate, "utf8"));
+            if (metadata.name === "agent-hitch") {
+                cachedRoot = directory;
+                return directory;
+            }
+        }
+        catch {
+            // Keep walking up.
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error("could not locate the Hitch package root");
+        directory = parent;
+    }
+}
+export function packageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    const metadata = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8"));
+    cachedVersion = metadata.version;
+    return cachedVersion;
+}
+//# sourceMappingURL=package-root.js.map

package/dist/src/foundation/package-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-root.js","sourceRoot":"","sources":["../../../src/foundation/package-root.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,UAA8B,CAAC;AACnC,IAAI,aAAiC,CAAC;AAEtC,MAAM,UAAU,WAAW;IACzB,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,IAAI,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAClD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAuB,CAAC;YACnF,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBACpC,UAAU,GAAG,SAAS,CAAC;gBACvB,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,mBAAmB;QACrB,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACrF,SAAS,GAAG,MAAM,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;IAC9G,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC;IACjC,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/src/foundation/process.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+export async function terminateProcess(child, graceMs = 3_000) {
+    if (!child || child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        await waitForExitOrTimeout(killer, graceMs);
+        return;
+    }
+    try {
+        process.kill(-child.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error?.code !== "ESRCH")
+            throw error;
+        return;
+    }
+    await waitForExitOrTimeout(child, graceMs);
+    if (child.exitCode === null && child.signalCode === null) {
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch (error) {
+            if (error?.code !== "ESRCH")
+                throw error;
+        }
+    }
+}
+export function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function waitForExitOrTimeout(child, milliseconds) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.removeListener("exit", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        child.once("exit", finish);
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/src/foundation/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../../src/foundation/process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAsC,EAAE,OAAO,GAAG,KAAK;IAC5F,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO;IAE3E,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE;YACxE,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,MAAM,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAE,KAAK,CAAC,GAAc,EAAE,SAAS,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,EAAE,IAAI,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC;QACpE,OAAO;IACT,CAAC;IAED,MAAM,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACzD,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAE,KAAK,CAAC,GAAc,EAAE,SAAS,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,EAAE,IAAI,KAAK,OAAO;gBAAE,MAAM,KAAK,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,YAAoB;IACxC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAmB,EAAE,YAAoB;IACrE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC/C,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/revisions/index.js

@@ -0,0 +1,4 @@
+export { assertExactLocalGitEvalReference, parseHarnessReference } from "./reference.js";
+export { resolveHarness } from "./resolver.js";
+export { gitCacheDirectory } from "./sources/git.js";
+//# sourceMappingURL=index.js.map

package/dist/src/revisions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/revisions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEzF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/revisions/reference.js

@@ -0,0 +1,97 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+import { invalidInput } from "../foundation/index.js";
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const COMMIT_PATTERN = /^[0-9a-fA-F]{7,64}$/;
+const HARNESS_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export function parseHarnessReference(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw invalidInput("harness reference must be a non-empty string");
+    const raw = value.trim();
+    const separator = raw.indexOf("@");
+    const harnessId = separator < 0 ? raw : raw.slice(0, separator);
+    const revision = separator < 0 ? "installed" : raw.slice(separator + 1);
+    if (!HARNESS_ID_PATTERN.test(harnessId))
+        throw invalidInput(`invalid harness name: ${harnessId || raw}`);
+    if (!revision)
+        throw invalidInput(`harness reference is missing a selector: ${raw}`);
+    if (revision === "installed") {
+        return canonicalReference(raw, harnessId, { type: "installed" });
+    }
+    if (revision.startsWith("version:")) {
+        const version = revision.slice("version:".length);
+        if (!VERSION_PATTERN.test(version)) {
+            throw invalidInput(`version selector must be an exact semantic version: ${version || "(empty)"}`);
+        }
+        return canonicalReference(raw, harnessId, { type: "version", value: version });
+    }
+    if (revision.startsWith("commit:")) {
+        const commit = revision.slice("commit:".length);
+        assertCommit(commit);
+        return canonicalReference(raw, harnessId, { type: "commit", value: commit.toLowerCase() });
+    }
+    if (revision.startsWith("git+")) {
+        const hash = revision.lastIndexOf("#");
+        if (hash < 0)
+            throw invalidInput("explicit Git references require #<commit>");
+        const sourceValue = revision.slice("git+".length, hash);
+        const commit = revision.slice(hash + 1);
+        assertCommit(commit);
+        let source;
+        try {
+            source = new URL(sourceValue);
+        }
+        catch (error) {
+            throw invalidInput(`invalid Git source URL: ${sourceValue}`, { cause: error });
+        }
+        if (source.protocol !== "file:") {
+            throw invalidInput("explicit Git sources are limited to file:// URLs; use the registered source for remote commits");
+        }
+        const localPath = path.resolve(fileURLToPath(source));
+        if ([...localPath].some((character) => character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f)) {
+            throw invalidInput("explicit Git source paths cannot contain control characters");
+        }
+        const sourceUrl = pathToFileURL(localPath).href;
+        return canonicalReference(raw, harnessId, {
+            type: "commit",
+            value: commit.toLowerCase(),
+            source: { type: "git", url: sourceUrl, local_path: localPath, explicit: true },
+        });
+    }
+    throw invalidInput(`unsupported harness selector in ${raw}; use installed, version:<exact>, or commit:<sha>`);
+}
+/** Harbor can transport only an explicitly selected, exact object id. Local
+ * resolution remains intentionally more permissive for ordinary host runs. */
+export function assertExactLocalGitEvalReference(reference) {
+    const selector = reference.selector;
+    if (selector.type !== "commit" || !selector.source?.explicit)
+        return;
+    const hash = reference.raw.slice(reference.raw.lastIndexOf("#") + 1);
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(hash)) {
+        throw invalidInput("Harbor local Git eval requires a full lowercase 40- or 64-character commit OID");
+    }
+}
+function canonicalReference(raw, harnessId, selector) {
+    let suffix;
+    if (selector.type === "installed") {
+        suffix = "installed";
+    }
+    else if (selector.type === "commit" && selector.source) {
+        suffix = `git+${selector.source.url}#${selector.value}`;
+    }
+    else {
+        suffix = `${selector.type}:${selector.value}`;
+    }
+    return {
+        raw,
+        canonical: `${harnessId}@${suffix}`,
+        harness_id: harnessId,
+        selector,
+    };
+}
+function assertCommit(value) {
+    if (!COMMIT_PATTERN.test(value || "")) {
+        throw invalidInput(`commit selector must be a 7-64 character hexadecimal ID: ${value || "(empty)"}`);
+    }
+}
+//# sourceMappingURL=reference.js.map

package/dist/src/revisions/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../src/revisions/reference.ts"],"names":[],"mappings":"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"}

package/dist/src/revisions/resolver.js

@@ -0,0 +1,25 @@
+import { getAdapter } from "../adapters/index.js";
+import { HitchError, statePaths } from "../foundation/index.js";
+import { parseHarnessReference } from "./reference.js";
+import { resolveInstalled } from "./sources/installed.js";
+import { resolveVersion } from "./sources/npm.js";
+import { resolveCommit } from "./sources/git.js";
+export async function resolveHarness(referenceValue, { root, env = process.env } = {}) {
+    const reference = typeof referenceValue === "string" ? parseHarnessReference(referenceValue) : referenceValue;
+    const adapter = getAdapter(reference.harness_id);
+    if (reference.selector.type === "installed")
+        return resolveInstalled(reference, env);
+    const source = adapter.revision_sources?.[reference.selector.type];
+    if (!source) {
+        throw new HitchError(`${reference.harness_id} does not support ${reference.selector.type} revisions`, {
+            code: "revision_selector_unsupported",
+            exitCode: 10,
+        });
+    }
+    if (!root)
+        throw new HitchError("a Hitch state root is required to resolve managed revisions");
+    if (reference.selector.type === "version")
+        return resolveVersion(reference, source, env);
+    return resolveCommit(reference, source, statePaths(root), env);
+}
+//# sourceMappingURL=resolver.js.map

package/dist/src/revisions/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/revisions/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,cAA+C,EAC/C,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,KAAiD,EAAE;IAE5E,MAAM,SAAS,GAAG,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,qBAAqB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;IAC9G,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,gBAAgB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAErF,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACnE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,UAAU,CAAC,GAAG,SAAS,CAAC,UAAU,qBAAqB,SAAS,CAAC,QAAQ,CAAC,IAAI,YAAY,EAAE;YACpG,IAAI,EAAE,+BAA+B;YACrC,QAAQ,EAAE,EAAE;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,UAAU,CAAC,6DAA6D,CAAC,CAAC;IAC/F,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACzF,OAAO,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;AACjE,CAAC"}

package/dist/src/revisions/sources/git.js

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { HitchError, SCHEMA_VERSION, commandExecutable, digest, ensureDir, runCommand, withFileLock } from "../../foundation/index.js";
+export async function resolveCommit(reference, source, paths, env) {
+    const selector = reference.selector;
+    const sourceUrl = selector.source?.url || source.url;
+    if (!sourceUrl) {
+        throw new HitchError(`no Git source registered for ${reference.harness_id}`, {
+            code: "revision_selector_unsupported",
+            exitCode: 10,
+        });
+    }
+    const localPath = selector.source?.local_path;
+    const git = commandExecutable("git", env);
+    let fullCommit;
+    if (localPath) {
+        const statusResult = await runCommand(git, ["-C", localPath, "status", "--porcelain"], {
+            env,
+            failureCode: "resolution_failed",
+            failureExitCode: 4,
+        });
+        if (statusResult.stdout.trim()) {
+            throw new HitchError(`local harness repository has uncommitted changes: ${localPath}`, {
+                code: "dirty_source",
+                exitCode: 11,
+            });
+        }
+        fullCommit = await revParseCommit(git, localPath, selector.value, env);
+    }
+    const cacheDirectory = gitCacheDirectory(paths, sourceUrl);
+    const requestedCommit = fullCommit || selector.value;
+    fullCommit = await withFileLock(paths.sourceLocks, digest(sourceUrl), async () => {
+        await ensureGitCache(git, cacheDirectory, sourceUrl, env);
+        if (requestedCommit.length >= 40) {
+            await fetchCommit(git, cacheDirectory, sourceUrl, requestedCommit, env);
+        }
+        else {
+            await fetchAdvertisedRefs(git, cacheDirectory, sourceUrl, env);
+        }
+        return revParseBareCommit(git, cacheDirectory, requestedCommit, env);
+    }, { timeoutCode: "resolution_locked", timeoutExitCode: 4 });
+    const normalizedSource = sanitizeUrl(sourceUrl);
+    const identity = digest({
+        harness_id: reference.harness_id,
+        source_type: "git",
+        source: normalizedSource,
+        commit: fullCommit,
+    });
+    return {
+        schema_version: SCHEMA_VERSION,
+        requested_ref: reference.raw,
+        canonical_ref: reference.canonical,
+        harness_id: reference.harness_id,
+        selector: { type: "commit", value: selector.value },
+        source: {
+            type: "git",
+            url: normalizedSource,
+            registered: !selector.source?.explicit,
+        },
+        revision: {
+            type: "commit",
+            requested_commit: selector.value,
+            commit: fullCommit,
+        },
+        identity,
+        resolved_at: new Date().toISOString(),
+    };
+}
+async function ensureGitCache(git, directory, sourceUrl, env) {
+    try {
+        await access(path.join(directory, "HEAD"));
+        try {
+            await runCommand(git, ["--git-dir", directory, "remote", "set-url", "origin", sourceUrl], {
+                env,
+                failureCode: "resolution_failed",
+                failureExitCode: 4,
+            });
+        }
+        catch {
+            await runCommand(git, ["--git-dir", directory, "remote", "add", "origin", sourceUrl], {
+                env,
+                failureCode: "resolution_failed",
+                failureExitCode: 4,
+            });
+        }
+        return;
+    }
+    catch (error) {
+        if (error instanceof HitchError)
+            throw error;
+    }
+    await ensureDir(path.dirname(directory));
+    await runCommand(git, ["init", "--bare", directory], {
+        env,
+        failureCode: "resolution_failed",
+        failureExitCode: 4,
+    });
+    await runCommand(git, ["--git-dir", directory, "remote", "add", "origin", sourceUrl], {
+        env,
+        failureCode: "resolution_failed",
+        failureExitCode: 4,
+    });
+}
+async function fetchCommit(git, cacheDirectory, sourceUrl, commit, env) {
+    try {
+        await runCommand(git, ["--git-dir", cacheDirectory, "fetch", "--no-tags", "origin", commit], {
+            env,
+            failureCode: "revision_not_found",
+            failureExitCode: 3,
+        });
+    }
+    catch {
+        await fetchAdvertisedRefs(git, cacheDirectory, sourceUrl, env);
+    }
+}
+async function fetchAdvertisedRefs(git, cacheDirectory, _sourceUrl, env) {
+    await runCommand(git, [
+        "--git-dir", cacheDirectory,
+        "fetch", "--force", "origin",
+        "+refs/heads/*:refs/remotes/origin/*",
+        "+refs/tags/*:refs/tags/*",
+    ], {
+        env,
+        failureCode: "resolution_failed",
+        failureExitCode: 4,
+    });
+}
+async function revParseCommit(git, directory, commit, env) {
+    try {
+        const result = await runCommand(git, ["-C", directory, "rev-parse", "--verify", `${commit}^{commit}`], {
+            env,
+            failureCode: "revision_not_found",
+            failureExitCode: 3,
+        });
+        return result.stdout.trim().toLowerCase();
+    }
+    catch (error) {
+        throw new HitchError(`revision not found or ambiguous: ${commit}`, {
+            code: "revision_not_found",
+            exitCode: 3,
+            cause: error,
+        });
+    }
+}
+async function revParseBareCommit(git, directory, commit, env) {
+    try {
+        const result = await runCommand(git, ["--git-dir", directory, "rev-parse", "--verify", `${commit}^{commit}`], {
+            env,
+            failureCode: "revision_not_found",
+            failureExitCode: 3,
+        });
+        return result.stdout.trim().toLowerCase();
+    }
+    catch (error) {
+        throw new HitchError(`revision not found or ambiguous: ${commit}`, {
+            code: "revision_not_found",
+            exitCode: 3,
+            cause: error,
+        });
+    }
+}
+function sanitizeUrl(value) {
+    try {
+        const url = new URL(value);
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        return url.href;
+    }
+    catch {
+        return value;
+    }
+}
+export function gitCacheDirectory(paths, sourceUrl) {
+    const key = createHash("sha256").update(sourceUrl).digest("hex");
+    return path.join(paths.sourceCache, `git-${key}`);
+}
+//# sourceMappingURL=git.js.map

package/dist/src/revisions/sources/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../../src/revisions/sources/git.ts"],"names":[],"mappings":"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"}

package/dist/src/revisions/sources/installed.js

@@ -0,0 +1,45 @@
+import { inspectAgent } from "../../adapters/index.js";
+import { HitchError, SCHEMA_VERSION, digest } from "../../foundation/index.js";
+export async function resolveInstalled(reference, env) {
+    let discovered;
+    try {
+        discovered = await inspectAgent(reference.harness_id, { env });
+    }
+    catch (error) {
+        throw new HitchError(`failed to inspect installed harness: ${reference.harness_id}`, {
+            code: "resolution_failed",
+            exitCode: 4,
+            cause: error,
+        });
+    }
+    if (discovered.status !== "available" || !discovered.executable || !discovered.identity) {
+        throw new HitchError(`installed harness not found: ${reference.harness_id}`, {
+            code: "revision_not_found",
+            exitCode: 3,
+        });
+    }
+    const identity = digest({
+        harness_id: reference.harness_id,
+        source_type: "installed",
+        executable_identity: discovered.identity,
+    });
+    return {
+        schema_version: SCHEMA_VERSION,
+        requested_ref: reference.raw,
+        canonical_ref: reference.canonical,
+        harness_id: reference.harness_id,
+        selector: { type: "installed" },
+        source: {
+            type: "installed",
+            executable: discovered.executable,
+            integrity: discovered.identity,
+        },
+        revision: {
+            type: "installed",
+            version: discovered.version || null,
+        },
+        identity,
+        resolved_at: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=installed.js.map

package/dist/src/revisions/sources/installed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installed.js","sourceRoot":"","sources":["../../../../src/revisions/sources/installed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAG/E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiC,EAAE,GAAsB;IAC9F,IAAI,UAA2B,CAAC;IAChC,IAAI,CAAC;QACH,UAAU,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,wCAAwC,SAAS,CAAC,UAAU,EAAE,EAAE;YACnF,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,UAAU,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;QACxF,MAAM,IAAI,UAAU,CAAC,gCAAgC,SAAS,CAAC,UAAU,EAAE,EAAE;YAC3E,IAAI,EAAE,oBAAoB;YAC1B,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC;QACtB,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,WAAW,EAAE,WAAW;QACxB,mBAAmB,EAAE,UAAU,CAAC,QAAQ;KACzC,CAAC,CAAC;IACH,OAAO;QACL,cAAc,EAAE,cAAc;QAC9B,aAAa,EAAE,SAAS,CAAC,GAAG;QAC5B,aAAa,EAAE,SAAS,CAAC,SAAS;QAClC,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;QAC/B,MAAM,EAAE;YACN,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,SAAS,EAAE,UAAU,CAAC,QAAQ;SAC/B;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,IAAI;SACpC;QACD,QAAQ;QACR,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACtC,CAAC;AACJ,CAAC"}