apcore-toolkit 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [0.5.0] - 2026-04-21
+
+### Added
+
+- **`BindingLoader`** / **`BindingLoadError`** — parses `.binding.yaml` files back into `ScannedModule` objects (inverse of `YAMLWriter`). Pure-data reader: no target resolution, no Registry side effects. Matches the Python and Rust implementations in API shape and behaviour.
+  - `load(path, options?)` — single file or directory of `*.binding.yaml`.
+  - `loadData(data, options?)` — pre-parsed YAML data.
+  - Loose mode (default): only `module_id + target` required.
+  - Strict mode (`{ strict: true }`): additionally requires `input_schema + output_schema`.
+  - `spec_version` validated; missing or unsupported values emit a `console.warn` but do not throw.
+  - `annotations` parsed via `annotationsFromJSON` from `apcore-js`; malformed values degrade to `null` with a warning.
+  - `BindingLoadError.filePath`, `moduleId`, `missingFields`, and `reason` fields exposed for programmatic handling.
+- **`ScannedModule.display`** — new readonly field (`Record<string, unknown> | null`) for the sparse display overlay. `createScannedModule` factory and `cloneModule` helper updated; deep-cloned on read and write.
+
+### Changed
+
+- **`YAMLWriter._buildBinding`** — emits top-level `display:` key only when `module.display !== null`.
+- **`serializers.moduleToDict`** — includes `display` key (deep-cloned).
+
+### Dependencies
+
+- **`apcore-js >= 0.19.0`** — picks up the 12-field `ModuleAnnotations` and `annotationsFromJSON`. No toolkit changes required for annotations semantics.
+
+### Tests
+
+- +29 new tests: 23 for `BindingLoader` (parsing, strict/loose modes, filesystem loading, round-trip), 4 for `display` field emission/serialization, and 2 hardening tests (malformed display/schema warning). Total suite: 320 tests.
+
+### Hardening (post-review)
+
+- **`BindingLoader`**: `_asRecord` / `_asRecordOrNull` now warn when given a non-mapping value (previously silent). `_parseExamples` uses `structuredClone` on each entry so caller mutation of the returned `ScannedModule.examples` cannot leak into the YAML parser's object graph. `fs.statSync` failures are inspected for `ENOENT`/other `errno` codes so users see a specific error instead of a generic "path does not exist" for permission issues.
+
+### Hardening (cross-SDK sync — post-audit)
+
+- **`BindingLoader` strict-mode wrong-type rejection** — a required field is now rejected when absent, `null`, or of the wrong type (e.g. `module_id: 42`, `target: true`, empty-string `module_id`). Previously TypeScript silently coerced wrong-type scalars via `String(value)`, while Rust already rejected them; the same YAML now behaves identically in all three SDKs. The error reason widens from `"missing required fields"` to **`"missing or invalid required fields"`**, matching the Rust loader.
+- **`BindingLoader._asRecord` defensive deep-copy** — previously returned a fresh outer `{}` but shared nested refs with the parsed YAML source graph. Now `structuredClone`s the filtered result so caller mutation of `ScannedModule.inputSchema`/`outputSchema`/`metadata` does not leak back into the YAML parser's object graph (defensive parity with the Python `copy.deepcopy` and Rust `Value.clone` loaders).
+
+### Removed
+
+- **`flattenParams`** — removed from README (Features list and API table). The symbol was advertised there but never exported from `src/index.ts`; the canonical docs previously described it as a TypeScript utility for "flattening Zod schemas", but TypeScript's native object-argument idiom (`function createUser(body: { username, email })`) already accepts flat inputs, making the wrapper a no-op. Users who need to iterate a Zod schema's fields at runtime can do so directly via `Object.keys(schema.shape)`. The Python `flatten_pydantic_params` remains and continues to serve Python's Pydantic-model unwrapping use-case.
+
+### Added (browser / edge runtime subpath)
+
+- **`apcore-toolkit/browser`** — new subpath export that exposes the runtime-neutral subset of the toolkit. Intended for consumers that bundle apcore-toolkit into a browser, edge runtime, or worker environment (e.g. `tiptap-apcore`). The default entry point continues to re-export the full Node-capable surface unchanged — this subpath is strictly additive; existing consumers (`nestjs-apcore` et al.) see zero API changes.
+  - Exposes: `ScannedModule` / `createScannedModule` / `cloneModule`, `BaseScanner`, the HTTP verb mapping helpers, `enrichSchemaDescriptions`, the OpenAPI resolvers (`resolveRef` / `resolveSchema` / `deepResolveRefs` / `extractInputSchema` / `extractOutputSchema`), the serializers (`annotationsToDict` / `moduleToDict` / `modulesToDicts`), `toMarkdown`, `BindingParser` / `parseBindingDocument` / `BindingLoadError`, the write-pipeline types (`WriteResult` / `VerifyResult` / `Verifier` / `createWriteResult` / `WriteError` / `InvalidFormatError`), `RegistryVerifier` / `runVerifierChain`, and `HTTPProxyRegistryWriter` / `HTTPProxyWriterError`.
+  - Excludes (Node-only): `YAMLWriter`, `TypeScriptWriter`, `RegistryWriter`, `getWriter`, `BindingLoader` (the fs-reading subclass — use `BindingParser` instead), `DisplayResolver`, `AIEnhancer`, `resolveTarget`, the file-based verifiers (`YAMLVerifier`, `SyntaxVerifier`, `MagicBytesVerifier`, `JSONVerifier`), and `VERSION`. These touch `node:fs` / `node:path` / `node:module` / `process.*` and cannot be safely bundled for browsers.
+- **`BindingParser`** — new class at `src/binding-parser.ts` that owns the runtime-neutral binding document parsing logic. `BindingLoader` is now a subclass that adds `load(filePath)` for filesystem loading. `BindingLoader.loadData(data)` continues to work unchanged (inherited). Mirrors the `load_data` split available on the Python `BindingLoader` class.
+- **`parseBindingDocument(raw, options?, filePath?)`** — standalone function form of `BindingParser.loadData`, with an optional explicit `filePath` for richer `BindingLoadError` messages when the document came from a known file location.
+- **`HTTPProxyRegistryWriter` documented in README API table** — previously shipped but undocumented. Uses only global `fetch` / `AbortController` / `URLSearchParams`; runs in any modern runtime.
+
+### Internal restructuring (no public API change)
+
+- **`src/output/verifiers.ts` split** — the runtime-neutral `RegistryVerifier` class and `runVerifierChain` function moved to a new `src/output/verify-core.ts`. `verifiers.ts` still re-exports them, so all existing imports (`nestjs-apcore`, the default package entry, internal consumers like `registry-writer.ts` and `base-writer.ts`) continue to resolve the same symbols from the same path. The split lets `apcore-toolkit/browser` import directly from `verify-core.ts` without pulling in the file-based verifiers' `node:fs` / `node:module` dependencies.
+- **`src/binding-loader.ts` split** — the class hierarchy is now `BindingLoader extends BindingParser`, with the pure parsing primitives and error / options types relocated to `src/binding-parser.ts`. `BindingLoader` retains its `load(filePath)` method and re-exports `BindingParser`, `parseBindingDocument`, `BindingLoadError`, and `BindingLoadOptions` so all existing import paths keep working.
+
+### Tests
+
+- +3 new tests in `tests/browser-entry.test.ts`:
+  1. The expected 30-symbol browser-safe surface is actually exported.
+  2. Node-only symbols (`YAMLWriter`, `BindingLoader`, `AIEnhancer`, `VERSION`, et al.) are **not** leaked into the subpath.
+  3. Static import-graph walker starts at `src/browser/index.ts` and recursively reads every relative import; fails if any file in the transitive graph references `node:*`, a bare Node builtin, `process.*`, or `createRequire`. This is the regression guard — any future change that accidentally pulls a Node dependency into the browser subpath will be blocked in CI.
+- Full suite: **457 tests across 22 files, all passing.**
+
 ## [0.4.0] - 2026-03-25
 
 ### Added

package/LICENSE

@@ -0,0 +1,185 @@
+                                 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 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, as defined in Section 5, any work of authorship,
+      including the original version of the Work and any modifications or
+      additions to that Work or Derivative Works of the Work, that is
+      intentionally submitted to the 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 Legal Entity on behalf of
+      whom a Contribution has been received by the 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 the 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 any 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, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, 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 license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the Work and
+      Derivative Works, subject to the conditions of 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 reasonable and customary use in 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 reproducing 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 exemplary 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 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 offer
+      such conditions 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
+
+   Copyright 2024 AI Partner Up
+
+   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

@@ -16,10 +16,10 @@ npm install apcore-toolkit
 
 - Abstract `BaseScanner` for framework-specific endpoint scanning
 - OpenAPI schema extraction (`extractInputSchema`, `extractOutputSchema`)
-- Multi-format output writers (YAML, TypeScript, Registry) with pluggable verification
+- Multi-format output writers (YAML, TypeScript, Registry, HTTP-proxy) with pluggable verification
 - Markdown formatting with depth control and table heuristics
 - Module serialization utilities
-- `flattenParams` for Zod-based parameter flattening
+- Runtime-neutral subset via `apcore-toolkit/browser` for browser / edge / worker environments
 
 ## Usage
 
@@ -114,45 +114,97 @@ const dict = moduleToDict(mod);       // snake_case keys
 const dicts = modulesToDicts(modules); // batch conversion
 ```
 
+## Browser / edge runtime
+
+The default entry point (`apcore-toolkit`) targets Node: it exposes writers
+that touch the filesystem (`YAMLWriter`, `TypeScriptWriter`), a binding
+loader that reads from disk (`BindingLoader`), display / target resolvers,
+and the `VERSION` constant — all of which transitively pull in `node:fs`,
+`node:path`, `node:module`, or `process.*` and would break a browser
+bundle.
+
+For browser, edge-runtime, or worker consumers, `apcore-toolkit/browser`
+exports the runtime-neutral subset — schema / OpenAPI utilities, the
+abstract scanner, serializers, Markdown formatting, the binding **parser**
+(no filesystem access), the write-pipeline types, the runtime-neutral
+verifier primitives (`RegistryVerifier`, `runVerifierChain`), and the
+`HTTPProxyRegistryWriter` (uses only global `fetch` / `AbortController`).
+
+```typescript
+import {
+  BaseScanner,
+  BindingParser,
+  parseBindingDocument,
+  HTTPProxyRegistryWriter,
+  toMarkdown,
+} from 'apcore-toolkit/browser';
+
+// Parse a binding document fetched from a backend (no fs access).
+const resp   = await fetch('/api/bindings');
+const doc    = await resp.json();
+const modules = new BindingParser().loadData(doc);
+
+// Register each module as an HTTP proxy in an in-browser registry.
+const writer = new HTTPProxyRegistryWriter({ baseUrl: '/api' });
+await writer.write(modules, registry);
+```
+
+The default entry continues to re-export every symbol it always did (for
+tri-SDK parity with the Python and Rust toolkits and for unchanged behaviour
+in `nestjs-apcore` etc.). The `/browser` subpath is strictly additive — it
+exposes a subset of the same underlying classes, not a forked implementation.
+A static import-graph check in the test suite fails CI if any Node-only
+reference leaks into the subpath.
+
 ## API
 
-| Export | Description |
-|--------|-------------|
-| `ScannedModule` | Interface for scanned endpoint data |
-| `createScannedModule()` | Factory with defaults for optional fields |
-| `cloneModule()` | Defensive copy with optional overrides |
-| `BaseScanner` | Abstract base class for scanners |
-| `YAMLWriter` | Writes YAML binding files |
-| `TypeScriptWriter` | Generates TypeScript module wrappers |
-| `RegistryWriter` | Registers modules into an apcore Registry |
-| `getWriter()` | Factory for writer instances |
-| `extractInputSchema()` | Extract input schema from OpenAPI operation |
-| `extractOutputSchema()` | Extract output schema from OpenAPI operation |
-| `resolveRef()` | Resolve `$ref` in OpenAPI documents |
-| `resolveSchema()` | Resolve schema with single-level `$ref` support |
-| `deepResolveRefs()` | Recursively resolve all nested `$ref` pointers in a schema |
-| `enrichSchemaDescriptions()` | Merge parameter descriptions into schema |
-| `toMarkdown()` | Convert dict to formatted Markdown |
-| `moduleToDict()` | Serialize module to snake_case dict |
-| `modulesToDicts()` | Batch serialize modules |
-| `annotationsToDict()` | Convert annotations to plain dict |
-| `resolveTarget()` | Dynamic import + named export resolution |
-| `flattenParams()` | Flatten Zod schema params into keyword args |
-| `WriteResult` | Structured result type for writer operations |
-| `Verifier` | Interface for pluggable output verification |
-| `VerifyResult` | Result type for verification operations |
-| `WriteError` | Error class for I/O failures during write |
-| `YAMLVerifier` | Verifies YAML binding file structure |
-| `SyntaxVerifier` | Verifies file is non-empty and readable |
-| `RegistryVerifier` | Verifies module registered in registry |
-| `MagicBytesVerifier` | Verifies file header matches expected bytes |
-| `JSONVerifier` | Verifies valid JSON, optional schema check |
-| `createWriteResult()` | Factory for WriteResult with defaults |
-| `runVerifierChain()` | Run verifier chain, short-circuit on first failure |
-| `Enhancer` | Pluggable interface for metadata enhancement |
-| `AIEnhancer` | SLM-based metadata enhancement for scanned modules |
-| `DisplayResolver` | Sparse binding.yaml overlay — resolves alias, description, guidance, tags into `metadata["display"]` |
-| `VERSION` | Package version string |
+The **Browser** column marks whether a symbol is also re-exported from
+`apcore-toolkit/browser`. All symbols without a ✓ touch `node:fs`,
+`node:path`, `node:module`, or `process.*` and are Node-only.
+
+| Export | Browser | Description |
+|--------|:---:|-------------|
+| `ScannedModule` | ✓ | Interface for scanned endpoint data |
+| `createScannedModule()` | ✓ | Factory with defaults for optional fields |
+| `cloneModule()` | ✓ | Defensive copy with optional overrides |
+| `BaseScanner` | ✓ | Abstract base class for scanners |
+| `YAMLWriter` | | Writes YAML binding files |
+| `BindingLoader` | | Reads `.binding.yaml` files from disk and parses them back into `ScannedModule` objects. Subclass of `BindingParser`. |
+| `BindingParser` | ✓ | Runtime-neutral half of `BindingLoader`. `loadData(data)` parses an already-loaded binding document into `ScannedModule[]` — no filesystem access. |
+| `parseBindingDocument()` | ✓ | Standalone-function form of `BindingParser.loadData`, with an optional `filePath` for richer error messages. |
+| `BindingLoadError` | ✓ | Error class raised when binding parsing fails; carries `filePath`, `moduleId`, `missingFields`, `reason` |
+| `TypeScriptWriter` | | Generates TypeScript module wrappers |
+| `RegistryWriter` | | Registers modules into an apcore Registry |
+| `HTTPProxyRegistryWriter` | ✓ | Registers modules as HTTP-proxied entries in an in-memory registry. Each module's `execute()` forwards inputs to a backend URL via global `fetch`. Works in any runtime with `fetch` (Node 20+, browsers, edge, workers). |
+| `HTTPProxyWriterError` | ✓ | Error class thrown when HTTP fields cannot be extracted from a `ScannedModule` |
+| `getWriter()` | | Factory for writer instances |
+| `extractInputSchema()` | ✓ | Extract input schema from OpenAPI operation |
+| `extractOutputSchema()` | ✓ | Extract output schema from OpenAPI operation |
+| `resolveRef()` | ✓ | Resolve `$ref` in OpenAPI documents |
+| `resolveSchema()` | ✓ | Resolve schema with single-level `$ref` support |
+| `deepResolveRefs()` | ✓ | Recursively resolve all nested `$ref` pointers in a schema |
+| `enrichSchemaDescriptions()` | ✓ | Merge parameter descriptions into schema |
+| `toMarkdown()` | ✓ | Convert dict to formatted Markdown |
+| `moduleToDict()` | ✓ | Serialize module to snake_case dict |
+| `modulesToDicts()` | ✓ | Batch serialize modules |
+| `annotationsToDict()` | ✓ | Convert annotations to plain dict |
+| `resolveTarget()` | | Dynamic import + named export resolution (supports `allowedPrefixes` allowlist) |
+| `WriteResult` | ✓ | Structured result type for writer operations |
+| `Verifier` | ✓ | Interface for pluggable output verification |
+| `VerifyResult` | ✓ | Result type for verification operations |
+| `WriteError` | ✓ | Error class for I/O failures during write |
+| `InvalidFormatError` | ✓ | Error thrown by `getWriter` for unrecognised format names |
+| `YAMLVerifier` | | Verifies YAML binding file structure (reads file) |
+| `SyntaxVerifier` | | Verifies file is non-empty and parses as TypeScript (reads file) |
+| `RegistryVerifier` | ✓ | Verifies module registered in a registry (pure; no filesystem) |
+| `MagicBytesVerifier` | | Verifies file header matches expected bytes (reads file) |
+| `JSONVerifier` | | Verifies valid JSON, optional schema check (reads file) |
+| `createWriteResult()` | ✓ | Factory for WriteResult with defaults |
+| `runVerifierChain()` | ✓ | Run verifier chain, short-circuit on first failure |
+| `Enhancer` | | Pluggable interface for metadata enhancement |
+| `AIEnhancer` | | SLM-based metadata enhancement for scanned modules |
+| `DisplayResolver` | | Sparse binding.yaml overlay — resolves alias, description, guidance, tags into `metadata["display"]` |
+| `VERSION` | | Package version string |
 
 ## Documentation
 

package/dist/ai-enhancer.d.ts

@@ -25,6 +25,22 @@ export interface AIEnhancerOptions {
     batchSize?: number;
     timeout?: number;
 }
+/**
+ * AI-driven metadata enhancement using a local SLM (Small Language Model).
+ *
+ * Calls an OpenAI-compatible local API (Ollama, vLLM, LM Studio, etc.) to fill
+ * metadata gaps that static analysis cannot resolve: missing descriptions,
+ * behavioral annotation inference, and input schema generation for untyped
+ * functions.
+ *
+ * Enhancement is gated behind the `APCORE_AI_ENABLED` environment variable.
+ * All AI-generated fields are tagged with `x-generated-by: slm` in the module
+ * metadata for auditability.
+ *
+ * @example
+ * const enhancer = new AIEnhancer({ endpoint: 'http://localhost:11434/v1', model: 'qwen:0.6b' });
+ * const enhanced = await enhancer.enhance(modules);
+ */
 export declare class AIEnhancer {
     readonly endpoint: string;
     readonly model: string;
@@ -34,10 +50,11 @@ export declare class AIEnhancer {
     constructor(options?: AIEnhancerOptions);
     static isEnabled(): boolean;
     enhance(modules: ScannedModule[]): Promise<ScannedModule[]>;
+    private _annotationsAreDefault;
     private _identifyGaps;
     private _enhanceModule;
     private _buildPrompt;
     private _callLLM;
-    static _parseResponse(response: string): Record<string, unknown>;
+    private static _parseResponse;
 }
 //# sourceMappingURL=ai-enhancer.d.ts.map

package/dist/ai-enhancer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-enhancer.d.ts","sourceRoot":"","sources":["../src/ai-enhancer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA4EhD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,CAAC,EAAE,iBAAiB;IAkBvC,MAAM,CAAC,SAAS,IAAI,OAAO;IAKrB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA0BjE,OAAO,CAAC,aAAa;YAkBP,cAAc;IA6E5B,OAAO,CAAC,YAAY;YAkDN,QAAQ;IAuCtB,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAcjE"}
+{"version":3,"file":"ai-enhancer.d.ts","sourceRoot":"","sources":["../src/ai-enhancer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA4EhD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,CAAC,EAAE,iBAAiB;IA4BvC,MAAM,CAAC,SAAS,IAAI,OAAO;IAKrB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA+BjE,OAAO,CAAC,sBAAsB;IAc9B,OAAO,CAAC,aAAa;YAsBP,cAAc;IAyF5B,OAAO,CAAC,YAAY;YA2DN,QAAQ;IAuCtB,OAAO,CAAC,MAAM,CAAC,cAAc;CAsB9B"}