nexarch 0.8.27 → 0.9.1

package/dist/commands/check-in.js

@@ -34,7 +34,7 @@ function loadIdentity() {
 }
 export async function checkIn(args) {
     const asJson = parseFlag(args, "--json");
-    const agentKeyArg = parseOptionValue(args, "--agent-key");
+    const agentKeyArg = parseOptionValue(args, "--agent-ref") ?? parseOptionValue(args, "--agent-key");
     const creds = requireCredentials();
     const identity = loadIdentity();
     const agentKey = agentKeyArg ?? identity.agentKey;
@@ -48,6 +48,7 @@ export async function checkIn(args) {
         return;
     }
     const raw = await callMcpTool("nexarch_claim_command", {
+        agentRef: agentKey,
         agentKey,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });

package/dist/commands/command-claim.js

@@ -35,7 +35,7 @@ function loadIdentity() {
 export async function commandClaim(args) {
     const asJson = parseFlag(args, "--json");
     const id = parseOptionValue(args, "--id");
-    const agentKeyArg = parseOptionValue(args, "--agent-key");
+    const agentKeyArg = parseOptionValue(args, "--agent-ref") ?? parseOptionValue(args, "--agent-key");
     if (!id) {
         console.error("error: --id <commandId> is required");
         process.exit(1);
@@ -49,6 +49,7 @@ export async function commandClaim(args) {
     }
     const raw = await callMcpTool("nexarch_claim_command_by_id", {
         commandId: id,
+        agentRef: agentKey,
         agentKey,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });

package/dist/commands/init-agent.js

@@ -76,10 +76,16 @@ function renderChecksTable(checks) {
     const lines = [hr, formatRow(headers), hr, ...rows.map(formatRow), hr];
     return lines.join("\n");
 }
+function normalizeRefSegment(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function buildEntityRef(entityTypeCode, ...segments) {
+    return [normalizeRefSegment(entityTypeCode), ...segments.map(normalizeRefSegment).filter(Boolean)].join(":");
+}
 function getDefaultAgentId() {
     const osUser = process.env.USERNAME || process.env.USER || userInfo().username || "unknown";
     const host = hostname() || "unknown-host";
-    return `nexarch-cli:${osUser}@${host}`;
+    return `nexarch_cli_${normalizeRefSegment(osUser)}_${normalizeRefSegment(host)}`;
 }
 function getRuntimeMode() {
     if (process.env.CI)
@@ -519,6 +525,7 @@ export async function initAgent(args) {
     const capabilitiesArg = parseCsv(parseOptionValue(args, "--capabilities"));
     const notesArg = parseOptionValue(args, "--notes");
     const agentId = explicitAgentId ?? getDefaultAgentId();
+    const agentExternalKey = buildEntityRef("agent", agentId);
     const runtime = {
         osPlatform: platform(),
         osType: osType(),
@@ -635,7 +642,6 @@ export async function initAgent(args) {
     if (preflightPassed && policies.policyBundleHash && relForTechBinding) {
         const nowIso = new Date().toISOString();
         const agentRunId = `init-agent-${Date.now()}`;
-        const agentExternalKey = `agent:${agentId}`;
         const upsertRaw = await callMcpTool("nexarch_upsert_entities", {
             entities: [
                 {
@@ -713,9 +719,9 @@ export async function initAgent(args) {
         }
         if (registration.ok) {
             techComponents.attempted = true;
-            const hostExternalKey = `tech:host:${runtime.hostname}:${runtime.arch}`;
-            const osExternalKey = `tech:os:${runtime.osPlatform}:${runtime.osRelease}:${runtime.arch}`;
-            const nodeExternalKey = `tech:runtime:nodejs:${runtime.nodeVersion}`;
+            const hostExternalKey = buildEntityRef("technology_component", "host", runtime.hostname, runtime.arch);
+            const osExternalKey = buildEntityRef("technology_component", "os", runtime.osPlatform, runtime.osRelease, runtime.arch);
+            const nodeExternalKey = buildEntityRef("technology_component", "runtime", "nodejs", runtime.nodeVersion);
             const techUpsertRaw = await callMcpTool("nexarch_upsert_entities", {
                 entities: [
                     {
@@ -886,7 +892,7 @@ export async function initAgent(args) {
                         relationships: [
                             {
                                 relationshipTypeCode: "accountable_for",
-                                fromEntityExternalKey: `org:${creds.companyId}`,
+                                fromEntityExternalKey: buildEntityRef("organisation", creds.companyId),
                                 toEntityExternalKey: agentExternalKey,
                                 confidence: 1,
                                 attributes: { source: "nexarch-cli-init-agent", kind: "org_agent", createdAt: nowIso },
@@ -1065,7 +1071,7 @@ export async function initAgent(args) {
             // Save identity so check-in can find the agent key
             const identityDir = join(homedir(), ".nexarch");
             mkdirSync(identityDir, { recursive: true });
-            writeFileSync(join(identityDir, "identity.json"), JSON.stringify({ agentKey: `agent:${agentId}`, companyId: creds.companyId }, null, 2), { mode: 0o600 });
+            writeFileSync(join(identityDir, "identity.json"), JSON.stringify({ agentKey: agentExternalKey, companyId: creds.companyId }, null, 2), { mode: 0o600 });
         }
         catch {
             // non-fatal

package/dist/commands/init-project.js

@@ -1,4 +1,5 @@
 import process from "process";
+import * as readline from "node:readline/promises";
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, join, relative, resolve as resolvePath } from "node:path";
@@ -23,7 +24,7 @@ function parseToolText(result) {
     return JSON.parse(text);
 }
 function slugify(name) {
-    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
 }
 function safeExec(command, args, cwd) {
     try {
@@ -89,14 +90,14 @@ function inferProvider(ref) {
 }
 function providerCanonicalRepoRef(provider) {
     switch (provider) {
-        case "github": return "global:repo:github";
-        case "gitlab": return "global:repo:gitlab";
-        case "bitbucket": return "global:repo:bitbucket";
-        case "azure-repos": return "global:repo:azure-repos";
-        case "codecommit": return "global:repo:codecommit";
-        case "gitea": return "global:repo:gitea";
-        case "forgejo": return "global:repo:forgejo";
-        case "sourcehut": return "global:repo:sourcehut";
+        case "github": return "global:technology_component:github";
+        case "gitlab": return "global:technology_component:gitlab";
+        case "bitbucket": return "global:technology_component:bitbucket";
+        case "azure-repos": return "global:technology_component:azure_repos";
+        case "codecommit": return "global:technology_component:codecommit";
+        case "gitea": return "global:technology_component:gitea";
+        case "forgejo": return "global:technology_component:forgejo";
+        case "sourcehut": return "global:technology_component:sourcehut";
         default: return null;
     }
 }
@@ -864,6 +865,88 @@ function pickRelationshipType(toEntityTypeCode, _fromEntityTypeCode = "applicati
             return "depends_on";
     }
 }
+function normalizeToken(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function extractHost(input) {
+    if (!input)
+        return null;
+    try {
+        return new URL(input).hostname.replace(/^www\./, "").toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function scoreApplicationCandidate(app, projectName, repoUrl) {
+    const entityRef = app.entityRef ?? app.externalKey ?? null;
+    if (!entityRef)
+        return null;
+    let score = 0;
+    const reasons = [];
+    const appNameNorm = normalizeToken(app.name);
+    const projectNorm = normalizeToken(projectName);
+    const refNorm = normalizeToken(entityRef);
+    if (appNameNorm === projectNorm) {
+        score += 0.45;
+        reasons.push("name_exact");
+    }
+    else if (appNameNorm.includes(projectNorm) || projectNorm.includes(appNameNorm)) {
+        score += 0.25;
+        reasons.push("name_partial");
+    }
+    if (refNorm.includes(projectNorm)) {
+        score += 0.25;
+        reasons.push("ref_matches_project");
+    }
+    const repoHost = extractHost(repoUrl);
+    const appWebsite = typeof app.attributes?.website_url === "string" ? app.attributes.website_url : null;
+    const appWebsiteHost = extractHost(appWebsite);
+    if (repoHost && appWebsiteHost && repoHost === appWebsiteHost) {
+        score += 0.5;
+        reasons.push("website_host_exact");
+    }
+    if (score <= 0)
+        return null;
+    return { entityRef, name: app.name, score: Math.min(1, score), reasons };
+}
+async function promptApplicationChoice(matches, allApps, suggested) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("\nExisting application entities found.");
+        if (suggested) {
+            console.log(`Suggested match: ${suggested.name} (${suggested.entityRef}) score=${suggested.score.toFixed(2)} [${suggested.reasons.join(", ")}]`);
+        }
+        console.log("\nChoose target application:");
+        const options = [];
+        let index = 1;
+        for (const m of matches.slice(0, 5)) {
+            options.push({
+                key: String(index++),
+                label: `${m.name} (${m.entityRef}) score=${m.score.toFixed(2)}`,
+                value: m.entityRef,
+            });
+        }
+        options.push({ key: String(index++), label: "Show all applications", value: "__show_all__" });
+        options.push({ key: String(index), label: "Create a new application", value: "__create__" });
+        for (const o of options)
+            console.log(`  ${o.key}) ${o.label}`);
+        const answer = (await rl.question("Select option: ")).trim();
+        const chosen = options.find((o) => o.key === answer)?.value;
+        if (chosen === "__show_all__") {
+            console.log("\nAll applications:");
+            allApps.forEach((a, i) => console.log(`  ${i + 1}) ${a.name} (${a.entityRef ?? a.externalKey ?? "n/a"})`));
+            const pick = Number((await rl.question("Pick application number or 0 to create new: ")).trim());
+            if (!Number.isFinite(pick) || pick <= 0 || pick > allApps.length)
+                return "__create__";
+            return allApps[pick - 1].entityRef ?? allApps[pick - 1].externalKey ?? "__create__";
+        }
+        return chosen && chosen !== "__show_all__" ? chosen : "__create__";
+    }
+    finally {
+        rl.close();
+    }
+}
 // ─── Main command ─────────────────────────────────────────────────────────────
 export async function initProject(args) {
     const asJson = parseFlag(args, "--json");
@@ -875,6 +958,10 @@ export async function initProject(args) {
     const repoRefOverride = parseOptionValue(args, "--repo-ref");
     const repoUrlOverride = parseOptionValue(args, "--repo-url");
     const repoPathOverride = parseOptionValue(args, "--repo-path");
+    const applicationRefOverride = parseOptionValue(args, "--application-ref");
+    const forceCreateApplication = parseFlag(args, "--create-application");
+    const autoMapApplication = parseFlag(args, "--auto-map-application");
+    const nonInteractive = parseFlag(args, "--non-interactive");
     const creds = requireCredentials();
     const mcpOpts = { companyId: creds.companyId };
     if (!asJson)
@@ -883,7 +970,7 @@ export async function initProject(args) {
     const detectedRepo = detectSourceRepository(dir);
     const displayName = nameOverride ?? projectName;
     const projectSlug = slugify(displayName);
-    const projectExternalKey = `${entityTypeOverride}:${projectSlug}`;
+    let projectExternalKey = `${entityTypeOverride}:${projectSlug}`;
     // Compute sub-package external keys now that projectSlug is known.
     // Unscoped names (no "/") get prefixed with the project slug to avoid ambiguous keys
     // like "application:crawler" — they become "application:whatsontap-crawler" instead,
@@ -987,6 +1074,57 @@ export async function initProject(args) {
     const repoUrl = repoUrlOverride ?? detectedRepo?.url ?? null;
     const sourceVcsType = detectedRepo?.vcsType ?? "unknown";
     const sourceProvider = detectedRepo?.provider ?? "unknown";
+    if (entityTypeOverride === "application" && !forceCreateApplication) {
+        if (applicationRefOverride) {
+            projectExternalKey = applicationRefOverride;
+            if (!asJson)
+                console.log(`\nUsing --application-ref target: ${projectExternalKey}`);
+        }
+        else {
+            const appsRaw = await callMcpTool("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: creds.companyId }, mcpOpts);
+            const appsData = parseToolText(appsRaw);
+            const apps = (appsData.entities ?? []).filter((e) => (e.entityRef ?? e.externalKey));
+            if (apps.length > 0) {
+                const matches = apps
+                    .map((a) => scoreApplicationCandidate(a, displayName, repoUrl))
+                    .filter((m) => Boolean(m))
+                    .sort((a, b) => b.score - a.score);
+                const suggested = matches.length > 0 ? matches[0] : null;
+                const highConfidence = suggested && suggested.score >= 0.85;
+                const interactiveAllowed = !asJson && !nonInteractive && process.stdin.isTTY;
+                if (autoMapApplication && highConfidence) {
+                    projectExternalKey = suggested.entityRef;
+                    if (!asJson)
+                        console.log(`\nAuto-mapped to existing application: ${suggested.name} (${projectExternalKey})`);
+                }
+                else if (!interactiveAllowed) {
+                    if (highConfidence) {
+                        projectExternalKey = suggested.entityRef;
+                    }
+                    else if (autoMapApplication) {
+                        const message = "Ambiguous application mapping in non-interactive mode. Pass --application-ref or --create-application.";
+                        if (asJson) {
+                            process.stdout.write(`${JSON.stringify({ ok: false, error: "APPLICATION_MAPPING_AMBIGUOUS", message, candidates: matches.slice(0, 5) }, null, 2)}\n`);
+                            process.exitCode = 1;
+                            return;
+                        }
+                        throw new Error(message);
+                    }
+                }
+                else {
+                    const chosen = await promptApplicationChoice(matches, apps, highConfidence ? suggested : null);
+                    if (chosen !== "__create__") {
+                        projectExternalKey = chosen;
+                        if (!asJson)
+                            console.log(`Mapped to existing application: ${projectExternalKey}`);
+                    }
+                    else if (!asJson) {
+                        console.log("Creating a new application entity for this project.");
+                    }
+                }
+            }
+        }
+    }
     const agentContext = {
         agentId: "nexarch-cli:init-project",
         agentRunId: `init-project-${Date.now()}`,
@@ -1131,7 +1269,17 @@ export async function initProject(args) {
         }
     }
     // Company org is accountable_for the top-level project entity
-    const orgExternalKey = `org:${creds.companyId}`;
+    let orgExternalKey = `organisation:${normalizeToken(creds.companyId)}`;
+    try {
+        const orgRaw = await callMcpTool("nexarch_list_entities", { entityTypeCode: "organisation", status: "active", limit: 1, companyId: creds.companyId }, mcpOpts);
+        const orgData = parseToolText(orgRaw);
+        const org = (orgData.entities ?? [])[0];
+        if (org?.entityRef || org?.externalKey)
+            orgExternalKey = (org.entityRef ?? org.externalKey);
+    }
+    catch {
+        // keep fallback
+    }
     addRel("accountable_for", orgExternalKey, projectExternalKey, 1);
     // Also accountable_for any sub-package applications
     for (const sp of subPackages) {

package/dist/commands/policy-audit-submit.js

@@ -115,11 +115,11 @@ export async function policyAuditSubmit(args) {
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
         console.log(`
 Usage:
-  nexarch policy-audit-submit --command-id <id> --application-key <key> [options]
+  nexarch policy-audit-submit --command-id <id> --application-ref <key> [options]
 
 Options:
   --command-id <id>          Required command id
-  --application-key <key>    Required application key (e.g. application:bad-driving)
+  --application-ref <key>    Required application reference key (e.g. application:bad-driving)
   --agent-key <key>          Optional agent key (defaults from identity)
   --finding <controlId|ruleId|result|rationale|missing1;missing2>   Repeatable
   --findings-json <json>     JSON array of findings
@@ -134,22 +134,23 @@ Notes:
         return;
     }
     const commandId = parseOptionValue(args, "--command-id") ?? parseOptionValue(args, "--id");
-    const applicationEntityKey = parseOptionValue(args, "--application-key") ?? parseOptionValue(args, "--entity");
+    const applicationEntityRef = parseOptionValue(args, "--application-ref") ?? parseOptionValue(args, "--application-key") ?? parseOptionValue(args, "--entity-ref") ?? parseOptionValue(args, "--entity");
     const agentKey = parseOptionValue(args, "--agent-key") ?? loadIdentityAgentKey();
     if (!commandId) {
         console.error("error: --command-id <uuid> is required");
         process.exit(1);
     }
-    if (!applicationEntityKey) {
-        console.error("error: --application-key <externalKey> is required (e.g. application:bad-driving)");
+    if (!applicationEntityRef) {
+        console.error("error: --application-ref <entityRef> is required (e.g. application:bad-driving)");
         process.exit(1);
     }
     const findings = parseFindings(args);
     const creds = requireCredentials();
     const raw = await callMcpTool("nexarch_submit_policy_audit", {
         commandId,
-        applicationEntityKey,
-        ...(agentKey ? { agentKey } : {}),
+        applicationEntityRef,
+        applicationEntityKey: applicationEntityRef,
+        ...(agentKey ? { agentRef: agentKey, agentKey } : {}),
         findings,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });
@@ -162,7 +163,7 @@ Notes:
         console.error(`Policy audit submit failed${result.error ? `: ${result.error}` : ""}`);
         process.exit(1);
     }
-    console.log(`Policy audit submitted for ${applicationEntityKey}.`);
+    console.log(`Policy audit submitted for ${applicationEntityRef}.`);
     if (result.runId)
         console.log(`Run ID: ${result.runId}`);
     if (result.summary) {

package/dist/commands/policy-audit-template.js

@@ -32,7 +32,7 @@ function parseToolText(result) {
 }
 export async function policyAuditTemplate(args) {
     const asJson = parseFlag(args, "--json");
-    const entity = parseOptionValue(args, "--entity") ?? parseOptionValue(args, "--application-key");
+    const entity = parseOptionValue(args, "--entity-ref") ?? parseOptionValue(args, "--entity") ?? parseOptionValue(args, "--application-key");
     const outputPath = parseOptionValue(args, "--out") ?? parseOptionValue(args, "--output");
     const defaultResult = (parseOptionValue(args, "--default-result") ?? "fail").toLowerCase();
     const selectedControlIds = new Set(parseMultiOptionValues(args, "--control-id"));
@@ -62,7 +62,7 @@ Output shape is ready for:
         process.exit(1);
     }
     const creds = requireCredentials();
-    const raw = await callMcpTool("nexarch_get_entity_policy_controls", { entityExternalKey: entity, companyId: creds.companyId }, { companyId: creds.companyId });
+    const raw = await callMcpTool("nexarch_get_entity_policy_controls", { entityRef: entity, entityExternalKey: entity, companyId: creds.companyId }, { companyId: creds.companyId });
     const result = parseToolText(raw);
     if (!result.found) {
         console.error(`error: entity not found: ${entity}`);

package/dist/commands/policy-controls.js

@@ -19,13 +19,13 @@ function parseToolText(result) {
 }
 export async function policyControls(args) {
     const asJson = parseFlag(args, "--json");
-    const entity = parseOptionValue(args, "--entity") ?? parseOptionValue(args, "--application-key");
+    const entity = parseOptionValue(args, "--entity-ref") ?? parseOptionValue(args, "--entity") ?? parseOptionValue(args, "--application-key");
     if (!entity) {
         console.error("error: --entity <externalKey> is required (e.g. application:bad-driving)");
         process.exit(1);
     }
     const creds = requireCredentials();
-    const raw = await callMcpTool("nexarch_get_entity_policy_controls", { entityExternalKey: entity, companyId: creds.companyId }, { companyId: creds.companyId });
+    const raw = await callMcpTool("nexarch_get_entity_policy_controls", { entityRef: entity, entityExternalKey: entity, companyId: creds.companyId }, { companyId: creds.companyId });
     const result = parseToolText(raw);
     if (asJson) {
         process.stdout.write(JSON.stringify(result) + "\n");
@@ -35,7 +35,7 @@ export async function policyControls(args) {
         console.log(`Entity not found: ${entity}`);
         return;
     }
-    console.log(`Policy controls for ${result.entityExternalKey ?? entity}`);
+    console.log(`Policy controls for ${result.entityRef ?? result.entityExternalKey ?? entity}`);
     console.log(`Controls: ${result.controlCount ?? 0}`);
     for (const control of result.controls ?? []) {
         const rules = control.rules ?? [];

package/dist/index.js

@@ -85,9 +85,15 @@ Usage:
                       config files against the reference library, write entities and
                       relationships to the architecture graph, and log unresolved
                       names as reference candidates.
+                      When entity-type=application and existing applications are present,
+                      prompts to map to an existing app or create a new one.
                       Options: --dir <path>  (default: cwd)
                                --name <name>  override project name
                                --entity-type <code>  (default: application)
+                               --application-ref <entityRef>  force mapping target
+                               --create-application  force new application entity
+                               --auto-map-application  auto-map only when high confidence
+                               --non-interactive  fail on ambiguous mapping
                                --dry-run  preview without writing
                                --json
   nexarch update-entity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.8.27",
+  "version": "0.9.1",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",