@inkobytes/nexus 1.0.0 → 1.0.2

package/src/commands/completion.js

@@ -0,0 +1,124 @@
+/**
+ * nexus completion zsh
+ * Print shell completion scripts.
+ */
+
+export default function completion(args) {
+  const shell = args[0] || 'zsh';
+
+  switch (shell) {
+    case 'zsh':
+      console.log(buildZshCompletion());
+      return;
+    case '--help':
+    case '-h':
+    case 'help':
+      printHelp();
+      return;
+    default:
+      throw new Error(`Unsupported completion shell: ${shell}`);
+  }
+}
+
+function printHelp() {
+  console.log(`Usage: nexus completion zsh
+
+Print a shell completion script for Nexus.
+
+Example:
+  source <(nexus completion zsh)
+`);
+}
+
+function buildZshCompletion() {
+  return `#compdef nexus
+
+local -a commands
+commands=(
+  'init:Scaffold Nexus files into current repo'
+  'doctor:Check or repair agent protocol files'
+  'completion:Print a shell completion script'
+  'checkin:Signal agent presence'
+  'checkout:Signal session end or cleanup'
+  'claim:Lock a file or directory'
+  'release:Unlock, auto-commit, and log'
+  'standup:Append a validated standup line'
+  'status:Show current blackboard state'
+  'clean:Prune locks'
+  'next:Suggest next safe task from queue'
+  'start:Orient an agent entering this repo'
+  'dashboard:Serve the local dashboard'
+  'metrics:Summarize commits, releases, and queue cost'
+  'ledger:Show or backfill completed task ledger'
+  'chmod:Show or set promptCHMOD permissions'
+  'db:Database backup and recovery'
+  'drill:Inspect or run protocol drills'
+  'soul:Manage local soul overlay in agent files'
+  'help:Show command help'
+)
+
+local -a drill_actions db_actions
+drill_actions=(list show run report help)
+db_actions=(backup list restore schedule)
+
+case $CURRENT in
+  2)
+    _describe 'nexus command' commands
+    return
+  ;;
+esac
+
+case $words[2] in
+  checkin|checkout|next)
+    _arguments '1:agent:(@agy @claude @codex @gemini)'
+    ;;
+  claim)
+    _arguments \\
+      '1:path:_files' \\
+      '2:agent:(@agy @claude @codex @gemini)' \\
+      '3:intent:_message' \\
+      '--agent[Agent handle]:agent:(@agy @claude @codex @gemini)' \\
+      '--intent[Claim intent]:intent:_message'
+    ;;
+  release)
+    _arguments '1:path:_files' '2:commit message:_message'
+    ;;
+  standup)
+    _arguments '1:standup message:_message'
+    ;;
+  doctor)
+    _arguments '--fix[Repair known protocol drift]' '--json[Print JSON report]'
+    ;;
+  completion)
+    _arguments '1:shell:(zsh)'
+    ;;
+  clean)
+    _arguments '1:target or flag:(--stale)'
+    ;;
+  dashboard)
+    _arguments '--serve[Start the dashboard server]' '--port[Dashboard port]:port number:'
+    ;;
+  metrics)
+    _arguments '--json[Print JSON]'
+    ;;
+  ledger)
+    _arguments '1:mode:(backfill --json)'
+    ;;
+  chmod)
+    _arguments '--list[List current permissions]' '--init[Initialize promptCHMOD permissions]'
+    ;;
+  db)
+    _arguments '1:db action:(\${db_actions[*]})'
+    ;;
+  drill)
+    _arguments '1:drill action:(\${drill_actions[*]})'
+    ;;
+  soul)
+    _arguments '--file[Overlay file path]:path:_files' '--status[Show status]' '--remove[Remove overlay]'
+    ;;
+  start)
+    _arguments '--agent[Agent handle]:agent:(@agy @claude @codex @gemini)'
+    ;;
+esac
+`;
+}

package/src/commands/dashboard.js

@@ -54,6 +54,7 @@ export function buildSnapshot() {
   const queueText = readText(config.queue);
   const standupText = readText(config.standup);
   const reportText = readText(config.report);
+  const parsedReport = parseReportBlocks(reportText);
   const git = getGitStatus(config.root);
 
   return {
@@ -69,6 +70,8 @@ export function buildSnapshot() {
     ledger: readLedgerEntries().reverse(),
     standup: parseStandupEntries(standupText).filter(entry => entry.type.startsWith('@')).slice(-8).reverse(),
     releases: parseReleaseEntries(reportText).slice(-16).reverse(),
+    reportIntro: parsedReport.intro,
+    reportBlocks: parsedReport.blocks,
     report: sortReportBlocksLatestFirst(reportText),
   };
 }
@@ -364,6 +367,70 @@ function hasReleaseDetailValue(detail) {
   return detail.slice(colon + 1).trim().length > 0;
 }
 
+function parseReportBlocks(content) {
+  const trimmed = content.trim();
+  if (!trimmed) return { intro: '', blocks: [] };
+
+  const firstBlock = trimmed.search(/^## \[/m);
+  if (firstBlock === -1) return { intro: trimmed, blocks: [] };
+
+  const intro = trimmed.slice(0, firstBlock).trimEnd();
+  const blocks = trimmed
+    .slice(firstBlock)
+    .split(/\n(?=## \[)/)
+    .map((block) => block.trimEnd())
+    .filter(Boolean)
+    .reverse()
+    .map((block, index) => {
+      const lines = block.split('\n');
+      const heading = lines[0]?.match(/^## \[([^\]]+)\]\s*(.*)$/);
+      const timestamp = heading?.[1]?.trim() || '';
+      const target = heading?.[2]?.trim() || lines[0]?.replace(/^##\s*/, '') || '';
+      const details = lines.slice(1).join('\n').trim();
+      const parsed = parseReportTimestamp(timestamp);
+      const monthKey = parsed
+        ? `${parsed.getFullYear()}-${String(parsed.getMonth() + 1).padStart(2, '0')}`
+        : '';
+
+      return {
+        id: `report-${index}`,
+        timestamp,
+        target,
+        details,
+        raw: block,
+        monthKey,
+        monthLabel: parsed ? formatReportMonth(parsed) : 'Undated',
+      };
+    });
+
+  return { intro, blocks };
+}
+
+function parseReportTimestamp(value) {
+  const match = String(value || '').match(
+    /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2}))?(?:\s?(AM|PM|am|pm))?)?$/
+  );
+  if (!match) return null;
+
+  const year = Number.parseInt(match[1], 10);
+  const month = Number.parseInt(match[2], 10) - 1;
+  const day = Number.parseInt(match[3], 10);
+  let hour = Number.parseInt(match[4] || '0', 10);
+  const minute = Number.parseInt(match[5] || '0', 10);
+  const second = Number.parseInt(match[6] || '0', 10);
+  const meridiem = (match[7] || '').toUpperCase();
+
+  if (meridiem === 'PM' && hour < 12) hour += 12;
+  if (meridiem === 'AM' && hour === 12) hour = 0;
+
+  const date = new Date(year, month, day, hour, minute, second);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function formatReportMonth(date) {
+  return date.toLocaleString('en-US', { month: 'long', year: 'numeric' });
+}
+
 function sortReportBlocksLatestFirst(content) {
   const trimmed = content.trim();
   if (!trimmed) return content;

package/src/commands/doctor.js

@@ -93,6 +93,8 @@ This project uses Nexus for multi-agent coordination.
 ### Nexus Rules
 
 - Claim before editing shared project files: \`nexus claim <path> @Agent "intent"\`.
+- Nexus is agent-native and file-native, not feature-native: commit and release by file as soon as the file reaches a coherent checkpoint.
+- Do not hold claims while waiting to bundle related files into one feature commit; that blocks other agents who may need the file next.
 - Release finished work through Nexus: \`nexus release <path> "commit message"\`.
 - Use \`nexus next @Agent\` for the next safe queue task.
 - Do not free-roam into unassigned or \`Auto-flow: no\` work without user approval.
@@ -673,6 +675,11 @@ export default function doctor(args) {
     for (const entry of entries) {
       const prefix = entry.ok ? '-' : '!';
       console.log(`  ${prefix} ${entry.issue}`);
+      if (entry.details) {
+        for (const detail of entry.details) {
+          console.log(`    ${detail}`);
+        }
+      }
       if (entry.fix) console.log(`    Fix: ${entry.fix}`);
       if (!entry.ok) problemCount++;
     }
@@ -843,6 +850,20 @@ const PRIVATE_GIT_PATHS = [
   'USER.md',
 ];
 
+const GIT_PRIVACY_COLLAPSE_ROOTS = [
+  '.agent-session-logs',
+  '.agent-*',
+  '.agy',
+  '.antigravitycli',
+  '.claude',
+  '.codex',
+  '.gemini',
+  '.nexus/local',
+  'docs-priv',
+  'scratch',
+  'session-logs',
+];
+
 function scanPackagePrivacy(root) {
   const packagePath = join(root, 'package.json');
   if (!existsSync(packagePath)) return [];
@@ -886,10 +907,66 @@ function scanGitPrivacy(root) {
   if (result.status !== 0) return [];
 
   const tracked = result.stdout.split('\n').filter(Boolean);
-  return tracked.map((file) => ({
-    issue: `Git tracks private/local path: ${file}`,
-    fix: 'Untrack it without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.',
-  }));
+  return summarizeGitPrivacyIssues(tracked);
+}
+
+function summarizeGitPrivacyIssues(tracked) {
+  const grouped = new Map();
+  const singles = [];
+
+  for (const file of tracked) {
+    const root = gitPrivacyRoot(file);
+    if (!root) {
+      singles.push(file);
+      continue;
+    }
+    if (!grouped.has(root)) grouped.set(root, []);
+    grouped.get(root).push(file);
+  }
+
+  const issues = [];
+
+  for (const file of singles.sort()) {
+    issues.push({
+      issue: `Git tracks private/local path: ${file}`,
+      fix: 'Untrack it without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.',
+    });
+  }
+
+  for (const root of Array.from(grouped.keys()).sort()) {
+    const files = grouped.get(root).slice().sort(compareGitPrivacyFiles);
+    const samples = files.slice(0, 5);
+    const hiddenCount = files.length - samples.length;
+    const noun = files.length === 1 ? 'path' : 'paths';
+    const issue = `Git tracks private/local ${noun} under ${root}/ (${files.length} files)`;
+    const fix = 'Review the sample paths below. If the tree is intentionally tracked in this repo, keep it. Otherwise untrack it without deleting local files: `git rm --cached -r -- <path>`, then add an ignore rule.';
+    const details = samples.map((file) => `sample: ${file}`);
+    if (hiddenCount > 0) {
+      details.push(`...and ${hiddenCount} more tracked paths`);
+    }
+    issues.push({ issue, fix, details });
+  }
+
+  return issues;
+}
+
+function gitPrivacyRoot(file) {
+  for (const root of GIT_PRIVACY_COLLAPSE_ROOTS) {
+    if (matchesPrivatePath(file, root)) {
+      return root.replace(/\/$/, '');
+    }
+  }
+  return '';
+}
+
+function compareGitPrivacyFiles(a, b) {
+  return gitPrivacyPriority(a) - gitPrivacyPriority(b) || a.localeCompare(b);
+}
+
+function gitPrivacyPriority(file) {
+  if (/\/(CONTINUITY\.md|memories\/)/.test(file)) return 0;
+  if (/\/(AGENTS\.md|CLAUDE\.md|GEMINI\.md)$/.test(file)) return 1;
+  return 2;
 }
 
 function scanGeneratedArtifacts(root) {

package/src/commands/init.js

@@ -379,6 +379,8 @@ This project uses Nexus for multi-agent coordination.
 ### Nexus Rules
 
 - Claim before editing shared project files: \`nexus claim <path> @Agent "intent"\`.
+- Nexus is agent-native and file-native, not feature-native: commit and release by file as soon as the file reaches a coherent checkpoint.
+- Do not hold claims while waiting to bundle related files into one feature commit; that blocks other agents who may need the file next.
 - Release finished work through Nexus: \`nexus release <path> "commit message"\`.
 - Use \`nexus next @Agent\` for the next safe queue task.
 - Do not free-roam into unassigned or \`Auto-flow: no\` work without user approval.

package/src/commands/status.js

@@ -7,6 +7,8 @@ import { listLocks } from '../lib/lockManager.js';
 import { getConfig } from '../lib/config.js';
 import { spawnSync } from 'child_process';
 
+const FILE_FLOW_WARNING = 'Stale claim. Commit this file now.';
+
 export default function status(args) {
   const config = getConfig();
   const locks = listLocks();
@@ -36,6 +38,9 @@ export default function status(args) {
     const staleTag = stale ? ' ⚠️  STALE' : '';
     console.log(`  🔒 ${lock.target}`);
     console.log(`     Agent: ${agent} | Age: ${ageStr}${staleTag}`);
+    if (stale) {
+      console.log(`     Warning: ${FILE_FLOW_WARNING}`);
+    }
   }
 
   console.log('');