archbyte 0.5.1 → 0.5.3

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

@@ -138,6 +138,11 @@ function createHttpServer() {
             return;
         }
         const url = req.url || "/";
+        // Log API actions to terminal (skip static files, SSE, health checks)
+        if (url.startsWith("/api/") && url !== "/api/health") {
+            const label = url.replace("/api/", "").split("?")[0];
+            console.error(`[archbyte] ${req.method} ${label}`);
+        }
         // SSE endpoint
         if (url === "/events") {
             res.writeHead(200, {
@@ -657,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" });
@@ -1129,7 +1205,7 @@ function createHttpServer() {
             const child = spawn(process.execPath, [bin, "generate"], {
                 cwd: config.workspaceRoot,
                 stdio: ["ignore", "pipe", "pipe"],
-                env: { ...process.env, FORCE_COLOR: "0" },
+                env: { ...process.env, FORCE_COLOR: "0", ARCHBYTE_INTERNAL: "1" },
             });
             runningWorkflows.set("__generate__", child);
             broadcastOpsEvent({ type: "generate:started" });
@@ -1221,7 +1297,7 @@ function createHttpServer() {
             const child = spawn(process.execPath, [bin, "workflow", "--run", id], {
                 cwd: config.workspaceRoot,
                 stdio: ["ignore", "pipe", "pipe"],
-                env: { ...process.env, FORCE_COLOR: "0" },
+                env: { ...process.env, FORCE_COLOR: "0", ARCHBYTE_INTERNAL: "1" },
             });
             runningWorkflows.set(id, child);
             broadcastOpsEvent({ type: "workflow:started", id });
@@ -1452,6 +1528,22 @@ function createHttpServer() {
             }
             return;
         }
+        // API: UI event logging — fire-and-forget from UI to server console
+        if (url === "/api/ui-event" && req.method === "POST") {
+            let body = "";
+            req.on("data", (chunk) => { body += chunk.toString(); });
+            req.on("end", () => {
+                try {
+                    const { event, detail } = JSON.parse(body);
+                    const msg = detail ? `${event} — ${detail}` : event;
+                    console.error(`[archbyte] ui: ${msg}`);
+                }
+                catch { }
+                res.writeHead(204);
+                res.end();
+            });
+            return;
+        }
         // API: Telemetry — record agent timing data
         if (url === "/api/telemetry" && req.method === "POST") {
             let body = "";
@@ -1717,7 +1809,7 @@ function runAnalyzePipeline(mode = "static", fileChanges) {
     const analyzeChild = spawn(process.execPath, analyzeArgs, {
         cwd: config.workspaceRoot,
         stdio: ["ignore", "pipe", "pipe"],
-        env: { ...process.env, FORCE_COLOR: "0" },
+        env: { ...process.env, FORCE_COLOR: "0", ARCHBYTE_INTERNAL: "1" },
     });
     let analyzeStderr = "";
     analyzeChild.stdout?.on("data", (d) => process.stderr.write(`[analyze] ${d}`));
@@ -1733,7 +1825,7 @@ function runAnalyzePipeline(mode = "static", fileChanges) {
         const genChild = spawn(process.execPath, [bin, "generate"], {
             cwd: config.workspaceRoot,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, FORCE_COLOR: "0" },
+            env: { ...process.env, FORCE_COLOR: "0", ARCHBYTE_INTERNAL: "1" },
         });
         genChild.stdout?.on("data", (d) => process.stderr.write(`[generate] ${d}`));
         genChild.stderr?.on("data", (d) => process.stderr.write(`[generate] ${d}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archbyte",
-  "version": "0.5.1",
+  "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: