@nurix/nustack 0.23.11 → 0.23.13

package/dist/lib/harness/vendor.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const VENDORED = {
+    digest: "digest/index.js",
+    mount: "mount/index.js",
+    rules: "rules/index.js",
+    rulesNode: "rules/node.js",
+};
+const WORKSPACE = {
+    digest: "@nurix/harness/digest",
+    mount: "@nurix/harness/mount",
+    rules: "@nurix/harness/rules",
+    rulesNode: "@nurix/harness/rules/node",
+};
+const VENDOR_ROOT = new URL("../../vendor/harness/", import.meta.url);
+export function isSourceRun(moduleUrl = import.meta.url) {
+    const file = fileURLToPath(moduleUrl);
+    return file.split(path.sep).join("/").includes("/packages/cli/src/");
+}
+const loaded = new Map();
+export function loadHarness(name) {
+    let module = loaded.get(name);
+    if (!module) {
+        const specifier = isSourceRun() ? WORKSPACE[name] : new URL(VENDORED[name], VENDOR_ROOT).href;
+        module = import(specifier);
+        loaded.set(name, module);
+    }
+    return module;
+}

package/dist/lib/harness/versionsClient.js

@@ -0,0 +1,54 @@
+import { authorizedFetch } from "../nustack_client.js";
+import { assertSafeOpaqueId } from "../guards.js";
+const REQUEST_TIMEOUT_MS = 15_000;
+export class VersionsRouteError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "VersionsRouteError";
+        this.status = status;
+        this.code = code;
+    }
+}
+function versionsPath(projectId, ...segments) {
+    const safe = assertSafeOpaqueId("The Project id", projectId);
+    return `/api/v2/projects/${encodeURIComponent(safe)}/harness-versions${segments.map((segment) => `/${encodeURIComponent(segment)}`).join("")}`;
+}
+async function request(baseUrl, accessToken, routePath) {
+    try {
+        return await authorizedFetch(`${baseUrl}${routePath}`, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (typeof error.code === "string" && error.code === "ORIGIN_MISMATCH")
+            throw error;
+        throw new VersionsRouteError(0, null, `${routePath} did not answer: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function enveloped(response, label) {
+    const body = (await response.json().catch(() => null));
+    if (!response.ok || body?.data === undefined) {
+        const code = typeof body?.error?.code === "string" ? body.error.code : null;
+        const message = typeof body?.error?.message === "string" ? body.error.message : `HTTP ${response.status}`;
+        throw new VersionsRouteError(response.status, code, `${label}: ${message}`);
+    }
+    return body.data;
+}
+export async function resolveProjectVersion(baseUrl, accessToken, projectId, ask) {
+    const query = "digest" in ask ? `?digest=${encodeURIComponent(ask.digest)}` : "?track=latest";
+    const response = await request(baseUrl, accessToken, `${versionsPath(projectId, "resolve")}${query}`);
+    return enveloped(response, "harness version resolve failed");
+}
+export async function fetchVersionManifest(baseUrl, accessToken, projectId, semver) {
+    const response = await request(baseUrl, accessToken, versionsPath(projectId, semver, "manifest"));
+    return enveloped(response, `harness version ${semver} manifest read failed`);
+}
+export async function fetchVersionObject(baseUrl, accessToken, projectId, semver, entry) {
+    const response = await request(baseUrl, accessToken, versionsPath(projectId, semver, "files", ...entry.path.split("/")));
+    if (!response.ok)
+        await enveloped(response, `harness file ${entry.path} read failed`);
+    return new Uint8Array(await response.arrayBuffer());
+}

package/dist/lib/local_store/database.js

@@ -54,6 +54,24 @@ export async function openLocalStore(options = {}) {
         },
     };
 }
+export async function openLocalStoreReadOnly(options = {}) {
+    const dbFile = options.dbPath ?? stateDbPath();
+    if (!existsSync(dbFile))
+        return null;
+    const db = await withSuppressedSqliteWarning(async () => {
+        const { DatabaseSync } = await loadSqlite();
+        return new DatabaseSync(dbFile, { readOnly: true });
+    });
+    db.exec("PRAGMA busy_timeout = 2000");
+    const row = db.prepare("PRAGMA user_version").get();
+    return {
+        db,
+        version: Number(row?.user_version ?? 0),
+        close() {
+            db.close();
+        },
+    };
+}
 export async function readStoreVersion(dbFile = stateDbPath()) {
     if (!existsSync(dbFile))
         return null;

package/dist/lib/nustack_client.js

@@ -2,10 +2,16 @@ import { assertSafeNuStackUrl, assertSafeOpaqueId } from "./guards.js";
 import { createSseParser } from "./sse_framing.js";
 import { deadCredentialCopy, DEVICE_HEADER, envToken, forgetRefusedToken, knownDeviceId, TokenRefusedError, userAgent } from "./auth_grant.js";
 import { getOrCreateDeviceId } from "./device_identity.js";
-const DEFAULT_NUSTACK_URL = "https://apps.nustack.ai";
+import { readStoredCredential } from "./auth_grant.js";
+import { readProjectContractSync } from "./project_contract.js";
+import { contractOrigins, isContractOrigin, isPlatformDefault, originMismatchError, PLATFORM_DEFAULT_ORIGIN, recordContractOrigin, refusedContractOrigin, } from "./origin_guard.js";
+const DEFAULT_NUSTACK_URL = PLATFORM_DEFAULT_ORIGIN;
+export { contractOrigins };
 const REQUEST_TIMEOUT_MS = 10_000;
 export async function authorizedFetch(input, init = {}) {
     const headers = new Headers(init.headers);
+    if (headers.has("Authorization"))
+        await assertCredentialOrigin(String(input));
     headers.set(DEVICE_HEADER, knownDeviceId() ?? (await getOrCreateDeviceId()));
     headers.set("User-Agent", userAgent());
     const response = await globalThis.fetch(input, { ...init, headers });
@@ -33,8 +39,35 @@ export function errorMessage(payload, status, label, plane) {
     const enveloped = typeof payload?.error === "object" ? payload.error?.message : undefined;
     return enveloped ?? payload?.message ?? `${label}: HTTP ${status}`;
 }
+export function resolveNuStackOrigin(options, cwd) {
+    if (options.nustackUrl)
+        return { url: assertSafeNuStackUrl(options.nustackUrl), source: "flag" };
+    if (process.env.NUSTACK_URL)
+        return { url: assertSafeNuStackUrl(process.env.NUSTACK_URL), source: "env" };
+    const origin = readProjectContractSync(cwd).origin;
+    if (origin) {
+        const url = assertSafeNuStackUrl(origin);
+        if (!isPlatformDefault(url)) {
+            recordContractOrigin(url);
+            if (process.env.NUSTACK_TOKEN?.trim())
+                throw originMismatchError(url, null, "pat");
+        }
+        return { url, source: "contract" };
+    }
+    return { url: assertSafeNuStackUrl(DEFAULT_NUSTACK_URL), source: "default" };
+}
 export function resolveNuStackUrl(options) {
-    return assertSafeNuStackUrl(options.nustackUrl ?? process.env.NUSTACK_URL ?? DEFAULT_NUSTACK_URL);
+    return resolveNuStackOrigin(options, process.cwd()).url;
+}
+export async function assertCredentialOrigin(url) {
+    if (contractOrigins.size === 0 || !isContractOrigin(url))
+        return;
+    if (process.env.NUSTACK_TOKEN?.trim())
+        throw originMismatchError(url, null, "pat");
+    const held = (await readStoredCredential().catch(() => null))?.credential ?? null;
+    const refused = refusedContractOrigin(held?.studioBaseUrl ?? null, url);
+    if (refused)
+        throw originMismatchError(refused, held?.studioBaseUrl ?? null, held ? "device" : "none");
 }
 export async function fetchCatalogue(baseUrl) {
     const response = await authorizedFetch(`${baseUrl}/api/catalog.json`, {

package/dist/lib/onboarding/attach_existing_git.js

@@ -1,7 +1,7 @@
 import { readHeadCommit } from "../git-sync/core/repository.js";
 import { readSymbolicBranch } from "../git-sync/core/repository.js";
 import { reconcileInboundBinding } from "../git-sync/inbound/index.js";
-import { fetchToolkitProfile } from "../etna/profile.js";
+import { fetchToolkitProfile, ToolkitProfileUnavailableError } from "../etna/profile.js";
 import { classifyFolder, attachRejection } from "./folder_state.js";
 import { runRepositoryOnboarding, } from "./binding.js";
 export async function attachExistingGit(ctx, options) {
@@ -24,7 +24,19 @@ export async function attachExistingGit(ctx, options) {
     if (!boundBranch) {
         return { ok: false, code: "DETACHED_HEAD", message: "HEAD is detached — check out a branch before attaching." };
     }
-    const profile = await fetchToolkitProfile(ctx.baseUrl, ctx.accessToken, options.projectId);
+    let profile;
+    try {
+        profile = await fetchToolkitProfile(ctx.baseUrl, ctx.accessToken, options.projectId);
+    }
+    catch (error) {
+        if (error instanceof ToolkitProfileUnavailableError)
+            throw error;
+        return {
+            ok: false,
+            code: "PROJECT_SUMMARY_UNREACHABLE",
+            message: `The summary of Project ${options.projectId} could not be read, so this folder was not bound: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
     const baselineCommitId = readHeadCommit(state.repository);
     const result = await runRepositoryOnboarding({
         store: ctx.store,

package/dist/lib/onboarding/binding.js

@@ -6,6 +6,9 @@ import { readHeadCommit } from "../git-sync/core/repository.js";
 import { writeProjectManifests } from "./manifest_writer.js";
 import { installToolkit } from "../etna/manager.js";
 import { serializeProfileForBinding } from "../etna/profile.js";
+import { contractFieldsFromSummary, readProjectContract } from "../project_contract.js";
+import { hasEtnaMountHook, installHarnessMountHook } from "./session_hook.js";
+import { installCommitTrailerHook, trailerHookLine } from "./commit_trailer_hook.js";
 import { SYNC_PROTOCOL_VERSION } from "../git-sync/whitelist/types.js";
 export function computeRepositoryFingerprint(repository) {
     return createHash("sha256").update(repository.commonDir).digest("hex");
@@ -49,7 +52,19 @@ async function maybeRunTelemetry(input, binding) {
         return;
     await ensureBindingTelemetry({ baseUrl: input.baseUrl, store: input.store, binding }).catch(() => { });
 }
+export async function onboardingContractFields(root, baseUrl, profile) {
+    const held = await readProjectContract(root);
+    const fromSummary = profile.contractFields ?? contractFieldsFromSummary(null);
+    return {
+        origin: baseUrl,
+        door: baseUrl,
+        harness: fromSummary.harness,
+        branchPolicy: fromSummary.branchPolicy ?? null,
+        docsRoot: held.docsRoot ?? "docs",
+    };
+}
 export async function runRepositoryOnboarding(input) {
+    const root = input.repository.repositoryRoot;
     const baselineCommitId = input.baselineCommitId !== undefined ? input.baselineCommitId : readHeadCommit(input.repository);
     const established = await establishBinding({
         store: input.store,
@@ -64,8 +79,7 @@ export async function runRepositoryOnboarding(input) {
         etnaProfileJson: serializeProfileForBinding(input.profile),
         runTelemetry: input.runTelemetry,
     });
-    const install = await installToolkit(input.store, established.binding.id, input.profile, input.repository.repositoryRoot, input.toolkitDeps ?? {});
-    const projectManifest = await writeProjectManifests(input.repository.repositoryRoot, {
+    const projectManifest = await writeProjectManifests(root, {
         projectId: input.projectId,
         organizationId: input.organizationId,
         toolkit: {
@@ -74,7 +88,33 @@ export async function runRepositoryOnboarding(input) {
             rendererVersion: input.profile.rendererVersion,
             placementMapVersion: input.profile.placementMapVersion,
         },
+        contract: await onboardingContractFields(root, input.baseUrl, input.profile),
+    });
+    const notices = [];
+    const etnaMounts = await hasEtnaMountHook(root);
+    let sessionHook = "skipped_etna_mount";
+    if (etnaMounts) {
+        notices.push("etna's mount hook is in .claude/settings.json, so NuStack installed no session-start hook and mounted nothing: remove etna's SessionStart entry (.claude/hooks/mount.mjs), then re-run `nustack init`.");
+    }
+    else {
+        sessionHook = await installHarnessMountHook(root);
+        if (sessionHook === "skipped_unparsable")
+            notices.push(".claude/settings.json does not parse as JSON, so the session-start mount hook was not installed; the file was left untouched.");
+    }
+    const install = await installToolkit(input.store, established.binding.id, input.profile, root, {
+        ...(input.toolkitDeps ?? {}),
+        skipMount: etnaMounts,
+        writeContract: "when-unmodified",
+        projectId: input.projectId,
+        globals: { nustackUrl: input.baseUrl },
     });
+    const mount = install.mount ?? { status: "failed", code: "HARNESS_UNAVAILABLE", message: install.reason ?? "no harness to mount" };
+    if (mount.status === "failed")
+        notices.push(`harness not mounted (${mount.code}): ${mount.message ?? ""} — the next session start retries it.`);
+    const trailerHook = await installCommitTrailerHook(root);
+    const trailerLine = trailerHookLine(trailerHook);
+    if (trailerLine)
+        notices.push(trailerLine);
     return {
         flow: input.flow,
         projectId: input.projectId,
@@ -86,6 +126,10 @@ export async function runRepositoryOnboarding(input) {
         reused: !established.created,
         install,
         projectManifest,
+        sessionHook,
+        mount,
+        trailerHook,
+        notices,
         noPush: true,
     };
 }

package/dist/lib/onboarding/commit_trailer_hook.js

@@ -0,0 +1,66 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const TRAILER_HOOK_MARKER = "# nustack:managed commit-msg v1";
+export const CHANGE_TRAILER_KEY = "NuStack-Change";
+export const TRAILER_HOOK_BODY = `#!/bin/sh
+${TRAILER_HOOK_MARKER}
+# Appends a ${CHANGE_TRAILER_KEY}: <32 lowercase hex> trailer, the change id NuStack's harness records key a
+# commit by. Written by the nustack CLI (nustack init, nustack harness mount); an amend or a rebase keeps the id.
+msg="$1"
+[ -f "$msg" ] || exit 0
+case "$(sed -n '1p' "$msg")" in
+    "fixup! "*|"squash! "*) exit 0 ;;
+esac
+grep -qi '^${CHANGE_TRAILER_KEY}:' "$msg" && exit 0
+id=$(od -An -N16 -tx1 /dev/urandom | tr -d ' \\n')
+[ \${#id} -eq 32 ] || exit 0
+git interpret-trailers --in-place --trailer "${CHANGE_TRAILER_KEY}: $id" "$msg"
+`;
+function git(root, args) {
+    try {
+        return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function isManagedTrailerHook(text) {
+    return text.split("\n").slice(0, 2).some((line) => line.trim() === TRAILER_HOOK_MARKER);
+}
+export async function installCommitTrailerHook(root) {
+    const commonDir = git(root, ["rev-parse", "--git-common-dir"]);
+    if (!commonDir)
+        return "skipped_not_git";
+    const hooksPath = git(root, ["config", "--get", "core.hooksPath"]);
+    if (hooksPath)
+        return "skipped_hooks_path";
+    const hooksDir = path.join(path.isAbsolute(commonDir) ? commonDir : path.join(root, commonDir), "hooks");
+    const hookFile = path.join(hooksDir, "commit-msg");
+    if (existsSync(hookFile)) {
+        const held = await readFile(hookFile, "utf8").catch(() => "");
+        if (!isManagedTrailerHook(held))
+            return "skipped_foreign_hook";
+        if (held === TRAILER_HOOK_BODY) {
+            await chmod(hookFile, 0o755);
+            return "installed";
+        }
+    }
+    await mkdir(hooksDir, { recursive: true });
+    await writeFile(hookFile, TRAILER_HOOK_BODY, { encoding: "utf8", mode: 0o755 });
+    await chmod(hookFile, 0o755);
+    return "installed";
+}
+export function trailerHookLine(value) {
+    switch (value) {
+        case "skipped_hooks_path":
+            return "NuStack-Change trailer hook not installed: core.hooksPath is set, so this repository's own hook manager owns commit-msg.";
+        case "skipped_foreign_hook":
+            return "NuStack-Change trailer hook not installed: a commit-msg hook NuStack did not write is already there.";
+        case "skipped_not_git":
+            return "NuStack-Change trailer hook not installed: this folder is not a git repository.";
+        default:
+            return null;
+    }
+}

package/dist/lib/onboarding/manifest_writer.js

@@ -5,8 +5,8 @@ import { legacyAppJsonPath, readBindingMarker, projectJsonPath } from "../projec
 import { manifestPath } from "../manifest.js";
 const CURRENT_BINDING_PROTOCOL_VERSION = 1;
 const CURRENT_DOCUMENT_PROTOCOL_VERSION = 1;
-function buildProjectManifest(identity) {
-    return {
+function buildProjectManifest(identity, existing) {
+    const owned = {
         schemaVersion: 2,
         workspaceId: identity.projectId,
         organizationId: identity.organizationId,
@@ -19,6 +19,22 @@ function buildProjectManifest(identity) {
             placementMapVersion: identity.toolkit.placementMapVersion,
         },
     };
+    const supplied = Object.fromEntries(Object.entries(identity.contract ?? {}).filter(([, value]) => value !== undefined));
+    return { ...(existing ?? {}), ...owned, ...supplied };
+}
+async function readExistingContract(root) {
+    const filePath = projectJsonPath(root);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const parsed = JSON.parse(await readFile(filePath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed.schemaVersion === 2 ? parsed : null;
+    }
+    catch {
+        return null;
+    }
 }
 async function atomicWrite(target, content) {
     const prior = existsSync(target) ? await readFile(target, "utf8") : null;
@@ -54,7 +70,7 @@ export async function writeProjectManifests(root, identity, hooks = {}) {
         toolkit: { name: identity.toolkit.name, version: identity.toolkit.version },
     };
     delete nextService.nustackApp;
-    const projectManifest = buildProjectManifest(identity);
+    const projectManifest = buildProjectManifest(identity, await readExistingContract(root));
     const projectDir = path.dirname(projectJsonPath(root));
     await mkdir(projectDir, { recursive: true });
     const projectPrior = await atomicWrite(projectJsonPath(root), JSON.stringify(projectManifest, null, 2) + "\n");

package/dist/lib/onboarding/session_hook.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const SETTINGS_PATH = ".claude/settings.json";
+export const HARNESS_MOUNT_MARKER = "nustack:managed:harness-mount";
+export const HARNESS_MOUNT_COMMAND = `nustack harness mount "$CLAUDE_PROJECT_DIR" >/dev/null || true # ${HARNESS_MOUNT_MARKER}`;
+const ETNA_MOUNT_HOOK = /\.claude\/hooks\/mount\.mjs/;
+const DEFAULT_INDENT = 2;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function commandsOf(entry) {
+    if (!isObject(entry) || !Array.isArray(entry.hooks))
+        return [];
+    return entry.hooks.flatMap((hook) => (isObject(hook) && typeof hook.command === "string" ? [hook.command] : []));
+}
+function sessionStartEntries(settings) {
+    const hooks = settings.hooks;
+    if (!isObject(hooks) || !Array.isArray(hooks.SessionStart))
+        return [];
+    return hooks.SessionStart;
+}
+function isHarnessMountEntry(entry) {
+    return commandsOf(entry).some((command) => command.trimEnd().endsWith(`# ${HARNESS_MOUNT_MARKER}`));
+}
+function managedEntry() {
+    return { matcher: "", hooks: [{ type: "command", command: HARNESS_MOUNT_COMMAND }] };
+}
+function detectIndent(raw) {
+    const indented = /\n(\x20+)"/.exec(raw);
+    return indented?.[1] ? indented[1].length : DEFAULT_INDENT;
+}
+async function readSettings(root) {
+    const file = path.join(root, SETTINGS_PATH);
+    if (!existsSync(file))
+        return { kind: "absent" };
+    const raw = await readFile(file, "utf8").catch(() => null);
+    if (raw === null)
+        return { kind: "unparsable" };
+    if (raw.trim() === "")
+        return { kind: "parsed", settings: {}, indent: DEFAULT_INDENT };
+    try {
+        const parsed = JSON.parse(raw);
+        return isObject(parsed) ? { kind: "parsed", settings: parsed, indent: detectIndent(raw) } : { kind: "unparsable" };
+    }
+    catch {
+        return { kind: "unparsable" };
+    }
+}
+export async function hasEtnaMountHook(root) {
+    const read = await readSettings(root);
+    if (read.kind !== "parsed")
+        return false;
+    return sessionStartEntries(read.settings).some((entry) => commandsOf(entry).some((command) => ETNA_MOUNT_HOOK.test(command)));
+}
+export async function installHarnessMountHook(root) {
+    const read = await readSettings(root);
+    if (read.kind === "unparsable")
+        return "skipped_unparsable";
+    const settings = read.kind === "parsed" ? read.settings : {};
+    const indent = read.kind === "parsed" ? read.indent : DEFAULT_INDENT;
+    const entries = sessionStartEntries(settings);
+    if (entries.some((entry) => commandsOf(entry).some((command) => ETNA_MOUNT_HOOK.test(command))))
+        return "skipped_etna_mount";
+    const wanted = managedEntry();
+    const index = entries.findIndex(isHarnessMountEntry);
+    if (index >= 0 && JSON.stringify(entries[index]) === JSON.stringify(wanted))
+        return "present";
+    const nextEntries = index >= 0 ? entries.map((entry, at) => (at === index ? wanted : entry)) : [...entries, wanted];
+    const hooks = isObject(settings.hooks) ? settings.hooks : {};
+    const next = { ...settings, hooks: { ...hooks, SessionStart: nextEntries } };
+    const file = path.join(root, SETTINGS_PATH);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(next, null, indent)}\n`, "utf8");
+    return "installed";
+}

package/dist/lib/origin_guard.js

@@ -0,0 +1,43 @@
+import { HarnessError, HARNESS_CODES } from "./harness/codes.js";
+export const PLATFORM_DEFAULT_ORIGIN = "https://apps.nustack.ai";
+export const contractOrigins = new Set();
+export function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url.trim().replace(/\/+$/, "");
+    }
+}
+export function isPlatformDefault(url) {
+    return originOf(url) === originOf(PLATFORM_DEFAULT_ORIGIN);
+}
+export function recordContractOrigin(url) {
+    if (!isPlatformDefault(url))
+        contractOrigins.add(originOf(url));
+}
+export function isContractOrigin(url) {
+    return contractOrigins.has(originOf(url));
+}
+export function originMismatchError(origin, credentialOrigin, credentialKind) {
+    const held = credentialKind === "pat"
+        ? "a personal access token (NUSTACK_TOKEN) is never sent to an origin a repository names"
+        : credentialKind === "none"
+            ? "this machine is not signed in to it, and a sign-in never opens for an origin a repository names"
+            : `this machine's sign-in is for ${credentialOrigin ?? "another origin"}`;
+    return new HarnessError(HARNESS_CODES.ORIGIN_MISMATCH, `This repository's .nustack/workspace.json names ${origin} as its NuStack origin, but ${held}. ` +
+        `To use ${origin}, state it outside the repository: \`nustack login --nustack-url ${origin}\`, or set NUSTACK_URL=${origin}.`);
+}
+export function refusedContractOrigin(credentialOrigin, origin) {
+    const candidates = origin === undefined ? [...contractOrigins] : isContractOrigin(origin) ? [originOf(origin)] : [];
+    const held = credentialOrigin === null ? null : originOf(credentialOrigin);
+    return candidates.find((candidate) => candidate !== held) ?? null;
+}
+export function isOriginMismatch(error) {
+    return error instanceof HarnessError && error.code === HARNESS_CODES.ORIGIN_MISMATCH;
+}
+export function nullUnlessOriginRefused(error) {
+    if (isOriginMismatch(error))
+        throw error;
+    return null;
+}

package/dist/lib/project_contract.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export const CONTRACT_PATH = ".nustack/workspace.json";
+export const LEGACY_HARNESS_MANIFEST_PATH = ".claude/harness.json";
+const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+function parseObject(text) {
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function contractObject(text) {
+    const parsed = parseObject(text);
+    return parsed !== null && parsed.schemaVersion === 2 ? parsed : null;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function urlOf(value) {
+    const trimmed = nonEmpty(value);
+    return trimmed === null ? null : trimmed.replace(/\/+$/, "");
+}
+export function docsRootDeclaration(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim().replace(/[\\/]+$/, "");
+    if (trimmed === "" || /^([A-Za-z]:)?[\\/]/.test(trimmed))
+        return null;
+    return trimmed.split(/[\\/]/).includes("..") ? null : trimmed;
+}
+export function harnessOf(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const harness = value;
+    if (harness.track === "latest")
+        return { track: "latest" };
+    const pin = nonEmpty(harness.pin);
+    const digest = typeof harness.digest === "string" ? harness.digest.trim() : "";
+    return pin !== null && DIGEST_PATTERN.test(digest) ? { pin, digest } : null;
+}
+function doorOf(holder) {
+    if (holder === null || !Object.hasOwn(holder, "door"))
+        return undefined;
+    return urlOf(holder.door);
+}
+function legacyMount(legacy) {
+    const mount = legacy?.mount;
+    return typeof mount === "object" && mount !== null && !Array.isArray(mount) ? mount : null;
+}
+export function parseProjectContract(contractText, legacyText) {
+    const contract = contractObject(contractText);
+    const legacy = parseObject(legacyText);
+    const contractDoor = doorOf(contract);
+    const legacyDoor = doorOf(legacyMount(legacy));
+    return {
+        projectId: contract === null ? null : nonEmpty(contract.workspaceId),
+        harness: contract === null ? null : harnessOf(contract.harness),
+        door: contractDoor !== undefined ? contractDoor : legacyDoor,
+        doorSource: contractDoor !== undefined ? "contract" : legacyDoor !== undefined ? "legacy" : null,
+        origin: contract === null ? null : urlOf(contract.origin),
+        docsRoot: (contract === null ? null : docsRootDeclaration(contract.docsRoot)) ?? docsRootDeclaration(legacy?.docsRoot),
+        branchPolicy: contract?.branchPolicy === "trunk" || contract?.branchPolicy === "branch" ? contract.branchPolicy : null,
+        contractPresent: contract !== null,
+        legacyPresent: legacyText !== null,
+        legacyVersion: nonEmpty(legacy?.version),
+    };
+}
+function readTextSync(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function readText(file) {
+    if (!existsSync(file))
+        return null;
+    return readFile(file, "utf8").catch(() => null);
+}
+export async function readProjectContract(root) {
+    return parseProjectContract(await readText(path.join(root, CONTRACT_PATH)), await readText(path.join(root, LEGACY_HARNESS_MANIFEST_PATH)));
+}
+export function readProjectContractSync(root) {
+    return parseProjectContract(readTextSync(path.join(root, CONTRACT_PATH)), readTextSync(path.join(root, LEGACY_HARNESS_MANIFEST_PATH)));
+}
+export function contractFieldsFromSummary(summary) {
+    if (summary === null)
+        return { harness: { track: "latest" }, branchPolicy: null };
+    const harness = summary.harness;
+    const branchPolicy = summary.branchPolicy === "trunk" || summary.branchPolicy === "branch" ? summary.branchPolicy : null;
+    if (harness?.track === "pinned" && typeof harness.digest === "string" && DIGEST_PATTERN.test(harness.digest)) {
+        return { harness: { pin: harness.version, digest: harness.digest }, branchPolicy };
+    }
+    return { harness: { track: "latest" }, branchPolicy };
+}