@nurix/nustack 0.10.0-dev.10

package/README.md

@@ -0,0 +1,77 @@
+# `@nurix/nustack` — the `nustack` CLI
+
+The developer's terminal surface for NuStack (`apps.nustack.ai`). It signs a machine in once through browser-approved device trust, then works against the same organizations, Workspaces, and documents the web studio serves — list and create Workspaces, read their documents, publish to the marketplace, search the public catalog, and mirror the machine's telemetry state.
+
+Interactive UX is built on [`@clack/prompts`](https://github.com/bombshell-dev/clack).
+
+## Install
+
+Published to npm with **public access** — no npm account or token required to run it.
+
+```
+npx @nurix/nustack@latest --help      # one-shot, no auth
+npm install -g @nurix/nustack         # or install the `nustack` binary globally
+```
+
+The tarball ships no secrets. Authentication is the **device-trust flow**: `nustack login` registers this machine, you approve its code once in the browser (at `/device`, behind the studio's Google SSO), and the durable refresh material lands in your OS keychain — never in a file. Every authenticated command then rides a short-lived access token minted from it. Signing in on the CLI signs in the desktop workspace too: both clients share one keychain item and one `~/.nustack/device_id`.
+
+A dead credential is never a dead end: if the server refuses this device's sign-in (revoked, stale), the CLI clears the dead keychain item and drops you straight back into `nustack login` — you never edit a config file by hand.
+
+## Commands
+
+### Identity & devices
+
+```
+nustack login [--no-open]         # browser-approved device trust; re-login inside the
+                                 # 24h window needs no browser
+nustack logout                    # clears the shared keychain item (signs out CLI + desktop)
+nustack logout --revoke           # server-side self-revoke first, then the local clear
+nustack logout --forget-device    # also mints a fresh machine identity on next login
+nustack device list|status|revoke # this account's devices; revoke kills a machine's access
+```
+
+### Organizations & Workspaces
+
+```
+nustack organization list|create|use # memberships; `use` persists the active Organization,
+                                 # sent as the X-NuStack-Organization selection header
+nustack workspace list                  # the active Organization's Workspaces
+nustack workspace create [--prompt <text> | --name <name>]
+                                 # prompt-first: the first prompt creates the Workspace and
+                                 # streams the founding turn (SSE)
+nustack workspace attach [--workspace <id>]   # bind the current folder to a Workspace
+nustack workspace status|open           # cloud + local binding view; open in the browser
+nustack workspace publish|unpublish     # role-gated marketplace visibility
+```
+
+### Documents
+
+```
+nustack docs list [--workspace <id>]    # the Workspace's documents: slug, type, status, written/empty
+nustack docs show <slug-or-id>    # the document body inline (bounded)
+nustack docs status               # per-document workability and row versions
+```
+
+### Discovery & health
+
+```
+nustack list                      # one line per catalogue service
+nustack describe <svc> [--json]   # full catalogue entry
+nustack search <keywords...>      # public Workspace search (the headline)
+nustack search services <keywords...>
+                                 # service registry search (then `nustack add <name>`)
+nustack graph [--mermaid]         # consumes-graph from the catalogue
+nustack validate [manifest]       # nustack.service.json schema validation
+nustack doctor                    # connectivity + manifest conformance probes
+nustack open <svc>                # open a service's endpoint or repo
+nustack telemetry [status|enable|disable|reinstall]
+                                 # device-wide Filebeat telemetry control, mirrored server-side
+```
+
+`nustack workspace sync …` (the document-sync engine) is present but dormant: every call reaches the studio Worker's `/api/*` catch-all `404`, and its disposition — grow a surface, keep it against a rebuilt binding seam, or drop it — is an open product decision tracked in the backlog.
+
+## Conventions
+
+- **`--json` almost everywhere** — most commands emit the `nustackJsonVersion: 1` machine envelope with `--json`; errors are typed (`{ error: { code, message } }`), never a bare HTTP status. Four surfaces break the pattern by design — `describe`, `search`, `search services`, and the `workspace sync` family emit a bare array/object instead, because the desktop and the agents pin those exact shapes.
+- **Base URL** — `--nustack-url` flag → `NUSTACK_URL` env → the hosted default (`https://apps.nustack.ai`).
+- **Organization context** — `nustack organization use` persists the selection locally; commands send it as a header the server re-proves against your memberships on every request.

package/dist/commands/add.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { fetchCatalogue, resolveNuStackUrl } from "../lib/nustack_client.js";
+import { detectPackageManager, installPackage } from "../lib/package_manager.js";
+import { appendConsumesEdge, hasManifest, scaffoldManifest } from "../lib/manifest.js";
+import { confirmOrFallback, isInteractive } from "../lib/interactive.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+const COMMAND = "add";
+export async function runAdd(serviceArg, options) {
+    const cwd = process.cwd();
+    const baseUrl = resolveNuStackUrl(options);
+    const json = options.json === true;
+    if (!json)
+        p.intro(`nustack add${serviceArg ? ` ${serviceArg}` : ""}`);
+    if (json && !serviceArg) {
+        printJsonError(COMMAND, { code: "SERVICE_REQUIRED", message: "nustack add --json requires an explicit service argument." });
+        return;
+    }
+    const catalogue = await fetchCatalogue(baseUrl).catch(() => null);
+    const services = catalogue?.services ?? [];
+    const serviceName = serviceArg ?? (await pickService(services));
+    if (!serviceName) {
+        if (!json)
+            p.outro("Nothing was written.");
+        process.exitCode = 1;
+        return;
+    }
+    const catalogueEntry = services.find((service) => service.name === serviceName);
+    if (!catalogueEntry) {
+        return failAdd(json, "SERVICE_NOT_IN_CATALOGUE", `'${serviceName}' is not in the catalogue at ${baseUrl}.`, "Nothing was written. Run `nustack list` to see what is available.");
+    }
+    if (!json) {
+        const endpoint = catalogueEntry.http?.endpoints?.dev ?? catalogueEntry.http?.endpoints?.production;
+        p.log.info(`${catalogueEntry.name}${catalogueEntry.type ? ` · ${catalogueEntry.type}` : ""}` +
+            `${catalogueEntry.description ? `\n${catalogueEntry.description}` : ""}` +
+            `${endpoint ? `\nEndpoint: ${endpoint}` : ""}`);
+    }
+    const packageInstalled = await maybeInstallPackage(catalogueEntry, cwd, json, options.yes === true);
+    const consumesRecorded = await recordConsumesEdge(catalogueEntry, serviceName, cwd, json, options.yes === true);
+    if (json) {
+        printJsonSuccess(COMMAND, {
+            service: serviceName,
+            packageInstalled,
+            consumesRecorded,
+            credential: "deferred",
+        });
+        return;
+    }
+    p.log.info("No credential was issued — the credential plane is deferred by design, so `.env` was not touched.");
+    p.outro(`'${serviceName}' is recorded in this repo's manifest.`);
+}
+function failAdd(json, code, message, humanTail) {
+    if (json) {
+        printJsonError(COMMAND, { code, message });
+        return;
+    }
+    p.log.error(message);
+    p.outro(humanTail);
+    process.exitCode = 1;
+}
+async function pickService(services) {
+    if (services.length === 0) {
+        p.log.error("The catalogue is empty — pass the service name explicitly: nustack add <service>");
+        return undefined;
+    }
+    if (!isInteractive()) {
+        p.log.error("No terminal for the picker — pass the service name explicitly: nustack add <service>");
+        return undefined;
+    }
+    const selection = await p.select({
+        message: "Which service do you want to add?",
+        options: services.map((service) => ({
+            value: service.name,
+            label: service.name,
+            hint: [service.type ?? service.kind, service.status].filter(Boolean).join(" · "),
+        })),
+    });
+    if (p.isCancel(selection)) {
+        p.cancel("add cancelled.");
+        return undefined;
+    }
+    return selection;
+}
+async function maybeInstallPackage(entry, cwd, json, yes) {
+    const packageName = entry?.npm?.package;
+    if (!packageName)
+        return false;
+    const manager = detectPackageManager(cwd);
+    const shouldInstall = json ? yes : await confirmOrFallback(`Install ${packageName} with ${manager}?`, true);
+    if (!shouldInstall) {
+        if (!json)
+            p.log.info(`Skipped the package install — run: ${manager} add ${packageName}`);
+        return false;
+    }
+    try {
+        await installPackage(manager, packageName, cwd);
+        if (!json)
+            p.log.success(`Installed ${packageName}`);
+        return true;
+    }
+    catch (error) {
+        if (!json)
+            p.log.warn(`Package install failed (non-blocking): ${error instanceof Error ? error.message : error}`);
+        return false;
+    }
+}
+async function recordConsumesEdge(entry, serviceName, cwd, json, yes) {
+    if (!hasManifest(cwd)) {
+        const repoName = path.basename(cwd).toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+        const shouldScaffold = json
+            ? yes
+            : await confirmOrFallback(`No nustack.service.json — scaffold one for "${repoName}" to record the consumes edge?`, true);
+        if (!shouldScaffold) {
+            if (!json)
+                p.log.info("Skipped — the consumes edge (bill of materials) was not recorded.");
+            return false;
+        }
+        await scaffoldManifest(cwd, repoName);
+        if (!json)
+            p.log.success("Scaffolded nustack.service.json");
+    }
+    const via = entry?.npm?.package ? "npm" : "http";
+    const wasAppended = await appendConsumesEdge(cwd, { service: serviceName, via, endpoint: "dev" });
+    if (!json) {
+        p.log.success(wasAppended
+            ? `Recorded the consumes edge: ${serviceName} (via ${via})`
+            : `Consumes edge for ${serviceName} already declared`);
+    }
+    return true;
+}

package/dist/commands/agent.js

@@ -0,0 +1,100 @@
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { installSessionStartHook, removeSessionStartHook } from "../lib/agent/claudeHooks.js";
+const PROBE_TIMEOUT_MS = 1500;
+function desktopConfigDir() {
+    return (process.env.NUSTACK_DESKTOP_CONFIG_DIR ||
+        path.join(os.homedir(), "Library", "Application Support", "co.nurix.nustack"));
+}
+async function readServerRecord() {
+    const recordPath = path.join(desktopConfigDir(), "server.json");
+    try {
+        const parsed = JSON.parse(await readFile(recordPath, "utf8"));
+        if (typeof parsed.port !== "number" ||
+            typeof parsed.token !== "string" ||
+            typeof parsed.pid !== "number" ||
+            typeof parsed.startedAt !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function isRosterProject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.path === "string" &&
+        typeof value.label === "string");
+}
+async function probeProjects(record) {
+    try {
+        const response = await fetch(`http://127.0.0.1:${record.port}/api/projects`, {
+            headers: { Authorization: `Bearer ${record.token}` },
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        const projects = body.data?.projects;
+        return Array.isArray(projects) ? projects.filter(isRosterProject) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function describeContext(record, projects) {
+    const baseUrl = `http://127.0.0.1:${record.port}`;
+    const roster = projects.length
+        ? projects.map((project) => `- ${project.label} (${project.path})`).join("\n")
+        : "(no projects open)";
+    return [
+        `The NuStack desktop is running and reachable at ${baseUrl}.`,
+        `Bearer token for its API: ${record.token}`,
+        `Open projects (${projects.length}):`,
+        roster,
+        "This confirms NuStack answered just now — it says nothing about whether any project's code graph is current; ask `nustack graph` for that.",
+    ].join("\n");
+}
+export async function runAgentContext() {
+    const record = await readServerRecord();
+    if (!record)
+        return;
+    if (!isPidAlive(record.pid))
+        return;
+    const projects = await probeProjects(record);
+    if (projects === null)
+        return;
+    console.log(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: describeContext(record, projects),
+        },
+    }));
+}
+function claudeSettingsPath() {
+    return path.join(os.homedir(), ".claude", "settings.json");
+}
+export async function runAgentHookInstall() {
+    const { changed } = await installSessionStartHook(claudeSettingsPath());
+    console.log(changed
+        ? "Installed the SessionStart hook."
+        : "Installed the SessionStart hook (already installed — no change).");
+}
+export async function runAgentHookRemove() {
+    const { removed } = await removeSessionStartHook(claudeSettingsPath());
+    console.log(removed
+        ? "Removed the SessionStart hook."
+        : "Removed the SessionStart hook (already absent — no change).");
+}

package/dist/commands/bootstrap.js

@@ -0,0 +1,54 @@
+import * as p from "@clack/prompts";
+import { resolveNuStackUrl } from "../lib/nustack_client.js";
+import { isInteractive } from "../lib/interactive.js";
+import { ensureDeviceTelemetry } from "../lib/session_telemetry.js";
+import { openLocalStore } from "../lib/local_store/database.js";
+import { getBindingByRepositoryRoot } from "../lib/local_store/bindings.js";
+import { listApplicationsForBinding } from "../lib/local_store/handoff_applications.js";
+import { classifyFolder } from "../lib/onboarding/folder_state.js";
+import { ensureSignedIn, runOnboardingFlow } from "./init.js";
+export async function runBootstrap(options) {
+    const cwd = process.cwd();
+    const baseUrl = resolveNuStackUrl(options);
+    p.intro("nustack");
+    if (!isInteractive()) {
+        p.log.error("Bare `nustack` needs an interactive terminal (browser sign-in + prompts).");
+        p.outro("In scripted contexts run `nustack login --no-open`, then `nustack init`.");
+        process.exitCode = 1;
+        return;
+    }
+    const accessToken = await ensureSignedIn(baseUrl, cwd);
+    if (!accessToken)
+        return;
+    await ensureDeviceTelemetry({ baseUrl, log: (message) => p.log.info(message) });
+    const state = classifyFolder(cwd);
+    const bound = state.class === "git_worktree" && state.repository && state.git?.markerWorkspaceId
+        ? await printBoundStatus(state.repository.repositoryRoot)
+        : false;
+    if (bound)
+        return;
+    await runOnboardingFlow(baseUrl, accessToken, {});
+}
+async function printBoundStatus(root) {
+    const store = await openLocalStore();
+    try {
+        const binding = getBindingByRepositoryRoot(store, root);
+        if (!binding)
+            return false;
+        const pending = listApplicationsForBinding(store, binding.id, [
+            "received",
+            "evaluating",
+            "technical_wait",
+            "decision_required",
+            "approved",
+        ]);
+        p.log.success(`This repository is bound to Workspace ${binding.workspaceId} on branch ${binding.boundBranch}.`);
+        p.log.info(`Binding ${binding.id} · ${binding.status} · applied Workspace sequence ${binding.lastAppliedWorkspaceSequence}` +
+            (pending.length > 0 ? ` · ${pending.length} pending inbound` : ""));
+        p.outro("Up to date locally — `nustack workspace status` for the cloud view, `nustack workspace sync now` to reconcile.");
+        return true;
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/commands/describe.js

@@ -0,0 +1,34 @@
+import * as p from "@clack/prompts";
+import { fetchCatalogue, resolveNuStackUrl } from "../lib/nustack_client.js";
+export async function runDescribe(serviceName, options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
+    const entry = (catalogue.services ?? []).find((service) => service.name === serviceName);
+    if (!entry) {
+        p.log.error(`'${serviceName}' is not in the catalogue at ${baseUrl} (${catalogue.services?.length ?? 0} services listed).`);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(entry, null, 2));
+        return;
+    }
+    console.log(`${entry.name}  —  ${entry.description ?? "(no description)"}`);
+    console.log(`  kind/type:  ${entry.kind ?? "?"} / ${entry.type ?? "?"}`);
+    console.log(`  status:     ${entry.status ?? "?"}`);
+    console.log(`  environment: ${entry.environmentKey ?? "dev"}`);
+    if (entry.repository)
+        console.log(`  repository: ${entry.repository}`);
+    if (entry.npm?.package)
+        console.log(`  npm:        ${entry.npm.package}`);
+    for (const [envName, url] of Object.entries(entry.http?.endpoints ?? {})) {
+        console.log(`  endpoint:   ${envName} → ${url}`);
+    }
+    if (entry.env?.required?.length)
+        console.log(`  env (required): ${entry.env.required.join(", ")}`);
+    if (entry.env?.optional?.length)
+        console.log(`  env (optional): ${entry.env.optional.join(", ")}`);
+    for (const edge of entry.consumes ?? []) {
+        console.log(`  consumes:   ${edge.service}${edge.via ? ` (via ${edge.via})` : ""}`);
+    }
+}

package/dist/commands/device.js

@@ -0,0 +1,159 @@
+import * as p from "@clack/prompts";
+import { listDevices, resolveNuStackUrl } from "../lib/nustack_client.js";
+import { readGrant, revokeGrant } from "../lib/auth_grant.js";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { deleteDeviceCredential } from "../lib/device_keychain.js";
+import { isInteractive } from "../lib/interactive.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+function clientLabel(client) {
+    if (client === "nustack-cli")
+        return "NuStack CLI";
+    if (client === "nustack-desktop")
+        return "NuStack desktop";
+    if (client === "browser")
+        return "Browser";
+    return client;
+}
+function relativeTime(iso) {
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return iso;
+    const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+function formatRow(device) {
+    const name = device.machine ?? clientLabel(device.client);
+    const platform = device.platform && device.platform !== name ? device.platform : "";
+    return (`${device.deviceRef.padEnd(38)} ${name.padEnd(22)} ${clientLabel(device.client).padEnd(16)} ${platform.padEnd(10)} ` +
+        `active ${device.lastActiveAt ? relativeTime(device.lastActiveAt) : "never"}${device.isCurrent ? "  (this machine)" : ""}`);
+}
+function toView(device, currentDeviceRef) {
+    return {
+        id: device.id,
+        deviceRef: device.deviceRef,
+        client: device.clientName ?? "unknown",
+        machine: device.label ?? device.displayName ?? null,
+        platform: device.platform ?? null,
+        lastActiveAt: device.lastSeenAt ?? null,
+        isCurrent: device.deviceRef === currentDeviceRef,
+    };
+}
+function failSignedOut(command, json) {
+    const failure = lastAuthFailure();
+    if (json)
+        printJsonError(command, { code: failure.code, message: failure.message });
+    else {
+        p.log.error(failure.message);
+        process.exitCode = 1;
+    }
+}
+function fail(command, json, code, message) {
+    if (json)
+        printJsonError(command, { code, message });
+    else {
+        p.log.error(message);
+        process.exitCode = 1;
+    }
+}
+async function liveGrant(baseUrl, json) {
+    const auth = await ensureAuthWithRecovery(baseUrl, json);
+    if (!auth)
+        return null;
+    const grant = await readGrant();
+    return grant ? { grant, accessToken: auth.accessToken } : null;
+}
+export async function runDeviceList(options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const json = options.json === true;
+    const live = await liveGrant(baseUrl, json);
+    if (!live)
+        return failSignedOut("device list", json);
+    const devices = (await listDevices(baseUrl, live.accessToken)).map((row) => toView(row, live.grant.deviceId));
+    if (json) {
+        printJsonSuccess("device list", { devices });
+        return;
+    }
+    if (devices.length === 0) {
+        console.log("No devices signed in.");
+        return;
+    }
+    console.log(`${"DEVICE".padEnd(38)} ${"MACHINE".padEnd(22)} ${"CLIENT".padEnd(16)} ${"PLATFORM".padEnd(10)} LAST ACTIVE`);
+    for (const device of devices)
+        console.log(formatRow(device));
+}
+export async function runDeviceStatus(options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const json = options.json === true;
+    const live = await liveGrant(baseUrl, json);
+    if (!live)
+        return failSignedOut("device status", json);
+    const { grant, accessToken } = live;
+    const rows = await listDevices(baseUrl, accessToken);
+    const current = rows.map((row) => toView(row, grant.deviceId)).find((d) => d.isCurrent) ?? null;
+    if (json) {
+        printJsonSuccess("device status", {
+            deviceId: grant.deviceId,
+            email: grant.userEmail,
+            authBaseUrl: grant.authBaseUrl,
+            resources: grant.grantedResources,
+            keychainMaterial: true,
+            server: current,
+        });
+        return;
+    }
+    p.intro("nustack device status");
+    p.note([
+        `device id:        ${grant.deviceId}`,
+        `signed in as:     ${grant.userEmail || "—"}`,
+        `auth service:     ${grant.authBaseUrl}`,
+        `resources:        ${grant.grantedResources.join(", ") || "—"}`,
+        `keychain grant:   present`,
+        `server record:    ${current ? `${current.id} (${clientLabel(current.client)})` : "not found"}`,
+        `last active:      ${current?.lastActiveAt ?? "—"}`,
+    ].join("\n"), "This device");
+    p.outro(grant.userEmail || "signed in");
+}
+export async function runDeviceRevoke(deviceRefArg, options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const json = options.json === true;
+    const live = await liveGrant(baseUrl, json);
+    if (!live)
+        return failSignedOut("device revoke", json);
+    const { grant, accessToken } = live;
+    const views = (await listDevices(baseUrl, accessToken)).map((row) => toView(row, grant.deviceId));
+    const target = deviceRefArg ? views.find((view) => view.deviceRef === deviceRefArg || view.id === deviceRefArg) : (views.find((view) => view.isCurrent) ?? null);
+    if (deviceRefArg && !target)
+        return fail("device revoke", json, "DEVICE_NOT_FOUND", "No device with that id — pass one from `nustack device list`.");
+    if (target && !target.isCurrent) {
+        const label = target.machine ? `${clientLabel(target.client)} on ${target.machine}` : clientLabel(target.client);
+        return fail("device revoke", json, "NOT_THIS_MACHINE", `Only this machine's own access can be ended from here. Sign ${label} out from that machine, or revoke it from Profile › Devices.`);
+    }
+    if (options.yes !== true) {
+        if (json || !isInteractive())
+            return fail("device revoke", json, "CONFIRMATION_REQUIRED", "Refusing to revoke without confirmation — re-run with --yes.");
+        const answer = await p.confirm({ message: "Revoke this machine's access? The CLI and the desktop here will be signed out." });
+        if (p.isCancel(answer) || !answer) {
+            p.outro("Cancelled — nothing revoked.");
+            return;
+        }
+    }
+    const clientId = grant.clientId;
+    const outcome = clientId ? await revokeGrant({ authBaseUrl: grant.authBaseUrl, refreshToken: grant.grantToken, clientId }) : "unreachable";
+    if (outcome === "refused" || outcome === "unreachable") {
+        return fail("device revoke", json, "REVOKE_FAILED", outcome === "refused" ? "The auth service refused to end the grant." : "Couldn't reach the auth service to end the grant.");
+    }
+    await deleteDeviceCredential(grant.deviceId).catch(() => false);
+    if (json) {
+        printJsonSuccess("device revoke", { deviceId: grant.deviceId, revoked: true, current: true });
+        return;
+    }
+    p.log.success("Revoked this machine's access.");
+}

package/dist/commands/docs.js

@@ -0,0 +1,119 @@
+import { getDocument, listDocuments, resolveNuStackUrl, } from "../lib/nustack_client.js";
+import { ensureAuthWithRecovery, lastAuthFailure } from "../lib/auth_recovery.js";
+import { resolveWorkspaceId } from "../lib/workspace_context.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+const INLINE_BODY_LIMIT = 16 * 1024;
+async function resolveContext(command, json, options, globals) {
+    const baseUrl = resolveNuStackUrl(globals);
+    const workspace = await resolveWorkspaceId(process.cwd(), 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 };
+}
+function emitFail(command, json, code, message) {
+    if (json)
+        printJsonError(command, { code, message });
+    else {
+        console.error(message);
+        process.exitCode = 1;
+    }
+}
+export async function runDocsList(options, globals) {
+    const json = options.json === true;
+    const ctx = await resolveContext("docs list", json, options, globals);
+    if (!ctx)
+        return;
+    const documents = await listDocuments(ctx.baseUrl, ctx.accessToken, ctx.workspaceId);
+    if (json) {
+        printJsonSuccess("docs list", { workspaceId: ctx.workspaceId, documents });
+        return;
+    }
+    if (documents.length === 0) {
+        console.log("This Workspace has no Documents yet.");
+        return;
+    }
+    for (const doc of documents) {
+        const written = doc.hasBody ? "written" : "empty";
+        console.log(`${doc.slug.padEnd(28)} ${(doc.type ?? "-").padEnd(16)} ${doc.status.padEnd(8)} ${written.padEnd(8)} ${doc.label}`);
+    }
+}
+export async function runDocsShow(target, options, globals) {
+    const json = options.json === true;
+    const ctx = await resolveContext("docs show", json, options, globals);
+    if (!ctx)
+        return;
+    const documents = await listDocuments(ctx.baseUrl, ctx.accessToken, ctx.workspaceId);
+    const match = documents.find((d) => d.id === target || d.slug === target);
+    if (!match) {
+        emitFail("docs show", json, "DOCUMENT_NOT_FOUND", `No Document "${target}" in this Workspace.`);
+        return;
+    }
+    const payload = await getDocument(ctx.baseUrl, ctx.accessToken, match.id);
+    const doc = payload.document;
+    const body = doc.body || null;
+    const byteSize = body ? Buffer.byteLength(body) : 0;
+    const inlineable = body !== null && byteSize <= INLINE_BODY_LIMIT;
+    if (json) {
+        printJsonSuccess("docs show", {
+            document: {
+                id: doc.id,
+                slug: doc.slug,
+                label: doc.label,
+                documentType: doc.docType,
+                status: doc.status,
+                bodySha256: doc.bodySha256,
+                blockedBy: doc.blockedBy,
+            },
+            body: inlineable ? body : null,
+            byteSize,
+        });
+        return;
+    }
+    console.log(`# ${doc.label} (${doc.slug})`);
+    console.log(`type: ${doc.docType ?? "-"}   status: ${doc.status}   bodySha256: ${doc.bodySha256.slice(0, 12)}`);
+    if (doc.blockedBy.length > 0)
+        console.log(`blocked by: ${doc.blockedBy.join(", ")}`);
+    if (inlineable && body !== null) {
+        console.log("");
+        console.log(body);
+    }
+    else if (body !== null) {
+        console.log(`Body is ${byteSize} bytes — larger than the inline limit; open it in the studio.`);
+    }
+    else {
+        console.log("Nothing has been written into this document yet.");
+    }
+}
+export async function runDocsStatus(options, globals) {
+    const json = options.json === true;
+    const ctx = await resolveContext("docs status", json, options, globals);
+    if (!ctx)
+        return;
+    const documents = await listDocuments(ctx.baseUrl, ctx.accessToken, ctx.workspaceId);
+    const rows = documents.map((doc) => ({
+        slug: doc.slug,
+        documentId: doc.id,
+        bodySha256: doc.bodySha256,
+        status: doc.status,
+        convergence: "unmapped",
+    }));
+    if (json) {
+        printJsonSuccess("docs status", { workspaceId: ctx.workspaceId, paths: rows });
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("This Workspace has no Documents to converge.");
+        return;
+    }
+    for (const row of rows) {
+        console.log(`${row.slug.padEnd(28)} ${row.convergence.padEnd(10)} ${row.status.padEnd(8)} ${row.bodySha256 ? row.bodySha256.slice(0, 12) : "-"}`);
+    }
+}