@nurix/nustack 0.10.0-dev.10

package/dist/commands/review.js

@@ -0,0 +1,152 @@
+import { ensureAccessToken } from "../lib/auth_grant.js";
+import { resolveNuStackUrl } from "../lib/nustack_client.js";
+import { makeReviewClient, ReviewUnreachableError } from "../lib/review/client.js";
+import { printJsonSuccess } from "../lib/json_output.js";
+const EXIT_FOR = {
+    signed: 0,
+    refused: 1,
+    none: 1,
+    unreachable: 2,
+};
+export function decisionStateOf(items) {
+    const latest = items.find((item) => item.answer?.verdict === "signed" || item.answer?.verdict === "refused");
+    if (!latest)
+        return "none";
+    return latest.answer?.verdict === "signed" ? "signed" : "refused";
+}
+function checkLine(state, commit) {
+    switch (state) {
+        case "signed":
+            return `review check: ${commit} is signed off\n`;
+        case "refused":
+            return `review check: ${commit} was refused\n`;
+        case "none":
+            return `review check: ${commit} has no answered decision\n`;
+        case "unreachable":
+            return `review check: NuStack is unreachable or this device is signed out\n`;
+    }
+}
+export async function runReviewCheck(options, globals) {
+    const json = options.json === true;
+    const commit = options.commit?.trim() ?? "";
+    if (!commit) {
+        process.stderr.write("review check: --commit is required\n");
+        process.exitCode = 2;
+        return;
+    }
+    const report = (state) => {
+        if (json)
+            printJsonSuccess("review check", { commit, state, exitCode: EXIT_FOR[state] });
+        else
+            process.stdout.write(checkLine(state, commit));
+        process.exitCode = EXIT_FOR[state];
+    };
+    const baseUrl = resolveNuStackUrl(globals);
+    const deviceAuth = await ensureAccessToken(baseUrl).catch(() => null);
+    if (!deviceAuth)
+        return report("unreachable");
+    try {
+        const items = await makeReviewClient(baseUrl, deviceAuth.accessToken).readDecisions(commit, options.repository?.trim() || null);
+        report(decisionStateOf(items));
+    }
+    catch (error) {
+        if (error instanceof ReviewUnreachableError)
+            return report("unreachable");
+        process.stderr.write(`review check: ${error instanceof Error ? error.message : String(error)}\n`);
+        report("unreachable");
+    }
+}
+function readSubject(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const row = parsed;
+    const toolName = typeof row.toolName === "string" ? row.toolName.trim() : "";
+    if (!toolName)
+        return null;
+    const displayName = typeof row.displayName === "string" && row.displayName.trim() ? row.displayName.trim() : toolName;
+    return {
+        type: "tool_permission",
+        toolName,
+        displayName,
+        toolInput: row.toolInput ?? null,
+        ...(typeof row.description === "string" ? { description: row.description } : {}),
+    };
+}
+function mirrorReport(json, state, id, note) {
+    if (json) {
+        printJsonSuccess("review mirror", { state, id, ...(note ? { note } : {}) });
+        return;
+    }
+    if (note)
+        process.stderr.write(`review mirror: ${note}\n`);
+    else
+        process.stdout.write(`review mirror: ${state}${id ? ` ${id}` : ""}\n`);
+}
+export async function runReviewMirror(options, globals) {
+    const json = options.json === true;
+    const state = options.state?.trim();
+    const sessionId = options.session?.trim() ?? "";
+    if (state !== "open" && state !== "answered") {
+        return mirrorReport(json, "skipped", null, "--state must be open or answered");
+    }
+    if (!sessionId)
+        return mirrorReport(json, "skipped", null, "--session is required");
+    const baseUrl = resolveNuStackUrl(globals);
+    const deviceAuth = await ensureAccessToken(baseUrl).catch(() => null);
+    if (!deviceAuth)
+        return mirrorReport(json, "skipped", null, "signed out");
+    const client = makeReviewClient(baseUrl, deviceAuth.accessToken);
+    try {
+        if (state === "answered") {
+            const id = options.id?.trim();
+            const verdict = options.verdict?.trim();
+            if (!id)
+                return mirrorReport(json, "skipped", null, "--id is required to answer a mirrored prompt");
+            if (verdict !== "allow" && verdict !== "deny") {
+                return mirrorReport(json, "skipped", null, "--verdict must be allow or deny");
+            }
+            const answered = await client.answerReviewItem(id, verdict);
+            return mirrorReport(json, "answered", answered.id);
+        }
+        const workspaceId = options.workspace?.trim() ?? "";
+        if (!workspaceId)
+            return mirrorReport(json, "skipped", null, "--workspace is required to open a mirrored prompt");
+        const subject = readSubject(options.subject);
+        if (!subject)
+            return mirrorReport(json, "skipped", null, "--subject must be a tool-permission JSON object");
+        const created = await client.createReviewItem({ workspaceId, sessionId, subject });
+        return mirrorReport(json, "open", created.id);
+    }
+    catch (error) {
+        return mirrorReport(json, "skipped", null, error instanceof Error ? error.message : String(error));
+    }
+}
+export function registerReviewCommands(reviewCommand, getGlobalOptions) {
+    reviewCommand
+        .command("check")
+        .description("Exit 0 when a person's sign-off stands against a commit, 1 when it does not, 2 when NuStack cannot be reached")
+        .option("--commit <sha>", "the commit the sign-off is owed against")
+        .option("--repository <url>", "narrow to one repository when a commit sha is ambiguous")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runReviewCheck(options, getGlobalOptions()));
+    reviewCommand
+        .command("mirror")
+        .description("Reflect a lane's permission prompt, or its answer, into the Review pane")
+        .option("--session <laneId>", "the lane's session id")
+        .option("--workspace <id>", "the Workspace the lane's folder is bound to (required with --state open)")
+        .option("--state <state>", "open or answered")
+        .option("--subject <json>", "the tool-permission subject, as JSON (required with --state open)")
+        .option("--verdict <verdict>", "allow or deny (required with --state answered)")
+        .option("--id <rowId>", "the mirrored row to answer (required with --state answered)")
+        .option("--json", "emit the versioned machine envelope")
+        .action(async (options) => runReviewMirror(options, getGlobalOptions()));
+}

package/dist/commands/search.js

@@ -0,0 +1,57 @@
+import { resolveNuStackUrl, searchWorkspaces, searchCatalogue, } from "../lib/nustack_client.js";
+export async function runSearch(keywords, options, globals) {
+    const query = keywords.join(" ").trim();
+    if (!query) {
+        console.error("Usage: nustack search <keywords> — give at least one keyword.");
+        process.exitCode = 1;
+        return;
+    }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        console.error("Usage: nustack search --limit <n> — n must be a positive integer.");
+        process.exitCode = 1;
+        return;
+    }
+    const baseUrl = resolveNuStackUrl(globals);
+    const results = await searchWorkspaces(baseUrl, query, { category: options.category, limit: options.limit });
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No workspaces matched "${query}". Looking for a platform capability? Try \`nustack search services ${query}\`.`);
+        return;
+    }
+    console.log(`${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`);
+    for (const workspace of results) {
+        const category = workspace.categories[0] ?? "—";
+        console.log(`${workspace.displayName.padEnd(28)} ${category.padEnd(16)} ${workspace.tagline ?? ""}`);
+        const link = workspace.links[0];
+        if (link)
+            console.log(`  ${link.url}`);
+    }
+}
+export async function runSearchServices(keywords, options, globals) {
+    const query = keywords.join(" ").trim();
+    if (!query) {
+        console.error("Usage: nustack search services <keywords> — give at least one keyword.");
+        process.exitCode = 1;
+        return;
+    }
+    const baseUrl = resolveNuStackUrl(globals);
+    const results = await searchCatalogue(baseUrl, query, { type: options.type, limit: options.limit });
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No services matched "${query}". Browse the full catalogue with \`nustack list\`.`);
+        return;
+    }
+    console.log(`${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`);
+    for (const service of results) {
+        const classifier = service.type ?? service.kind ?? "?";
+        const status = service.status ?? "?";
+        console.log(`${service.name.padEnd(28)} ${classifier.padEnd(14)} ${status.padEnd(12)} ${service.description ?? ""}`);
+        console.log(`  → nustack add ${service.name}`);
+    }
+}

package/dist/commands/sessions.js

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import { ensureAccessToken } from "../lib/auth_grant.js";
+import { resolveNuStackUrl } from "../lib/nustack_client.js";
+import { makeSessionsClient } from "../lib/sessions/client.js";
+import { recordOutsideSessions, } from "../lib/sessions/outsideSessions.js";
+import { printJsonSuccess } from "../lib/json_output.js";
+async function readScanArgument(raw) {
+    const body = raw.startsWith("@") ? await readFile(raw.slice(1), "utf8") : raw;
+    return JSON.parse(body);
+}
+function readTranscripts(value) {
+    if (!Array.isArray(value))
+        return [];
+    const transcripts = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const row = entry;
+        const sessionKey = typeof row.sessionKey === "string" ? row.sessionKey : null;
+        const provider = typeof row.provider === "string" ? row.provider : null;
+        const modifiedMs = typeof row.modifiedMs === "number" ? row.modifiedMs : null;
+        if (!sessionKey || !provider || modifiedMs === null)
+            continue;
+        transcripts.push({
+            sessionKey,
+            provider,
+            modifiedMs,
+            workspaceId: typeof row.workspaceId === "string" && row.workspaceId ? row.workspaceId : null,
+            vendorSessionId: typeof row.id === "string" && row.id ? row.id : null,
+            ...(typeof row.sizeBytes === "number" ? { sizeBytes: row.sizeBytes } : {}),
+        });
+    }
+    return transcripts;
+}
+const EMPTY = { created: 0, finished: 0, skipped: 0, failed: 0 };
+function report(command, summary, json, note) {
+    if (json) {
+        printJsonSuccess(command, { ...summary, ...(note ? { note } : {}) });
+        return;
+    }
+    process.stdout.write(`sessions record: ${summary.created} created, ${summary.finished} finished, ${summary.skipped} unchanged, ${summary.failed} failed${note ? ` (${note})` : ""}\n`);
+}
+export async function runSessionsRecord(options, globals) {
+    const json = options.json === true;
+    const baseUrl = resolveNuStackUrl(globals);
+    if (!options.scan)
+        return report("sessions record", EMPTY, json, "no scan payload");
+    const payload = (await readScanArgument(options.scan).catch(() => null));
+    const transcripts = readTranscripts(payload?.sessions);
+    if (transcripts.length === 0)
+        return report("sessions record", EMPTY, json, "nothing to record");
+    const deviceAuth = await ensureAccessToken(baseUrl).catch(() => null);
+    if (!deviceAuth)
+        return report("sessions record", EMPTY, json, "signed out");
+    const summary = await recordOutsideSessions(makeSessionsClient(baseUrl, deviceAuth.accessToken), {
+        transcripts,
+        laneSessionIds: Array.isArray(payload?.laneSessionIds)
+            ? payload.laneSessionIds.filter((id) => typeof id === "string")
+            : [],
+    });
+    report("sessions record", summary, json);
+}

package/dist/commands/sync.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { exchangeServiceCredential, fetchServiceCredential, listWorkspaceIntegrations, resolveNuStackUrl, } from "../lib/nustack_client.js";
+import { readConsumesEdges } from "../lib/manifest.js";
+import { ensureAccessToken, signedOutCopy } from "../lib/auth_grant.js";
+import { resolveWorkspaceId } from "../lib/workspace_context.js";
+import { readManagedValues, writeManagedValues } from "../lib/env_file.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+const COMMAND = "sync";
+const signedOut = () => signedOutCopy();
+export async function runSync(options) {
+    const cwd = process.cwd();
+    const baseUrl = resolveNuStackUrl(options);
+    const json = options.json === true;
+    if (!json)
+        p.intro("nustack sync");
+    const deviceAuth = await ensureAccessToken(baseUrl).catch(() => null);
+    if (!deviceAuth)
+        return failSync(json, "SIGNED_OUT", signedOut(), "The managed block was not touched.");
+    const accessToken = deviceAuth.accessToken;
+    const workspace = await resolveWorkspaceId(cwd, { workspace: options.workspace });
+    if (!workspace.ok)
+        return failSync(json, "WORKSPACE_UNRESOLVED", workspace.message, "The managed block was not touched.");
+    const spinner = json ? null : p.spinner();
+    spinner?.start("Exchanging declared services");
+    let activeServices;
+    let projections;
+    try {
+        for (const edge of await readConsumesEdges(cwd)) {
+            await exchangeServiceCredential(baseUrl, accessToken, { workspaceId: workspace.workspaceId, service: edge.service });
+        }
+        spinner?.message("Enumerating active integrations");
+        const integrations = await listWorkspaceIntegrations(baseUrl, accessToken, workspace.workspaceId);
+        activeServices = integrations.filter((i) => i.status === "active").map((i) => i.serviceSlug);
+        projections = [];
+        for (const service of activeServices) {
+            projections.push(await fetchServiceCredential(baseUrl, accessToken, { workspaceId: workspace.workspaceId, service }));
+        }
+    }
+    catch (error) {
+        spinner?.stop("Projection failed", 1);
+        return failSync(json, "PROJECTION_FAILED", error instanceof Error ? error.message : String(error), "The managed block was not touched.");
+    }
+    spinner?.stop(`${projections.length} service credential(s) projected`);
+    const managedValues = await readManagedValues(path.join(cwd, ".env"));
+    const nextValues = {};
+    if (managedValues.NUSTACK_WORKSPACE_ID)
+        nextValues.NUSTACK_WORKSPACE_ID = managedValues.NUSTACK_WORKSPACE_ID;
+    for (const credential of [...projections].sort((a, b) => a.service.localeCompare(b.service))) {
+        const prefix = toEnvPrefix(credential.service);
+        nextValues[`${prefix}_ENDPOINT`] = credential.endpoint;
+        nextValues[`${prefix}_KEY`] = credential.serviceKey;
+    }
+    const removedKeys = Object.keys(managedValues).filter((key) => !(key in nextValues));
+    const placeholders = {};
+    for (const key of Object.keys(nextValues))
+        placeholders[key] = "";
+    await writeManagedValues(path.join(cwd, ".env"), nextValues);
+    await writeManagedValues(path.join(cwd, ".env.example"), placeholders);
+    if (json) {
+        printJsonSuccess(COMMAND, {
+            workspaceId: workspace.workspaceId,
+            integrations: activeServices.map((service) => ({ service, status: "active" })),
+            envKeysWritten: Object.keys(nextValues),
+            removedKeys,
+        });
+        return;
+    }
+    p.log.success(`Managed block rewritten: ${projections.length} service credential(s).`);
+    if (removedKeys.length > 0)
+        p.log.info(`Removed stale entries: ${removedKeys.join(", ")}`);
+    p.outro("In sync with NuStack — Service credentials only (Documents & Git are `nustack workspace sync`).");
+}
+function failSync(json, code, message, humanTail) {
+    if (json) {
+        printJsonError(COMMAND, { code, message });
+        return;
+    }
+    p.log.error(message);
+    p.outro(humanTail);
+    process.exitCode = 1;
+}
+function toEnvPrefix(serviceName) {
+    return serviceName.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}

package/dist/commands/telemetry.js

@@ -0,0 +1,112 @@
+import * as p from "@clack/prompts";
+import { resolveNuStackUrl } from "../lib/nustack_client.js";
+import { printJsonSuccess } from "../lib/json_output.js";
+import { openLocalStore } from "../lib/local_store/database.js";
+import { getBindingByRepositoryRoot, listActiveBindings, setBindingTelemetry, } from "../lib/local_store/bindings.js";
+import { upsertFilebeatState } from "../lib/local_store/filebeat_state.js";
+import { ensureFilebeatBinary, unregisterService } from "../lib/filebeat_installer.js";
+import { collectTelemetryStatus } from "../lib/telemetry/health_report.js";
+import { ensureBindingTelemetry } from "../lib/session_telemetry.js";
+import { resolveRepository } from "../lib/git-sync/core/repository.js";
+function resolveTargetBinding(store, options) {
+    if (options.device)
+        return null;
+    try {
+        const { repositoryRoot } = resolveRepository(options.cwd ?? process.cwd());
+        return getBindingByRepositoryRoot(store, repositoryRoot);
+    }
+    catch {
+        return null;
+    }
+}
+function folderLabel(binding) {
+    const segments = binding.repositoryRoot.split("/").filter(Boolean);
+    return segments[segments.length - 1] ?? binding.id;
+}
+export async function runTelemetry(action, options) {
+    const json = options.json ?? false;
+    const store = await openLocalStore();
+    try {
+        const verbose = { localVerbose: options.localVerbose === true };
+        if (action === "status") {
+            const status = await collectTelemetryStatus(store, undefined, verbose);
+            if (json) {
+                printJsonSuccess("telemetry status", status);
+                return;
+            }
+            const shipping = status.folders.filter((f) => f.enabled).length;
+            p.intro("nustack telemetry status");
+            p.note([
+                `telemetry_enabled: ${status.telemetryEnabled}`,
+                `env opt-out:       ${status.optedOutByEnv}`,
+                `binary:            ${status.binaryPath ?? "not installed"}`,
+                `version:           desired ${status.desiredVersion ?? "—"} / observed ${status.observedVersion ?? "—"}`,
+                `service:           ${status.serviceRegistered ? "registered" : "not registered"}`,
+                `install state:     ${status.filebeatState}${status.lastErrorCode ? ` (${status.lastErrorCode})` : ""}`,
+                `config version:    ${status.desiredConfigVersion}`,
+                `folders:           ${shipping} of ${status.folders.length} shipping`,
+                `last cloud report: ${status.lastHealthAtMs ? new Date(status.lastHealthAtMs).toISOString() : "never"}`,
+            ].join("\n"), "Telemetry");
+            p.outro("Telemetry status.");
+            return;
+        }
+        const target = action === "reinstall" ? null : resolveTargetBinding(store, options);
+        if (target) {
+            const enabled = action === "enable";
+            setBindingTelemetry(store, target.id, enabled);
+            const baseUrl = resolveNuStackUrl(options);
+            await ensureBindingTelemetry({ baseUrl, store, binding: { ...target, telemetryEnabled: enabled } });
+            const status = await collectTelemetryStatus(store, undefined, verbose);
+            if (json) {
+                printJsonSuccess(`telemetry ${action}`, {
+                    scope: "folder",
+                    bindingId: target.id,
+                    folderEnabled: enabled,
+                    ...status,
+                });
+                return;
+            }
+            p.intro(`nustack telemetry ${action}`);
+            p.log.success(enabled
+                ? `${folderLabel(target)} is shipping. Other folders are unchanged.`
+                : `${folderLabel(target)} has stopped shipping and its input config is removed. Other folders are unchanged.`);
+            p.outro(`Run \`nustack telemetry ${enabled ? "disable" : "enable"}\` here to reverse it.`);
+            return;
+        }
+        if (action === "disable") {
+            unregisterService();
+            upsertFilebeatState(store, { telemetryEnabled: false, processState: "stopped" });
+            if (json) {
+                printJsonSuccess("telemetry disable", {
+                    scope: "device",
+                    bindingId: null,
+                    telemetryEnabled: false,
+                });
+                return;
+            }
+            p.log.success("Stopped the telemetry shipper on this machine; every folder reports disabled (Document sync untouched).");
+            p.outro("Run `nustack telemetry enable` to resume.");
+            return;
+        }
+        const baseUrl = resolveNuStackUrl(options);
+        upsertFilebeatState(store, { telemetryEnabled: true });
+        if (action === "reinstall")
+            await ensureFilebeatBinary(() => { });
+        const bindings = listActiveBindings(store);
+        for (const binding of bindings) {
+            await ensureBindingTelemetry({ baseUrl, store, binding });
+        }
+        const status = await collectTelemetryStatus(store, undefined, verbose);
+        if (json) {
+            printJsonSuccess(`telemetry ${action}`, { scope: "device", bindingId: null, ...status });
+            return;
+        }
+        const shipping = bindings.filter((b) => b.telemetryEnabled).length;
+        p.intro(`nustack telemetry ${action}`);
+        p.log.success(`Reconciled ${shipping} of ${bindings.length} folder${bindings.length === 1 ? "" : "s"}; install state ${status.filebeatState}.`);
+        p.outro(action === "reinstall" ? "Reinstalled." : "Enabled.");
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/commands/toolkit.js

@@ -0,0 +1,167 @@
+import * as p from "@clack/prompts";
+import { resolveNuStackUrl } from "../lib/nustack_client.js";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { resolveWorkspaceId } from "../lib/workspace_context.js";
+import { isInteractive } from "../lib/interactive.js";
+import { openLocalStore } from "../lib/local_store/database.js";
+import { getBindingByRepositoryRoot } from "../lib/local_store/bindings.js";
+import { resolveRepository } from "../lib/git-sync/core/repository.js";
+import { readWorkspaceManifests, diagnoseManifests } from "../lib/onboarding/manifest_writer.js";
+import { fetchToolkitProfile, ToolkitProfileUnavailableError } from "../lib/etna/profile.js";
+import { buildReconcilePlan, applyReconcile, toolkitCompatibility } from "../lib/etna/reconcile.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+function emitFail(command, json, code, message) {
+    if (json)
+        printJsonError(command, { code, message });
+    else {
+        console.error(message);
+        process.exitCode = 1;
+    }
+}
+async function resolveContext(command, json, options, globals) {
+    let root;
+    try {
+        root = resolveRepository(process.cwd()).repositoryRoot;
+    }
+    catch {
+        emitFail(command, json, "NOT_A_REPOSITORY", "Run `nustack toolkit` inside a bound Git repository.");
+        return null;
+    }
+    const baseUrl = resolveNuStackUrl(globals);
+    const workspace = await resolveWorkspaceId(root, options);
+    if (!workspace.ok) {
+        emitFail(command, json, "WORKSPACE_CONTEXT_MISSING", workspace.message);
+        return null;
+    }
+    const deviceAuth = await ensureAuthWithRecovery(baseUrl, json);
+    if (!deviceAuth) {
+        const failure = lastAuthFailure();
+        emitFail(command, json, failure.code, failure.message);
+        return null;
+    }
+    return { baseUrl, accessToken: deviceAuth.accessToken, workspaceId: workspace.workspaceId, root };
+}
+export async function runToolkitStatus(options, globals) {
+    const json = options.json === true;
+    const ctx = await resolveContext("toolkit status", json, options, globals);
+    if (!ctx)
+        return;
+    let cloud;
+    try {
+        cloud = await fetchToolkitProfile(ctx.baseUrl, ctx.accessToken, ctx.workspaceId);
+    }
+    catch (error) {
+        if (error instanceof ToolkitProfileUnavailableError) {
+            emitFail("toolkit status", json, "HARNESS_PROFILE_UNAVAILABLE", error.message);
+            return;
+        }
+        throw error;
+    }
+    const manifests = await readWorkspaceManifests(ctx.root);
+    const diagnosis = diagnoseManifests({ name: cloud.name, version: cloud.version }, manifests.workspaceManifest?.toolkit ?? null, manifests.serviceToolkit);
+    const binding = await withStore((store) => getBindingByRepositoryRoot(store, ctx.root));
+    const compatibility = toolkitCompatibility(binding ?? { etnaProfileJson: null }, cloud);
+    if (json) {
+        printJsonSuccess("toolkit status", {
+            workspaceId: ctx.workspaceId,
+            cloud,
+            workspaceJson: manifests.workspaceManifest?.toolkit ?? null,
+            serviceJson: manifests.serviceToolkit,
+            diagnosis,
+            compatibility,
+        });
+        return;
+    }
+    console.log(`Toolkit for Workspace ${ctx.workspaceId}`);
+    console.log(`  cloud pin:          ${cloud.name}@${cloud.version} (renderer ${cloud.rendererVersion}, placement ${cloud.placementMapVersion})`);
+    console.log(`  .nustack/app.json:   ${fmtToolkit(manifests.workspaceManifest?.toolkit)}`);
+    console.log(`  nustack.service.json:${fmtToolkit(manifests.serviceToolkit)}`);
+    console.log(`  diagnosis:          ${diagnosis}`);
+    console.log(`  write gate:         ${compatibility.blocksWrites ? `BLOCKED — ${compatibility.reason}` : "clear (projection and sync writes allowed)"}`);
+    if (diagnosis !== "aligned" && diagnosis !== "missing") {
+        console.log("  Repair with `nustack toolkit reconcile`.");
+    }
+}
+export async function runToolkitReconcile(options, globals) {
+    const json = options.json === true;
+    const ctx = await resolveContext("toolkit reconcile", json, options, globals);
+    if (!ctx)
+        return;
+    let cloud;
+    try {
+        cloud = await fetchToolkitProfile(ctx.baseUrl, ctx.accessToken, ctx.workspaceId);
+    }
+    catch (error) {
+        if (error instanceof ToolkitProfileUnavailableError) {
+            emitFail("toolkit reconcile", json, "HARNESS_PROFILE_UNAVAILABLE", error.message);
+            return;
+        }
+        throw error;
+    }
+    const binding = await withStore((store) => getBindingByRepositoryRoot(store, ctx.root));
+    const manifests = await readWorkspaceManifests(ctx.root);
+    const identity = manifests.workspaceManifest
+        ? { workspaceId: manifests.workspaceManifest.workspaceId, organizationId: manifests.workspaceManifest.organizationId }
+        : manifests.serviceWorkspaceBinding;
+    if (!identity) {
+        emitFail("toolkit reconcile", json, "WORKSPACE_CONTEXT_MISSING", "No `.nustack/app.json` binding to reconcile — attach the repository first.");
+        return;
+    }
+    const plan = await buildReconcilePlan(ctx.root, binding ?? { etnaProfileJson: null }, cloud);
+    if (plan.noOp) {
+        if (json)
+            printJsonSuccess("toolkit reconcile", { applied: false, plan });
+        else
+            console.log("Toolkit already aligned with the cloud pin — nothing to reconcile.");
+        return;
+    }
+    const confirmed = options.yes === true ? true : json ? false : await promptApply(plan);
+    if (!confirmed) {
+        if (json)
+            printJsonSuccess("toolkit reconcile", { applied: false, plan, note: "preview only — pass --yes to apply" });
+        else
+            console.log("Preview only — re-run with --yes to apply.");
+        return;
+    }
+    await withStoreVoid(async (store) => {
+        await applyReconcile(store, binding?.id ?? "", ctx.root, identity, cloud);
+    });
+    if (json)
+        printJsonSuccess("toolkit reconcile", { applied: true, plan });
+    else
+        console.log(`Reconciled ${plan.changes.length} field(s) to the cloud pin ${cloud.name}@${cloud.version}.`);
+}
+async function promptApply(plan) {
+    if (!isInteractive())
+        return false;
+    p.intro("nustack toolkit reconcile");
+    p.note(plan.changes.map((c) => `${c.file} ${c.field}: ${c.from || "∅"} → ${c.to}`).join("\n"), "Repair preview");
+    const answer = await p.confirm({ message: "Apply this reconcile? No User content is touched." });
+    return !p.isCancel(answer) && answer === true;
+}
+function fmtToolkit(h) {
+    return h ? `${h.name}@${h.version}` : "(absent)";
+}
+async function withStore(fn) {
+    try {
+        const store = await openLocalStore();
+        try {
+            return fn(store);
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+async function withStoreVoid(fn) {
+    const store = await openLocalStore();
+    try {
+        await fn(store);
+    }
+    finally {
+        store.close();
+    }
+}