nexarch 0.1.13 → 0.1.16

package/dist/commands/agent-identify.js

@@ -48,7 +48,7 @@ export async function agentIdentify(args) {
     await mcpInitialize({ companyId: creds.companyId });
     const tools = await mcpListTools({ companyId: creds.companyId });
     const toolNames = new Set(tools.map((t) => t.name));
-    const required = ["nexarch_upsert_entities"];
+    const required = ["nexarch_upsert_entities", "nexarch_upsert_relationships"];
     const missing = required.filter((name) => !toolNames.has(name));
     if (missing.length) {
         throw new Error(`missing required MCP tools: ${missing.join(", ")}`);
@@ -112,6 +112,93 @@ export async function agentIdentify(args) {
     const upsert = parseToolText(upsertRaw);
     const failed = Number(upsert.summary?.failed ?? 0) > 0;
     const firstResult = upsert.results?.[0];
+    // Upsert provider, model, and client as first-class graph entities
+    const providerExternalKey = `org:provider:${provider.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
+    const modelExternalKey = `model:${model.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
+    const clientExternalKey = `tool:client:${client.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
+    const agentExternalKey = `agent:${agentId}`;
+    await callMcpTool("nexarch_upsert_entities", {
+        entities: [
+            {
+                externalKey: providerExternalKey,
+                entityTypeCode: "organisation",
+                entitySubtypeCode: "org_partner",
+                name: provider,
+                description: `AI provider: ${provider}`,
+                confidence: 1,
+            },
+            {
+                externalKey: modelExternalKey,
+                entityTypeCode: "model",
+                entitySubtypeCode: "model_llm",
+                name: model,
+                description: `Large language model: ${model}`,
+                confidence: 1,
+            },
+            {
+                externalKey: clientExternalKey,
+                entityTypeCode: "tool",
+                name: client,
+                description: `AI agent client: ${client}`,
+                confidence: 1,
+            },
+        ],
+        agentContext: {
+            agentId,
+            agentRunId: `agent-identify-entities-${Date.now()}`,
+            repoRef: "nexarch-cli/agent-identify",
+            observedAt: nowIso,
+            source: "nexarch-cli",
+            model,
+            provider,
+        },
+        policyContext: policyBundleHash
+            ? {
+                policyBundleHash,
+                alignmentSummary: { score: 1, violations: [], waivers: [] },
+            }
+            : undefined,
+        dryRun: false,
+    }, { companyId: creds.companyId });
+    // Wire relationships: uses_model, uses, accountable_for
+    await callMcpTool("nexarch_upsert_relationships", {
+        relationships: [
+            {
+                relationshipTypeCode: "uses_model",
+                fromEntityExternalKey: agentExternalKey,
+                toEntityExternalKey: modelExternalKey,
+                confidence: 1,
+            },
+            {
+                relationshipTypeCode: "uses",
+                fromEntityExternalKey: agentExternalKey,
+                toEntityExternalKey: clientExternalKey,
+                confidence: 1,
+            },
+            {
+                relationshipTypeCode: "accountable_for",
+                fromEntityExternalKey: providerExternalKey,
+                toEntityExternalKey: agentExternalKey,
+                confidence: 1,
+            },
+        ],
+        agentContext: {
+            agentId,
+            agentRunId: `agent-identify-rels-${Date.now()}`,
+            repoRef: "nexarch-cli/agent-identify",
+            observedAt: nowIso,
+            source: "nexarch-cli",
+            model,
+            provider,
+        },
+        policyContext: policyBundleHash
+            ? {
+                policyBundleHash,
+                alignmentSummary: { score: 1, violations: [], waivers: [] },
+            }
+            : undefined,
+        dryRun: false,
+    }, { companyId: creds.companyId });
     const output = {
         ok: !failed,
         detail: failed ? `failed (${upsert.errors?.[0]?.error ?? "unknown"})` : `agent ${firstResult?.action ?? "updated"}`,

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.13";
+const CLI_VERSION = "0.1.16";
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
 function parseFlag(args, flag) {

package/dist/commands/init-project.js

@@ -0,0 +1,339 @@
+import process from "process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, resolve as resolvePath } from "node:path";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+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);
+}
+function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+// ─── Project scanning ─────────────────────────────────────────────────────────
+function parseEnvKeys(content) {
+    return content
+        .split("\n")
+        .map((line) => line.trim())
+        .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
+}
+function detectFromGitConfig(dir) {
+    const configPath = join(dir, ".git", "config");
+    if (!existsSync(configPath))
+        return [];
+    try {
+        const content = readFileSync(configPath, "utf8");
+        // Match url under [remote "origin"]
+        const match = content.match(/\[remote\s+"origin"\][^\[]*url\s*=\s*([^\n]+)/s);
+        if (!match)
+            return [];
+        const url = match[1].trim();
+        if (url.includes("github.com"))
+            return ["github"];
+        if (url.includes("gitlab.com"))
+            return ["gitlab"];
+        if (url.includes("bitbucket.org"))
+            return ["bitbucket"];
+        if (url.includes("dev.azure.com") || url.includes("visualstudio.com"))
+            return ["azure-devops"];
+    }
+    catch { }
+    return [];
+}
+function detectFromFilesystem(dir) {
+    const detected = [];
+    // CI/CD
+    if (existsSync(join(dir, ".github", "workflows")))
+        detected.push("github-actions");
+    if (existsSync(join(dir, ".gitlab-ci.yml")))
+        detected.push("gitlab");
+    if (existsSync(join(dir, "Jenkinsfile")))
+        detected.push("jenkins");
+    if (existsSync(join(dir, ".circleci", "config.yml")))
+        detected.push("circleci");
+    // Deployment / hosting
+    if (existsSync(join(dir, "vercel.json")) || existsSync(join(dir, ".vercel")))
+        detected.push("vercel");
+    if (existsSync(join(dir, "netlify.toml")))
+        detected.push("netlify");
+    if (existsSync(join(dir, "fly.toml")))
+        detected.push("fly");
+    if (existsSync(join(dir, "railway.json")) || existsSync(join(dir, "railway.toml")))
+        detected.push("railway");
+    if (existsSync(join(dir, "render.yaml")))
+        detected.push("render");
+    // Containers
+    if (existsSync(join(dir, "Dockerfile")))
+        detected.push("docker");
+    if (existsSync(join(dir, "docker-compose.yml")) || existsSync(join(dir, "docker-compose.yaml")))
+        detected.push("docker");
+    // Infrastructure
+    if (existsSync(join(dir, "terraform")) || existsSync(join(dir, "main.tf")))
+        detected.push("terraform");
+    if (existsSync(join(dir, "pulumi.yaml")))
+        detected.push("pulumi");
+    return detected;
+}
+function collectPackageDeps(pkgPath) {
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return Object.keys({
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+            ...pkg.peerDependencies,
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function readProjectName(pkgPath) {
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return typeof pkg.name === "string" ? pkg.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+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);
+            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);
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    // .env files
+    for (const envFile of [".env", ".env.example", ".env.local", ".env.runtime"]) {
+        const envPath = join(dir, envFile);
+        if (existsSync(envPath)) {
+            try {
+                for (const key of parseEnvKeys(readFileSync(envPath, "utf8")))
+                    names.add(key);
+            }
+            catch { }
+        }
+    }
+    // Git remote, CI/CD, deployment config
+    for (const name of detectFromGitConfig(dir))
+        names.add(name);
+    for (const name of detectFromFilesystem(dir))
+        names.add(name);
+    return { projectName, packageJsonCount, detectedNames: Array.from(names) };
+}
+// ─── Relationship type selection ──────────────────────────────────────────────
+function pickRelationshipType(entityTypeCode) {
+    switch (entityTypeCode) {
+        case "model":
+            return "uses_model";
+        case "platform":
+        case "platform_component":
+        case "skill":
+            return "uses";
+        default:
+            return "depends_on";
+    }
+}
+// ─── Main command ─────────────────────────────────────────────────────────────
+export async function initProject(args) {
+    const asJson = parseFlag(args, "--json");
+    const dryRun = parseFlag(args, "--dry-run");
+    const dirArg = parseOptionValue(args, "--dir") ?? process.cwd();
+    const dir = resolvePath(dirArg);
+    const nameOverride = parseOptionValue(args, "--name");
+    const entityTypeOverride = parseOptionValue(args, "--entity-type") ?? "service";
+    const creds = requireCredentials();
+    const mcpOpts = { companyId: creds.companyId };
+    if (!asJson)
+        console.log(`Scanning ${dir}…`);
+    const { projectName, packageJsonCount, detectedNames } = scanProject(dir);
+    const displayName = nameOverride ?? projectName;
+    const projectSlug = slugify(displayName);
+    const projectExternalKey = `${entityTypeOverride}:${projectSlug}`;
+    if (!asJson) {
+        console.log(`  Project : ${displayName} (${entityTypeOverride})`);
+        console.log(`  Packages: ${packageJsonCount} package.json file(s)`);
+        console.log(`  Detected: ${detectedNames.length} raw names`);
+    }
+    if (detectedNames.length === 0) {
+        if (!asJson)
+            console.log("Nothing detected — is this a supported project type?");
+        return;
+    }
+    // Resolve all detected names against the reference library
+    if (!asJson)
+        console.log("\nResolving against reference library…");
+    const allResolveResults = [];
+    const BATCH_SIZE = 200;
+    for (let i = 0; i < detectedNames.length; i += BATCH_SIZE) {
+        const batch = detectedNames.slice(i, i + BATCH_SIZE);
+        const raw = await callMcpTool("nexarch_resolve_reference", { names: batch, companyId: creds.companyId }, mcpOpts);
+        const data = parseToolText(raw);
+        allResolveResults.push(...data.results);
+    }
+    const resolvedItems = allResolveResults.filter((r) => r.resolved);
+    const unresolvedItems = allResolveResults.filter((r) => !r.resolved);
+    if (!asJson) {
+        console.log(`  Resolved  : ${resolvedItems.length}/${detectedNames.length}`);
+        console.log(`  Candidates: ${unresolvedItems.length} unresolved (logged to reference candidates)`);
+    }
+    if (dryRun) {
+        const output = {
+            dryRun: true,
+            project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride },
+            resolved: resolvedItems.map((r) => ({
+                input: r.input,
+                canonicalName: r.canonicalName,
+                entityTypeCode: r.entityTypeCode,
+                externalRef: r.canonicalExternalRef,
+            })),
+            unresolved: unresolvedItems.map((r) => r.input),
+        };
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        return;
+    }
+    // Policy bootstrap
+    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:init-project",
+        agentRunId: `init-project-${Date.now()}`,
+        repoRef: dir,
+        observedAt: nowIso,
+        source: "nexarch-cli",
+        model: "n/a",
+        provider: "n/a",
+    };
+    const policyContext = policyBundleHash
+        ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
+        : undefined;
+    // Build entity list — project entity + all resolved reference entities
+    const entities = [];
+    // The project itself
+    entities.push({
+        externalKey: projectExternalKey,
+        entityTypeCode: entityTypeOverride,
+        name: displayName,
+        description: `Project initialised from ${dir}`,
+        confidence: 1,
+        attributes: { source_dir: dir, scanned_at: nowIso, package_json_count: packageJsonCount },
+    });
+    // Resolved reference entities (deduplicated by canonical external ref)
+    const seenRefs = new Set();
+    for (const r of resolvedItems) {
+        if (!r.canonicalExternalRef || seenRefs.has(r.canonicalExternalRef))
+            continue;
+        seenRefs.add(r.canonicalExternalRef);
+        entities.push({
+            externalKey: r.canonicalExternalRef,
+            entityTypeCode: r.entityTypeCode,
+            ...(r.entitySubtypeCode ? { entitySubtypeCode: r.entitySubtypeCode } : {}),
+            name: r.canonicalName,
+            ...(r.description ? { description: r.description } : {}),
+            confidence: 0.95,
+        });
+    }
+    // Build relationships from project entity to each resolved dependency
+    const relationships = [];
+    const seenRelPairs = new Set();
+    for (const r of resolvedItems) {
+        if (!r.canonicalExternalRef || !r.entityTypeCode)
+            continue;
+        const relType = pickRelationshipType(r.entityTypeCode);
+        const pairKey = `${relType}::${projectExternalKey}::${r.canonicalExternalRef}`;
+        if (seenRelPairs.has(pairKey))
+            continue;
+        seenRelPairs.add(pairKey);
+        relationships.push({
+            relationshipTypeCode: relType,
+            fromEntityExternalKey: projectExternalKey,
+            toEntityExternalKey: r.canonicalExternalRef,
+            confidence: 0.9,
+        });
+    }
+    if (!asJson)
+        console.log(`\nWriting to graph…`);
+    // Upsert entities
+    const entitiesRaw = await callMcpTool("nexarch_upsert_entities", { entities, agentContext, policyContext }, mcpOpts);
+    const entitiesResult = parseToolText(entitiesRaw);
+    // Upsert relationships
+    let relsResult = null;
+    if (relationships.length > 0) {
+        const relsRaw = await callMcpTool("nexarch_upsert_relationships", { relationships, agentContext, policyContext }, mcpOpts);
+        relsResult = parseToolText(relsRaw);
+    }
+    const output = {
+        ok: Number(entitiesResult.summary?.failed ?? 0) === 0,
+        project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride },
+        entities: entitiesResult.summary ?? {},
+        relationships: relsResult?.summary ?? { requested: 0, succeeded: 0, failed: 0 },
+        resolved: resolvedItems.length,
+        unresolved: unresolvedItems.length,
+        unresolvedSample: unresolvedItems.slice(0, 10).map((r) => r.input),
+        entityErrors: entitiesResult.errors ?? [],
+        relationshipErrors: relsResult?.errors ?? [],
+    };
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+        if (!output.ok)
+            process.exitCode = 1;
+        return;
+    }
+    console.log(`\nDone.`);
+    console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${output.entities.failed ?? 0} failed`);
+    console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
+    if (unresolvedItems.length > 0) {
+        console.log(`  Candidates   : ${unresolvedItems.length} added to reference candidates`);
+    }
+    if (output.entityErrors.length > 0) {
+        console.log("\nEntity errors:");
+        for (const err of output.entityErrors) {
+            console.log(`  ${err.externalKey}: ${err.error} — ${err.message}`);
+        }
+    }
+}

package/dist/index.js

@@ -10,6 +10,7 @@ import { mcpConfig } from "./commands/mcp-config.js";
 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";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -20,6 +21,7 @@ const commands = {
     "mcp-proxy": mcpProxy,
     "init-agent": initAgent,
     "agent-identify": agentIdentify,
+    "init-project": initProject,
 };
 async function main() {
     if (command === "agent") {
@@ -69,6 +71,16 @@ Usage:
                                [--notes <text>] [--json]
   nexarch agent-identify
                       Alias of 'nexarch agent identify'
+  nexarch init-project
+                      Scan a project directory, resolve detected packages/env vars/
+                      config files against the reference library, write entities and
+                      relationships to the architecture graph, and log unresolved
+                      names as reference candidates.
+                      Options: --dir <path>  (default: cwd)
+                               --name <name>  override project name
+                               --entity-type <code>  (default: service)
+                               --dry-run  preview without writing
+                               --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

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