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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kindgi Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,219 @@
-# @kindgi/handler-runtime
+# `@kindgi/handler-runtime`
 
-A placeholder. Releases come from https://github.com/kindgi/kindgi-sdk.
+Runs a Kindgi pack's own code: its tool handlers and guardrail checks.
+
+- **The pack service**: a long-lived HTTP server that runs a pack's tools and checks over pack protocol v2. It's the process a pack image runs, and `kindgi dev` runs the same process locally, behind a supervisor.
+- **The handler runner** (`runHandler`, `runCheck`): runs one tool call or one check in process. The pack service runs every call through it.
+- **The build-time indexer** (`kindgi-index`): writes the pack's `index.json`, the list of its tools, guardrails, agents and flows that the pack service and the runtime read.
+
+## Handler runner
+
+`runHandler({ tool, input, ctx })` runs one tool call:
+
+1. Validates a copy of `input` against the tool's input JSON Schema (ajv, Draft 2020-12), filling in each property's `default`. When the module exports a Zod schema (`defineTool`'s `inputZod`), it also parses the input with it, so the handler gets what its type says.
+2. Imports `tool.modulePath` and resolves the handler: a bare function export, or `default` / `handler` / `run`, or a `defineTool` export holding one.
+3. Calls `handler(input, ctx)`, awaiting a promise.
+4. Validates the return value against the tool's output JSON Schema.
+
+`runCheck({ check, config, trace, abortSignal? })` runs one guardrail check: it imports the module, resolves its `evaluate` (`default`, `check`, or a bare export), and calls `evaluate(config, trace, bindings)`. `bindings` carries only `abortSignal`; a check here has no provider registry, so llm-judge checks run in the server.
+
+Neither throws. Each returns `{ kind: 'ok', value }` or `{ kind: 'err', error: HandlerError }`:
+
+| `error.code` | When |
+|---|---|
+| `input-validation-failed` | The input failed its schema (`issues` lists why). The handler isn't called. |
+| `output-validation-failed` | The handler's return value failed the output schema. |
+| `handler-import-failed` | Importing the module threw (`cause`). |
+| `handler-shape-invalid` | The module exports no handler. |
+| `handler-throw` | The handler (or `evaluate`) threw (`cause`). |
+| `check-shape-invalid` | The check module exports no `evaluate`. |
+
+```ts
+import { runHandler } from '@kindgi/handler-runtime';
+
+const outcome = await runHandler({
+  tool: { id: 'acme.lookup', modulePath: '/app/dist/tools/lookup.js', inputSchema, outputSchema },
+  input: { q: 'backpay' },
+  ctx: { tenantId, runId, abortSignal },
+});
+```
+
+`importHandler` / `importCheck` replace the default `import(modulePath)` (tests use them). The runner is not a sandbox: the pack service's process is the boundary, and pack code is the team's own.
+
+## Pack service (protocol v2)
+
+A long-lived HTTP server that runs a pack's tool handlers and guardrail checks for a runtime. It's the process a pack image runs, and the same process runs locally during development. Imports happen once at boot, calls run concurrently, and handler console output can't corrupt a response.
+
+```sh
+KINDGI_PACK_SERVICE_TOKEN=… PORT=8080 node node_modules/@kindgi/handler-runtime/dist/pack-service/main.js \
+  --index dist/index.json          # module paths resolve against --module-root (default: the index's directory)
+                                   # --bundle-map <path>: a build's map of the index's source paths to their bundles
+                                   # --host <address>: listen on one address (default: every interface)
+```
+
+A pack image runs it bundled (`dist/kindgi-pack-service.mjs`) with `--bundle-map`: the index names each module by its source path (`tools/echo/index.ts`), and the map points it at the bundle that loads (`tools/echo/index.mjs`).
+
+| Route | Auth | Answer |
+|---|---|---|
+| `POST /v1/invoke` | `kindgi-pack-token` | `200` with a v2 response message |
+| `GET /v1/info` | `kindgi-pack-token` | pack id, versions, protocol, tools, checks, and the required env names it lacks (`missingEnv`) |
+| `GET /healthz` | none | the process is up |
+| `GET /readyz` | none | prewarmed, not draining, and every required env name set (unless the env check is `warn`) |
+
+- **Requests** (`@kindgi/handler-runtime/protocol`) name a tool (`{ id, version? }`) or a check (`{ id }`). The service resolves it from its own `index.json`, so a caller never chooses which module is imported.
+- **Every outcome of running pack code is a message**, answered with `200`: the result, validation failures (with `issues`), a throw, an unknown tool or check, a version mismatch, `deadline-exceeded` (from `kindgi-timeout-ms`), and `cancelled` (the caller disconnected). HTTP statuses are for the transport only: `401`, `404`, `405`, `413`, `415`, `503` with `Retry-After` when the service isn't ready, is draining, or is at its concurrency cap, and `500` if the service itself fails while handling a call.
+- **The declared process env:** a pack lists the environment variables its code reads in `kindgi.config` (`env: { required, optional }`), and the index carries them. With a `required` name unset or empty, the service isn't ready: `/readyz` and every call answer `503` with `{ "error": "missing env", "missingEnv": [...] }`, names only. `KINDGI_PACK_ENV_CHECK=warn` serves anyway and names them in the log (`missing-env`) and `/v1/info`; `kindgi dev` uses it. `resolvePackEnv` and `missingPackEnv` are the shared checks.
+- **Cancellation:** the handler's `ctx.abortSignal` fires on a deadline or a disconnect. Handlers that do slow I/O should pass it on.
+- **Boot fails** (exit `1`, listing every problem) when the index can't be read, a module it names is missing, or one fails to import. SIGTERM drains in-flight calls and exits `0`.
+- **Logs** are JSON lines on stderr. The `listening` line carries the bound port, so a caller can start the service with `PORT=0`.
+- **Programmatic:** `createPackService({ index, resolveModule, token, … })` returns a service whose `handle` is a `node:http` request handler. `startPackService(config)` also listens (`@kindgi/handler-runtime/pack-service`).
+
+### Supervisor (local development)
+
+`createPackServiceSupervisor({ command, moduleRoot, env, … })` (`@kindgi/handler-runtime/pack-service`) runs a pack service as a child process behind a **front**: one HTTP listener on a fixed loopback address with a session token, for the supervisor's whole life. A caller — a runtime calling tools — holds that one URL and token however often the code changes.
+
+- `listen()` opens the front; `start(indexPath)` boots a child on the index (loopback, any port) and switches calls to it once it listens. The previous child finishes its in-flight calls and stops; a child that fails to boot leaves the previous one serving; a child that exits on its own is restarted.
+- The front forwards `POST /v1/invoke` and `GET /v1/info`, and answers `503` with `Retry-After` while no child serves (the call did not run, so a caller may retry) and `502` when a child died mid-call (it may have run). `/healthz` answers while the front listens, `/readyz` while a child serves.
+- `command` is the child's argv; the supervisor appends `--index`, `--module-root` and `--host`. Any pack service with the process contract of [`pack-protocol.schema.json`](../specs/schemas/pack-protocol.schema.json) works: this package's (`[process.execPath, <pack-service-main>]`) or the Python SDK's (`[python, '-m', 'kindgi.pack', 'serve']`).
+- The child's environment is exactly `env()` plus the token and `PORT=0`.
+- Forwarding is a separate `relay` (a request body plus deadline, run and request ids, and a cancel signal), so a listener other than HTTP can reuse it.
+- `stop()` stops the child (the front then answers `503`); `close()` also closes the front.
+
+## Build extensions
+
+`@kindgi/handler-runtime/build-extensions` (re-exported as `@kindgi/sdk/build`): the types and helpers for `image` in a TypeScript pack's `kindgi.config.*`.
+- `ImageConfig { systemPackages?, extensions?, buildEnv? }`;
+- `BuildExtension { name, contextFiles?, systemPackages?, postInstall?, buildEnv? }`;
+- `prisma({ schema, config? })`: `prisma generate` after the install;
+- `defineBuildExtension()`.
+
+They're data only: `kindgi build` renders them into the image's Containerfile.
+
+## Build-time indexer
+
+`kindgi-index.ts` writes a pack's `index.json`. A pack image's indexer stage runs it over the image's bundles (process entry `kindgi-index-main`, bundled as `dist/kindgi-index.mjs`), and the emitted `/app/index.json` is `COPY --from=indexer`'d into the runtime image; `kindgi build` runs the same bundle locally, so the two indexes compare byte for byte. The pack service reads `index.json` at boot: it serves exactly the tools and checks the index lists.
+
+### What the indexer does
+
+1. **Discovers** files under `tools/`, `guardrails/`, `agents/`, `flows/` per `kindgi.config.ts` (`.ts` / `.js` / `.mjs` all accepted). Indexing a build (`bundleMap`), the map's source paths are the file list, classified by the same patterns — the source tree needn't be there — each imported from its bundle; the index still records the source path.
+2. **Kind-maps** each file by its containing directory (primary) or by structural detection on the default export (fallback for files matched by custom-discovery globs outside the four default folders).
+3. **Imports** each file and reads the `default` export — accepting either the raw primitive shape or a `Result`-wrapped envelope from `defineTool` / `defineGuardrail` / etc. Fails loud on: no default export, kind mismatch, or a `Result`-wrapped error.
+4. **Converts Zod schemas** — `tool.inputZod` / `tool.outputZod` / `check.configZod` — to their JSON Schema wire form via `@kindgi/schema.toJSONSchemaSync`. JSON-Schema-authored slots pass through verbatim.
+5. **Writes** the `v: 1` `index.json` envelope atomically (write to `.tmp-<pid>-<time>`, then rename) to the configured output path.
+
+### Programmatic form
+
+```ts
+import { runIndexer } from '@kindgi/handler-runtime';
+
+const outcome = await runIndexer({
+  packDir: '/path/to/pack',
+  // Optional overrides
+  configPath:      '/path/to/kindgi.config.ts',
+  outputPath:      '/app/index.json',
+  artifactVersion: '20260920.1',                      // pin for reproducible builds
+  publishedAt:     '2026-09-20T14:32:07.104Z',        // pin for byte-determinism
+});
+
+if (outcome.kind === 'ok') {
+  console.log(outcome.value.counts);   // { tools, guardrails, agents, flows }
+  console.log(outcome.value.outputPath);
+} else {
+  console.error(outcome.error.code, outcome.error.message);
+}
+```
+
+`runIndexer` never throws — every failure surfaces as a typed `IndexerError`:
+
+| Code | When |
+|---|---|
+| `config-not-found` | No `kindgi.config.{ts,mts,mjs,js,cjs}` at the pack root. |
+| `config-parse-failed` | Config file imported but is malformed. |
+| `discovery-empty` | Glob patterns matched zero files. |
+| `file-import-failed` | Dynamic `import()` of a discovered file threw. |
+| `no-default-export` | A discovered file exported no `default`. |
+| `kind-mismatch` | File under `tools/` default-exports a non-tool (or symmetric for the other three folders). |
+| `ambiguous-kind` | Custom-pattern file whose default export doesn't structurally match any primitive shape. |
+| `zod-conversion-failed` | `z.toJSONSchema()` threw for a specific schema. |
+| `manifest-validation-failed` | Inner manifest didn't match the expected shape (or was a `Result`-wrapped error). |
+| `output-write-failed` | Filesystem write error. |
+
+### Loading `kindgi.config.*` on its own
+
+The indexer's config loader is exported so every tool reads the pack
+config the same way:
+
+```ts
+import { loadKindgiConfig } from '@kindgi/handler-runtime';
+
+const r = await loadKindgiConfig('/path/to/pack');
+if (r.kind === 'ok') r.value.pack.id;
+// r.kind === 'err': 'config-not-found' | 'config-parse-failed' (message carries the cause)
+```
+
+It looks up `KINDGI_CONFIG_FILENAMES` in order and imports the first that
+exists (cache-busted by mtime, so a long-running process sees edits). With
+none, a `pyproject.toml` whose `[tool.kindgi]` table holds the same keys is
+the config — a **Python pack** (`language: 'python'`, unless the table says
+otherwise). It checks `pack.id` / `pack.version` and `language`. Never throws.
+
+- `findKindgiConfig(packDir)` — where the config is (`{ path, format: 'module' | 'pyproject' }`), or `undefined`; a `pyproject.toml` without the table is not a pack.
+- `packLanguage(config)` — `'node'` or `'python'`: which indexer reads the pack and which pack service runs it. `runIndexer` refuses a Python pack (`language-mismatch`); `python -m kindgi.pack index` indexes it.
+- `resolveDiscovery(discovery, language)` — the patterns with the language's defaults (`DEFAULT_DISCOVERY`, `DEFAULT_PYTHON_DISCOVERY`).
+
+### Command-line form
+
+`main(argv)` is the command; the `kindgi-index-main` export runs it as a process (a pack image runs it bundled, as `dist/kindgi-index.mjs`).
+
+```
+kindgi-index --pack-dir <path> [--config <path>] [--output <path>]
+                [--bundle-map <path> [--module-root <path>]]
+                [--artifact-version <str>] [--published-at <iso>]
+                [--help] [--version]
+```
+
+`--bundle-map` indexes a build: a JSON object of source path → bundle path, the bundle paths relative to `--module-root` (default `--pack-dir`).
+
+### `index.json` shape
+
+```jsonc
+{
+  "v": 1,
+  "packId":          "acme.support",
+  "packVersion":     "1.0.0",
+  "artifactVersion": "20260920.1",
+  "publishedAt":     "2026-09-20T14:32:07.104Z",
+  "tools":      [{ "id": "…", "input": { … }, "output": { … }, "effects": [ … ], "modulePath": "tools/…/index.js", "sandbox": "strict", "limits": { … }, "network": { … } }, …],
+  "guardrails": [{ "id": "…", "kind": "zero-llm", "action": { "on-violation": "halt" }, "severity": "error", "checkModulePath": "guardrails/…/index.js", "checkId": "…", "configSchema": { … } }, …],
+  "agents":     [{ "id": "…", "version": "1.0.0", "instructions": "…", "capabilities": [ … ], "tools": [ … ], "modulePath": "agents/…/index.js" }, …],
+  "flows":     [{ "id": "…", "version": "1.0.0", "nodes": [ … ], "edges": [ … ], "kernelPayloadVersion": 1, "modulePath": "flows/…/index.js" }, …],
+  "env":        { "optional": ["LOG_LEVEL"], "required": ["DATABASE_URL"] }   // only when the pack declares env
+}
+```
+
+The pack service:
+1. Reads the index at boot (`--index`, else `KINDGI_PACK_INDEX`, else `/app/index.json`) and imports every module it names (prewarm). A missing or failing module fails the boot.
+2. For a call to tool `X`, finds `X` in the index and runs it with `runHandler`, with its module path resolved against `--module-root`. A guardrail check is found by its `checkId`.
+
+### Determinism
+
+An index computed on a developer's laptop must match one computed by the build server for the same inputs — byte-identical inputs must produce byte-identical outputs. To make that work:
+
+- All list fields (`tools` / `guardrails` / `agents` / `flows`) are sorted lexicographically by `id`.
+- JSON serialization writes keys in sorted order at every level.
+- `publishedAt` is accepted as an explicit `opts.publishedAt` (build-arg from the Dockerfile, SOURCE_DATE_EPOCH-shaped). Default: fresh ISO string — non-deterministic; production builds must override it.
+
+## Not in this package
+
+- Running the indexer as part of a pack build — that is the build tooling's job.
+- Multi-pack workspace indexing (one pack per subfolder).
+- Watch mode / hot re-indexing.
+- A signed `index.json` — the image digest, which contains the file, is what gets signed.
+- Cross-file dependency validation (an agent referencing a tool the pack doesn't have).
+- Bundle-size warnings or thresholds.
+- Handler-side telemetry / cost-tracking hooks.
+- Streaming output for tools that yield incremental results.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/build-extensions.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A TypeScript pack image's build extensions: what an app's image needs
+ * beyond installing the app's dependencies — Debian packages, a step
+ * that generates code after the install (Prisma's client), placeholder
+ * env for build steps. `image` in `kindgi.config.*`:
+ *
+ * ```ts
+ * import { prisma } from '@kindgi/sdk/build';
+ *
+ * export default {
+ *   pack: { id: 'acme.app', version: '1.0.0' },
+ *   image: {
+ *     systemPackages: ['tesseract-ocr'],
+ *     extensions: [prisma({ schema: 'prisma/schema.prisma', config: 'prisma.config.ts' })],
+ *     buildEnv: { DATABASE_URL: 'postgresql://build-placeholder' },
+ *   },
+ * };
+ * ```
+ *
+ * Data only: nothing here runs at build time. `kindgi build` renders it
+ * into the image's Containerfile — system packages in the base stage,
+ * `buildEnv` in the install stage only (never in the final image), each
+ * `postInstall` step after the install and before the prune to
+ * production, through the app's own package manager.
+ */
+/** A package's bin, run through the app's package manager (`pnpm exec`, `npx --no`, `yarn`). */
+export interface BuildStep {
+    readonly bin: string;
+    readonly args?: readonly string[];
+}
+export interface BuildExtension {
+    readonly name: string;
+    /**
+     * Files the steps read, relative to the pack folder: copied into the
+     * image's install stage, at the same paths.
+     */
+    readonly contextFiles?: readonly string[];
+    /** Debian packages the image needs. */
+    readonly systemPackages?: readonly string[];
+    /**
+     * Steps after the install, before the prune: dev dependencies (a
+     * generator's CLI) are still there. Run in the pack folder.
+     */
+    readonly postInstall?: readonly BuildStep[];
+    /**
+     * Env for the build steps, and for the indexer stage that imports the
+     * pack's modules: non-secret placeholders only. Never in the final
+     * image.
+     */
+    readonly buildEnv?: Readonly<Record<string, string>>;
+}
+/** `image` in `kindgi.config.*` (a TypeScript pack). */
+export interface ImageConfig {
+    /** Debian packages the image needs (as a Python pack's `[tool.kindgi.image] system-packages`). */
+    readonly systemPackages?: readonly string[];
+    readonly extensions?: readonly BuildExtension[];
+    /** Env for the build steps, merged over the extensions' (see `BuildExtension.buildEnv`). */
+    readonly buildEnv?: Readonly<Record<string, string>>;
+}
+/** An app's own extension: the shape checked by the type, returned as is. */
+export declare function defineBuildExtension(extension: BuildExtension): BuildExtension;
+export interface PrismaExtensionOptions {
+    /** The Prisma schema, relative to the pack folder. */
+    readonly schema: string;
+    /** The Prisma config file (`prisma.config.ts`), when the app has one; it names the schema. */
+    readonly config?: string;
+}
+/**
+ * Prisma's generated client in the image. The app's own `postinstall:
+ * prisma generate` doesn't run (the image installs with scripts off), so
+ * this copies the schema (and config) in and runs `prisma generate` after
+ * the install, with the app's `prisma` CLI.
+ */
+export declare function prisma(options: PrismaExtensionOptions): BuildExtension;
+//# sourceMappingURL=build-extensions.d.ts.map

package/dist/build-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-extensions.d.ts","sourceRoot":"","sources":["../src/build-extensions.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,gGAAgG;AAChG,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,uCAAuC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,cAAc,GAAG,cAAc,CAE9E;AAED,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAetE"}

package/dist/build-extensions.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** An app's own extension: the shape checked by the type, returned as is. */
+export function defineBuildExtension(extension) {
+    return extension;
+}
+/**
+ * Prisma's generated client in the image. The app's own `postinstall:
+ * prisma generate` doesn't run (the image installs with scripts off), so
+ * this copies the schema (and config) in and runs `prisma generate` after
+ * the install, with the app's `prisma` CLI.
+ */
+export function prisma(options) {
+    return {
+        name: 'prisma',
+        contextFiles: options.config !== undefined ? [options.schema, options.config] : [options.schema],
+        postInstall: [
+            {
+                bin: 'prisma',
+                args: options.config !== undefined
+                    ? ['generate', '--config', options.config]
+                    : ['generate', '--schema', options.schema],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=build-extensions.js.map

package/dist/build-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-extensions.js","sourceRoot":"","sources":["../src/build-extensions.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiEjC,6EAA6E;AAC7E,MAAM,UAAU,oBAAoB,CAAC,SAAyB;IAC5D,OAAO,SAAS,CAAC;AACnB,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,OAA+B;IACpD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,YAAY,EACV,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QACpF,WAAW,EAAE;YACX;gBACE,GAAG,EAAE,QAAQ;gBACb,IAAI,EACF,OAAO,CAAC,MAAM,KAAK,SAAS;oBAC1B,CAAC,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;oBAC1C,CAAC,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;aAC/C;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/discovery.d.ts

@@ -0,0 +1,19 @@
+/** Test / spec files sit next to primitives and are never primitives. */
+export declare const TEST_FILE_REGEX: RegExp;
+/** Compile a discovery pattern to an anchored RegExp over `/`-separated relative paths. */
+export declare function globToRegex(pattern: string): RegExp;
+/**
+ * Directory prefix before the first wildcard segment, `''` for the pack
+ * root. A pattern without wildcards names a file; its prefix is that
+ * file's directory.
+ */
+export declare function globStaticPrefix(pattern: string): string;
+/**
+ * The directories to walk or watch for a set of patterns: each pattern's
+ * static prefix, with any prefix inside another one dropped. `['']`
+ * means the pack root.
+ */
+export declare function discoveryRoots(patterns: readonly string[]): readonly string[];
+/** `(relPath) => true` when the path matches any pattern and is not a test file. */
+export declare function createGlobMatcher(patterns: readonly string[]): (relPath: string) => boolean;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAqBA,yEAAyE;AACzE,eAAO,MAAM,eAAe,QAAoC,CAAC;AAEjE,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASnD;AA0BD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAK7E;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAG3F"}

package/dist/discovery.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Discovery-glob primitives shared by the indexer and anything that
+ * watches a pack (a dev watch loop) — so "which files are primitives"
+ * has one answer.
+ *
+ * Supported syntax: `**` (any depth, including none), `*` (within one
+ * segment), `?` (one character), `{a,b,c}` alternation. Negations and
+ * extglobs are not supported.
+ *
+ * Every pattern has a **static prefix** — the directory segments before
+ * the first wildcard (`kindgi/tools/**\/*.ts` → `kindgi/tools`). Walking
+ * or watching only that prefix matters when a pack lives inside a large
+ * application: the indexer must not crawl the whole host repo to find
+ * `kindgi/**`.
+ */
+const GLOB_CHARS = /[*?{[]/;
+/** Test / spec files sit next to primitives and are never primitives. */
+export const TEST_FILE_REGEX = /\.(test|spec)\.(ts|js|mjs|cjs)$/;
+/** Compile a discovery pattern to an anchored RegExp over `/`-separated relative paths. */
+export function globToRegex(pattern) {
+    let re = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const [piece, next] = globToken(pattern, i);
+        re += piece;
+        i = next;
+    }
+    return new RegExp(`^${re}$`);
+}
+/** The regex source for the token at `i`, and the index after it. */
+function globToken(pattern, i) {
+    const c = pattern.charAt(i);
+    if (c === '*' && pattern.charAt(i + 1) === '*') {
+        // `**/` may match zero segments; a trailing `**` matches anything.
+        return pattern.charAt(i + 2) === '/' ? ['(?:.*/)?', i + 3] : ['.*', i + 2];
+    }
+    if (c === '*')
+        return ['[^/]*', i + 1];
+    if (c === '?')
+        return ['[^/]', i + 1];
+    const close = c === '{' ? pattern.indexOf('}', i) : -1;
+    if (close !== -1) {
+        const options = pattern
+            .slice(i + 1, close)
+            .split(',')
+            .map(escapeRegex);
+        return [`(?:${options.join('|')})`, close + 1];
+    }
+    return [escapeRegex(c), i + 1];
+}
+function escapeRegex(s) {
+    return s.replace(/[.+^$()|[\]\\{}]/g, '\\$&');
+}
+/**
+ * Directory prefix before the first wildcard segment, `''` for the pack
+ * root. A pattern without wildcards names a file; its prefix is that
+ * file's directory.
+ */
+export function globStaticPrefix(pattern) {
+    const segments = pattern.split('/');
+    const firstGlob = segments.findIndex((s) => GLOB_CHARS.test(s));
+    const dirSegments = firstGlob === -1 ? segments.slice(0, -1) : segments.slice(0, firstGlob);
+    return dirSegments.filter((s) => s !== '' && s !== '.').join('/');
+}
+/**
+ * The directories to walk or watch for a set of patterns: each pattern's
+ * static prefix, with any prefix inside another one dropped. `['']`
+ * means the pack root.
+ */
+export function discoveryRoots(patterns) {
+    const prefixes = [...new Set(patterns.map(globStaticPrefix))].sort();
+    return prefixes.filter((p) => !prefixes.some((other) => other !== p && (other === '' || p.startsWith(`${other}/`))));
+}
+/** `(relPath) => true` when the path matches any pattern and is not a test file. */
+export function createGlobMatcher(patterns) {
+    const regexes = patterns.map(globToRegex);
+    return (relPath) => !TEST_FILE_REGEX.test(relPath) && regexes.some((r) => r.test(relPath));
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

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