@neat.is/core 0.9.17-dev.20260916 → 0.9.18-dev.20260917

package/dist/cli.d.cts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 declare function readPackageVersion(): string;
 declare function printBanner(): void;
+declare function isNpxInvocation(): boolean;
+declare function commandPrefix(): string;
 
 interface HttpClient {
     get<T>(path: string): Promise<T>;
@@ -21,8 +23,6 @@ interface InitResult {
     exitCode: number;
     writtenFiles: string[];
 }
-declare function isNpxInvocation(): boolean;
-declare function commandPrefix(): string;
 declare function usage(): void;
 interface ParsedArgs {
     project: string | null;
@@ -31,6 +31,7 @@ interface ParsedArgs {
     dryRun: boolean;
     noInstall: boolean;
     noInstrument: boolean;
+    open: boolean;
     noOpen: boolean;
     yes: boolean;
     verbose: boolean;

package/dist/cli.d.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 declare function readPackageVersion(): string;
 declare function printBanner(): void;
+declare function isNpxInvocation(): boolean;
+declare function commandPrefix(): string;
 
 interface HttpClient {
     get<T>(path: string): Promise<T>;
@@ -21,8 +23,6 @@ interface InitResult {
     exitCode: number;
     writtenFiles: string[];
 }
-declare function isNpxInvocation(): boolean;
-declare function commandPrefix(): string;
 declare function usage(): void;
 interface ParsedArgs {
     project: string | null;
@@ -31,6 +31,7 @@ interface ParsedArgs {
     dryRun: boolean;
     noInstall: boolean;
     noInstrument: boolean;
+    open: boolean;
     noOpen: boolean;
     yes: boolean;
     verbose: boolean;

package/dist/cli.js

@@ -129,6 +129,17 @@ function printBanner() {
   console.log(`  neat.is  \xB7  v${readPackageVersion()}  \xB7  Apache 2.0`);
   console.log("");
 }
+function isNpxInvocation() {
+  if (process.env.npm_command === "exec") return true;
+  const execpath = process.env.npm_execpath ?? "";
+  if (execpath.includes("npx")) return true;
+  const entry2 = process.argv[1] ?? "";
+  if (entry2.includes("/_npx/") || entry2.includes("\\_npx\\")) return true;
+  return false;
+}
+function commandPrefix() {
+  return isNpxInvocation() ? "npx neat.is" : "neat";
+}
 
 // src/gitignore.ts
 import { promises as fs } from "fs";
@@ -4379,17 +4390,17 @@ async function runOrchestrator(opts) {
   }
   const webPort = allocated?.web ?? NEAT_PORTS[2];
   const dashboardUrl = opts.dashboardUrl ?? `http://localhost:${webPort}`;
-  if (opts.noOpen || !process.stdout.isTTY) {
-    result.steps.browser = "skipped";
-  } else {
+  if (opts.open === true && !opts.noOpen && process.stdout.isTTY) {
     result.steps.browser = openBrowser(dashboardUrl);
+  } else {
+    result.steps.browser = "skipped";
   }
   const daemonRunning = result.steps.daemon === "spawned" || result.steps.daemon === "already-running";
   const daemonLog = daemonRunning ? path10.relative(opts.scanPath, daemonLogPath(opts.scanPath)) : null;
-  printSummary(result, graph, dashboardUrl, daemonLog);
+  printSummary(result, graph, daemonLog);
   return result;
 }
-function printSummary(result, graph, dashboardUrl, daemonLog) {
+function printSummary(result, graph, daemonLog) {
   const nodes = [];
   graph.forEachNode((_id, attrs) => nodes.push(attrs));
   const edges = [];
@@ -4404,12 +4415,21 @@ function printSummary(result, graph, dashboardUrl, daemonLog) {
   for (const [t, c] of [...byNode.entries()].sort()) console.log(`  ${t}: ${c}`);
   for (const [t, c] of [...byEdge.entries()].sort()) console.log(`  ${t}: ${c}`);
   console.log("");
-  console.log(`dashboard: ${dashboardUrl}`);
+  const neat = commandPrefix();
+  console.log("query the graph from your coding agent \u2014 NEAT runs as an MCP server, so");
+  console.log("Claude Code, Cursor, and the rest read it directly:");
+  console.log(`      ${neat} skill --apply    put NEAT in front of Claude Code`);
+  console.log(`      (\`${neat} --help\` lists Cursor, Codex, Gemini, and the other clients)`);
+  console.log("or ask it straight from this terminal:");
+  console.log(`      ${neat} ask "how does checkout work?"`);
+  console.log("");
+  console.log(`want a visual dashboard? log in to hosted NEAT \u2014 \`${neat} login\``);
   const token = process.env.NEAT_AUTH_TOKEN;
+  console.log("");
   if (typeof token === "string" && token.length > 0) {
-    console.log(`auth token: ${token}`);
+    console.log(`auth token (needed to reach the daemon and route OTel): ${token}`);
   } else {
-    console.log("running locally \u2014 open the dashboard, no token needed");
+    console.log("running locally \u2014 no auth token needed");
   }
   const failedInstalls = (result.steps.apply.packageManagerInstalls ?? []).filter(
     (i) => i.exitCode !== 0
@@ -5779,7 +5799,7 @@ async function clearActiveProfile(home = neatHome()) {
 import { createServer } from "http";
 import { spawn as spawn3 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-var DEFAULT_CP_URL = "https://api.neat.is";
+var DEFAULT_CP_URL = "https://neat-control-plane-bg5yqctn2q-nw.a.run.app";
 var DEFAULT_WEB_URL = "https://app.neat.is";
 var CALLBACK_TIMEOUT_MS = 5 * 6e4;
 function resolveCpUrl(env = process.env, override) {
@@ -6267,6 +6287,98 @@ async function defaultReadSecret(prompt) {
   });
 }
 
+// src/welcome.ts
+import readline4 from "readline/promises";
+var WORDMARK = [
+  "\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557",
+  "\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D",
+  "\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551   \u2588\u2588\u2551   ",
+  "\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255D  \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551   \u2588\u2588\u2551   ",
+  "\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2551   \u2588\u2588\u2551   ",
+  "\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D   \u255A\u2550\u255D   "
+];
+var AGENT_SETUP_PROMPT = `Set up self-hosted NEAT for this project. NEAT keeps a live graph of the code
+fused with runtime OpenTelemetry data, queryable over MCP \u2014 so you can ask it
+about the system instead of grepping files.
+
+1. Extract the code graph and instrument the services for OpenTelemetry:
+     npx neat.is init . --apply
+   Then install the deps it added (npm install, or your language's equivalent).
+2. Start the NEAT daemon so it watches the code and ingests live traces:
+     npx neat.is watch .
+3. Wire NEAT's MCP server into your agent so it queries the graph first:
+     npx neat.is skill --apply
+   (other agents: npx neat.is codex|cursor|gemini \u2026 --apply)
+
+Then ask NEAT instead of reading files, e.g.
+     npx neat.is ask "why is checkout failing?"`;
+function printHeader(out) {
+  for (const line of WORDMARK) out(line);
+  out("");
+  out(`  neat.is  \xB7  v${readPackageVersion()}`);
+  out("");
+}
+async function runWelcome(deps = {}) {
+  const out = deps.out ?? ((line) => console.log(line));
+  const readLine = deps.readLine ?? defaultReadLine2;
+  const login = deps.login ?? (() => Promise.resolve(0));
+  const orchestrator = deps.orchestrator ?? (() => Promise.resolve(0));
+  const cwd = deps.cwd ?? process.cwd();
+  printHeader(out);
+  out("Welcome to NEAT. Let's get you a graph of this system.");
+  out("");
+  out("  1) I have a NEAT account \u2014 log in");
+  out("  2) Self-hosted \u2014 set up NEAT on this machine");
+  out("");
+  for (; ; ) {
+    const choice = (await readLine("Choose 1 or 2 (default 2): "))?.trim();
+    if (choice === void 0) return runSelfHosted(out, readLine, orchestrator, cwd);
+    if (choice === "1") {
+      return login(["--browser"]);
+    }
+    if (choice === "2" || choice === "") {
+      return runSelfHosted(out, readLine, orchestrator, cwd);
+    }
+    out(`"${choice}" isn't 1 or 2 \u2014 try again, or press Enter for self-hosted.`);
+  }
+}
+async function runSelfHosted(out, readLine, orchestrator, cwd) {
+  const wantsPrompt = (await readLine("Print a copy-paste setup prompt for your coding agent? [Y/n]: "))?.trim().toLowerCase();
+  if (wantsPrompt !== "n" && wantsPrompt !== "no") {
+    out("");
+    out("\u2500\u2500\u2500 copy the prompt below into your coding agent \u2500\u2500\u2500");
+    out("");
+    out(AGENT_SETUP_PROMPT);
+    out("");
+    out("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    out("");
+  }
+  out("Building your local graph now\u2026");
+  out("");
+  return orchestrator(cwd);
+}
+async function shouldShowWelcome(deps = {}) {
+  const stdinTTY = deps.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+  const stdoutTTY = deps.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
+  if (!stdinTTY || !stdoutTTY) return false;
+  const readProfiles = deps.readProfiles ?? (() => readProfilesConfig());
+  try {
+    const { profiles } = await readProfiles();
+    return profiles.length === 0;
+  } catch {
+    return false;
+  }
+}
+async function defaultReadLine2(prompt) {
+  if (!process.stdin.isTTY) return void 0;
+  const rl = readline4.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(prompt);
+  } finally {
+    rl.close();
+  }
+}
+
 // src/hooks-cli.ts
 import path13 from "path";
 import os2 from "os";
@@ -7807,17 +7919,6 @@ async function runSync(opts) {
 
 // src/cli.ts
 import { DivergenceTypeSchema } from "@neat.is/types";
-function isNpxInvocation() {
-  if (process.env.npm_command === "exec") return true;
-  const execpath = process.env.npm_execpath ?? "";
-  if (execpath.includes("npx")) return true;
-  const entry2 = process.argv[1] ?? "";
-  if (entry2.includes("/_npx/") || entry2.includes("\\_npx\\")) return true;
-  return false;
-}
-function commandPrefix() {
-  return isNpxInvocation() ? "npx neat.is" : "neat";
-}
 function usage5() {
   const neat = commandPrefix();
   console.log("Installed via npx? Prefix commands with `npx neat.is`, or install once: `npm i -g neat.is`.");
@@ -7825,8 +7926,15 @@ function usage5() {
   console.log(`usage: ${neat} <command> [args] [--project <name>]`);
   console.log("");
   console.log(`Run \`${neat}\` with no command from inside your project to go zero-to-graph in one step.`);
+  console.log(`On your first run in a terminal, \`${neat}\` opens a short menu \u2014 log in to a hosted`);
+  console.log(`NEAT, or set up self-hosted here. Run \`${neat} welcome\` to open it again anytime.`);
+  console.log(`The run stays in your terminal \u2014 query the graph over MCP or the CLI. For a visual`);
+  console.log(`dashboard, log in to hosted NEAT; \`--open\` launches the local preview one by choice.`);
   console.log("");
   console.log("lifecycle commands:");
+  console.log("  welcome        Open the first-run menu: log in to a hosted NEAT, or set up");
+  console.log("                 self-hosted (print an agent-setup prompt, then build the graph");
+  console.log("                 for the current directory).");
   console.log("  init <path>    One-time install: discover, extract, register, plan SDK install.");
   console.log("                 Snapshot lands in <path>/neat-out/graph.json by default");
   console.log("                 (or <path>/neat-out/<project>.json for non-default).");
@@ -8037,6 +8145,7 @@ function parseArgs(rest) {
     dryRun: false,
     noInstall: false,
     noInstrument: false,
+    open: false,
     noOpen: false,
     yes: false,
     verbose: false,
@@ -8074,6 +8183,10 @@ function parseArgs(rest) {
       out.noInstrument = true;
       continue;
     }
+    if (arg === "--open") {
+      out.open = true;
+      continue;
+    }
     if (arg === "--no-open") {
       out.noOpen = true;
       continue;
@@ -8453,6 +8566,11 @@ async function main() {
   }
   const argvParsed = parseArgs(argv);
   if (argvParsed.positional.length === 0) {
+    if (await shouldShowWelcome()) {
+      const welcomeCode = await runWelcomeFlow(argvParsed);
+      if (welcomeCode !== 0) process.exit(welcomeCode);
+      return;
+    }
     const orchestratorCode2 = await tryOrchestrator(process.cwd(), argvParsed);
     if (orchestratorCode2 !== null && orchestratorCode2 !== 0) process.exit(orchestratorCode2);
     return;
@@ -8461,6 +8579,11 @@ async function main() {
   const parsed = { ...argvParsed, positional: argvParsed.positional.slice(1) };
   const { positional, apply: apply6, dryRun, noInstall } = parsed;
   const project = parsed.project ?? DEFAULT_PROJECT;
+  if (cmd === "welcome") {
+    const code = await runWelcomeFlow(parsed);
+    if (code !== 0) process.exit(code);
+    return;
+  }
   if (cmd === "init") {
     const target = positional[0];
     if (!target) {
@@ -8713,11 +8836,18 @@ async function tryOrchestrator(cmd, parsed) {
     project: projectName,
     projectExplicit,
     noInstrument: parsed.noInstrument,
+    open: parsed.open,
     noOpen: parsed.noOpen,
     yes: parsed.yes
   });
   return result.exitCode;
 }
+async function runWelcomeFlow(parsed) {
+  return runWelcome({
+    login: (loginArgv) => runLoginCommand(loginArgv),
+    orchestrator: async (cwd) => await tryOrchestrator(cwd, parsed) ?? 0
+  });
+}
 var QUERY_VERBS = /* @__PURE__ */ new Set([
   "root-cause",
   "blast-radius",