@mrace07/kairo 0.1.0

package/dist/infrastructure/repository/repository-profiler.d.ts

@@ -0,0 +1,35 @@
+import type { RepositoryFingerprint, RepositorySnapshot } from "../../domain/models.js";
+export declare class RepositoryProfiler {
+    private readonly limits;
+    constructor(limits?: {
+        maxInventoryEntries?: number;
+        maxControlFileBytes?: number;
+    });
+    /** Builds a bounded, language-neutral snapshot with optional JS/TS enrichment. */
+    profile(root: string): Promise<RepositorySnapshot>;
+    /** Computes the same deterministic identity used by a full snapshot. */
+    fingerprint(root: string): Promise<RepositoryFingerprint>;
+    private inventory;
+    private gitMetadata;
+    private gitPaths;
+    private walkPaths;
+    private changedPaths;
+    private inventoryFingerprint;
+    private classify;
+    private ecosystems;
+    private pathsOf;
+    private isControlFile;
+    private hashFile;
+    private readPackage;
+    private readGitignore;
+    private scripts;
+    private indexFiles;
+    private readText;
+    private terms;
+    private symbols;
+    private connectFiles;
+    private imports;
+    private resolveImport;
+    private testTarget;
+    private isUseful;
+}

package/dist/infrastructure/repository/repository-profiler.js

@@ -0,0 +1,498 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { basename, extname, join, posix, relative, resolve, sep } from "node:path";
+import { VerificationPlanner } from "../../application/verification-planner.js";
+const execute = promisify(execFile);
+const gitExecutable = process.platform === "darwin" ? "/usr/bin/git" : "git";
+const DEFAULT_IGNORES = new Set([
+    ".git",
+    ".kairo",
+    ".cache",
+    ".next",
+    ".venv",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "coverage",
+    "target",
+    "out",
+    "venv",
+]);
+const SOURCE_DIRS = new Set(["src", "app", "lib", "pkg", "cmd", "internal", "crates", "packages"]);
+const TEST_DIRS = new Set(["test", "tests", "__tests__", "spec", "specs"]);
+const MAX_INVENTORY_ENTRIES = 20_000;
+const MAX_INDEXED_FILES = 800;
+const MAX_CONTROL_FILE_BYTES = 256 * 1024;
+const MAX_INDEXED_FILE_BYTES = 200_000;
+const MAX_TERMS_PER_FILE = 400;
+const MAX_SYMBOLS_PER_FILE = 80;
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const SOURCE_FILE_EXTENSIONS = new Set([
+    ".c",
+    ".cc",
+    ".cpp",
+    ".cs",
+    ".ex",
+    ".exs",
+    ".go",
+    ".h",
+    ".hpp",
+    ".java",
+    ".js",
+    ".jsx",
+    ".kt",
+    ".kts",
+    ".php",
+    ".py",
+    ".rb",
+    ".rs",
+    ".swift",
+    ".ts",
+    ".tsx",
+]);
+const MANIFEST_NAMES = new Set([
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.py",
+    "go.mod",
+    "cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "gemfile",
+    "composer.json",
+    "mix.exs",
+    "workspace.json",
+    "nx.json",
+    "turbo.json",
+    "lerna.json",
+]);
+const LOCKFILE_NAMES = new Set([
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+    "poetry.lock",
+    "uv.lock",
+    "cargo.lock",
+    "go.sum",
+    "gemfile.lock",
+    "composer.lock",
+    "mix.lock",
+]);
+const BUILD_NAMES = new Set([
+    "makefile",
+    "justfile",
+    "taskfile.yml",
+    "taskfile.yaml",
+    "dockerfile",
+    "compose.yml",
+    "compose.yaml",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "cmakelists.txt",
+    "build",
+    "build.bazel",
+    "workspace",
+    "jenkinsfile",
+]);
+const CONFIG_NAMES = new Set([
+    "tsconfig.json",
+    "jsconfig.json",
+    "vite.config.ts",
+    "vite.config.js",
+    "vitest.config.ts",
+    "jest.config.js",
+    "eslint.config.js",
+    ".eslintrc.json",
+    "tox.ini",
+    "pytest.ini",
+    "ruff.toml",
+]);
+export class RepositoryProfiler {
+    limits;
+    constructor(limits = {}) {
+        this.limits = limits;
+    }
+    /** Builds a bounded, language-neutral snapshot with optional JS/TS enrichment. */
+    async profile(root) {
+        const absoluteRoot = resolve(root);
+        const inventory = await this.inventory(absoluteRoot);
+        const [packageJson, gitignore] = await Promise.all([
+            this.readPackage(absoluteRoot),
+            this.readGitignore(absoluteRoot),
+        ]);
+        const paths = new Set(inventory.entries.map((entry) => entry.path));
+        const sourceRoots = [...SOURCE_DIRS].filter((name) => inventory.entries.some((entry) => entry.path.startsWith(`${name}/`)));
+        const testRoots = [...TEST_DIRS].filter((name) => inventory.entries.some((entry) => entry.path.startsWith(`${name}/`)));
+        const packageManager = paths.has("pnpm-lock.yaml")
+            ? "pnpm"
+            : paths.has("yarn.lock")
+                ? "yarn"
+                : paths.has("bun.lockb") || paths.has("bun.lock")
+                    ? "bun"
+                    : paths.has("package-lock.json")
+                        ? "npm"
+                        : "unknown";
+        const files = await this.indexFiles(absoluteRoot, inventory.entries);
+        const snapshot = {
+            schemaVersion: 1,
+            root: absoluteRoot,
+            fingerprint: this.inventoryFingerprint(inventory),
+            entries: inventory.entries,
+            ecosystems: this.ecosystems(paths),
+            changedPaths: inventory.git?.changedPaths ?? [],
+            instructionFiles: this.pathsOf(inventory.entries, "instruction"),
+            documentationFiles: this.pathsOf(inventory.entries, "documentation"),
+            manifestFiles: this.pathsOf(inventory.entries, "manifest"),
+            ciFiles: this.pathsOf(inventory.entries, "ci"),
+            buildFiles: this.pathsOf(inventory.entries, "build"),
+            truncated: inventory.truncated,
+            packageName: typeof packageJson?.name === "string" ? packageJson.name : undefined,
+            packageManager,
+            scripts: this.scripts(packageJson),
+            configFiles: this.pathsOf(inventory.entries, "config"),
+            sourceRoots,
+            testRoots,
+            ignoredPaths: [...new Set([...DEFAULT_IGNORES, ...gitignore])].sort(),
+            indexedFiles: files.map((file) => file.path),
+            files: this.connectFiles(files, sourceRoots, testRoots),
+            verificationCandidates: [],
+            createdAt: Date.now(),
+        };
+        snapshot.verificationCandidates = new VerificationPlanner().candidates(snapshot);
+        return snapshot;
+    }
+    /** Computes the same deterministic identity used by a full snapshot. */
+    async fingerprint(root) {
+        return this.inventoryFingerprint(await this.inventory(resolve(root)));
+    }
+    async inventory(root) {
+        const git = await this.gitMetadata(root);
+        const paths = git
+            ? await this.gitPaths(root)
+            : await this.walkPaths(root, new Set(await this.readGitignore(root)));
+        const maxEntries = this.limits.maxInventoryEntries ?? MAX_INVENTORY_ENTRIES;
+        const truncated = paths.length > maxEntries;
+        const entries = [];
+        for (const path of paths.slice(0, maxEntries).sort()) {
+            const full = resolve(root, path);
+            if (full !== root && !full.startsWith(`${root}${sep}`))
+                continue;
+            try {
+                const file = await lstat(full);
+                if (!file.isFile() || file.isSymbolicLink())
+                    continue;
+                const kind = this.classify(path);
+                entries.push({
+                    path: path.split(sep).join("/"),
+                    kind,
+                    size: file.size,
+                    mtimeMs: Math.trunc(file.mtimeMs),
+                    contentHash: this.isControlFile(kind) &&
+                        file.size <= (this.limits.maxControlFileBytes ?? MAX_CONTROL_FILE_BYTES)
+                        ? await this.hashFile(full)
+                        : undefined,
+                });
+            }
+            catch {
+                // A concurrent edit can remove a file; the next fingerprint will observe it.
+            }
+        }
+        return { entries, truncated, git };
+    }
+    async gitMetadata(root) {
+        try {
+            const [{ stdout: gitRoot }, head, branch, { stdout: status }] = await Promise.all([
+                execute(gitExecutable, ["-C", root, "rev-parse", "--show-toplevel"], {
+                    encoding: "utf8",
+                }),
+                execute(gitExecutable, ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" }).catch(() => ({
+                    stdout: "",
+                })),
+                execute(gitExecutable, ["-C", root, "branch", "--show-current"], {
+                    encoding: "utf8",
+                }).catch(() => ({ stdout: "" })),
+                execute(gitExecutable, ["-C", root, "status", "--porcelain=v1", "-z", "--untracked-files=all"], {
+                    encoding: "utf8",
+                }),
+            ]);
+            return {
+                root: gitRoot.trim(),
+                head: head.stdout.trim() || undefined,
+                branch: branch.stdout.trim() || undefined,
+                changedPaths: this.changedPaths(status),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async gitPaths(root) {
+        const { stdout } = await execute(gitExecutable, ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+        return stdout.split("\0").filter(Boolean);
+    }
+    async walkPaths(root, ignored) {
+        const paths = [];
+        const visit = async (directory) => {
+            const maxEntries = this.limits.maxInventoryEntries ?? MAX_INVENTORY_ENTRIES;
+            if (paths.length > maxEntries)
+                return;
+            let entries;
+            try {
+                entries = await readdir(directory, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+                const path = relative(root, join(directory, entry.name)).split(sep).join("/");
+                if (DEFAULT_IGNORES.has(entry.name) ||
+                    ignored.has(entry.name) ||
+                    ignored.has(path) ||
+                    entry.isSymbolicLink())
+                    continue;
+                const full = join(directory, entry.name);
+                if (entry.isDirectory())
+                    await visit(full);
+                else if (entry.isFile())
+                    paths.push(relative(root, full));
+                if (paths.length > maxEntries)
+                    return;
+            }
+        };
+        await visit(root);
+        return paths;
+    }
+    changedPaths(status) {
+        const fields = status.split("\0").filter(Boolean);
+        const paths = [];
+        for (let index = 0; index < fields.length; index += 1) {
+            const field = fields[index];
+            if (field.length < 4)
+                continue;
+            paths.push(field.slice(3));
+            if (field[0] === "R" || field[0] === "C" || field[1] === "R" || field[1] === "C")
+                index += 1;
+        }
+        return [...new Set(paths)].sort();
+    }
+    inventoryFingerprint(inventory) {
+        const payload = {
+            gitRoot: inventory.git?.root,
+            branch: inventory.git?.branch,
+            head: inventory.git?.head,
+            changedPaths: inventory.git?.changedPaths,
+            truncated: inventory.truncated,
+            entries: inventory.entries.map(({ path, size, mtimeMs, contentHash }) => ({
+                path,
+                size,
+                mtimeMs,
+                contentHash,
+            })),
+        };
+        return {
+            value: createHash("sha256").update(JSON.stringify(payload)).digest("hex"),
+            kind: inventory.git ? "git" : "filesystem",
+            gitRoot: inventory.git?.root,
+            branch: inventory.git?.branch,
+            head: inventory.git?.head,
+        };
+    }
+    classify(path) {
+        const lower = path.replaceAll("\\", "/").toLowerCase();
+        const name = basename(lower);
+        if (name === "agents.md" ||
+            name === "claude.md" ||
+            lower === ".github/copilot-instructions.md" ||
+            lower.startsWith(".cursor/rules/"))
+            return "instruction";
+        if (MANIFEST_NAMES.has(name) || /\.(?:sln|csproj)$/.test(name))
+            return "manifest";
+        if (lower.startsWith(".github/workflows/") ||
+            lower === ".gitlab-ci.yml" ||
+            lower === ".gitlab-ci.yaml" ||
+            lower.startsWith(".circleci/"))
+            return "ci";
+        if (BUILD_NAMES.has(name) || /^dockerfile(?:\..+)?$/.test(name))
+            return "build";
+        if (name.startsWith("readme") ||
+            name.startsWith("contributing") ||
+            name.startsWith("architecture") ||
+            lower.startsWith("docs/"))
+            return "documentation";
+        if (CONFIG_NAMES.has(name) || /(?:^|\/)[^/]+\.config\.[^/]+$/.test(lower))
+            return "config";
+        const segments = lower.split("/");
+        if (segments.some((segment) => TEST_DIRS.has(segment)) ||
+            /(?:^|[._-])(test|spec)\.[^.]+$/.test(name))
+            return "test";
+        if (segments.some((segment) => SOURCE_DIRS.has(segment)) ||
+            SOURCE_FILE_EXTENSIONS.has(extname(name)))
+            return "source";
+        return "other";
+    }
+    ecosystems(paths) {
+        const detected = new Set();
+        const has = (...names) => names.some((name) => paths.has(name));
+        if (has("package.json"))
+            detected.add("node");
+        if (has("pyproject.toml", "requirements.txt", "setup.py"))
+            detected.add("python");
+        if (has("go.mod"))
+            detected.add("go");
+        if (has("Cargo.toml"))
+            detected.add("rust");
+        if (has("pom.xml", "build.gradle", "build.gradle.kts"))
+            detected.add("jvm");
+        if (has("Gemfile"))
+            detected.add("ruby");
+        if (has("composer.json"))
+            detected.add("php");
+        if (has("mix.exs"))
+            detected.add("elixir");
+        if ([...paths].some((path) => /\.(?:sln|csproj)$/.test(path)))
+            detected.add("dotnet");
+        return [...detected].sort();
+    }
+    pathsOf(entries, kind) {
+        return entries.filter((entry) => entry.kind === kind).map((entry) => entry.path);
+    }
+    isControlFile(kind) {
+        return kind === "instruction" || kind === "manifest" || kind === "ci" || kind === "build";
+    }
+    async hashFile(path) {
+        return createHash("sha256")
+            .update(await readFile(path))
+            .digest("hex");
+    }
+    async readPackage(root) {
+        try {
+            const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async readGitignore(root) {
+        try {
+            return (await readFile(join(root, ".gitignore"), "utf8"))
+                .split("\n")
+                .map((line) => line.trim().replace(/\/$/, ""))
+                .filter((line) => line && !line.startsWith("#") && !line.includes("*") && !line.startsWith("!"));
+        }
+        catch {
+            return [];
+        }
+    }
+    scripts(packageJson) {
+        const scripts = packageJson?.scripts;
+        if (!scripts || typeof scripts !== "object" || Array.isArray(scripts))
+            return {};
+        return Object.fromEntries(Object.entries(scripts).filter((entry) => typeof entry[1] === "string"));
+    }
+    async indexFiles(root, entries) {
+        const files = [];
+        for (const entry of entries) {
+            if (files.length >= MAX_INDEXED_FILES || !this.isUseful(entry))
+                continue;
+            const text = await this.readText(join(root, entry.path));
+            if (!text)
+                continue;
+            const isJavaScript = SOURCE_EXTENSIONS.includes(extname(entry.path));
+            files.push({
+                path: entry.path,
+                terms: this.terms(text),
+                symbols: isJavaScript ? this.symbols(text) : [],
+                imports: isJavaScript ? this.imports(text) : [],
+                relatedFiles: [],
+            });
+        }
+        return files;
+    }
+    async readText(path) {
+        try {
+            const content = await readFile(path);
+            if (content.subarray(0, 8_000).includes(0))
+                return "";
+            return content.toString("utf8");
+        }
+        catch {
+            return "";
+        }
+    }
+    terms(text) {
+        return [text, text.replace(/([a-z])([A-Z])/g, "$1 $2")]
+            .flatMap((part) => part.toLowerCase().split(/[^a-z0-9_$]+/))
+            .filter((term) => term.length > 2)
+            .filter((term, index, terms) => terms.indexOf(term) === index)
+            .slice(0, MAX_TERMS_PER_FILE);
+    }
+    symbols(text) {
+        return [
+            ...text.matchAll(/(?:function|class|interface|type|enum|const|let|var)\s+([A-Za-z_$][\w$]*)/g),
+        ]
+            .map((match) => match[1].toLowerCase())
+            .slice(0, MAX_SYMBOLS_PER_FILE);
+    }
+    connectFiles(files, sourceRoots, testRoots) {
+        const paths = new Set(files.map((file) => file.path));
+        const byPath = new Map(files.map((file) => [file.path, file]));
+        for (const file of files) {
+            const targets = new Set();
+            for (const specifier of file.imports) {
+                const target = this.resolveImport(file.path, specifier, paths);
+                if (target)
+                    targets.add(target);
+            }
+            const testTarget = this.testTarget(file.path, paths, sourceRoots, testRoots);
+            if (testTarget)
+                targets.add(testTarget);
+            file.relatedFiles = [...targets].sort();
+        }
+        for (const file of files) {
+            for (const target of file.relatedFiles) {
+                const targetFile = byPath.get(target);
+                if (targetFile && !targetFile.relatedFiles.includes(file.path))
+                    targetFile.relatedFiles.push(file.path);
+            }
+        }
+        return files.map((file) => ({ ...file, relatedFiles: file.relatedFiles.sort() }));
+    }
+    imports(text) {
+        return [...text.matchAll(/(?:import|export)\s+(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']/g)]
+            .map((match) => match[1])
+            .filter((specifier) => specifier.startsWith("."));
+    }
+    resolveImport(from, specifier, paths) {
+        const base = posix.normalize(posix.join(posix.dirname(from), specifier));
+        const extensionless = base.replace(/\.[^.\/]+$/, "");
+        return [
+            base,
+            extensionless,
+            ...SOURCE_EXTENSIONS.map((extension) => `${extensionless}${extension}`),
+            ...SOURCE_EXTENSIONS.map((extension) => `${extensionless}/index${extension}`),
+        ].find((candidate) => paths.has(candidate));
+    }
+    testTarget(file, paths, sourceRoots, testRoots) {
+        if (!testRoots.some((root) => file.startsWith(`${root}/`)))
+            return undefined;
+        const name = basename(file).replace(/\.(test|spec)\.[^.]+$/, "");
+        return sourceRoots
+            .flatMap((root) => SOURCE_EXTENSIONS.map((extension) => `${root}/${name}${extension}`))
+            .find((candidate) => paths.has(candidate));
+    }
+    isUseful(entry) {
+        return (entry.size <= MAX_INDEXED_FILE_BYTES &&
+            !LOCKFILE_NAMES.has(basename(entry.path).toLowerCase()) &&
+            !/(\.min\.js|\.map|\.lock)$/i.test(entry.path));
+    }
+}

package/dist/infrastructure/security/macos-keychain-store.d.ts

@@ -0,0 +1,17 @@
+import type { CredentialId } from "../../domain/models.js";
+import type { CredentialStore } from "../../domain/ports.js";
+type KeychainCommand = (file: string, args: string[]) => Promise<{
+    stdout: string;
+}>;
+export declare class MacOSKeychainStore implements CredentialStore {
+    private readonly command;
+    private readonly env;
+    constructor(command?: KeychainCommand, env?: NodeJS.ProcessEnv);
+    /** Reads an environment override first, then the macOS Keychain credential. */
+    get(provider: CredentialId): Promise<string | undefined>;
+    /** Saves a non-empty provider key in the macOS Keychain rather than local config. */
+    save(provider: CredentialId, value: string): Promise<void>;
+    /** Removes Kairo's saved Keychain entry during logout. */
+    clear(provider: CredentialId): Promise<void>;
+}
+export {};

package/dist/infrastructure/security/macos-keychain-store.js

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const account = "default";
+const services = {
+    gemini: "dev.kairo.gemini",
+    groq: "dev.kairo.groq",
+    mistral: "dev.kairo.mistral",
+    jev: "dev.kairo.jev",
+};
+const environment = {
+    gemini: "GEMINI_API_KEY",
+    groq: "GROQ_API_KEY",
+    mistral: "MISTRAL_API_KEY",
+    jev: "TYPESAFE_API_KEY",
+};
+export class MacOSKeychainStore {
+    command;
+    env;
+    constructor(command = run, env = process.env) {
+        this.command = command;
+        this.env = env;
+    }
+    /** Reads an environment override first, then the macOS Keychain credential. */
+    async get(provider) {
+        const override = this.env[environment[provider]];
+        if (override)
+            return override;
+        try {
+            return ((await this.command("security", [
+                "find-generic-password",
+                "-s",
+                services[provider],
+                "-a",
+                account,
+                "-w",
+            ])).stdout.trim() || undefined);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Saves a non-empty provider key in the macOS Keychain rather than local config. */
+    async save(provider, value) {
+        if (!value.trim())
+            throw new Error("API key cannot be empty.");
+        await this.command("security", [
+            "add-generic-password",
+            "-U",
+            "-s",
+            services[provider],
+            "-a",
+            account,
+            "-w",
+            value.trim(),
+        ]);
+    }
+    /** Removes Kairo's saved Keychain entry during logout. */
+    async clear(provider) {
+        try {
+            await this.command("security", [
+                "delete-generic-password",
+                "-s",
+                services[provider],
+                "-a",
+                account,
+            ]);
+        }
+        catch {
+            /* missing credential is already logged out */
+        }
+    }
+}

package/dist/infrastructure/tools/workspace-tools.d.ts

@@ -0,0 +1,30 @@
+import type { ToolCall, ToolResult } from "../../domain/models.js";
+import type { ToolDefinition, ToolExecutor } from "../../domain/ports.js";
+export declare const definitions: ToolDefinition[];
+export declare class WorkspaceTools implements ToolExecutor {
+    readonly root: string;
+    /** Stores the already-resolved workspace root used for every safety check. */
+    private constructor();
+    /** Resolves the requested workspace once before exposing any file tools. */
+    static create(workspace: string): Promise<WorkspaceTools>;
+    /** Returns whether an absolute path remains inside the resolved workspace root. */
+    private inside;
+    /** Validates a user path and rejects traversal or symlink escapes before access. */
+    private filePath;
+    /** Resolves an optional directory, treating a blank value as the workspace root. */
+    private directoryPath;
+    /** Produces the exact action text shown in the terminal approval prompt. */
+    description(call: ToolCall): string;
+    /** Dispatches a validated tool request and converts executor errors into tool results. */
+    execute(call: ToolCall): Promise<ToolResult>;
+    /** Recursively lists a bounded set of non-ignored workspace files. */
+    private list;
+    /** Searches readable workspace files for a literal query with bounded matches. */
+    private search;
+    /** Returns an inclusive, line-numbered slice while enforcing a small read limit. */
+    private readRange;
+    /** Replaces one unambiguous text occurrence in a workspace file. */
+    private edit;
+    /** Runs a shell command in the workspace and captures bounded output and timing. */
+    private command;
+}