archbyte 0.6.1 → 0.7.1

package/README.md

@@ -5,11 +5,8 @@ AI-powered architecture visualization for your codebase. Analyzes code, generate
 ## Quick Start
 
 ```bash
-# Install
-curl -fsSL https://archbyte.heartbyte.io/install.sh | bash
-
-# Run (auto-configures on first use)
-archbyte run
+# Run directly — no install required
+npx archbyte run
 ```
 
 On first run, ArchByte walks you through sign-in and provider setup interactively. Your API keys stay on your machine — ArchByte never stores or transmits your provider credentials.
@@ -19,8 +16,17 @@ On first run, ArchByte walks you through sign-in and provider setup interactivel
 Prefer to configure each step separately:
 
 ```bash
-archbyte login          # Sign in or create a free account
-archbyte init           # Configure your AI provider (BYOK)
+npx archbyte login          # Sign in or create a free account
+npx archbyte init           # Configure your AI provider (BYOK)
+```
+
+### Global install (optional)
+
+If you prefer a persistent install:
+
+```bash
+npm install -g archbyte
+archbyte run
 ```
 
 ### Setup with Claude Code
@@ -65,11 +71,11 @@ Run `/archbyte-help` in Claude Code to see all commands.
 Sign in or create a free account. Shows an interactive provider picker (GitHub, Google, Email & Password).
 
 ```bash
-archbyte login              # interactive provider picker
-archbyte login --github     # sign in with GitHub
-archbyte login --google     # sign in with Google
-archbyte login --email      # sign in with email and password
-archbyte login --token JWT  # login with a pre-existing JWT token
+npx archbyte login              # interactive provider picker
+npx archbyte login --github     # sign in with GitHub
+npx archbyte login --google     # sign in with Google
+npx archbyte login --email      # sign in with email and password
+npx archbyte login --token JWT  # login with a pre-existing JWT token
 ```
 
 Multiple accounts are supported. If already logged in, you'll be prompted to add a different account.
@@ -79,9 +85,9 @@ Multiple accounts are supported. If already logged in, you'll be prompted to add
 Sign out of ArchByte.
 
 ```bash
-archbyte logout              # logout active account
-archbyte logout user@co.com  # logout specific account
-archbyte logout --all        # logout all accounts
+npx archbyte logout              # logout active account
+npx archbyte logout user@co.com  # logout specific account
+npx archbyte logout --all        # logout all accounts
 ```
 
 ### `archbyte accounts`
@@ -89,9 +95,9 @@ archbyte logout --all        # logout all accounts
 List and manage logged-in accounts.
 
 ```bash
-archbyte accounts                    # list all accounts
-archbyte accounts switch             # interactive account switcher
-archbyte accounts switch user@co.com # switch to specific account
+npx archbyte accounts                    # list all accounts
+npx archbyte accounts switch             # interactive account switcher
+npx archbyte accounts switch user@co.com # switch to specific account
 ```
 
 ### `archbyte status`
@@ -99,7 +105,7 @@ archbyte accounts switch user@co.com # switch to specific account
 Show account status, tier, and usage.
 
 ```bash
-archbyte status
+npx archbyte status
 ```
 
 ### `archbyte init`
@@ -107,54 +113,54 @@ archbyte status
 Scaffold an `archbyte.yaml` config and `.archbyte/` directory.
 
 ```bash
-archbyte init
-archbyte init --force    # overwrite existing
+npx archbyte init
+npx archbyte init --force    # overwrite existing
 ```
 
 > **Why this matters:** Without a config, every team member picks their own rules and thresholds. `init` gives your project a single source of truth for architecture governance from day one.
 >
-> *Example:* You join a new monorepo and want to enforce "no direct DB calls from the frontend." Run `archbyte init`, edit the generated `archbyte.yaml` to add that custom rule, and commit it — now every contributor shares the same guardrails.
+> *Example:* You join a new monorepo and want to enforce "no direct DB calls from the frontend." Run `npx archbyte init`, edit the generated `archbyte.yaml` to add that custom rule, and commit it — now every contributor shares the same guardrails.
 
 ### `archbyte generate`
 
 Convert analysis JSON into an architecture diagram.
 
 ```bash
-archbyte generate
-archbyte generate --input path/to/analysis.json --output path/to/arch.json
-archbyte generate --verbose
+npx archbyte generate
+npx archbyte generate --input path/to/analysis.json --output path/to/arch.json
+npx archbyte generate --verbose
 ```
 
 Merges with existing diagram to preserve user-adjusted node positions.
 
 > **Why this matters:** Raw analysis JSON is data — a positioned architecture diagram is *understanding*. Generate turns a flat list of components and dependencies into a spatial map you can actually reason about.
 >
-> *Example:* After an AI analysis finds 40 components and 120 dependencies, `archbyte generate` lays them out by layer so you instantly see that your "AuthService" sits in the wrong tier. Re-running after code changes merges new nodes in without losing the positions you manually adjusted last sprint.
+> *Example:* After an AI analysis finds 40 components and 120 dependencies, `npx archbyte generate` lays them out by layer so you instantly see that your "AuthService" sits in the wrong tier. Re-running after code changes merges new nodes in without losing the positions you manually adjusted last sprint.
 
 ### `archbyte serve`
 
 Start the HTTP server with the interactive visualization UI.
 
 ```bash
-archbyte serve                    # default port 3847
-archbyte serve --port 8080
-archbyte serve --diagram path/to/architecture.json
+npx archbyte serve                    # default port 3847
+npx archbyte serve --port 8080
+npx archbyte serve --diagram path/to/architecture.json
 ```
 
 Features: real-time SSE updates, drag-and-drop nodes, environment filtering, flow animation, dependency highlighting, export to PNG/SVG.
 
 > **Why this matters:** Architecture diagrams on a wiki go stale the moment they're drawn. A live, interactive diagram that updates in real-time means you're always looking at the truth, not a six-month-old Confluence page.
 >
-> *Example:* During an incident review, run `archbyte serve` and drag the failing service to the center. Click it to highlight all upstream dependencies — now the whole team can see which services are affected and trace the blast radius visually instead of grep-ing through YAML manifests.
+> *Example:* During an incident review, run `npx archbyte serve` and drag the failing service to the center. Click it to highlight all upstream dependencies — now the whole team can see which services are affected and trace the blast radius visually instead of grep-ing through YAML manifests.
 
 ### `archbyte validate`
 
 Run architecture fitness function rules.
 
 ```bash
-archbyte validate
-archbyte validate --ci       # JSON output, exit code 1 on errors
-archbyte validate --watch    # re-validate on file changes
+npx archbyte validate
+npx archbyte validate --ci       # JSON output, exit code 1 on errors
+npx archbyte validate --watch    # re-validate on file changes
 ```
 
 **Built-in rules:**
@@ -185,54 +191,54 @@ rules:
 
 > **Why this matters:** Code review catches syntax and logic bugs, but architectural violations slip through because no human reviewer holds the entire dependency graph in their head. Validate acts as an automated architect that never misses a rule.
 >
-> *Example:* A junior developer adds a direct import from a React component to a Postgres client library. `archbyte validate --ci` in your GitHub Actions pipeline catches the layer bypass (`presentation -> data`) and fails the build *before* the PR is merged — no manual review needed.
+> *Example:* A junior developer adds a direct import from a React component to a Postgres client library. `npx archbyte validate --ci` in your GitHub Actions pipeline catches the layer bypass (`presentation -> data`) and fails the build *before* the PR is merged — no manual review needed.
 
 ### `archbyte stats`
 
 Architecture health dashboard.
 
 ```bash
-archbyte stats
-archbyte stats --diagram path/to/architecture.json
+npx archbyte stats
+npx archbyte stats --diagram path/to/architecture.json
 ```
 
 Shows: component counts, layer distribution, connection density, hub detection, orphan detection, layer violations.
 
 > **Why this matters:** "How healthy is our architecture?" is usually answered with gut feelings. Stats turns that into numbers you can track over time and discuss objectively in sprint retros.
 >
-> *Example:* You run `archbyte stats` and discover your `ApiGateway` has 14 connections — more than double the threshold. That's a hub risk: if it goes down, 14 services are affected. You bring this to the team meeting with hard data instead of a hunch, and the team agrees to split it into domain-specific gateways.
+> *Example:* You run `npx archbyte stats` and discover your `ApiGateway` has 14 connections — more than double the threshold. That's a hub risk: if it goes down, 14 services are affected. You bring this to the team meeting with hard data instead of a hunch, and the team agrees to split it into domain-specific gateways.
 
 ### `archbyte export`
 
 Export to various formats.
 
 ```bash
-archbyte export                              # mermaid to stdout
-archbyte export --format plantuml
-archbyte export --format dot                 # Graphviz
-archbyte export --format markdown
-archbyte export --format json
-archbyte export --output docs/architecture.mmd
+npx archbyte export                              # mermaid to stdout
+npx archbyte export --format plantuml
+npx archbyte export --format dot                 # Graphviz
+npx archbyte export --format markdown
+npx archbyte export --format json
+npx archbyte export --output docs/architecture.mmd
 ```
 
 > **Why this matters:** Your architecture diagram shouldn't be locked inside one tool. Export lets you embed it in PRs, design docs, ADRs, or any toolchain your team already uses.
 >
-> *Example:* Before each release, you run `archbyte export --format mermaid --output docs/architecture.mmd` and commit it. GitHub renders the Mermaid diagram inline in your repo — anyone browsing the codebase sees an always-current architecture map without installing anything.
+> *Example:* Before each release, you run `npx archbyte export --format mermaid --output docs/architecture.mmd` and commit it. GitHub renders the Mermaid diagram inline in your repo — anyone browsing the codebase sees an always-current architecture map without installing anything.
 
 ### `archbyte diff`
 
 Compare architecture snapshots and detect drift.
 
 ```bash
-archbyte diff --baseline .archbyte/baseline.json
-archbyte diff --baseline old.json --current new.json
+npx archbyte diff --baseline .archbyte/baseline.json
+npx archbyte diff --baseline old.json --current new.json
 ```
 
 Reports added/removed components, added/removed connections, density change, new/resolved violations. Exit code 1 on new errors.
 
 > **Why this matters:** Architecture erosion happens one commit at a time. By the time someone notices, the codebase has drifted far from its intended design. Diff catches drift early by comparing snapshots and surfacing exactly what changed.
 >
-> *Example:* You save a baseline after your v2.0 release with `cp .archbyte/architecture.json .archbyte/baseline.json`. Two months later, run `archbyte diff --baseline .archbyte/baseline.json` and discover 3 new circular dependencies and a removed service boundary. You can now decide whether to accept the drift or fix it — before it compounds further.
+> *Example:* You save a baseline after your v2.0 release with `cp .archbyte/architecture.json .archbyte/baseline.json`. Two months later, run `npx archbyte diff --baseline .archbyte/baseline.json` and discover 3 new circular dependencies and a removed service boundary. You can now decide whether to accept the drift or fix it — before it compounds further.
 
 ### `archbyte patrol`
 
@@ -241,11 +247,11 @@ Continuous architecture health monitoring — runs the validation pipeline on a
 Inspired by [Gastown's](https://github.com/steveyegge/gastown) patrol loop pattern.
 
 ```bash
-archbyte patrol                       # default 5m interval
-archbyte patrol --interval 30s        # 30 second cycles
-archbyte patrol --interval 1h         # hourly
-archbyte patrol --on-violation json   # JSON output for piping
-archbyte patrol --history             # view patrol history dashboard
+npx archbyte patrol                       # default 5m interval
+npx archbyte patrol --interval 30s        # 30 second cycles
+npx archbyte patrol --interval 1h         # hourly
+npx archbyte patrol --on-violation json   # JSON output for piping
+npx archbyte patrol --history             # view patrol history dashboard
 ```
 
 **Options:**
@@ -263,19 +269,19 @@ The patrol daemon:
 
 > **Why this matters:** Validate catches violations at a point in time; Patrol catches them *over time*. Running continuously, it detects the moment a violation appears and tells you when violations get resolved — giving you a living health timeline for your architecture.
 >
-> *Example:* You start `archbyte patrol --interval 5m` in a tmux session during a refactoring sprint. Mid-afternoon, it flags a new circular dependency introduced in the latest commit. You fix it immediately instead of discovering it three weeks later in a failing CI pipeline. At the end of the sprint, `archbyte patrol --history` shows the team a sparkline proving architecture health improved from 72% to 95%.
+> *Example:* You start `npx archbyte patrol --interval 5m` in a tmux session during a refactoring sprint. Mid-afternoon, it flags a new circular dependency introduced in the latest commit. You fix it immediately instead of discovering it three weeks later in a failing CI pipeline. At the end of the sprint, `npx archbyte patrol --history` shows the team a sparkline proving architecture health improved from 72% to 95%.
 
 ### `archbyte workflow`
 
 Composable multi-step architecture pipelines with dependency tracking and resume-on-failure. Inspired by Gastown's MEOW (Molecular Expression of Work) system.
 
 ```bash
-archbyte workflow --list                  # list available workflows
-archbyte workflow --run full-analysis     # run a workflow
-archbyte workflow --show ci-check         # show step details
-archbyte workflow --status                # show progress bars
-archbyte workflow --create "my-pipeline"  # scaffold a custom workflow
-archbyte workflow --reset                 # clear all state
+npx archbyte workflow --list                  # list available workflows
+npx archbyte workflow --run full-analysis     # run a workflow
+npx archbyte workflow --show ci-check         # show step details
+npx archbyte workflow --status                # show progress bars
+npx archbyte workflow --create "my-pipeline"  # scaffold a custom workflow
+npx archbyte workflow --reset                 # clear all state
 ```
 
 **Built-in workflows:**
@@ -314,7 +320,7 @@ Workflows **resume on failure** — completed steps are skipped when you re-run.
 
 > **Why this matters:** Running `generate`, then `validate`, then `stats`, then `export` manually is tedious and error-prone. Workflows chain them into a single reproducible pipeline — and if step 3 fails, you re-run and it skips the already-completed steps instead of starting from scratch.
 >
-> *Example:* You add a `ci-check` workflow to your GitHub Actions. On every PR, it runs `archbyte workflow --run ci-check`, which validates architecture rules in CI mode and exits non-zero on violations. No manual steps, no forgotten checks. For bigger releases, `archbyte workflow --run full-analysis` runs the entire generate-validate-stats-export pipeline in one command and produces a Mermaid diagram committed to `docs/`.
+> *Example:* You add a `ci-check` workflow to your GitHub Actions. On every PR, it runs `npx archbyte workflow --run ci-check`, which validates architecture rules in CI mode and exits non-zero on violations. No manual steps, no forgotten checks. For bigger releases, `npx archbyte workflow --run full-analysis` runs the entire generate-validate-stats-export pipeline in one command and produces a Mermaid diagram committed to `docs/`.
 
 ## Keyboard Shortcuts (UI)
 
@@ -328,8 +334,8 @@ Workflows **resume on failure** — completed steps are skipped when you re-run.
 
 ## Requirements
 
-- Node.js >= 18
-- Claude Code (for `/archbyte-analyze`)
+- Node.js >= 18 (for `npx archbyte`)
+- Claude Code (for `/archbyte-analyze` slash commands)
 
 ## License
 

package/dist/agents/index.js

@@ -53,6 +53,7 @@ export async function loadPremiumAgents() {
             import("./premium/migration-planner.js"),
             import("./premium/api-contract-verifier.js"),
             import("./premium/drift-detector.js"),
+            import("./premium/infra-agent-auditor.js"),
         ]);
         return [
             mods[0].securityAuditor,
@@ -62,6 +63,7 @@ export async function loadPremiumAgents() {
             mods[4].migrationPlanner,
             mods[5].apiContractVerifier,
             mods[6].driftDetector,
+            mods[7].infraAgentAuditor,
         ];
     }
     catch {

package/dist/agents/observability/adapters/archbyte.d.ts

@@ -0,0 +1,3 @@
+import type { AgentSession } from "../types.js";
+/** Import a .archbyte/ directory into AgentSession(s) */
+export declare function importArchbyte(archbyteDir: string): Promise<AgentSession[]>;

package/dist/agents/observability/adapters/archbyte.js

@@ -0,0 +1,104 @@
+// Archbyte Adapter — reads .archbyte/runs/ + session.json + metadata.json
+// Converts archbyte pipeline run data into AgentSession for the Sessions panel
+import { readFile, readdir } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+/** Read a text file if it exists, return null otherwise */
+async function readOptional(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Read and parse a JSON file, return null on failure */
+function readJsonSync(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Import a .archbyte/ directory into AgentSession(s) */
+export async function importArchbyte(archbyteDir) {
+    const runsDir = path.join(archbyteDir, "runs");
+    if (!existsSync(runsDir))
+        return [];
+    // Read run subdirectories
+    let entries;
+    try {
+        const dirEntries = await readdir(runsDir, { withFileTypes: true });
+        entries = dirEntries.filter(e => e.isDirectory()).map(e => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+    if (entries.length === 0)
+        return [];
+    // Read session.json for session-level metadata
+    const session = readJsonSync(path.join(archbyteDir, "session.json"));
+    const metadata = readJsonSync(path.join(archbyteDir, "metadata.json"));
+    const sessionId = session?.sessionId ?? `archbyte-${path.basename(path.dirname(archbyteDir))}`;
+    // Build runs from subdirectories
+    const runs = [];
+    for (const dirName of entries) {
+        const runPath = path.join(runsDir, dirName);
+        const meta = readJsonSync(path.join(runPath, "meta.json"));
+        if (!meta)
+            continue;
+        const prompt = await readOptional(path.join(runPath, "prompt.md"));
+        const output = await readOptional(path.join(runPath, "output.md"));
+        runs.push({
+            ...meta,
+            artifacts: {
+                ...(prompt ? { prompt } : {}),
+                ...(output ? { output } : {}),
+            },
+        });
+    }
+    if (runs.length === 0)
+        return [];
+    // Derive session summary
+    const totalElapsed = session?.totalElapsedSeconds ?? runs.reduce((s, r) => s + (r.elapsedSeconds ?? 0), 0);
+    const totalTokens = session?.totalTokens ?? {
+        input: runs.reduce((s, r) => s + (r.tokens?.input ?? 0), 0),
+        output: runs.reduce((s, r) => s + (r.tokens?.output ?? 0), 0),
+    };
+    const phases = [...new Set(runs.map(r => r.phase))];
+    const models = [...new Set(runs.map(r => r.model))];
+    const successfulRuns = runs.filter(r => r.status === "success").length;
+    const failedRuns = runs.filter(r => r.status === "error").length;
+    const skippedRuns = runs.filter(r => r.status === "skipped").length;
+    const firstRun = runs[0];
+    const lastRun = runs[runs.length - 1];
+    const startedAt = session?.startedAt ?? firstRun.startedAt;
+    const completedAt = session?.completedAt ?? lastRun.completedAt ?? lastRun.startedAt;
+    const status = failedRuns > 0 ? "partial" : "success";
+    return [{
+            sessionId,
+            startedAt,
+            completedAt,
+            status: session?.status ?? status,
+            source: "archbyte",
+            projectMeta: {
+                mode: session?.mode ?? metadata?.mode ?? "pipeline",
+            },
+            summary: {
+                totalRuns: runs.length,
+                successfulRuns,
+                failedRuns,
+                skippedRuns,
+                totalElapsedSeconds: totalElapsed,
+                totalTokens,
+                phases,
+                models,
+            },
+            runs,
+        }];
+}

package/dist/agents/observability/adapters/claude-transcripts.d.ts

@@ -0,0 +1,31 @@
+import type { AgentSession } from "../types.js";
+/** Invalidate cached index entries. Call with a path to invalidate one file, or no args to clear all. */
+export declare function invalidateIndexCache(filePath?: string): void;
+export declare function getClaudeProjectsDir(): string;
+export declare function encodeProjectPath(cwd: string): string;
+export declare function getProjectTranscriptDir(cwd: string): string | null;
+export type SessionCategory = "implementation" | "exploration" | "conversation" | "pipeline";
+export interface SessionIndexEntry {
+    sessionId: string;
+    startedAt: string;
+    completedAt?: string;
+    status: "success" | "partial";
+    runCount: number;
+    phases: string[];
+    source: string;
+    model?: string;
+    version?: string;
+    gitBranch?: string;
+    subagentCount?: number;
+    category?: SessionCategory;
+    label?: string;
+    touchedDirs?: string[];
+    eventCount?: number;
+    dirMetrics?: Record<string, {
+        reads: number;
+        writes: number;
+    }>;
+    estimatedCost?: number;
+}
+export declare function scanTranscriptIndex(projectDir: string): Promise<SessionIndexEntry[]>;
+export declare function importClaudeTranscript(projectDir: string, sessionId: string): Promise<AgentSession | null>;