archbyte 0.4.2 → 0.5.1

package/README.md

@@ -8,40 +8,24 @@ AI-powered architecture visualization for your codebase. Analyzes code, generate
 # Install
 curl -fsSL https://archbyte.heartbyte.io/install.sh | bash
 
-# Sign in or create a free account
-archbyte login
-
-# Configure your AI provider (BYOK)
-archbyte init
-
-# Using Claude Code / Codex? Install the MCP server too:
-archbyte mcp install
+# Run (auto-configures on first use)
+archbyte run
 ```
 
-Your API keys stay on your machine. ArchByte never stores or transmits your provider credentials.
+On first run, ArchByte walks you through sign-in and provider setup interactively. Your API keys stay on your machine — ArchByte never stores or transmits your provider credentials.
 
-### Setup with Claude Code
+### Manual setup
 
-**Option A: MCP** — use ArchByte tools directly in Claude Code. You still need to sign in and configure a provider first:
+Prefer to configure each step separately:
 
 ```bash
-archbyte mcp install
-# or manually:
-claude mcp add archbyte --transport stdio -- npx -y archbyte@latest mcp
+archbyte login          # Sign in or create a free account
+archbyte init           # Configure your AI provider (BYOK)
 ```
 
-Then just ask Claude Code in plain English:
-
-```
-"Analyze the architecture of this project"
-"Export the architecture as a Mermaid diagram"
-"Show me the architecture stats"
-"Read the current architecture diagram"
-```
-
-Available MCP tools: `archbyte_analyze`, `archbyte_generate`, `archbyte_validate` (Pro), `archbyte_export`, `archbyte_stats`, `archbyte_diff`, `archbyte_read_diagram`.
+### Setup with Claude Code
 
-**Option B: Slash commands** — installed globally so they work in any project:
+Slash commands — installed globally so they work in any project:
 
 ```bash
 mkdir -p ~/.claude/commands

package/bin/archbyte.js

@@ -11,10 +11,7 @@ import { Command } from 'commander';
 import { handleServe } from '../dist/cli/serve.js';
 import { handleGenerate } from '../dist/cli/generate.js';
 import { handleStats } from '../dist/cli/stats.js';
-import { handleValidate } from '../dist/cli/validate.js';
 import { handleExport } from '../dist/cli/export.js';
-import { handleDiff } from '../dist/cli/diff.js';
-import { handlePatrol } from '../dist/cli/patrol.js';
 import { handleWorkflow } from '../dist/cli/workflow.js';
 import { handleAnalyze } from '../dist/cli/analyze.js';
 import { handleConfig } from '../dist/cli/config.js';
@@ -36,9 +33,13 @@ program
   .version(PKG_VERSION, '-v, --version', 'Show version number')
   .addHelpText('after', `
   Quick start:
+    $ archbyte run            Analyze + open diagram (auto-configures on first run)
+
+  Or step by step:
     $ archbyte login          Sign in or create a free account
     $ archbyte init           Configure your model provider
-    $ archbyte run            Analyze + open interactive diagram UI
+
+  Run from your project root, or pass --dir <path> to specify the directory.
 
   https://archbyte.heartbyte.io
 `);
@@ -93,7 +94,7 @@ program
   .option('--force', 'Force full re-scan (skip incremental detection)')
   .option('--dry-run', 'Preview without running')
   .action(async (options) => {
-    await requireLicense('analyze');
+    // handleRun manages login + setup + requireLicense internally
     await handleRun(options);
   });
 
@@ -145,27 +146,6 @@ program
     await handleStats(options);
   });
 
-program
-  .command('validate')
-  .description('Run architecture fitness function rules')
-  .option('-d, --diagram <path>', 'Path to architecture JSON (default: .archbyte/architecture.json)')
-  .option('-c, --config <path>', 'Path to archbyte.yaml config')
-  .option('--ci', 'Machine-readable JSON output for CI pipelines')
-  .action(async (options) => {
-    await requireLicense('analyze');
-    await handleValidate(options);
-  });
-
-program
-  .command('diff')
-  .description('Compare architecture snapshots and detect drift')
-  .requiredOption('-b, --baseline <path>', 'Path to baseline architecture JSON')
-  .option('-c, --current <path>', 'Path to current architecture JSON (default: .archbyte/architecture.json)')
-  .option('--config <path>', 'Path to archbyte.yaml config')
-  .action(async (options) => {
-    await handleDiff(options);
-  });
-
 program
   .command('export')
   .description('Export architecture to various formats')
@@ -178,21 +158,6 @@ program
 
 // — Advanced (Pro) —
 
-program
-  .command('patrol')
-  .description('Run continuous architecture health monitoring (Gastown-inspired patrol loop)')
-  .option('-d, --diagram <path>', 'Path to architecture JSON (default: .archbyte/architecture.json)')
-  .option('-c, --config <path>', 'Path to archbyte.yaml config')
-  .option('-i, --interval <duration>', 'Patrol interval: 30s, 5m, 1h (default: 5m)')
-  .option('--on-violation <action>', 'Action on new violations: log, json (default: log)')
-  .option('--once', 'Run a single patrol cycle then exit')
-  .option('-w, --watch', 'Watch source files for changes instead of polling on interval')
-  .option('--history', 'Show patrol history dashboard')
-  .action(async (options) => {
-    await requireLicense('analyze');
-    await handlePatrol(options);
-  });
-
 program
   .command('workflow')
   .description('Run composable architecture workflows (MEOW-inspired pipeline system)')

package/dist/agents/static/component-detector.js

@@ -1,75 +1,22 @@
 // Static Analysis — Component Detector
 // Detects project components via workspaces, conventional directories, build configs, or single-app fallback
 import { slugify, assignLayer } from "./utils.js";
-// Map well-known deps to architecturally significant tech names
-const TECH_MAP = {
-    react: "React", "react-dom": "React", "next": "Next.js", "vue": "Vue", "nuxt": "Nuxt",
-    svelte: "Svelte", angular: "Angular", "@angular/core": "Angular",
-    express: "Express", fastify: "Fastify", "@nestjs/core": "NestJS", hono: "Hono", koa: "Koa",
-    prisma: "Prisma", "@prisma/client": "Prisma", typeorm: "TypeORM", drizzle: "Drizzle",
-    sequelize: "Sequelize", mongoose: "Mongoose", pg: "PostgreSQL", mysql2: "MySQL",
-    redis: "Redis", ioredis: "Redis",
-    graphql: "GraphQL", "@apollo/server": "Apollo GraphQL",
-    "socket.io": "Socket.IO", ws: "WebSocket",
-    tailwindcss: "Tailwind CSS", "@xyflow/react": "React Flow",
-    commander: "Commander.js", yargs: "Yargs",
-    vite: "Vite", webpack: "Webpack", esbuild: "esbuild",
-    typescript: "TypeScript",
-    kafkajs: "Kafka", amqplib: "RabbitMQ", bullmq: "BullMQ", bull: "Bull",
-    stripe: "Stripe", "@stripe/stripe-js": "Stripe",
-    playwright: "Playwright", "@playwright/test": "Playwright",
-    jest: "Jest", vitest: "Vitest", mocha: "Mocha",
-    flutter: "Flutter",
-};
-// Conventional directory → type mapping (hint-based, not exclusive)
-const DIR_TYPE_HINTS = {
-    ui: { type: "frontend", label: "UI" },
-    web: { type: "frontend", label: "Web App" },
-    frontend: { type: "frontend", label: "Frontend" },
-    client: { type: "frontend", label: "Client" },
-    app: { type: "frontend", label: "App" },
-    server: { type: "api", label: "Server" },
-    api: { type: "api", label: "API" },
-    backend: { type: "api", label: "Backend" },
-    gateway: { type: "api", label: "Gateway" },
-    cli: { type: "service", label: "CLI" },
-    agents: { type: "library", label: "Agents" },
-    lib: { type: "library", label: "Library" },
-    packages: { type: "library", label: "Packages" },
-    shared: { type: "library", label: "Shared" },
-    common: { type: "library", label: "Common" },
-    cloud: { type: "service", label: "Cloud" },
-    infra: { type: "service", label: "Infrastructure" },
-    deploy: { type: "service", label: "Deployment" },
-    deployment: { type: "service", label: "Deployment" },
-    workers: { type: "worker", label: "Workers" },
-    jobs: { type: "worker", label: "Jobs" },
-    scripts: { type: "service", label: "Scripts" },
-    e2e: { type: "service", label: "E2E Tests" },
-    tests: { type: "service", label: "Tests" },
-    tools: { type: "service", label: "Tools" },
-    homepage: { type: "frontend", label: "Homepage" },
-    docs: { type: "service", label: "Docs" },
-};
-// Build config files that indicate a directory is a standalone component
-const BUILD_CONFIG_FILES = [
-    "package.json",
-    "Cargo.toml",
-    "go.mod",
-    "pyproject.toml",
-    "requirements.txt",
-    "setup.py",
-    "pubspec.yaml",
-    "build.gradle",
-    "pom.xml",
-    "Gemfile",
-    "Makefile",
-    "Dockerfile",
-    "wrangler.toml",
-    "tsconfig.json",
-];
+import { categorizeDep, categorizeAllDeps, ROLE_TO_TYPE, MANIFEST_FILES } from "./taxonomy.js";
 // Skip these dirs — not components
 import { EXCLUDED_DIRS as SKIP_DIRS } from "./excluded-dirs.js";
+// Structural inference patterns — framework-agnostic grep queries
+const STRUCTURAL_PROBES = [
+    // Frontend: renders UI to DOM / uses JSX components
+    { grep: "createRoot|ReactDOM|hydrateRoot|createApp.*mount|new Vue|bootstrapApplication", type: "frontend", label: "UI renderer" },
+    // API: defines HTTP route handlers
+    { grep: "app\\.(get|post|put|delete|use)\\(|router\\.|@(Get|Post|Put|Delete|Controller)|handle.*Request|Hono\\(", type: "api", label: "HTTP routes" },
+    // Worker: consumes from queue / processes jobs
+    { grep: "\\.process\\(|\\.consume\\(|new Worker\\(|@Processor|celery\\.task", type: "worker", label: "Job processor" },
+    // CLI: parses command-line args
+    { grep: "\\.command\\(|\\.parse\\(process\\.argv|argparse|@Command\\(", type: "service", label: "CLI" },
+    // Server: creates a network listener
+    { grep: "createServer\\(|listen\\(\\d|serve\\(|app\\.listen", type: "api", label: "Server" },
+];
 export async function detectComponents(tk, structure) {
     // Strategy 1: Monorepo workspaces
     if (structure.isMonorepo) {
@@ -157,8 +104,8 @@ async function resolveWorkspacePatterns(tk) {
 }
 /**
  * Scan every top-level directory. If it has a build config, README, Dockerfile,
- * or code files, treat it as a component. Use dir name hints + config file analysis
- * to determine type.
+ * or code files, treat it as a component. Use taxonomy + grep-based structural
+ * inference to determine type.
  */
 async function detectAllComponents(tk, structure) {
     const components = [];
@@ -171,7 +118,7 @@ async function detectAllComponents(tk, structure) {
             continue;
         const fileNames = entries.map((e) => e.name);
         // Check for build config files
-        const hasBuildConfig = BUILD_CONFIG_FILES.some((f) => fileNames.includes(f));
+        const hasBuildConfig = MANIFEST_FILES.some((f) => fileNames.includes(f));
         const hasCode = entries.some((e) => e.type === "file" &&
             /\.(ts|js|tsx|jsx|py|go|rs|java|rb|dart|kt|swift|c|cpp|cs)$/.test(e.name));
         const hasSrcDir = entries.some((e) => e.type === "directory" && (e.name === "src" || e.name === "lib" || e.name === "app"));
@@ -181,10 +128,12 @@ async function detectAllComponents(tk, structure) {
             continue;
         // Detect language + type + tech stack from config files
         const detected = await detectFromBuildConfigs(tk, dir, fileNames);
-        const hint = DIR_TYPE_HINTS[dir.toLowerCase()];
-        const type = detected.type ?? hint?.type ?? "service";
-        const label = hint?.label ?? capitalize(dir);
-        const name = label;
+        // If no type from deps, try grep-based structural inference
+        if (!detected.type) {
+            detected.type = await inferTypeFromCode(tk, dir);
+        }
+        const type = detected.type ?? "service";
+        const name = capitalize(dir);
         // Read description from sub-README if available
         let description = detected.description;
         if (!description && hasReadme) {
@@ -205,6 +154,21 @@ async function detectAllComponents(tk, structure) {
     }
     return components;
 }
+/**
+ * Infer component type by grepping actual code in the directory.
+ * Runs all probes in parallel — first match with hits wins.
+ */
+async function inferTypeFromCode(tk, dir) {
+    const results = await Promise.all(STRUCTURAL_PROBES.map(async (probe) => ({
+        ...probe,
+        hits: await tk.grepFiles(probe.grep, dir),
+    })));
+    for (const r of results) {
+        if (r.hits.length > 0)
+            return r.type;
+    }
+    return null;
+}
 async function detectFromBuildConfigs(tk, dir, fileNames) {
     const info = {
         type: null,
@@ -335,57 +299,57 @@ async function detectFromBuildConfigs(tk, dir, fileNames) {
     info.technologies = [...new Set(info.technologies)].slice(0, 5);
     return info;
 }
-function buildSingleAppComponent(structure) {
-    return {
-        id: slugify(structure.projectName) ?? "app",
-        name: structure.projectName || "Application",
-        type: structure.framework
-            ? (["React", "Vue", "Svelte", "Angular", "Next.js", "Nuxt"].includes(structure.framework)
-                ? "frontend"
-                : "api")
-            : "service",
-        layer: "application",
-        path: ".",
-        description: "",
-        technologies: [structure.language, structure.framework].filter(Boolean),
-    };
-}
+/** Detect component type from package.json dependencies using taxonomy */
 function detectTypeFromDeps(pkg) {
     const deps = Object.keys({
         ...pkg.dependencies,
         ...pkg.devDependencies,
     });
-    // Frontend indicators
-    if (deps.some((d) => ["react", "react-dom", "vue", "svelte", "@angular/core", "next", "nuxt"].includes(d))) {
-        return "frontend";
-    }
-    // API indicators
-    if (deps.some((d) => ["express", "fastify", "@nestjs/core", "hono", "koa"].includes(d))) {
-        return "api";
-    }
-    // Worker indicators
-    if (deps.some((d) => ["bullmq", "bull", "bee-queue"].includes(d))) {
-        return "worker";
-    }
-    // Test indicators
-    if (deps.some((d) => ["@playwright/test", "playwright", "cypress"].includes(d))) {
-        return "service";
+    // Priority: meta-framework > ui-framework > http-framework > queue > test
+    const priorityCategories = [
+        "meta-framework", "ui-framework", "http-framework", "queue-client", "test-framework",
+    ];
+    for (const targetCat of priorityCategories) {
+        for (const dep of deps) {
+            const cat = categorizeDep(dep);
+            if (cat?.category === targetCat) {
+                return ROLE_TO_TYPE[cat.role] ?? "service";
+            }
+        }
     }
     return "service";
 }
+/** Extract display-worthy tech stack names from deps using taxonomy */
 function extractTechStack(pkg) {
     const deps = Object.keys({
         ...pkg.dependencies,
         ...pkg.devDependencies,
     });
+    const categorized = categorizeAllDeps(deps);
+    const seen = new Set();
     const techs = [];
-    for (const dep of deps) {
-        if (TECH_MAP[dep] && !techs.includes(TECH_MAP[dep])) {
-            techs.push(TECH_MAP[dep]);
+    for (const cat of categorized.values()) {
+        if (!seen.has(cat.displayName)) {
+            seen.add(cat.displayName);
+            techs.push(cat.displayName);
         }
     }
     return techs.slice(0, 5);
 }
+function buildSingleAppComponent(structure) {
+    const type = structure.framework
+        ? (categorizeDep(structure.framework.toLowerCase())?.role === "frontend" ? "frontend" : "api")
+        : "service";
+    return {
+        id: slugify(structure.projectName) ?? "app",
+        name: structure.projectName || "Application",
+        type,
+        layer: "application",
+        path: ".",
+        description: "",
+        technologies: [structure.language, structure.framework].filter(Boolean),
+    };
+}
 function capitalize(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }

package/dist/agents/static/connection-mapper.js

@@ -2,6 +2,7 @@
 // Maps connections between components via imports, Docker, K8s, env vars, known SDKs
 // Only deterministic matches — ambiguous mappings are left as gaps for the LLM
 import { slugify } from "./utils.js";
+import { categorizeDep } from "./taxonomy.js";
 export async function mapConnections(tk, components, infra, events, importMap) {
     const connections = [];
     const componentIds = new Set(components.map((c) => c.id));
@@ -194,34 +195,32 @@ async function detectServerServesUI(tk, components, connections) {
     }
 }
 async function detectKnownSDKConnections(components, connections) {
-    const externalTechs = {
-        Stripe: "stripe-api",
-        Firebase: "firebase",
-        Supabase: "supabase",
-        Redis: "redis",
-        Kafka: "kafka",
-        RabbitMQ: "rabbitmq",
-        "Socket.IO": "websocket",
-        PostgreSQL: "database",
-        MySQL: "database",
-        MongoDB: "database",
+    // Role → connection type mapping
+    const roleToConnType = {
+        data: "database",
+        messaging: "queue",
+        external: "http",
     };
     for (const comp of components) {
         for (const tech of comp.technologies) {
-            const externalId = externalTechs[tech];
-            if (externalId) {
-                const target = components.find((c) => c.id !== comp.id && (c.technologies.includes(tech) ||
-                    c.type === "database" && (externalId === "database")));
-                if (target) {
-                    connections.push({
-                        from: comp.id,
-                        to: target.id,
-                        type: externalId === "database" ? "database" : "http",
-                        description: `${comp.name} uses ${tech}`,
-                        confidence: 95,
-                        async: false,
-                    });
-                }
+            // Use taxonomy to determine the role/connection type of this tech
+            const cat = categorizeDep(tech.toLowerCase());
+            if (!cat)
+                continue;
+            const connType = roleToConnType[cat.role];
+            if (!connType)
+                continue;
+            const target = components.find((c) => c.id !== comp.id && (c.technologies.includes(tech) ||
+                (c.type === "database" && connType === "database")));
+            if (target) {
+                connections.push({
+                    from: comp.id,
+                    to: target.id,
+                    type: connType,
+                    description: `${comp.name} uses ${tech}`,
+                    confidence: 95,
+                    async: false,
+                });
             }
         }
     }

package/dist/agents/static/deep-drill.d.ts

@@ -0,0 +1,72 @@
+import type { TreeEntry } from "./types.js";
+export interface DeepDrillResult {
+    componentId: string;
+    componentName: string;
+    componentPath: string;
+    scannedAt: string;
+    durationMs: number;
+    fileTree: TreeEntry[];
+    metrics: {
+        fileCount: number;
+        codeFileCount: number;
+        totalLines: number;
+        languages: Array<{
+            language: string;
+            files: number;
+        }>;
+    };
+    structure: {
+        entryPoints: string[];
+        keyFiles: Array<{
+            path: string;
+            role: string;
+        }>;
+        publicExports: string[];
+        directories: string[];
+    };
+    dependencies: {
+        manifest: string | null;
+        production: Array<{
+            name: string;
+            category: string | null;
+            displayName: string;
+        }>;
+        development: Array<{
+            name: string;
+            category: string | null;
+            displayName: string;
+        }>;
+    };
+    imports: {
+        internalImports: Array<{
+            targetPath: string;
+            sourceFiles: string[];
+        }>;
+        externalPackages: string[];
+    };
+    patterns: Array<{
+        type: string;
+        label: string;
+        matches: Array<{
+            file: string;
+            line: string;
+            content: string;
+        }>;
+        count: number;
+    }>;
+    connections: {
+        outgoing: Array<{
+            targetId: string;
+            targetName: string;
+            type: string;
+            description: string;
+        }>;
+        incoming: Array<{
+            sourceId: string;
+            sourceName: string;
+            type: string;
+            description: string;
+        }>;
+    };
+}
+export declare function runDeepDrill(projectRoot: string, componentId: string, componentName: string, componentPath: string): Promise<DeepDrillResult>;