apcore-toolkit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+
+## [0.6.0] - 2026-05-07
+
+### Changed
+
+- **`apcore-js` minimum version bumped from 0.20.0 to 0.21.0** — `package.json` `dependencies` now requires `apcore-js >=0.21.0`. Toolkit only imports stable apcore-js surface (`ModuleAnnotations`, `DEFAULT_ANNOTATIONS`, `ModuleExample`, `Context`, `FunctionModule`, `jsonSchemaToTypeBox`, `annotationsFromJSON`, `annotationsToJSON`); the 0.21.0 additions (`discoverable` field on `ModuleAnnotations`, `PreviewResult`, `Change`, `ephemeral.*` namespace) are automatically handled — `annotationsFromJSON` / `annotationsToJSON` already serialize `discoverable`, and `inferAnnotationsFromMethod` spreads `DEFAULT_ANNOTATIONS` so the new field propagates without code changes. `AIEnhancer` derives its annotation field set from `Object.entries(DEFAULT_ANNOTATIONS)` at load time, so it also picks up `discoverable` automatically. Full vitest suite + `tsc --noEmit` verified against apcore-js 0.21.0.
+- **`apcore-js` minimum version bumped from 0.19.0 to 0.20.0** — `package.json` `dependencies` now requires `apcore-js >=0.20.0`; `pnpm-lock.yaml` regenerated to `apcore-js@0.20.0`. Toolkit only imports stable apcore-js surface (`ModuleAnnotations`, `DEFAULT_ANNOTATIONS`, `ModuleExample`, `Context`, `FunctionModule`, `jsonSchemaToTypeBox`, `annotationsFromJSON`, `annotationsToJSON`); none of these were affected by 0.20.0 changes. Full vitest suite (490 passed) + `tsc --noEmit` clean against apcore-js 0.20.0.
+
+### Added
+
+- **Surface-aware formatters** (refs aiperceivable/apcore-toolkit#13) — `formatModule`, `formatSchema`, `formatModules` for rendering `ScannedModule` and JSON Schema for specific consumer surfaces. Four styles for `formatModule`: `markdown` (LLM context), `skill` (drop-in `.claude/skills/<id>/SKILL.md` or `.gemini/skills/<id>/SKILL.md` body with minimal `name` + `description` frontmatter — no vendor-specific extensions), `table-row` (CLI listing), `json` (programmatic). `formatSchema` styles: `prose`, `table`, `json`. `formatModules` adds optional `groupBy: "tag" | "prefix"`. `display: true` (default) prefers the `ScannedModule.display` overlay over raw fields. Lives in `src/formatting/surface.ts`; re-exported from the top-level package.
+- **Annotation-table cross-SDK alignment** — `formatModule({style: "markdown" | "skill"})` `## Behavior` table now emits only fields that differ from `DEFAULT_ANNOTATIONS`, sorts rows alphabetically by snake_case key, and renders bool values as lowercase `true`/`false`. The section is omitted entirely when every annotation field matches its default. Closes the byte-equality gap with the Python and Rust SDKs.
+
+### Changed
+
+- **`inferAnnotationsFromMethod` canonical mapping** (refs aiperceivable/apcore-toolkit#11) — `HEAD` and `OPTIONS` now map to `readonly=true` (without `cacheable=true`), matching the canonical mapping declared in `apcore-toolkit/docs/features/scanning.md` and aligning with the existing Rust SDK. Previously these methods returned default annotations.
+
+## [0.5.1] - 2026-04-30
+
+### Fixed
+
+- **`package.json` `preinstall` hook removed** — the `npx only-allow pnpm` script was a development-time guardrail that also fired when downstream consumers installed `apcore-toolkit` as a dependency via npm or yarn, causing their installs to fail. The hook has been removed from the published package; pnpm enforcement remains in the monorepo root for internal development.
+
 ## [0.5.0] - 2026-04-21
 
 ### Added

package/LICENSE

@@ -170,7 +170,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2024 AI Partner Up
+   Copyright 2024 aiperceivable
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/dist/binding-loader.d.ts

@@ -13,7 +13,6 @@
  * from `apcore-toolkit/browser` instead.
  */
 import { BindingParser } from './binding-parser.js';
-import type { BindingLoadOptions } from './binding-parser.js';
 import type { ScannedModule } from './types.js';
 export { BindingLoadError, BindingParser, parseBindingDocument } from './binding-parser.js';
 export type { BindingLoadOptions } from './binding-parser.js';
@@ -29,17 +28,20 @@ export type { BindingLoadOptions } from './binding-parser.js';
  * ```ts
  * const loader = new BindingLoader();
  * const modules = loader.load('./bindings/');
- * const strict = loader.load('foo.binding.yaml', { strict: true });
+ * const strict = loader.load('foo.binding.yaml', true, false);
  * ```
  */
 export declare class BindingLoader extends BindingParser {
     /**
      * Load one file or every `*.binding.yaml` in a directory.
      *
+     * @param filePath - Path to a single `.binding.yaml` file or a directory.
+     * @param strict - When `true`, also require `input_schema` and `output_schema`. Default: `false`.
+     * @param recursive - When `true`, recurse into subdirectories. Default: `false`.
      * @throws {BindingLoadError} when the path is missing, YAML is malformed,
      *   or any entry fails validation.
      */
-    load(filePath: string, options?: BindingLoadOptions): ScannedModule[];
+    load(filePath: string, strict?: boolean, recursive?: boolean): ScannedModule[];
     /**
      * Recursively collect `.binding.yaml` files under `dir`. Follows symlinks
      * (for parity with the non-recursive branch, which reads file contents and

package/dist/binding-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding-loader.d.ts","sourceRoot":"","sources":["../src/binding-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAEL,aAAa,EAEd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC5F,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAU9D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC9C;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa,EAAE;IAiErE;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;CA6C1B"}
+{"version":3,"file":"binding-loader.d.ts","sourceRoot":"","sources":["../src/binding-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAEL,aAAa,EAEd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC5F,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAgB9D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC9C;;;;;;;;OAQG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE;IAwF9E;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;CA6C1B"}

package/dist/binding-loader.js

@@ -22,6 +22,10 @@ import { BindingLoadError, BindingParser, parseBindingDocument, } from './bindin
 // change — plus the new {@link BindingParser} and
 // {@link parseBindingDocument} additions that are now also available.
 export { BindingLoadError, BindingParser, parseBindingDocument } from './binding-parser.js';
+/** Maximum file size (bytes) that BindingLoader will read — matches Rust SDK's 16 MiB cap. */
+const MAX_BINDING_FILE_SIZE = 16 * 1024 * 1024; // 16 MiB
+/** Maximum number of .binding.yaml files per directory scan — matches Rust SDK's cap. */
+const MAX_BINDING_FILES_PER_DIR = 10_000;
 // Cap on directory recursion depth in `_collectRecursive`. This is the
 // PRIMARY defense against symlink loops (`a -> b -> a`): `statSync` resolves
 // symlinks but does not detect cycles, so a cyclic graph would recurse until
@@ -41,19 +45,22 @@ const MAX_RECURSION_DEPTH = 64;
  * ```ts
  * const loader = new BindingLoader();
  * const modules = loader.load('./bindings/');
- * const strict = loader.load('foo.binding.yaml', { strict: true });
+ * const strict = loader.load('foo.binding.yaml', true, false);
  * ```
  */
 export class BindingLoader extends BindingParser {
     /**
      * Load one file or every `*.binding.yaml` in a directory.
      *
+     * @param filePath - Path to a single `.binding.yaml` file or a directory.
+     * @param strict - When `true`, also require `input_schema` and `output_schema`. Default: `false`.
+     * @param recursive - When `true`, recurse into subdirectories. Default: `false`.
      * @throws {BindingLoadError} when the path is missing, YAML is malformed,
      *   or any entry fails validation.
      */
-    load(filePath, options) {
-        const strict = options?.strict ?? false;
-        const recursive = options?.recursive ?? false;
+    load(filePath, strict, recursive) {
+        strict = strict ?? false;
+        recursive = recursive ?? false;
         let stat;
         try {
             stat = fs.statSync(filePath);
@@ -74,9 +81,16 @@ export class BindingLoader extends BindingParser {
                 files = this._collectRecursive(filePath).sort();
             }
             else {
-                files = fs
+                const allEntries = fs
                     .readdirSync(filePath)
-                    .filter((f) => f.endsWith('.binding.yaml'))
+                    .filter((f) => f.endsWith('.binding.yaml'));
+                if (allEntries.length > MAX_BINDING_FILES_PER_DIR) {
+                    throw new BindingLoadError({
+                        reason: `too many files in directory: ${allEntries.length} exceeds limit of ${MAX_BINDING_FILES_PER_DIR}`,
+                        filePath,
+                    });
+                }
+                files = allEntries
                     .sort()
                     .map((f) => path.join(filePath, f));
             }
@@ -89,6 +103,23 @@ export class BindingLoader extends BindingParser {
         }
         const modules = [];
         for (const f of files) {
+            // Enforce per-file size cap before reading
+            let fileStat;
+            try {
+                fileStat = fs.statSync(f);
+            }
+            catch (exc) {
+                throw new BindingLoadError({
+                    reason: `failed to stat file: ${exc.message}`,
+                    filePath: f,
+                });
+            }
+            if (fileStat.size > MAX_BINDING_FILE_SIZE) {
+                throw new BindingLoadError({
+                    reason: `file too large: ${fileStat.size} bytes exceeds limit of ${MAX_BINDING_FILE_SIZE} bytes (16 MiB)`,
+                    filePath: f,
+                });
+            }
             let content;
             try {
                 content = fs.readFileSync(f, 'utf-8');

package/dist/binding-loader.js.map

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

package/dist/browser/index.d.ts

@@ -12,6 +12,6 @@ export type { WriteResult, VerifyResult, Verifier } from '../output/types.js';
 export { createWriteResult } from '../output/types.js';
 export { WriteError, InvalidFormatError } from '../output/errors.js';
 export { RegistryVerifier, runVerifierChain } from '../output/verify-core.js';
-export { HTTPProxyRegistryWriter, HTTPProxyWriterError, } from '../output/http-proxy-writer.js';
+export { HTTPProxyRegistryWriter, HTTPProxyRegistryWriterError, } from '../output/http-proxy-writer.js';
 export type { HTTPProxyRegistryWriterOptions, ProxyRegistry, } from '../output/http-proxy-writer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAkBA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOpD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAMrE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO9E,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,8BAA8B,EAC9B,aAAa,GACd,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAkBA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOpD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAMrE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO9E,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,8BAA8B,EAC9B,aAAa,GACd,MAAM,gCAAgC,CAAC"}

package/dist/browser/index.js

@@ -42,5 +42,5 @@ export { RegistryVerifier, runVerifierChain } from '../output/verify-core.js';
 // registry — each module's `execute()` forwards inputs to a backend URL.
 // Works in any environment where `fetch` is available (Node 20+, browsers,
 // Deno, workers).
-export { HTTPProxyRegistryWriter, HTTPProxyWriterError, } from '../output/http-proxy-writer.js';
+export { HTTPProxyRegistryWriter, HTTPProxyRegistryWriterError, } from '../output/http-proxy-writer.js';
 //# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,sBAAsB;AACtB,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,qEAAqE;AACrE,yEAAyE;AACzE,MAAM;AAIN,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,6EAA6E;AAC7E,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,6EAA6E;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,qDAAqD;AACrD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAErE,6EAA6E;AAC7E,gFAAgF;AAChF,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE9E,6EAA6E;AAC7E,sEAAsE;AACtE,yEAAyE;AACzE,2EAA2E;AAC3E,kBAAkB;AAClB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,sBAAsB;AACtB,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,qEAAqE;AACrE,yEAAyE;AACzE,MAAM;AAIN,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,6EAA6E;AAC7E,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,6EAA6E;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,qDAAqD;AACrD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAErE,6EAA6E;AAC7E,gFAAgF;AAChF,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE9E,6EAA6E;AAC7E,sEAAsE;AACtE,yEAAyE;AACzE,2EAA2E;AAC3E,kBAAkB;AAClB,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC"}

package/dist/formatting/index.d.ts

@@ -1,2 +1,4 @@
 export { toMarkdown } from './markdown.js';
+export { formatSchema, formatModule, formatModules, } from './surface.js';
+export type { SchemaStyle, ModuleStyle, GroupBy, FormatSchemaOptions, FormatModuleOptions, FormatModulesOptions, } from './surface.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/formatting/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatting/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatting/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,cAAc,CAAC"}

package/dist/formatting/index.js

@@ -1,2 +1,3 @@
 export { toMarkdown } from './markdown.js';
+export { formatSchema, formatModule, formatModules, } from './surface.js';
 //# sourceMappingURL=index.js.map

package/dist/formatting/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/formatting/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/formatting/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC"}

package/dist/formatting/surface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Surface-aware formatters.
+ *
+ * Render `ScannedModule` and JSON Schema for specific consumer surfaces:
+ * LLM context (markdown), agent skill files (skill), CLI listings (table-row),
+ * and programmatic APIs (json). See
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+import type { ScannedModule } from '../types.js';
+export type SchemaStyle = 'prose' | 'table' | 'json';
+export type ModuleStyle = 'markdown' | 'skill' | 'table-row' | 'json';
+export type GroupBy = 'tag' | 'prefix';
+export interface FormatSchemaOptions {
+    style?: SchemaStyle;
+    maxDepth?: number;
+}
+export interface FormatModuleOptions {
+    style?: ModuleStyle;
+    display?: boolean;
+}
+export interface FormatModulesOptions {
+    style?: ModuleStyle;
+    groupBy?: GroupBy | null;
+    display?: boolean;
+}
+/**
+ * Render a JSON Schema for a specific surface.
+ * See `Contract: format_schema` in
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+export declare function formatSchema(schema: Record<string, unknown>, options?: FormatSchemaOptions): string | Record<string, unknown>;
+/**
+ * Render a single ScannedModule for the chosen surface.
+ * See `Contract: format_module` in
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+export declare function formatModule(module: ScannedModule, options?: FormatModuleOptions): string | Record<string, unknown>;
+/**
+ * Render a sequence of ScannedModule for the chosen surface.
+ * See `Contract: format_modules` in
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+export declare function formatModules(modules: ScannedModule[], options?: FormatModulesOptions): string | Record<string, unknown>[];
+//# sourceMappingURL=surface.d.ts.map

package/dist/formatting/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/formatting/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AASjD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AACtE,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAMvC,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwClC;AAyED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+BlC;AAoJD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,GAAE,oBAAyB,GACjC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAyCpC"}

package/dist/formatting/surface.js

@@ -0,0 +1,338 @@
+/**
+ * Surface-aware formatters.
+ *
+ * Render `ScannedModule` and JSON Schema for specific consumer surfaces:
+ * LLM context (markdown), agent skill files (skill), CLI listings (table-row),
+ * and programmatic APIs (json). See
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+import { DEFAULT_ANNOTATIONS } from 'apcore-js';
+import { annotationsToDict, moduleToDict } from '../serializers.js';
+// Snake-case dict of every default-valued annotation field. Used by the
+// behavior-table renderer to skip fields that match the protocol default,
+// keeping the table focused on what is actually non-default about the module.
+const DEFAULT_ANNOTATIONS_DICT = annotationsToDict(DEFAULT_ANNOTATIONS) ?? {};
+const SCHEMA_STYLES = ['prose', 'table', 'json'];
+const MODULE_STYLES = ['markdown', 'skill', 'table-row', 'json'];
+const GROUP_BY_VALUES = ['tag', 'prefix'];
+/**
+ * Render a JSON Schema for a specific surface.
+ * See `Contract: format_schema` in
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+export function formatSchema(schema, options = {}) {
+    const style = options.style ?? 'prose';
+    const maxDepth = options.maxDepth ?? 3;
+    if (!SCHEMA_STYLES.includes(style)) {
+        throw new Error(`formatSchema: unknown style ${JSON.stringify(style)}; expected one of ${JSON.stringify(SCHEMA_STYLES)}`);
+    }
+    if (style === 'json') {
+        return schema;
+    }
+    if (!schema || typeof schema !== 'object') {
+        return '';
+    }
+    const type = schema['type'];
+    const properties = schema['properties'];
+    if (type !== 'object' || !properties || typeof properties !== 'object') {
+        if (type && type !== 'object') {
+            return `_schema accepts ${type}_`;
+        }
+        if (style === 'prose') {
+            return '';
+        }
+        return '| Name | Type | Required | Default | Description |\n|---|---|---|---|---|\n';
+    }
+    const required = new Set(Array.isArray(schema['required'])
+        ? schema['required']
+        : []);
+    if (style === 'prose') {
+        return formatSchemaProse(properties, required, maxDepth, 0);
+    }
+    return formatSchemaTable(properties, required);
+}
+function formatSchemaProse(properties, required, maxDepth, depth) {
+    const lines = [];
+    for (const [name, propRaw] of Object.entries(properties)) {
+        const prop = (typeof propRaw === 'object' && propRaw !== null) ? propRaw : {};
+        const type = prop['type'] ?? 'any';
+        const reqLabel = required.has(name) ? 'required' : 'optional';
+        const desc = (prop['description'] ?? '').trim();
+        let head = `- \`${name}\` (${type}, ${reqLabel})`;
+        if (desc) {
+            head += ` — ${desc}`;
+        }
+        lines.push(head);
+        if (prop['type'] === 'object' &&
+            typeof prop['properties'] === 'object' &&
+            prop['properties'] !== null) {
+            if (depth + 1 >= maxDepth) {
+                lines.push('  ```json');
+                for (const jsonLine of JSON.stringify(prop, null, 2).split('\n')) {
+                    lines.push(`  ${jsonLine}`);
+                }
+                lines.push('  ```');
+            }
+            else {
+                const nestedRequired = new Set(Array.isArray(prop['required']) ? prop['required'] : []);
+                const nested = formatSchemaProse(prop['properties'], nestedRequired, maxDepth, depth + 1);
+                for (const nestedLine of nested.split('\n')) {
+                    lines.push(`  ${nestedLine}`);
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function formatSchemaTable(properties, required) {
+    const rows = [
+        '| Name | Type | Required | Default | Description |',
+        '|---|---|---|---|---|',
+    ];
+    for (const [name, propRaw] of Object.entries(properties)) {
+        const prop = (typeof propRaw === 'object' && propRaw !== null) ? propRaw : {};
+        const type = prop['type'] ?? 'any';
+        const reqLabel = required.has(name) ? 'yes' : 'no';
+        const desc = (prop['description'] ?? '').trim();
+        let defaultStr = '';
+        if (prop['default'] !== undefined) {
+            const d = prop['default'];
+            defaultStr = typeof d === 'object' ? JSON.stringify(d) : String(d);
+        }
+        rows.push(`| \`${name}\` | ${type} | ${reqLabel} | ${defaultStr} | ${desc} |`);
+    }
+    return rows.join('\n');
+}
+/**
+ * Render a single ScannedModule for the chosen surface.
+ * See `Contract: format_module` in
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+export function formatModule(module, options = {}) {
+    const style = options.style ?? 'markdown';
+    const display = options.display ?? true;
+    if (!MODULE_STYLES.includes(style)) {
+        throw new Error(`formatModule: unknown style ${JSON.stringify(style)}; expected one of ${JSON.stringify(MODULE_STYLES)}`);
+    }
+    if (style === 'json') {
+        return moduleToDict(module);
+    }
+    const { title, description, guidance, tags } = resolveDisplayFields(module, display);
+    if (style === 'table-row') {
+        const alias = title !== module.moduleId ? title : '';
+        const tagStr = tags.length > 0 ? tags.join(', ') : '';
+        return `\`${module.moduleId}\` │ \`${alias}\` │ ${description} │ ${tagStr}`;
+    }
+    const body = renderModuleMarkdownBody(module, title, description, guidance, tags);
+    if (style === 'skill') {
+        const oneLine = description.replace(/\n/g, ' ').trim();
+        const frontmatter = `---\nname: ${title}\ndescription: ${yamlScalar(oneLine)}\n---\n\n`;
+        return frontmatter + body;
+    }
+    return body;
+}
+function resolveDisplayFields(module, useDisplay) {
+    const rawTitle = module.moduleId;
+    const rawDesc = module.description ?? '';
+    const rawTags = module.tags ? [...module.tags] : [];
+    if (!useDisplay || !module.display) {
+        return { title: rawTitle, description: rawDesc, guidance: null, tags: rawTags };
+    }
+    const overlay = module.display;
+    const title = overlay['alias'] || rawTitle;
+    const description = overlay['description'] || rawDesc;
+    const guidance = overlay['guidance'] || null;
+    const tagsOverlay = overlay['tags'];
+    const tags = Array.isArray(tagsOverlay) && tagsOverlay.length > 0
+        ? tagsOverlay
+        : rawTags;
+    return { title, description, guidance, tags: [...tags] };
+}
+function renderModuleMarkdownBody(module, title, description, guidance, tags) {
+    const sections = [];
+    sections.push(`# ${title}`);
+    if (description) {
+        sections.push(description);
+    }
+    if (guidance) {
+        sections.push(`_${guidance}_`);
+    }
+    sections.push('## Parameters');
+    const paramsProse = formatSchema(module.inputSchema ?? {}, { style: 'prose' });
+    sections.push(paramsProse ? paramsProse : '_(no parameters)_');
+    sections.push('## Returns');
+    const returnsProse = formatSchema(module.outputSchema ?? {}, { style: 'prose' });
+    sections.push(returnsProse ? returnsProse : '_(no return schema)_');
+    const annotationTable = renderAnnotationsTable(module.annotations);
+    if (annotationTable) {
+        sections.push('## Behavior');
+        sections.push(annotationTable);
+    }
+    if (module.examples && module.examples.length > 0) {
+        sections.push('## Examples');
+        let idx = 1;
+        for (const example of module.examples) {
+            sections.push(`### Example ${idx}`);
+            sections.push('```json');
+            sections.push(JSON.stringify(example, null, 2));
+            sections.push('```');
+            idx += 1;
+        }
+    }
+    if (tags.length > 0) {
+        sections.push('## Tags');
+        sections.push(tags.map((t) => `\`${t}\``).join(', '));
+    }
+    return sections.join('\n\n') + '\n';
+}
+/**
+ * Render `ModuleAnnotations` as a Markdown fact table.
+ *
+ * Cross-SDK alignment rules (see
+ * `apcore-toolkit/docs/features/formatting.md` § Annotations Rendering):
+ *
+ * 1. Emit only fields whose value differs from `DEFAULT_ANNOTATIONS`.
+ * 2. The `extra` free-form bag is always skipped.
+ * 3. Rows are sorted alphabetically by snake_case key.
+ * 4. Bool values render as lowercase `true` / `false`; objects/arrays use
+ *    `JSON.stringify`; everything else uses `String()`.
+ *
+ * Returns `null` when the resulting table would be empty (i.e. every
+ * annotation field equals its default), causing the caller to omit the
+ * `## Behavior` section entirely.
+ */
+function renderAnnotationsTable(annotations) {
+    const data = annotationsToDict(annotations);
+    if (!data)
+        return null;
+    const entries = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (key === 'extra')
+            continue;
+        if (deepEqual(value, DEFAULT_ANNOTATIONS_DICT[key]))
+            continue;
+        entries.push([key, value]);
+    }
+    if (entries.length === 0)
+        return null;
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const rows = ['| Flag | Value |', '|---|---|'];
+    for (const [key, value] of entries) {
+        let rendered;
+        if (value === true) {
+            rendered = 'true';
+        }
+        else if (value === false) {
+            rendered = 'false';
+        }
+        else if (typeof value === 'object' && value !== null) {
+            rendered = JSON.stringify(value);
+        }
+        else {
+            rendered = String(value);
+        }
+        rows.push(`| \`${key}\` | ${rendered} |`);
+    }
+    return rows.join('\n');
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    const aKeys = Object.keys(a).sort();
+    const bKeys = Object.keys(b).sort();
+    if (aKeys.length !== bKeys.length)
+        return false;
+    if (!aKeys.every((k, i) => k === bKeys[i]))
+        return false;
+    return aKeys.every((k) => deepEqual(a[k], b[k]));
+}
+function yamlScalar(text) {
+    if (text === '')
+        return '""';
+    const needsQuote = /[:#{}[\]'"\n&*!|>]/.test(text);
+    if (!needsQuote && !/^[-?%@`]/.test(text)) {
+        return text;
+    }
+    const escaped = text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `"${escaped}"`;
+}
+/**
+ * Render a sequence of ScannedModule for the chosen surface.
+ * See `Contract: format_modules` in
+ * `apcore-toolkit/docs/features/formatting.md`.
+ */
+export function formatModules(modules, options = {}) {
+    const style = options.style ?? 'markdown';
+    const groupBy = options.groupBy ?? null;
+    const display = options.display ?? true;
+    if (!MODULE_STYLES.includes(style)) {
+        throw new Error(`formatModules: unknown style ${JSON.stringify(style)}; expected one of ${JSON.stringify(MODULE_STYLES)}`);
+    }
+    if (groupBy !== null && !GROUP_BY_VALUES.includes(groupBy)) {
+        throw new Error(`formatModules: unknown groupBy ${JSON.stringify(groupBy)}; expected one of ${JSON.stringify(GROUP_BY_VALUES)} or null`);
+    }
+    if (style === 'json') {
+        return modules.map((m) => moduleToDict(m));
+    }
+    const joiner = (style === 'markdown' || style === 'skill') ? '\n\n' : '\n';
+    if (groupBy === null) {
+        return modules
+            .map((m) => formatModule(m, { style, display }))
+            .join(joiner);
+    }
+    const groups = groupModules(modules, groupBy);
+    const out = [];
+    for (const [groupName, groupMembers] of groups) {
+        if (style === 'markdown' || style === 'skill') {
+            out.push(`## ${groupName}`);
+        }
+        else {
+            out.push(`── ${groupName} ──`);
+        }
+        for (const m of groupMembers) {
+            out.push(formatModule(m, { style, display }));
+        }
+    }
+    return out.join(joiner);
+}
+function groupModules(modules, groupBy) {
+    const groups = new Map();
+    for (const module of modules) {
+        if (groupBy === 'prefix') {
+            const idx = module.moduleId.indexOf('.');
+            const prefix = idx >= 0 ? module.moduleId.slice(0, idx) : module.moduleId;
+            const arr = groups.get(prefix) ?? [];
+            arr.push(module);
+            groups.set(prefix, arr);
+        }
+        else {
+            // groupBy === 'tag'
+            if (!module.tags || module.tags.length === 0) {
+                const arr = groups.get('(untagged)') ?? [];
+                arr.push(module);
+                groups.set('(untagged)', arr);
+                continue;
+            }
+            for (const tag of module.tags) {
+                const arr = groups.get(tag) ?? [];
+                arr.push(module);
+                groups.set(tag, arr);
+            }
+        }
+    }
+    return groups;
+}
+//# sourceMappingURL=surface.js.map