@nurix/nustack 0.10.0-dev.10

package/dist/lib/nustack_client.js

@@ -0,0 +1,547 @@
+import { assertSafeNuStackUrl, assertSafeOpaqueId } from "./guards.js";
+import { createSseParser } from "./sse_framing.js";
+import { DEVICE_HEADER, knownDeviceId, refreshAccessTokenAfterRefusal, userAgent } from "./auth_grant.js";
+import { getOrCreateDeviceId } from "./device_identity.js";
+const DEFAULT_NUSTACK_URL = "https://apps.nustack.ai";
+const REQUEST_TIMEOUT_MS = 10_000;
+async function authorizedFetch(input, init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set(DEVICE_HEADER, knownDeviceId() ?? (await getOrCreateDeviceId()));
+    headers.set("User-Agent", userAgent());
+    const response = await globalThis.fetch(input, { ...init, headers });
+    const bearer = headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
+    if (response.status !== 401 || !bearer || isStreamBody(init.body))
+        return response;
+    const fresh = await refreshAccessTokenAfterRefusal(bearer).catch(() => null);
+    if (!fresh)
+        return response;
+    headers.set("Authorization", `Bearer ${fresh}`);
+    return globalThis.fetch(input, { ...init, headers });
+}
+function isStreamBody(body) {
+    return body != null && typeof body !== "string" && !(body instanceof ArrayBuffer) && !ArrayBuffer.isView(body) && !(body instanceof URLSearchParams);
+}
+const KEYS_PLANE = "the credential plane (/api/v1/keys)";
+function errorMessage(payload, status, label, plane) {
+    if (plane && status === 404 && typeof payload?.error === "string") {
+        return `${label}: this NuStack deployment does not serve ${plane} — the server half of this command is not deployed, so it cannot succeed against this host.`;
+    }
+    const enveloped = typeof payload?.error === "object" ? payload.error?.message : undefined;
+    return enveloped ?? payload?.message ?? `${label}: HTTP ${status}`;
+}
+export function resolveNuStackUrl(options) {
+    return assertSafeNuStackUrl(options.nustackUrl ?? process.env.NUSTACK_URL ?? DEFAULT_NUSTACK_URL);
+}
+export async function fetchCatalogue(baseUrl) {
+    const response = await authorizedFetch(`${baseUrl}/api/catalog.json`, {
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`catalogue fetch failed: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}
+function narrowProjection(projection, service) {
+    if (!projection.endpoint || !projection.serviceKey || !projection.grantId) {
+        throw new Error(`the projection for '${service}' is incomplete`);
+    }
+    if (projection.environmentKey !== "dev") {
+        throw new Error(`refusing a '${projection.environmentKey}' credential for '${service}' — the CLI is development-plane only`);
+    }
+    return {
+        service: projection.service,
+        endpoint: projection.endpoint,
+        serviceKey: projection.serviceKey,
+        grantId: projection.grantId,
+        environmentKey: projection.environmentKey,
+    };
+}
+export async function exchangeServiceCredential(baseUrl, accessToken, params) {
+    const response = await authorizedFetch(`${baseUrl}/api/v1/keys/exchange`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ workspaceId: params.workspaceId, service: params.service }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.serviceKey) {
+        throw new Error(errorMessage(payload, response.status, "exchange failed", KEYS_PLANE));
+    }
+    return narrowProjection(payload, params.service);
+}
+export async function fetchServiceCredential(baseUrl, accessToken, params) {
+    const url = new URL(`${baseUrl}/api/v1/keys/credentials`);
+    url.searchParams.set("workspaceId", assertSafeOpaqueId("The Workspace id", params.workspaceId));
+    url.searchParams.set("service", assertSafeOpaqueId("The Service slug", params.service));
+    const response = await authorizedFetch(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.serviceKey) {
+        throw new Error(errorMessage(payload, response.status, `projection for '${params.service}' failed`, KEYS_PLANE));
+    }
+    return narrowProjection(payload, params.service);
+}
+export async function listWorkspaceIntegrations(baseUrl, accessToken, workspaceId) {
+    const url = new URL(`${baseUrl}/api/v1/keys/integrations`);
+    url.searchParams.set("workspaceId", assertSafeOpaqueId("The Workspace id", workspaceId));
+    const response = await authorizedFetch(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.integrations)) {
+        throw new Error(errorMessage(payload, response.status, "integration list failed", KEYS_PLANE));
+    }
+    return payload.integrations;
+}
+export async function fetchBrokeredCredential(baseUrl, accessToken, params) {
+    const service = assertSafeOpaqueId("The Service slug", params.service);
+    const response = await authorizedFetch(`${baseUrl}/api/v1/keys/broker/${encodeURIComponent(service)}`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ workspaceId: params.workspaceId }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.key || !payload?.grantId) {
+        throw new Error(errorMessage(payload, response.status, "broker fetch failed", KEYS_PLANE));
+    }
+    return { url: payload.url ?? null, key: payload.key, meta: payload.meta ?? null, grantId: payload.grantId };
+}
+export async function searchWorkspaces(baseUrl, query, opts = {}) {
+    const url = new URL(`${baseUrl}/public/v1/workspaces`);
+    url.searchParams.set("q", query);
+    if (opts.category)
+        url.searchParams.set("category", opts.category);
+    if (opts.limit)
+        url.searchParams.set("limit", String(opts.limit));
+    const response = await authorizedFetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "workspace search failed"));
+    }
+    return payload.data.items;
+}
+export async function searchCatalogue(baseUrl, query, opts = {}) {
+    const url = new URL(`${baseUrl}/api/catalog/search`);
+    url.searchParams.set("q", query);
+    if (opts.type)
+        url.searchParams.set("type", opts.type);
+    if (opts.limit)
+        url.searchParams.set("limit", String(opts.limit));
+    const response = await authorizedFetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.results)) {
+        throw new Error(payload?.message ?? `service search failed: HTTP ${response.status}`);
+    }
+    return payload.results;
+}
+export async function fetchHandoffManifest(baseUrl, accessToken, params) {
+    const handoffId = assertSafeOpaqueId("The handoff id", params.handoffId);
+    const url = new URL(`${baseUrl}/api/v2/handoffs/${encodeURIComponent(handoffId)}/manifest`);
+    url.searchParams.set("bindingId", assertSafeOpaqueId("The binding id", params.bindingId));
+    const response = await authorizedFetch(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.manifestSha256) {
+        throw new Error(errorMessage(payload, response.status, "handoff manifest fetch failed"));
+    }
+    return payload.data;
+}
+export async function downloadTargetContent(baseUrl, accessToken, contentUrl) {
+    if (!contentUrl.startsWith("/")) {
+        throw new Error("target content URL must be a server-relative path");
+    }
+    const response = await authorizedFetch(`${baseUrl}${contentUrl}`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`target content fetch failed: HTTP ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+export async function fetchBindingEvents(baseUrl, accessToken, params) {
+    const bindingId = assertSafeOpaqueId("The binding id", params.bindingId);
+    const url = new URL(`${baseUrl}/api/v2/bindings/${encodeURIComponent(bindingId)}/events`);
+    url.searchParams.set("after", String(Math.max(0, Math.trunc(params.after))));
+    if (params.limit)
+        url.searchParams.set("limit", String(params.limit));
+    const response = await authorizedFetch(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "binding events fetch failed"));
+    }
+    return payload.data.items;
+}
+export async function acknowledgeBindingCursor(baseUrl, accessToken, params) {
+    const bindingId = assertSafeOpaqueId("The binding id", params.bindingId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/bindings/${encodeURIComponent(bindingId)}/cursor`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ lastAppliedSequence: Math.max(0, Math.trunc(params.lastAppliedSequence)) }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || typeof payload?.data?.lastAppliedWorkspaceSequence !== "number") {
+        throw new Error(errorMessage(payload, response.status, "cursor acknowledgement failed"));
+    }
+    return payload.data.lastAppliedWorkspaceSequence;
+}
+export async function fetchSyncWhitelist(baseUrl, accessToken, bindingId) {
+    const safeId = assertSafeOpaqueId("The binding id", bindingId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/bindings/${encodeURIComponent(safeId)}/sync-whitelist`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.manifestSha256) {
+        throw new Error(errorMessage(payload, response.status, "sync whitelist fetch failed"));
+    }
+    return payload.data;
+}
+export async function reportApplicationDecision(baseUrl, accessToken, report) {
+    const response = await postApplicationReport(baseUrl, accessToken, report, "decision", {
+        decision: report.decision,
+        localStateFingerprint: report.localStateFingerprint,
+        affectedPaths: report.affectedPaths,
+    });
+    const payload = (await response.json().catch(() => null));
+    if (response.status === 409 && payload?.error?.code === "HANDOFF_SUPERSEDED") {
+        return { ok: false, code: "HANDOFF_SUPERSEDED" };
+    }
+    if (!response.ok || payload?.data?.recorded !== true) {
+        throw new Error(errorMessage(payload, response.status, "decision report failed"));
+    }
+    return { ok: true };
+}
+export async function reportApplicationResult(baseUrl, accessToken, report) {
+    const response = await postApplicationReport(baseUrl, accessToken, report, "result", {
+        commitId: report.commitId,
+        status: report.status,
+        manifestHash: report.manifestHash ?? null,
+        noPush: true,
+        diagnostics: report.diagnostics ?? null,
+        affectedPaths: report.affectedPaths ?? [],
+    });
+    await assertReportRecorded(response, "result report failed");
+}
+export async function reportApplicationUndoResult(baseUrl, accessToken, report) {
+    const response = await postApplicationReport(baseUrl, accessToken, report, "undo-result", {
+        outcome: report.outcome,
+        affectedPaths: report.affectedPaths,
+        commitId: report.commitId ?? null,
+    });
+    await assertReportRecorded(response, "undo-result report failed");
+}
+function postApplicationReport(baseUrl, accessToken, report, action, body) {
+    const bindingId = assertSafeOpaqueId("The binding id", report.bindingId);
+    const handoffId = assertSafeOpaqueId("The handoff id", report.handoffId);
+    return authorizedFetch(`${baseUrl}/api/v2/bindings/${encodeURIComponent(bindingId)}/handoff-applications/${encodeURIComponent(handoffId)}/${action}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+            "Idempotency-Key": report.idempotencyKey,
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+}
+async function assertReportRecorded(response, label) {
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || payload?.data?.recorded !== true) {
+        throw new Error(errorMessage(payload, response.status, label));
+    }
+}
+function authHeaders(accessToken) {
+    return { Authorization: `Bearer ${accessToken}` };
+}
+function mutationHeaders(accessToken, idempotencyKey) {
+    return {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+        "Idempotency-Key": idempotencyKey,
+    };
+}
+export async function listOrganizations(baseUrl, accessToken) {
+    const response = await authorizedFetch(`${baseUrl}/api/v2/organizations`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "organization list failed"));
+    }
+    return payload.data.items;
+}
+export async function createOrganization(baseUrl, accessToken, params, idempotencyKey) {
+    const response = await authorizedFetch(`${baseUrl}/api/v2/organizations`, {
+        method: "POST",
+        headers: mutationHeaders(accessToken, idempotencyKey),
+        body: JSON.stringify({ label: params.label, ...(params.slug ? { slug: params.slug } : {}) }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "organization create failed"));
+    }
+    return payload.data;
+}
+export async function listWorkspaces(baseUrl, accessToken, organizationId) {
+    const safeId = assertSafeOpaqueId("The Organization id", organizationId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/workspaces`, {
+        headers: { ...authHeaders(accessToken), "X-NuStack-Organization": safeId },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "workspace list failed"));
+    }
+    return payload.data.items;
+}
+export async function getWorkspace(baseUrl, accessToken, workspaceId) {
+    const safeId = assertSafeOpaqueId("The Workspace id", workspaceId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/workspaces/${encodeURIComponent(safeId)}`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "workspace fetch failed"));
+    }
+    return payload.data;
+}
+export function mintWorkspaceId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    const ms = Date.now();
+    bytes[0] = Math.floor(ms / 2 ** 40) & 0xff;
+    bytes[1] = Math.floor(ms / 2 ** 32) & 0xff;
+    bytes[2] = Math.floor(ms / 2 ** 24) & 0xff;
+    bytes[3] = Math.floor(ms / 2 ** 16) & 0xff;
+    bytes[4] = Math.floor(ms / 2 ** 8) & 0xff;
+    bytes[5] = ms & 0xff;
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    let hex = "";
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, "0");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+async function* readSseFrames(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const parser = createSseParser();
+    const toFrame = (block) => {
+        let data = {};
+        try {
+            const parsed = JSON.parse(block.data);
+            if (parsed && typeof parsed === "object")
+                data = parsed;
+        }
+        catch {
+        }
+        return { event: block.event, data };
+    };
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        for (const block of parser.push(decoder.decode(value, { stream: true })))
+            yield toFrame(block);
+    }
+    for (const block of parser.flush())
+        yield toFrame(block);
+}
+export async function createWorkspaceViaAsk(baseUrl, accessToken, organizationId, prompt, opts = {}) {
+    const safeOrganization = assertSafeOpaqueId("The Organization id", organizationId);
+    const workspaceId = opts.workspaceId ?? mintWorkspaceId();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${baseUrl}/api/v2/ask`, {
+        method: "POST",
+        headers: {
+            ...authHeaders(accessToken),
+            "Content-Type": "application/json",
+            "X-NuStack-Organization": safeOrganization,
+        },
+        body: JSON.stringify({ prompt, workspaceId }),
+    });
+    if (!response.ok || !response.body) {
+        const payload = (await response.json().catch(() => null));
+        throw new Error(errorMessage(payload, response.status, "workspace create failed"));
+    }
+    let started = false;
+    let turnId = null;
+    let generationError = null;
+    for await (const frame of readSseFrames(response.body)) {
+        if (frame.event === "start") {
+            started = true;
+            turnId = typeof frame.data.turnId === "string" ? frame.data.turnId : null;
+            opts.onPhase?.("Workspace created — writing the first document");
+        }
+        else if (frame.event === "thinking" && typeof frame.data.message === "string") {
+            opts.onPhase?.(frame.data.message);
+        }
+        else if (frame.event === "error") {
+            const message = typeof frame.data.message === "string" ? frame.data.message : "generation failed";
+            if (!started)
+                throw new Error(`workspace create failed: ${message}`);
+            generationError = message;
+            break;
+        }
+        else if (frame.event === "done") {
+            break;
+        }
+    }
+    if (!started)
+        throw new Error("workspace create failed: the stream ended before the Workspace was reported");
+    return { workspaceId, turnId, generationError };
+}
+async function postWorkspacePublication(baseUrl, accessToken, workspaceId, action, body, idempotencyKey) {
+    const safeId = assertSafeOpaqueId("The Workspace id", workspaceId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/workspaces/${encodeURIComponent(safeId)}/${action}`, {
+        method: "POST",
+        headers: mutationHeaders(accessToken, idempotencyKey),
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || payload?.data === undefined) {
+        throw new Error(errorMessage(payload, response.status, `workspace ${action} failed`));
+    }
+    return payload.data;
+}
+export async function publishWorkspace(baseUrl, accessToken, workspaceId, profile, idempotencyKey) {
+    return postWorkspacePublication(baseUrl, accessToken, workspaceId, "publish", profile, idempotencyKey);
+}
+export async function unpublishWorkspace(baseUrl, accessToken, workspaceId, idempotencyKey) {
+    return postWorkspacePublication(baseUrl, accessToken, workspaceId, "unpublish", {}, idempotencyKey);
+}
+export async function listDocuments(baseUrl, accessToken, workspaceId) {
+    const safeId = assertSafeOpaqueId("The Workspace id", workspaceId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/documents?workspaceId=${encodeURIComponent(safeId)}`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "document list failed"));
+    }
+    return payload.data.items;
+}
+export async function getDocument(baseUrl, accessToken, documentId) {
+    const safeId = assertSafeOpaqueId("The Document id", documentId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/documents/${encodeURIComponent(safeId)}`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.document?.id) {
+        throw new Error(errorMessage(payload, response.status, "document fetch failed"));
+    }
+    return payload.data;
+}
+export async function listHandoffs(baseUrl, accessToken, workspaceId) {
+    const safeId = assertSafeOpaqueId("The Workspace id", workspaceId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/workspaces/${encodeURIComponent(safeId)}/handoffs`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "handoff list failed"));
+    }
+    return payload.data.items;
+}
+export async function getHandoff(baseUrl, accessToken, handoffId) {
+    const safeId = assertSafeOpaqueId("The handoff id", handoffId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/handoffs/${encodeURIComponent(safeId)}`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "handoff fetch failed"));
+    }
+    return payload.data;
+}
+export async function latestHandoff(baseUrl, accessToken, workspaceId) {
+    const handoffs = await listHandoffs(baseUrl, accessToken, workspaceId);
+    return handoffs.length > 0 ? handoffs[0] : null;
+}
+export async function createBinding(baseUrl, accessToken, workspaceId, input, idempotencyKey) {
+    const safeId = assertSafeOpaqueId("The Workspace id", workspaceId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/workspaces/${encodeURIComponent(safeId)}/bindings`, {
+        method: "POST",
+        headers: mutationHeaders(accessToken, idempotencyKey),
+        body: JSON.stringify({
+            repositoryFingerprint: input.repositoryFingerprint,
+            boundBranch: input.boundBranch,
+            protocolVersion: input.protocolVersion,
+            ...(input.displayName ? { displayName: input.displayName } : {}),
+        }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "binding create failed"));
+    }
+    return payload.data;
+}
+export async function getBinding(baseUrl, accessToken, bindingId) {
+    const safeId = assertSafeOpaqueId("The binding id", bindingId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/bindings/${encodeURIComponent(safeId)}`, {
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "binding fetch failed"));
+    }
+    return payload.data;
+}
+export async function deleteBinding(baseUrl, accessToken, bindingId) {
+    const safeId = assertSafeOpaqueId("The binding id", bindingId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/bindings/${encodeURIComponent(safeId)}`, {
+        method: "DELETE",
+        headers: authHeaders(accessToken),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "binding remove failed"));
+    }
+    return { id: payload.data.id, status: payload.data.status ?? "removed" };
+}
+export async function postBindingHealth(baseUrl, accessToken, bindingId, report) {
+    const safeId = assertSafeOpaqueId("The binding id", bindingId);
+    const response = await authorizedFetch(`${baseUrl}/api/v2/bindings/${encodeURIComponent(safeId)}/health`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify(report),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.data?.id) {
+        throw new Error(errorMessage(payload, response.status, "binding health failed"));
+    }
+    return payload.data;
+}
+export async function listDevices(baseUrl, accessToken) {
+    const response = await authorizedFetch(`${baseUrl}/api/v2/devices`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data?.items)) {
+        throw new Error(errorMessage(payload, response.status, "device list failed"));
+    }
+    return payload.data.items;
+}

package/dist/lib/nustack_store.js

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export function nustackDir() {
+    return path.join(os.homedir(), ".nustack");
+}
+function legacyDeviceFilePath() {
+    return path.join(nustackDir(), "device.json");
+}
+export async function readLegacyDeviceRecord() {
+    try {
+        return JSON.parse(await readFile(legacyDeviceFilePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/onboarding/attach_existing_git.js

@@ -0,0 +1,65 @@
+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 { classifyFolder, attachRejection } from "./folder_state.js";
+import { runRepositoryOnboarding, } from "./binding.js";
+export async function attachExistingGit(ctx, options) {
+    const state = classifyFolder(ctx.cwd);
+    if (state.class !== "git_worktree" || !state.repository || !state.git) {
+        return { ok: false, code: "NOT_A_WORKTREE", message: "`nustack workspace attach` needs an existing Git worktree — run `nustack init` to establish one." };
+    }
+    const rejection = attachRejection(state.git);
+    if (rejection) {
+        return { ok: false, code: rejection.toUpperCase(), message: rejectionMessage(rejection) };
+    }
+    if (state.git.markerWorkspaceId && state.git.markerWorkspaceId !== options.workspaceId && !options.confirmRebind) {
+        return {
+            ok: false,
+            code: "REBIND_CONFIRMATION_REQUIRED",
+            message: `This repository is bound to Workspace ${state.git.markerWorkspaceId}. Re-run with confirmation to rebind it to ${options.workspaceId}.`,
+        };
+    }
+    const boundBranch = readSymbolicBranch(state.repository);
+    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.workspaceId);
+    const baselineCommitId = readHeadCommit(state.repository);
+    const result = await runRepositoryOnboarding({
+        store: ctx.store,
+        baseUrl: ctx.baseUrl,
+        accessToken: ctx.accessToken,
+        deviceRef: ctx.deviceRef,
+        flow: "existing_git",
+        workspaceId: options.workspaceId,
+        organizationId: options.organizationId,
+        repository: state.repository,
+        boundBranch,
+        profile,
+        baselineCommitId,
+        toolkitDeps: ctx.toolkitDeps,
+        runTelemetry: ctx.runTelemetry,
+    });
+    await reconcileLatest(ctx, result.bindingId);
+    return { ok: true, result };
+}
+async function reconcileLatest(ctx, bindingId) {
+    const runtime = {
+        baseUrl: ctx.baseUrl,
+        accessToken: ctx.accessToken,
+        userId: ctx.userId,
+        deviceRef: ctx.deviceRef,
+    };
+    await reconcileInboundBinding(ctx.store, runtime, bindingId).catch(() => { });
+}
+function rejectionMessage(rejection) {
+    switch (rejection) {
+        case "nested_workspace":
+            return "This repository is nested inside another NuStack Workspace — one Workspace has one logical repository root (F-014).";
+        case "operation_in_progress":
+            return "A merge, rebase, cherry-pick, or revert is in progress — finish or abort it, then re-attach.";
+        case "detached_head":
+            return "HEAD is detached — check out a branch before attaching.";
+    }
+}