archbyte 0.5.2 → 0.5.3

package/bin/archbyte.js

@@ -98,6 +98,7 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .option('--force', 'Force full re-scan (skip incremental detection)')
   .option('--dry-run', 'Preview without running')
+  .option('--debug', 'Show transparency report (what data is collected and sent)')
   .action(async (options) => {
     // handleRun manages login + setup + requireLicense internally
     await handleRun(options);
@@ -115,6 +116,7 @@ program
   .option('--skip-llm', 'Alias for --static')
   .option('--force', 'Force full re-scan (skip incremental detection)')
   .option('--dry-run', 'Preview without running')
+  .option('--debug', 'Show transparency report (what data is collected and sent)')
   .action(async (options) => {
     await gate('analyze');
     await handleAnalyze(options);
@@ -136,6 +138,7 @@ program
   .description('Start the visualization UI server')
   .option('-p, --port <number>', `Server port (default: ${DEFAULT_PORT})`, parseInt)
   .option('-d, --diagram <path>', 'Path to architecture JSON (default: .archbyte/architecture.json)')
+  .option('--debug', 'Enable transparency endpoint (/api/transparency)')
   .action(async (options) => {
     await handleServe(options);
   });

package/dist/agents/pipeline/index.d.ts

@@ -6,7 +6,7 @@ import type { IncrementalContext } from "./types.js";
  * Run the multi-agent pipeline: 3 parallel fast agents → 2 sequential agents.
  * Each agent gets a single chat() call with pre-collected static context.
  */
-export declare function runPipeline(ctx: StaticContext, provider: LLMProvider, config: ArchByteConfig, onProgress?: (msg: string) => void, incrementalContext?: IncrementalContext): Promise<StaticAnalysisResult & {
+export declare function runPipeline(ctx: StaticContext, provider: LLMProvider, config: ArchByteConfig, onProgress?: (msg: string) => void, incrementalContext?: IncrementalContext, onDebug?: (agentId: string, model: string, system: string, user: string) => void): Promise<StaticAnalysisResult & {
     tokenUsage?: {
         input: number;
         output: number;

package/dist/agents/pipeline/index.js

@@ -92,7 +92,7 @@ function getFallbackData(agentId, inc) {
  * Run the multi-agent pipeline: 3 parallel fast agents → 2 sequential agents.
  * Each agent gets a single chat() call with pre-collected static context.
  */
-export async function runPipeline(ctx, provider, config, onProgress, incrementalContext) {
+export async function runPipeline(ctx, provider, config, onProgress, incrementalContext, onDebug) {
     const agentResults = {};
     const agentMeta = [];
     const skippedAgents = [];
@@ -118,7 +118,7 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
             agentResults[agent.id] = fallback;
             return Promise.resolve(null);
         }
-        return runAgent(agent, ctx, provider, config, parallelPrior, onProgress);
+        return runAgent(agent, ctx, provider, config, parallelPrior, onProgress, onDebug);
     }));
     let authFailed = false;
     for (let i = 0; i < parallelTasks.length; i++) {
@@ -156,7 +156,7 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
             continue;
         }
         try {
-            const result = await runAgent(agent, ctx, provider, config, agentResults, onProgress);
+            const result = await runAgent(agent, ctx, provider, config, agentResults, onProgress, onDebug);
             if (result) {
                 agentResults[agent.id] = result.data;
                 agentMeta.push(result);
@@ -214,10 +214,12 @@ const MAX_TOKENS = {
     "flow-detector": 4096,
     "validator": 4096,
 };
-async function runAgent(agent, ctx, provider, config, priorResults, onProgress) {
+async function runAgent(agent, ctx, provider, config, priorResults, onProgress, onDebug) {
     const start = Date.now();
     const model = resolveModel(config.provider, agent.modelTier, config.modelOverrides, config.model);
     const { system, user } = agent.buildPrompt(ctx, priorResults);
+    // Debug callback — report what data is being sent
+    onDebug?.(agent.id, model, system, user);
     onProgress?.(`  ${agent.name}: calling ${model}...`);
     const maxTokens = MAX_TOKENS[agent.id] ?? 4096;
     const response = await provider.chat({

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

@@ -0,0 +1,12 @@
+export interface IgnoreFilter {
+    /** Returns true if the relative path should be excluded from analysis */
+    isIgnored(relativePath: string): boolean;
+    /** Number of active patterns (excluding comments and blank lines) */
+    patternCount: number;
+}
+/**
+ * Load `.archbyteignore` from the project root.
+ * Returns an IgnoreFilter that matches paths against the patterns.
+ * If the file doesn't exist, returns a no-op filter that ignores nothing.
+ */
+export declare function loadIgnoreFile(projectRoot: string): IgnoreFilter;

package/dist/agents/static/ignore.js

@@ -0,0 +1,140 @@
+// .archbyteignore — File exclusion filter
+// Supports .gitignore-style patterns: # comments, ! negation, ** globstar, * wildcard
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Load `.archbyteignore` from the project root.
+ * Returns an IgnoreFilter that matches paths against the patterns.
+ * If the file doesn't exist, returns a no-op filter that ignores nothing.
+ */
+export function loadIgnoreFile(projectRoot) {
+    const ignorePath = path.join(projectRoot, ".archbyteignore");
+    if (!fs.existsSync(ignorePath)) {
+        return { isIgnored: () => false, patternCount: 0 };
+    }
+    const content = fs.readFileSync(ignorePath, "utf-8");
+    const rules = parseIgnorePatterns(content);
+    return {
+        isIgnored(relativePath) {
+            // Normalize path separators
+            const normalized = relativePath.replace(/\\/g, "/").replace(/^\//, "");
+            let ignored = false;
+            for (const rule of rules) {
+                if (rule.pattern.test(normalized)) {
+                    ignored = !rule.negated;
+                }
+            }
+            return ignored;
+        },
+        patternCount: rules.length,
+    };
+}
+/**
+ * Parse .gitignore-style content into an ordered list of rules.
+ */
+function parseIgnorePatterns(content) {
+    const rules = [];
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        // Skip blank lines and comments
+        if (!line || line.startsWith("#"))
+            continue;
+        let pattern = line;
+        let negated = false;
+        // Handle negation
+        if (pattern.startsWith("!")) {
+            negated = true;
+            pattern = pattern.slice(1);
+        }
+        // Remove trailing spaces (unless escaped)
+        pattern = pattern.replace(/(?<!\\)\s+$/, "");
+        if (!pattern)
+            continue;
+        const regex = patternToRegex(pattern);
+        rules.push({ pattern: regex, negated });
+    }
+    return rules;
+}
+/**
+ * Convert a .gitignore-style pattern to a RegExp.
+ * Supports: * (any non-slash), ** (any including slashes), ? (single char),
+ * trailing / (directory match), leading / (root-anchored).
+ */
+function patternToRegex(pattern) {
+    let anchored = false;
+    // Leading / means anchored to root
+    if (pattern.startsWith("/")) {
+        anchored = true;
+        pattern = pattern.slice(1);
+    }
+    // Trailing / means match directories — for our purposes, match the prefix
+    const dirOnly = pattern.endsWith("/");
+    if (dirOnly) {
+        pattern = pattern.slice(0, -1);
+    }
+    // Escape regex special chars, then convert glob patterns
+    let regex = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        const next = pattern[i + 1];
+        if (ch === "*" && next === "*") {
+            // ** — match anything including path separators
+            if (pattern[i + 2] === "/") {
+                // **/ — match zero or more directories
+                regex += "(?:.*/)?";
+                i += 3;
+            }
+            else {
+                // ** at end or before non-slash
+                regex += ".*";
+                i += 2;
+            }
+        }
+        else if (ch === "*") {
+            // * — match anything except /
+            regex += "[^/]*";
+            i++;
+        }
+        else if (ch === "?") {
+            // ? — match single non-slash char
+            regex += "[^/]";
+            i++;
+        }
+        else if (ch === "[") {
+            // Character class — pass through until ]
+            const closeBracket = pattern.indexOf("]", i + 1);
+            if (closeBracket !== -1) {
+                regex += pattern.slice(i, closeBracket + 1);
+                i = closeBracket + 1;
+            }
+            else {
+                regex += escapeRegex(ch);
+                i++;
+            }
+        }
+        else {
+            regex += escapeRegex(ch);
+            i++;
+        }
+    }
+    if (dirOnly) {
+        // Match the directory itself or anything under it
+        regex += "(?:/.*)?";
+    }
+    if (anchored) {
+        // Must match from the start
+        return new RegExp(`^${regex}$`);
+    }
+    // Unanchored: match if the pattern matches the full path
+    // or any suffix after a /
+    // If pattern contains /, it's implicitly anchored
+    if (pattern.includes("/")) {
+        return new RegExp(`^${regex}$`);
+    }
+    // No slash: match against the basename OR any path segment
+    return new RegExp(`(?:^|/)${regex}(?:/.*)?$`);
+}
+function escapeRegex(ch) {
+    return ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -1,4 +1,5 @@
 import type { StaticAnalysisResult, StaticContext } from "./types.js";
+import type { PrivacyConfig } from "../../cli/yaml-io.js";
 export type { StaticAnalysisResult, StaticContext } from "./types.js";
 export { validateAnalysis } from "./validator.js";
 /**
@@ -16,4 +17,4 @@ export declare function runStaticAnalysis(projectRoot: string, onProgress?: (msg
  * This runs ONLY fact-collectors (no component-detector, connection-mapper, or validator).
  * Output is consumed by the pipeline LLM agents.
  */
-export declare function runStaticContextCollection(projectRoot: string, onProgress?: (msg: string) => void): Promise<StaticContext>;
+export declare function runStaticContextCollection(projectRoot: string, onProgress?: (msg: string) => void, privacy?: Required<PrivacyConfig>): Promise<StaticContext>;

package/dist/agents/static/index.js

@@ -11,6 +11,8 @@ import { mapConnections } from "./connection-mapper.js";
 import { validateAnalysis } from "./validator.js";
 import { collectFileTree } from "./file-tree-collector.js";
 import { collectCodeSamples } from "./code-sampler.js";
+import { loadIgnoreFile } from "./ignore.js";
+import { redactContext } from "./redactor.js";
 export { validateAnalysis } from "./validator.js";
 /**
  * Run all static analysis scanners.
@@ -22,7 +24,11 @@ export { validateAnalysis } from "./validator.js";
  *   4. Gap detection — identify what the LLM should resolve
  */
 export async function runStaticAnalysis(projectRoot, onProgress) {
-    const tk = new StaticToolkit(projectRoot);
+    const ignoreFilter = loadIgnoreFile(projectRoot);
+    if (ignoreFilter.patternCount > 0) {
+        onProgress?.(`Loaded .archbyteignore: ${ignoreFilter.patternCount} pattern(s)`);
+    }
+    const tk = new StaticToolkit(projectRoot, ignoreFilter);
     // Phase 1: parallel scanners (no dependencies)
     onProgress?.("Running parallel scanners...");
     const [structure, docs, infra, events, envs] = await Promise.all([
@@ -292,8 +298,12 @@ async function collectGaps(analysis, tk) {
  * This runs ONLY fact-collectors (no component-detector, connection-mapper, or validator).
  * Output is consumed by the pipeline LLM agents.
  */
-export async function runStaticContextCollection(projectRoot, onProgress) {
-    const tk = new StaticToolkit(projectRoot);
+export async function runStaticContextCollection(projectRoot, onProgress, privacy) {
+    const ignoreFilter = loadIgnoreFile(projectRoot);
+    if (ignoreFilter.patternCount > 0) {
+        onProgress?.(`Loaded .archbyteignore: ${ignoreFilter.patternCount} pattern(s)`);
+    }
+    const tk = new StaticToolkit(projectRoot, ignoreFilter);
     onProgress?.("Collecting static context (7 scanners in parallel)...");
     const [structure, docs, infra, events, envs, fileTree, codeSamples] = await Promise.all([
         scanStructure(tk),
@@ -306,5 +316,43 @@ export async function runStaticContextCollection(projectRoot, onProgress) {
     ]);
     onProgress?.(`Context: ${fileTree.totalFiles} files, ${fileTree.totalDirs} dirs, ${codeSamples.configFiles.length} configs, ${codeSamples.samples.length} samples`);
     onProgress?.(`Detected: ${structure.language}, ${structure.framework ?? "no framework"}, monorepo=${structure.isMonorepo}`);
-    return { structure, docs, infra, events, envs, fileTree, codeSamples };
+    let ctx = { structure, docs, infra, events, envs, fileTree, codeSamples };
+    // Apply privacy controls — zero out disabled fields
+    if (privacy) {
+        if (!privacy.sendCodeSamples) {
+            ctx.codeSamples = { ...ctx.codeSamples, samples: [] };
+            onProgress?.("Privacy: code samples excluded");
+        }
+        if (!privacy.sendImportMap) {
+            ctx.codeSamples = { ...ctx.codeSamples, importMap: {} };
+            onProgress?.("Privacy: import map excluded");
+        }
+        if (!privacy.sendEnvNames) {
+            ctx.envs = { ...ctx.envs, environments: ctx.envs.environments.map((e) => ({ ...e, variables: [] })) };
+            onProgress?.("Privacy: env variable names excluded");
+        }
+        if (!privacy.sendDocs) {
+            ctx.docs = { projectDescription: "", architectureNotes: [], apiEndpoints: [], externalDependencies: [] };
+            onProgress?.("Privacy: documentation excluded");
+        }
+        if (!privacy.sendFileTree) {
+            ctx.fileTree = { tree: [], totalFiles: ctx.fileTree.totalFiles, totalDirs: ctx.fileTree.totalDirs };
+            onProgress?.("Privacy: file tree excluded");
+        }
+        if (!privacy.sendInfra) {
+            ctx.infra = {
+                docker: { services: [], composeFile: false },
+                kubernetes: { resources: [] },
+                cloud: { provider: null, services: [], iac: null },
+                ci: { platform: null, pipelines: [] },
+            };
+            onProgress?.("Privacy: infrastructure details excluded");
+        }
+        // Redaction — hash identifiers before returning
+        if (privacy.redact) {
+            ctx = redactContext(ctx);
+            onProgress?.("Privacy: redaction applied — identifiers hashed");
+        }
+    }
+    return ctx;
 }

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

@@ -0,0 +1,12 @@
+import type { StaticContext } from "./types.js";
+/**
+ * Redact sensitive identifiers in a StaticContext.
+ * - File paths: hash each segment, preserve extensions and depth
+ * - Env var names: hash
+ * - Docker service names: hash
+ * - String literals in code samples: hash
+ * - Preserve: npm package names, language keywords, structural info
+ *
+ * Returns a deep copy — the original context is not modified.
+ */
+export declare function redactContext(ctx: StaticContext): StaticContext;

package/dist/agents/static/redactor.js

@@ -0,0 +1,206 @@
+// Redaction Mode — Hash sensitive identifiers in StaticContext
+// Preserves structure and public package names while hiding proprietary paths/names.
+import { createHash } from "crypto";
+/**
+ * Redact sensitive identifiers in a StaticContext.
+ * - File paths: hash each segment, preserve extensions and depth
+ * - Env var names: hash
+ * - Docker service names: hash
+ * - String literals in code samples: hash
+ * - Preserve: npm package names, language keywords, structural info
+ *
+ * Returns a deep copy — the original context is not modified.
+ */
+export function redactContext(ctx) {
+    return {
+        structure: redactStructure(ctx.structure),
+        docs: redactDocs(ctx.docs),
+        infra: redactInfra(ctx.infra),
+        events: redactEvents(ctx.events),
+        envs: redactEnvs(ctx.envs),
+        fileTree: redactFileTree(ctx.fileTree),
+        codeSamples: redactCodeSamples(ctx.codeSamples),
+    };
+}
+// --- Hashing ---
+const hashCache = new Map();
+function hashStr(value) {
+    const cached = hashCache.get(value);
+    if (cached)
+        return cached;
+    const hash = createHash("sha256").update(value).digest("hex").slice(0, 8);
+    const result = `redacted-${hash}`;
+    hashCache.set(value, result);
+    return result;
+}
+/**
+ * Hash each segment of a path, preserving the extension and directory depth.
+ * `src/auth/handler.ts` → `redacted-a1b2c3/redacted-d4e5f6/redacted-g7h8.ts`
+ */
+function redactPath(filePath) {
+    if (!filePath || filePath === ".")
+        return filePath;
+    const parts = filePath.split("/");
+    return parts
+        .map((part) => {
+        const dotIdx = part.lastIndexOf(".");
+        if (dotIdx > 0 && dotIdx < part.length - 1) {
+            const name = part.slice(0, dotIdx);
+            const ext = part.slice(dotIdx);
+            return `${hashStr(name)}${ext}`;
+        }
+        return hashStr(part);
+    })
+        .join("/");
+}
+// --- Structure ---
+function redactStructure(s) {
+    return {
+        ...s,
+        // Keep project name generic
+        projectName: hashStr(s.projectName),
+        // Keep language/framework/build info (public knowledge)
+        entryPoints: s.entryPoints.map(redactPath),
+        directories: Object.fromEntries(Object.entries(s.directories).map(([dir, isPresent]) => [hashStr(dir), isPresent])),
+    };
+}
+// --- Docs ---
+function redactDocs(d) {
+    return {
+        // Preserve project description (it's user-written public text)
+        projectDescription: d.projectDescription,
+        architectureNotes: d.architectureNotes,
+        apiEndpoints: d.apiEndpoints.map((ep) => ({
+            ...ep,
+            path: redactApiPath(ep.path),
+        })),
+        externalDependencies: d.externalDependencies, // Public package names — keep
+    };
+}
+function redactApiPath(apiPath) {
+    // Redact path parameters but keep HTTP structure
+    return apiPath.replace(/\/[a-zA-Z_]\w*/g, (segment) => {
+        // Keep common REST verbs/patterns
+        const common = ["/api", "/v1", "/v2", "/v3", "/health", "/status", "/auth"];
+        if (common.includes(segment))
+            return segment;
+        return `/${hashStr(segment.slice(1))}`;
+    });
+}
+// --- Infra ---
+function redactInfra(i) {
+    return {
+        docker: {
+            services: i.docker.services.map((svc) => ({
+                ...svc,
+                name: hashStr(svc.name),
+                buildContext: svc.buildContext ? redactPath(svc.buildContext) : undefined,
+                environment: svc.environment
+                    ? Object.fromEntries(Object.entries(svc.environment).map(([k, v]) => [hashStr(k), "***"]))
+                    : undefined,
+            })),
+            composeFile: i.docker.composeFile,
+            composeFilePath: i.docker.composeFilePath ? redactPath(i.docker.composeFilePath) : undefined,
+        },
+        kubernetes: {
+            resources: i.kubernetes.resources.map((r) => ({
+                ...r,
+                name: hashStr(r.name),
+                namespace: r.namespace ? hashStr(r.namespace) : undefined,
+            })),
+        },
+        cloud: i.cloud, // Provider names and service types are public
+        ci: i.ci, // CI platform names are public
+    };
+}
+// --- Events ---
+function redactEvents(e) {
+    return {
+        hasEDA: e.hasEDA,
+        patterns: e.patterns, // Technology names are public
+        events: e.events.map((ev) => ({
+            ...ev,
+            file: redactPath(ev.file),
+        })),
+    };
+}
+// --- Envs ---
+function redactEnvs(e) {
+    return {
+        environments: e.environments.map((env) => ({
+            name: env.name, // "production", "staging" etc — keep
+            variables: env.variables.map((v) => hashStr(v)),
+        })),
+        configPattern: e.configPattern,
+        hasSecrets: e.hasSecrets,
+    };
+}
+// --- File Tree ---
+function redactFileTree(ft) {
+    return {
+        tree: ft.tree.map(redactTreeEntry),
+        totalFiles: ft.totalFiles,
+        totalDirs: ft.totalDirs,
+    };
+}
+function redactTreeEntry(entry) {
+    return {
+        path: redactPath(entry.path),
+        type: entry.type,
+        children: entry.children?.map(redactTreeEntry),
+    };
+}
+// --- Code Samples ---
+function redactCodeSamples(cs) {
+    return {
+        samples: cs.samples.map((s) => ({
+            ...s,
+            path: redactPath(s.path),
+            excerpt: redactCodeExcerpt(s.excerpt),
+        })),
+        importMap: Object.fromEntries(Object.entries(cs.importMap).map(([file, imports]) => [
+            redactPath(file),
+            imports.map((imp) => {
+                // Keep npm package imports (don't start with . or /)
+                if (!imp.startsWith(".") && !imp.startsWith("/"))
+                    return imp;
+                return redactPath(imp);
+            }),
+        ])),
+        configFiles: cs.configFiles.map((cf) => ({
+            path: redactPath(cf.path),
+            content: redactConfigContent(cf.content),
+        })),
+    };
+}
+/**
+ * Redact string literals in code excerpts while preserving structure.
+ * Keeps language keywords, npm imports, and structural tokens.
+ */
+function redactCodeExcerpt(code) {
+    // Replace string literals (single/double quoted) with hashed versions
+    // But preserve common patterns like import paths to npm packages
+    return code.replace(/(["'])([^"']*)\1/g, (_match, quote, content) => {
+        // Keep npm package imports
+        if (!content.startsWith(".") && !content.startsWith("/") && !content.includes(" ")) {
+            return `${quote}${content}${quote}`;
+        }
+        // Keep short common strings
+        if (content.length <= 2)
+            return `${quote}${content}${quote}`;
+        // Redact everything else
+        return `${quote}${hashStr(content)}${quote}`;
+    });
+}
+function redactConfigContent(content) {
+    // Redact values in key=value and key: value patterns
+    return content
+        .replace(/^(\s*[\w.-]+\s*[:=]\s*)(.+)$/gm, (_match, prefix, value) => {
+        const trimmed = value.trim();
+        // Keep boolean, numeric, null values
+        if (/^(true|false|null|undefined|\d+(\.\d+)?)$/i.test(trimmed)) {
+            return `${prefix}${value}`;
+        }
+        return `${prefix}${hashStr(trimmed)}`;
+    });
+}

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

@@ -1,10 +1,12 @@
 import type { GrepResult, DirEntry } from "../runtime/types.js";
+import type { IgnoreFilter } from "./ignore.js";
 /**
  * Wraps LocalFSBackend with safe-read helpers for static scanners.
  */
 export declare class StaticToolkit {
     private fs;
-    constructor(projectRoot: string);
+    private ignore;
+    constructor(projectRoot: string, ignoreFilter?: IgnoreFilter);
     readFileSafe(path: string): Promise<string | null>;
     globFiles(pattern: string, cwd?: string): Promise<string[]>;
     grepFiles(pattern: string, searchPath?: string): Promise<GrepResult[]>;

package/dist/agents/static/utils.js

@@ -6,10 +6,14 @@ import { LocalFSBackend } from "../tools/local-fs.js";
  */
 export class StaticToolkit {
     fs;
-    constructor(projectRoot) {
+    ignore;
+    constructor(projectRoot, ignoreFilter) {
         this.fs = new LocalFSBackend(projectRoot);
+        this.ignore = ignoreFilter ?? null;
     }
     async readFileSafe(path) {
+        if (this.ignore?.isIgnored(path))
+            return null;
         try {
             return await this.fs.readFile(path);
         }
@@ -21,12 +25,19 @@ export class StaticToolkit {
         try {
             // Expand brace patterns like *.{yml,yaml} → [*.yml, *.yaml]
             const patterns = expandBraces(pattern);
+            let results;
             if (patterns.length === 1) {
-                return await this.fs.glob(patterns[0], cwd);
+                results = await this.fs.glob(patterns[0], cwd);
+            }
+            else {
+                const resultSets = await Promise.all(patterns.map((p) => this.fs.glob(p, cwd).catch(() => [])));
+                results = [...new Set(resultSets.flat())].sort();
+            }
+            // Apply ignore filter
+            if (this.ignore) {
+                results = results.filter((f) => !this.ignore.isIgnored(f));
             }
-            const resultSets = await Promise.all(patterns.map((p) => this.fs.glob(p, cwd).catch(() => [])));
-            // Deduplicate and sort
-            return [...new Set(resultSets.flat())].sort();
+            return results;
         }
         catch {
             return [];
@@ -36,11 +47,16 @@ export class StaticToolkit {
         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));
+            let results = await this.fs.grep(pattern);
+            if (searchPath) {
+                const prefix = searchPath.endsWith("/") ? searchPath : `${searchPath}/`;
+                results = results.filter((r) => r.file.startsWith(prefix));
+            }
+            // Apply ignore filter
+            if (this.ignore) {
+                results = results.filter((r) => !this.ignore.isIgnored(r.file));
+            }
+            return results;
         }
         catch {
             return [];
@@ -48,7 +64,14 @@ export class StaticToolkit {
     }
     async listDir(dirPath) {
         try {
-            return await this.fs.listDir(dirPath);
+            const entries = await this.fs.listDir(dirPath);
+            if (this.ignore) {
+                return entries.filter((e) => {
+                    const fullPath = dirPath === "." ? e.name : `${dirPath}/${e.name}`;
+                    return !this.ignore.isIgnored(fullPath);
+                });
+            }
+            return entries;
         }
         catch {
             return [];

package/dist/cli/analyze.d.ts

@@ -9,6 +9,7 @@ interface AnalyzeOptions {
     dryRun?: boolean;
     force?: boolean;
     dir?: string;
+    debug?: boolean;
     /** When true, skip "archbyte serve" in the Next steps (e.g. called from `archbyte run`) */
     skipServeHint?: boolean;
 }

package/dist/cli/analyze.js

@@ -4,9 +4,10 @@ import { execSync } from "child_process";
 import chalk from "chalk";
 import { resolveConfig } from "./config.js";
 import { recordUsage } from "./license-gate.js";
-import { staticResultToSpec, writeSpec, writeMetadata, loadSpec, loadMetadata } from "./yaml-io.js";
+import { staticResultToSpec, writeSpec, writeMetadata, loadSpec, loadMetadata, resolvePrivacy } from "./yaml-io.js";
 import { getChangedFiles, mapFilesToComponents, shouldRunAgents, isGitAvailable, categorizeChanges, computeNeighbors, getCommitCount } from "./incremental.js";
 import { progressBar, confirm } from "./ui.js";
+import { buildCollectorReport, buildAgentReport, buildTransparencyReport, printTransparencyReport, saveTransparencyReport, } from "./transparency.js";
 export async function handleAnalyze(options) {
     const rootDir = options.dir ? path.resolve(options.dir) : process.cwd();
     const isStaticOnly = options.static || options.skipLlm;
@@ -201,13 +202,17 @@ export async function handleAnalyze(options) {
             console.log(chalk.yellow(`File tree grew from ${priorCount} to ${currentFileCount} files — running full scan.`));
         }
     }
-    // 4. Run static context collection → LLM pipeline
+    // 4. Load privacy config
+    const privacySpec = loadSpec(rootDir);
+    const privacy = resolvePrivacy(privacySpec);
+    const agentReports = [];
+    // 5. Run static context collection → LLM pipeline
     const progress = progressBar(7);
     progress.update(0, "Collecting static context...");
     const { runStaticContextCollection } = await import("../agents/static/index.js");
     const ctx = await runStaticContextCollection(rootDir, (msg) => {
         progress.update(0, `Static context: ${msg}`);
-    });
+    }, privacy);
     // Save static context for debugging / re-runs
     const ctxPath = path.join(rootDir, ".archbyte", "static-context.json");
     if (!fs.existsSync(path.dirname(ctxPath))) {
@@ -219,6 +224,12 @@ export async function handleAnalyze(options) {
     const { runPipeline } = await import("../agents/pipeline/index.js");
     let result;
     let pipelineStep = 1;
+    // Debug callback — collect agent reports for transparency log
+    const onDebug = options.debug
+        ? (agentId, model, system, user) => {
+            agentReports.push(buildAgentReport(agentId, model, system, user));
+        }
+        : undefined;
     try {
         result = await runPipeline(ctx, provider, config, (msg) => {
             // Map pipeline progress messages to bar steps
@@ -249,7 +260,7 @@ export async function handleAnalyze(options) {
             else {
                 progress.update(pipelineStep, msg.trim());
             }
-        }, incrementalContext);
+        }, incrementalContext, onDebug);
     }
     catch (err) {
         const errorMsg = err instanceof Error ? err.message : String(err);
@@ -311,6 +322,22 @@ export async function handleAnalyze(options) {
     const spec = staticResultToSpec(result, rootDir, existingSpec?.rules);
     writeSpec(rootDir, spec);
     writeScanMetadata(rootDir, duration, "pipeline", ctx.fileTree.totalFiles, result.tokenUsage, incrementalContext ? true : undefined, result.skippedAgents);
+    // Transparency report (--debug)
+    if (options.debug) {
+        const collectors = buildCollectorReport(ctx);
+        const privacyControls = {
+            sendCodeSamples: privacy.sendCodeSamples,
+            sendImportMap: privacy.sendImportMap,
+            sendEnvNames: privacy.sendEnvNames,
+            sendDocs: privacy.sendDocs,
+            sendFileTree: privacy.sendFileTree,
+            sendInfra: privacy.sendInfra,
+        };
+        const ignoreFilter = (await import("../agents/static/ignore.js")).loadIgnoreFile(rootDir);
+        const report = buildTransparencyReport(collectors, agentReports, privacyControls, ignoreFilter.patternCount, privacy.redact);
+        printTransparencyReport(report);
+        saveTransparencyReport(rootDir, report);
+    }
     progress.update(6, "Generating diagram...");
     await autoGenerate(rootDir, options);
     progress.done("Analysis complete");

package/dist/cli/run.d.ts

@@ -7,6 +7,7 @@ interface RunOptions {
     verbose?: boolean;
     force?: boolean;
     dryRun?: boolean;
+    debug?: boolean;
     dir?: string;
 }
 export declare function handleRun(options: RunOptions): Promise<void>;

package/dist/cli/run.js

@@ -128,11 +128,12 @@ export async function handleRun(options) {
         apiKey: options.apiKey,
         force: options.force,
         dryRun: options.dryRun,
+        debug: options.debug,
         dir: options.dir,
         skipServeHint: true,
     });
     if (options.dryRun)
         return;
     // 2. Serve the UI
-    await handleServe({ port });
+    await handleServe({ port, debug: options.debug });
 }

package/dist/cli/serve.d.ts

@@ -1,6 +1,7 @@
 interface ServeOptions {
     port?: number;
     diagram?: string;
+    debug?: boolean;
 }
 /**
  * Start the ArchByte UI server

package/dist/cli/serve.js

@@ -84,6 +84,7 @@ export async function handleServe(options) {
                 diagramPath,
                 workspaceRoot: rootDir,
                 port,
+                debug: options.debug,
             });
             return;
         }

package/dist/cli/transparency.d.ts

@@ -0,0 +1,36 @@
+import type { StaticContext } from "../agents/static/types.js";
+export interface CollectorReport {
+    name: string;
+    itemCount: number;
+    filePaths: string[];
+    byteEstimate: number;
+}
+export interface AgentReport {
+    agentId: string;
+    model: string;
+    dataCategories: string[];
+    fileRefs: string[];
+    promptTokenEstimate: number;
+}
+export interface TransparencyReport {
+    timestamp: string;
+    collectors: CollectorReport[];
+    agents: AgentReport[];
+    privacyControls: Record<string, boolean>;
+    ignorePatterns: number;
+    redactionEnabled: boolean;
+    totals: {
+        collectorsRun: number;
+        agentsRun: number;
+        filesReferenced: number;
+        estimatedPromptBytes: number;
+    };
+}
+export declare function buildCollectorReport(ctx: StaticContext): CollectorReport[];
+export declare function buildAgentReport(agentId: string, model: string, systemPrompt: string, userPrompt: string): AgentReport;
+export declare function printTransparencyReport(report: TransparencyReport): void;
+export declare function saveTransparencyReport(rootDir: string, report: TransparencyReport): void;
+/**
+ * Build a complete TransparencyReport from collector reports and agent reports.
+ */
+export declare function buildTransparencyReport(collectors: CollectorReport[], agents: AgentReport[], privacy: Record<string, boolean>, ignorePatterns: number, redactionEnabled: boolean): TransparencyReport;

package/dist/cli/transparency.js

@@ -0,0 +1,214 @@
+// Transparency Log — Debug output showing exactly what data is collected and sent
+// Used with `archbyte analyze --debug`
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+// --- Collector Report ---
+export function buildCollectorReport(ctx) {
+    const reports = [];
+    // Structure scanner
+    const structJson = JSON.stringify(ctx.structure);
+    reports.push({
+        name: "structure-scanner",
+        itemCount: ctx.structure.entryPoints.length + Object.keys(ctx.structure.directories).length,
+        filePaths: ctx.structure.entryPoints,
+        byteEstimate: structJson.length,
+    });
+    // Doc parser
+    const docsJson = JSON.stringify(ctx.docs);
+    reports.push({
+        name: "doc-parser",
+        itemCount: ctx.docs.apiEndpoints.length + ctx.docs.externalDependencies.length + ctx.docs.architectureNotes.length,
+        filePaths: [],
+        byteEstimate: docsJson.length,
+    });
+    // Infra analyzer
+    const infraJson = JSON.stringify(ctx.infra);
+    reports.push({
+        name: "infra-analyzer",
+        itemCount: ctx.infra.docker.services.length + ctx.infra.kubernetes.resources.length + ctx.infra.cloud.services.length,
+        filePaths: ctx.infra.docker.composeFilePath ? [ctx.infra.docker.composeFilePath] : [],
+        byteEstimate: infraJson.length,
+    });
+    // Event detector
+    const eventsJson = JSON.stringify(ctx.events);
+    reports.push({
+        name: "event-detector",
+        itemCount: ctx.events.events.length + ctx.events.patterns.length,
+        filePaths: ctx.events.events.map((e) => e.file),
+        byteEstimate: eventsJson.length,
+    });
+    // Env detector
+    const envsJson = JSON.stringify(ctx.envs);
+    const envVarCount = ctx.envs.environments.reduce((sum, e) => sum + e.variables.length, 0);
+    reports.push({
+        name: "env-detector",
+        itemCount: ctx.envs.environments.length + envVarCount,
+        filePaths: [],
+        byteEstimate: envsJson.length,
+    });
+    // File tree collector
+    const treeJson = JSON.stringify(ctx.fileTree);
+    reports.push({
+        name: "file-tree-collector",
+        itemCount: ctx.fileTree.totalFiles + ctx.fileTree.totalDirs,
+        filePaths: [],
+        byteEstimate: treeJson.length,
+    });
+    // Code sampler
+    const samplesJson = JSON.stringify(ctx.codeSamples);
+    reports.push({
+        name: "code-sampler",
+        itemCount: ctx.codeSamples.samples.length + ctx.codeSamples.configFiles.length,
+        filePaths: [
+            ...ctx.codeSamples.samples.map((s) => s.path),
+            ...ctx.codeSamples.configFiles.map((c) => c.path),
+        ],
+        byteEstimate: samplesJson.length,
+    });
+    return reports;
+}
+// --- Agent Report ---
+export function buildAgentReport(agentId, model, systemPrompt, userPrompt) {
+    const combined = systemPrompt + userPrompt;
+    // Extract data categories from prompt content
+    const categories = [];
+    if (combined.includes("fileTree") || combined.includes("file tree"))
+        categories.push("file-tree");
+    if (combined.includes("codeSamples") || combined.includes("code sample"))
+        categories.push("code-samples");
+    if (combined.includes("importMap") || combined.includes("import map"))
+        categories.push("import-map");
+    if (combined.includes("structure"))
+        categories.push("project-structure");
+    if (combined.includes("infra"))
+        categories.push("infrastructure");
+    if (combined.includes("events"))
+        categories.push("events");
+    if (combined.includes("envs") || combined.includes("environment"))
+        categories.push("environments");
+    if (combined.includes("docs"))
+        categories.push("documentation");
+    // Extract file references from prompt
+    const fileRefs = [];
+    const fileRefPattern = /["']([a-zA-Z0-9_./-]+\.[a-zA-Z]{1,6})["']/g;
+    let match;
+    while ((match = fileRefPattern.exec(combined)) !== null) {
+        if (!fileRefs.includes(match[1])) {
+            fileRefs.push(match[1]);
+        }
+    }
+    // Rough token estimate (~4 chars per token)
+    const promptTokenEstimate = Math.ceil(combined.length / 4);
+    return {
+        agentId,
+        model,
+        dataCategories: categories,
+        fileRefs: fileRefs.slice(0, 50),
+        promptTokenEstimate,
+    };
+}
+// --- Print ---
+export function printTransparencyReport(report) {
+    console.error();
+    console.error(chalk.bold.cyan("Transparency Report"));
+    console.error(chalk.gray("What data was collected and sent to your LLM provider"));
+    console.error();
+    // Privacy controls
+    console.error(chalk.bold("Privacy Controls"));
+    for (const [key, value] of Object.entries(report.privacyControls)) {
+        const status = value ? chalk.green("enabled") : chalk.gray("disabled");
+        console.error(`  ${key}: ${status}`);
+    }
+    if (report.ignorePatterns > 0) {
+        console.error(`  .archbyteignore: ${chalk.yellow(`${report.ignorePatterns} pattern(s)`)}`);
+    }
+    if (report.redactionEnabled) {
+        console.error(`  redaction: ${chalk.yellow("enabled — paths/names hashed")}`);
+    }
+    console.error();
+    // Collectors
+    console.error(chalk.bold("Static Collectors"));
+    for (const c of report.collectors) {
+        const size = formatBytes(c.byteEstimate);
+        console.error(`  ${c.name.padEnd(22)} ${String(c.itemCount).padStart(4)} items  ${size.padStart(8)}`);
+        if (c.filePaths.length > 0 && c.filePaths.length <= 5) {
+            for (const fp of c.filePaths) {
+                console.error(chalk.gray(`    ${fp}`));
+            }
+        }
+        else if (c.filePaths.length > 5) {
+            for (const fp of c.filePaths.slice(0, 3)) {
+                console.error(chalk.gray(`    ${fp}`));
+            }
+            console.error(chalk.gray(`    ... and ${c.filePaths.length - 3} more`));
+        }
+    }
+    console.error();
+    // Agents
+    if (report.agents.length > 0) {
+        console.error(chalk.bold("LLM Agents"));
+        for (const a of report.agents) {
+            console.error(`  ${a.agentId.padEnd(22)} model=${a.model}  ~${a.promptTokenEstimate} tokens`);
+            if (a.dataCategories.length > 0) {
+                console.error(chalk.gray(`    data: ${a.dataCategories.join(", ")}`));
+            }
+            if (a.fileRefs.length > 0) {
+                console.error(chalk.gray(`    files: ${a.fileRefs.slice(0, 5).join(", ")}${a.fileRefs.length > 5 ? ` +${a.fileRefs.length - 5} more` : ""}`));
+            }
+        }
+        console.error();
+    }
+    // Totals
+    console.error(chalk.bold("Totals"));
+    console.error(`  Collectors:        ${report.totals.collectorsRun}`);
+    console.error(`  Agents:            ${report.totals.agentsRun}`);
+    console.error(`  Files referenced:  ${report.totals.filesReferenced}`);
+    console.error(`  Est. prompt data:  ${formatBytes(report.totals.estimatedPromptBytes)}`);
+    console.error();
+}
+// --- Save ---
+export function saveTransparencyReport(rootDir, report) {
+    const dir = path.join(rootDir, ".archbyte");
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const reportPath = path.join(dir, "transparency.json");
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf-8");
+}
+// --- Helpers ---
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Build a complete TransparencyReport from collector reports and agent reports.
+ */
+export function buildTransparencyReport(collectors, agents, privacy, ignorePatterns, redactionEnabled) {
+    const allFiles = new Set();
+    for (const c of collectors) {
+        for (const fp of c.filePaths)
+            allFiles.add(fp);
+    }
+    for (const a of agents) {
+        for (const fp of a.fileRefs)
+            allFiles.add(fp);
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        collectors,
+        agents,
+        privacyControls: privacy,
+        ignorePatterns,
+        redactionEnabled,
+        totals: {
+            collectorsRun: collectors.length,
+            agentsRun: agents.length,
+            filesReferenced: allFiles.size,
+            estimatedPromptBytes: collectors.reduce((s, c) => s + c.byteEstimate, 0),
+        },
+    };
+}

package/dist/cli/yaml-io.d.ts

@@ -41,6 +41,15 @@ export interface ArchbyteSpecFlow {
     category: string;
     steps: ArchbyteSpecFlowStep[];
 }
+export interface PrivacyConfig {
+    sendCodeSamples?: boolean;
+    sendImportMap?: boolean;
+    sendEnvNames?: boolean;
+    sendDocs?: boolean;
+    sendFileTree?: boolean;
+    sendInfra?: boolean;
+    redact?: boolean;
+}
 export interface ArchbyteSpec {
     version: number;
     project: {
@@ -58,6 +67,7 @@ export interface ArchbyteSpec {
     environments: ArchbyteSpecEnvironment[];
     flows: ArchbyteSpecFlow[];
     rules: Record<string, unknown>;
+    privacy?: PrivacyConfig;
 }
 export interface ScanMetadata {
     analyzedAt: string;
@@ -83,6 +93,10 @@ export declare function writeMetadata(rootDir: string, meta: ScanMetadata): void
  * Optionally preserves existing rules from a prior spec.
  */
 export declare function staticResultToSpec(result: StaticAnalysisResult, rootDir: string, existingRules?: Record<string, unknown>): ArchbyteSpec;
+/**
+ * Resolve privacy config with defaults. All fields default to enabled (true) except redact (false).
+ */
+export declare function resolvePrivacy(spec: ArchbyteSpec | null): Required<PrivacyConfig>;
 /**
  * Convert an ArchbyteSpec back to the AnalysisResult format expected by generate.ts.
  * This is the inverse of staticResultToSpec → buildAnalysisFromStatic.

package/dist/cli/yaml-io.js

@@ -163,6 +163,21 @@ export function staticResultToSpec(result, rootDir, existingRules) {
         rules,
     };
 }
+/**
+ * Resolve privacy config with defaults. All fields default to enabled (true) except redact (false).
+ */
+export function resolvePrivacy(spec) {
+    const p = spec?.privacy ?? {};
+    return {
+        sendCodeSamples: p.sendCodeSamples ?? true,
+        sendImportMap: p.sendImportMap ?? true,
+        sendEnvNames: p.sendEnvNames ?? true,
+        sendDocs: p.sendDocs ?? true,
+        sendFileTree: p.sendFileTree ?? true,
+        sendInfra: p.sendInfra ?? true,
+        redact: p.redact ?? false,
+    };
+}
 /**
  * Convert an ArchbyteSpec back to the AnalysisResult format expected by generate.ts.
  * This is the inverse of staticResultToSpec → buildAnalysisFromStatic.

package/dist/server/src/index.d.ts

@@ -4,5 +4,6 @@ export interface ServerConfig {
     diagramPath: string;
     workspaceRoot: string;
     port: number;
+    debug?: boolean;
 }
 export declare function startServer(cfg: ServerConfig): Promise<void>;

package/dist/server/src/index.js

@@ -662,6 +662,77 @@ function createHttpServer() {
             }));
             return;
         }
+        // API: Transparency report (--debug)
+        if (url === "/api/transparency" && req.method === "GET") {
+            const transparencyPath = path.join(config.workspaceRoot, ".archbyte", "transparency.json");
+            if (existsSync(transparencyPath)) {
+                const content = readFileSync(transparencyPath, "utf-8");
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(content);
+            }
+            else {
+                res.writeHead(404, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "No transparency report found. Run 'archbyte analyze --debug' to generate one." }));
+            }
+            return;
+        }
+        // API: Data flow documentation
+        if (url === "/api/data-flow" && req.method === "GET") {
+            const dataFlow = {
+                outboundConnections: [
+                    {
+                        destination: "Your LLM Provider (BYOK)",
+                        protocol: "HTTPS",
+                        data: [
+                            "Project structure metadata (language, framework, directories)",
+                            "File tree (paths only, no contents)",
+                            "Code excerpts (first ~80 lines of key files)",
+                            "Import relationships between files",
+                            "Config file contents (package.json, docker-compose, etc.)",
+                            "Environment variable names (never values)",
+                            "Infrastructure details (Docker services, K8s resources)",
+                        ],
+                        controlledBy: "archbyte.yaml privacy section + .archbyteignore",
+                    },
+                    {
+                        destination: "ArchByte Cloud (api.heartbyte.io)",
+                        protocol: "HTTPS",
+                        data: ["Email address", "JWT token", "Scan count"],
+                        controlledBy: "Required for license validation only",
+                    },
+                ],
+                neverSent: [
+                    "Environment variable values",
+                    "Full source code (only excerpts of key files)",
+                    "Secrets, passwords, API keys",
+                    "Git history, commits, diffs",
+                    "Git credentials (SSH keys, tokens)",
+                    "Binary files",
+                    "node_modules / vendor dependencies",
+                    "User home directory contents",
+                ],
+                privacyControls: {
+                    archbyteignore: "Exclude files/directories from all scanners (.gitignore syntax)",
+                    sendCodeSamples: "Toggle code excerpt collection",
+                    sendImportMap: "Toggle import relationship collection",
+                    sendEnvNames: "Toggle env variable name collection",
+                    sendDocs: "Toggle documentation extraction",
+                    sendFileTree: "Toggle file tree collection",
+                    sendInfra: "Toggle infrastructure detail collection",
+                    redact: "Hash all identifiers (paths, names) before sending to LLM",
+                },
+                localOnly: [
+                    ".archbyte/archbyte.yaml — Architecture spec",
+                    ".archbyte/analysis.json — Full analysis output",
+                    ".archbyte/architecture.json — Diagram layout",
+                    ".archbyte/static-context.json — Raw scanner output",
+                    ".archbyte/transparency.json — Audit trail",
+                ],
+            };
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(dataFlow, null, 2));
+            return;
+        }
         // API: Health (deprecated - redirect to audit for backward compat)
         if (url === "/api/health" && req.method === "GET") {
             res.writeHead(307, { "Location": "/api/audit" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archbyte",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "ArchByte - See what agents build. As they build it.",
   "type": "module",
   "bin": {

package/templates/archbyte.yaml

@@ -80,6 +80,26 @@ environments: []
 #         label: "api-gateway -> user-service"
 flows: []
 
+# ── Privacy Controls ──
+# Control what data is sent to your LLM provider during analysis.
+# All options default to true (enabled). Set to false to exclude.
+# See: docs/DATA_FLOW.md for full details on what each scanner collects.
+#
+# privacy:
+#   sendCodeSamples: true    # Code excerpts (first ~80 lines of key files)
+#   sendImportMap: true       # Import relationships between files
+#   sendEnvNames: true        # Environment variable names (never values)
+#   sendDocs: true            # Documentation extracts (README, etc.)
+#   sendFileTree: true        # Directory structure (paths only)
+#   sendInfra: true           # Infrastructure details (Docker, K8s, CI)
+#   redact: false             # Hash all identifiers before sending to LLM
+#
+# Also create .archbyteignore in your project root to exclude specific
+# files/directories from all scanners (.gitignore syntax):
+#   secrets/
+#   *.env
+#   *.pem
+
 # ── Architecture Fitness Rules ──
 # Levels: error (fail CI), warn (report), off (skip)
 rules: