@fungi.computer/forage 0.0.0-stage → 0.0.1

package/docs/api/json-schema-subset.md

@@ -0,0 +1,42 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/forage**](README.md)
+
+---
+
+[@fungi.computer/forage](README.md) / json-schema-subset
+
+# json-schema-subset
+
+## Functions
+
+### jsonSchemaSubset()
+
+```ts
+function jsonSchemaSubset(
+  allowNullable?,
+): ZodPipe<
+  ZodUnknown,
+  ZodType<
+    boolean | Record<string, JSONType>,
+    unknown,
+    $ZodTypeInternals<boolean | Record<string, JSONType>, unknown>
+  >
+>;
+```
+
+Decode the supported schema subset before using the shared Zod compiler. Refuse
+depth over 32, more than 50,000 expanded nodes and reserved keys before
+recursive decoding. Callers bound transport bytes separately.
+
+#### Parameters
+
+| Parameter       | Type      | Default value |
+| --------------- | --------- | ------------- |
+| `allowNullable` | `boolean` | `false`       |
+
+#### Returns
+
+`ZodPipe`\<`ZodUnknown`, `ZodType`\<`boolean` \| `Record`\<`string`,
+`JSONType`\>, `unknown`, `$ZodTypeInternals`\<`boolean` \| `Record`\<`string`,
+`JSONType`\>, `unknown`\>\>\>

package/docs/api/openapi.md

@@ -0,0 +1,308 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/forage**](README.md)
+
+---
+
+[@fungi.computer/forage](README.md) / openapi
+
+# openapi
+
+## Classes
+
+### OpenApiError
+
+A bounded intake refusal, distinct from a listed unsupported operation.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new OpenApiError(
+   code,
+   message,
+   cause?
+): OpenApiError;
+```
+
+###### Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `code`    | [`OpenApiRefusalCode`](#openapirefusalcode) |
+| `message` | `string`                                    |
+| `cause?`  | `unknown`                                   |
+
+###### Returns
+
+[`OpenApiError`](#openapierror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "OpenApiError" = "OpenApiError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### code
+
+```ts
+readonly code: OpenApiRefusalCode;
+```
+
+## Type Aliases
+
+### OpenApiThirdPartyText
+
+```ts
+type OpenApiThirdPartyText = string & z.BRAND<"ThirdPartyText">;
+```
+
+Bounded provider-authored text. Hosts must frame it as data, never instructions.
+
+---
+
+### OpenApiIntakeOptions
+
+```ts
+type OpenApiIntakeOptions = object;
+```
+
+Optional owner-declared credential parameter excluded from guest input.
+
+#### Properties
+
+##### authParameter?
+
+```ts
+optional authParameter?: object;
+```
+
+###### in
+
+```ts
+in: "header" | "query";
+```
+
+###### name
+
+```ts
+name: string;
+```
+
+---
+
+### OpenApiRefusalCode
+
+```ts
+type OpenApiRefusalCode =
+  | "too_large"
+  | "invalid_spec"
+  | "not_openapi3"
+  | "nodes_limit"
+  | "depth_limit"
+  | "alias_limit"
+  | "external_reference"
+  | "recursive_schema"
+  | "operations_limit"
+  | "invalid_operation"
+  | "unsupported_schema"
+  | "parameter_collision"
+  | "unsafe_auth_parameter"
+  | "unsafe_header"
+  | "unsupported_parameter"
+  | "unsupported_media"
+  | "unsupported_path_item"
+  | "unsupported_method"
+  | "table_too_large"
+  | "invalid_table"
+  | "unsafe_name"
+  | "unsafe_path";
+```
+
+Stable intake and per-operation refusal codes.
+
+---
+
+### OpenApiOperation
+
+```ts
+type OpenApiOperation = z.output<typeof openApiOperationSchema>;
+```
+
+Decoded normalized operation ready for selection, not an execution grant.
+
+---
+
+### OpenApiPreviewOperation
+
+```ts
+type OpenApiPreviewOperation =
+  | OpenApiOperation
+  | {
+      status: "unsupported";
+      name: string;
+      method: string;
+      path: string;
+      reason: OpenApiRefusalCode;
+    };
+```
+
+An operation's supported call shape or bounded unsupported reason.
+
+## Variables
+
+### openApiOperationSchema
+
+```ts
+const openApiOperationSchema: ZodObject<
+  {
+    status: ZodLiteral<"supported">;
+    name: ZodString;
+    method: ZodEnum<{
+      GET: "GET";
+      HEAD: "HEAD";
+      OPTIONS: "OPTIONS";
+      POST: "POST";
+      PUT: "PUT";
+      PATCH: "PATCH";
+      DELETE: "DELETE";
+    }>;
+    path: ZodString;
+    effect: ZodEnum<{
+      write: "write";
+      read: "read";
+    }>;
+    description: $ZodBranded<ZodString, "ThirdPartyText", "out">;
+    textSource: ZodLiteral<"third_party">;
+    tags: ZodArray<$ZodBranded<ZodString, "ThirdPartyText", "out">>;
+    parameters: ZodArray<
+      ZodObject<
+        {
+          name: ZodString;
+          in: ZodEnum<{
+            header: "header";
+            path: "path";
+            query: "query";
+          }>;
+          required: ZodDefault<ZodBoolean>;
+          schema: ZodUnion<
+            readonly [ZodRecord<ZodString, ZodJSONSchema>, ZodBoolean]
+          >;
+          style: ZodOptional<ZodString>;
+          explode: ZodOptional<ZodBoolean>;
+          allowReserved: ZodOptional<ZodBoolean>;
+        },
+        $strip
+      >
+    >;
+    input: ZodPipe<
+      ZodUnknown,
+      ZodType<
+        boolean | Record<string, JSONType>,
+        unknown,
+        $ZodTypeInternals<boolean | Record<string, JSONType>, unknown>
+      >
+    >;
+    output: ZodPipe<
+      ZodUnknown,
+      ZodType<
+        boolean | Record<string, JSONType>,
+        unknown,
+        $ZodTypeInternals<boolean | Record<string, JSONType>, unknown>
+      >
+    >;
+  },
+  $strict
+>;
+```
+
+One stored operation, independent of spec-host URLs or credentials.
+
+## Functions
+
+### normalizeOpenApi()
+
+```ts
+function normalizeOpenApi(
+  source,
+  options?,
+): Promise<{
+  title: string & $brand<"ThirdPartyText">;
+  version: string;
+  servers: string[];
+  authHints: (
+    | {
+        scheme: string;
+        kind: "api_key_header" | "api_key_query";
+        name: string;
+      }
+    | {
+        scheme: string;
+        kind: "bearer" | "oauth" | "unsupported";
+      }
+  )[];
+  operations: OpenApiPreviewOperation[];
+  tableDigest: string;
+}>;
+```
+
+Pure intake: the host supplies bounded spec text, never a fetch locator.
+
+#### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `source`  | `string`                                        |
+| `options` | [`OpenApiIntakeOptions`](#openapiintakeoptions) |
+
+#### Returns
+
+`Promise`\<\{ `title`: `string` & `$brand`\<`"ThirdPartyText"`\>; `version`:
+`string`; `servers`: `string`[]; `authHints`: ( \| \{ `scheme`: `string`;
+`kind`: `"api_key_header"` \| `"api_key_query"`; `name`: `string`; \} \| \{
+`scheme`: `string`; `kind`: `"bearer"` \| `"oauth"` \| `"unsupported"`; \})[];
+`operations`: [`OpenApiPreviewOperation`](#openapipreviewoperation)[];
+`tableDigest`: `string`; \}\>
+
+---
+
+### parseOpenApiTable()
+
+```ts
+function parseOpenApiTable(source): Promise<{
+  operations: object[];
+  digest: string;
+}>;
+```
+
+Decode selected operations before persistence or execution; no authority is
+granted.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `source`  | `unknown` |
+
+#### Returns
+
+`Promise`\<\{ `operations`: `object`[]; `digest`: `string`; \}\>

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@fungi.computer/forage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Pure immutable Zod-typed capability discovery",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./json-schema-subset": {
+      "types": "./dist/json-schema-subset.d.ts",
+      "import": "./dist/json-schema-subset.js"
+    },
+    "./openapi": {
+      "types": "./dist/openapi.d.ts",
+      "import": "./dist/openapi.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "16.0.3",
+    "@fungi.computer/puffball": "0.0.1",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "effect": "4.0.2",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/forage.git"
+  },
+  "scripts": {
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "vitest run",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "pack": "mkdir -p ../../.botanical/forage-pack && pnpm pack --pack-destination ../../.botanical/forage-pack",
+    "smoke": "node --input-type=module -e \"import('./dist/index.js').then(({Forage}) => { if (!Forage) process.exit(1); })\"",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }