nexarch 0.13.3 → 0.13.5

package/dist/commands/init-project.js

@@ -2343,7 +2343,7 @@ export async function initProject(args) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "enrich_entity",
-                instruction: `Enrich the application entity with a meaningful name, description, subtype, and icon.`,
+                instruction: `Enrich the application entity with a meaningful name, description, subtype, and icon. Find a real icon name with \`nexarch search-icons "<what the application is>"\`; a guessed name that doesn't exist is dropped without an error.`,
                 command: `nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`,
                 ...(entityTypeOverride === "application"
                     ? { notes: [APPLICATION_SUBTYPE_HINT, "Choose app_custom_built as the default if none of the others clearly apply."] }
@@ -2384,9 +2384,11 @@ export async function initProject(args) {
                 instruction: `Review the codebase to identify discrete application functions (what the application does). ` +
                     `Examine named modules, route layout, service boundaries, and any architecture documentation. ` +
                     `Register functions as application_function entities with subtype core_function (primary business function), supporting_function (auxiliary/enablement), integration_function (external connectivity), or data_function (data processing). ` +
-                    `Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE}`,
+                    `Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE} ` +
+                    `Give each function an icon for what it does: find a real name with \`nexarch search-icons "<what it does>"\` (or nexarch_search_icons) and pass it as --icon. Don't guess a name; one that doesn't exist is dropped without an error. If two searches find nothing fitting, leave the icon off.`,
                 commandTemplates: {
-                    updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`,
+                    searchIcons: `nexarch search-icons "<what the function does>"`,
+                    updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --icon "<name from search-icons>" --name "..." --description "..."`,
                     addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}_<function_slug>" --to ${projectConstruct && isMonorepo ? '"<owning application key from classifyPackages>"' : `"${projectExternalKey}"`} --type part_of`,
                     note: "Functions are structural decomposition only: do not add runtime dependencies from an application_function. Model independently deployable services as applications or application components, then relate those boundaries with depends_on or integrates_with.",
                 },
@@ -2405,7 +2407,7 @@ export async function initProject(args) {
         pendingSteps.push({
             step: stepNum++,
             action: "register_decision_records",
-            instruction: `Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register each as a decision_record entity.`,
+            instruction: `Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register the architectural ones as decision_record entities: a decision that crosses a boundary between applications, services or teams; changes an integration, data ownership, security or deployment; adopts, replaces or retires a technology others depend on; or is expensive to reverse. Skip design decisions inside one application, even when they are written up as ADRs.`,
             commandTemplates: {
                 updateEntity: `nexarch update-entity --key "decision_record:${projectSlug}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`,
                 addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}_<adr_slug>" --to ${projectConstruct && isMonorepo ? '"<the relevant application key>"' : `"${projectExternalKey}"`} --type decides`,
@@ -2519,7 +2521,7 @@ export async function initProject(args) {
             unresolvedNames: unresolvedItems.map((r) => r.input),
             iconHints: {
                 provider: "lucide",
-                note: "Use any Lucide icon name (kebab-case); omit when confidence is low.",
+                note: "Use a name returned by `nexarch search-icons` (or nexarch_search_icons); a guessed name that doesn't exist is dropped without an error. Omit when nothing fits.",
             },
         };
     }
@@ -2643,15 +2645,19 @@ export async function initProject(args) {
             lines.push(`     Use subtype core_function (primary business function), supporting_function (auxiliary/enablement),`);
             lines.push(`     integration_function (external connectivity), or data_function (data processing).`);
             lines.push(`     Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE}`);
+            lines.push(`     Give each function an icon for what it does. Find a real name first; a guessed one is dropped without an error:`);
+            lines.push(`       nexarch search-icons "<what the function does>"`);
             lines.push(`     For each one found:`);
             const fnOwnerTarget = projectConstruct && isMonorepo ? '"<owning application key from CLASSIFY_THESE>"' : `"${projectExternalKey}"`;
-            lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`);
+            lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --icon "<name from search-icons>" --name "..." --description "..."`);
             lines.push(`       nexarch add-relationship --from "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --to ${fnOwnerTarget} --type part_of`);
             lines.push("       Functions are structural only: model runtime/service dependencies between application or application_component boundaries, never from an application_function.");
         }
         lines.push(`  ${step++}. Scan the READMEs for platforms/SaaS not auto-detected (Vercel, Neon, Stripe, etc.).`);
         lines.push(`       For each found: nexarch resolve-names --names "..." --json  →  nexarch update-entity  →  nexarch add-relationship`);
-        lines.push(`  ${step++}. Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register decision_record entities.`);
+        lines.push(`  ${step++}. Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register the architectural ones as decision_record entities.`);
+        lines.push(`     Architectural means it crosses a boundary between applications, services or teams; changes an integration, data ownership, security or deployment;`);
+        lines.push(`     adopts or retires a technology others depend on; or is expensive to reverse. Skip design decisions inside one application.`);
         lines.push(`       nexarch update-entity --key "decision_record:${projectExternalKey.split(":")[1] ?? "project"}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`);
         lines.push(`       nexarch add-relationship --from "decision_record:..." --to ${projectConstruct && isMonorepo ? '"<the relevant application key>"' : `"${projectExternalKey}"`} --type decides`);
         lines.push("");

package/dist/commands/login.js

@@ -1,6 +1,7 @@
 import { createServer } from "http";
 import { createServer as createNetServer } from "net";
-import { randomBytes } from "crypto";
+import { createHash, randomBytes } from "crypto";
+import * as readline from "node:readline/promises";
 import { execFile } from "child_process";
 import { saveCredentials } from "../lib/credentials.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -136,6 +137,68 @@ function waitForCallback(port, expectedState) {
         });
     });
 }
+/**
+ * Whether the browser that approves this login can reach the CLI at
+ * localhost. It can't over SSH (the browser is on the person's own machine,
+ * the CLI on the remote one) or on a Linux machine with no display; the
+ * loopback callback then lands on the wrong machine and the login hangs.
+ * `--no-browser` forces paste mode, `--browser` forces the loopback flow.
+ */
+export function shouldUsePasteLogin(args, env = process.env, platform = process.platform) {
+    if (args.includes("--browser"))
+        return false;
+    if (args.includes("--no-browser"))
+        return true;
+    if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY)
+        return true;
+    return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+/** A random verifier the CLI keeps, and the challenge it sends: base64url(SHA-256(verifier)). */
+export function createPasteChallenge() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+/** Mistakes worth letting someone paste again rather than starting over. */
+const RETRYABLE_EXCHANGE_ERRORS = new Set(["malformed", "bad_signature"]);
+async function pasteLogin(qp, verifier) {
+    const authUrl = `${NEXARCH_URL}/auth/cli?${qp.toString()}`;
+    console.log("\nThis terminal can't receive the browser's reply directly (for example over SSH),");
+    console.log("so you'll paste a one-time code instead.\n");
+    console.log("  1. Open this link in a browser on any machine:\n");
+    console.log(`     ${authUrl}\n`);
+    console.log("  2. Sign in and authorize.");
+    console.log("  3. Copy the code the page shows and paste it here.\n");
+    if (!process.stdin.isTTY) {
+        throw new Error("Paste login needs an interactive terminal to paste the code into. Run this command directly in a terminal.");
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            const code = (await rl.question("Code: ")).trim();
+            if (!code)
+                continue;
+            const response = await fetch(`${NEXARCH_URL}/api/auth/cli/exchange`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ code, verifier }),
+            });
+            const body = (await response.json().catch(() => ({})));
+            if (response.ok && body.token && body.companyId) {
+                return { token: body.token, companyId: body.companyId, companyName: body.companyName, companyCode: body.companyCode };
+            }
+            const message = body.message ?? `Login failed (${response.status}).`;
+            if (body.error && RETRYABLE_EXCHANGE_ERRORS.has(body.error) && attempt < 3) {
+                console.log(`\n${message}\n`);
+                continue;
+            }
+            throw new Error(message);
+        }
+        throw new Error("No code was entered. Run the command again to get a new link.");
+    }
+    finally {
+        rl.close();
+    }
+}
 function getArgValue(args, flag) {
     const idx = args.indexOf(flag);
     if (idx === -1)
@@ -148,21 +211,33 @@ function getArgValue(args, flag) {
 export async function login(args) {
     printLoginBanner();
     const state = generateState();
-    const port = await findFreePort();
     const requestedCompany = getArgValue(args, "--company");
     const requestedProfile = getArgValue(args, "--profile");
     const isCapabilityProfile = (value) => PROFILE_CHOICES.some((c) => c.value === value);
     const profile = isCapabilityProfile(requestedProfile) ? requestedProfile : await promptCapabilityProfile();
-    const qp = new URLSearchParams({ port: String(port), state, profile });
-    if (requestedCompany)
-        qp.set("company", requestedCompany);
-    const authUrl = `${NEXARCH_URL}/auth/cli?${qp.toString()}`;
     console.log(`\nCapability profile: ${profile}`);
-    console.log("Opening Nexarch in your browser…");
-    console.log(`\n  ${authUrl}\n`);
-    console.log("If the browser did not open, copy the URL above and paste it in manually.\n");
-    openBrowser(authUrl);
-    const { token, companyId, companyName, companyCode } = await waitForCallback(port, state);
+    let result;
+    if (shouldUsePasteLogin(args)) {
+        const { verifier, challenge } = createPasteChallenge();
+        const qp = new URLSearchParams({ mode: "paste", challenge, state, profile });
+        if (requestedCompany)
+            qp.set("company", requestedCompany);
+        result = await pasteLogin(qp, verifier);
+    }
+    else {
+        const port = await findFreePort();
+        const qp = new URLSearchParams({ port: String(port), state, profile });
+        if (requestedCompany)
+            qp.set("company", requestedCompany);
+        const authUrl = `${NEXARCH_URL}/auth/cli?${qp.toString()}`;
+        console.log("Opening Nexarch in your browser…");
+        console.log(`\n  ${authUrl}\n`);
+        console.log("If the browser did not open, copy the URL above and paste it in manually.");
+        console.log("If your browser is on a different machine (for example over SSH), stop this and run it again with --no-browser.\n");
+        openBrowser(authUrl);
+        result = await waitForCallback(port, state);
+    }
+    const { token, companyId, companyName, companyCode } = result;
     const expiresAt = new Date();
     expiresAt.setDate(expiresAt.getDate() + 90);
     saveCredentials({

package/dist/commands/search-icons.js

@@ -0,0 +1,64 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const value = args[idx + 1];
+    if (!value || value.startsWith("--"))
+        return null;
+    return value;
+}
+/**
+ * The words to search for: everything that isn't an option or an option's
+ * value, so both `search-icons database` and `search-icons "event stream"` work.
+ */
+export function searchIconsQuery(args) {
+    const valued = new Set(["--limit"]);
+    const words = [];
+    for (let i = 0; i < args.length; i++) {
+        if (valued.has(args[i])) {
+            i++;
+            continue;
+        }
+        if (args[i].startsWith("--"))
+            continue;
+        words.push(args[i]);
+    }
+    return words.join(" ").trim();
+}
+/**
+ * Finds real icon names for `update-entity --icon`. The gateway silently drops
+ * an icon name that doesn't exist, so an agent guessing from memory ends up
+ * with no icon and no error; this searches the same validated set it checks.
+ */
+export async function searchIcons(args) {
+    const asJson = args.includes("--json");
+    const query = searchIconsQuery(args);
+    if (!query) {
+        console.error('error: say what the icon should show, e.g. nexarch search-icons "credit card"');
+        process.exit(1);
+    }
+    const limitRaw = parseOptionValue(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : undefined;
+    if (limitRaw && (!Number.isInteger(limit) || limit < 1)) {
+        console.error("error: --limit must be a whole number of 1 or more");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_search_icons", { query, ...(limit ? { limit } : {}) }, { companyId: creds.companyId });
+    const result = JSON.parse(raw.content?.[0]?.text ?? "{}");
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    if (!result.matches?.length) {
+        console.log(`No icons match "${query}".`);
+        console.log("Icon names are literal objects and actions (database, file, box). Try one more concrete word; if that also finds nothing, leave the icon unset.");
+        return;
+    }
+    for (const name of result.matches)
+        console.log(name);
+    console.log(`\n${result.matches.length} of ${result.totalMatches} match${result.totalMatches === 1 ? "" : "es"}. Use one with: nexarch update-entity --key "<key>" --icon "${result.matches[0]}"`);
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { updateEntity } from "./commands/update-entity.js";
 import { addRelationship } from "./commands/add-relationship.js";
 import { registerAlias } from "./commands/register-alias.js";
 import { resolveNames } from "./commands/resolve-names.js";
+import { searchIcons } from "./commands/search-icons.js";
 import { feedback } from "./commands/feedback.js";
 import { listEntities } from "./commands/list-entities.js";
 import { listRelationships } from "./commands/list-relationships.js";
@@ -57,6 +58,7 @@ const commands = {
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
     "resolve-names": resolveNames,
+    "search-icons": searchIcons,
     feedback,
     "list-entities": listEntities,
     "list-relationships": listRelationships,
@@ -105,7 +107,12 @@ nexarch — Your architecture workspace for AI delivery.
 
 Usage:
   nexarch login         Authenticate in browser and store company-scoped credentials
-                        Option: --company <id>
+                        Options: --company <id>
+                                 --no-browser  paste a one-time code instead of
+                                               receiving the browser's reply
+                                               locally; automatic over SSH or on
+                                               Linux with no display
+                                 --browser     always use the local browser reply
   nexarch --version     Print the version and the path this copy runs from
   nexarch enroll        Bootstrap a headless (browserless) agent with a one-time
                         enrollment code — no login required. Writes the resulting
@@ -133,6 +140,7 @@ Usage:
                         registering anything; answer 'n' to pick a different one.
                         Options: --company <id|code>  target a workspace directly
                                  --yes  accept the stored workspace without asking
+                                 --no-browser  log in by pasting a one-time code (see login)
   nexarch mcp-config    Print MCP server config block for manual setup
                         Client list is registry-managed (see 'nexarch mcp-config --client <code>')
   nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
@@ -232,6 +240,12 @@ Usage:
                       results before calling add-relationship.
                       Options: --names <csv>  (required, e.g. "vercel,neon")
                                --json
+  nexarch search-icons <words>
+                      Find real icon names for update-entity --icon. An icon
+                      name that doesn't exist is dropped without an error, so
+                      look one up rather than guessing.
+                      Options: --limit <n>  (default 20, max 50)
+                               --json
   nexarch feedback
                       Report a Nexarch usability problem or tool error.
                       Options: --kind <usability|error>  (required)

package/dist/lib/skills.js

@@ -240,7 +240,7 @@ evidence — never invent a compliance status that isn't stored.
 `;
 const DECISION_RECORDS_SKILL_BODY = `---
 name: nexarch-decision-records
-description: Record an architectural decision in Nexarch, or check what's already been decided about something. Use when a decision is being made (a technology, pattern, or approach chosen over alternatives), when ADR/RFC documents are found in a repository, when asked what's already been decided about a topic, or when a new decision replaces an older one. Requires the Nexarch MCP tools (nexarch_*).
+description: Record an architectural decision in Nexarch, or check what's already been decided about something. Use when a decision crosses a boundary between applications, services or teams, changes an integration, data ownership, security or deployment, adopts a technology others depend on, or is expensive to reverse; when ADR/RFC documents are found in a repository; when asked what's already been decided about a topic; or when a new decision replaces an older one. Not for design decisions inside one application. Requires the Nexarch MCP tools (nexarch_*).
 ---
 
 # Nexarch Decision Records
@@ -252,6 +252,23 @@ skill is for recording one as it happens — mining a whole repository's ADR
 history systematically is a separate, human-triggered Decision Review
 command from the application's page in the workspace.
 
+## Architectural, not design
+
+Record only architectural decisions. A decision is architectural when it does
+at least one of these:
+
+- crosses a boundary between applications, services or teams
+- changes an integration, data ownership, security or authentication, or how
+  the system is deployed
+- adopts, replaces or retires a technology that other systems or teams depend on
+- is expensive to reverse once other work builds on it
+
+Anything else is a design decision — screen layouts, interaction patterns,
+component library choices, internal module structure, naming. It belongs in
+the repository's design documentation, not in the graph. When unsure, ask:
+if this decision changed, would another team or system have to change too? If
+not, do not record it, even when it is written up as an ADR.
+
 ## Before recording
 
 \`nexarch_resolve_reference\` / \`nexarch_list_entities\` for an existing

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "nexarch",
-  "version": "0.13.3",
-  "description": "Your architecture workspace for AI delivery.",
-  "keywords": [
-    "nexarch",
-    "mcp",
-    "architecture",
-    "ai"
-  ],
-  "license": "MIT",
-  "author": "Nexarch <hello@nexarch.ai>",
-  "homepage": "https://nexarch.ai",
-  "engines": {
-    "node": ">=18"
-  },
-  "type": "module",
-  "bin": {
-    "nexarch": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "tsc",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "tsx": "^4",
-    "typescript": "^5"
-  },
-  "dependencies": {
-    "yaml": "^2.9.0"
-  }
-}
+{
+  "name": "nexarch",
+  "version": "0.13.5",
+  "description": "Your architecture workspace for AI delivery.",
+  "keywords": [
+    "nexarch",
+    "mcp",
+    "architecture",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Nexarch <hello@nexarch.ai>",
+  "homepage": "https://nexarch.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "bin": {
+    "nexarch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts && tsx scripts/test-search-icons.ts && tsx scripts/test-paste-login.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}