@nurix/nustack 0.10.0-dev.10

package/dist/lib/telemetry/config_renderer.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { assertSafeApiKey, assertSafeElkUrl, assertSafeIndexName } from "../guards.js";
+import { claudeProjectDir, codexSessionsDir } from "./provider_paths.js";
+import { REDACTION_POLICY_VERSION, SLASH_COMMAND_CLOSE, SLASH_COMMAND_OPEN, providerDropFields, } from "./redaction_policy.js";
+export const TELEMETRY_CONFIG_VERSION = 2;
+export const ENVELOPE_SCHEMA_VERSION = 2;
+export function renderTemplate(template, vars) {
+    return template.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_match, name) => {
+        const value = vars[name];
+        if (value === undefined)
+            throw new Error(`template variable not provided: ${name}`);
+        assertNoControlChars(name, value);
+        return value;
+    });
+}
+function assertNoControlChars(label, value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f) {
+            throw new Error(`template variable ${label} contains control characters`);
+        }
+    }
+}
+export function yamlScalar(value) {
+    assertNoControlChars("scalar", value);
+    return JSON.stringify(value);
+}
+export function claudeFilestreamId(repoRoot) {
+    const slug = repoRoot.replace(/[^a-zA-Z0-9]/g, "-").replace(/^-+/, "").toLowerCase();
+    return `claude-${slug}`;
+}
+export function desiredConfigHash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+const CENTRAL_TEMPLATE = `# Managed by the nustack CLI — do not edit by hand.
+filebeat.config.inputs:
+  enabled: true
+  path: \${path.config}/inputs.d/*.yml
+  reload.enabled: true
+  reload.period: 30s
+
+# Set @timestamp to the session/prompt time (each line's own \`timestamp\` field).
+processors:
+  - timestamp:
+      field: timestamp
+      layouts:
+        - '2006-01-02T15:04:05.999999999Z07:00'
+        - '2006-01-02T15:04:05Z07:00'
+      ignore_missing: true
+      ignore_failure: true
+
+queue.mem:
+  events: 4096
+  flush.min_events: 512
+  flush.timeout: 5s
+
+output.elasticsearch:
+  hosts: [{{elk_url}}]
+  api_key: {{api_key}}
+  index: {{index}}
+  ssl.verification_mode: full
+
+setup.ilm.enabled: false
+setup.template.name: {{index}}
+setup.template.pattern: {{index_pattern}}
+
+logging.level: warning
+`;
+export function renderCentralConfig(opts) {
+    const elkUrl = assertSafeElkUrl(opts.elkUrl);
+    const apiKey = assertSafeApiKey(opts.apiKey);
+    const index = assertSafeIndexName(opts.index);
+    return renderTemplate(CENTRAL_TEMPLATE, {
+        elk_url: yamlScalar(elkUrl),
+        api_key: yamlScalar(apiKey),
+        index: yamlScalar(index),
+        index_pattern: yamlScalar(`${index}-*`),
+    });
+}
+const BINDING_TEMPLATE = `# Managed by the nustack CLI — binding: {{binding_id_raw}}
+- type: filestream
+  id: {{filestream_id}}
+  paths:
+    - {{claude_glob}}
+  parsers:
+    - ndjson:
+        target: ""
+        overwrite_keys: true
+        add_error_key: true
+  fields_under_root: true
+  fields:
+    nustack:
+      schema_version: {{schema_version}}
+      organization_id: {{organization_id}}
+      workspace_id: {{workspace_id}}
+      binding_id: {{binding_id}}
+      device_id: {{device_id}}
+      user_id: {{user_id}}
+      provider: {{provider}}
+      redaction_policy_version: {{redaction_policy_version}}
+      redaction_applied: true
+  processors:
+    - dissect:
+        tokenizer: "%{}{{slash_open}}%{slashCommand}{{slash_close}}%{}"
+        field: "message.content"
+        target_prefix: ""
+        ignore_failure: true
+    - drop_fields:
+        fields: [{{drop_fields}}]
+        ignore_missing: true
+`;
+export function renderBindingInput(binding) {
+    return renderTemplate(BINDING_TEMPLATE, {
+        binding_id_raw: binding.bindingId,
+        filestream_id: claudeFilestreamId(binding.repoRoot),
+        claude_glob: yamlScalar(`${claudeProjectDir(binding.repoRoot)}/**/*.jsonl`),
+        schema_version: String(ENVELOPE_SCHEMA_VERSION),
+        organization_id: yamlScalar(binding.organizationId),
+        workspace_id: yamlScalar(binding.workspaceId),
+        binding_id: yamlScalar(binding.bindingId),
+        device_id: yamlScalar(binding.deviceRef),
+        user_id: yamlScalar(binding.userId),
+        provider: yamlScalar("claude_code"),
+        redaction_policy_version: String(REDACTION_POLICY_VERSION),
+        slash_open: SLASH_COMMAND_OPEN,
+        slash_close: SLASH_COMMAND_CLOSE,
+        drop_fields: providerDropFields("claude_code").join(", "),
+    });
+}
+export function renderCodexSharedInput(bindings) {
+    if (bindings.length === 0) {
+        throw new Error("renderCodexSharedInput requires at least one binding");
+    }
+    const sorted = [...bindings].sort((a, b) => (a.bindingId < b.bindingId ? -1 : a.bindingId > b.bindingId ? 1 : 0));
+    const device = sorted[0];
+    const conditionals = sorted
+        .map((binding) => `    - if:
+        equals:
+          cwd: ${yamlScalar(binding.repoRoot)}
+      then:
+        - add_fields:
+            target: nustack
+            fields:
+              organization_id: ${yamlScalar(binding.organizationId)}
+              workspace_id: ${yamlScalar(binding.workspaceId)}
+              binding_id: ${yamlScalar(binding.bindingId)}`)
+        .join("\n");
+    const dropList = ["cwd", ...providerDropFields("codex")].join(", ");
+    return `# Managed by the nustack CLI — codex shared input (all bindings)
+- type: filestream
+  id: codex-shared
+  paths:
+    - ${yamlScalar(`${codexSessionsDir()}/**/*.jsonl`)}
+  parsers:
+    - ndjson:
+        target: ""
+        overwrite_keys: true
+        add_error_key: true
+  fields_under_root: true
+  processors:
+    - add_fields:
+        target: nustack
+        fields:
+          schema_version: ${ENVELOPE_SCHEMA_VERSION}
+          device_id: ${yamlScalar(device.deviceRef)}
+          user_id: ${yamlScalar(device.userId)}
+          provider: ${yamlScalar("codex")}
+          redaction_policy_version: ${REDACTION_POLICY_VERSION}
+          redaction_applied: true
+${conditionals}
+    - drop_fields:
+        fields: [${dropList}]
+        ignore_missing: true
+`;
+}

package/dist/lib/telemetry/health_report.js

@@ -0,0 +1,173 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { listActiveBindings } from "../local_store/bindings.js";
+import { readDeviceState } from "../local_store/device_state.js";
+import { listActivityBindings, readFilebeatState, upsertFilebeatState, } from "../local_store/filebeat_state.js";
+import { desiredFilebeatVersion, filebeatBinPath, filebeatDir, inputsDir, observedFilebeatVersion, probeServiceRegistered, } from "../filebeat_installer.js";
+import { REDACTION_POLICY_VERSION, } from "./redaction_policy.js";
+import { TELEMETRY_CONFIG_VERSION, desiredConfigHash, renderBindingInput, } from "./config_renderer.js";
+import { discoverProviderBindings } from "./provider_paths.js";
+import { readObservedConfigBytes } from "./reload.js";
+export function defaultProbes() {
+    return {
+        binaryPresent: () => existsSync(filebeatBinPath()),
+        binaryPath: () => (existsSync(filebeatBinPath()) ? filebeatBinPath() : null),
+        desiredVersion: () => desiredFilebeatVersion(),
+        observedVersion: () => observedFilebeatVersion(),
+        serviceRegistered: () => probeServiceRegistered(),
+        observedConfigBytes: () => readObservedConfigBytes(filebeatDir()),
+        bindingInputHash: async (bindingId) => {
+            const file = path.join(inputsDir(), `${bindingId}.yml`);
+            return existsSync(file) ? desiredConfigHash(await readFile(file, "utf8")) : null;
+        },
+    };
+}
+export async function collectTelemetryStatus(store, probes = defaultProbes(), options = {}) {
+    const fbState = readFilebeatState(store);
+    const device = readDeviceState(store);
+    const telemetryEnabled = fbState ? fbState.telemetryEnabled : true;
+    const binaryPresent = probes.binaryPresent();
+    const serviceRegistered = probes.serviceRegistered();
+    const deviceRef = device?.deviceRef ?? "";
+    const userId = device?.activeUserId ?? "";
+    const folders = [];
+    const activity = [];
+    for (const binding of listActiveBindings(store)) {
+        const rendered = renderBindingInput({
+            bindingId: binding.id,
+            repoRoot: binding.repositoryRoot,
+            organizationId: binding.organizationId,
+            workspaceId: binding.workspaceId,
+            deviceRef,
+            userId,
+        });
+        const desired = desiredConfigHash(rendered);
+        const observed = await probes.bindingInputHash(binding.id);
+        folders.push({
+            bindingId: binding.id,
+            label: binding.repositoryRoot.split("/").filter(Boolean).pop() ?? binding.id,
+            repositoryRoot: options.localVerbose === true ? binding.repositoryRoot : null,
+            enabled: binding.telemetryEnabled,
+            pathFingerprint: binding.repositoryFingerprint,
+            desiredConfigVersion: TELEMETRY_CONFIG_VERSION,
+            desiredConfigHash: desired,
+            observedConfigHash: observed,
+            redactionPolicyVersion: REDACTION_POLICY_VERSION,
+            state: folderState({
+                telemetryEnabled,
+                folderEnabled: binding.telemetryEnabled,
+                binaryPresent,
+                desired,
+                observed,
+            }),
+        });
+        const rows = listActivityBindings(store, binding.id);
+        for (const discovered of discoverProviderBindings(binding.repositoryRoot)) {
+            const row = rows.find((r) => r.provider === discovered.provider);
+            const baseState = row ? row.state : discovered.state;
+            activity.push({
+                bindingId: binding.id,
+                provider: discovered.provider,
+                providerProjectKey: discovered.providerProjectKey,
+                pathFingerprint: discovered.pathFingerprint,
+                discoveryMethod: discovered.discoveryMethod,
+                state: !telemetryEnabled || !binding.telemetryEnabled ? "disabled" : baseState,
+                lastObservedAtMs: row?.lastObservedAtMs ?? null,
+            });
+        }
+    }
+    const observedConfigHash = binaryPresent
+        ? desiredConfigHash(await probes.observedConfigBytes())
+        : null;
+    return {
+        telemetryEnabled,
+        optedOutByEnv: process.env.NUSTACK_TELEMETRY === "off",
+        binaryPresent,
+        binaryPath: probes.binaryPath(),
+        desiredVersion: probes.desiredVersion(),
+        observedVersion: probes.observedVersion(),
+        serviceRegistered,
+        desiredConfigVersion: TELEMETRY_CONFIG_VERSION,
+        observedConfigHash,
+        filebeatState: installState({
+            binaryPresent,
+            serviceRegistered,
+            lastErrorCode: fbState?.lastErrorCode ?? null,
+        }),
+        lastErrorCode: fbState?.lastErrorCode ?? null,
+        lastHealthAtMs: fbState?.lastHealthAtMs ?? null,
+        folders,
+        activity,
+    };
+}
+function folderState(args) {
+    if (!args.telemetryEnabled || !args.folderEnabled)
+        return "disabled";
+    if (args.observed === null)
+        return "pending";
+    if (args.observed === args.desired && args.binaryPresent)
+        return "healthy";
+    return "degraded";
+}
+function installState(args) {
+    if (!args.binaryPresent)
+        return "not_installed";
+    if (args.lastErrorCode)
+        return "degraded";
+    return args.serviceRegistered ? "healthy" : "degraded";
+}
+export function buildTelemetryHealthReport(status) {
+    return {
+        filebeat: {
+            desiredVersion: status.desiredVersion,
+            observedVersion: status.observedVersion,
+            desiredConfigVersion: status.desiredConfigVersion,
+            observedConfigHash: status.observedConfigHash,
+            state: status.filebeatState,
+            errorCode: status.lastErrorCode,
+        },
+        folders: status.folders.map((folder) => ({
+            bindingId: folder.bindingId,
+            enabled: folder.enabled,
+            pathFingerprint: folder.pathFingerprint,
+            desiredConfigVersion: folder.desiredConfigVersion,
+            desiredConfigHash: folder.desiredConfigHash,
+            observedConfigHash: folder.observedConfigHash,
+            redactionPolicyVersion: folder.redactionPolicyVersion,
+            state: folder.state,
+        })),
+        activity: status.activity.map((entry) => ({
+            bindingId: entry.bindingId,
+            provider: entry.provider,
+            providerProjectKey: entry.providerProjectKey,
+            pathFingerprint: entry.pathFingerprint,
+            discoveryMethod: entry.discoveryMethod,
+            state: entry.state,
+            lastObservedAt: entry.lastObservedAtMs === null ? null : new Date(entry.lastObservedAtMs).toISOString(),
+        })),
+    };
+}
+const HEALTH_REPORT_TIMEOUT_MS = 10_000;
+export async function reportTelemetryHealth(opts) {
+    try {
+        const deviceRef = opts.deviceRef ?? readDeviceState(opts.store)?.deviceRef ?? null;
+        if (!deviceRef || !opts.accessToken)
+            return;
+        const report = opts.report ??
+            buildTelemetryHealthReport(await collectTelemetryStatus(opts.store, opts.probes));
+        const fetchImpl = opts.fetchImpl ?? fetch;
+        await fetchImpl(`${opts.baseUrl}/api/v2/devices/${encodeURIComponent(deviceRef)}/telemetry-health`, {
+            method: "PUT",
+            headers: {
+                Authorization: `Bearer ${opts.accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(report),
+            signal: AbortSignal.timeout(HEALTH_REPORT_TIMEOUT_MS),
+        });
+        upsertFilebeatState(opts.store, { lastHealthAtMs: Date.now() });
+    }
+    catch {
+    }
+}

package/dist/lib/telemetry/provider_paths.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function encodeClaudeProjectKey(repoRoot) {
+    return repoRoot.replace(/[^a-zA-Z0-9]/g, "-");
+}
+export function claudeProjectDir(repoRoot) {
+    return path.join(os.homedir(), ".claude", "projects", encodeClaudeProjectKey(repoRoot));
+}
+export function codexSessionsDir() {
+    return path.join(os.homedir(), ".codex", "sessions");
+}
+function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function discoverProviderBindings(repoRoot) {
+    const claudeDir = claudeProjectDir(repoRoot);
+    const codexDir = codexSessionsDir();
+    return [
+        {
+            provider: "claude_code",
+            providerProjectKey: encodeClaudeProjectKey(repoRoot),
+            absolutePath: claudeDir,
+            pathFingerprint: sha256Hex(claudeDir),
+            discoveryMethod: "claude_projects_dir",
+            state: existsSync(claudeDir) ? "active" : "missing",
+        },
+        {
+            provider: "codex",
+            providerProjectKey: sha256Hex(repoRoot),
+            absolutePath: codexDir,
+            pathFingerprint: sha256Hex(`codex:${repoRoot}`),
+            discoveryMethod: "codex_sessions_cwd",
+            state: existsSync(codexDir) ? "active" : "missing",
+        },
+    ];
+}

package/dist/lib/telemetry/redaction_policy.js

@@ -0,0 +1,90 @@
+export const REDACTION_POLICY_VERSION = 1;
+const DROP_FIELDS = {
+    claude_code: ["message.content", "message.thinking", "toolUseResult", "summary", "attachment"],
+    codex: [
+        "payload.content",
+        "payload.arguments",
+        "payload.output",
+        "payload.instructions",
+        "payload.environment",
+    ],
+};
+const KEEP_FIELDS = {
+    claude_code: [
+        "sessionId",
+        "type",
+        "subtype",
+        "timestamp",
+        "uuid",
+        "parentUuid",
+        "gitBranch",
+        "userType",
+        "version",
+        "requestId",
+        "isSidechain",
+        "entrypoint",
+        "promptSource",
+        "mode",
+        "permissionMode",
+        "durationMs",
+        "messageCount",
+        "slashCommand",
+        "skillTrigger",
+        "message.role",
+        "message.model",
+        "message.stop_reason",
+        "message.usage",
+    ],
+    codex: ["id", "timestamp", "type", "payload.type", "payload.model", "payload.usage", "cwd"],
+};
+export function providerDropFields(provider) {
+    return DROP_FIELDS[provider];
+}
+export function providerKeepFields(provider) {
+    return KEEP_FIELDS[provider];
+}
+export const SLASH_COMMAND_OPEN = "<command-name>";
+export const SLASH_COMMAND_CLOSE = "</command-name>";
+export function extractSlashCommand(content) {
+    if (typeof content !== "string")
+        return null;
+    const open = content.indexOf(SLASH_COMMAND_OPEN);
+    if (open === -1)
+        return null;
+    const start = open + SLASH_COMMAND_OPEN.length;
+    const close = content.indexOf(SLASH_COMMAND_CLOSE, start);
+    if (close === -1)
+        return null;
+    return content.slice(start, close);
+}
+function deleteDottedPath(target, path) {
+    const segments = path.split(".");
+    let node = target;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const next = node[segments[i]];
+        if (next === null || typeof next !== "object" || Array.isArray(next))
+            return;
+        node = next;
+    }
+    delete node[segments[segments.length - 1]];
+}
+export function applyRedaction(event, provider) {
+    const redacted = structuredClone(event);
+    if (provider === "claude_code") {
+        const message = redacted.message;
+        if (message !== null && typeof message === "object" && !Array.isArray(message)) {
+            const command = extractSlashCommand(message.content);
+            if (command !== null)
+                redacted.slashCommand = command;
+        }
+    }
+    for (const field of providerDropFields(provider)) {
+        deleteDottedPath(redacted, field);
+    }
+    redacted.nustack = {
+        ...(typeof redacted.nustack === "object" && redacted.nustack !== null ? redacted.nustack : {}),
+        redaction_policy_version: REDACTION_POLICY_VERSION,
+        redaction_applied: true,
+    };
+    return redacted;
+}

package/dist/lib/telemetry/reload.js

@@ -0,0 +1,84 @@
+import { existsSync } from "node:fs";
+import { copyFile, readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { mkdirSecure, writeFileSecure } from "../secure_file.js";
+const MAIN_CONFIG = "filebeat.yml";
+const INPUTS_DIR = "inputs.d";
+async function liveConfigFiles(configDir) {
+    const files = [];
+    if (existsSync(path.join(configDir, MAIN_CONFIG)))
+        files.push(MAIN_CONFIG);
+    const inputsDir = path.join(configDir, INPUTS_DIR);
+    if (existsSync(inputsDir)) {
+        for (const name of await readdir(inputsDir)) {
+            if (name.endsWith(".yml"))
+                files.push(`${INPUTS_DIR}/${name}`);
+        }
+    }
+    return files;
+}
+async function copyRelative(fromRoot, toRoot, relativePath) {
+    const dest = path.join(toRoot, relativePath);
+    await mkdirSecure(path.dirname(dest));
+    await copyFile(path.join(fromRoot, relativePath), dest);
+}
+async function mirrorSet(configDir, targetDir) {
+    await rm(targetDir, { recursive: true, force: true });
+    await mkdirSecure(targetDir);
+    for (const relativePath of await liveConfigFiles(configDir)) {
+        await copyRelative(configDir, targetDir, relativePath);
+    }
+}
+async function writeRendered(root, file) {
+    const dest = path.join(root, file.relativePath);
+    await mkdirSecure(path.dirname(dest));
+    await writeFileSecure(dest, file.contents);
+}
+async function restoreKnownGood(configDir, knownGoodDir, files) {
+    for (const file of files) {
+        const snapshot = path.join(knownGoodDir, file.relativePath);
+        const live = path.join(configDir, file.relativePath);
+        if (existsSync(snapshot)) {
+            await copyFile(snapshot, live);
+        }
+        else {
+            await rm(live, { force: true });
+        }
+    }
+}
+export async function applyConfigChange(opts) {
+    const { configDir, testConfig, restartService } = opts.context;
+    const stagedDir = path.join(configDir, "staged");
+    const knownGoodDir = path.join(configDir, "known_good");
+    await mirrorSet(configDir, stagedDir);
+    for (const file of opts.files)
+        await writeRendered(stagedDir, file);
+    const validation = testConfig({ configDir: stagedDir, mainConfigPath: path.join(stagedDir, MAIN_CONFIG) });
+    if (!validation.ok) {
+        await rm(stagedDir, { recursive: true, force: true });
+        return { ok: false, errorCode: "config_invalid", rolledBack: false };
+    }
+    await mirrorSet(configDir, knownGoodDir);
+    for (const file of opts.files)
+        await writeRendered(configDir, file);
+    await rm(stagedDir, { recursive: true, force: true });
+    if (opts.scope === "central") {
+        const restart = await restartService();
+        if (!restart.ok) {
+            await restoreKnownGood(configDir, knownGoodDir, opts.files);
+            return { ok: false, errorCode: "restart_failed", rolledBack: true };
+        }
+    }
+    return { ok: true };
+}
+export async function removeInputFile(configDir, relativePath) {
+    await rm(path.join(configDir, relativePath), { force: true });
+}
+export async function readObservedConfigBytes(configDir) {
+    const parts = [];
+    for (const relativePath of [MAIN_CONFIG, `${INPUTS_DIR}/codex-shared.yml`]) {
+        const file = path.join(configDir, relativePath);
+        parts.push(existsSync(file) ? await readFile(file, "utf8") : "");
+    }
+    return parts.join("\n");
+}

package/dist/lib/workspace_context.js

@@ -0,0 +1,121 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readManagedValues } from "./env_file.js";
+import { manifestPath } from "./manifest.js";
+import { assertSafeOpaqueId } from "./guards.js";
+const NO_WORKSPACE_MESSAGE = "No Workspace id — run inside a bound repository (`.nustack/workspace.json`), pass `--workspace <id>`, add an `nustackWorkspace.workspaceId` to nustack.service.json, or set NUSTACK_WORKSPACE_ID in the managed .env block.";
+export function workspaceJsonPath(cwd) {
+    return path.join(cwd, ".nustack", "workspace.json");
+}
+export function legacyAppJsonPath(cwd) {
+    return path.join(cwd, ".nustack", "app.json");
+}
+export async function readBindingMarker(cwd) {
+    const v2Path = workspaceJsonPath(cwd);
+    if (existsSync(v2Path)) {
+        try {
+            const marker = JSON.parse(await readFile(v2Path, "utf8"));
+            if (marker.schemaVersion === 2) {
+                const workspaceId = trimmed(marker.workspaceId);
+                if (workspaceId) {
+                    return { workspaceId, organizationId: trimmed(marker.organizationId), version: 2 };
+                }
+            }
+        }
+        catch {
+        }
+    }
+    const v1Path = legacyAppJsonPath(cwd);
+    if (!existsSync(v1Path))
+        return null;
+    try {
+        const marker = JSON.parse(await readFile(v1Path, "utf8"));
+        if (marker.schemaVersion !== undefined && marker.schemaVersion !== 1)
+            return null;
+        const workspaceId = trimmed(marker.appId);
+        if (!workspaceId)
+            return null;
+        return { workspaceId, organizationId: trimmed(marker.workspaceId), version: 1 };
+    }
+    catch {
+        return null;
+    }
+}
+function trimmed(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+export async function readWorkspaceJsonWorkspaceId(cwd) {
+    return (await readBindingMarker(cwd))?.workspaceId ?? null;
+}
+async function readManifestWorkspaceId(cwd) {
+    const filePath = manifestPath(cwd);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const manifest = JSON.parse(await readFile(filePath, "utf8"));
+        return trimmed(manifest.nustackWorkspace?.workspaceId) ?? trimmed(manifest.nustackApp?.appId);
+    }
+    catch {
+        return null;
+    }
+}
+async function readEnvWorkspaceId(cwd) {
+    const managed = await readManagedValues(path.join(cwd, ".env"));
+    const workspaceId = managed.NUSTACK_WORKSPACE_ID?.trim();
+    return workspaceId ? workspaceId : null;
+}
+export async function resolveWorkspaceId(cwd, options) {
+    const flag = options.workspace?.trim();
+    const workspaceJsonId = await readWorkspaceJsonWorkspaceId(cwd);
+    const candidate = workspaceJsonId
+        ? { value: workspaceJsonId, source: "workspace_json" }
+        : flag
+            ? { value: flag, source: "flag" }
+            : (await readManifestWorkspaceId(cwd).then((id) => (id ? { value: id, source: "manifest" } : null))) ??
+                (await readEnvWorkspaceId(cwd).then((id) => (id ? { value: id, source: "env" } : null)));
+    if (!candidate)
+        return { ok: false, message: NO_WORKSPACE_MESSAGE };
+    try {
+        return { ok: true, workspaceId: assertSafeOpaqueId("The Workspace id", candidate.value), source: candidate.source };
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+}
+const NO_ORGANIZATION_MESSAGE = "No Organization context — pass `--organization <id-or-slug>`, run `nustack organization use <id>`, or create one with `nustack organization create <name>`.";
+export function resolveOrganizationId(options, activeOrganizationId, memberships) {
+    const flag = options.organization?.trim();
+    if (flag) {
+        if (memberships && memberships.length > 0) {
+            const match = memberships.find((m) => m.id === flag || m.slug === flag);
+            if (!match)
+                return { ok: false, message: `No Organization "${flag}" among your memberships.` };
+            return finalizeOrganization(match.id, "flag");
+        }
+        return finalizeOrganization(flag, "flag");
+    }
+    if (activeOrganizationId) {
+        if (!memberships || memberships.length === 0)
+            return finalizeOrganization(activeOrganizationId, "active");
+        if (memberships.some((m) => m.id === activeOrganizationId))
+            return finalizeOrganization(activeOrganizationId, "active");
+        if (memberships.length === 1)
+            return finalizeOrganization(memberships[0].id, "single_membership");
+        return {
+            ok: false,
+            message: "Your active Organization is no longer among your memberships — run `nustack organization use <id-or-slug>` to pick a current one.",
+        };
+    }
+    if (memberships && memberships.length === 1)
+        return finalizeOrganization(memberships[0].id, "single_membership");
+    return { ok: false, message: NO_ORGANIZATION_MESSAGE };
+}
+function finalizeOrganization(value, source) {
+    try {
+        return { ok: true, organizationId: assertSafeOpaqueId("The Organization id", value), source };
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+}