nexarch 0.12.0 → 0.12.3

package/dist/commands/check-in.js

@@ -5,6 +5,7 @@ import { homedir } from "os";
 import { saveCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
+import { inferAccessibleApplicationRefs } from "../lib/application-context.js";
 function parseFlag(args, flag) {
     return args.includes(flag);
 }
@@ -36,6 +37,7 @@ function loadIdentity() {
 export async function checkIn(args) {
     const asJson = parseFlag(args, "--json");
     const agentKeyArg = parseOptionValue(args, "--agent-ref") ?? parseOptionValue(args, "--agent-key");
+    const applicationRefArg = parseOptionValue(args, "--application-ref");
     const creds = requireCredentials();
     const identity = loadIdentity();
     const agentKey = agentKeyArg ?? identity.agentKey;
@@ -48,9 +50,16 @@ export async function checkIn(args) {
         }
         return;
     }
+    const applicationContext = await inferAccessibleApplicationRefs({
+        companyId: creds.companyId,
+        explicitApplicationRefs: applicationRefArg ? [applicationRefArg] : undefined,
+    });
     const raw = await callMcpTool("nexarch_check_in", {
         agentRef: agentKey,
         agentKey,
+        applicationContext: applicationContext.accessibleApplicationRefs.length > 0
+            ? { accessibleApplicationRefs: applicationContext.accessibleApplicationRefs }
+            : undefined,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });
     const result = parseToolText(raw);
@@ -74,6 +83,7 @@ export async function checkIn(args) {
     if (result.leaseExpiresAt) {
         console.log(`Check-in lease active until ${new Date(result.leaseExpiresAt).toLocaleString()}.`);
     }
+    console.log(`Application context: ${applicationContext.detail}`);
     for (const warning of result.warnings ?? []) {
         if (warning.message)
             console.log(`Warning: ${warning.message}`);
@@ -91,7 +101,7 @@ export async function checkIn(args) {
         }
         for (const cmd of commands) {
             const claimable = cmd.claimable ? "yes" : "no";
-            const reason = cmd.claimReason ?? (cmd.claimable ? "application_access_confirmed" : "application_not_found_for_company");
+            const reason = cmd.claimReason ?? (cmd.claimable ? "application_access_confirmed" : "application_context_required_for_claim");
             console.log(`\n- ID         : ${cmd.id}`);
             console.log(`  Type       : ${cmd.command_type}`);
             console.log(`  Target     : ${cmd.target_entity_key ?? "(none)"}`);
@@ -101,12 +111,14 @@ export async function checkIn(args) {
                 console.log(`  Type ver   : ${cmd.command_type_version}`);
             if (cmd.resolved_runtime_handler)
                 console.log(`  Runtime    : ${cmd.resolved_runtime_handler}`);
-            if (cmd.claimable) {
-                console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"`);
-            }
+            if (cmd.claimGuidance)
+                console.log(`  Guidance   : ${cmd.claimGuidance}`);
+            console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"${cmd.target_entity_key ? ` --application-ref "${cmd.target_entity_key}"` : ""}`);
         }
         console.log("\nTo validate an application target is accessible in Nexarch before claiming:");
         console.log("  npx nexarch policy-controls --entity <application:key> --json");
+        console.log("If no application context was inferred, re-run with:");
+        console.log("  npx nexarch check-in --application-ref <application:key>");
     }
     else {
         console.log("No pending application-target commands found.");

package/dist/commands/command-claim.js

@@ -37,6 +37,7 @@ export async function commandClaim(args) {
     const asJson = parseFlag(args, "--json");
     const id = parseOptionValue(args, "--id");
     const agentKeyArg = parseOptionValue(args, "--agent-ref") ?? parseOptionValue(args, "--agent-key");
+    const applicationEntityRef = parseOptionValue(args, "--application-ref");
     if (!id) {
         console.error("error: --id <commandId> is required");
         process.exit(1);
@@ -54,6 +55,7 @@ export async function commandClaim(args) {
         agentRef: agentKey,
         agentKey,
         leaseToken: lease?.leaseToken,
+        applicationEntityRef: applicationEntityRef ?? undefined,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });
     const result = parseToolText(raw);
@@ -72,6 +74,8 @@ export async function commandClaim(args) {
         console.log(`Command ${id} was not claimed.`);
         if (result.reason)
             console.log(`Reason: ${result.reason}`);
+        if (!applicationEntityRef)
+            console.log("Tip: re-run with --application-ref <application:key>.");
         return;
     }
     const cmd = result.command;

package/dist/commands/init-agent.js

@@ -337,29 +337,28 @@ function canonicalTargetKey(filePath) {
     const abs = resolve(filePath);
     return process.platform === "win32" || process.platform === "darwin" ? abs.toLowerCase() : abs;
 }
-function injectAgentConfigs(registry) {
+function injectAgentConfigs(registry, runtimeCode) {
     const templateByCode = new Map(registry.instructionTemplates.map((t) => [t.code, t]));
-    const targets = [...registry.instructionTargets].sort((a, b) => a.sortOrder - b.sortOrder || a.filePathPattern.localeCompare(b.filePathPattern));
-    const results = [];
-    const seenTargets = new Set();
-    for (const target of targets) {
-        if (target.matchMode !== "exact")
-            continue;
+    const sortedTargets = [...registry.instructionTargets]
+        .filter((target) => target.matchMode === "exact")
+        .sort((a, b) => a.sortOrder - b.sortOrder || a.filePathPattern.localeCompare(b.filePathPattern));
+    const candidateTargets = runtimeCode
+        ? sortedTargets.filter((target) => target.runtimeCode === runtimeCode)
+        : sortedTargets;
+    const applyToTarget = (target) => {
         const template = templateByCode.get(target.templateCode);
         if (!template)
-            continue;
+            return null;
         const filePath = join(process.cwd(), target.filePathPattern);
-        const targetKey = canonicalTargetKey(filePath);
-        if (seenTargets.has(targetKey))
-            continue;
-        seenTargets.add(targetKey);
-        if (!existsSync(filePath))
-            continue;
-        const existing = readFileSync(filePath, "utf8");
         const sectionBody = template.body.trim();
         const sectionHeading = target.sectionHeading ?? "## Nexarch Agent Registration";
         const sectionMarker = target.sectionMarker ?? sectionHeading;
         const managedBody = wrapManagedSection("agent-registration", sectionBody);
+        if (!existsSync(filePath)) {
+            writeFileSync(filePath, `${managedBody}\n`, "utf8");
+            return { path: filePath, status: "injected" };
+        }
+        const existing = readFileSync(filePath, "utf8");
         if (target.insertionMode === "replace_section") {
             let replaced = replaceManagedSection(existing, "agent-registration", sectionBody);
             if (replaced === existing) {
@@ -372,29 +371,46 @@ function injectAgentConfigs(registry) {
             }
             if (replaced !== existing) {
                 writeFileSync(filePath, replaced, "utf8");
-                results.push({ path: filePath, status: "updated" });
+                return { path: filePath, status: "updated" };
             }
-            else if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-                results.push({ path: filePath, status: "already_present" });
-            }
-            else {
-                const separator = existing.endsWith("\n") ? "" : "\n";
-                writeFileSync(filePath, existing + separator + managedBody + "\n", "utf8");
-                results.push({ path: filePath, status: "injected" });
+            if (existing.includes(managedBody) || existing.includes(sectionBody)) {
+                return { path: filePath, status: "already_present" };
             }
-            continue;
+            const separator = existing.endsWith("\n") ? "" : "\n";
+            writeFileSync(filePath, existing + separator + managedBody + "\n", "utf8");
+            return { path: filePath, status: "injected" };
         }
         if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-            results.push({ path: filePath, status: "already_present" });
-        }
-        else {
-            const separator = existing.endsWith("\n") ? "" : "\n";
-            const next = existing + separator + managedBody + "\n";
-            writeFileSync(filePath, next, "utf8");
-            results.push({ path: filePath, status: "injected" });
+            return { path: filePath, status: "already_present" };
         }
+        const separator = existing.endsWith("\n") ? "" : "\n";
+        const next = existing + separator + managedBody + "\n";
+        writeFileSync(filePath, next, "utf8");
+        return { path: filePath, status: "injected" };
+    };
+    const seenTargets = new Set();
+    const existingMatches = [];
+    for (const target of candidateTargets) {
+        const filePath = join(process.cwd(), target.filePathPattern);
+        const targetKey = canonicalTargetKey(filePath);
+        if (seenTargets.has(targetKey))
+            continue;
+        seenTargets.add(targetKey);
+        if (existsSync(filePath))
+            existingMatches.push(target);
+    }
+    if (existingMatches.length > 0) {
+        const results = existingMatches
+            .map((target) => applyToTarget(target))
+            .filter((result) => Boolean(result));
+        if (results.length > 0)
+            return results;
+    }
+    if (runtimeCode && candidateTargets.length > 0) {
+        const created = applyToTarget(candidateTargets[0]);
+        return created ? [created] : [];
     }
-    return results;
+    return [];
 }
 function injectTrustAttestationBlock(path, attestation) {
     if (!attestation.token || !attestation.payload)
@@ -1017,6 +1033,7 @@ export async function initAgent(args) {
         detail: "skipped",
         missingRequired: [],
     };
+    let selectedClient = clientArg ?? null;
     if (registration.ok) {
         let provider = providerArg;
         let model = modelArg;
@@ -1026,6 +1043,7 @@ export async function initAgent(args) {
             model = model ?? await promptForValue("Model id (e.g. claude-sonnet-4-6): ", true);
             client = client ?? await promptForValue("Client (e.g. claude-code/cursor/codex-cli): ", true);
         }
+        selectedClient = client ?? null;
         const missingRequired = [
             !provider ? "provider" : null,
             !model ? "model" : null,
@@ -1110,7 +1128,7 @@ export async function initAgent(args) {
         catch {
             // non-fatal
         }
-        let existingInstructionTargets = injectAgentConfigs(registry);
+        let existingInstructionTargets = injectAgentConfigs(registry, selectedClient);
         if (existingInstructionTargets.length === 0) {
             existingInstructionTargets = injectGenericAgentConfig(registry);
         }

package/dist/commands/init-project.js

@@ -221,7 +221,7 @@ function choosePreferredRepositoryRef(candidates) {
     });
     return scored[0]?.rawRef ?? null;
 }
-function detectSourceRepository(dir) {
+export function detectSourceRepository(dir) {
     let rawRef = null;
     let vcsType = "unknown";
     // Prefer git when present, and prefer hosted remotes over local-only URLs.
@@ -869,7 +869,7 @@ function structuralRelForSubPackage(sp, projectExternalKey) {
         return { type: "part_of", from: sp.externalKey, to: projectExternalKey };
     return null;
 }
-function scanProject(dir) {
+export function scanProject(dir) {
     const names = new Set();
     let projectName = basename(dir);
     const subPackages = [];
@@ -995,7 +995,7 @@ function pickRelationshipType(toEntityTypeCode, toEntitySubtypeCode, _fromEntity
             return "depends_on";
     }
 }
-function normalizeToken(value) {
+export function normalizeToken(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
 }
 function extractHost(input) {
@@ -1008,7 +1008,7 @@ function extractHost(input) {
         return null;
     }
 }
-function scoreApplicationCandidate(app, projectName, repoUrl) {
+export function scoreApplicationCandidate(app, projectName, repoUrl) {
     const entityRef = app.entityRef ?? app.externalKey ?? null;
     if (!entityRef)
         return null;

package/dist/commands/register-runtime.js

@@ -0,0 +1,77 @@
+import process from "process";
+import { existsSync, readFileSync } from "node:fs";
+import { arch, hostname, platform, release, type as osType, homedir } from "node:os";
+import { join } from "node:path";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+import { inferAccessibleApplicationRefs } from "../lib/application-context.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);
+}
+function loadIdentity() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return { agentKey: null };
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return { agentKey: data.agentKey ?? null };
+    }
+    catch {
+        return { agentKey: null };
+    }
+}
+export async function registerRuntime(args) {
+    const asJson = parseFlag(args, "--json");
+    const applicationRefArg = parseOptionValue(args, "--application-ref");
+    const client = parseOptionValue(args, "--client") ?? "nexarch-cli";
+    const version = parseOptionValue(args, "--version") ?? null;
+    const mode = process.env.CI ? "ci" : "interactive";
+    const creds = requireCredentials();
+    const identity = loadIdentity();
+    if (!identity.agentKey)
+        throw new Error("No agent key found. Run nexarch init-agent first.");
+    const applicationContext = await inferAccessibleApplicationRefs({
+        companyId: creds.companyId,
+        explicitApplicationRefs: applicationRefArg ? [applicationRefArg] : undefined,
+    });
+    const raw = await callMcpTool("nexarch_register_agent_runtime", {
+        agentRef: identity.agentKey,
+        runtime: {
+            client,
+            ...(version ? { version } : {}),
+            mode,
+            nodeVersion: process.version,
+        },
+        host: {
+            hostname: hostname(),
+            osPlatform: platform(),
+            osType: osType(),
+            osRelease: release(),
+            arch: arch(),
+        },
+        applicationContext: applicationContext.accessibleApplicationRefs.length > 0
+            ? { accessibleApplicationRefs: applicationContext.accessibleApplicationRefs }
+            : undefined,
+        companyId: creds.companyId,
+    }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
+    console.log(`Registered runtime for ${identity.agentKey}.`);
+    console.log(`Application context: ${applicationContext.detail}`);
+}

package/dist/commands/setup.js

@@ -67,9 +67,9 @@ export async function setup(args) {
     if (clients.length > 0) {
         const names = clients.map((c) => c.name);
         const listed = names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
-        console.log(`\nSetup complete. Open a new ${listed} session and ask your agent to "register with Nexarch".`);
+        console.log(`\nSetup complete. Open a new ${listed} session — your Nexarch registration is already in place. If you want the agent to look for pending work, ask it to check in.`);
     }
     else {
-        console.log('\nSetup complete. Once you have configured an MCP client (see above), open a new session and ask your agent to "register with Nexarch".');
+        console.log("\nSetup complete. Once you have configured an MCP client (see above), open a new session — your Nexarch registration is already in place. If you want the agent to look for pending work, ask it to check in.");
     }
 }

package/dist/index.js

@@ -25,6 +25,7 @@ import { policyAuditResults } from "./commands/policy-audit-results.js";
 import { appliedPolicies } from "./commands/applied-policies.js";
 import { governanceSummary } from "./commands/governance-summary.js";
 import { proposalsStart } from "./commands/proposals-start.js";
+import { registerRuntime } from "./commands/register-runtime.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -43,6 +44,7 @@ const commands = {
     "resolve-names": resolveNames,
     "list-entities": listEntities,
     "list-relationships": listRelationships,
+    "register-runtime": registerRuntime,
     "check-in": checkIn,
     "command-done": commandDone,
     "command-fail": commandFail,
@@ -180,12 +182,20 @@ Usage:
                                --to <toExternalKey>
                                --limit <1-500>
                                --json
+  nexarch register-runtime
+                      Register or refresh runtime + optional application context
+                      without performing check-in.
+                      Options: --application-ref <entityRef>
+                               --client <name>
+                               --version <semver>
+                               --json
   nexarch check-in    Preview pending application-target commands (no auto-claim)
                       and report draft/proposed applications needing review so the
                       agent can prompt the user to explore and instantiate them.
                       Use command-claim to explicitly claim a specific command.
                       Scope is resolved server-side from active company context.
                       Options: --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  narrow preview scope
                                --json              JSON output includes draftApplications[] and proposedApplications[]
   nexarch proposals start
                       Start a new application workspace from a proposed NexArch app.
@@ -205,6 +215,7 @@ Usage:
                       Explicitly claim a pending command by ID.
                       Options: --id <commandId>    (required)
                                --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  required for application-target commands
                                --json
   nexarch command-done
                       Mark a claimed command as completed.

package/dist/lib/application-context.js

@@ -0,0 +1,51 @@
+import { resolve as resolvePath } from "node:path";
+import { callMcpTool } from "./mcp.js";
+import { detectSourceRepository, scanProject, scoreApplicationCandidate } from "../commands/init-project.js";
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function inferAccessibleApplicationRefs(params) {
+    const explicit = Array.from(new Set((params.explicitApplicationRefs ?? []).map((value) => value.trim()).filter(Boolean)));
+    if (explicit.length > 0) {
+        return {
+            accessibleApplicationRefs: explicit,
+            source: "explicit",
+            detail: `Using explicit application context (${explicit.join(", ")}).`,
+            repoUrl: detectSourceRepository(params.dir ?? process.cwd())?.url ?? null,
+            projectNames: [],
+            candidates: [],
+        };
+    }
+    const dir = resolvePath(params.dir ?? process.cwd());
+    const repoUrl = detectSourceRepository(dir)?.url ?? null;
+    const scan = scanProject(dir);
+    const projectNames = Array.from(new Set([scan.projectName, ...scan.subPackages.map((sp) => sp.name)])).filter(Boolean);
+    const appsRaw = await callMcpTool("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: params.companyId }, { companyId: params.companyId });
+    const appsData = parseToolText(appsRaw);
+    const apps = (appsData.entities ?? []).filter((entity) => (entity.entityRef ?? entity.externalKey));
+    const candidateMap = new Map();
+    for (const projectName of projectNames) {
+        for (const app of apps) {
+            const match = scoreApplicationCandidate(app, projectName, repoUrl);
+            if (!match)
+                continue;
+            const existing = candidateMap.get(match.entityRef);
+            if (!existing || match.score > existing.score) {
+                candidateMap.set(match.entityRef, match);
+            }
+        }
+    }
+    const candidates = Array.from(candidateMap.values()).sort((a, b) => b.score - a.score);
+    const accessibleApplicationRefs = candidates.filter((candidate) => candidate.score >= 0.85).map((candidate) => candidate.entityRef);
+    return {
+        accessibleApplicationRefs,
+        source: accessibleApplicationRefs.length > 0 ? "inferred" : "none",
+        detail: accessibleApplicationRefs.length > 0
+            ? `Inferred application context from current folder (${accessibleApplicationRefs.join(", ")}).`
+            : "No high-confidence application context inferred from current folder.",
+        repoUrl,
+        projectNames,
+        candidates,
+    };
+}

package/package.json

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