@inkobytes/nexus 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,9 +1,12 @@
 # Changelog
 
-## 1.0.2 - 2026-06-03
+## 1.0.3 - 2026-06-03
 
 - Collapsed large `nexus doctor` Git Privacy floods into grouped per-root summaries with sample paths.
 - Prioritized `CONTINUITY.md` and `memories/` samples first so agent-local issues stay visible.
+- Collapsed shared agent roots like `.claude/`, `.codex/`, and `.gemini/` into one concise Git Privacy note for repos that intentionally track them.
+- Colorized `nexus doctor` output and grouped findings under clearer action buckets like `Fix the following` and `Review / informational`.
+- Added `.nexus/config.json` support for `doctor.allowTrackedAgentTrees` so intentionally tracked shared agent trees can be treated as informational.
 
 ## 1.0.1 - 2026-06-02
 

package/README.md

@@ -166,7 +166,8 @@ Doctor reports grouped issues:
 - missing Nexus files
 - package script exfiltration and install-hook risks
 - package privacy risks for local/private files
-- grouped Git Privacy summaries for tracked private/local trees so large agent folders stay readable
+- grouped Git Privacy summaries for tracked private/local trees, with shared agent dirs collapsed into one concise note
+- colorized action buckets so fixes and informational lock notes are easier to scan
 - stale nexus locks
 - missing agent instructions specifically for nexus
 - missing continuity and memory scaffolds
@@ -176,6 +177,18 @@ With `--fix`, Nexus creates safe missing scaffolds and updates managed protocol
 
 With `--json`, Nexus prints the same health sections as structured JSON for tools such as Inkobytes reports.
 
+If a private repo intentionally tracks shared agent trees like `.claude/`, `.codex/`, or `.gemini/`, you can mark that as allowed in `.nexus/config.json`:
+
+```json
+{
+  "doctor": {
+    "allowTrackedAgentTrees": true
+  }
+}
+```
+
+With that setting, `nexus doctor` keeps the shared-agent-tree note as informational instead of repeating an untrack fix.
+
 Use `doctor` for audit or repair. Do not make it the normal first command for every agent session.
 
 ### `nexus soul [--file <path>] [--status | --remove]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkobytes/nexus",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Multi-agent coordination CLI for coding agents sharing a local repository",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -347,6 +347,7 @@ export default function doctor(args) {
   const fix = args.includes('--fix');
   const json = args.includes('--json');
   const root = cwd();
+  const colors = createColors();
   const sections = {
     'Nexus Files': [],
     'Agent Instructions': [],
@@ -365,8 +366,8 @@ export default function doctor(args) {
   const config = getConfig(root);
 
   if (!json) {
-    console.log(`Nexus doctor${fix ? ' --fix' : ''}`);
-    console.log(`Repo: ${root}\n`);
+    console.log(colors.bold(colors.cyan(`Nexus doctor${fix ? ' --fix' : ''}`)));
+    console.log(`${colors.dim('Repo:')} ${root}\n`);
   }
 
   const nexusProtocolFiles = ['_NEXUS_CONSTITUTION.md', '_NEXUS_QUEUE.md', '_NEXUS_STANDUP.md'];
@@ -412,7 +413,7 @@ export default function doctor(args) {
     sections['Package Privacy'].push(issue);
   }
 
-  for (const issue of scanGitPrivacy(root)) {
+  for (const issue of scanGitPrivacy(root, config)) {
     sections['Git Privacy'].push(issue);
   }
 
@@ -658,40 +659,95 @@ export default function doctor(args) {
   }
 
   if (changes.length) {
-    console.log('Applied fixes:');
-    for (const change of changes) console.log(`  - ${change}`);
+    console.log(colors.bold(colors.green('Applied fixes')));
+    for (const change of changes) console.log(`  ${colors.green('-')} ${change}`);
     console.log('');
   }
 
   let problemCount = 0;
   for (const [title, entries] of Object.entries(sections)) {
-    console.log(`[${title}]`);
+    console.log(colors.bold(colors.cyan(`[${title}]`)));
     if (!entries.length) {
-      console.log('  OK');
+      console.log(`  ${colors.green('OK')}`);
       console.log('');
       continue;
     }
 
-    for (const entry of entries) {
+    const actionable = entries.filter((entry) => !entry.ok);
+    const informational = entries.filter((entry) => entry.ok);
+    problemCount += actionable.length;
+
+    if (actionable.length) renderEntryBucket('Fix the following', actionable, colors.yellow, colors.red, title, colors);
+    if (informational.length) renderEntryBucket('Review / informational', informational, colors.blue, colors.green, title, colors);
+    console.log('');
+  }
+
+  if (problemCount) {
+    console.log(colors.bold(colors.yellow('Some issues need attention.')));
+    console.log(colors.dim('Safe scaffold fixes: `nexus doctor --fix`.'));
+    return;
+  }
+
+  console.log(colors.bold(colors.green('All checked Nexus categories are ready.')));
+}
+
+function renderEntryBucket(label, entries, headingColor, markerColor, sectionTitle, colors) {
+  console.log(`  ${headingColor(label)}`);
+  const groups = groupEntriesForDisplay(entries, sectionTitle);
+  for (const group of groups) {
+    if (group.label) {
+      console.log(`    ${colors.bold(group.label)}`);
+    }
+    for (const entry of group.entries) {
+      const baseIndent = group.label ? '      ' : '    ';
+      const detailIndent = group.label ? '        ' : '      ';
       const prefix = entry.ok ? '-' : '!';
-      console.log(`  ${prefix} ${entry.issue}`);
+      console.log(`${baseIndent}${markerColor(prefix)} ${entry.issue}`);
       if (entry.details) {
         for (const detail of entry.details) {
-          console.log(`    ${detail}`);
+          console.log(`${detailIndent}${colors.dim(detail)}`);
         }
       }
-      if (entry.fix) console.log(`    Fix: ${entry.fix}`);
-      if (!entry.ok) problemCount++;
+      if (entry.fix) {
+        console.log(`${detailIndent}${colors.bold('Fix:')} ${colors.dim(entry.fix)}`);
+      }
     }
-    console.log('');
   }
+}
 
-  if (problemCount) {
-    console.log('Some issues need attention. Safe scaffold fixes: `nexus doctor --fix`.');
-    return;
+function groupEntriesForDisplay(entries, sectionTitle) {
+  const groups = [];
+  const grouped = new Map();
+
+  for (const entry of entries) {
+    const label = entry.displayGroup || inferDisplayGroup(entry.issue, sectionTitle);
+    if (!label) {
+      groups.push({ label: '', entries: [entry] });
+      continue;
+    }
+    if (!grouped.has(label)) {
+      const group = { label, entries: [] };
+      grouped.set(label, group);
+      groups.push(group);
+    }
+    grouped.get(label).entries.push(entry);
+  }
+
+  return groups;
+}
+
+function inferDisplayGroup(issue, sectionTitle) {
+  if (sectionTitle === 'Locks') {
+    const lockMatch = issue.match(/^(?:Stale lock on|Active lock on|Unverified claim on) ([^ ]+)/);
+    if (lockMatch) return lockMatch[1];
   }
 
-  console.log('All checked Nexus categories are ready.');
+  if (sectionTitle === 'Queue Authorship') {
+    const taskMatch = issue.match(/^Task "([^"]+)"/);
+    if (taskMatch) return taskMatch[1];
+  }
+
+  return '';
 }
 
 function extractReadyQueueSection(content) {
@@ -864,6 +920,13 @@ const GIT_PRIVACY_COLLAPSE_ROOTS = [
   'session-logs',
 ];
 
+const GIT_PRIVACY_AGENT_ROOTS = new Set([
+  '.agy',
+  '.claude',
+  '.codex',
+  '.gemini',
+]);
+
 function scanPackagePrivacy(root) {
   const packagePath = join(root, 'package.json');
   if (!existsSync(packagePath)) return [];
@@ -895,7 +958,7 @@ function scanPackagePrivacy(root) {
   return issues;
 }
 
-function scanGitPrivacy(root) {
+function scanGitPrivacy(root, config) {
   const gitDir = join(root, '.git');
   if (!existsSync(gitDir)) return [];
 
@@ -907,10 +970,10 @@ function scanGitPrivacy(root) {
   if (result.status !== 0) return [];
 
   const tracked = result.stdout.split('\n').filter(Boolean);
-  return summarizeGitPrivacyIssues(tracked);
+  return summarizeGitPrivacyIssues(tracked, config);
 }
 
-function summarizeGitPrivacyIssues(tracked) {
+function summarizeGitPrivacyIssues(tracked, config) {
   const grouped = new Map();
   const singles = [];
 
@@ -925,6 +988,7 @@ function summarizeGitPrivacyIssues(tracked) {
   }
 
   const issues = [];
+  const agentRootSummaries = [];
 
   for (const file of singles.sort()) {
     issues.push({
@@ -935,6 +999,10 @@ function summarizeGitPrivacyIssues(tracked) {
 
   for (const root of Array.from(grouped.keys()).sort()) {
     const files = grouped.get(root).slice().sort(compareGitPrivacyFiles);
+    if (GIT_PRIVACY_AGENT_ROOTS.has(root)) {
+      agentRootSummaries.push(`${root}/ (${files.length} files)`);
+      continue;
+    }
     const samples = files.slice(0, 5);
     const hiddenCount = files.length - samples.length;
     const noun = files.length === 1 ? 'path' : 'paths';
@@ -947,6 +1015,21 @@ function summarizeGitPrivacyIssues(tracked) {
     issues.push({ issue, fix, details });
   }
 
+  if (agentRootSummaries.length) {
+    issues.unshift({
+      issue: `Tracked shared agent trees detected: ${agentRootSummaries.join(', ')}`,
+      fix: config.doctor.allowTrackedAgentTrees
+        ? undefined
+        : 'If these agent trees are intentionally versioned in this repo, keep them. Otherwise untrack them without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.',
+      details: [
+        config.doctor.allowTrackedAgentTrees
+          ? 'Allowed by `.nexus/config.json` because this repo intentionally versions shared agent trees.'
+          : 'This can be normal in private repos that share agent protocols and memory in Git.',
+      ],
+      ok: config.doctor.allowTrackedAgentTrees,
+    });
+  }
+
   return issues;
 }
 
@@ -969,6 +1052,26 @@ function gitPrivacyPriority(file) {
   return 2;
 }
 
+function createColors() {
+  const enabled = supportsColor();
+  const wrap = (open, close) => (value) => enabled ? `\u001b[${open}m${value}\u001b[${close}m` : String(value);
+  return {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    cyan: wrap(36, 39),
+  };
+}
+
+function supportsColor() {
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true;
+  if ('NO_COLOR' in process.env) return false;
+  return Boolean(process.stdout && process.stdout.isTTY);
+}
+
 function scanGeneratedArtifacts(root) {
   const gitDir = join(root, '.git');
   if (!existsSync(gitDir)) return [];

package/src/lib/config.js

@@ -2,7 +2,7 @@
  * Config — resolve project root and Nexus paths
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
 import { cwd } from 'process';
 
@@ -14,6 +14,7 @@ export function getConfig(fromDir) {
   const root = fromDir || cwd();
   const lockDir = join(root, '.nexus', 'locks');
   const budgetFile = join(root, '.nexus', 'agent-budgets.json');
+  const localConfig = readLocalConfig(root);
 
   _config = {
     root,
@@ -28,6 +29,9 @@ export function getConfig(fromDir) {
     maxDumpFiles: 20,
     maxClaimAttempts: 10,
     claimRetryMs: 2000,
+    doctor: {
+      allowTrackedAgentTrees: Boolean(localConfig.doctor?.allowTrackedAgentTrees),
+    },
   };
 
   return _config;
@@ -36,3 +40,15 @@ export function getConfig(fromDir) {
 export function resetConfig() {
   _config = null;
 }
+
+function readLocalConfig(root) {
+  const path = join(root, '.nexus', 'config.json');
+  if (!existsSync(path)) return {};
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}