archbyte 0.1.0

package/dist/agents/static/structure-scanner.js

@@ -0,0 +1,195 @@
+// Static Analysis — Structure Scanner
+// Detects project language, framework, monorepo, package manager, entry points
+export async function scanStructure(tk) {
+    const result = {
+        projectName: "",
+        language: "unknown",
+        languages: [],
+        framework: null,
+        packageManager: null,
+        isMonorepo: false,
+        monorepoTool: null,
+        entryPoints: [],
+        buildSystem: null,
+        testFramework: null,
+        directories: {},
+    };
+    // Read config files in parallel
+    const [pkg, cargoToml, goMod, pyProject, tsconfig] = await Promise.all([
+        tk.readJSON("package.json"),
+        tk.readFileSafe("Cargo.toml"),
+        tk.readFileSafe("go.mod"),
+        tk.readFileSafe("pyproject.toml"),
+        tk.readJSON("tsconfig.json"),
+    ]);
+    // Project name
+    if (pkg?.name) {
+        result.projectName = pkg.name;
+    }
+    else if (goMod) {
+        const match = goMod.match(/^module\s+(.+)/m);
+        if (match)
+            result.projectName = match[1].split("/").pop() ?? match[1];
+    }
+    // Language detection
+    if (tsconfig) {
+        result.language = "TypeScript";
+        result.languages.push("TypeScript");
+    }
+    if (pkg && !tsconfig) {
+        result.languages.push("JavaScript");
+        if (result.language === "unknown")
+            result.language = "JavaScript";
+    }
+    if (cargoToml) {
+        result.languages.push("Rust");
+        if (result.language === "unknown")
+            result.language = "Rust";
+    }
+    if (goMod) {
+        result.languages.push("Go");
+        if (result.language === "unknown")
+            result.language = "Go";
+    }
+    if (pyProject) {
+        result.languages.push("Python");
+        if (result.language === "unknown")
+            result.language = "Python";
+    }
+    // Framework detection from deps
+    if (pkg) {
+        const allDeps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+        };
+        const depNames = Object.keys(allDeps);
+        // JS/TS frameworks
+        if (depNames.includes("next"))
+            result.framework = "Next.js";
+        else if (depNames.includes("nuxt"))
+            result.framework = "Nuxt";
+        else if (depNames.includes("@nestjs/core"))
+            result.framework = "NestJS";
+        else if (depNames.includes("fastify"))
+            result.framework = "Fastify";
+        else if (depNames.includes("express"))
+            result.framework = "Express";
+        else if (depNames.includes("hono"))
+            result.framework = "Hono";
+        else if (depNames.includes("react"))
+            result.framework = "React";
+        else if (depNames.includes("vue"))
+            result.framework = "Vue";
+        else if (depNames.includes("svelte"))
+            result.framework = "Svelte";
+        else if (depNames.includes("angular"))
+            result.framework = "Angular";
+        // Test framework
+        if (depNames.includes("vitest"))
+            result.testFramework = "Vitest";
+        else if (depNames.includes("jest"))
+            result.testFramework = "Jest";
+        else if (depNames.includes("mocha"))
+            result.testFramework = "Mocha";
+        // Build system
+        if (depNames.includes("vite"))
+            result.buildSystem = "Vite";
+        else if (depNames.includes("webpack"))
+            result.buildSystem = "Webpack";
+        else if (depNames.includes("esbuild"))
+            result.buildSystem = "esbuild";
+        else if (depNames.includes("rollup"))
+            result.buildSystem = "Rollup";
+        // Monorepo detection
+        if (pkg.workspaces) {
+            result.isMonorepo = true;
+            result.monorepoTool = "npm-workspaces";
+        }
+    }
+    // Python frameworks
+    if (pyProject) {
+        if (pyProject.includes("django"))
+            result.framework = "Django";
+        else if (pyProject.includes("fastapi"))
+            result.framework = "FastAPI";
+        else if (pyProject.includes("flask"))
+            result.framework = "Flask";
+    }
+    // Rust frameworks
+    if (cargoToml) {
+        if (cargoToml.includes("axum"))
+            result.framework = "Axum";
+        else if (cargoToml.includes("actix"))
+            result.framework = "Actix";
+        else if (cargoToml.includes("rocket"))
+            result.framework = "Rocket";
+        result.buildSystem = "Cargo";
+    }
+    // Go frameworks
+    if (goMod) {
+        if (goMod.includes("gin-gonic"))
+            result.framework = "Gin";
+        else if (goMod.includes("labstack/echo"))
+            result.framework = "Echo";
+        else if (goMod.includes("go-fiber"))
+            result.framework = "Fiber";
+        result.buildSystem = "Go";
+    }
+    // Monorepo tools (check files in parallel)
+    const [nxJson, turboJson, lernaJson, pnpmWorkspace] = await Promise.all([
+        tk.readJSON("nx.json"),
+        tk.readJSON("turbo.json"),
+        tk.readJSON("lerna.json"),
+        tk.readFileSafe("pnpm-workspace.yaml"),
+    ]);
+    if (nxJson) {
+        result.isMonorepo = true;
+        result.monorepoTool = "nx";
+    }
+    if (turboJson) {
+        result.isMonorepo = true;
+        result.monorepoTool = "turborepo";
+    }
+    if (lernaJson) {
+        result.isMonorepo = true;
+        result.monorepoTool = "lerna";
+    }
+    if (pnpmWorkspace) {
+        result.isMonorepo = true;
+        result.monorepoTool = "pnpm";
+    }
+    // Package manager detection
+    const [hasPackageLock, hasYarnLock, hasPnpmLock, hasBunLock] = await Promise.all([
+        tk.readFileSafe("package-lock.json").then((c) => !!c),
+        tk.readFileSafe("yarn.lock").then((c) => !!c),
+        tk.readFileSafe("pnpm-lock.yaml").then((c) => !!c),
+        tk.readFileSafe("bun.lockb").then((c) => !!c),
+    ]);
+    if (hasPnpmLock)
+        result.packageManager = "pnpm";
+    else if (hasYarnLock)
+        result.packageManager = "yarn";
+    else if (hasBunLock)
+        result.packageManager = "bun";
+    else if (hasPackageLock)
+        result.packageManager = "npm";
+    // Entry points
+    if (pkg?.main)
+        result.entryPoints.push(pkg.main);
+    if (pkg?.bin) {
+        const bin = pkg.bin;
+        if (typeof bin === "string") {
+            result.entryPoints.push(bin);
+        }
+        else if (typeof bin === "object") {
+            result.entryPoints.push(...Object.values(bin));
+        }
+    }
+    // Directory structure
+    const rootEntries = await tk.listDir(".");
+    const dirs = rootEntries.filter((e) => e.type === "directory").map((e) => e.name);
+    for (const d of dirs) {
+        result.directories[d] = true;
+    }
+    return result;
+}

package/dist/agents/static/types.d.ts

@@ -0,0 +1,165 @@
+export interface StructureResult {
+    projectName: string;
+    language: string;
+    languages: string[];
+    framework: string | null;
+    packageManager: string | null;
+    isMonorepo: boolean;
+    monorepoTool: string | null;
+    entryPoints: string[];
+    buildSystem: string | null;
+    testFramework: string | null;
+    directories: Record<string, boolean>;
+}
+export interface DocResult {
+    projectDescription: string;
+    architectureNotes: string[];
+    apiEndpoints: Array<{
+        method: string;
+        path: string;
+        description: string;
+    }>;
+    externalDependencies: string[];
+}
+export interface ComponentResult {
+    components: StaticComponent[];
+}
+export interface StaticComponent {
+    id: string;
+    name: string;
+    type: string;
+    layer: string;
+    path: string;
+    description: string;
+    technologies: string[];
+}
+export interface InfraResult {
+    docker: {
+        services: Array<{
+            name: string;
+            image?: string;
+            buildContext?: string;
+            ports?: string[];
+            dependsOn?: string[];
+            environment?: Record<string, string>;
+        }>;
+        composeFile: boolean;
+        composeFilePath?: string;
+    };
+    kubernetes: {
+        resources: Array<{
+            kind: string;
+            name: string;
+            namespace?: string;
+        }>;
+    };
+    cloud: {
+        provider: string | null;
+        services: string[];
+        iac: string | null;
+    };
+    ci: {
+        platform: string | null;
+        pipelines: string[];
+    };
+}
+export interface EventResult {
+    hasEDA: boolean;
+    patterns: Array<{
+        technology: string;
+        dependency: string;
+    }>;
+    events: Array<{
+        type: string;
+        file: string;
+        pattern: string;
+    }>;
+}
+export interface EnvResult {
+    environments: Array<{
+        name: string;
+        variables: string[];
+    }>;
+    configPattern: string | null;
+    hasSecrets: boolean;
+}
+export interface StaticConnection {
+    from: string;
+    to: string;
+    type: string;
+    description: string;
+    confidence: number;
+    async: boolean;
+}
+export interface ConnectionResult {
+    connections: StaticConnection[];
+    flows: Array<{
+        name: string;
+        description: string;
+        steps: string[];
+    }>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    repairs: string[];
+    errors: string[];
+}
+/**
+ * A gap identified by static analysis that the LLM should try to resolve.
+ * Each gap is a generic question/uncertainty — not project-specific.
+ */
+export interface AnalysisGap {
+    /** Category of the gap */
+    category: "unresolved_docker_service" | "isolated_component" | "weak_description" | "missing_database" | "unmodeled_external_service" | "unmapped_api_endpoints" | "event_pattern_no_connection" | "ambiguous_component_type" | "unknown_primary_language";
+    /** Human-readable description of the gap */
+    description: string;
+    /** IDs of related components (if any) */
+    relatedComponentIds?: string[];
+    /** Raw context data the LLM can use to resolve this gap */
+    context?: Record<string, unknown>;
+}
+export interface StaticAnalysisResult {
+    structure: StructureResult;
+    docs: DocResult;
+    components: ComponentResult;
+    infra: InfraResult;
+    events: EventResult;
+    envs: EnvResult;
+    connections: ConnectionResult;
+    validation: ValidationResult;
+    /** Gaps the static analysis couldn't resolve — passed to LLM for resolution */
+    gaps: AnalysisGap[];
+}
+export interface TreeEntry {
+    path: string;
+    type: "file" | "directory";
+    children?: TreeEntry[];
+}
+export interface FileTreeResult {
+    tree: TreeEntry[];
+    totalFiles: number;
+    totalDirs: number;
+}
+export interface FileSample {
+    path: string;
+    excerpt: string;
+    category: "entry-point" | "config" | "route-file" | "model-file";
+}
+export interface ConfigSample {
+    path: string;
+    content: string;
+}
+export interface CodeSampleResult {
+    samples: FileSample[];
+    importMap: Record<string, string[]>;
+    configFiles: ConfigSample[];
+}
+export interface StaticContext {
+    structure: StructureResult;
+    docs: DocResult;
+    infra: InfraResult;
+    events: EventResult;
+    envs: EnvResult;
+    fileTree: FileTreeResult;
+    codeSamples: CodeSampleResult;
+}

package/dist/agents/static/types.js

@@ -0,0 +1,2 @@
+// Static Analysis — Result Interfaces
+export {};

package/dist/agents/static/utils.d.ts

@@ -0,0 +1,21 @@
+import type { GrepResult, DirEntry } from "../runtime/types.js";
+/**
+ * Wraps LocalFSBackend with safe-read helpers for static scanners.
+ */
+export declare class StaticToolkit {
+    private fs;
+    constructor(projectRoot: string);
+    readFileSafe(path: string): Promise<string | null>;
+    globFiles(pattern: string, cwd?: string): Promise<string[]>;
+    grepFiles(pattern: string, searchPath?: string): Promise<GrepResult[]>;
+    listDir(dirPath: string): Promise<DirEntry[]>;
+    readJSON(path: string): Promise<Record<string, unknown> | null>;
+    readYAML(path: string): Promise<unknown>;
+    readYAMLAll(path: string): Promise<unknown[]>;
+}
+export declare function slugify(name: string | undefined): string | undefined;
+export declare function mapComponentType(type: string | undefined): string;
+/**
+ * Assign a layer based on component type.
+ */
+export declare function assignLayer(type: string): string;

package/dist/agents/static/utils.js

@@ -0,0 +1,146 @@
+// Static Analysis — Shared Utilities
+import yaml from "js-yaml";
+import { LocalFSBackend } from "../tools/local-fs.js";
+/**
+ * Wraps LocalFSBackend with safe-read helpers for static scanners.
+ */
+export class StaticToolkit {
+    fs;
+    constructor(projectRoot) {
+        this.fs = new LocalFSBackend(projectRoot);
+    }
+    async readFileSafe(path) {
+        try {
+            return await this.fs.readFile(path);
+        }
+        catch {
+            return null;
+        }
+    }
+    async globFiles(pattern, cwd) {
+        try {
+            // Expand brace patterns like *.{yml,yaml} → [*.yml, *.yaml]
+            const patterns = expandBraces(pattern);
+            if (patterns.length === 1) {
+                return await this.fs.glob(patterns[0], cwd);
+            }
+            const resultSets = await Promise.all(patterns.map((p) => this.fs.glob(p, cwd).catch(() => [])));
+            // Deduplicate and sort
+            return [...new Set(resultSets.flat())].sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    async grepFiles(pattern, searchPath) {
+        try {
+            // Work around LocalFSBackend.grep glob bug with cwd:
+            // grep from root and filter by path prefix
+            const results = await this.fs.grep(pattern);
+            if (!searchPath)
+                return results;
+            const prefix = searchPath.endsWith("/") ? searchPath : `${searchPath}/`;
+            return results.filter((r) => r.file.startsWith(prefix));
+        }
+        catch {
+            return [];
+        }
+    }
+    async listDir(dirPath) {
+        try {
+            return await this.fs.listDir(dirPath);
+        }
+        catch {
+            return [];
+        }
+    }
+    async readJSON(path) {
+        const content = await this.readFileSafe(path);
+        if (!content)
+            return null;
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async readYAML(path) {
+        const content = await this.readFileSafe(path);
+        if (!content)
+            return null;
+        try {
+            return yaml.load(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async readYAMLAll(path) {
+        const content = await this.readFileSafe(path);
+        if (!content)
+            return [];
+        try {
+            return yaml.loadAll(content);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+export function slugify(name) {
+    if (!name)
+        return undefined;
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export function mapComponentType(type) {
+    if (!type)
+        return "service";
+    const t = type.toLowerCase();
+    if (t.includes("frontend") || t.includes("ui") || t.includes("web"))
+        return "frontend";
+    if (t.includes("api") || t.includes("gateway"))
+        return "api";
+    if (t.includes("database") || t.includes("db"))
+        return "database";
+    if (t.includes("worker") || t.includes("job") || t.includes("queue"))
+        return "worker";
+    if (t.includes("library") || t.includes("lib") || t.includes("package"))
+        return "library";
+    if (t.includes("cli") || t.includes("command"))
+        return "service";
+    if (t.includes("cache"))
+        return "cache";
+    return "service";
+}
+/**
+ * Assign a layer based on component type.
+ */
+export function assignLayer(type) {
+    switch (type) {
+        case "frontend":
+        case "cli":
+        case "gateway":
+            return "presentation";
+        case "database":
+            return "data";
+        case "external":
+            return "external";
+        default:
+            return "application";
+    }
+}
+/**
+ * Expand simple brace patterns: "*.{a,b}" → ["*.a", "*.b"]
+ * Handles one level of braces only (sufficient for our glob patterns).
+ */
+function expandBraces(pattern) {
+    const match = pattern.match(/^(.*)\{([^}]+)\}(.*)$/);
+    if (!match)
+        return [pattern];
+    const [, prefix, alternatives, suffix] = match;
+    return alternatives.split(",").map((alt) => `${prefix}${alt}${suffix}`);
+}

package/dist/agents/static/validator.d.ts

@@ -0,0 +1,2 @@
+import type { StaticAnalysisResult, ValidationResult } from "./types.js";
+export declare function validateAnalysis(analysis: StaticAnalysisResult): ValidationResult;

package/dist/agents/static/validator.js

@@ -0,0 +1,75 @@
+// Static Analysis — Validator
+// Referential integrity checks, dedup, auto-repair
+export function validateAnalysis(analysis) {
+    const result = {
+        valid: true,
+        repairs: [],
+        errors: [],
+    };
+    const componentIds = new Set(analysis.components.components.map((c) => c.id));
+    // Check: at least 1 component
+    if (componentIds.size === 0) {
+        result.errors.push("No components detected");
+        result.valid = false;
+    }
+    // Check: no duplicate component IDs
+    const idCounts = new Map();
+    for (const c of analysis.components.components) {
+        idCounts.set(c.id, (idCounts.get(c.id) ?? 0) + 1);
+    }
+    for (const [id, count] of idCounts) {
+        if (count > 1) {
+            result.repairs.push(`Deduplicated component ID: ${id} (appeared ${count}x)`);
+        }
+    }
+    // Dedup components
+    const seenIds = new Set();
+    analysis.components.components = analysis.components.components.filter((c) => {
+        if (seenIds.has(c.id))
+            return false;
+        seenIds.add(c.id);
+        return true;
+    });
+    // Check: every connection from/to references existing component ID
+    const validConnections = [];
+    for (const conn of analysis.connections.connections) {
+        if (!componentIds.has(conn.from)) {
+            result.repairs.push(`Removed connection: unknown source "${conn.from}"`);
+            continue;
+        }
+        if (!componentIds.has(conn.to)) {
+            result.repairs.push(`Removed connection: unknown target "${conn.to}"`);
+            continue;
+        }
+        if (conn.from === conn.to) {
+            result.repairs.push(`Removed self-connection: ${conn.from}`);
+            continue;
+        }
+        validConnections.push(conn);
+    }
+    // Dedup connections
+    const connSeen = new Set();
+    analysis.connections.connections = validConnections.filter((c) => {
+        const key = `${c.from}::${c.to}::${c.type}`;
+        if (connSeen.has(key)) {
+            result.repairs.push(`Deduplicated connection: ${key}`);
+            return false;
+        }
+        connSeen.add(key);
+        return true;
+    });
+    // Assign stable slugified IDs to any components missing them
+    for (const comp of analysis.components.components) {
+        if (!comp.id) {
+            comp.id = comp.name
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "");
+            result.repairs.push(`Assigned ID to component: ${comp.name} → ${comp.id}`);
+        }
+    }
+    if (result.repairs.length > 0 || result.errors.length > 0) {
+        result.valid = result.errors.length === 0;
+    }
+    return result;
+}

package/dist/agents/tools/claude-code.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Claude Code Tool Backend
+ *
+ * When archbyte runs inside Claude Code (via /archbyte-analyze skill),
+ * this backend bridges to Claude Code's native tools (Glob, Grep, Read)
+ * instead of using the local filesystem directly.
+ *
+ * This gives the best analysis quality — Claude's tools are optimized
+ * for code understanding and handle large repos efficiently.
+ */
+import type { ToolBackend, GrepResult, DirEntry } from "../runtime/types.js";
+/**
+ * ClaudeCodeBackend — uses the same local FS operations as LocalFSBackend
+ * but is designed to be instantiated when running inside Claude Code.
+ *
+ * In practice, when archbyte is invoked via a Claude Code skill,
+ * Claude Code's Task agents run the archbyte agent pipeline.
+ * The agents use tool_use calls which are executed by the orchestrator
+ * against this backend — which reads the local filesystem that
+ * Claude Code also has access to.
+ *
+ * The key difference from LocalFSBackend:
+ * - Optimized for the files Claude Code has already discovered
+ * - Can accept a pre-scanned file list to avoid redundant discovery
+ * - Respects .gitignore and Claude Code's file filtering
+ */
+export declare class ClaudeCodeBackend implements ToolBackend {
+    private root;
+    private preScannedFiles?;
+    constructor(projectRoot: string, preScannedFiles?: string[]);
+    readFile(filePath: string): Promise<string>;
+    glob(pattern: string): Promise<string[]>;
+    grep(pattern: string, searchPath?: string): Promise<GrepResult[]>;
+    listDir(dirPath: string): Promise<DirEntry[]>;
+    private resolvePath;
+    private walk;
+    private globToRegex;
+}