@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/companion/technical-documentation-placeholder-materializer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Materializes the framework's deterministic PNG stand-in for a product screenshot.
+ *
+ * Screenshot placeholders and Playwright captures intentionally share one media and
+ * path contract: refining provisional documentation changes bytes and evidence at the
+ * same `assets/captures/<semantic-ref>.png` URL. The authored description is embedded
+ * as UTF-8 PNG metadata while the rendered Markdown/MDX retains the actual image alt.
+ */
+export declare function materializeTechnicalDocumentationPlaceholder(input: {
+    readonly assetRef: string;
+    readonly altText: string;
+}): {
+    readonly bytes: Uint8Array;
+    readonly byteDigest: string;
+    readonly mediaType: 'image/png';
+};
+//# sourceMappingURL=technical-documentation-placeholder-materializer.d.ts.map

package/dist/esm/companion/technical-documentation-placeholder-materializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-placeholder-materializer.d.ts","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-placeholder-materializer.ts"],"names":[],"mappings":"AA2BA;;;;;;;GAOG;AACH,wBAAgB,4CAA4C,CAAC,KAAK,EAAE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GAAG;IACF,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;CACjC,CAgCA"}

package/dist/esm/companion/technical-documentation-placeholder-materializer.js

@@ -0,0 +1,63 @@
+import { deflateSync } from 'node:zlib';
+import { technicalDocumentationSha256Bytes } from './rendering/technical-documentation-render-model.js';
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const WIDTH = 720;
+const HEIGHT = 512;
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit += 1)
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function pngChunk(kind, data) {
+    const type = Buffer.from(kind, 'ascii');
+    const body = Buffer.from(data);
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(body.byteLength);
+    const checksum = Buffer.alloc(4);
+    checksum.writeUInt32BE(crc32(Buffer.concat([type, body])));
+    return Buffer.concat([length, type, body, checksum]);
+}
+/**
+ * Materializes the framework's deterministic PNG stand-in for a product screenshot.
+ *
+ * Screenshot placeholders and Playwright captures intentionally share one media and
+ * path contract: refining provisional documentation changes bytes and evidence at the
+ * same `assets/captures/<semantic-ref>.png` URL. The authored description is embedded
+ * as UTF-8 PNG metadata while the rendered Markdown/MDX retains the actual image alt.
+ */
+export function materializeTechnicalDocumentationPlaceholder(input) {
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(WIDTH, 0);
+    header.writeUInt32BE(HEIGHT, 4);
+    header[8] = 8;
+    header[9] = 2;
+    const rowLength = 1 + (WIDTH * 3);
+    const raster = Buffer.alloc(rowLength * HEIGHT);
+    for (let y = 0; y < HEIGHT; y += 1) {
+        const rowOffset = y * rowLength;
+        raster[rowOffset] = 0;
+        for (let x = 0; x < WIDTH; x += 1) {
+            const pixelOffset = rowOffset + 1 + (x * 3);
+            const border = x < 10 || y < 10 || x >= WIDTH - 10 || y >= HEIGHT - 10;
+            const diagonal = Math.abs((x / WIDTH) - (y / HEIGHT)) < 0.012 || Math.abs((1 - (x / WIDTH)) - (y / HEIGHT)) < 0.012;
+            const color = border || diagonal ? [113, 113, 122] : [244, 244, 245];
+            raster[pixelOffset] = color[0];
+            raster[pixelOffset + 1] = color[1];
+            raster[pixelOffset + 2] = color[2];
+        }
+    }
+    const description = Buffer.from(`Description\0\0\0\0\0Awaiting product capture — ${input.assetRef} — ${input.altText}`, 'utf8');
+    const bytes = Buffer.concat([
+        PNG_SIGNATURE,
+        pngChunk('IHDR', header),
+        pngChunk('iTXt', description),
+        pngChunk('IDAT', deflateSync(raster, { level: 9 })),
+        pngChunk('IEND', Buffer.alloc(0)),
+    ]);
+    return { bytes, byteDigest: technicalDocumentationSha256Bytes(bytes), mediaType: 'image/png' };
+}
+//# sourceMappingURL=technical-documentation-placeholder-materializer.js.map

package/dist/esm/companion/technical-documentation-placeholder-materializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-placeholder-materializer.js","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-placeholder-materializer.ts"],"names":[],"mappings":"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","sourcesContent":["import { deflateSync } from 'node:zlib';\n\nimport { technicalDocumentationSha256Bytes } from './rendering/technical-documentation-render-model';\n\nconst PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);\nconst WIDTH = 720;\nconst HEIGHT = 512;\n\nfunction crc32(bytes: Uint8Array): number {\n  let crc = 0xffffffff;\n  for (const byte of bytes) {\n    crc ^= byte;\n    for (let bit = 0; bit < 8; bit += 1) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));\n  }\n  return (crc ^ 0xffffffff) >>> 0;\n}\n\nfunction pngChunk(kind: string, data: Uint8Array): Buffer {\n  const type = Buffer.from(kind, 'ascii');\n  const body = Buffer.from(data);\n  const length = Buffer.alloc(4);\n  length.writeUInt32BE(body.byteLength);\n  const checksum = Buffer.alloc(4);\n  checksum.writeUInt32BE(crc32(Buffer.concat([type, body])));\n  return Buffer.concat([length, type, body, checksum]);\n}\n\n/**\n * Materializes the framework's deterministic PNG stand-in for a product screenshot.\n *\n * Screenshot placeholders and Playwright captures intentionally share one media and\n * path contract: refining provisional documentation changes bytes and evidence at the\n * same `assets/captures/<semantic-ref>.png` URL. The authored description is embedded\n * as UTF-8 PNG metadata while the rendered Markdown/MDX retains the actual image alt.\n */\nexport function materializeTechnicalDocumentationPlaceholder(input: {\n  readonly assetRef: string;\n  readonly altText: string;\n}): {\n  readonly bytes: Uint8Array;\n  readonly byteDigest: string;\n  readonly mediaType: 'image/png';\n} {\n  const header = Buffer.alloc(13);\n  header.writeUInt32BE(WIDTH, 0);\n  header.writeUInt32BE(HEIGHT, 4);\n  header[8] = 8;\n  header[9] = 2;\n\n  const rowLength = 1 + (WIDTH * 3);\n  const raster = Buffer.alloc(rowLength * HEIGHT);\n  for (let y = 0; y < HEIGHT; y += 1) {\n    const rowOffset = y * rowLength;\n    raster[rowOffset] = 0;\n    for (let x = 0; x < WIDTH; x += 1) {\n      const pixelOffset = rowOffset + 1 + (x * 3);\n      const border = x < 10 || y < 10 || x >= WIDTH - 10 || y >= HEIGHT - 10;\n      const diagonal = Math.abs((x / WIDTH) - (y / HEIGHT)) < 0.012 || Math.abs((1 - (x / WIDTH)) - (y / HEIGHT)) < 0.012;\n      const color = border || diagonal ? [113, 113, 122] : [244, 244, 245];\n      raster[pixelOffset] = color[0];\n      raster[pixelOffset + 1] = color[1];\n      raster[pixelOffset + 2] = color[2];\n    }\n  }\n\n  const description = Buffer.from(`Description\\0\\0\\0\\0\\0Awaiting product capture — ${input.assetRef} — ${input.altText}`, 'utf8');\n  const bytes = Buffer.concat([\n    PNG_SIGNATURE,\n    pngChunk('IHDR', header),\n    pngChunk('iTXt', description),\n    pngChunk('IDAT', deflateSync(raster, { level: 9 })),\n    pngChunk('IEND', Buffer.alloc(0)),\n  ]);\n  return { bytes, byteDigest: technicalDocumentationSha256Bytes(bytes), mediaType: 'image/png' };\n}\n\n"]}

package/dist/esm/companion/zod-to-openapi.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc/companion (Zod helper)
+ *
+ * Single-purpose helper that converts a (possibly absent) Zod schema
+ * into a JSON Schema fragment suitable for splicing into an OpenAPI
+ * 3.1 `requestBody.content['application/json'].schema` or
+ * `responses.<status>.content['application/json'].schema` slot.
+ *
+ * # Why this lives in `engine/saas-technical-doc/src/companion/`
+ *
+ * The OpenAPI generator (`openapi-generator.ts`) consumes
+ * `OperationProjection.requestBodySchema` / `responseBodySchema` as
+ * opaque `unknown` values that get spliced verbatim into the emitted
+ * YAML. The conversion from Zod schema → JSON Schema MUST happen
+ * before the projection is handed to the generator (the generator is
+ * decorator-framework-free and intentionally does not depend on the
+ * caller's Zod runtime).
+ *
+ * Today every companion behavior that builds an
+ * `OpenApiGenerationInput` re-implements this conversion inline. Two
+ * problems:
+ *
+ *   1. Future companion behaviors (e.g. a per-route schema-export
+ *      command, an SDK-codegen pre-pass, a "show this resource's
+ *      DTO" debug endpoint) would copy the same five lines of
+ *      `z.toJSONSchema(...)` boilerplate, forking the trade-off
+ *      decisions (`null` semantics for absent schemas, `unknown`
+ *      return type, throw-vs-swallow on conversion failure).
+ *
+ *   2. The wonder-todos behavior currently buries the helper as a
+ *      `function` declaration after 300 lines of unrelated projector
+ *      logic — discoverable only by grepping `toJSONSchema` across
+ *      the workspace.
+ *
+ * Promoting the helper to the engine companion subpath gives every
+ * future caller one stable import (
+ * `import { convertZodSchemaToOpenApiSchema } from
+ * '@wildo-ai/saas-technical-doc/companion'`), a single JSDoc
+ * authority on the conversion contract, and a unit-tested surface
+ * the generator's own tests can rely on indirectly.
+ *
+ * # Why we don't import from `@wildo-ai/saas-models`
+ *
+ * Same K-3 boundary the rest of `companion/` honors: the helper
+ * imports from `'zod'` directly (the runtime the user app already
+ * brings via its DTOs) and never touches `@wildo-ai/saas-models`'s
+ * decorator-bootstrapping root barrel.
+ *
+ * @wildo-boundary
+ *   This file imports ONLY from `zod` — no React, no
+ *   `@wildo-ai/saas-models`, no decorator framework. Mirrors the
+ *   boundary contract of `operation-projection.schemas.ts`.
+ */
+import { z } from 'zod';
+/**
+ * Sentinel returned when no schema is present. The OpenAPI generator
+ * inspects for `null` to decide whether to omit the `requestBody`
+ * block entirely or emit a `204 No Content`-style response — see
+ * `openapi-generator.ts` for the consumption rules. Promoting this
+ * to a typed null (rather than `undefined`) makes the absence
+ * semantics explicit at the wire format and survives the JSON
+ * round-trip the introspection subprocess does on the way to the
+ * parent companion process.
+ */
+export type OpenApiSchemaFragmentOrNull = unknown | null;
+export declare const convertZodSchemaToOpenApiSchema: (schema: z.ZodSchema<unknown> | undefined) => OpenApiSchemaFragmentOrNull;
+//# sourceMappingURL=zod-to-openapi.d.ts.map

package/dist/esm/companion/zod-to-openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-openapi.d.ts","sourceRoot":"","sources":["../../../../src/companion/zod-to-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,IAAI,CAAC;AA4GzD,eAAO,MAAM,+BAA+B,GAC1C,QAAQ,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,SAAS,KACvC,2BAqDF,CAAC"}

package/dist/esm/companion/zod-to-openapi.js

@@ -0,0 +1,211 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc/companion (Zod helper)
+ *
+ * Single-purpose helper that converts a (possibly absent) Zod schema
+ * into a JSON Schema fragment suitable for splicing into an OpenAPI
+ * 3.1 `requestBody.content['application/json'].schema` or
+ * `responses.<status>.content['application/json'].schema` slot.
+ *
+ * # Why this lives in `engine/saas-technical-doc/src/companion/`
+ *
+ * The OpenAPI generator (`openapi-generator.ts`) consumes
+ * `OperationProjection.requestBodySchema` / `responseBodySchema` as
+ * opaque `unknown` values that get spliced verbatim into the emitted
+ * YAML. The conversion from Zod schema → JSON Schema MUST happen
+ * before the projection is handed to the generator (the generator is
+ * decorator-framework-free and intentionally does not depend on the
+ * caller's Zod runtime).
+ *
+ * Today every companion behavior that builds an
+ * `OpenApiGenerationInput` re-implements this conversion inline. Two
+ * problems:
+ *
+ *   1. Future companion behaviors (e.g. a per-route schema-export
+ *      command, an SDK-codegen pre-pass, a "show this resource's
+ *      DTO" debug endpoint) would copy the same five lines of
+ *      `z.toJSONSchema(...)` boilerplate, forking the trade-off
+ *      decisions (`null` semantics for absent schemas, `unknown`
+ *      return type, throw-vs-swallow on conversion failure).
+ *
+ *   2. The wonder-todos behavior currently buries the helper as a
+ *      `function` declaration after 300 lines of unrelated projector
+ *      logic — discoverable only by grepping `toJSONSchema` across
+ *      the workspace.
+ *
+ * Promoting the helper to the engine companion subpath gives every
+ * future caller one stable import (
+ * `import { convertZodSchemaToOpenApiSchema } from
+ * '@wildo-ai/saas-technical-doc/companion'`), a single JSDoc
+ * authority on the conversion contract, and a unit-tested surface
+ * the generator's own tests can rely on indirectly.
+ *
+ * # Why we don't import from `@wildo-ai/saas-models`
+ *
+ * Same K-3 boundary the rest of `companion/` honors: the helper
+ * imports from `'zod'` directly (the runtime the user app already
+ * brings via its DTOs) and never touches `@wildo-ai/saas-models`'s
+ * decorator-bootstrapping root barrel.
+ *
+ * @wildo-boundary
+ *   This file imports ONLY from `zod` — no React, no
+ *   `@wildo-ai/saas-models`, no decorator framework. Mirrors the
+ *   boundary contract of `operation-projection.schemas.ts`.
+ */
+import { z } from 'zod';
+/**
+ * Convert an optional Zod schema into a JSON Schema fragment via
+ * Zod 4's native `z.toJSONSchema()` API.
+ *
+ * # Contract
+ *
+ *   - `undefined` input → `null` output. Use this branch for "no
+ *     body" / "no response payload" semantics. The OpenAPI generator
+ *     omits the corresponding block.
+ *   - Non-`undefined` input → result of `z.toJSONSchema(schema)`.
+ *     Even an empty `z.object({})` produces a defined fragment;
+ *     callers that want to express "empty object body" should pass
+ *     the empty object schema explicitly.
+ *
+ * # Date handling
+ *
+ * `Date` has no native JSON Schema / OpenAPI 3.1 type, so Zod 4's
+ * `z.toJSONSchema()` throws on it by default (`"Date cannot be
+ * represented in JSON Schema"`). Resource DTOs are full of date fields
+ * (`createdAt`, `updatedAt`, `dueDate`, …), so the default behavior
+ * makes OpenAPI generation impossible for any realistic app. We map
+ * `Date` to its honest on-the-wire form — an ISO-8601 `string` with
+ * `format: 'date-time'` — via the `override` hook below.
+ *
+ * # Default handling (dynamic date defaults are dropped)
+ *
+ * The framework stamps audit fields with `z.date().default(() => new Date())`
+ * (`createdAt` / `updatedAt` on essentially every resource). `z.toJSONSchema()`
+ * serialises ONE evaluation of that default into the JSON-Schema `default:`
+ * keyword — and because Zod's `def.defaultValue` is a getter that RE-INVOKES
+ * `() => new Date()` on every read, each per-operation conversion bakes a
+ * DIFFERENT "now" into the docs. That is wrong on two counts, so the `override`
+ * hook strips it (leaving the honest `string` / `date-time` shape intact):
+ *
+ *   1. **Determinism.** Volatile timestamps break byte-stable regeneration —
+ *      the generator's K-4 contract (`openapi-generator.ts`): unchanged input
+ *      ⇒ byte-identical YAML. Without the strip, dozens of `default:` values
+ *      churn on every publish.
+ *   2. **Semantics.** These fields are `.excludeFromCreate().excludeFromUpdate()`
+ *      (server-populated, never client-supplied), so a documented `default:` is
+ *      meaningless on a request body (the field is absent) and on a response
+ *      body (the server always sends a real value). A "now" default is a
+ *      write-time server stamp, not a client-facing API constant.
+ *
+ * The strip is keyed on the RESOLVED default VALUE being a `Date` (not the
+ * inner Zod type) so every wrapper ordering is covered (`.default()`,
+ * `.optional().default()`, `.nullable().default()`, `.min(...).default()` all
+ * resolve to a Date). STATIC / stable defaults — `'draft'`, `0`, a
+ * fresh-container `() => ({})` — are documentable constants and are preserved.
+ *
+ * # Failure mode
+ *
+ * Mapping `Date` requires `unrepresentable: 'any'` (Zod's
+ * `unrepresentable` flag is global, and the `override` hook runs only
+ * AFTER the per-node processor, so with the default `'throw'` the date
+ * node throws before the override can rewrite it). `'any'` would
+ * otherwise let EVERY unrepresentable type silently degrade to an open
+ * `{}` schema — exactly the "silently-partial OpenAPI doc" this helper
+ * was written to avoid. So the override RE-IMPOSES fail-loud for the
+ * genuinely non-serialisable Zod types (raw transforms, symbols,
+ * functions, maps, sets, bigints, …) — see
+ * `UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES`. The throw propagates verbatim
+ * so the companion HTTP response surfaces the real failure (which
+ * resource / operation / DTO) instead of producing a partial document.
+ *
+ * # Why this helper exists rather than inlining `z.toJSONSchema`
+ *
+ * Three reasons:
+ *
+ *   1. Encodes the `undefined → null` mapping that the
+ *      `OperationProjectionSchema` wire format requires (the schema
+ *      types `requestBodySchema` / `responseBodySchema` as
+ *      `z.unknown().nullable()` — a stray `undefined` would fail the
+ *      Zod parse on the parent process side after the JSON
+ *      round-trip drops the field entirely).
+ *   2. Returns the `unknown` type the projection contract uses,
+ *      saving every caller from a redundant cast.
+ *   3. Provides a single doc anchor for future "what does the
+ *      generator do with this output" questions — search-discoverable
+ *      by helper name rather than spread across copies of
+ *      `z.toJSONSchema(...)` in every companion behavior.
+ */
+/**
+ * Zod `def.type` values that have NO honest OpenAPI 3.1 representation
+ * and must therefore fail loud rather than degrade to an open `{}`
+ * schema.
+ *
+ * Keyed by `def.type` — the same discriminant `z.toJSONSchema()`
+ * dispatches on internally (`ctx.processors[def.type]`). `date` and
+ * `bigint` are deliberately ABSENT: both ARE representable on the wire
+ * (`date` → ISO-8601 `string`; `bigint` → 64-bit `integer`, the shape
+ * `z_money` amounts use) and are remapped in the `override` hook. If a
+ * future Zod release adds a new unrepresentable type, add its `def.type`
+ * here in the same change so generation keeps failing loud on it.
+ */
+const UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES = new Set([
+    'symbol',
+    'undefined',
+    'void',
+    'custom',
+    'function',
+    'transform',
+    'map',
+    'set',
+]);
+export const convertZodSchemaToOpenApiSchema = (schema) => {
+    if (!schema)
+        return null;
+    return z.toJSONSchema(schema, {
+        // `'any'` suppresses the built-in throw for unrepresentable types
+        // so the `override` below can remap `Date` → `string`/`date-time`.
+        // Fail-loud for the genuinely non-serialisable types is re-imposed
+        // in the override (see UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES).
+        unrepresentable: 'any',
+        override: (ctx) => {
+            const def = ctx.zodSchema._zod.def;
+            const defType = def.type;
+            if (defType === 'date') {
+                ctx.jsonSchema.type = 'string';
+                ctx.jsonSchema.format = 'date-time';
+                return;
+            }
+            // Drop a dynamic date default (`z.date().default(() => new Date())`) — a
+            // write-time server stamp that `z.toJSONSchema()` bakes as a volatile
+            // "now" into `default:`, breaking byte-stable regeneration and misdocu-
+            // menting a server-populated field. Keyed on the RESOLVED value being a
+            // `Date` so every wrapper ordering is covered; static / stable defaults
+            // (`'draft'`, `0`, `() => ({})`) are preserved. See the "# Default
+            // handling" section on this helper for the full rationale.
+            if (defType === 'default'
+                && 'default' in ctx.jsonSchema
+                && def.defaultValue instanceof Date) {
+                delete ctx.jsonSchema.default;
+                return;
+            }
+            if (defType === 'bigint') {
+                // `bigint` is the framework's money/large-integer storage type
+                // (`z_money` amounts are minor-unit cents as bigint). It IS
+                // representable: a 64-bit integer. `format: 'int64'` is the OpenAPI
+                // convention for a value that may exceed JS Number safe-integer range
+                // and is therefore frequently string-encoded on the wire — codegen
+                // tooling handles int64 specially. Honest, and never an open `{}`.
+                ctx.jsonSchema.type = 'integer';
+                ctx.jsonSchema.format = 'int64';
+                return;
+            }
+            if (UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES.has(defType)) {
+                const where = ctx.path.length > 0 ? ctx.path.join('.') : '<root>';
+                throw new Error(`convertZodSchemaToOpenApiSchema: Zod type "${defType}" at "${where}" has no `
+                    + 'OpenAPI 3.1 representation. Expose a serialisable shape on the operation DTO, '
+                    + 'or exclude the field from the API surface — emitting an open "{}" schema here '
+                    + 'would silently ship a misleading API document.');
+            }
+        },
+    });
+};
+//# sourceMappingURL=zod-to-openapi.js.map

package/dist/esm/companion/zod-to-openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-openapi.js","sourceRoot":"","sources":["../../../../src/companion/zod-to-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,mCAAmC,GAAwB,IAAI,GAAG,CAAC;IACvE,QAAQ;IACR,WAAW;IACX,MAAM;IACN,QAAQ;IACR,UAAU;IACV,WAAW;IACX,KAAK;IACL,KAAK;CACN,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAC7C,MAAwC,EACX,EAAE;IAC/B,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE;QAC5B,kEAAkE;QAClE,mEAAmE;QACnE,mEAAmE;QACnE,6DAA6D;QAC7D,eAAe,EAAE,KAAK;QACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;YAChB,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;YACnC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC;YACzB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;gBACvB,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,QAAQ,CAAC;gBAC/B,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,WAAW,CAAC;gBACpC,OAAO;YACT,CAAC;YACD,yEAAyE;YACzE,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,wEAAwE;YACxE,mEAAmE;YACnE,2DAA2D;YAC3D,IACE,OAAO,KAAK,SAAS;mBAClB,SAAS,IAAI,GAAG,CAAC,UAAU;mBAC1B,GAAkC,CAAC,YAAY,YAAY,IAAI,EACnE,CAAC;gBACD,OAAO,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACzB,+DAA+D;gBAC/D,4DAA4D;gBAC5D,oEAAoE;gBACpE,sEAAsE;gBACtE,mEAAmE;gBACnE,mEAAmE;gBACnE,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,SAAS,CAAC;gBAChC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,OAAO,CAAC;gBAChC,OAAO;YACT,CAAC;YACD,IAAI,mCAAmC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAClE,MAAM,IAAI,KAAK,CACb,8CAA8C,OAAO,SAAS,KAAK,WAAW;sBAC5E,gFAAgF;sBAChF,gFAAgF;sBAChF,gDAAgD,CACnD,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["/**\n * @wildo-package @wildo-ai/saas-technical-doc/companion (Zod helper)\n *\n * Single-purpose helper that converts a (possibly absent) Zod schema\n * into a JSON Schema fragment suitable for splicing into an OpenAPI\n * 3.1 `requestBody.content['application/json'].schema` or\n * `responses.<status>.content['application/json'].schema` slot.\n *\n * # Why this lives in `engine/saas-technical-doc/src/companion/`\n *\n * The OpenAPI generator (`openapi-generator.ts`) consumes\n * `OperationProjection.requestBodySchema` / `responseBodySchema` as\n * opaque `unknown` values that get spliced verbatim into the emitted\n * YAML. The conversion from Zod schema → JSON Schema MUST happen\n * before the projection is handed to the generator (the generator is\n * decorator-framework-free and intentionally does not depend on the\n * caller's Zod runtime).\n *\n * Today every companion behavior that builds an\n * `OpenApiGenerationInput` re-implements this conversion inline. Two\n * problems:\n *\n *   1. Future companion behaviors (e.g. a per-route schema-export\n *      command, an SDK-codegen pre-pass, a \"show this resource's\n *      DTO\" debug endpoint) would copy the same five lines of\n *      `z.toJSONSchema(...)` boilerplate, forking the trade-off\n *      decisions (`null` semantics for absent schemas, `unknown`\n *      return type, throw-vs-swallow on conversion failure).\n *\n *   2. The wonder-todos behavior currently buries the helper as a\n *      `function` declaration after 300 lines of unrelated projector\n *      logic — discoverable only by grepping `toJSONSchema` across\n *      the workspace.\n *\n * Promoting the helper to the engine companion subpath gives every\n * future caller one stable import (\n * `import { convertZodSchemaToOpenApiSchema } from\n * '@wildo-ai/saas-technical-doc/companion'`), a single JSDoc\n * authority on the conversion contract, and a unit-tested surface\n * the generator's own tests can rely on indirectly.\n *\n * # Why we don't import from `@wildo-ai/saas-models`\n *\n * Same K-3 boundary the rest of `companion/` honors: the helper\n * imports from `'zod'` directly (the runtime the user app already\n * brings via its DTOs) and never touches `@wildo-ai/saas-models`'s\n * decorator-bootstrapping root barrel.\n *\n * @wildo-boundary\n *   This file imports ONLY from `zod` — no React, no\n *   `@wildo-ai/saas-models`, no decorator framework. Mirrors the\n *   boundary contract of `operation-projection.schemas.ts`.\n */\n\nimport { z } from 'zod';\n\n/**\n * Sentinel returned when no schema is present. The OpenAPI generator\n * inspects for `null` to decide whether to omit the `requestBody`\n * block entirely or emit a `204 No Content`-style response — see\n * `openapi-generator.ts` for the consumption rules. Promoting this\n * to a typed null (rather than `undefined`) makes the absence\n * semantics explicit at the wire format and survives the JSON\n * round-trip the introspection subprocess does on the way to the\n * parent companion process.\n */\nexport type OpenApiSchemaFragmentOrNull = unknown | null;\n\n/**\n * Convert an optional Zod schema into a JSON Schema fragment via\n * Zod 4's native `z.toJSONSchema()` API.\n *\n * # Contract\n *\n *   - `undefined` input → `null` output. Use this branch for \"no\n *     body\" / \"no response payload\" semantics. The OpenAPI generator\n *     omits the corresponding block.\n *   - Non-`undefined` input → result of `z.toJSONSchema(schema)`.\n *     Even an empty `z.object({})` produces a defined fragment;\n *     callers that want to express \"empty object body\" should pass\n *     the empty object schema explicitly.\n *\n * # Date handling\n *\n * `Date` has no native JSON Schema / OpenAPI 3.1 type, so Zod 4's\n * `z.toJSONSchema()` throws on it by default (`\"Date cannot be\n * represented in JSON Schema\"`). Resource DTOs are full of date fields\n * (`createdAt`, `updatedAt`, `dueDate`, …), so the default behavior\n * makes OpenAPI generation impossible for any realistic app. We map\n * `Date` to its honest on-the-wire form — an ISO-8601 `string` with\n * `format: 'date-time'` — via the `override` hook below.\n *\n * # Default handling (dynamic date defaults are dropped)\n *\n * The framework stamps audit fields with `z.date().default(() => new Date())`\n * (`createdAt` / `updatedAt` on essentially every resource). `z.toJSONSchema()`\n * serialises ONE evaluation of that default into the JSON-Schema `default:`\n * keyword — and because Zod's `def.defaultValue` is a getter that RE-INVOKES\n * `() => new Date()` on every read, each per-operation conversion bakes a\n * DIFFERENT \"now\" into the docs. That is wrong on two counts, so the `override`\n * hook strips it (leaving the honest `string` / `date-time` shape intact):\n *\n *   1. **Determinism.** Volatile timestamps break byte-stable regeneration —\n *      the generator's K-4 contract (`openapi-generator.ts`): unchanged input\n *      ⇒ byte-identical YAML. Without the strip, dozens of `default:` values\n *      churn on every publish.\n *   2. **Semantics.** These fields are `.excludeFromCreate().excludeFromUpdate()`\n *      (server-populated, never client-supplied), so a documented `default:` is\n *      meaningless on a request body (the field is absent) and on a response\n *      body (the server always sends a real value). A \"now\" default is a\n *      write-time server stamp, not a client-facing API constant.\n *\n * The strip is keyed on the RESOLVED default VALUE being a `Date` (not the\n * inner Zod type) so every wrapper ordering is covered (`.default()`,\n * `.optional().default()`, `.nullable().default()`, `.min(...).default()` all\n * resolve to a Date). STATIC / stable defaults — `'draft'`, `0`, a\n * fresh-container `() => ({})` — are documentable constants and are preserved.\n *\n * # Failure mode\n *\n * Mapping `Date` requires `unrepresentable: 'any'` (Zod's\n * `unrepresentable` flag is global, and the `override` hook runs only\n * AFTER the per-node processor, so with the default `'throw'` the date\n * node throws before the override can rewrite it). `'any'` would\n * otherwise let EVERY unrepresentable type silently degrade to an open\n * `{}` schema — exactly the \"silently-partial OpenAPI doc\" this helper\n * was written to avoid. So the override RE-IMPOSES fail-loud for the\n * genuinely non-serialisable Zod types (raw transforms, symbols,\n * functions, maps, sets, bigints, …) — see\n * `UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES`. The throw propagates verbatim\n * so the companion HTTP response surfaces the real failure (which\n * resource / operation / DTO) instead of producing a partial document.\n *\n * # Why this helper exists rather than inlining `z.toJSONSchema`\n *\n * Three reasons:\n *\n *   1. Encodes the `undefined → null` mapping that the\n *      `OperationProjectionSchema` wire format requires (the schema\n *      types `requestBodySchema` / `responseBodySchema` as\n *      `z.unknown().nullable()` — a stray `undefined` would fail the\n *      Zod parse on the parent process side after the JSON\n *      round-trip drops the field entirely).\n *   2. Returns the `unknown` type the projection contract uses,\n *      saving every caller from a redundant cast.\n *   3. Provides a single doc anchor for future \"what does the\n *      generator do with this output\" questions — search-discoverable\n *      by helper name rather than spread across copies of\n *      `z.toJSONSchema(...)` in every companion behavior.\n */\n/**\n * Zod `def.type` values that have NO honest OpenAPI 3.1 representation\n * and must therefore fail loud rather than degrade to an open `{}`\n * schema.\n *\n * Keyed by `def.type` — the same discriminant `z.toJSONSchema()`\n * dispatches on internally (`ctx.processors[def.type]`). `date` and\n * `bigint` are deliberately ABSENT: both ARE representable on the wire\n * (`date` → ISO-8601 `string`; `bigint` → 64-bit `integer`, the shape\n * `z_money` amounts use) and are remapped in the `override` hook. If a\n * future Zod release adds a new unrepresentable type, add its `def.type`\n * here in the same change so generation keeps failing loud on it.\n */\nconst UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES: ReadonlySet<string> = new Set([\n  'symbol',\n  'undefined',\n  'void',\n  'custom',\n  'function',\n  'transform',\n  'map',\n  'set',\n]);\n\nexport const convertZodSchemaToOpenApiSchema = (\n  schema: z.ZodSchema<unknown> | undefined,\n): OpenApiSchemaFragmentOrNull => {\n  if (!schema) return null;\n  return z.toJSONSchema(schema, {\n    // `'any'` suppresses the built-in throw for unrepresentable types\n    // so the `override` below can remap `Date` → `string`/`date-time`.\n    // Fail-loud for the genuinely non-serialisable types is re-imposed\n    // in the override (see UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES).\n    unrepresentable: 'any',\n    override: (ctx) => {\n      const def = ctx.zodSchema._zod.def;\n      const defType = def.type;\n      if (defType === 'date') {\n        ctx.jsonSchema.type = 'string';\n        ctx.jsonSchema.format = 'date-time';\n        return;\n      }\n      // Drop a dynamic date default (`z.date().default(() => new Date())`) — a\n      // write-time server stamp that `z.toJSONSchema()` bakes as a volatile\n      // \"now\" into `default:`, breaking byte-stable regeneration and misdocu-\n      // menting a server-populated field. Keyed on the RESOLVED value being a\n      // `Date` so every wrapper ordering is covered; static / stable defaults\n      // (`'draft'`, `0`, `() => ({})`) are preserved. See the \"# Default\n      // handling\" section on this helper for the full rationale.\n      if (\n        defType === 'default'\n        && 'default' in ctx.jsonSchema\n        && (def as { defaultValue?: unknown }).defaultValue instanceof Date\n      ) {\n        delete ctx.jsonSchema.default;\n        return;\n      }\n      if (defType === 'bigint') {\n        // `bigint` is the framework's money/large-integer storage type\n        // (`z_money` amounts are minor-unit cents as bigint). It IS\n        // representable: a 64-bit integer. `format: 'int64'` is the OpenAPI\n        // convention for a value that may exceed JS Number safe-integer range\n        // and is therefore frequently string-encoded on the wire — codegen\n        // tooling handles int64 specially. Honest, and never an open `{}`.\n        ctx.jsonSchema.type = 'integer';\n        ctx.jsonSchema.format = 'int64';\n        return;\n      }\n      if (UNREPRESENTABLE_FAIL_LOUD_DEF_TYPES.has(defType)) {\n        const where = ctx.path.length > 0 ? ctx.path.join('.') : '<root>';\n        throw new Error(\n          `convertZodSchemaToOpenApiSchema: Zod type \"${defType}\" at \"${where}\" has no `\n          + 'OpenAPI 3.1 representation. Expose a serialisable shape on the operation DTO, '\n          + 'or exclude the field from the API surface — emitting an open \"{}\" schema here '\n          + 'would silently ship a misleading API document.',\n        );\n      }\n    },\n  });\n};\n"]}

package/dist/esm/companion-exports.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc (companion entry)
+ *
+ * Narrow, React-free entry point for companion-side OpenAPI generation and
+ * exact engine-owned application-consumer documentation content.
+ * Consumed by:
+ *   - `examples/<app>/.wildo-saas/wildo-dev-companion/` companion controllers
+ *     that walk the app's resource definitions and emit
+ *     the normal and application-administration YAML/JSON OpenAPI documents.
+ *
+ * @wildo-boundary
+ *   This file MUST re-export ONLY from `./companion/**` and the shared
+ *   schemas under `./openapi/**`.
+ *   It MUST NOT import or re-export anything from:
+ *     - `./runtime/**` (React + DOM + fetch — browser-only).
+ *   It MUST NOT import React or `react-dom`.
+ *
+ *   Enforced by review until a programmatic boundary lint lands (cf.
+ *   the equivalent rule in `engine/saas-website/src/companion-exports.ts`).
+ *
+ * The companion surface ships
+ * `OperationProjectionSchema` (input contract), `OpenApiGenerationInputSchema`
+ * (top-level wire format), and the pure-function `generateOpenApiDocuments`
+ * entry point that produces the `OpenApiGenerationOutput` declared in
+ * `./openapi/`. It also ships the verified application-consumer content
+ * loader and the reusable framework projection/rendering pipeline. Reusable
+ * authored content and its portable identity contracts live behind `./content`;
+ * the browser runtime remains isolated behind `./runtime`.
+ */
+export * from './openapi/index';
+export * from './companion/index';
+//# sourceMappingURL=companion-exports.d.ts.map

package/dist/esm/companion-exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-exports.d.ts","sourceRoot":"","sources":["../../../src/companion-exports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/esm/companion-exports.js

@@ -0,0 +1,32 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc (companion entry)
+ *
+ * Narrow, React-free entry point for companion-side OpenAPI generation and
+ * exact engine-owned application-consumer documentation content.
+ * Consumed by:
+ *   - `examples/<app>/.wildo-saas/wildo-dev-companion/` companion controllers
+ *     that walk the app's resource definitions and emit
+ *     the normal and application-administration YAML/JSON OpenAPI documents.
+ *
+ * @wildo-boundary
+ *   This file MUST re-export ONLY from `./companion/**` and the shared
+ *   schemas under `./openapi/**`.
+ *   It MUST NOT import or re-export anything from:
+ *     - `./runtime/**` (React + DOM + fetch — browser-only).
+ *   It MUST NOT import React or `react-dom`.
+ *
+ *   Enforced by review until a programmatic boundary lint lands (cf.
+ *   the equivalent rule in `engine/saas-website/src/companion-exports.ts`).
+ *
+ * The companion surface ships
+ * `OperationProjectionSchema` (input contract), `OpenApiGenerationInputSchema`
+ * (top-level wire format), and the pure-function `generateOpenApiDocuments`
+ * entry point that produces the `OpenApiGenerationOutput` declared in
+ * `./openapi/`. It also ships the verified application-consumer content
+ * loader and the reusable framework projection/rendering pipeline. Reusable
+ * authored content and its portable identity contracts live behind `./content`;
+ * the browser runtime remains isolated behind `./runtime`.
+ */
+export * from './openapi/index.js';
+export * from './companion/index.js';
+//# sourceMappingURL=companion-exports.js.map

package/dist/esm/companion-exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-exports.js","sourceRoot":"","sources":["../../../src/companion-exports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC","sourcesContent":["/**\n * @wildo-package @wildo-ai/saas-technical-doc (companion entry)\n *\n * Narrow, React-free entry point for companion-side OpenAPI generation and\n * exact engine-owned application-consumer documentation content.\n * Consumed by:\n *   - `examples/<app>/.wildo-saas/wildo-dev-companion/` companion controllers\n *     that walk the app's resource definitions and emit\n *     the normal and application-administration YAML/JSON OpenAPI documents.\n *\n * @wildo-boundary\n *   This file MUST re-export ONLY from `./companion/**` and the shared\n *   schemas under `./openapi/**`.\n *   It MUST NOT import or re-export anything from:\n *     - `./runtime/**` (React + DOM + fetch — browser-only).\n *   It MUST NOT import React or `react-dom`.\n *\n *   Enforced by review until a programmatic boundary lint lands (cf.\n *   the equivalent rule in `engine/saas-website/src/companion-exports.ts`).\n *\n * The companion surface ships\n * `OperationProjectionSchema` (input contract), `OpenApiGenerationInputSchema`\n * (top-level wire format), and the pure-function `generateOpenApiDocuments`\n * entry point that produces the `OpenApiGenerationOutput` declared in\n * `./openapi/`. It also ships the verified application-consumer content\n * loader and the reusable framework projection/rendering pipeline. Reusable\n * authored content and its portable identity contracts live behind `./content`;\n * the browser runtime remains isolated behind `./runtime`.\n */\n\nexport * from './openapi/index';\nexport * from './companion/index';\n"]}

package/dist/esm/config/define-tech-doc-config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Author helper for `wildo.tech-doc.config.ts` files.
+ *
+ * `defineTechnicalDocConfig({...})` mirrors the `defineSaasConfig` /
+ * `defineInfraEnvConfig` helpers from `@wildo-ai/platform-config-lib`:
+ * it wraps `WildoTechnicalDocConfigSchema.parse(...)` with full IDE
+ * autocompletion on the input shape and runs Zod validation
+ * (fail-closed on typos / unknown keys / out-of-range values).
+ *
+ * As of `auth-hardening.md` Slice B B-Step 1 + B-Step 3 (shipped
+ * 2026-04-19), every documented field on `WildoTechnicalDocConfig`
+ * has a real runtime consumer (`csp?` flows through the build-time
+ * generator at `platform-config-lib/src/project-config/shared/csp-emit.ts`).
+ * The previous `@unimplemented` warner was retired in the same commit;
+ * if a future field lands here without a consumer, re-introduce the
+ * warner pattern from the git history of this file (commits before
+ * the Slice B B-Step 1 landing).
+ */
+import { type WildoTechnicalDocConfig, type WildoTechnicalDocConfigInput } from './wildo-tech-doc-config.schemas';
+/**
+ * Define a per-service technical-documentation config. Provides full
+ * IDE autocompletion on the input shape and runs Zod validation
+ * (fail-closed on typos / unknown keys / out-of-range values).
+ *
+ * Throws on validation failure — same contract as `defineSaasConfig`.
+ *
+ * @example
+ * ```ts
+ * import { defineTechnicalDocConfig } from '@wildo-ai/saas-technical-doc';
+ *
+ * export default defineTechnicalDocConfig({
+ *   supportedApiVersion: '1.0.0',
+ *   publicMarketingTitle: 'Wonder Todos — Technical Documentation',
+ * });
+ * ```
+ */
+export declare function defineTechnicalDocConfig(config: WildoTechnicalDocConfigInput): WildoTechnicalDocConfig;
+//# sourceMappingURL=define-tech-doc-config.d.ts.map

package/dist/esm/config/define-tech-doc-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tech-doc-config.d.ts","sourceRoot":"","sources":["../../../../src/config/define-tech-doc-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EAClC,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,4BAA4B,GACnC,uBAAuB,CAEzB"}

package/dist/esm/config/define-tech-doc-config.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Author helper for `wildo.tech-doc.config.ts` files.
+ *
+ * `defineTechnicalDocConfig({...})` mirrors the `defineSaasConfig` /
+ * `defineInfraEnvConfig` helpers from `@wildo-ai/platform-config-lib`:
+ * it wraps `WildoTechnicalDocConfigSchema.parse(...)` with full IDE
+ * autocompletion on the input shape and runs Zod validation
+ * (fail-closed on typos / unknown keys / out-of-range values).
+ *
+ * As of `auth-hardening.md` Slice B B-Step 1 + B-Step 3 (shipped
+ * 2026-04-19), every documented field on `WildoTechnicalDocConfig`
+ * has a real runtime consumer (`csp?` flows through the build-time
+ * generator at `platform-config-lib/src/project-config/shared/csp-emit.ts`).
+ * The previous `@unimplemented` warner was retired in the same commit;
+ * if a future field lands here without a consumer, re-introduce the
+ * warner pattern from the git history of this file (commits before
+ * the Slice B B-Step 1 landing).
+ */
+import { WildoTechnicalDocConfigSchema, } from './wildo-tech-doc-config.schemas.js';
+/**
+ * Define a per-service technical-documentation config. Provides full
+ * IDE autocompletion on the input shape and runs Zod validation
+ * (fail-closed on typos / unknown keys / out-of-range values).
+ *
+ * Throws on validation failure — same contract as `defineSaasConfig`.
+ *
+ * @example
+ * ```ts
+ * import { defineTechnicalDocConfig } from '@wildo-ai/saas-technical-doc';
+ *
+ * export default defineTechnicalDocConfig({
+ *   supportedApiVersion: '1.0.0',
+ *   publicMarketingTitle: 'Wonder Todos — Technical Documentation',
+ * });
+ * ```
+ */
+export function defineTechnicalDocConfig(config) {
+    return WildoTechnicalDocConfigSchema.parse(config);
+}
+//# sourceMappingURL=define-tech-doc-config.js.map

package/dist/esm/config/define-tech-doc-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tech-doc-config.js","sourceRoot":"","sources":["../../../../src/config/define-tech-doc-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,6BAA6B,GAG9B,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAoC;IAEpC,OAAO,6BAA6B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC","sourcesContent":["/**\n * @fileoverview Author helper for `wildo.tech-doc.config.ts` files.\n *\n * `defineTechnicalDocConfig({...})` mirrors the `defineSaasConfig` /\n * `defineInfraEnvConfig` helpers from `@wildo-ai/platform-config-lib`:\n * it wraps `WildoTechnicalDocConfigSchema.parse(...)` with full IDE\n * autocompletion on the input shape and runs Zod validation\n * (fail-closed on typos / unknown keys / out-of-range values).\n *\n * As of `auth-hardening.md` Slice B B-Step 1 + B-Step 3 (shipped\n * 2026-04-19), every documented field on `WildoTechnicalDocConfig`\n * has a real runtime consumer (`csp?` flows through the build-time\n * generator at `platform-config-lib/src/project-config/shared/csp-emit.ts`).\n * The previous `@unimplemented` warner was retired in the same commit;\n * if a future field lands here without a consumer, re-introduce the\n * warner pattern from the git history of this file (commits before\n * the Slice B B-Step 1 landing).\n */\n\nimport {\n  WildoTechnicalDocConfigSchema,\n  type WildoTechnicalDocConfig,\n  type WildoTechnicalDocConfigInput,\n} from './wildo-tech-doc-config.schemas';\n\n/**\n * Define a per-service technical-documentation config. Provides full\n * IDE autocompletion on the input shape and runs Zod validation\n * (fail-closed on typos / unknown keys / out-of-range values).\n *\n * Throws on validation failure — same contract as `defineSaasConfig`.\n *\n * @example\n * ```ts\n * import { defineTechnicalDocConfig } from '@wildo-ai/saas-technical-doc';\n *\n * export default defineTechnicalDocConfig({\n *   supportedApiVersion: '1.0.0',\n *   publicMarketingTitle: 'Wonder Todos — Technical Documentation',\n * });\n * ```\n */\nexport function defineTechnicalDocConfig(\n  config: WildoTechnicalDocConfigInput,\n): WildoTechnicalDocConfig {\n  return WildoTechnicalDocConfigSchema.parse(config);\n}\n"]}

package/dist/esm/config/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@wildo-ai/saas-technical-doc` — config surface.
+ *
+ * Per-service `wildo.tech-doc.config.ts` schema + `defineTechnicalDocConfig`
+ * helper. Co-located with the engine package that owns the recipe
+ * registry + OpenAPI generator so a new base recipe ships in a single
+ * PR with no cross-package allow-list to keep in sync (see
+ * `wildo-tech-doc-config.schemas.ts` JSDoc for the architectural
+ * rationale behind moving this out of `platform-config-lib`).
+ *
+ * @wildo-boundary
+ *   This sub-tree is Node-side only (the `defineTechnicalDocConfig`
+ *   helper writes to `process.stderr` via the `@unimplemented`
+ *   warner). It MUST NOT be imported from `../runtime/**` or any
+ *   browser-bundled code path. The Docusaurus build at the app
+ *   level loads the per-service `wildo.tech-doc.config.ts` via the
+ *   companion or via a Node-side helper, NEVER from the rendered
+ *   docs bundle.
+ */
+export * from './define-tech-doc-config';
+export * from './wildo-tech-doc-config.schemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC"}

package/dist/esm/config/index.js

@@ -0,0 +1,22 @@
+/**
+ * `@wildo-ai/saas-technical-doc` — config surface.
+ *
+ * Per-service `wildo.tech-doc.config.ts` schema + `defineTechnicalDocConfig`
+ * helper. Co-located with the engine package that owns the recipe
+ * registry + OpenAPI generator so a new base recipe ships in a single
+ * PR with no cross-package allow-list to keep in sync (see
+ * `wildo-tech-doc-config.schemas.ts` JSDoc for the architectural
+ * rationale behind moving this out of `platform-config-lib`).
+ *
+ * @wildo-boundary
+ *   This sub-tree is Node-side only (the `defineTechnicalDocConfig`
+ *   helper writes to `process.stderr` via the `@unimplemented`
+ *   warner). It MUST NOT be imported from `../runtime/**` or any
+ *   browser-bundled code path. The Docusaurus build at the app
+ *   level loads the per-service `wildo.tech-doc.config.ts` via the
+ *   companion or via a Node-side helper, NEVER from the rendered
+ *   docs bundle.
+ */
+export * from './define-tech-doc-config.js';
+export * from './wildo-tech-doc-config.schemas.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC","sourcesContent":["/**\n * `@wildo-ai/saas-technical-doc` — config surface.\n *\n * Per-service `wildo.tech-doc.config.ts` schema + `defineTechnicalDocConfig`\n * helper. Co-located with the engine package that owns the recipe\n * registry + OpenAPI generator so a new base recipe ships in a single\n * PR with no cross-package allow-list to keep in sync (see\n * `wildo-tech-doc-config.schemas.ts` JSDoc for the architectural\n * rationale behind moving this out of `platform-config-lib`).\n *\n * @wildo-boundary\n *   This sub-tree is Node-side only (the `defineTechnicalDocConfig`\n *   helper writes to `process.stderr` via the `@unimplemented`\n *   warner). It MUST NOT be imported from `../runtime/**` or any\n *   browser-bundled code path. The Docusaurus build at the app\n *   level loads the per-service `wildo.tech-doc.config.ts` via the\n *   companion or via a Node-side helper, NEVER from the rendered\n *   docs bundle.\n */\n\nexport * from './define-tech-doc-config';\nexport * from './wildo-tech-doc-config.schemas';\n"]}