feat: implement visual dashboard and enhanced intelligence

- add scoring for copy-suffix duplicates (prioritizing originals)
- implement archive vs. extracted folder detection
- create REST API backend for dashboard
- build modern React/Vite dashboard for visual review
- add ui:build and ui CLI commands

Author: ptkvaibhav

package.json

@@ -34,9 +34,11 @@
     "check:quality": "node scripts/check-quality.js",
     "check:security": "node scripts/check-security.js",
     "test:smoke": "node scripts/run-smoke.js",
-    "test": "node --test test/engagement.test.js test/executor.test.js test/local-audit.test.js test/local-drive.test.js test/protection.test.js test/review-queue.test.js"
+    "test": "node --test test/engagement.test.js test/executor.test.js test/local-audit.test.js test/local-drive.test.js test/protection.test.js test/review-queue.test.js",
+    "ui:build": "cd ui && npm run build"
   },
   "dependencies": {
-    "better-sqlite3": "^12.9.0"
+    "better-sqlite3": "^12.9.0",
+    "express": "^5.2.1"
   }
 }

src/cli.js

@@ -18,6 +18,7 @@ import { ensureLocalDriveScaffold, getLocalDriveStatus } from "./providers/local
 import { createMockProviderSnapshots } from "./providers/mock-snapshots.js";
 import { explainPricingStrategy } from "./advisory/pricing-catalog.js";
 import { Catalog } from "./core/catalog.js";
+import { startServer } from "./server.js";
 
 const [, , command, ...args] = process.argv;
 const DEFAULT_DB_PATH = ".nyx/nyx.db";
@@ -47,7 +48,8 @@ const handlers = {
   "sync-file": runSyncFile,
   decide: runDecide,
   fingerprint: runFingerprint,
-  classify: runClassify
+  classify: runClassify,
+  ui: runUi
 };
 
 async function main() {
@@ -392,6 +394,12 @@ async function runClassify(args) {
   console.log(JSON.stringify(classifyFile(fileProfile), null, 2));
 }
 
+async function runUi(args) {
+  const port = parseInt(args[0] ?? "3000", 10);
+  const dbPath = args[1] ?? DEFAULT_DB_PATH;
+  await startServer({ port, dbPath });
+}
+
 async function buildProfileForClassification(filePath) {
   const profile = await fingerprintFile(filePath);
   return {
@@ -416,6 +424,7 @@ function printUsage() {
   console.log("- plan");
   console.log("- doctor");
   console.log("- demo");
+  console.log("- ui [port] [db-path]");
   console.log("- engagement-summary [engagement-path]");
   console.log("- audit-local [engagement-path]");
   console.log("- review-local [engagement-path]");

src/organization/irrelevance.js

@@ -1,18 +1,62 @@
+import path from "node:path";
 import { isEligibleDuplicateGroup } from "./eligibility.js";
 
-export function findIrrelevanceFindings({ duplicates = [], configuredRules = [] } = {}) {
+export function findIrrelevanceFindings({ duplicates = [], files = [], directories = [], configuredRules = [] } = {}) {
   const normalizedRules = configuredRules.map((rule) => rule.toLowerCase());
   const findings = [];
 
   if (normalizedRules.includes("exact duplicate files by content hash")) {
     findings.push(...duplicates.filter(isEligibleDuplicateGroup).map(buildDuplicateFinding));
   }
 
+  // New rule: redundant archives
+  findings.push(...findExtractedArchives({ files, directories }));
+
   return findings.sort((left, right) => left.id.localeCompare(right.id));
 }
 
+function findExtractedArchives({ files, directories }) {
+  const findings = [];
+  const ARCHIVE_EXTENSIONS = [".zip", ".7z", ".rar", ".tar", ".gz", ".tgz"];
+  const directoryPaths = new Set(directories.map(d => d.absolutePath.toLowerCase()));
+
+  for (const file of files) {
+    const baseName = file.baseName || path.basename(file.absolutePath || "");
+    if (!baseName) continue;
+
+    const ext = path.extname(baseName).toLowerCase();
+    if (!ARCHIVE_EXTENSIONS.includes(ext)) continue;
+
+    const baseNameWithoutExt = baseName.slice(0, -ext.length);
+    const possibleDirPath = path.join(path.dirname(file.absolutePath), baseNameWithoutExt);
+
+    if (directoryPaths.has(possibleDirPath.toLowerCase())) {
+      findings.push({
+        id: `irrelevance:extracted_archive:${file.sha256}:${file.relativePath}`,
+        type: "irrelevance_finding",
+        action: "review_archive_cleanup",
+        status: "pending_user_approval",
+        approvalGate: "deleting irrelevant files",
+        risk: "destructive",
+        subjectPath: file.absolutePath,
+        matchedRule: "archive exists alongside extracted folder",
+        confidence: "medium",
+        reviewOnly: true,
+        evidence: {
+          archivePath: file.absolutePath,
+          extractedFolderPath: possibleDirPath,
+          reasons: ["This archive appears to have been extracted into a folder in the same location."]
+        }
+      });
+    }
+  }
+
+  return findings;
+}
+
 function buildDuplicateFinding(group) {
-  const [proposedKeepFile, ...proposedDeleteFiles] = group.files;
+  const proposedKeepFile = identifyProposedKeepFile(group.files);
+  const proposedDeleteFiles = group.files.filter((file) => file.absolutePath !== proposedKeepFile.absolutePath);
 
   return {
     id: `irrelevance:duplicate:${group.sha256}`,
@@ -37,3 +81,27 @@ function buildDuplicateFinding(group) {
     }
   };
 }
+
+function identifyProposedKeepFile(files) {
+  // Score files based on "originality" (lower score is better/more original)
+  const scoredFiles = files.map((file) => {
+    let score = 0;
+    const name = file.baseName || path.basename(file.absolutePath || "");
+
+    // Penalize common download suffixes
+    if (name) {
+        const baseNameOnly = path.parse(name.toLowerCase()).name;
+        if (/\(\d+\)$/.test(baseNameOnly)) score += 10;
+        if (name.toLowerCase().includes("copy")) score += 5;
+        if (name.toLowerCase().includes("duplicate")) score += 5;
+    }
+
+    // Prefer shorter paths (usually more root-level/intentional)
+    score += (file.relativePath || "").split("/").length;
+
+    return { file, score };
+  });
+
+  scoredFiles.sort((a, b) => a.score - b.score);
+  return scoredFiles[0].file;
+}

src/organization/local-audit.js

@@ -63,6 +63,8 @@ export async function buildLocalAudit({
   const organizationProposals = buildOrganizationProposals(files);
   const irrelevanceFindings = findIrrelevanceFindings({
     duplicates,
+    files,
+    directories: scanResult.directories,
     configuredRules: engagement.safeIrrelevanceRules
   });
 

src/organization/scan-managed.js

@@ -4,6 +4,7 @@ import path from "node:path";
 export async function scanManagedDirectories({ managedDirectories, exclusions = [] }) {
   const normalizedExclusions = exclusions.map((entry) => normalizeSegment(entry));
   const files = [];
+  const directories = [];
   const roots = [];
   const missingDirectories = [];
 
@@ -12,14 +13,17 @@ export async function scanManagedDirectories({ managedDirectories, exclusions =
 
     try {
       const rootFiles = [];
+      const rootDirs = [];
       await walkDirectory({
         rootPath,
         currentPath: rootPath,
         exclusions: normalizedExclusions,
-        files: rootFiles
+        files: rootFiles,
+        directories: rootDirs
       });
 
       files.push(...rootFiles);
+      directories.push(...rootDirs);
       roots.push({
         rootPath,
         fileCount: rootFiles.length
@@ -36,12 +40,13 @@ export async function scanManagedDirectories({ managedDirectories, exclusions =
 
   return {
     files,
+    directories,
     roots,
     missingDirectories
   };
 }
 
-async function walkDirectory({ rootPath, currentPath, exclusions, files }) {
+async function walkDirectory({ rootPath, currentPath, exclusions, files, directories }) {
   const entries = await readdir(currentPath, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -53,11 +58,17 @@ async function walkDirectory({ rootPath, currentPath, exclusions, files }) {
     }
 
     if (entry.isDirectory()) {
+      directories.push({
+        rootPath,
+        absolutePath,
+        relativePath
+      });
       await walkDirectory({
         rootPath,
         currentPath: absolutePath,
         exclusions,
-        files
+        files,
+        directories
       });
       continue;
     }
@@ -92,4 +103,3 @@ function normalizeSegment(value) {
 function isMissingPathError(error) {
   return error?.code === "ENOENT" || error?.code === "ENOTDIR";
 }
-

src/server.js

@@ -0,0 +1,92 @@
+import express from "express";
+import path from "node:path";
+import { Catalog } from "./core/catalog.js";
+import { applyApprovedReview } from "./organization/executor.js";
+
+const DEFAULT_DB_PATH = ".nyx/nyx.db";
+
+export async function startServer({ port = 3000, dbPath = DEFAULT_DB_PATH } = {}) {
+  const app = express();
+  const catalog = await Catalog.open(dbPath);
+
+  app.use(express.json());
+
+  // API Routes
+  app.get("/api/overview", async (req, res) => {
+    try {
+      const files = catalog.getAllFiles();
+      const items = catalog.getPendingReviewItems();
+      
+      const stats = {
+        totalFiles: files.length,
+        totalSize: files.reduce((sum, f) => sum + f.sizeBytes, 0),
+        pendingItems: items.length,
+        duplicates: items.filter(i => i.action === "review_duplicate_deletion").length,
+        proposals: items.filter(i => i.type === "organization_proposal").length,
+        archives: items.filter(i => i.action === "review_archive_cleanup").length
+      };
+
+      res.json(stats);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  app.get("/api/items", async (req, res) => {
+    try {
+      const items = catalog.getPendingReviewItems();
+      res.json(items);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  app.post("/api/items/:id/approve", async (req, res) => {
+    try {
+      const { id } = req.params;
+      if (id === "all") {
+        catalog.approveAllReviewItems();
+      } else {
+        catalog.approveReviewItem(id);
+      }
+      res.json({ success: true });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  app.post("/api/apply", async (req, res) => {
+    try {
+      const result = await applyApprovedReview({ catalog });
+      res.json(result);
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  // Serve UI static files
+  const uiPath = path.resolve("ui/dist");
+  app.use(express.static(uiPath));
+
+  // Final fallback for React routing - using a middleware without a path to avoid regex issues
+  app.use((req, res, next) => {
+    // If it's an API call that didn't match, 404
+    if (req.path.startsWith("/api")) {
+      return res.status(404).json({ error: "API route not found" });
+    }
+    
+    // Otherwise serve index.html
+    res.sendFile(path.join(uiPath, "index.html"), (err) => {
+      if (err) {
+        res.status(404).send("Nyx Dashboard UI not built yet. Run 'npm run ui:build' in the ui directory.");
+      }
+    });
+  });
+
+  return new Promise((resolve) => {
+    const server = app.listen(port, () => {
+      console.log(`Nyx Dashboard running at http://localhost:${port}`);
+      resolve(server);
+    });
+  });
+}

ui/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?