@nurix/nustack 0.10.0-dev.10

package/dist/lib/onboarding/binding.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { createBinding } from "../nustack_client.js";
+import { getBindingById, getBindingByRepositoryRoot, insertBinding, updateBindingCursor, updateBindingStatus, } from "../local_store/bindings.js";
+import { ensureBindingTelemetry } from "../session_telemetry.js";
+import { readHeadCommit } from "../git-sync/core/repository.js";
+import { writeWorkspaceManifests } from "./manifest_writer.js";
+import { installToolkit } from "../etna/manager.js";
+import { serializeProfileForBinding } from "../etna/profile.js";
+import { SYNC_PROTOCOL_VERSION } from "../git-sync/whitelist/types.js";
+export function computeRepositoryFingerprint(repository) {
+    return createHash("sha256").update(repository.commonDir).digest("hex");
+}
+function bindingIdempotencyKey(workspaceId, deviceRef, fingerprint) {
+    return createHash("sha256").update(`binding:${workspaceId}:${deviceRef}:${fingerprint}`).digest("hex");
+}
+export async function establishBinding(input) {
+    const { store, repository } = input;
+    const fingerprint = computeRepositoryFingerprint(repository);
+    const existing = getBindingByRepositoryRoot(store, repository.repositoryRoot);
+    if (existing && existing.workspaceId === input.workspaceId) {
+        if (input.baselineCommitId && existing.lastProcessedCommitId === null) {
+            updateBindingCursor(store, existing.id, { lastProcessedCommitId: input.baselineCommitId });
+        }
+        if (existing.status === "creating")
+            updateBindingStatus(store, existing.id, "active");
+        await maybeRunTelemetry(input, existing);
+        return { binding: getBindingById(store, existing.id), created: false };
+    }
+    const cloudBinding = await createBinding(input.baseUrl, input.accessToken, input.workspaceId, { repositoryFingerprint: fingerprint, boundBranch: input.boundBranch, protocolVersion: SYNC_PROTOCOL_VERSION }, bindingIdempotencyKey(input.workspaceId, input.deviceRef, fingerprint));
+    const row = getBindingById(store, cloudBinding.id) ??
+        insertBinding(store, {
+            id: cloudBinding.id,
+            workspaceId: input.workspaceId,
+            organizationId: input.organizationId,
+            repositoryRoot: repository.repositoryRoot,
+            gitDir: repository.gitDir,
+            gitCommonDir: repository.commonDir,
+            repositoryFingerprint: fingerprint,
+            boundBranch: input.boundBranch,
+            status: "active",
+            lastProcessedCommitId: input.baselineCommitId ?? null,
+            etnaProfileJson: input.etnaProfileJson ?? null,
+        });
+    await maybeRunTelemetry(input, row);
+    return { binding: getBindingById(store, cloudBinding.id), created: true };
+}
+async function maybeRunTelemetry(input, binding) {
+    if (input.runTelemetry === false)
+        return;
+    await ensureBindingTelemetry({ baseUrl: input.baseUrl, store: input.store, binding }).catch(() => { });
+}
+export async function runRepositoryOnboarding(input) {
+    const baselineCommitId = input.baselineCommitId !== undefined ? input.baselineCommitId : readHeadCommit(input.repository);
+    const established = await establishBinding({
+        store: input.store,
+        baseUrl: input.baseUrl,
+        accessToken: input.accessToken,
+        workspaceId: input.workspaceId,
+        organizationId: input.organizationId,
+        repository: input.repository,
+        boundBranch: input.boundBranch,
+        deviceRef: input.deviceRef,
+        baselineCommitId,
+        etnaProfileJson: serializeProfileForBinding(input.profile),
+        runTelemetry: input.runTelemetry,
+    });
+    const install = await installToolkit(input.store, established.binding.id, input.profile, input.repository.repositoryRoot, input.toolkitDeps ?? {});
+    const workspaceManifest = await writeWorkspaceManifests(input.repository.repositoryRoot, {
+        workspaceId: input.workspaceId,
+        organizationId: input.organizationId,
+        toolkit: {
+            name: input.profile.name,
+            version: input.profile.version,
+            rendererVersion: input.profile.rendererVersion,
+            placementMapVersion: input.profile.placementMapVersion,
+        },
+    });
+    return {
+        flow: input.flow,
+        workspaceId: input.workspaceId,
+        organizationId: input.organizationId,
+        bindingId: established.binding.id,
+        boundBranch: input.boundBranch,
+        baselineCommitId,
+        toolkit: { name: input.profile.name, version: input.profile.version },
+        reused: !established.created,
+        install,
+        workspaceManifest,
+        noPush: true,
+    };
+}

package/dist/lib/onboarding/folder_state.js

@@ -0,0 +1,99 @@
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { resolveRepository, readSymbolicBranch } from "../git-sync/core/repository.js";
+import { readGitOperationState } from "../git-sync/core/operation_state.js";
+import { NotARepositoryError } from "../git-sync/core/git_runner.js";
+import { legacyAppJsonPath, workspaceJsonPath } from "../workspace_context.js";
+const SAFE_OS_METADATA = new Set([".DS_Store", "Thumbs.db", "desktop.ini", ".localized"]);
+function significantEntries(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((name) => name !== ".git" && !SAFE_OS_METADATA.has(name));
+}
+function readMarkerWorkspaceId(root) {
+    const v2 = read(workspaceJsonPath(root));
+    if (v2 && v2.schemaVersion === 2) {
+        const id = trimmedField(v2.workspaceId);
+        if (id)
+            return id;
+    }
+    const v1 = read(legacyAppJsonPath(root));
+    return v1 ? trimmedField(v1.appId) : null;
+}
+function read(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function trimmedField(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function isNestedUnderWorkspace(root) {
+    let dir = path.dirname(root);
+    while (dir && dir !== path.dirname(dir)) {
+        const nustack = path.join(dir, ".nustack");
+        if (existsSync(path.join(nustack, "workspace.json")) || existsSync(path.join(nustack, "app.json")))
+            return true;
+        dir = path.dirname(dir);
+    }
+    return false;
+}
+export function classifyFolder(dir) {
+    const entries = significantEntries(dir);
+    const gitPath = path.join(dir, ".git");
+    const hasGit = existsSync(gitPath);
+    if (hasGit) {
+        let repository;
+        try {
+            repository = resolveRepository(dir);
+        }
+        catch (error) {
+            if (error instanceof NotARepositoryError) {
+                return { class: "populated_non_git", entries };
+            }
+            throw error;
+        }
+        const symbolicBranch = readSymbolicBranch(repository);
+        const operation = readGitOperationState(repository);
+        const pointerFileGit = lstatSync(gitPath).isFile();
+        const markerWorkspaceId = readMarkerWorkspaceId(repository.repositoryRoot);
+        return {
+            class: "git_worktree",
+            entries,
+            repository,
+            git: {
+                clean: operation.kind === "normal" && symbolicBranch !== null,
+                detachedHead: symbolicBranch === null,
+                operationKind: operation.kind,
+                operationInProgress: operation.kind !== "normal",
+                pointerFileGit,
+                hasWorkspaceMarker: markerWorkspaceId !== null,
+                markerWorkspaceId,
+                nestedUnderWorkspace: isNestedUnderWorkspace(repository.repositoryRoot),
+                symbolicBranch,
+            },
+        };
+    }
+    if (entries.length === 0)
+        return { class: "genuinely_empty", entries: [] };
+    return { class: "populated_non_git", entries };
+}
+export function attachRejection(git) {
+    if (git.nestedUnderWorkspace)
+        return "nested_workspace";
+    if (git.operationInProgress)
+        return "operation_in_progress";
+    if (git.detachedHead)
+        return "detached_head";
+    return null;
+}

package/dist/lib/onboarding/git_init.js

@@ -0,0 +1,10 @@
+import { execFileSync } from "node:child_process";
+import { resolveRepository } from "../git-sync/core/repository.js";
+export function initGitRepository(dir) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    execFileSync("git", ["init", "-b", "main", dir], { env, stdio: "ignore" });
+    return resolveRepository(dir);
+}

package/dist/lib/onboarding/handoff_apply.js

@@ -0,0 +1,68 @@
+import { downloadTargetContent, fetchHandoffManifest } from "../nustack_client.js";
+import { updateBindingCursor } from "../local_store/bindings.js";
+import { recordInboundCommit } from "../local_store/commit_origins.js";
+import { readHeadCommit } from "../git-sync/core/repository.js";
+import { buildCommit, buildCommitMessage, casBranchRef, materializeTarget, NUSTACK_SYNC_IDENTITY, } from "../git-sync/inbound/apply_commit.js";
+import { decideHandoffContent } from "../git-sync/inbound/content_decision.js";
+export function toResolvedTarget(target) {
+    return {
+        path: target.path,
+        operation: target.operation,
+        targetSha256: target.targetSha256,
+        byteSize: target.byteSize,
+        base: target.baseAbsent ? { absent: true } : { sha256: target.baseSha256 ?? "" },
+        ...(target.contentUrl ? { contentUrl: target.contentUrl } : {}),
+    };
+}
+export async function resolveHandoffTargets(baseUrl, accessToken, handoffId, bindingId) {
+    const manifest = await fetchHandoffManifest(baseUrl, accessToken, { handoffId, bindingId });
+    const bytesByPath = new Map();
+    for (const target of manifest.targets) {
+        if (target.operation === "upsert" && target.contentUrl) {
+            const bytes = await downloadTargetContent(baseUrl, accessToken, target.contentUrl);
+            bytesByPath.set(target.path, Buffer.from(bytes));
+        }
+    }
+    return { manifestTargets: manifest.targets, bytesByPath };
+}
+export function decideOnboardingApply(repo, targets) {
+    if (targets.length === 0)
+        return { kind: "no_op" };
+    const decision = decideHandoffContent(repo, targets);
+    if (decision.kind === "no_op")
+        return { kind: "no_op" };
+    if (decision.kind === "automatic")
+        return { kind: "apply" };
+    return { kind: "overwrite_required", divergent: decision.divergent };
+}
+export function composeOnboardingCommit(store, repo, binding, handoffId, workspaceId, entries) {
+    const oldHead = readHeadCommit(repo);
+    const targets = entries.map((entry) => ({
+        path: entry.path,
+        operation: entry.operation,
+        targetSha256: null,
+        byteSize: entry.bytes ? entry.bytes.byteLength : 0,
+        base: { absent: true },
+    }));
+    const bytesByPath = new Map();
+    for (const entry of entries) {
+        if (entry.operation === "upsert" && entry.bytes)
+            bytesByPath.set(entry.path, entry.bytes);
+    }
+    const message = buildCommitMessage(handoffId, workspaceId, null);
+    const built = buildCommit(repo, oldHead, targets, bytesByPath, message, {
+        authorName: NUSTACK_SYNC_IDENTITY.name,
+        authorEmail: NUSTACK_SYNC_IDENTITY.email,
+        committerName: NUSTACK_SYNC_IDENTITY.name,
+        committerEmail: NUSTACK_SYNC_IDENTITY.email,
+    });
+    for (const target of targets) {
+        materializeTarget(repo, target, built.blobByPath.get(target.path) ?? null, bytesByPath.get(target.path) ?? null);
+    }
+    if (!casBranchRef(repo, binding.boundBranch, built.commitId, oldHead)) {
+        throw new Error("the bound branch moved while recording the onboarding commit — re-run to converge");
+    }
+    recordInboundCommit(store, { bindingId: binding.id, commitId: built.commitId, handoffId });
+    updateBindingCursor(store, binding.id, { lastProcessedCommitId: built.commitId });
+    return { commitId: built.commitId, changedPaths: targets.map((target) => target.path) };
+}

package/dist/lib/onboarding/init_fresh_folder.js

@@ -0,0 +1,100 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { acknowledgeBindingCursor, createWorkspaceViaAsk, getWorkspace, latestHandoff, } from "../nustack_client.js";
+import { getBindingById } from "../local_store/bindings.js";
+import { hasManifest, scaffoldManifest } from "../manifest.js";
+import { fetchToolkitProfile, toolkitProfileFromManifest, ToolkitProfileUnavailableError } from "../etna/profile.js";
+import { fetchHandoffManifest } from "../nustack_client.js";
+import { classifyFolder } from "./folder_state.js";
+import { initGitRepository } from "./git_init.js";
+import { composeOnboardingCommit, resolveHandoffTargets, } from "./handoff_apply.js";
+import { runRepositoryOnboarding, } from "./binding.js";
+export const MANAGED_ONBOARDING_FILES = [".nustack/workspace.json", "nustack.service.json"];
+export async function initFreshFolder(ctx, options) {
+    const state = classifyFolder(ctx.cwd);
+    if (state.class === "git_worktree") {
+        return { ok: false, code: "ALREADY_A_WORKTREE", message: "This folder is already a Git worktree — use `nustack workspace attach` instead of `nustack init`." };
+    }
+    if (state.class === "populated_non_git" && options.confirmPopulated !== true) {
+        return {
+            ok: false,
+            code: "CONFIRMATION_REQUIRED",
+            message: `This folder has ${state.entries.length} existing file(s). Onboarding will create only ${MANAGED_ONBOARDING_FILES.join(", ")} and make one commit of just those — no pre-existing file is staged, and no remote or push is created. Re-run with confirmation to proceed.`,
+            managedFiles: MANAGED_ONBOARDING_FILES,
+        };
+    }
+    if (!hasManifest(ctx.cwd)) {
+        await scaffoldManifest(ctx.cwd, options.slug);
+    }
+    const repository = initGitRepository(ctx.cwd);
+    const boundBranch = "main";
+    const workspaceId = options.workspaceId ?? (await createFreshWorkspace(ctx, state.class, options));
+    if (workspaceId === null) {
+        return { ok: false, code: "WORKSPACE_INITIALIZATION_FAILED", message: "The Workspace failed to initialize — check the Organization and try again." };
+    }
+    const profile = await resolveProfile(ctx, workspaceId);
+    if (!profile) {
+        return { ok: false, code: "HARNESS_PROFILE_UNAVAILABLE", message: "The Workspace did not project a Toolkit Profile pin — the owning server plan must expose it." };
+    }
+    const result = await runRepositoryOnboarding({
+        store: ctx.store,
+        baseUrl: ctx.baseUrl,
+        accessToken: ctx.accessToken,
+        deviceRef: ctx.deviceRef,
+        flow: "fresh_folder",
+        workspaceId,
+        organizationId: options.organizationId,
+        repository,
+        boundBranch,
+        profile,
+        baselineCommitId: null,
+        toolkitDeps: ctx.toolkitDeps,
+        runTelemetry: ctx.runTelemetry,
+    });
+    const seed = await latestHandoff(ctx.baseUrl, ctx.accessToken, workspaceId);
+    const entries = MANAGED_ONBOARDING_FILES.map((rel) => ({
+        path: rel,
+        operation: "upsert",
+        bytes: readFileSync(path.join(repository.repositoryRoot, rel)),
+    }));
+    if (seed) {
+        const { manifestTargets, bytesByPath } = await resolveHandoffTargets(ctx.baseUrl, ctx.accessToken, seed.id, result.bindingId);
+        for (const target of manifestTargets) {
+            if (!target.baseAbsent) {
+                return { ok: false, code: "SEED_TARGET_NOT_BASE_ABSENT", message: `Seed Handoff target ${target.path} is not baseAbsent — a fresh folder cannot host a non-clean target.` };
+            }
+            entries.push({ path: target.path, operation: target.operation, bytes: bytesByPath.get(target.path) ?? null });
+        }
+    }
+    const binding = getBindingById(ctx.store, result.bindingId);
+    const handoffId = seed?.id ?? `onboarding_seed:${workspaceId}`;
+    const commit = composeOnboardingCommit(ctx.store, repository, binding, handoffId, workspaceId, entries);
+    if (seed) {
+        await acknowledgeBindingCursor(ctx.baseUrl, ctx.accessToken, { bindingId: result.bindingId, lastAppliedSequence: 0 }).catch(() => { });
+    }
+    return {
+        ok: true,
+        result: { ...result, baselineCommitId: commit.commitId, rootCommitId: commit.commitId, changedPaths: commit.changedPaths, handoffId: seed?.id ?? null },
+    };
+}
+async function createFreshWorkspace(ctx, folderClass, options) {
+    void folderClass;
+    const outcome = await createWorkspaceViaAsk(ctx.baseUrl, ctx.accessToken, options.organizationId, `Create a workspace named "${options.name}".`);
+    const final = await getWorkspace(ctx.baseUrl, ctx.accessToken, outcome.workspaceId);
+    const failed = final.status === "initialization_failed" || final.initStatus === "failed";
+    return failed ? null : outcome.workspaceId;
+}
+async function resolveProfile(ctx, workspaceId) {
+    try {
+        return await fetchToolkitProfile(ctx.baseUrl, ctx.accessToken, workspaceId);
+    }
+    catch (error) {
+        if (!(error instanceof ToolkitProfileUnavailableError))
+            throw error;
+    }
+    const seed = await latestHandoff(ctx.baseUrl, ctx.accessToken, workspaceId);
+    if (!seed)
+        return null;
+    const manifest = await fetchHandoffManifest(ctx.baseUrl, ctx.accessToken, { handoffId: seed.id, bindingId: "" }).catch(() => null);
+    return manifest ? toolkitProfileFromManifest(manifest) : null;
+}

package/dist/lib/onboarding/manifest_writer.js

@@ -0,0 +1,161 @@
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { legacyAppJsonPath, readBindingMarker, workspaceJsonPath } from "../workspace_context.js";
+import { manifestPath } from "../manifest.js";
+const CURRENT_BINDING_PROTOCOL_VERSION = 1;
+const CURRENT_DOCUMENT_PROTOCOL_VERSION = 1;
+function buildWorkspaceManifest(identity) {
+    return {
+        schemaVersion: 2,
+        workspaceId: identity.workspaceId,
+        organizationId: identity.organizationId,
+        bindingProtocolVersion: identity.bindingProtocolVersion ?? CURRENT_BINDING_PROTOCOL_VERSION,
+        documentProtocolVersion: identity.documentProtocolVersion ?? CURRENT_DOCUMENT_PROTOCOL_VERSION,
+        toolkit: {
+            name: identity.toolkit.name,
+            version: identity.toolkit.version,
+            rendererVersion: identity.toolkit.rendererVersion,
+            placementMapVersion: identity.toolkit.placementMapVersion,
+        },
+    };
+}
+async function atomicWrite(target, content) {
+    const prior = existsSync(target) ? await readFile(target, "utf8") : null;
+    const temp = `${target}.nustack-tmp-${process.pid}`;
+    await writeFile(temp, content, "utf8");
+    await rename(temp, target);
+    return prior;
+}
+async function restore(target, prior) {
+    if (prior === null) {
+        await unlink(target).catch(() => { });
+    }
+    else {
+        await writeFile(target, prior, "utf8");
+    }
+}
+export async function writeWorkspaceManifests(root, identity, hooks = {}) {
+    const servicePath = manifestPath(root);
+    if (!existsSync(servicePath)) {
+        throw new Error("nustack.service.json is required before writing the Workspace binding — scaffold it first.");
+    }
+    const serviceRaw = await readFile(servicePath, "utf8");
+    let serviceManifest;
+    try {
+        serviceManifest = JSON.parse(serviceRaw);
+    }
+    catch {
+        throw new Error("nustack.service.json is not valid JSON — refusing to overwrite it.");
+    }
+    const nextService = {
+        ...serviceManifest,
+        nustackWorkspace: { v: 2, workspaceId: identity.workspaceId, organizationId: identity.organizationId },
+        toolkit: { name: identity.toolkit.name, version: identity.toolkit.version },
+    };
+    delete nextService.nustackApp;
+    const workspaceManifest = buildWorkspaceManifest(identity);
+    const workspaceDir = path.dirname(workspaceJsonPath(root));
+    await mkdir(workspaceDir, { recursive: true });
+    const workspacePrior = await atomicWrite(workspaceJsonPath(root), JSON.stringify(workspaceManifest, null, 2) + "\n");
+    try {
+        if (hooks.beforeServiceWrite)
+            await hooks.beforeServiceWrite();
+        await atomicWrite(servicePath, JSON.stringify(nextService, null, 4) + "\n");
+    }
+    catch (error) {
+        await restore(workspaceJsonPath(root), workspacePrior);
+        throw error;
+    }
+    return workspaceManifest;
+}
+function toolkitEqual(a, b) {
+    return a !== null && b !== null && a.name === b.name && a.version === b.version;
+}
+export async function readWorkspaceManifests(root) {
+    const workspaceManifest = await readWorkspaceJson(root);
+    const service = await readServiceBlocks(root);
+    let localDiagnosis;
+    if (!workspaceManifest || !service.toolkit) {
+        localDiagnosis = "missing";
+    }
+    else {
+        localDiagnosis = toolkitEqual(workspaceManifest.toolkit, service.toolkit) ? "aligned" : "divergent";
+    }
+    return {
+        workspaceManifest,
+        serviceWorkspaceBinding: service.binding,
+        serviceToolkit: service.toolkit,
+        localDiagnosis,
+    };
+}
+export function diagnoseManifests(cloud, workspaceJson, serviceJson) {
+    if (!workspaceJson || !serviceJson)
+        return "missing";
+    if (!cloud) {
+        return toolkitEqual(workspaceJson, serviceJson) ? "aligned" : "divergent";
+    }
+    const workspaceOk = toolkitEqual(cloud, workspaceJson);
+    const serviceOk = toolkitEqual(cloud, serviceJson);
+    if (workspaceOk && serviceOk)
+        return "aligned";
+    if (!workspaceOk && serviceOk)
+        return "workspace_json_stale";
+    if (workspaceOk && !serviceOk)
+        return "service_json_stale";
+    return "divergent";
+}
+async function readWorkspaceJson(root) {
+    const marker = await readBindingMarker(root);
+    if (!marker)
+        return null;
+    const filePath = marker.version === 2 ? workspaceJsonPath(root) : legacyAppJsonPath(root);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(await readFile(filePath, "utf8"));
+        if (marker.organizationId === null)
+            return null;
+        const h = raw.toolkit;
+        if (!h || typeof h.name !== "string" || typeof h.version !== "string")
+            return null;
+        return {
+            schemaVersion: 2,
+            workspaceId: marker.workspaceId,
+            organizationId: marker.organizationId,
+            bindingProtocolVersion: typeof raw.bindingProtocolVersion === "number" ? raw.bindingProtocolVersion : 1,
+            documentProtocolVersion: typeof raw.documentProtocolVersion === "number" ? raw.documentProtocolVersion : 1,
+            toolkit: {
+                name: h.name,
+                version: h.version,
+                rendererVersion: typeof h.rendererVersion === "string" ? h.rendererVersion : "",
+                placementMapVersion: typeof h.placementMapVersion === "string" ? h.placementMapVersion : "",
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function readServiceBlocks(root) {
+    const filePath = manifestPath(root);
+    if (!existsSync(filePath))
+        return { binding: null, toolkit: null };
+    try {
+        const manifest = JSON.parse(await readFile(filePath, "utf8"));
+        const v2 = manifest.nustackWorkspace;
+        const v1 = manifest.nustackApp;
+        const binding = typeof v2?.workspaceId === "string" && typeof v2?.organizationId === "string"
+            ? { workspaceId: v2.workspaceId, organizationId: v2.organizationId }
+            : typeof v1?.appId === "string" && typeof v1?.workspaceId === "string"
+                ? { workspaceId: v1.appId, organizationId: v1.workspaceId }
+                : null;
+        const toolkit = typeof manifest.toolkit?.name === "string" && typeof manifest.toolkit?.version === "string"
+            ? { name: manifest.toolkit.name, version: manifest.toolkit.version }
+            : null;
+        return { binding, toolkit };
+    }
+    catch {
+        return { binding: null, toolkit: null };
+    }
+}

package/dist/lib/onboarding/web_first_attach.js

@@ -0,0 +1,133 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { acknowledgeBindingCursor, latestHandoff } from "../nustack_client.js";
+import { fetchHandoffManifest } from "../nustack_client.js";
+import { getBindingById } from "../local_store/bindings.js";
+import { readHeadCommit, readSymbolicBranch } from "../git-sync/core/repository.js";
+import { fetchToolkitProfile, toolkitProfileFromManifest, ToolkitProfileUnavailableError } from "../etna/profile.js";
+import { hasManifest, scaffoldManifest } from "../manifest.js";
+import { classifyFolder, attachRejection } from "./folder_state.js";
+import { initGitRepository } from "./git_init.js";
+import { MANAGED_ONBOARDING_FILES } from "./init_fresh_folder.js";
+import { composeOnboardingCommit, decideOnboardingApply, resolveHandoffTargets, toResolvedTarget, } from "./handoff_apply.js";
+import { runRepositoryOnboarding, } from "./binding.js";
+export async function webFirstAttach(ctx, options) {
+    const state = classifyFolder(ctx.cwd);
+    let repository = state.repository ?? null;
+    let boundBranch;
+    let isFresh;
+    if (state.class === "git_worktree" && state.git && repository) {
+        const rejection = attachRejection(state.git);
+        if (rejection)
+            return { ok: false, code: rejection.toUpperCase(), message: rejectionMessage(rejection) };
+        const branch = readSymbolicBranch(repository);
+        if (!branch)
+            return { ok: false, code: "DETACHED_HEAD", message: "HEAD is detached — check out a branch before attaching." };
+        boundBranch = branch;
+        isFresh = false;
+    }
+    else {
+        if (state.class === "populated_non_git" && options.confirmPopulated !== true) {
+            return {
+                ok: false,
+                code: "CONFIRMATION_REQUIRED",
+                message: `This folder has ${state.entries.length} existing file(s). Attaching will establish Git and create only ${MANAGED_ONBOARDING_FILES.join(", ")} — no pre-existing file is staged, and no remote or push is created. Re-run with confirmation to proceed.`,
+                managedFiles: MANAGED_ONBOARDING_FILES,
+            };
+        }
+        repository = initGitRepository(ctx.cwd);
+        boundBranch = "main";
+        isFresh = true;
+    }
+    if (!hasManifest(repository.repositoryRoot)) {
+        await scaffoldManifest(repository.repositoryRoot, deriveScaffoldSlug(repository.repositoryRoot));
+    }
+    const profile = await resolveProfile(ctx, options.workspaceId);
+    if (!profile)
+        return { ok: false, code: "HARNESS_PROFILE_UNAVAILABLE", message: "The Workspace did not project a Toolkit Profile pin — the owning server plan must expose it." };
+    const baselineCommitId = isFresh ? null : readHeadCommit(repository);
+    const result = await runRepositoryOnboarding({
+        store: ctx.store,
+        baseUrl: ctx.baseUrl,
+        accessToken: ctx.accessToken,
+        deviceRef: ctx.deviceRef,
+        flow: "web_first",
+        workspaceId: options.workspaceId,
+        organizationId: options.organizationId,
+        repository,
+        boundBranch,
+        profile,
+        baselineCommitId,
+        toolkitDeps: ctx.toolkitDeps,
+        runTelemetry: ctx.runTelemetry,
+    });
+    const binding = getBindingById(ctx.store, result.bindingId);
+    const latest = await latestHandoff(ctx.baseUrl, ctx.accessToken, options.workspaceId).catch(() => null);
+    if (!latest) {
+        const applied = isFresh
+            ? composeOnboardingCommit(ctx.store, repository, binding, `onboarding_seed:${options.workspaceId}`, options.workspaceId, managedEntries(repository.repositoryRoot))
+            : null;
+        return { ok: true, result: baseResult(result, applied, null, false, []) };
+    }
+    const { manifestTargets, bytesByPath } = await resolveHandoffTargets(ctx.baseUrl, ctx.accessToken, latest.id, result.bindingId);
+    const resolved = manifestTargets.map(toResolvedTarget);
+    const decision = decideOnboardingApply(repository, resolved);
+    if (decision.kind === "overwrite_required") {
+        return {
+            ok: true,
+            result: baseResult(result, null, latest.id, true, decision.divergent),
+        };
+    }
+    const entries = [];
+    if (isFresh)
+        entries.push(...managedEntries(repository.repositoryRoot));
+    if (decision.kind === "apply") {
+        for (const target of manifestTargets) {
+            entries.push({ path: target.path, operation: target.operation, bytes: bytesByPath.get(target.path) ?? null });
+        }
+    }
+    const applied = entries.length > 0 ? composeOnboardingCommit(ctx.store, repository, binding, latest.id, options.workspaceId, entries) : null;
+    await acknowledgeBindingCursor(ctx.baseUrl, ctx.accessToken, { bindingId: result.bindingId, lastAppliedSequence: 0 }).catch(() => { });
+    return { ok: true, result: baseResult(result, applied, latest.id, false, []) };
+}
+function managedEntries(root) {
+    return MANAGED_ONBOARDING_FILES.map((rel) => ({ path: rel, operation: "upsert", bytes: readFileSync(path.join(root, rel)) }));
+}
+function baseResult(result, applied, handoffId, overwriteRequired, divergent) {
+    return {
+        ...result,
+        baselineCommitId: applied?.commitId ?? result.baselineCommitId,
+        appliedCommitId: applied?.commitId ?? null,
+        changedPaths: applied?.changedPaths ?? [],
+        handoffId,
+        overwriteRequired,
+        divergent,
+    };
+}
+async function resolveProfile(ctx, workspaceId) {
+    try {
+        return await fetchToolkitProfile(ctx.baseUrl, ctx.accessToken, workspaceId);
+    }
+    catch (error) {
+        if (!(error instanceof ToolkitProfileUnavailableError))
+            throw error;
+    }
+    const seed = await latestHandoff(ctx.baseUrl, ctx.accessToken, workspaceId).catch(() => null);
+    if (!seed)
+        return null;
+    const manifest = await fetchHandoffManifest(ctx.baseUrl, ctx.accessToken, { handoffId: seed.id, bindingId: "" }).catch(() => null);
+    return manifest ? toolkitProfileFromManifest(manifest) : null;
+}
+function deriveScaffoldSlug(root) {
+    return path.basename(root).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "workspace";
+}
+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.";
+    }
+}