@nurix/nustack 0.10.0-dev.10

package/dist/index.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { Command } from "commander";
+import { runLogin } from "./commands/login.js";
+import { runInit } from "./commands/init.js";
+import { runAdd } from "./commands/add.js";
+import { runList } from "./commands/list.js";
+import { runSync } from "./commands/sync.js";
+import { runDescribe } from "./commands/describe.js";
+import { runValidate } from "./commands/validate.js";
+import { runGraph } from "./commands/graph.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runOpen } from "./commands/open.js";
+import { runBootstrap } from "./commands/bootstrap.js";
+import { runLogout } from "./commands/logout.js";
+import { runTelemetry } from "./commands/telemetry.js";
+import { runSearch, runSearchServices } from "./commands/search.js";
+import { runDeviceList, runDeviceRevoke, runDeviceStatus } from "./commands/device.js";
+import { registerWorkspaceSyncCommands } from "./commands/workspace-sync.js";
+import { registerWorkspaceCommands } from "./commands/workspace.js";
+import { runOrganizationList, runOrganizationCreate, runOrganizationUse } from "./commands/organization.js";
+import { runDocsList, runDocsShow, runDocsStatus } from "./commands/docs.js";
+import { runHandoffList, runHandoffShow } from "./commands/handoff.js";
+import { runToolkitStatus, runToolkitReconcile } from "./commands/toolkit.js";
+import { runLaneServe } from "./commands/lane.js";
+import { runSessionsRecord } from "./commands/sessions.js";
+import { registerReviewCommands } from "./commands/review.js";
+import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
+import { printJsonError } from "./lib/json_output.js";
+import { setCliVersion } from "./lib/auth_grant.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+setCliVersion(version);
+const program = new Command();
+program
+    .name("nustack")
+    .description("Bootstrap NuStack services into your repo via the NuStack discovery plane.")
+    .version(version)
+    .option("--nustack-url <url>", "NuStack base URL (defaults to $NUSTACK_URL, then the hosted instance)")
+    .action(async () => runBootstrap(program.opts()));
+program.addHelpText("after", "\nRun `nustack` with no command to bootstrap: it checks your sign-in, runs login if needed, then init.");
+program
+    .command("login")
+    .description("Sign in with your browser; this machine's grant is saved to your OS keychain")
+    .option("--no-open", "don't auto-open the browser; just print the sign-in URL")
+    .option("--manual", "sign in anywhere and paste the code here instead of using a browser on this machine")
+    .option("--force", "sign in again even if this machine already holds a grant, and ask for the account")
+    .action(async (options) => runLogin(program.opts(), options));
+program
+    .command("logout")
+    .description("Sign out: end this machine's grant and clear the shared keychain credential (both CLI and desktop)")
+    .option("--forget-device", "also clear the shared ~/.nustack/device_id machine identity")
+    .action(async (options) => runLogout(program.opts(), { forgetDevice: options.forgetDevice }));
+program
+    .command("init")
+    .description("Onboard this folder: sign in, then bind it to a Workspace (the onboarding router)")
+    .option("--organization <id>", "the Organization to create or select the Workspace in")
+    .option("--yes", "pre-confirm the populated-folder onboarding guard")
+    .action(async (options) => runInit({ ...program.opts(), ...options }));
+program
+    .command("add [service]")
+    .description("Record a stack service in this repo: install its package, add the consumes edge")
+    .option("--json", "emit the versioned machine envelope instead of interactive output")
+    .option("--yes", "assume yes for the package-install and manifest-scaffold prompts")
+    .action(async (service, options) => runAdd(service, { ...program.opts(), ...options }));
+program
+    .command("list")
+    .description("List the services in the NuStack catalogue")
+    .option("--json", "emit the versioned machine envelope wrapping the catalogue entries")
+    .action(async (options) => runList(options, program.opts()));
+program
+    .command("sync")
+    .description("Project this Workspace's Service credentials into the managed .env block (not Documents or Git)")
+    .option("--workspace <id>", "the Workspace to act as (defaults to nustack.service.json / NUSTACK_WORKSPACE_ID)")
+    .option("--json", "emit the versioned machine envelope instead of interactive output")
+    .action(async (options) => runSync({ ...program.opts(), ...options }));
+program
+    .command("describe <service>")
+    .description("Show the full catalogue entry for a service")
+    .option("--json", "emit the raw catalogue entry as JSON")
+    .action(async (service, options) => runDescribe(service, options, program.opts()));
+program
+    .command("validate [manifest]")
+    .description("Validate an nustack.service.json (path or URL) against the nustack.dev/v1 schema")
+    .option("--schema <pathOrUrl>", "override the bundled packages/contracts/spec/schema.json")
+    .option("--json", "emit the versioned machine envelope with { target, isValid, errors }")
+    .action(async (manifest, options) => runValidate(manifest, options));
+program
+    .command("graph [fn] [args...]")
+    .description("The code graph: ask a question of this repository's index, or `index` / `status` / `functions`")
+    .option("--repo <pathOrId>", "the repository to ask about (default: the working tree's root)")
+    .option("--no-refresh", "answer from the index as it stands, however old")
+    .option("--budget <n>", "token ceiling for the answer; 0 means unbounded")
+    .option("--commits <n>", "history depth for `graph index` (default 5000)")
+    .option("--json", "emit the versioned machine envelope with the answer as data")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(async (_fn, _args, options) => runGraph(process.argv, options));
+program
+    .command("doctor")
+    .description("Run the full local diagnostics matrix (identity, repository, manifests, toolkit, telemetry, credentials)")
+    .option("--workspace <id>", "the Workspace to diagnose (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope (secrets and absolute paths redacted)")
+    .option("--local-verbose", "include Device-local absolute paths in the output")
+    .action(async (options) => runDoctor({ ...program.opts(), ...options }));
+program
+    .command("open <service>")
+    .description("Open the service's dev endpoint (or repository) in the browser")
+    .option("--env <name>", "pick a specific endpoint environment (default: dev)")
+    .option("--json", "print the resolved URL as the machine envelope instead of launching")
+    .action(async (service, options) => runOpen(service, options, program.opts()));
+const device = program.command("device").description("Inspect your signed-in devices and end this machine's access");
+device
+    .command("list")
+    .description("List your signed-in devices (never a token)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDeviceList(options, program.opts()));
+device
+    .command("status")
+    .description("Show this device's local state merged with its server record")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDeviceStatus(options, program.opts()));
+device
+    .command("revoke [device-id]")
+    .description("End this machine's access (other machines are revoked from Profile › Devices)")
+    .option("--json", "emit the versioned machine envelope")
+    .option("--yes", "skip the confirmation prompt")
+    .action(async (deviceId, options) => runDeviceRevoke(deviceId, options, program.opts()));
+program
+    .command("telemetry [action]")
+    .description("Inspect or control telemetry (status | enable | disable | reinstall). Inside a bound folder, enable/disable move that folder alone")
+    .option("--json", "emit the versioned machine envelope")
+    .option("--device", "move this machine's switch instead of the current folder's")
+    .option("--local-verbose", "include each folder's absolute path (local consumers only — never pipe into a log)")
+    .action(async (action, options) => {
+    const allowed = ["status", "enable", "disable", "reinstall"];
+    const chosen = (allowed.includes(action ?? "") ? action : "status");
+    return runTelemetry(chosen, {
+        ...program.opts(),
+        json: options.json,
+        device: options.device,
+        localVerbose: options.localVerbose,
+    });
+});
+const toLimit = (value) => Number.parseInt(value, 10);
+const search = program
+    .command("search [keywords...]")
+    .description("Search the NuStack Directory for workspaces by keyword")
+    .option("--json", "emit the raw results array as JSON")
+    .option("--category <cat>", "filter workspaces by category")
+    .option("--limit <n>", "max results (default 20)", toLimit)
+    .action(async (keywords, options) => runSearch(keywords, options, program.opts()));
+search
+    .command("services [keywords...]")
+    .description("Search the services registry by keyword (then `nustack add <name>` to integrate)")
+    .option("--json", "emit the raw results array as JSON")
+    .option("--type <type>", "filter services by type")
+    .option("--limit <n>", "max results (default 20)", toLimit)
+    .action(async (keywords, options) => runSearchServices(keywords, { ...search.opts(), ...options }, program.opts()));
+search.addHelpText("after", '\n`services` is a reserved subcommand. To search workspaces for the literal word "services", use the\n' +
+    "explicit separator: `nustack search -- services` (everything after `--` is an workspaces query).");
+const organization = program.command("organization").description("Work with your NuStack Organizations");
+organization
+    .command("list")
+    .description("List your Organization memberships (name, slug, role, active marker)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runOrganizationList(options, program.opts()));
+organization
+    .command("create <name>")
+    .description("Create an Organization and print it")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (name, options) => runOrganizationCreate(name, options, program.opts()));
+organization
+    .command("use <id-or-slug>")
+    .description("Set the active Organization context for this device")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (target, options) => runOrganizationUse(target, options, program.opts()));
+const workspace = program.command("workspace").description("Work with NuStack Workspaces");
+registerWorkspaceCommands(workspace, () => program.opts());
+registerWorkspaceSyncCommands(workspace, () => program.opts());
+registerReviewCommands(program.command("review").description("Read and mirror NuStack Review items"), () => program.opts());
+const docs = program.command("docs").description("Work with a Workspace's Documents");
+docs
+    .command("list")
+    .description("List the Workspace's Documents")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDocsList(options, program.opts()));
+docs
+    .command("show <slug-or-id>")
+    .description("Show a Document: a bounded inline body or its content URL")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (target, options) => runDocsShow(target, options, program.opts()));
+docs
+    .command("status")
+    .description("Report per-path local/cloud Document convergence for the bound repository")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runDocsStatus(options, program.opts()));
+const handoff = program.command("handoff").description("Work with a Workspace's Handoffs");
+handoff
+    .command("list")
+    .description("List the Workspace's Handoffs")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runHandoffList(options, program.opts()));
+handoff
+    .command("show <id>")
+    .description("Show a Handoff (add --targets for the binding-scoped per-target manifest)")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--targets", "list each target's path, operation, and base semantics")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (id, options) => runHandoffShow(id, options, program.opts()));
+const lane = program.command("lane").description("The desktop build room's lane engine");
+lane
+    .command("serve")
+    .description("Run the long-lived lane supervisor: JSONL frames on stdin/stdout (used by the NuStack desktop)")
+    .action(async () => runLaneServe(version));
+const sessions = program.command("sessions").description("The session record over this machine's agent work");
+sessions
+    .command("record")
+    .description("Record the sessions one desktop scan found in a bound folder (used by the NuStack desktop)")
+    .option("--scan <json>", "the scan payload as JSON, or @<path> to read it from a file")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runSessionsRecord(options, program.opts()));
+const toolkit = program.command("toolkit").description("Inspect and reconcile the Workspace's toolkit pin");
+toolkit
+    .command("status")
+    .description("Compare the cloud pin against .nustack/workspace.json and nustack.service.json (F-026)")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runToolkitStatus(options, program.opts()));
+toolkit
+    .command("reconcile")
+    .description("Preview and apply the deterministic toolkit repair (no User content is touched)")
+    .option("--workspace <id>", "the Workspace to act as (defaults to the bound repository)")
+    .option("--yes", "apply the deterministic preview without prompting")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runToolkitReconcile(options, program.opts()));
+const agent = program.command("agent").description("The discovery hook an agent uses to find the running NuStack desktop");
+agent
+    .command("context")
+    .description("Print the SessionStart hook payload when the NuStack desktop is reachable (silent otherwise)")
+    .action(async () => runAgentContext());
+const agentHook = agent.command("hook").description("Manage the `nustack agent context` SessionStart hook in ~/.claude/settings.json");
+agentHook
+    .command("install")
+    .description("Register the SessionStart hook (idempotent — a second install is a no-op)")
+    .action(async () => runAgentHookInstall());
+agentHook
+    .command("remove")
+    .description("Remove exactly the managed SessionStart hook entry")
+    .action(async () => runAgentHookRemove());
+function describeError(error) {
+    const directCode = error?.code;
+    if (directCode === "WORKSPACE_CONTEXT_MISSING") {
+        return "no Workspace in context — run inside a bound repository (`.nustack/workspace.json`) or pass `--workspace <id>`.";
+    }
+    if (directCode === "ORGANIZATION_CONTEXT_MISSING") {
+        return "no Organization in context — run `nustack organization use <id>` or pass `--organization <id>`.";
+    }
+    if (directCode === "TOOLKIT_INCOMPATIBLE") {
+        return "the installed toolkit is incompatible with the Workspace's cloud pin — run `nustack toolkit reconcile`.";
+    }
+    const cause = error?.cause;
+    const code = cause?.code;
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+        return "couldn't resolve the NuStack host — check your connection or pass --nustack-url.";
+    }
+    if (code === "ECONNREFUSED") {
+        return "the NuStack host refused the connection — is it up? Override with --nustack-url.";
+    }
+    if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+        return "the request to NuStack timed out — check your connection or try again.";
+    }
+    if (error instanceof Error && error.message === "fetch failed") {
+        return "couldn't reach NuStack — check your connection or pass --nustack-url.";
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function searchSeparatorInvocation(rawArgv) {
+    const args = rawArgv.slice(2);
+    const searchIdx = args.indexOf("search");
+    if (searchIdx === -1)
+        return null;
+    if (searchIdx > 0 && args[searchIdx - 1] === "--nustack-url")
+        return null;
+    let cut = searchIdx + 1;
+    while (cut < args.length) {
+        const token = args[cut] ?? "";
+        if (token === "--category" || token === "--limit" || token === "--nustack-url") {
+            cut += 2;
+        }
+        else if (token.startsWith("--") && token !== "--") {
+            cut += 1;
+        }
+        else {
+            break;
+        }
+    }
+    if (args[cut] !== "--")
+        return null;
+    const beforeSeparator = args.slice(0, cut);
+    const literalKeywords = args.slice(cut + 1);
+    return {
+        run: async () => {
+            const scoped = new Command();
+            scoped.exitOverride();
+            scoped.name("nustack").option("--nustack-url <url>", "");
+            scoped
+                .command("search [keywords...]")
+                .option("--json", "")
+                .option("--category <cat>", "")
+                .option("--limit <n>", "", toLimit)
+                .action(async (keywords, options) => runSearch(keywords, options, scoped.opts()));
+            await scoped.parseAsync(["node", "nustack", ...beforeSeparator, ...literalKeywords]);
+        },
+    };
+}
+function isJsonInvocation(argv) {
+    return argv.slice(2).includes("--json");
+}
+function commandLabelFromArgv(argv) {
+    const args = argv.slice(2);
+    const parts = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i] ?? "";
+        if (token === "--nustack-url") {
+            i++;
+            continue;
+        }
+        if (token.startsWith("-"))
+            break;
+        parts.push(token);
+    }
+    return parts.length ? parts.join(" ") : "nustack";
+}
+function errorCodeOf(error) {
+    const direct = error?.code ?? error?.cause?.code;
+    return typeof direct === "string" ? direct : "UNEXPECTED";
+}
+try {
+    const separated = searchSeparatorInvocation(process.argv);
+    if (separated)
+        await separated.run();
+    else
+        await program.parseAsync(process.argv);
+}
+catch (error) {
+    if (isJsonInvocation(process.argv)) {
+        printJsonError(commandLabelFromArgv(process.argv), { code: errorCodeOf(error), message: describeError(error) });
+    }
+    else {
+        console.error(`nustack: ${describeError(error)}`);
+        process.exitCode = 1;
+    }
+}

package/dist/lib/agent/claudeHooks.js

@@ -0,0 +1,77 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const MANAGED_MARKER = "nustack:managed";
+const MANAGED_COMMAND = `nustack agent context # ${MANAGED_MARKER}`;
+function managedEntry() {
+    return { matcher: "", hooks: [{ type: "command", command: MANAGED_COMMAND }] };
+}
+function isManagedEntry(entry) {
+    if (entry === null || typeof entry !== "object")
+        return false;
+    const hooks = entry.hooks;
+    if (!Array.isArray(hooks))
+        return false;
+    return hooks.some((hook) => hook !== null &&
+        typeof hook === "object" &&
+        typeof hook.command === "string" &&
+        hook.command.includes(MANAGED_MARKER));
+}
+const DEFAULT_INDENT = 2;
+function detectIndent(raw) {
+    const indented = /\n(\x20+)"/.exec(raw);
+    return indented?.[1] ? indented[1].length : DEFAULT_INDENT;
+}
+async function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return { settings: {}, indent: DEFAULT_INDENT };
+    const raw = await readFile(settingsPath, "utf8");
+    if (raw.trim() === "")
+        return { settings: {}, indent: DEFAULT_INDENT };
+    return { settings: JSON.parse(raw), indent: detectIndent(raw) };
+}
+async function writeSettings(settingsPath, settings, indent) {
+    await mkdir(path.dirname(settingsPath), { recursive: true });
+    await writeFile(settingsPath, `${JSON.stringify(settings, null, indent)}\n`, "utf8");
+}
+export async function installSessionStartHook(settingsPath) {
+    const { settings, indent } = await readSettings(settingsPath);
+    const hooks = { ...(settings.hooks ?? {}) };
+    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+    const existingIndex = sessionStart.findIndex(isManagedEntry);
+    const entry = managedEntry();
+    if (existingIndex !== -1) {
+        const current = sessionStart[existingIndex];
+        if (JSON.stringify(current) === JSON.stringify(entry)) {
+            return { changed: false };
+        }
+        sessionStart[existingIndex] = entry;
+    }
+    else {
+        sessionStart.push(entry);
+    }
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
+    await writeSettings(settingsPath, settings, indent);
+    return { changed: true };
+}
+export async function removeSessionStartHook(settingsPath) {
+    const { settings, indent } = await readSettings(settingsPath);
+    const hooks = settings.hooks;
+    const sessionStart = hooks?.SessionStart;
+    if (!hooks || !Array.isArray(sessionStart))
+        return { removed: false };
+    const filtered = sessionStart.filter((entry) => !isManagedEntry(entry));
+    if (filtered.length === sessionStart.length)
+        return { removed: false };
+    const nextHooks = { ...hooks };
+    if (filtered.length > 0) {
+        nextHooks.SessionStart = filtered;
+    }
+    else {
+        delete nextHooks.SessionStart;
+    }
+    settings.hooks = nextHooks;
+    await writeSettings(settingsPath, settings, indent);
+    return { removed: true };
+}