nexarch 0.1.17 → 0.1.19

package/dist/commands/init-agent.js

@@ -4,7 +4,7 @@ import { join } from "path";
 import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
-const CLI_VERSION = "0.1.17";
+const CLI_VERSION = "0.1.19";
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {

package/dist/commands/init-project.js

@@ -24,6 +24,8 @@ function slugify(name) {
     return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
 // ─── Project scanning ─────────────────────────────────────────────────────────
+// Noise patterns for env var keys that are internal config, not external service references
+const ENV_KEY_NOISE = /^(NODE_ENV|PORT|HOST|DEBUG|LOG_LEVEL|TZ|LANG|PATH|HOME|USER|SHELL|TERM)$|(_LOG_LEVEL|_MAX_|_MIN_|_DEFAULT_|_TIMEOUT|_DELAY|_JOBS|_INTERVAL|_LIMIT|_RETRIES|_CONCURREN|_WORKERS)$|^NEXT_PUBLIC_(APP|ADMIN|API|SITE|BASE|WEB)_URL$/;
 function parseEnvKeys(content) {
     return content
         .split("\n")
@@ -31,7 +33,8 @@ function parseEnvKeys(content) {
         .filter((line) => line && !line.startsWith("#"))
         .map((line) => line.replace(/^export\s+/, ""))
         .map((line) => line.split("=")[0].trim())
-        .filter((key) => /^[A-Z][A-Z0-9_]{2,}$/.test(key)); // min 3 chars, all caps
+        .filter((key) => /^[A-Z][A-Z0-9_]{2,}$/.test(key))
+        .filter((key) => !ENV_KEY_NOISE.test(key));
 }
 function detectFromGitConfig(dir) {
     const configPath = join(dir, ".git", "config");
@@ -90,6 +93,7 @@ function detectFromFilesystem(dir) {
         detected.push("pulumi");
     return detected;
 }
+const SKIP_DIRS = new Set(["node_modules", "dist", ".next", ".turbo", "build", "coverage", ".git"]);
 function collectPackageDeps(pkgPath) {
     try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
@@ -103,50 +107,125 @@ function collectPackageDeps(pkgPath) {
         return [];
     }
 }
-function readProjectName(pkgPath) {
+function readRootPackage(pkgPath) {
     try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        return typeof pkg.name === "string" ? pkg.name : null;
+        return JSON.parse(readFileSync(pkgPath, "utf8"));
     }
     catch {
-        return null;
+        return {};
     }
 }
-function scanProject(dir) {
-    const names = new Set();
-    let projectName = basename(dir);
-    let packageJsonCount = 0;
-    // Root package.json
-    const rootPkgPath = join(dir, "package.json");
-    if (existsSync(rootPkgPath)) {
-        packageJsonCount++;
-        const rootName = readProjectName(rootPkgPath);
-        if (rootName)
-            projectName = rootName;
-        for (const dep of collectPackageDeps(rootPkgPath))
-            names.add(dep);
-    }
-    // One level of subdirectories (monorepo packages)
-    try {
-        for (const entry of readdirSync(dir)) {
-            if (entry.startsWith(".") || entry === "node_modules" || entry === "dist")
-                continue;
-            const entryPath = join(dir, entry);
+// Resolve workspace glob patterns (e.g. "apps/*", "packages/*") to actual directories.
+// Handles the common case of a single wildcard — no full glob library needed.
+function resolveWorkspaceDirs(rootDir, workspaces) {
+    const patterns = Array.isArray(workspaces) ? workspaces : (workspaces.packages ?? []);
+    const dirs = [];
+    for (const pattern of patterns) {
+        if (pattern.endsWith("/*")) {
+            const parent = join(rootDir, pattern.slice(0, -2));
             try {
-                if (!statSync(entryPath).isDirectory())
-                    continue;
-                const subPkgPath = join(entryPath, "package.json");
-                if (existsSync(subPkgPath)) {
-                    packageJsonCount++;
-                    for (const dep of collectPackageDeps(subPkgPath))
-                        names.add(dep);
+                for (const entry of readdirSync(parent)) {
+                    if (SKIP_DIRS.has(entry))
+                        continue;
+                    const full = join(parent, entry);
+                    try {
+                        if (statSync(full).isDirectory())
+                            dirs.push(full);
+                    }
+                    catch { }
                 }
             }
             catch { }
         }
+        else {
+            // Exact path
+            const full = join(rootDir, pattern);
+            try {
+                if (statSync(full).isDirectory())
+                    dirs.push(full);
+            }
+            catch { }
+        }
     }
-    catch { }
-    // .env files
+    return dirs;
+}
+// Collect all package.json paths: root + workspace packages + 2-level fallback
+function findPackageJsonPaths(rootDir) {
+    const paths = [];
+    const rootPkgPath = join(rootDir, "package.json");
+    if (!existsSync(rootPkgPath))
+        return paths;
+    paths.push(rootPkgPath);
+    const rootPkg = readRootPackage(rootPkgPath);
+    if (rootPkg.workspaces) {
+        // Workspace monorepo: resolve workspace dirs and find their package.json files
+        for (const wsDir of resolveWorkspaceDirs(rootDir, rootPkg.workspaces)) {
+            const pkgPath = join(wsDir, "package.json");
+            if (existsSync(pkgPath))
+                paths.push(pkgPath);
+        }
+    }
+    else {
+        // Non-workspace: scan up to 2 levels deep
+        try {
+            for (const l1 of readdirSync(rootDir)) {
+                if (SKIP_DIRS.has(l1) || l1.startsWith("."))
+                    continue;
+                const l1Path = join(rootDir, l1);
+                try {
+                    if (!statSync(l1Path).isDirectory())
+                        continue;
+                    const l1Pkg = join(l1Path, "package.json");
+                    if (existsSync(l1Pkg)) {
+                        paths.push(l1Pkg);
+                        continue;
+                    }
+                    for (const l2 of readdirSync(l1Path)) {
+                        if (SKIP_DIRS.has(l2) || l2.startsWith("."))
+                            continue;
+                        const l2Path = join(l1Path, l2);
+                        try {
+                            if (!statSync(l2Path).isDirectory())
+                                continue;
+                            const l2Pkg = join(l2Path, "package.json");
+                            if (existsSync(l2Pkg))
+                                paths.push(l2Pkg);
+                        }
+                        catch { }
+                    }
+                }
+                catch { }
+            }
+        }
+        catch { }
+    }
+    return paths;
+}
+function scanProject(dir) {
+    const names = new Set();
+    let projectName = basename(dir);
+    const subPackages = [];
+    const pkgPaths = findPackageJsonPaths(dir);
+    const rootPkgPath = join(dir, "package.json");
+    for (const pkgPath of pkgPaths) {
+        const pkg = readRootPackage(pkgPath);
+        if (pkgPath === rootPkgPath) {
+            if (pkg.name)
+                projectName = pkg.name;
+        }
+        else {
+            // Record as a sub-package for enrichment task
+            const relativePath = pkgPath.replace(dir + "/", "").replace("/package.json", "");
+            subPackages.push({
+                name: pkg.name ?? relativePath,
+                relativePath,
+                packageJsonPath: pkgPath,
+            });
+        }
+        for (const dep of collectPackageDeps(pkgPath))
+            names.add(dep);
+    }
+    // .env files at root
     for (const envFile of [".env", ".env.example", ".env.local", ".env.runtime"]) {
         const envPath = join(dir, envFile);
         if (existsSync(envPath)) {
@@ -162,7 +241,7 @@ function scanProject(dir) {
         names.add(name);
     for (const name of detectFromFilesystem(dir))
         names.add(name);
-    return { projectName, packageJsonCount, detectedNames: Array.from(names) };
+    return { projectName, packageJsonCount: pkgPaths.length, detectedNames: Array.from(names), subPackages };
 }
 // ─── Relationship type selection ──────────────────────────────────────────────
 function pickRelationshipType(entityTypeCode) {
@@ -189,7 +268,7 @@ export async function initProject(args) {
     const mcpOpts = { companyId: creds.companyId };
     if (!asJson)
         console.log(`Scanning ${dir}…`);
-    const { projectName, packageJsonCount, detectedNames } = scanProject(dir);
+    const { projectName, packageJsonCount, detectedNames, subPackages } = scanProject(dir);
     const displayName = nameOverride ?? projectName;
     const projectSlug = slugify(displayName);
     const projectExternalKey = `${entityTypeOverride}:${projectSlug}`;
@@ -261,7 +340,6 @@ export async function initProject(args) {
         entityTypeCode: entityTypeOverride,
         ...(projectSubtype ? { entitySubtypeCode: projectSubtype } : {}),
         name: displayName,
-        description: `Project initialised from ${dir}`,
         confidence: 1,
         attributes: { source_dir: dir, scanned_at: nowIso, package_json_count: packageJsonCount },
     });
@@ -338,4 +416,58 @@ export async function initProject(args) {
             console.log(`  ${err.externalKey}: ${err.error} — ${err.message}`);
         }
     }
+    // ─── Enrichment task ────────────────────────────────────────────────────────
+    const readmeHints = ["README.md", "README.mdx", "docs/README.md", "docs/index.md"]
+        .filter((f) => existsSync(join(dir, f)));
+    console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  ENRICHMENT TASK — action required                               ║
+╚══════════════════════════════════════════════════════════════════╝
+
+The mechanical scan has written a skeleton graph entry for this project.
+You now need to enrich it with meaningful content.
+
+PROJECT ENTITY  : ${projectExternalKey}
+PROJECT DIR     : ${dir}
+${readmeHints.length > 0 ? `README FILES    : ${readmeHints.join(", ")}` : "README FILES    : (none found — check docs/)"}
+
+STEP 1 — Read the project README / docs and build your understanding of:
+  • What does this project do? (business purpose, key features)
+  • Who are the users?
+  • What is the high-level architecture?
+  • Any notable technical decisions or constraints?
+
+STEP 2 — Enrich the project entity. Run this command with the description you've written:
+
+  npx nexarch update-entity \\
+    --key "${projectExternalKey}" \\
+    --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' \\\n    --subtype "app_custom_built"' : ""} \\
+    --name "<proper product name from README>" \\
+    --description "<2–4 sentence summary of what it does and why>"
+${subPackages.length > 0 ? `
+STEP 3 — Register each sub-application as its own entity.
+  The scanner found ${subPackages.length} workspace package(s). For each one, read its
+  README / package.json description, then run:
+
+  Sub-packages detected:
+${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")}
+
+  For each sub-package run:
+
+  npx nexarch update-entity \\
+    --key "application:<slugified-package-name>" \\
+    --entity-type "application" \\
+    --subtype "app_custom_built" \\
+    --name "<sub-app name>" \\
+    --description "<what this sub-app does>"
+
+  Then wire it to the parent project:
+
+  npx nexarch add-relationship \\
+    --from "application:<slugified-package-name>" \\
+    --to "${projectExternalKey}" \\
+    --type "part_of"
+
+  (Note: add-relationship is coming soon — skip if not yet available)
+` : ""}`);
 }

package/dist/commands/update-entity.js

@@ -0,0 +1,84 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+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;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function updateEntity(args) {
+    const asJson = parseFlag(args, "--json");
+    const externalKey = parseOptionValue(args, "--key");
+    const name = parseOptionValue(args, "--name");
+    const description = parseOptionValue(args, "--description");
+    const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
+    const entitySubtypeCode = parseOptionValue(args, "--subtype");
+    if (!externalKey) {
+        console.error("error: --key <externalKey> is required");
+        process.exit(1);
+    }
+    if (!name && !description) {
+        console.error("error: at least one of --name or --description is required");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const mcpOpts = { companyId: creds.companyId };
+    const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {}, mcpOpts);
+    const policies = parseToolText(policiesRaw);
+    const policyBundleHash = policies.policyBundleHash ?? null;
+    const nowIso = new Date().toISOString();
+    const agentContext = {
+        agentId: "nexarch-cli:update-entity",
+        agentRunId: `update-entity-${Date.now()}`,
+        observedAt: nowIso,
+        source: "nexarch-cli",
+        model: "n/a",
+        provider: "n/a",
+    };
+    const policyContext = policyBundleHash
+        ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
+        : undefined;
+    const entity = {
+        externalKey,
+        entityTypeCode,
+        confidence: 1,
+    };
+    if (name)
+        entity.name = name;
+    if (description)
+        entity.description = description;
+    if (entitySubtypeCode)
+        entity.entitySubtypeCode = entitySubtypeCode;
+    const raw = await callMcpTool("nexarch_upsert_entities", { entities: [entity], agentContext, policyContext }, mcpOpts);
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (Number(result.summary?.failed ?? 0) > 0)
+            process.exitCode = 1;
+        return;
+    }
+    const succeeded = result.summary?.succeeded ?? 0;
+    const failed = result.summary?.failed ?? 0;
+    if (failed > 0) {
+        console.error(`Failed to update entity: ${externalKey}`);
+        for (const err of result.errors ?? []) {
+            console.error(`  ${err.externalKey}: ${err.error} — ${err.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (!asJson) {
+        console.log(`Updated ${succeeded} entity: ${externalKey}`);
+    }
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { mcpProxy } from "./commands/mcp-proxy.js";
 import { initAgent } from "./commands/init-agent.js";
 import { agentIdentify } from "./commands/agent-identify.js";
 import { initProject } from "./commands/init-project.js";
+import { updateEntity } from "./commands/update-entity.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -22,6 +23,7 @@ const commands = {
     "init-agent": initAgent,
     "agent-identify": agentIdentify,
     "init-project": initProject,
+    "update-entity": updateEntity,
 };
 async function main() {
     if (command === "agent") {
@@ -78,9 +80,19 @@ Usage:
                       names as reference candidates.
                       Options: --dir <path>  (default: cwd)
                                --name <name>  override project name
-                               --entity-type <code>  (default: service)
+                               --entity-type <code>  (default: application)
                                --dry-run  preview without writing
                                --json
+  nexarch update-entity
+                      Update the name and/or description of an existing graph entity.
+                      Use this after init-project to enrich the entity with meaningful
+                      content from the project README or docs.
+                      Options: --key <externalKey>  (required)
+                               --name <name>
+                               --description <text>
+                               --entity-type <code>  (default: application)
+                               --subtype <code>
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Connect AI coding tools to your Nexarch architecture workspace",
   "keywords": [
     "nexarch",