@sunshinelife83/hearth 1.0.0

package/dist/config-migration.js

@@ -0,0 +1,82 @@
+import * as z from "zod/v4";
+import { HEARTH_CONFIG_VERSION, hearthConfigSchema, } from "./config-schema.js";
+import { storedSubagentsConfigSchema } from "./local-agent-config.js";
+import { LOCAL_AGENT_PROVIDERS } from "./local-agent-profiles.js";
+const legacyConfigSchema = z.object({
+    host: z.string().optional(),
+    port: z.number().optional(),
+    allowedRoots: z.array(z.string()).optional(),
+    publicBaseUrl: z.string().nullable().optional(),
+    allowedHosts: z.array(z.string()).optional(),
+    stateDir: z.string().optional(),
+    worktreeRoot: z.string().optional(),
+    artifactsEnabled: z.boolean().optional(),
+    artifactMaxFileBytes: z.number().optional(),
+    agentDir: z.string().optional(),
+    subagents: storedSubagentsConfigSchema.optional(),
+    tools: z.object({
+        mode: z.enum(["claude", "codex"]).optional(),
+    }).strict().optional(),
+    ui: z.object({
+        enabled: z.boolean().optional(),
+    }).strict().optional(),
+}).passthrough();
+const LEGACY_CONFIG_KEYS = new Set([
+    "host",
+    "port",
+    "allowedRoots",
+    "publicBaseUrl",
+    "allowedHosts",
+    "stateDir",
+    "worktreeRoot",
+    "artifactsEnabled",
+    "artifactMaxFileBytes",
+    "agentDir",
+    "subagents",
+    "tools",
+    "ui",
+]);
+export function migrateLegacyConfig(value) {
+    const legacy = legacyConfigSchema.parse(value);
+    const unsupportedKeys = Object.keys(legacy).filter((key) => !LEGACY_CONFIG_KEYS.has(key));
+    if (unsupportedKeys.length > 0) {
+        throw new Error(`Unsupported legacy configuration keys: ${unsupportedKeys.sort().join(", ")}`);
+    }
+    return hearthConfigSchema.parse({
+        configVersion: HEARTH_CONFIG_VERSION,
+        server: definedEntries({
+            host: legacy.host,
+            port: legacy.port,
+            publicBaseUrl: legacy.publicBaseUrl,
+            allowedHosts: legacy.allowedHosts,
+        }),
+        workspaces: definedEntries({
+            allowedRoots: legacy.allowedRoots,
+            worktreeRoot: legacy.worktreeRoot,
+        }),
+        storage: definedEntries({ stateDir: legacy.stateDir }),
+        tools: definedEntries({ mode: legacy.tools?.mode }),
+        ui: definedEntries({ enabled: legacy.ui?.enabled }),
+        artifacts: definedEntries({
+            enabled: legacy.artifactsEnabled,
+            maxFileBytes: legacy.artifactMaxFileBytes,
+        }),
+        skills: definedEntries({ agentDir: legacy.agentDir }),
+        subagents: migrateLegacySubagents(legacy.subagents),
+    });
+}
+function definedEntries(value) {
+    return Object.fromEntries(Object.entries(value).filter((entry) => entry[1] !== undefined));
+}
+function migrateLegacySubagents(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        return value;
+    return {
+        enabled: value,
+        providers: value
+            ? LOCAL_AGENT_PROVIDERS.map((id) => ({ id, enabled: true }))
+            : [],
+    };
+}

package/dist/config-schema.js

@@ -0,0 +1,136 @@
+import * as z from "zod/v4";
+import { subagentsConfigSchema } from "./local-agent-config.js";
+import { fleetConfigSchema } from "./orchestration/lanes.js";
+export const HEARTH_CONFIG_VERSION = 1;
+export const HEARTH_CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/Waishnav/hearth/main/schema/v1/hearth.schema.json";
+const serverConfigSchema = z.object({
+    host: z.string().trim().min(1).default("127.0.0.1"),
+    port: z.number().int().min(1).max(65_535).default(7176),
+    publicBaseUrl: z.string().url().nullable().default(null),
+    allowedHosts: z.array(z.string().trim().min(1)).default([]),
+    trustProxy: z.boolean().default(false),
+    // "derived": OAuth issuer/base URLs follow publicBaseUrl (today's behavior,
+    // required for remote clients like ChatGPT). "local": the issuer is pinned
+    // to the local bind address so changing the tunnel URL does not invalidate
+    // OAuth clients; only meaningful for local/LAN-only deployments.
+    issuerMode: z.enum(["derived", "local"]).default("derived"),
+}).strict().prefault({});
+const tlsConfigSchema = z.object({
+    // Native TLS for relay-free direct exposure: when both are set, `serve`
+    // terminates HTTPS itself (e.g. behind your own domain + port forward).
+    // Leave null when running behind localhost or a tunnel that terminates TLS.
+    certFile: z.string().trim().min(1).nullable().default(null),
+    keyFile: z.string().trim().min(1).nullable().default(null),
+    // Directory served (read-only) at /.well-known/acme-challenge/ so certbot
+    // webroot mode can provision certificates while the server runs.
+    acmeDir: z.string().trim().min(1).nullable().default(null),
+}).strict().prefault({});
+const workspaceProfileSchema = z.object({
+    path: z.string().trim().min(1).describe("Absolute path (or ~-prefixed) this profile applies to; longest prefix wins."),
+    mode: z.enum(["readonly", "supervised", "autonomous"]).optional(),
+    sandbox: z.enum(["auto", "none"]).optional(),
+    sandboxNetwork: z.enum(["allow", "deny"]).optional(),
+    requireSandboxForAutonomous: z.boolean().optional(),
+    commandAllow: z.array(z.string().trim().min(1)).default([]).describe("Regex allowlist; when non-empty only matching commands run."),
+    commandDeny: z.array(z.string().trim().min(1)).default([]).describe("Regex denylist; matching commands are always rejected."),
+    agentsAllowed: z.boolean().optional().describe("Whether agent tools may run for this workspace. Defaults to true."),
+}).strict();
+const workspacesConfigSchema = z.object({
+    allowedRoots: z.array(z.string().trim().min(1)).default([]),
+    worktreeRoot: z.string().trim().min(1).default("~/.hearth/worktrees"),
+    profiles: z.array(workspaceProfileSchema).default([]),
+}).strict().prefault({});
+const storageConfigSchema = z.object({
+    stateDir: z.string().trim().min(1).default("~/.local/share/hearth"),
+}).strict().prefault({});
+const toolsConfigSchema = z.object({
+    mode: z.enum(["claude", "codex"]).default("codex"),
+}).strict().prefault({});
+const uiConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+}).strict().prefault({});
+const artifactsConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    maxFileBytes: z.number().int().positive().default(100 * 1024 * 1024),
+}).strict().prefault({});
+const skillsConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    paths: z.array(z.string().trim().min(1)).default([]),
+    agentDir: z.string().trim().min(1).default("~/.codex"),
+}).strict().prefault({});
+const loggingConfigSchema = z.object({
+    level: z.enum(["silent", "error", "warn", "info", "debug"]).default("info"),
+    format: z.enum(["json", "pretty"]).default("json"),
+    requests: z.boolean().default(true),
+    assets: z.boolean().default(false),
+    toolCalls: z.boolean().default(true),
+    shellCommands: z.boolean().default(false),
+}).strict().prefault({});
+const executionConfigSchema = z.object({
+    // Policy mode for model-invoked shell tools:
+    // readonly    — tier-0 inspection commands only
+    // supervised  — tier 0/1 allowed; tier 2 requires an explicit
+    //               user-approval claim (approvedByUser) from the model
+    // autonomous  — tier 0/1/2 allowed without approval claims
+    // tier 3 commands are blocked in every mode.
+    mode: z.enum(["readonly", "supervised", "autonomous"]).default("supervised"),
+    // Pass the full parent environment to model-invoked commands. Insecure
+    // escape hatch; the default is a conservative allowlist.
+    envAllowAll: z.boolean().default(false),
+    // Additional environment variable names passed to model-invoked commands.
+    envAllowlist: z.array(z.string().trim().min(1)).default([]),
+    // OS sandbox for autonomous-mode shell commands and verification gates:
+    // "auto" uses bubblewrap (Linux) or seatbelt (macOS) when available.
+    sandbox: z.enum(["auto", "none"]).default("auto"),
+    sandboxNetwork: z.enum(["allow", "deny"]).default("allow"),
+    // When true, autonomous-mode tier-2/3 commands are denied unless a sandbox
+    // adapter is actually available (tier 3 is always denied regardless).
+    // Default true (fail closed): on machines without bubblewrap/seatbelt
+    // (notably Windows, where no equivalent exists), autonomous tier-2 is
+    // denied rather than silently unsandboxed. Opt out explicitly per
+    // workspace or globally when you accept unsandboxed autonomy.
+    requireSandboxForAutonomous: z.boolean().default(true),
+}).strict().prefault({});
+const oauthConfigSchema = z.object({
+    accessTokenTtlSeconds: z.number().int().positive().default(60 * 60),
+    refreshTokenTtlSeconds: z.number().int().positive().default(30 * 24 * 60 * 60),
+    scopes: z.array(z.string().trim().min(1)).min(1).default(["hearth"]),
+    allowedRedirectHosts: z.array(z.string().trim().min(1)).min(1).default([
+        "chatgpt.com",
+        "claude.ai",
+        "anthropic.com",
+        "localhost",
+        "127.0.0.1",
+    ]),
+}).strict().prefault({});
+export const hearthConfigSchema = z.object({
+    $schema: z.string().url().default(HEARTH_CONFIG_SCHEMA_URL),
+    configVersion: z.literal(HEARTH_CONFIG_VERSION),
+    server: serverConfigSchema,
+    workspaces: workspacesConfigSchema,
+    storage: storageConfigSchema,
+    tools: toolsConfigSchema,
+    ui: uiConfigSchema,
+    artifacts: artifactsConfigSchema,
+    skills: skillsConfigSchema,
+    subagents: subagentsConfigSchema.default({ enabled: false, providers: [] }),
+    fleet: fleetConfigSchema.default({ lanes: {} }),
+    execution: executionConfigSchema,
+    logging: loggingConfigSchema,
+    tls: tlsConfigSchema.default({ certFile: null, keyFile: null, acmeDir: null }),
+    oauth: oauthConfigSchema,
+}).strict();
+export function defaultHearthConfig() {
+    return hearthConfigSchema.parse({ configVersion: HEARTH_CONFIG_VERSION });
+}
+export function hearthConfigJsonSchema() {
+    return {
+        $id: HEARTH_CONFIG_SCHEMA_URL,
+        title: "Hearth configuration",
+        description: "Versioned configuration for a local Hearth MCP server.",
+        ...z.toJSONSchema(hearthConfigSchema, {
+            target: "draft-2020-12",
+            io: "input",
+        }),
+    };
+}

package/dist/config.js

@@ -0,0 +1,115 @@
+import { resolve } from "node:path";
+import { expandHomePath } from "./roots.js";
+import { hearthAgentsDir, hearthSkillsDir, loadHearthFiles } from "./user-config.js";
+export function loadConfig(env = process.env) {
+    const files = loadHearthFiles(env);
+    const stored = files.config;
+    const host = stored.server.host;
+    const port = stored.server.port;
+    const publicBaseUrl = parsePublicBaseUrl(stored.server.publicBaseUrl ?? localPublicBaseUrl(host, port));
+    const derivedAllowedHosts = [
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        host,
+        new URL(publicBaseUrl).hostname,
+        ...stored.server.allowedHosts,
+    ];
+    return {
+        configDir: files.dir,
+        host,
+        port,
+        oauth: {
+            ownerToken: parseRequiredSecret(env.HEARTH_OAUTH_OWNER_TOKEN ?? files.auth.ownerToken),
+            accessTokenTtlSeconds: stored.oauth.accessTokenTtlSeconds,
+            refreshTokenTtlSeconds: stored.oauth.refreshTokenTtlSeconds,
+            scopes: stored.oauth.scopes,
+            allowedRedirectHosts: stored.oauth.allowedRedirectHosts,
+            trustProxy: stored.server.trustProxy,
+        },
+        allowedRoots: normalizePaths(stored.workspaces.allowedRoots, [process.cwd()]),
+        workspaceProfiles: stored.workspaces.profiles.map((profile) => ({
+            path: normalizePath(profile.path),
+            ...(profile.mode !== undefined ? { mode: profile.mode } : {}),
+            ...(profile.sandbox !== undefined ? { sandbox: profile.sandbox } : {}),
+            ...(profile.sandboxNetwork !== undefined ? { sandboxNetwork: profile.sandboxNetwork } : {}),
+            ...(profile.requireSandboxForAutonomous !== undefined ? { requireSandboxForAutonomous: profile.requireSandboxForAutonomous } : {}),
+            commandAllow: profile.commandAllow,
+            commandDeny: profile.commandDeny,
+            ...(profile.agentsAllowed !== undefined ? { agentsAllowed: profile.agentsAllowed } : {}),
+        })),
+        allowedHosts: normalizeAllowedHosts(derivedAllowedHosts),
+        publicBaseUrl,
+        oauthIssuerUrl: stored.server.issuerMode === "local"
+            ? localPublicBaseUrl(host, port)
+            : publicBaseUrl,
+        toolMode: stored.tools.mode,
+        uiEnabled: stored.ui.enabled,
+        stateDir: normalizePath(stored.storage.stateDir),
+        worktreeRoot: normalizePath(stored.workspaces.worktreeRoot),
+        artifactsEnabled: stored.artifacts.enabled,
+        artifactMaxFileBytes: stored.artifacts.maxFileBytes,
+        skillsEnabled: stored.skills.enabled,
+        skillPaths: stored.skills.paths,
+        hearthSkillsDir: hearthSkillsDir(env),
+        hearthAgentsDir: hearthAgentsDir(env),
+        subagents: stored.subagents,
+        fleet: stored.fleet,
+        execution: {
+            mode: stored.execution.mode,
+            envAllowAll: stored.execution.envAllowAll,
+            envAllowlist: stored.execution.envAllowlist,
+            sandbox: stored.execution.sandbox,
+            sandboxNetwork: stored.execution.sandboxNetwork,
+            requireSandboxForAutonomous: stored.execution.requireSandboxForAutonomous,
+        },
+        agentDir: normalizePath(stored.skills.agentDir),
+        logging: {
+            ...stored.logging,
+            trustProxy: stored.server.trustProxy,
+        },
+        tls: {
+            certFile: stored.tls.certFile,
+            keyFile: stored.tls.keyFile,
+            acmeDir: stored.tls.acmeDir,
+        },
+    };
+}
+function normalizePaths(paths, fallback = []) {
+    return (paths.length > 0 ? paths : fallback).map(normalizePath);
+}
+function normalizePath(path) {
+    return resolve(expandHomePath(path));
+}
+function normalizeAllowedHosts(hosts) {
+    if (hosts.includes("*"))
+        return ["*"];
+    return Array.from(new Set(hosts.map((host) => host.trim()).filter(Boolean)));
+}
+function parseRequiredSecret(value) {
+    const secret = value?.trim();
+    if (!secret) {
+        throw new Error("OAuth owner token is required. Run: hearth init");
+    }
+    if (secret.length < 16) {
+        throw new Error("OAuth owner token must be at least 16 characters long.");
+    }
+    return secret;
+}
+function parsePublicBaseUrl(value) {
+    const parsed = new URL(value);
+    parsed.hash = "";
+    parsed.search = "";
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+    if (/(^|\/)mcp$/i.test(parsed.pathname)) {
+        throw new Error(`Invalid publicBaseUrl ${JSON.stringify(value)}: use the origin without /mcp (for example https://${parsed.host}). Fix with: hearth config set publicBaseUrl https://${parsed.host}`);
+    }
+    return parsed.toString().replace(/\/$/, "");
+}
+function localPublicBaseUrl(host, port) {
+    const publicHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+    const formattedHost = publicHost.includes(":") && !publicHost.startsWith("[")
+        ? `[${publicHost}]`
+        : publicHost;
+    return `http://${formattedHost}:${port}`;
+}

package/dist/context/context-tools.js

@@ -0,0 +1,150 @@
+import * as z from "zod/v4";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { buildRepoMap, formatRepoMap } from "./repo-map.js";
+import { logToolCall, resultOutputSchema, textBlock } from "../tool-surfaces/shared.js";
+import { workspaceIdDescription } from "../tool-surfaces/types.js";
+/**
+ * Context tools (P6, first slice): a repository overview and a bounded
+ * text search. Both are read-only, run locally, and hand the model curated
+ * repository knowledge instead of forcing it to shell its way around.
+ */
+const execFileAsync = promisify(execFile);
+let ripgrepAvailable;
+function hasRipgrep() {
+    ripgrepAvailable ??= (() => {
+        try {
+            execFileSyncShort("rg", ["--version"]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return ripgrepAvailable;
+}
+function execFileSyncShort(command, args) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { execFileSync } = require("node:child_process");
+    execFileSync(command, args, { stdio: "ignore", timeout: 5000 });
+}
+const MAX_SEARCH_OUTPUT_CHARS = 40_000;
+export function registerContextTools(target, context) {
+    const { config, workspaces } = context;
+    target.registerTool("context_overview", {
+        title: "Repository overview",
+        description: "Get a bounded repository map for the workspace: file counts, languages, manifests, and the largest directories. Use this before exploring a large repository so you stop guessing where things live.",
+        inputSchema: { workspaceId: z.string().describe(workspaceIdDescription) },
+        outputSchema: resultOutputSchema(),
+        annotations: { readOnlyHint: true },
+    }, async ({ workspaceId }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const map = await buildRepoMap(workspace.root);
+        const text = formatRepoMap(map);
+        logToolCall(config, {
+            tool: "context_overview",
+            workspaceId,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content: [textBlock(text)],
+            structuredContent: {
+                result: text,
+                totalFiles: map.totalFiles,
+                truncated: map.truncated,
+                manifests: map.manifests,
+                languages: map.languages,
+            },
+        };
+    });
+    target.registerTool("search", {
+        title: "Search workspace",
+        description: "Search file contents in the workspace with a regex (ripgrep when available, grep fallback). Read-only and bounded; prefer this over shell grep pipelines.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            pattern: z.string().min(1).max(500).describe("Regular expression to find."),
+            glob: z.string().max(200).optional().describe("Optional glob filter, e.g. '*.ts'."),
+            maxResults: z.number().int().min(1).max(500).optional().describe("Result line cap. Defaults to 100."),
+        },
+        outputSchema: resultOutputSchema(),
+        annotations: { readOnlyHint: true },
+    }, async ({ workspaceId, pattern, glob, maxResults }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const cap = maxResults ?? 100;
+        let text;
+        try {
+            text = await runSearch(workspace.root, pattern, glob, cap);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logToolCall(config, {
+                tool: "search",
+                workspaceId,
+                success: false,
+                durationMs: Math.round(performance.now() - startedAt),
+                error: message.slice(0, 200),
+            });
+            return {
+                content: [textBlock(`Search failed: ${message}`)],
+                isError: true,
+                structuredContent: { result: `Search failed: ${message}` },
+            };
+        }
+        logToolCall(config, {
+            tool: "search",
+            workspaceId,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content: [textBlock(text)],
+            structuredContent: { result: text },
+        };
+    });
+}
+async function runSearch(root, pattern, glob, cap) {
+    const args = hasRipgrep()
+        ? [
+            "rg", "--no-heading", "-n", "-S",
+            "--max-count", String(Math.min(cap, 500)),
+            "--glob", "!node_modules/**", "--glob", "!.git/**",
+            ...(glob ? ["-g", glob] : []),
+            pattern, root,
+        ]
+        : [
+            "grep", "-rn", "-E", "-I",
+            "--exclude-dir=node_modules", "--exclude-dir=.git",
+            ...(glob ? [`--include=${glob}`] : []),
+            pattern, root,
+        ];
+    const argv = args.slice(1);
+    const command = args[0];
+    try {
+        const { stdout } = await execFileAsync(command, argv, {
+            cwd: root,
+            timeout: 10_000,
+            maxBuffer: 1024 * 1024,
+        });
+        return bound(String(stdout), cap);
+    }
+    catch (error) {
+        const err = error;
+        // grep/rg exit 1 on "no matches" — that is a successful empty search.
+        if (err.code === 1)
+            return "No matches.";
+        if (typeof err.stdout === "string" && err.stdout)
+            return bound(err.stdout, cap);
+        throw error;
+    }
+}
+function bound(output, cap) {
+    const lines = output.split("\n").filter((line) => line.trim().length > 0).slice(0, cap);
+    let text = lines.join("\n");
+    if (text.length > MAX_SEARCH_OUTPUT_CHARS) {
+        text = `${text.slice(0, MAX_SEARCH_OUTPUT_CHARS)}\n…output truncated`;
+    }
+    return text || "No matches.";
+}

package/dist/context/repo-map.js

@@ -0,0 +1,102 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+/**
+ * Context Engine, first slice (P6): a deterministic, local repository map.
+ * No embeddings, no network — just the structure a model needs to stop
+ * re-walking the tree: languages, manifests, and a bounded directory tree.
+ */
+const SKIP_DIRS = new Set([
+    ".git", ".hg", ".svn", "node_modules", "dist", "build", "out", ".next",
+    ".turbo", ".cache", ".venv", "venv", "__pycache__", "target", "coverage",
+    ".idea", ".vscode", "vendor",
+]);
+const MANIFESTS = [
+    "package.json", "Cargo.toml", "go.mod", "pyproject.toml",
+    "requirements.txt", "Makefile", "composer.json", "Gemfile", "pom.xml",
+];
+export async function buildRepoMap(root, options = {}) {
+    const maxFiles = options.maxFiles ?? 5000;
+    const maxDepth = options.maxDepth ?? 20;
+    const files = [];
+    const dirFiles = new Map();
+    const manifests = new Set();
+    let truncated = false;
+    const walk = async (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+                    await walk(path, depth + 1);
+                }
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (files.length >= maxFiles) {
+                truncated = true;
+                return;
+            }
+            files.push(path);
+            dirFiles.set(dir, (dirFiles.get(dir) ?? 0) + 1);
+            if (MANIFESTS.includes(entry.name))
+                manifests.add(entry.name);
+        }
+    };
+    await walk(root, 0);
+    const byExt = new Map();
+    let totalBytes = 0;
+    for (const file of files) {
+        const ext = extname(file).toLowerCase() || "(none)";
+        byExt.set(ext, (byExt.get(ext) ?? 0) + 1);
+        try {
+            const stats = await stat(file);
+            totalBytes += stats.size;
+        }
+        catch {
+            // File vanished mid-walk; fine for an approximate map.
+        }
+    }
+    const languages = [...byExt.entries()]
+        .map(([extension, count]) => ({ extension, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 12);
+    const directories = [...dirFiles.entries()]
+        .map(([dir, count]) => ({ path: relative(root, dir) || ".", files: count }))
+        .filter((entry) => entry.path !== ".")
+        .sort((a, b) => b.files - a.files)
+        .slice(0, 25);
+    return {
+        root,
+        totalFiles: files.length,
+        truncated,
+        totalBytes,
+        languages,
+        manifests: [...manifests].sort(),
+        directories,
+    };
+}
+export function formatRepoMap(map) {
+    const lines = [
+        `Repository map for ${map.root}`,
+        `Files: ${map.totalFiles}${map.truncated ? "+ (truncated)" : ""}, ~${Math.round(map.totalBytes / 1024)} KB`,
+        `Manifests: ${map.manifests.length > 0 ? map.manifests.join(", ") : "none detected"}`,
+        "Languages: " + map.languages.map((lang) => `${lang.extension}×${lang.count}`).join(", "),
+        "Largest directories:",
+        ...map.directories.map((dir) => `  ${dir.path} (${dir.files} files)`),
+    ];
+    return lines.join("\n");
+}
+/** Cheap text file reader used by context tools (bounded). */
+export async function readTextHead(path, maxBytes = 64 * 1024) {
+    const content = await readFile(path, "utf8");
+    return content.length > maxBytes ? content.slice(0, maxBytes) : content;
+}