ankui 0.1.0

package/dist/scanner/safety.js

@@ -0,0 +1,330 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createWarning } from "../types.js";
+import { isPathInside, splitPathSegments } from "./paths.js";
+export const MAX_SAFE_FILE_BYTES = 1024 * 1024;
+export const MASKED_SECRET = "......";
+const allowedRootCache = new Map();
+function resolveRootCached(root) {
+    const normalized = path.resolve(root);
+    const cached = allowedRootCache.get(normalized);
+    if (cached) {
+        return cached;
+    }
+    const promise = fs.realpath(normalized).catch(() => normalized);
+    allowedRootCache.set(normalized, promise);
+    return promise;
+}
+export async function checkSafePath(filePath, options = {}) {
+    const sensitiveWarning = createSensitivePathWarning(options.sensitivePath ?? filePath, filePath);
+    if (sensitiveWarning) {
+        return safeFailure([sensitiveWarning]);
+    }
+    let resolvedPath;
+    try {
+        resolvedPath = await fs.realpath(filePath);
+    }
+    catch (error) {
+        const warning = createFsWarning(error, filePath, options.warnOnMissing ?? true);
+        return warning ? safeFailure([warning]) : safeFailure([]);
+    }
+    const normalizedPath = path.resolve(filePath);
+    const linked = normalizedPath !== resolvedPath &&
+        !resolvedPath.endsWith(normalizedPath) &&
+        !normalizedPath.endsWith(resolvedPath);
+    if (linked) {
+        const allowedRoots = options.allowedRoots ?? [os.homedir(), os.tmpdir()];
+        const resolvedRoots = await Promise.all(allowedRoots.map(resolveRootCached));
+        if (!resolvedRoots.some((root) => isPathInside(resolvedPath, root))) {
+            return safeFailure([
+                createWarning({
+                    reason: "symlink_skipped",
+                    path: filePath,
+                    message: `Skipped symlink whose target is outside allowed roots: ${filePath} -> ${resolvedPath}`
+                })
+            ]);
+        }
+        if (hasSensitivePathSegment(resolvedPath)) {
+            return safeFailure([
+                createWarning({
+                    reason: "symlink_skipped",
+                    path: filePath,
+                    message: `Skipped symlink whose target hits a sensitive path: ${filePath} -> ${resolvedPath}`
+                })
+            ]);
+        }
+    }
+    let stat;
+    try {
+        stat = await fs.stat(resolvedPath);
+    }
+    catch (error) {
+        const warning = createFsWarning(error, filePath, options.warnOnMissing ?? true);
+        return warning ? safeFailure([warning]) : safeFailure([]);
+    }
+    if (options.expectedType === "file" && !stat.isFile()) {
+        return safeFailure([
+            createWarning({
+                reason: "unknown",
+                path: filePath,
+                message: `Expected a file but found another filesystem entry: ${filePath}`
+            })
+        ]);
+    }
+    if (options.expectedType === "directory" && !stat.isDirectory()) {
+        return safeFailure([
+            createWarning({
+                reason: "unknown",
+                path: filePath,
+                message: `Expected a directory but found another filesystem entry: ${filePath}`
+            })
+        ]);
+    }
+    if (stat.isFile() && stat.size > (options.maxBytes ?? MAX_SAFE_FILE_BYTES)) {
+        return safeFailure([
+            createWarning({
+                reason: "file_too_large",
+                path: filePath,
+                message: `Skipped file larger than 1 MB: ${filePath}`
+            })
+        ]);
+    }
+    return safeSuccess({
+        path: filePath,
+        stat,
+        linked,
+        linkTarget: linked ? resolvedPath : undefined
+    });
+}
+export async function getLinkInfo(filePath) {
+    try {
+        const resolved = await fs.realpath(filePath);
+        const normalized = path.resolve(filePath);
+        if (normalized === resolved ||
+            resolved.endsWith(normalized) ||
+            normalized.endsWith(resolved)) {
+            return { linked: false };
+        }
+        return { linked: true, linkTarget: resolved };
+    }
+    catch {
+        return { linked: false };
+    }
+}
+export async function safeReadTextFile(filePath, options = {}) {
+    const safety = await checkSafePath(filePath, {
+        ...options,
+        expectedType: "file"
+    });
+    if (!safety.ok) {
+        return safety;
+    }
+    try {
+        const text = await fs.readFile(filePath, "utf8");
+        return safeSuccess(text, safety.warnings);
+    }
+    catch (error) {
+        const warning = createFsWarning(error, filePath, true);
+        return safeFailure([...safety.warnings, warning ?? createUnknownWarning(filePath, error)]);
+    }
+}
+export async function safeReadDirectory(directoryPath, options = {}) {
+    const safety = await checkSafePath(directoryPath, {
+        ...options,
+        expectedType: "directory"
+    });
+    if (!safety.ok) {
+        return safety;
+    }
+    try {
+        const entries = await fs.readdir(directoryPath, { withFileTypes: true });
+        return safeSuccess(entries, safety.warnings);
+    }
+    catch (error) {
+        const warning = createFsWarning(error, directoryPath, true);
+        return safeFailure([...safety.warnings, warning ?? createUnknownWarning(directoryPath, error)]);
+    }
+}
+export function isSensitivePath(filePath) {
+    return createSensitivePathWarning(filePath) !== undefined;
+}
+export function isSecretLikeKey(key) {
+    const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+    const compactKey = normalizedKey.replace(/_/g, "");
+    return (normalizedKey === "auth" ||
+        normalizedKey === "authorization" ||
+        normalizedKey.includes("token") ||
+        normalizedKey.includes("secret") ||
+        normalizedKey.includes("credential") ||
+        normalizedKey.includes("password") ||
+        normalizedKey.includes("passwd") ||
+        compactKey.includes("apikey") ||
+        compactKey.includes("privatekey") ||
+        compactKey.includes("accesstoken") ||
+        compactKey.includes("refreshtoken") ||
+        compactKey.includes("authtoken") ||
+        compactKey.includes("clientsecret"));
+}
+export function maskSecrets(value) {
+    return sanitizeValue(value, false);
+}
+export function maskUrl(value) {
+    try {
+        const parsed = new URL(value);
+        if (parsed.username || parsed.password) {
+            parsed.username = MASKED_SECRET;
+            parsed.password = MASKED_SECRET;
+            return parsed.toString();
+        }
+    }
+    catch {
+        // not a URL — fall through
+    }
+    return maskSecretText(value);
+}
+export function maskSecretText(text) {
+    return text
+        .replace(/((?:["']?)\b[\w.-]*(?:token|secret|credential|password|passwd|api[_-]?key|apikey|private[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|client[_-]?secret)[\w.-]*\b(?:["']?)\s*[:=]\s*)(["']?)[^"',\s}]+(["']?)/gi, (_match, prefix, openQuote, closeQuote) => `${prefix}${openQuote}${MASKED_SECRET}${closeQuote || openQuote}`)
+        .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+=*/gi, `$1${MASKED_SECRET}`)
+        .replace(/([?&](?:token|secret|password|api_key|apikey|access_token|refresh_token)=)[^&\s]+/gi, `$1${MASKED_SECRET}`)
+        .replace(/\bgh[pousr]_[A-Za-z0-9_]{8,}\b/g, MASKED_SECRET)
+        .replace(/\bsk-[A-Za-z0-9]{16,}\b/g, MASKED_SECRET);
+}
+function createSensitivePathWarning(sensitivePath, warningPath = sensitivePath) {
+    if (!hasSensitivePathSegment(sensitivePath)) {
+        return undefined;
+    }
+    return createWarning({
+        reason: "sensitive_file_skipped",
+        path: warningPath,
+        message: `Skipped sensitive path: ${warningPath}`
+    });
+}
+function hasSensitivePathSegment(filePath) {
+    const segments = splitPathSegments(filePath);
+    const lowerSegments = segments.map((segment) => segment.toLowerCase());
+    const isOpenCodePath = lowerSegments.some((segment) => segment === "opencode" || segment === ".opencode");
+    return lowerSegments.some((segment) => {
+        const basename = path.basename(segment);
+        return (isSensitiveName(basename) ||
+            isCommonSensitiveDirectoryName(basename) ||
+            (isOpenCodePath && isOpenCodeSensitiveDirectoryName(basename)));
+    });
+}
+function isSensitiveName(name) {
+    return (name === ".env" ||
+        name.startsWith(".env") ||
+        name.includes("token") ||
+        name.includes("secret") ||
+        name.includes("credential") ||
+        name.startsWith("auth") ||
+        name.startsWith("cookies") ||
+        name.startsWith("session") ||
+        name.endsWith(".pem") ||
+        name.endsWith(".key") ||
+        name.includes("apikey") ||
+        name.includes("api_key") ||
+        name.startsWith("private_key"));
+}
+function isCommonSensitiveDirectoryName(name) {
+    return (name === "sessions" ||
+        name === "session" ||
+        name === "history" ||
+        name === "histories" ||
+        name === "conversation" ||
+        name === "conversations");
+}
+function isOpenCodeSensitiveDirectoryName(name) {
+    return (name === "auth" ||
+        name === "log" ||
+        name === "logs" ||
+        name === "share" ||
+        name === "cache" ||
+        name === "database" ||
+        name === "databases" ||
+        name === "db" ||
+        name === "runtime" ||
+        isCommonSensitiveDirectoryName(name));
+}
+function sanitizeValue(value, inEnvBlock) {
+    if (Array.isArray(value)) {
+        return inEnvBlock ? value.map(maskSecretValue) : value.map((item) => sanitizeValue(item, false));
+    }
+    if (!isRecord(value)) {
+        return inEnvBlock ? MASKED_SECRET : value;
+    }
+    const sanitized = {};
+    for (const [key, entryValue] of Object.entries(value)) {
+        if (key.toLowerCase() === "env" && isRecord(entryValue)) {
+            sanitized[key] = maskEnvBlock(entryValue);
+            continue;
+        }
+        if (inEnvBlock || isSecretLikeKey(key)) {
+            sanitized[key] = maskSecretValue(entryValue);
+            continue;
+        }
+        sanitized[key] = sanitizeValue(entryValue, false);
+    }
+    return sanitized;
+}
+function maskEnvBlock(env) {
+    return Object.fromEntries(Object.keys(env).map((key) => [key, MASKED_SECRET]));
+}
+function maskSecretValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(maskSecretValue);
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.keys(value).map((key) => [key, MASKED_SECRET]));
+    }
+    return MASKED_SECRET;
+}
+function isRecord(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+function safeSuccess(value, warnings = []) {
+    return {
+        ok: true,
+        value,
+        warnings
+    };
+}
+function safeFailure(warnings) {
+    return {
+        ok: false,
+        warnings
+    };
+}
+function createFsWarning(error, filePath, warnOnMissing) {
+    if (isNodeError(error)) {
+        if (error.code === "ENOENT" && !warnOnMissing) {
+            return undefined;
+        }
+        if (error.code === "EACCES" || error.code === "EPERM") {
+            return createWarning({
+                reason: "permission_denied",
+                path: filePath,
+                message: `Permission denied while reading: ${filePath}`
+            });
+        }
+    }
+    return createUnknownWarning(filePath, error);
+}
+function createUnknownWarning(filePath, error) {
+    return createWarning({
+        reason: "unknown",
+        path: filePath,
+        message: `Could not read ${filePath}: ${formatErrorMessage(error)}`
+    });
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function formatErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=safety.js.map

package/dist/scanner/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../src/scanner/safety.ts"],"names":[],"mappings":"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"}

package/dist/scanner/skill-naming.d.ts

@@ -0,0 +1,5 @@
+export interface CanonicalMcpName {
+    canonical: string;
+    mcpId?: string;
+}
+export declare function canonicalMcpName(rawName: string): CanonicalMcpName;

package/dist/scanner/skill-naming.js

@@ -0,0 +1,53 @@
+const KNOWN_MCP_ALIASES = [
+    { mcpId: "github", canonical: "GitHub", keys: ["github", "githubmcp", "octocat"] },
+    { mcpId: "gitlab", canonical: "GitLab", keys: ["gitlab"] },
+    { mcpId: "postgres", canonical: "Postgres", keys: ["postgres", "postgresql", "pg"] },
+    { mcpId: "mysql", canonical: "MySQL", keys: ["mysql", "mariadb"] },
+    { mcpId: "sqlite", canonical: "SQLite", keys: ["sqlite"] },
+    { mcpId: "filesystem", canonical: "Filesystem", keys: ["filesystem", "fs", "localfiles"] },
+    { mcpId: "shell", canonical: "Shell", keys: ["shell", "bash", "terminal"] },
+    { mcpId: "slack", canonical: "Slack", keys: ["slack"] },
+    { mcpId: "discord", canonical: "Discord", keys: ["discord"] },
+    { mcpId: "linear", canonical: "Linear", keys: ["linear"] },
+    { mcpId: "jira", canonical: "Jira", keys: ["jira", "atlassianjira"] },
+    { mcpId: "notion", canonical: "Notion", keys: ["notion"] },
+    { mcpId: "puppeteer", canonical: "Puppeteer", keys: ["puppeteer"] },
+    { mcpId: "playwright", canonical: "Playwright", keys: ["playwright"] },
+    { mcpId: "browser", canonical: "Browser MCP", keys: ["browser", "browsermcp"] },
+    { mcpId: "sentry", canonical: "Sentry", keys: ["sentry"] },
+    { mcpId: "context7", canonical: "Context7", keys: ["context7"] },
+    { mcpId: "shadcn", canonical: "shadcn", keys: ["shadcn"] },
+    { mcpId: "reddit", canonical: "Reddit", keys: ["reddit"] },
+    { mcpId: "vercel", canonical: "Vercel", keys: ["vercel"] },
+    { mcpId: "supabase", canonical: "Supabase", keys: ["supabase"] }
+];
+const KEY_TO_ALIAS = (() => {
+    const map = new Map();
+    for (const alias of KNOWN_MCP_ALIASES) {
+        for (const key of alias.keys) {
+            map.set(key, { mcpId: alias.mcpId, canonical: alias.canonical });
+        }
+    }
+    return map;
+})();
+function normalizeMatchKey(rawName) {
+    return rawName.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+export function canonicalMcpName(rawName) {
+    const matchKey = normalizeMatchKey(rawName);
+    const hit = KEY_TO_ALIAS.get(matchKey);
+    if (hit) {
+        return { canonical: hit.canonical, mcpId: hit.mcpId };
+    }
+    for (const suffix of ["mcp", "server", "mcpserver"]) {
+        if (matchKey.endsWith(suffix) && matchKey.length > suffix.length) {
+            const stripped = matchKey.slice(0, -suffix.length);
+            const stripHit = KEY_TO_ALIAS.get(stripped);
+            if (stripHit) {
+                return { canonical: stripHit.canonical, mcpId: stripHit.mcpId };
+            }
+        }
+    }
+    return { canonical: rawName };
+}
+//# sourceMappingURL=skill-naming.js.map

package/dist/scanner/skill-naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-naming.js","sourceRoot":"","sources":["../../src/scanner/skill-naming.ts"],"names":[],"mappings":"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"}

package/dist/scanner/watcher.d.ts

@@ -0,0 +1,15 @@
+export interface CreateWatcherOptions {
+    /** Absolute paths (files or directories) to watch. */
+    paths: readonly string[];
+    /** Called once per stable, non-ignored event. */
+    onChange: (eventPath: string) => void;
+    /** Synchronous predicate — true means "drop the event, do not call onChange". */
+    isIgnored: (eventPath: string) => boolean;
+    /** chokidar stabilityThreshold for coalescing rapid writes. Default 300ms. */
+    debounceMs?: number;
+}
+export interface WatcherHandle {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createWatcher(options: CreateWatcherOptions): WatcherHandle;

package/dist/scanner/watcher.js

@@ -0,0 +1,71 @@
+import chokidar from "chokidar";
+const DEFAULT_DEBOUNCE_MS = 300;
+export function createWatcher(options) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    let watcher;
+    let stopped = false;
+    return {
+        async start() {
+            if (watcher || stopped)
+                return;
+            watcher = chokidar.watch(options.paths, {
+                // Don't follow symlinks — Phase 3 safety contract.
+                followSymlinks: false,
+                // Don't replay an "add" event for every existing file on startup.
+                // We only care about post-launch changes.
+                ignoreInitial: true,
+                // Top-level ignore filter — chokidar calls this for every path it
+                // considers, including descendants. Returning true short-circuits the
+                // entire subtree.
+                ignored: (eventPath) => options.isIgnored(eventPath),
+                // Coalesce rapid editor-save bursts. chokidar emits a single event
+                // once the file has been quiet for stabilityThreshold ms.
+                awaitWriteFinish: {
+                    stabilityThreshold: debounceMs,
+                    pollInterval: Math.min(50, debounceMs)
+                }
+            });
+            const forward = (eventPath) => {
+                if (stopped)
+                    return;
+                if (options.isIgnored(eventPath))
+                    return;
+                options.onChange(eventPath);
+            };
+            watcher.on("add", forward);
+            watcher.on("change", forward);
+            watcher.on("unlink", forward);
+            watcher.on("addDir", forward);
+            watcher.on("unlinkDir", forward);
+            // chokidar v4 reports errors via "error"; we swallow them — a per-watch
+            // failure must never crash the host process.
+            watcher.on("error", () => {
+                // intentionally ignored; orchestrator surfaces failures separately
+            });
+            // Wait for chokidar to finish its first pass so the caller can trust
+            // that subsequent fs operations will be observed.
+            await new Promise((resolve) => {
+                if (!watcher)
+                    return resolve();
+                const onReady = () => resolve();
+                watcher.once("ready", onReady);
+                // Safety net: don't hang forever if "ready" never fires (e.g. ghost path).
+                setTimeout(resolve, 1000).unref();
+            });
+        },
+        async stop() {
+            stopped = true;
+            if (!watcher)
+                return;
+            const w = watcher;
+            watcher = undefined;
+            try {
+                await w.close();
+            }
+            catch {
+                // closing twice or against a half-initialized watcher is fine
+            }
+        }
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/scanner/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/scanner/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,QAA4B,MAAM,UAAU,CAAC;AAkBpD,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC7D,IAAI,OAA8B,CAAC;IACnC,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,OAAO,IAAI,OAAO;gBAAE,OAAO;YAC/B,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,KAAiB,EAAE;gBAClD,mDAAmD;gBACnD,cAAc,EAAE,KAAK;gBACrB,kEAAkE;gBAClE,0CAA0C;gBAC1C,aAAa,EAAE,IAAI;gBACnB,kEAAkE;gBAClE,sEAAsE;gBACtE,kBAAkB;gBAClB,OAAO,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC;gBAC5D,mEAAmE;gBACnE,0DAA0D;gBAC1D,gBAAgB,EAAE;oBAChB,kBAAkB,EAAE,UAAU;oBAC9B,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC;iBACvC;aACF,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAQ,EAAE;gBAC1C,IAAI,OAAO;oBAAE,OAAO;gBACpB,IAAI,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC;oBAAE,OAAO;gBACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC9B,CAAC,CAAC;YAEF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9B,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YACjC,wEAAwE;YACxE,6CAA6C;YAC7C,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;gBACvB,mEAAmE;YACrE,CAAC,CAAC,CAAC;YAEH,qEAAqE;YACrE,kDAAkD;YAClD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,IAAI,CAAC,OAAO;oBAAE,OAAO,OAAO,EAAE,CAAC;gBAC/B,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,OAAO,EAAE,CAAC;gBACtC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC/B,2EAA2E;gBAC3E,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;YACpC,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,IAAI;YACR,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,MAAM,CAAC,GAAG,OAAO,CAAC;YAClB,OAAO,GAAG,SAAS,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,8DAA8D;YAChE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tui/App.d.ts

@@ -0,0 +1,33 @@
+import React from "react";
+import type { MultiProjectScanResult } from "../types.js";
+import type { CrawlOptions, CrawlResult } from "../scanner/filesystem-crawler.js";
+export type AppMode = "firstRun" | "main";
+export interface DataSource {
+    initial: MultiProjectScanResult;
+    subscribe?: (cb: (next: MultiProjectScanResult) => void) => () => void;
+}
+export type AppProps = {
+    mode?: "main";
+    result: MultiProjectScanResult;
+    dataSource?: never;
+    homeDir?: string;
+    onConfigChange?: (devRoots: string[]) => Promise<void>;
+    crawlImplForFirstRun?: (options: CrawlOptions) => Promise<CrawlResult>;
+    onRefresh?: () => Promise<void>;
+} | {
+    mode?: "main";
+    dataSource: DataSource;
+    result?: never;
+    homeDir?: string;
+    onConfigChange?: (devRoots: string[]) => Promise<void>;
+    crawlImplForFirstRun?: (options: CrawlOptions) => Promise<CrawlResult>;
+    onRefresh?: () => Promise<void>;
+} | {
+    mode: "firstRun";
+    result?: null;
+    dataSource?: never;
+    homeDir: string;
+    onConfigChange: (devRoots: string[]) => Promise<void>;
+    crawlImplForFirstRun?: (options: CrawlOptions) => Promise<CrawlResult>;
+};
+export declare function App(props: AppProps): React.ReactElement;