@kindgi/handler-runtime 0.0.0-bootstrap.0 → 0.1.0

package/dist/kindgi-index.js

@@ -0,0 +1,1201 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * `kindgi-index` — the pack indexer, which writes a pack's `index.json`.
+ * `kindgi dev` runs it over the dev bundles; a pack image's indexer
+ * stage runs it (process entry `kindgi-index-main`, bundled as
+ * `dist/kindgi-index.mjs`) over the image's bundles, and `kindgi build`
+ * runs the same bundle locally, so the two indexes compare.
+ *
+ * The indexer:
+ *
+ *   1. Loads `kindgi.config.ts` (or `.js` / `.mjs`) at the pack root
+ *      to read `pack.id` / `pack.version` + optional `discovery` glob
+ *      overrides.
+ *   2. Discovers files under the four default folders — `tools/`,
+ *      `guardrails/`, `agents/`, `flows/` — using the config's
+ *      discovery patterns; or, indexing a build, takes the files a
+ *      bundle map lists (`bundleMap`), classified by the same patterns.
+ *   3. Dynamically imports each file (from its bundle, given a map).
+ *      Reads the `default` export
+ *      (accepting either the raw primitive shape or a `Result`-wrapped
+ *      envelope from `defineTool` / `defineGuardrail` / etc.).
+ *   4. Kind-maps the discovered file by its default folder (primary) or
+ *      by structural shape of the default export (fallback for
+ *      custom-pattern files).
+ *   5. For every Zod-typed schema (`tool.inputZod`, `tool.outputZod`,
+ *      `check.configZod`) calls `@kindgi/schema.toJSONSchemaSync` to
+ *      derive the JSON Schema wire form. When JSON Schema is authored
+ *      directly, it is emitted verbatim.
+ *   6. Assembles a `v: 1` `index.json` envelope and writes it
+ *      atomically (write-to-tmp, then rename) to the configured output
+ *      path.
+ *
+ * ## Fail loud at every boundary
+ *
+ * Missing config, missing default export, kind mismatch, Zod conversion
+ * failure, filesystem write error — each is a distinct typed
+ * `IndexerError` variant with the file path attached. No silent skips.
+ *
+ * ## Determinism
+ *
+ * The integrity gate (locally verify the server's build) diffs an indexer output computed on the developer's
+ * laptop against the server's output. Byte-identical inputs must
+ * produce byte-identical outputs. All list fields are sorted
+ * lexicographically by id; JSON serialization uses compact stable
+ * output; `publishedAt` is accepted as an explicit `opts.publishedAt`
+ * for reproducible builds (the pack build passes it) and defaults to
+ * `new Date()` only for local dev (documented in the README).
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadFlow } from '@kindgi/flow';
+import { isZodSchema, loadZodConverterSync, toJSONSchemaSync } from '@kindgi/schema';
+import { parse as parseToml } from 'smol-toml';
+import { TEST_FILE_REGEX, globStaticPrefix, globToRegex } from './discovery.js';
+import { resolvePackEnv } from './pack-env.js';
+// -----------------------------------------------------------------------
+// Public envelope + shape types
+// -----------------------------------------------------------------------
+/**
+ * Envelope version emitted on `index.json`. Bump on breaking change;
+ * additive fields on an existing shape don't bump. Consumers (the
+ * controller) MUST refuse an envelope version they
+ * don't recognize.
+ */
+export const INDEX_ENVELOPE_VERSION = 1;
+/** The language of a loaded config's pack code. */
+export function packLanguage(config) {
+    return config.language ?? 'node';
+}
+/**
+ * Default discovery patterns. Extensions
+ * `.ts` / `.js` / `.mjs` are all accepted — a pack build may transpile
+ * `.ts` to `.js` before the indexer runs inside the Dockerfile's indexer
+ * stage, but the indexer accepts either shape so local development (no
+ * bundle) and CI-built images (post-bundle) share the same code path.
+ */
+export const DEFAULT_DISCOVERY = {
+    tools: 'tools/**/*.{ts,js,mjs}',
+    guardrails: 'guardrails/**/*.{ts,js,mjs}',
+    agents: 'agents/**/*.{ts,js,mjs}',
+    flows: 'flows/**/*.{ts,js,mjs}',
+};
+/**
+ * Default discovery patterns of a Python pack (`python -m kindgi.pack index`
+ * reads the same keys from `[tool.kindgi.discovery]`).
+ */
+export const DEFAULT_PYTHON_DISCOVERY = {
+    tools: 'tools/**/*.py',
+    guardrails: 'guardrails/**/*.py',
+    agents: 'agents/**/*.py',
+    flows: 'flows/**/*.py',
+};
+/** A config's discovery patterns with the language's defaults filled in. */
+export function resolveDiscovery(discovery, language = 'node') {
+    const defaults = language === 'python' ? DEFAULT_PYTHON_DISCOVERY : DEFAULT_DISCOVERY;
+    return { ...defaults, ...(discovery ?? {}) };
+}
+/**
+ * Envelope version for the flow payload embedded inside `index.json`.
+ * Distinct from the top-level `v` envelope so the flow substrate can
+ * evolve its own shape independently — matches the `packages/flow`
+ * schema-version convention (currently 1.8.0, which added input and
+ * output mappings). Additive fields don't bump this.
+ */
+export const KERNEL_PAYLOAD_VERSION = 1;
+// -----------------------------------------------------------------------
+// Entry point
+// -----------------------------------------------------------------------
+/**
+ * Run the indexer stage. Never throws — every failure is captured as a
+ * typed `IndexerError`.
+ */
+export async function runIndexer(opts) {
+    const packDir = path.resolve(opts.packDir);
+    const importModule = opts.importModule ?? defaultImportModule;
+    const configResult = await loadConfig(packDir, opts.configPath, importModule);
+    if (configResult.kind === 'err')
+        return configResult;
+    const config = configResult.value;
+    if (packLanguage(config) !== 'node') {
+        return {
+            kind: 'err',
+            error: {
+                code: 'language-mismatch',
+                message: `${packDir} is a ${packLanguage(config)} pack; index it with its own indexer (python -m kindgi.pack index)`,
+            },
+        };
+    }
+    const env = resolvePackEnv(config.env);
+    if (env.kind === 'err') {
+        return {
+            kind: 'err',
+            error: { code: 'config-invalid', field: 'env', message: `kindgi.config: ${env.message}` },
+        };
+    }
+    const discovery = resolveDiscovery(config.discovery);
+    const bundleMap = opts.bundleMap;
+    const moduleRoot = path.resolve(opts.moduleRoot ?? packDir);
+    const discovered = bundleMap !== undefined
+        ? discoverInBundleMap(bundleMap, discovery)
+        : await discoverFiles(packDir, discovery);
+    if (discovered.length === 0) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'discovery-empty',
+                message: bundleMap !== undefined
+                    ? 'The bundle map lists no file the discovery patterns match. Check kindgi.config.ts discovery patterns.'
+                    : `Indexer discovered zero files under ${packDir}. Check kindgi.config.ts discovery patterns.`,
+            },
+        };
+    }
+    const zodConverter = loadZodConverterSync();
+    const tools = [];
+    const guardrails = [];
+    const agents = [];
+    const flows = [];
+    const fileErrors = [];
+    for (const { relPath, expectedKind } of discovered) {
+        const bundle = bundleMap?.[relPath];
+        const absPath = bundle !== undefined ? path.resolve(moduleRoot, bundle) : path.join(packDir, relPath);
+        const fileUrl = pathToFileURL(absPath).href;
+        let module_;
+        try {
+            module_ = await importModule(fileUrl);
+        }
+        catch (cause) {
+            fileErrors.push({
+                code: 'file-import-failed',
+                message: `Failed to import ${relPath}: ${stringifyError(cause)}`,
+                filePath: relPath,
+                cause: serializeCause(cause),
+            });
+            continue;
+        }
+        const defExport = extractDefaultExport(module_);
+        if (defExport === undefined) {
+            fileErrors.push({
+                code: 'no-default-export',
+                message: `File ${relPath} has no default export`,
+                filePath: relPath,
+            });
+            continue;
+        }
+        const errResult = detectResultError(defExport);
+        if (errResult !== undefined) {
+            fileErrors.push({
+                code: 'manifest-validation-failed',
+                message: `File ${relPath} default export is a Result-wrapped error: ${resultErrorMessage(errResult)}`,
+                filePath: relPath,
+                cause: errResult,
+            });
+            continue;
+        }
+        const unwrapped = unwrapResult(defExport);
+        const detected = detectKind(unwrapped);
+        if (detected === undefined) {
+            fileErrors.push({
+                code: 'ambiguous-kind',
+                message: `File ${relPath} default export does not match any primitive shape (tool / guardrail / agent / flow)`,
+                filePath: relPath,
+            });
+            continue;
+        }
+        if (expectedKind !== undefined && detected !== expectedKind) {
+            fileErrors.push({
+                code: 'kind-mismatch',
+                message: `File ${relPath} is under the default folder for kind '${expectedKind}' but default-exports a '${detected}'`,
+                filePath: relPath,
+            });
+            continue;
+        }
+        switch (detected) {
+            case 'tool': {
+                const built = buildTool(unwrapped, relPath, zodConverter);
+                if (built.kind === 'err') {
+                    fileErrors.push(built.error);
+                    continue;
+                }
+                tools.push(built.value);
+                break;
+            }
+            case 'guardrail': {
+                const built = buildGuardrail(unwrapped, relPath, zodConverter);
+                if (built.kind === 'err') {
+                    fileErrors.push(built.error);
+                    continue;
+                }
+                guardrails.push(built.value);
+                break;
+            }
+            case 'agent': {
+                const built = buildAgent(unwrapped, relPath);
+                if (built.kind === 'err') {
+                    fileErrors.push(built.error);
+                    continue;
+                }
+                agents.push(built.value);
+                break;
+            }
+            case 'flow': {
+                const built = buildGraph(unwrapped, relPath);
+                if (built.kind === 'err') {
+                    fileErrors.push(built.error);
+                    continue;
+                }
+                flows.push(built.value);
+                break;
+            }
+        }
+    }
+    const outputPath = opts.outputPath !== undefined
+        ? path.resolve(opts.outputPath)
+        : path.join(packDir, 'index.json');
+    const artifactVersion = opts.artifactVersion ?? (await computeAutoArtifactVersion(outputPath));
+    const publishedAt = opts.publishedAt ?? new Date().toISOString();
+    const index = {
+        v: INDEX_ENVELOPE_VERSION,
+        packId: config.pack.id,
+        packVersion: config.pack.version,
+        artifactVersion,
+        publishedAt,
+        tools: sortById(tools),
+        guardrails: sortById(guardrails),
+        agents: sortById(agents),
+        flows: sortById(flows),
+        ...(env.value !== undefined && { env: env.value }),
+    };
+    const written = await atomicWriteJson(outputPath, index);
+    if (written.kind === 'err')
+        return written;
+    return {
+        kind: 'ok',
+        value: {
+            packId: config.pack.id,
+            packVersion: config.pack.version,
+            artifactVersion,
+            publishedAt,
+            counts: {
+                tools: tools.length,
+                guardrails: guardrails.length,
+                agents: agents.length,
+                flows: flows.length,
+            },
+            outputPath,
+            fileErrors,
+        },
+    };
+}
+// -----------------------------------------------------------------------
+// CLI entry
+// -----------------------------------------------------------------------
+/**
+ * The `kindgi-index` command (process entry: `kindgi-index-main`) — a
+ * pack image's indexer stage runs it over the image's bundles. Args:
+ *
+ *   --pack-dir <path>          root of the pack (required)
+ *   --config <path>            explicit config file (optional)
+ *   --output <path>            explicit output path (optional)
+ *   --bundle-map <path>        index a build: the bundle map (JSON, optional)
+ *   --module-root <path>       where the bundle map's paths resolve (optional)
+ *   --artifact-version <str>   pin artifact version (optional)
+ *   --published-at <iso>       pin publishedAt (optional; enables reproducible builds)
+ *   --help
+ *   --version
+ */
+export async function main(argv) {
+    const parsed = parseArgs(argv);
+    if (parsed.kind === 'help') {
+        process.stdout.write(`${HELP_TEXT}\n`);
+        return 0;
+    }
+    if (parsed.kind === 'version') {
+        process.stdout.write('kindgi-index v0.0.0\n');
+        return 0;
+    }
+    if (parsed.kind === 'err') {
+        process.stderr.write(`kindgi-index: ${parsed.error}\n`);
+        return 2;
+    }
+    let options = parsed.value.options;
+    if (parsed.value.bundleMapPath !== undefined) {
+        const bundleMap = await readBundleMap(parsed.value.bundleMapPath);
+        if (bundleMap.kind === 'err') {
+            process.stderr.write(`kindgi-index: ${bundleMap.message}\n`);
+            return 2;
+        }
+        options = { ...options, bundleMap: bundleMap.value };
+    }
+    const outcome = await runIndexer(options);
+    if (outcome.kind === 'err') {
+        process.stderr.write(`kindgi-index: ${outcome.error.code}: ${outcome.error.message}\n`);
+        return 1;
+    }
+    process.stdout.write(`${JSON.stringify(outcome.value, null, 2)}\n`);
+    return 0;
+}
+export const HELP_TEXT = `kindgi-index — build-time pack manifest indexer
+
+Usage:
+  kindgi-index --pack-dir <path> [--config <path>] [--output <path>]
+               [--bundle-map <path> [--module-root <path>]]
+               [--artifact-version <str>] [--published-at <iso>]
+
+Options:
+  --pack-dir <path>          Root of the pack (required).
+  --config <path>            Explicit kindgi.config.* path.
+  --output <path>            Output path for index.json (default: <packDir>/index.json).
+  --bundle-map <path>        Index a build: JSON mapping each source path to its bundle.
+  --module-root <path>       Where the bundle map's paths resolve (default: --pack-dir).
+  --artifact-version <str>   Pin artifact version (default: YYYYMMDD.N auto).
+  --published-at <iso>       Pin publishedAt for reproducible builds.
+  --help                     Show this help.
+  --version                  Print version and exit.`;
+function parseArgs(argv) {
+    let packDir;
+    let configPath;
+    let outputPath;
+    let artifactVersion;
+    let publishedAt;
+    let bundleMapPath;
+    let moduleRoot;
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === undefined)
+            break;
+        if (arg === '--help' || arg === '-h')
+            return { kind: 'help' };
+        if (arg === '--version' || arg === '-v')
+            return { kind: 'version' };
+        const takeValue = () => {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { err: `${arg} requires a value` };
+            return value;
+        };
+        if (arg === '--pack-dir') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            packDir = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--config') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            configPath = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--output') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            outputPath = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--artifact-version') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            artifactVersion = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--published-at') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            publishedAt = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--bundle-map') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            bundleMapPath = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--module-root') {
+            const value = takeValue();
+            if (typeof value !== 'string')
+                return { kind: 'err', error: value.err };
+            moduleRoot = value;
+            i += 2;
+            continue;
+        }
+        return { kind: 'err', error: `Unknown argument: ${arg}` };
+    }
+    if (packDir === undefined) {
+        return { kind: 'err', error: '--pack-dir is required' };
+    }
+    if (moduleRoot !== undefined && bundleMapPath === undefined) {
+        return { kind: 'err', error: '--module-root goes with --bundle-map' };
+    }
+    const options = {
+        packDir,
+        ...(configPath !== undefined && { configPath }),
+        ...(outputPath !== undefined && { outputPath }),
+        ...(artifactVersion !== undefined && { artifactVersion }),
+        ...(publishedAt !== undefined && { publishedAt }),
+        ...(moduleRoot !== undefined && { moduleRoot }),
+    };
+    return {
+        kind: 'ok',
+        value: { options, ...(bundleMapPath !== undefined && { bundleMapPath }) },
+    };
+}
+/**
+ * A bundle map file: a JSON object of source path → bundle path, both
+ * strings (`kindgi build` writes `dist/bundle-map.json`).
+ */
+export async function readBundleMap(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(file, 'utf8'));
+    }
+    catch (cause) {
+        return { kind: 'err', message: `Cannot read the bundle map ${file}: ${stringifyError(cause)}` };
+    }
+    if (parsed === null ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed) ||
+        !Object.values(parsed).every((v) => typeof v === 'string' && v !== '')) {
+        return {
+            kind: 'err',
+            message: `The bundle map ${file} must be a JSON object of source path → bundle path.`,
+        };
+    }
+    return { kind: 'ok', value: parsed };
+}
+// -----------------------------------------------------------------------
+// Config loading
+// -----------------------------------------------------------------------
+/** Config file names looked up at a pack root, in order. */
+export const KINDGI_CONFIG_FILENAMES = [
+    'kindgi.config.ts',
+    // `.mts` is always ESM — the config name for a CommonJS app, where a
+    // `.ts` config would be reparsed with a Node warning.
+    'kindgi.config.mts',
+    'kindgi.config.mjs',
+    'kindgi.config.js',
+    'kindgi.config.cjs',
+];
+/**
+ * Load and minimally validate a pack's `kindgi.config.*` — the one
+ * loader behind the indexer and any tooling that reads pack config.
+ * Never throws:
+ * `config-not-found` when no config file exists, `config-parse-failed`
+ * (with the underlying cause) when it exists but cannot be imported or
+ * lacks `pack.id` / `pack.version`. Imports are cache-busted by mtime so
+ * a long-running process sees edits.
+ */
+export async function loadKindgiConfig(packDir, options = {}) {
+    return loadConfig(path.resolve(packDir), options.configPath, options.importModule ?? defaultImportModule);
+}
+/** `pyproject.toml` — a Python pack keeps its config in the `[tool.kindgi]` table. */
+export const PYPROJECT_FILENAME = 'pyproject.toml';
+/**
+ * Where a pack's config lives: the first `kindgi.config.*` at `packDir`
+ * (`KINDGI_CONFIG_FILENAMES` order), else a `pyproject.toml` with a
+ * `[tool.kindgi]` table. `undefined` when neither — a `pyproject.toml`
+ * without the table is a Python project, not a pack.
+ */
+export async function findKindgiConfig(packDir) {
+    for (const name of KINDGI_CONFIG_FILENAMES) {
+        const candidate = path.join(packDir, name);
+        if (await exists(candidate))
+            return { path: candidate, format: 'module' };
+    }
+    const pyproject = path.join(packDir, PYPROJECT_FILENAME);
+    let text;
+    try {
+        text = await fs.readFile(pyproject, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const tool = parseToml(text).tool;
+        return isObject(tool) && 'kindgi' in tool
+            ? { path: pyproject, format: 'pyproject' }
+            : undefined;
+    }
+    catch {
+        // Unparsable: a pack only if it clearly meant to be one (the loader reports the error).
+        return /^\s*\[tool\.kindgi[\].]/m.test(text)
+            ? { path: pyproject, format: 'pyproject' }
+            : undefined;
+    }
+}
+async function exists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadConfig(packDir, explicitPath, importModule) {
+    let file;
+    if (explicitPath !== undefined) {
+        const resolved = path.resolve(explicitPath);
+        if (await exists(resolved)) {
+            const format = path.basename(resolved) === PYPROJECT_FILENAME ? 'pyproject' : 'module';
+            file = { path: resolved, format };
+        }
+    }
+    else {
+        file = await findKindgiConfig(packDir);
+    }
+    if (file === undefined) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'config-not-found',
+                message: `No kindgi.config.{ts,mts,mjs,js,cjs}, or pyproject.toml with a [tool.kindgi] table, found at pack root ${packDir}`,
+            },
+        };
+    }
+    const read = file.format === 'pyproject'
+        ? await readPyprojectTable(file.path)
+        : await importConfigModule(file.path, importModule);
+    if (read.kind === 'err')
+        return read;
+    const checked = checkConfig(read.value, file.path);
+    if (checked.kind === 'err')
+        return checked;
+    const record = checked.value;
+    return {
+        kind: 'ok',
+        value: file.format === 'pyproject' && record.language === undefined
+            ? { ...record, language: 'python' }
+            : record,
+    };
+}
+function parseFailed(filePath, message, cause) {
+    return {
+        kind: 'err',
+        error: {
+            code: 'config-parse-failed',
+            message,
+            filePath,
+            ...(cause !== undefined && { cause: serializeCause(cause) }),
+        },
+    };
+}
+async function importConfigModule(filePath, importModule) {
+    let module_;
+    try {
+        module_ = await importModule(pathToFileURL(filePath).href);
+    }
+    catch (cause) {
+        return parseFailed(filePath, `Failed to import ${filePath}: ${stringifyError(cause)}`, cause);
+    }
+    const defExport = extractDefaultExport(module_);
+    if (defExport === undefined || typeof defExport !== 'object' || defExport === null) {
+        return parseFailed(filePath, `Config file ${filePath} has no default export (or it is not an object)`);
+    }
+    return { kind: 'ok', value: defExport };
+}
+async function readPyprojectTable(filePath) {
+    let document;
+    try {
+        document = parseToml(await fs.readFile(filePath, 'utf8'));
+    }
+    catch (cause) {
+        return parseFailed(filePath, `Failed to read ${filePath}: ${stringifyError(cause)}`, cause);
+    }
+    const tool = document.tool;
+    const table = isObject(tool) ? tool.kindgi : undefined;
+    if (!isObject(table)) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'config-not-found',
+                message: `${filePath} has no [tool.kindgi] table`,
+                filePath,
+            },
+        };
+    }
+    return { kind: 'ok', value: table };
+}
+/** The checks every config passes, whatever file it came from. */
+function checkConfig(record, filePath) {
+    const pack = record.pack;
+    if (typeof pack !== 'object' || pack === null) {
+        return parseFailed(filePath, `Config file ${filePath}: 'pack' field is missing or not an object`);
+    }
+    const packRec = pack;
+    if (typeof packRec.id !== 'string' || packRec.id.length === 0) {
+        return parseFailed(filePath, `Config file ${filePath}: 'pack.id' is missing or not a non-empty string`);
+    }
+    if (typeof packRec.version !== 'string' || packRec.version.length === 0) {
+        return parseFailed(filePath, `Config file ${filePath}: 'pack.version' is missing or not a non-empty string`);
+    }
+    if (record.language !== undefined && record.language !== 'node' && record.language !== 'python') {
+        return parseFailed(filePath, `Config file ${filePath}: 'language' must be "node" or "python"`);
+    }
+    return { kind: 'ok', value: record };
+}
+const DEFAULT_FOLDERS = {
+    tool: 'tools',
+    guardrail: 'guardrails',
+    agent: 'agents',
+    flow: 'flows',
+};
+async function discoverFiles(packDir, discovery) {
+    const seen = new Map();
+    for (const { kind, pattern } of kindPatterns(discovery)) {
+        for (const rel of await globMatch(packDir, pattern))
+            classifyDiscovered(seen, rel, kind);
+    }
+    return sortedDiscovered(seen);
+}
+/** A bundle map's source paths, classified as `discoverFiles` classifies what it finds. */
+function discoverInBundleMap(bundleMap, discovery) {
+    const sources = Object.keys(bundleMap).sort();
+    const seen = new Map();
+    for (const { kind, pattern } of kindPatterns(discovery)) {
+        const regex = globToRegex(pattern);
+        for (const rel of sources)
+            if (regex.test(rel))
+                classifyDiscovered(seen, rel, kind);
+    }
+    return sortedDiscovered(seen);
+}
+function kindPatterns(discovery) {
+    return [
+        { kind: 'tool', pattern: discovery.tools },
+        { kind: 'guardrail', pattern: discovery.guardrails },
+        { kind: 'agent', pattern: discovery.agents },
+        { kind: 'flow', pattern: discovery.flows },
+    ];
+}
+/** Record `rel`, matched by `kind`'s pattern, unless it's a test file or already seen. */
+function classifyDiscovered(seen, rel, kind) {
+    // Skip test / spec files — they live next to the primitive
+    // (`tools/echo/index.ts` + `tools/echo/index.test.ts`)
+    // and would break the indexer if imported as a primitive
+    // module. Matches conventional test-file suffixes across
+    // vitest / jest / node:test.
+    if (TEST_FILE_REGEX.test(rel))
+        return;
+    if (seen.has(rel))
+        return;
+    const firstSegment = rel.split('/')[0];
+    const inDefaultFolder = firstSegment === DEFAULT_FOLDERS[kind];
+    seen.set(rel, inDefaultFolder ? kind : undefined);
+}
+function sortedDiscovered(seen) {
+    const out = [];
+    for (const [relPath, expectedKind] of seen)
+        out.push({ relPath, expectedKind });
+    out.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+    return out;
+}
+/**
+ * Minimal glob matcher supporting `**` (any depth), `*` (single-segment
+ * wildcard), and `{a,b,c}` alternation. Sufficient for the default
+ * discovery patterns and typical custom overrides. Negations and
+ * extglob patterns are not supported.
+ */
+async function globMatch(root, pattern) {
+    const regex = globToRegex(pattern);
+    const matches = [];
+    // Walk only the pattern's static prefix — a pack embedded in a large
+    // app (`kindgi/tools/**`) must not crawl the whole host repo.
+    await walk(root, globStaticPrefix(pattern), matches, regex);
+    return matches;
+}
+async function walk(root, rel, matches, regex) {
+    const abs = rel === '' ? root : path.join(root, rel);
+    let entries;
+    try {
+        entries = await fs.readdir(abs, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+            continue;
+        const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory()) {
+            await walk(root, childRel, matches, regex);
+        }
+        else if (entry.isFile()) {
+            if (regex.test(childRel))
+                matches.push(childRel);
+        }
+    }
+}
+// -----------------------------------------------------------------------
+// Module import + default export extraction
+// -----------------------------------------------------------------------
+/**
+ * Cache-busted dynamic import. Node's module cache is keyed by URL, so
+ * a plain `import(fileUrl)` inside a long-running process (a dev watch
+ * loop) returns the *originally loaded* module even after the author
+ * edits the file on disk — the indexer would then re-emit stale
+ * manifests every watch tick.
+ *
+ * Fix: append `?v=<mtimeMs>` to the URL. Node treats each distinct URL
+ * as a distinct module entry, so an edited file (with a newer mtime)
+ * triggers a fresh load; an unchanged file keeps the same URL and hits
+ * the cache — no wasted work, no memory churn.
+ *
+ * Best-effort: if `fs.stat` fails (e.g. an unusual URL scheme or a
+ * race), fall back to the plain `import()` so the indexer still
+ * completes — logged behavior remains the same, just without cache
+ * invalidation.
+ */
+async function defaultImportModule(fileUrl) {
+    try {
+        const abs = fileURLToPath(fileUrl);
+        const { mtimeMs } = await fs.stat(abs);
+        return await import(`${fileUrl}?v=${mtimeMs}`);
+    }
+    catch {
+        return await import(fileUrl);
+    }
+}
+function extractDefaultExport(module_) {
+    if (module_ === null || typeof module_ !== 'object')
+        return undefined;
+    const record = module_;
+    return record.default;
+}
+// -----------------------------------------------------------------------
+// Result-wrapper handling
+// -----------------------------------------------------------------------
+function detectResultError(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (record.kind === 'err' && 'error' in record)
+        return record.error;
+    return undefined;
+}
+function unwrapResult(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const record = value;
+    if (record.kind === 'ok' && 'value' in record)
+        return record.value;
+    return value;
+}
+function resultErrorMessage(err) {
+    if (err === null || typeof err !== 'object')
+        return String(err);
+    const rec = err;
+    if (typeof rec.message === 'string')
+        return rec.message;
+    return JSON.stringify(err);
+}
+// -----------------------------------------------------------------------
+// Structural kind detection
+// -----------------------------------------------------------------------
+function detectKind(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const rec = value;
+    if (typeof rec.handler === 'function' && ('input' in rec || 'inputZod' in rec)) {
+        return 'tool';
+    }
+    const isGuardrailAction = typeof rec.action === 'object' &&
+        rec.action !== null &&
+        'on-violation' in rec.action;
+    if (isGuardrailAction && 'kind' in rec)
+        return 'guardrail';
+    if (typeof rec.instructions === 'string' && Array.isArray(rec.tools))
+        return 'agent';
+    if (Array.isArray(rec.nodes) && Array.isArray(rec.edges))
+        return 'flow';
+    return undefined;
+}
+// -----------------------------------------------------------------------
+// Manifest builders
+// -----------------------------------------------------------------------
+function buildTool(raw, relPath, converter) {
+    const rec = raw;
+    if (typeof rec.id !== 'string') {
+        return manifestErr(relPath, `'id' is missing or not a string`);
+    }
+    const inputWire = resolveSchema(rec, 'input', 'inputZod', relPath, converter);
+    if (inputWire.kind === 'err')
+        return inputWire;
+    const outputWire = resolveSchema(rec, 'output', 'outputZod', relPath, converter);
+    if (outputWire.kind === 'err')
+        return outputWire;
+    const tool = {
+        id: rec.id,
+        ...(typeof rec.description === 'string' && { description: rec.description }),
+        ...(typeof rec.version === 'string' && { version: rec.version }),
+        input: inputWire.value,
+        output: outputWire.value,
+        ...(Array.isArray(rec.effects) && {
+            effects: rec.effects,
+        }),
+        ...(Array.isArray(rec.needs) && {
+            needs: rec.needs,
+        }),
+        ...(isObject(rec.needsSpec) && {
+            needsSpec: rec.needsSpec,
+        }),
+        ...(typeof rec.sandbox === 'string' && { sandbox: rec.sandbox }),
+        ...(isObject(rec.limits) && {
+            limits: rec.limits,
+        }),
+        ...(isObject(rec.network) && {
+            network: rec.network,
+        }),
+        ...(isObject(rec.spec) && { spec: rec.spec }),
+        ...(typeof rec.mutating === 'boolean' && { mutating: rec.mutating }),
+        modulePath: normalizeModulePath(relPath),
+    };
+    return { kind: 'ok', value: tool };
+}
+function buildGuardrail(raw, relPath, converter) {
+    const rec = raw;
+    if (typeof rec.id !== 'string') {
+        return manifestErr(relPath, `'id' is missing or not a string`);
+    }
+    if (typeof rec.kind !== 'string') {
+        return manifestErr(relPath, `'kind' is missing or not a string`);
+    }
+    if (!isObject(rec.action)) {
+        return manifestErr(relPath, `'action' is missing or not an object`);
+    }
+    // configSchema resolution: look in three places, in priority order:
+    //   1. guardrail.configZod  (top-level, DefinedCheck-style)
+    //   2. guardrail.check.configZod (nested inside the check object)
+    //   3. guardrail.configSchema / guardrail.check.configSchema (already JSON Schema)
+    const check = isObject(rec.check) ? rec.check : undefined;
+    const zodConfig = (isZodSchema(rec.configZod) ? rec.configZod : undefined) ??
+        (check && isZodSchema(check.configZod) ? check.configZod : undefined);
+    let configSchema;
+    if (zodConfig !== undefined) {
+        const converted = toJSONSchemaSync(zodConfig, converter, 'input');
+        if (converted.kind === 'err') {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'zod-conversion-failed',
+                    message: `Guardrail ${rec.id} configSchema Zod conversion failed: ${converted.error.message}`,
+                    filePath: relPath,
+                    field: 'configSchema',
+                    cause: converted.error.cause,
+                },
+            };
+        }
+        configSchema = converted.value;
+    }
+    else if (isObject(rec.configSchema)) {
+        configSchema = rec.configSchema;
+    }
+    else if (check !== undefined && isObject(check.configSchema)) {
+        configSchema = check.configSchema;
+    }
+    else if (check !== undefined && isObject(check.configJsonSchema)) {
+        // `defineCheck` (guardrails pkg) already stores the converted JSON
+        // Schema on `configJsonSchema` — accept that shape without a second
+        // conversion pass.
+        configSchema = check.configJsonSchema;
+    }
+    const checkId = typeof rec.check === 'string'
+        ? rec.check
+        : check !== undefined && typeof check.id === 'string'
+            ? check.id
+            : undefined;
+    const guardrail = {
+        id: rec.id,
+        ...(typeof rec.name === 'string' && { name: rec.name }),
+        kind: rec.kind,
+        action: rec.action,
+        ...(typeof rec.severity === 'string' && { severity: rec.severity }),
+        ...(isObject(rec.scope) && {
+            scope: rec.scope,
+        }),
+        checkModulePath: normalizeModulePath(relPath),
+        ...(checkId !== undefined && { checkId }),
+        ...(configSchema !== undefined && { configSchema }),
+        ...(isObject(rec.config) && { config: rec.config }),
+        ...(typeof rec.sandbox === 'string' && { sandbox: rec.sandbox }),
+        ...(isObject(rec.limits) && {
+            limits: rec.limits,
+        }),
+        ...(isObject(rec.network) && {
+            network: rec.network,
+        }),
+    };
+    return { kind: 'ok', value: guardrail };
+}
+function buildAgent(raw, relPath) {
+    const rec = raw;
+    if (typeof rec.id !== 'string') {
+        return manifestErr(relPath, `'id' is missing or not a string`);
+    }
+    if (typeof rec.version !== 'string') {
+        return manifestErr(relPath, `'version' is missing or not a string`);
+    }
+    if (typeof rec.name !== 'string') {
+        return manifestErr(relPath, `'name' is missing or not a string`);
+    }
+    if (typeof rec.instructions !== 'string') {
+        return manifestErr(relPath, `'instructions' is missing or not a string`);
+    }
+    if (!Array.isArray(rec.capabilities)) {
+        return manifestErr(relPath, `'capabilities' is missing or not an array`);
+    }
+    if (!Array.isArray(rec.tools)) {
+        return manifestErr(relPath, `'tools' is missing or not an array`);
+    }
+    const agent = {
+        id: rec.id,
+        version: rec.version,
+        name: rec.name,
+        instructions: rec.instructions,
+        capabilities: rec.capabilities,
+        tools: rec.tools,
+        ...optionalAgentFields(rec),
+        modulePath: normalizeModulePath(relPath),
+    };
+    return { kind: 'ok', value: agent };
+}
+/** The agent's optional fields, carried when present with the right shape. */
+function optionalAgentFields(rec) {
+    const out = {};
+    for (const key of ['retrieval', 'guardrails', 'parameters', 'tags']) {
+        if (Array.isArray(rec[key]))
+            out[key] = rec[key];
+    }
+    for (const key of ['budget', 'conversationPolicy', 'output', 'toolErrors']) {
+        if (isObject(rec[key]))
+            out[key] = rec[key];
+    }
+    for (const key of ['preferredProvider', 'preferredModel', 'description']) {
+        if (typeof rec[key] === 'string')
+            out[key] = rec[key];
+    }
+    return out;
+}
+/**
+ * Validate a discovered flow with the same loader the API uses, so a
+ * broken flow fails indexing with the loader's message instead of
+ * failing later at publish or run time, and carry every field it has.
+ */
+function buildGraph(raw, relPath) {
+    const loaded = loadFlow(raw);
+    if (loaded.kind === 'err')
+        return manifestErr(relPath, loaded.error.message);
+    const f = loaded.value;
+    const flow = {
+        id: f.id,
+        version: f.version,
+        ...(f.name !== undefined && { name: f.name }),
+        ...(f.description !== undefined && { description: f.description }),
+        nodes: f.nodes,
+        edges: f.edges,
+        ...(f.maxParallelism !== undefined && { maxParallelism: f.maxParallelism }),
+        ...(f.metadata !== undefined && { metadata: f.metadata }),
+        ...(f.output !== undefined && { output: f.output }),
+        kernelPayloadVersion: KERNEL_PAYLOAD_VERSION,
+        modulePath: normalizeModulePath(relPath),
+    };
+    return { kind: 'ok', value: flow };
+}
+function manifestErr(relPath, msg) {
+    return {
+        kind: 'err',
+        error: {
+            code: 'manifest-validation-failed',
+            message: `${relPath}: ${msg}`,
+            filePath: relPath,
+        },
+    };
+}
+// -----------------------------------------------------------------------
+// Schema resolution — Zod → JSON Schema pass
+// -----------------------------------------------------------------------
+function resolveSchema(rec, wireField, zodField, relPath, converter) {
+    // A tool's `input` is what a caller sends; its `output`, what it returns.
+    const side = wireField;
+    const zodValue = rec[zodField];
+    if (zodValue !== undefined && isZodSchema(zodValue)) {
+        const converted = toJSONSchemaSync(zodValue, converter, side);
+        if (converted.kind === 'err') {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'zod-conversion-failed',
+                    message: `${relPath}: Zod conversion for '${zodField}' failed: ${converted.error.message}`,
+                    filePath: relPath,
+                    field: zodField,
+                    cause: converted.error.cause,
+                },
+            };
+        }
+        return { kind: 'ok', value: converted.value };
+    }
+    const wireValue = rec[wireField];
+    // `wireValue` may itself be a Zod schema (author-time authored with Zod
+    // but not yet run through defineTool). Convert lazily in that case.
+    if (isZodSchema(wireValue)) {
+        const converted = toJSONSchemaSync(wireValue, converter, side);
+        if (converted.kind === 'err') {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'zod-conversion-failed',
+                    message: `${relPath}: Zod conversion for '${wireField}' failed: ${converted.error.message}`,
+                    filePath: relPath,
+                    field: wireField,
+                    cause: converted.error.cause,
+                },
+            };
+        }
+        return { kind: 'ok', value: converted.value };
+    }
+    if (!isObject(wireValue)) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'manifest-validation-failed',
+                message: `${relPath}: '${wireField}' is missing or not an object`,
+                filePath: relPath,
+                field: wireField,
+            },
+        };
+    }
+    return { kind: 'ok', value: wireValue };
+}
+// -----------------------------------------------------------------------
+// Output serialization — atomic write + auto artifact version
+// -----------------------------------------------------------------------
+async function atomicWriteJson(outputPath, index) {
+    const tmpPath = `${outputPath}.tmp-${process.pid}-${Date.now()}`;
+    const serialized = `${stableStringify(index)}\n`;
+    try {
+        await fs.mkdir(path.dirname(outputPath), { recursive: true });
+        await fs.writeFile(tmpPath, serialized, 'utf8');
+        await fs.rename(tmpPath, outputPath);
+    }
+    catch (cause) {
+        // Best-effort tmp cleanup — swallow errors here (the original write
+        // error is what the caller needs).
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch {
+            // ignore
+        }
+        return {
+            kind: 'err',
+            error: {
+                code: 'output-write-failed',
+                message: `Failed to write ${outputPath}: ${stringifyError(cause)}`,
+                filePath: outputPath,
+                cause: serializeCause(cause),
+            },
+        };
+    }
+    return { kind: 'ok', value: undefined };
+}
+/**
+ * Stable JSON serializer — keys sorted at every level. Guarantees
+ * byte-identical output for byte-identical semantic input, which is the
+ * property the local integrity gate depends on.
+ */
+function stableStringify(value) {
+    return JSON.stringify(canonicalize(value), null, 2);
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const rec = value;
+    const out = {};
+    for (const key of Object.keys(rec).sort()) {
+        out[key] = canonicalize(rec[key]);
+    }
+    return out;
+}
+async function computeAutoArtifactVersion(outputPath) {
+    const today = new Date();
+    const yyyymmdd = today.getUTCFullYear().toString().padStart(4, '0') +
+        (today.getUTCMonth() + 1).toString().padStart(2, '0') +
+        today.getUTCDate().toString().padStart(2, '0');
+    let n = 1;
+    try {
+        const existing = await fs.readFile(outputPath, 'utf8');
+        const parsed = JSON.parse(existing);
+        if (typeof parsed.artifactVersion === 'string') {
+            const match = /^(\d{8})\.(\d+)$/.exec(parsed.artifactVersion);
+            const dayPart = match?.[1];
+            const nPart = match?.[2];
+            if (dayPart === yyyymmdd && nPart !== undefined) {
+                const parsedN = Number.parseInt(nPart, 10);
+                if (Number.isFinite(parsedN))
+                    n = parsedN + 1;
+            }
+        }
+    }
+    catch {
+        // No prior index.json — start at .1
+    }
+    return `${yyyymmdd}.${n}`;
+}
+// -----------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function sortById(items) {
+    return [...items].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+function stringifyError(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    return String(err);
+}
+function serializeCause(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message, stack: err.stack };
+    }
+    if (err === undefined)
+        return null;
+    if (err === null ||
+        typeof err === 'string' ||
+        typeof err === 'number' ||
+        typeof err === 'boolean') {
+        return err;
+    }
+    try {
+        JSON.stringify(err);
+        return err;
+    }
+    catch {
+        return String(err);
+    }
+}
+function normalizeModulePath(relPath) {
+    // Forward slashes only, no leading './'
+    let normalized = relPath.replace(/\\/g, '/');
+    if (normalized.startsWith('./'))
+        normalized = normalized.slice(2);
+    return normalized;
+}
+//# sourceMappingURL=kindgi-index.js.map