@deltabox/toolchain 1.11.4 → 2.0.0

package/dist/packages/config/src/config-json.d.ts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigScopes } from "./types.js";
-import { CollectEnvVarsOptions } from "./collect.js";
+import { ConfigSchema } from "./types.js";
+import { CollectVarsOptions } from "./collect.js";
 //#region packages/config/src/config-json.d.ts
 /** A serialized env var entry in `config.json`. */
 export interface ConfigJsonEntry {
@@ -26,8 +26,8 @@ export interface BuildConfigJsonOptions {
   /** Override the `$comment` banner. */
   comment?: string;
   /** Custom env-name -> dotted-path derivation. */
-  envPathOf?: CollectEnvVarsOptions['envPathOf'];
+  envPathOf?: CollectVarsOptions['envPathOf'];
 }
 /** Build the config metadata JSON document. */
-export declare function buildConfigJson(scopes: ConfigScopes, options?: BuildConfigJsonOptions): ConfigJsonDoc;
+export declare function buildConfigJson(schema: ConfigSchema, options?: BuildConfigJsonOptions): ConfigJsonDoc;
 //#endregion

package/dist/packages/config/src/config-json.js

@@ -1 +1 @@
-import"node:path";import"node:url";import.meta.url;import{collectEnvVars as e}from"./collect.js";function t(t,n={}){let r=e(t,n.envPrefix,{envPathOf:n.envPathOf});return{$comment:n.comment??`Generated from the config engine — edit the config schemas instead.`,version:1,env:r.map(e=>({name:e.name,path:e.path,scope:e.scope,...e.description?{description:e.description}:{},...e.default===void 0?{}:{default:e.default},...e.required?{required:!0}:{},...e.secret?{secret:!0}:{},...e.public?{public:!0}:{}}))}}export{t as buildConfigJson};
+import"node:path";import"node:url";import.meta.url;import{collectVars as e}from"./collect.js";function t(t,n={}){let r=e(t,n.envPrefix,{envPathOf:n.envPathOf}).filter(e=>e.name);return{$comment:n.comment??`Generated from the config engine — edit the config schemas instead.`,version:1,env:r.map(e=>({name:e.name??``,path:e.path,scope:e.scope,...e.description?{description:e.description}:{},...e.default===void 0?{}:{default:e.default},...e.required?{required:!0}:{},...e.secret?{secret:!0}:{},...e.public?{public:!0}:{}}))}}export{t as buildConfigJson};

package/dist/packages/config/src/engine.d.ts

@@ -1,6 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigEngineOptions, ConfigScopes, EnvVarDef } from "./types.js";
+import { ConfigDef, ConfigEngineOptions, ConfigSchema } from "./types.js";
 import { BuildConfigJsonOptions, ConfigJsonDoc } from "./config-json.js";
 import { EnvFileOptions } from "./env-file.js";
 import { CliOptionDef, GenerateCliOptionsOptions } from "./generators/cli.js";
@@ -9,48 +9,37 @@ import { GenerateJsonSchemaOptions } from "./generators/json.js";
 import { GenerateMarkdownOptions } from "./generators/markdown.js";
 import { GenerateTypesOptions } from "./generators/types.js";
 //#region packages/config/src/engine.d.ts
-/** The bound, reusable config engine. */
 export interface ConfigEngine {
-  readonly scopes: ConfigScopes;
+  readonly schema: ConfigSchema;
   readonly envPrefix: string;
   readonly baseGroup: string;
   readonly root: string;
-  /** Every env-var-backed leaf across the registered scopes. */
-  collectEnvVars(): EnvVarDef[];
-  /** The names of the required env vars for a scope. */
-  requiredEnvVars(scope: string): string[];
-  /** Render `.env` content. */
-  renderEnvFile(options?: EnvFileOptions): string;
-  /** Write a `.env` file. Returns the path written. */
-  writeEnvFile(options: EnvFileOptions & {
-    output: string;
-  }): string;
-  /** Build the config metadata JSON document. */
+  collectVars(): ConfigDef[];
+  requiredVars(scope?: string): ConfigDef[];
+  generateEnvFile(options?: EnvFileOptions): string;
   buildConfigJson(options?: BuildConfigJsonOptions): ConfigJsonDoc;
-  /** Build (and optionally write) the untyped JSON Schema document. */
   generateJsonSchema(options?: GenerateJsonSchemaOptions): Promise<Record<string, unknown>>;
-  /** Write the JSON Schema document. Returns the path written. */
   writeJsonSchema(options: GenerateJsonSchemaOptions & {
     output: string;
   }): Promise<string>;
-  /** Render every config type file, keyed by scope name. */
-  renderConfigTypes(options?: GenerateTypesOptions): Record<string, string>;
-  /** Write the config type files into `outputDir`. */
+  generateConfigTypes(options?: GenerateTypesOptions): Record<string, string>;
+  generateConfigEnv(options?: GenerateEnvTypesOptions): Record<string, string>;
+  generateConfigMarkdown(options?: GenerateMarkdownOptions): Record<string, string>;
+  generateConfigCli(options?: GenerateCliOptionsOptions): CliOptionDef[];
+  writeEnvFile(options: EnvFileOptions & {
+    output: string;
+  }): string;
   writeConfigTypes(options: GenerateTypesOptions & {
     outputDir: string;
   }): string[];
-  /** Write the env type files into `outputDir`. */
   writeEnvTypes(options: GenerateEnvTypesOptions & {
     outputDir: string;
   }): string[];
-  /** Write the markdown reference into `outDir`. */
   writeMarkdown(options: GenerateMarkdownOptions & {
-    outDir: string;
+    outputDir: string;
   }): string[];
-  /** Generate (and optionally write) the CLI option definitions. */
   generateCliOptions(options?: GenerateCliOptionsOptions): CliOptionDef[];
 }
-/** Create a reusable config engine. */
 export declare function createConfigEngine(options: ConfigEngineOptions): ConfigEngine;
 //#endregion
-export type { ConfigEngineOptions, ConfigScopes };
+export type { ConfigEngineOptions };

package/dist/packages/config/src/engine.js

@@ -1 +1 @@
-import{default as e}from"node:path";import"node:url";import.meta.url;import{collectEnvVars as t,collectRequiredEnvVars as n}from"./collect.js";import{buildConfigJson as r}from"./config-json.js";import{generateEnvFile as i}from"./env-file.js";import{generateCliOptions as a}from"./generators/cli.js";import{generateEnvTypes as o}from"./generators/env.js";import{generateConfigJsonSchema as s,generateJsonSchemaFile as c}from"./generators/json.js";import{generateConfigMarkdown as l}from"./generators/markdown.js";import{generateConfigTypes as u,renderAllConfigTypes as d}from"./generators/types.js";import{findProjectRoot as f}from"./root.js";import p from"node:fs";function m(m){let h=m.scopes,g=m.envPrefix??`APP_`,_=m.baseGroup??`base`,v=m.root??f(),y=m.envPathOf;return{scopes:h,envPrefix:g,baseGroup:_,root:v,collectEnvVars:()=>t(h,g,{envPathOf:y}),requiredEnvVars:e=>n(h,e,g,{envPathOf:y}),renderEnvFile:(e={})=>i(h,{envPrefix:g,envPathOf:y,...e}),writeEnvFile:t=>{let n=i(h,{envPrefix:g,envPathOf:y,...t});return p.mkdirSync(e.dirname(t.output),{recursive:!0}),p.writeFileSync(t.output,n,`utf-8`),t.output},buildConfigJson:(e={})=>r(h,{envPrefix:g,envPathOf:y,...e}),generateJsonSchema:(e={})=>s(h,{baseGroup:_,...e}),writeJsonSchema:e=>c(h,{baseGroup:_,...e}),renderConfigTypes:(e={})=>d(h,{baseGroup:_,...e}),writeConfigTypes:e=>u(h,{baseGroup:_,...e}),writeEnvTypes:e=>o(h,{envPrefix:g,envPathOf:y,...e}),writeMarkdown:e=>l(h,{baseGroup:_,envPrefix:g,envPathOf:y,...e}),generateCliOptions:(e={})=>a(h,{envPrefix:g,envPathOf:y,...e})}}export{m as createConfigEngine};
+import{default as e}from"node:path";import"node:url";import.meta.url;import{collectVars as t}from"./collect.js";import{buildConfigJson as n}from"./config-json.js";import{generateEnvFile as r}from"./env-file.js";import{generateCliOptions as i}from"./generators/cli.js";import{generateConfigEnv as a}from"./generators/env.js";import{generateConfigJsonSchema as o,generateJsonSchemaFile as s}from"./generators/json.js";import{generateConfigMarkdown as c}from"./generators/markdown.js";import{generateConfigTypes as l}from"./generators/types.js";import{findProjectRoot as u}from"./root.js";import d from"node:fs";function f(f){let p=f.schema,m=f.envPrefix??`APP_`,h=f.baseGroup??`base`,g=f.root??u(),_=f.envPathOf,v=String(Array.isArray(h)?h[0]??`base`:h);return{schema:p,envPrefix:m,baseGroup:v,root:g,collectVars:()=>t(p,m,{envPathOf:_}),requiredVars:e=>t(p,m,{envPathOf:_}).filter(t=>t.required&&(e===void 0||t.scope===e)),generateEnvFile:(e={})=>r(p,{envPrefix:m,envPathOf:_,...e}),buildConfigJson:(e={})=>n(p,{envPrefix:m,envPathOf:_,...e}),generateJsonSchema:(e={})=>o(p,{baseGroup:v,...e}),writeJsonSchema:e=>s(p,{baseGroup:v,...e}),generateConfigTypes:(e={})=>l(p,{baseGroup:v,...e}),generateConfigEnv:(e={})=>a(p,{envPrefix:m,envPathOf:_,...e}),generateConfigMarkdown:(e={})=>c(p,{baseGroup:v,envPrefix:m,envPathOf:_,...e}),generateConfigCli:(e={})=>i(p,{envPrefix:m,envPathOf:_,...e}),writeEnvFile:t=>{let n=r(p,{envPrefix:m,envPathOf:_,...t});return d.mkdirSync(e.dirname(t.output),{recursive:!0}),d.writeFileSync(t.output,n,`utf-8`),t.output},writeConfigTypes:t=>{let n=l(p,{baseGroup:v,...t});return Object.keys(n).map(n=>e.join(t.outputDir,`${n}.ts`))},writeEnvTypes:t=>{let n=a(p,{envPrefix:m,envPathOf:_,...t});return Object.keys(n).map(n=>e.join(t.outputDir,n))},writeMarkdown:t=>{let n=c(p,{baseGroup:v,envPrefix:m,envPathOf:_,...t});return Object.keys(n).map(n=>e.join(t.outputDir,n))},generateCliOptions:(e={})=>i(p,{envPrefix:m,envPathOf:_,...e})}}export{f as createConfigEngine};

package/dist/packages/config/src/env-file.d.ts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigScopes } from "./types.js";
-import { CollectEnvVarsOptions } from "./collect.js";
+import { ConfigSchema } from "./types.js";
+import { CollectVarsOptions } from "./collect.js";
 //#region packages/config/src/env-file.d.ts
 export interface EnvFileOptions {
   /** Env vars to include (defaults to all). */
@@ -23,11 +23,11 @@ export interface EnvFileOptions {
   /** The characters wrapping a scope's section header (default `----`). */
   scopeSeparator?: string;
   /** Custom env-name -> dotted-path derivation. */
-  envPathOf?: CollectEnvVarsOptions['envPathOf'];
+  envPathOf?: CollectVarsOptions['envPathOf'];
 }
 /**
  * Generate `.env` content from the config schemas. Secrets and required-without-
  * default vars are emitted blank so operators fill them in.
  */
-export declare function generateEnvFile(scopes: ConfigScopes, options?: EnvFileOptions): string;
+export declare function generateEnvFile(schema: ConfigSchema, options?: EnvFileOptions): string;
 //#endregion

package/dist/packages/config/src/env-file.js

@@ -1,3 +1,3 @@
-import"node:path";import"node:url";import.meta.url;import{collectEnvVars as e}from"./collect.js";function t(e){let t=e.default;return Array.isArray(t)?t.join(`,`):typeof t==`boolean`?t?`true`:`false`:typeof t==`number`?String(t):typeof t==`object`&&t?JSON.stringify(t):t===void 0?``:String(t)}function n(n,r={}){let i=r.envPrefix??`APP_`,a=r.scopeSeparator??`----`,o=e(n,i,{envPathOf:r.envPathOf}),s=r.scopes??Object.keys(n),c=o.filter(e=>s.includes(e.scope)&&(!r.include||r.include.includes(e.name))&&!r.exclude?.includes(e.name)),l=[];r.header&&l.push(r.header,``);let u;for(let e of c){if(e.scope!==u&&(u!==void 0&&l.push(``),l.push(`# ${a} ${e.scope.toUpperCase()} ${a}`),u=e.scope),!r.bare&&e.description)for(let t of e.description.split(`
-`))l.push(`# ${t}`);let n=r.values?.[e.name];e.secret&&n===void 0?l.push(`# ${e.name}=`):l.push(`${e.name}=${n??t(e)}`)}if(r.extra){let e=Object.entries(r.extra).filter(([e])=>!c.some(t=>t.name===e)).map(([e,t])=>`${e}=${t}`);e.length&&l.push(``,`# ${a} EXTRA ${a}`,...e)}return`${l.join(`
+import"node:path";import"node:url";import.meta.url;import{collectVars as e}from"./collect.js";function t(e){let t=e.default;return Array.isArray(t)?t.join(`,`):typeof t==`boolean`?t?`true`:`false`:typeof t==`number`?String(t):typeof t==`object`&&t?JSON.stringify(t):t===void 0?``:String(t)}function n(n,r={}){let i=r.envPrefix??`APP_`,a=r.scopeSeparator??`----`,o=e(n,i,{envPathOf:r.envPathOf}).filter(e=>e.name!==void 0),s=r.scopes??[...new Set(o.map(e=>e.scope))],c=o.filter(e=>s.includes(e.scope)&&(!r.include||r.include.includes(e.name))&&!r.exclude?.includes(e.name)),l=[];r.header&&l.push(r.header,``);let u;for(let e of c){let n=e.name;if(e.scope!==u&&(u!==void 0&&l.push(``),l.push(`# ${a} ${e.scope.toUpperCase()} ${a}`),u=e.scope),!r.bare&&e.description)for(let t of e.description.split(`
+`))l.push(`# ${t}`);let i=r.values?.[n];e.secret&&i===void 0?l.push(`# ${n}=`):l.push(`${n}=${i??t(e)}`)}if(r.extra){let e=Object.entries(r.extra).filter(([e])=>!c.some(t=>t.name===e)).map(([e,t])=>`${e}=${t}`);e.length&&l.push(``,`# ${a} EXTRA ${a}`,...e)}return`${l.join(`
 `)}\n`}export{n as generateEnvFile};

package/dist/packages/config/src/env.d.ts

@@ -3,8 +3,8 @@ import __tsdown_shims_url from 'node:url';
 //#region packages/config/src/env.d.ts
 /**
  * Low-level configuration helpers: env-tree parsing, typed accessors and
- * override merging. Free of Node builtins so browser consumers can import the
- * frontend resolver without pulling `node:path` / `node:url` into a bundle.
+ * dotted-path derivation. Free of Node builtins so browser consumers can import
+ * the frontend resolver without pulling `node:path` / `node:url` into a bundle.
  */
 /** A flat env source (process.env, import.meta.env or a plain object). */
 export type EnvSource = Record<string, string | undefined>;
@@ -24,8 +24,6 @@ export declare function envBool(tree: EnvTree, path: string, fallback: boolean):
 export declare function envList(tree: EnvTree, path: string, fallback?: string[]): string[];
 /** Read `Header=value,...` into a lowercase-keyed record. */
 export declare function envMap(tree: EnvTree, path: string): Record<string, string>;
-/** Recursively merge typed overrides over a base object (shallow per level). */
-export declare function applyOverrides<T extends object>(base: T, overrides?: Partial<T>): T;
-/** Trim trailing slashes from a URL-ish string. */
-export declare function trimTrailingSlashes(value: string): string;
+/** Derive the dotted config path from an env var name + prefix. */
+export declare function envPathOf(env: string, prefix?: string): string;
 //#endregion

package/dist/packages/config/src/env.js

@@ -1 +1 @@
-import"node:path";import"node:url";import.meta.url;function e(e={},t=`APP_`){let n={};for(let[r,i]of Object.entries(e)){if(!r.startsWith(t)||i===void 0)continue;let e=r.slice(t.length).toLowerCase().split(`_`),a=n;for(let t=0;t<e.length-1;t+=1){let n=e[t]??``;(typeof a[n]!=`object`||a[n]===null)&&(a[n]={}),a=a[n]}a[e[e.length-1]??``]=i}return n}function t(e,t){let n=e;for(let e of t.split(`.`)){if(typeof n!=`object`||!n)return;n=n[e]}return n}function n(e,n,r=``){let i=t(e,n);return typeof i==`string`&&i.trim()!==``?i:r}function r(e,n,r){let i=t(e,n);if(typeof i!=`string`||i.trim()===``)return r;let a=Number.parseInt(i,10);return Number.isFinite(a)?a:r}function i(e,n,r){let i=t(e,n);if(typeof i!=`string`||i.trim()===``)return r;let a=i.trim().toLowerCase();return[`true`,`1`,`yes`,`on`].includes(a)?!0:![`false`,`0`,`no`,`off`].includes(a)&&r}function a(e,n,r=[]){let i=t(e,n);return typeof i!=`string`||i.trim()===``?r:i.split(`,`).map(e=>e.trim()).filter(Boolean)}function o(e,t){let n={};for(let r of a(e,t,[])){let e=r.indexOf(`=`);e!==-1&&(n[r.slice(0,e).trim().toLowerCase()]=r.slice(e+1).trim())}return n}function s(e,t){if(!t)return e;let n={...e};for(let[r,i]of Object.entries(t)){if(i===void 0)continue;let t=e[r];n[r]=t&&typeof t==`object`&&!Array.isArray(t)&&i&&typeof i==`object`&&!Array.isArray(i)?s(t,i):i}return n}function c(e){return e.replace(/\/+$/,``)}export{s as applyOverrides,i as envBool,r as envInt,a as envList,o as envMap,n as envString,e as parseEnvTree,t as readEnvPath,c as trimTrailingSlashes};
+import"node:path";import"node:url";import.meta.url;function e(e={},t=`APP_`){let n={};for(let[r,i]of Object.entries(e)){if(!r.startsWith(t)||i===void 0)continue;let e=r.slice(t.length).toLowerCase().split(`_`),a=n;for(let t=0;t<e.length-1;t+=1){let n=e[t]??``;(typeof a[n]!=`object`||a[n]===null)&&(a[n]={}),a=a[n]}a[e[e.length-1]??``]=i}return n}function t(e,t){let n=e;for(let e of t.split(`.`)){if(typeof n!=`object`||!n)return;n=n[e]}return n}function n(e,n,r=``){let i=t(e,n);return typeof i==`string`&&i.trim()!==``?i:r}function r(e,n,r){let i=t(e,n);if(typeof i!=`string`||i.trim()===``)return r;let a=Number.parseInt(i,10);return Number.isFinite(a)?a:r}function i(e,n,r){let i=t(e,n);if(typeof i!=`string`||i.trim()===``)return r;let a=i.trim().toLowerCase();return[`true`,`1`,`yes`,`on`].includes(a)?!0:![`false`,`0`,`no`,`off`].includes(a)&&r}function a(e,n,r=[]){let i=t(e,n);return typeof i!=`string`||i.trim()===``?r:i.split(`,`).map(e=>e.trim()).filter(Boolean)}function o(e,t){let n={};for(let r of a(e,t,[])){let e=r.indexOf(`=`);e!==-1&&(n[r.slice(0,e).trim().toLowerCase()]=r.slice(e+1).trim())}return n}function s(e,t=`APP_`){return e.slice(e.startsWith(t)?t.length:0).toLowerCase().replace(/_/g,`.`)}export{i as envBool,r as envInt,a as envList,o as envMap,s as envPathOf,n as envString,e as parseEnvTree,t as readEnvPath};

package/dist/packages/config/src/generators/cli.d.ts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigScopes } from "../types.js";
-import { CollectEnvVarsOptions } from "../collect.js";
+import { ConfigSchema } from "../types.js";
+import { CollectVarsOptions } from "../collect.js";
 import { ParseArgsOptionsConfig } from "node:util";
 //#region packages/config/src/generators/cli.d.ts
 /** Flag-shaping options shared by every CLI helper. */
@@ -11,9 +11,9 @@ export interface CliFlagOptions {
   /** Shorthand flags keyed by env var name (eg. `{ APP_TOKEN: 't' }`). */
   shortFlags?: Record<string, string>;
   /** Custom env-name -> dotted-path derivation. */
-  envPathOf?: CollectEnvVarsOptions['envPathOf'];
+  envPathOf?: CollectVarsOptions['envPathOf'];
 }
-/** A generated CLI option definition for one env var. */
+/** A generated CLI option definition. */
 export interface CliOptionDef {
   /** CLI flag, e.g. `--base-url`. */
   flag: string;
@@ -42,10 +42,10 @@ export interface GenerateCliOptionsOptions extends CliFlagOptions {
   /** The scope whose env vars become flags (default `cli`). */
   scope?: string;
   /** Output file path to write the options as JSON. */
-  output?: string;
+  output?: string | false;
 }
 /** Generate the CLI option definitions for a scope's env vars. */
-export declare function generateCliOptions(scopes: ConfigScopes, options?: GenerateCliOptionsOptions): CliOptionDef[];
+export declare function generateCliOptions(schema: ConfigSchema, options?: GenerateCliOptionsOptions): CliOptionDef[];
 /** The typed `values` of a parsed CLI args result. */
 export type CliArgsValues = Record<string, string | undefined>;
 /** A parsed CLI args result (node `parseArgs` output). */

package/dist/packages/config/src/generators/cli.js

@@ -1 +1 @@
-import"node:path";import"node:url";import.meta.url;import{formatCliFlag as e}from"../../../shared/src/string-utils.js";import"../../../shared/src/index.js";import{collectEnvVars as t}from"../collect.js";import n from"node:fs";import{parseArgs as r}from"node:util";function i(t,n={}){return e(t,n.envPrefix??`APP_`)}function a(e,t={}){return`--${i(e,t)}`}function o(e,t={}){let n=t.shortFlags?.[e];return n?`-${n}`:void 0}function s(e,t={}){let n=a(e,t),r=o(e,t);return r?`${r}, ${n}`:n}function c(e,r={}){let i=r.scope??`cli`,s=[];for(let n of t(e,r.envPrefix,{envPathOf:r.envPathOf}).filter(e=>e.scope===i)){let e=o(n.name,r);s.push({flag:a(n.name,r),env:n.name,type:n.envType??`string`,...e?{short:e}:{},...n.description?{description:n.description}:{},...n.secret?{secret:!0}:{},...n.default!==void 0&&!n.secret?{default:String(n.default)}:{}})}return r.output&&n.writeFileSync(r.output,`${JSON.stringify(s,null,4)}\n`,`utf-8`),s}function l(e){return Object.fromEntries(e.map(e=>[e.flag.replace(/^--/,``),{type:`string`,...e.short?{short:e.short.replace(/^-/,``)}:{},...e.default?{default:e.default}:{}}]))}function u(e,t){let n=l(e);return{options:n,parse:(e=process.argv.slice(2))=>r({args:e,options:n,strict:t?.strict??!0}),toConfig:e=>{let t=e?.values??{},n={};for(let[e,r]of Object.entries(t))r!==void 0&&(n[e]=r);return n}}}export{s as cliFlagLabel,a as cliFlagOf,o as cliShortOf,u as createCliArgsParser,i as flagOf,l as generateCliArgsOptions,c as generateCliOptions};
+import"node:path";import"node:url";import.meta.url;import{formatCliFlag as e}from"../../../shared/src/string-utils.js";import"../../../shared/src/index.js";import{collectVars as t}from"../collect.js";import n from"node:fs";import{parseArgs as r}from"node:util";function i(t,n={}){return e(t,n.envPrefix??`APP_`)}function a(e,t={}){return`--${i(e,t)}`}function o(e,t={}){let n=t.shortFlags?.[e];return n?`-${n}`:void 0}function s(e,t={}){let n=a(e,t),r=o(e,t);return r?`${r}, ${n}`:n}function c(e,r={}){let i=r.scope??`cli`,s=[];for(let n of t(e,r.envPrefix,{envPathOf:r.envPathOf}).filter(e=>e.scope===i&&(e.name||e.cliFlag))){let e=n.meta?.cliFlagShort?`-${n.meta.cliFlagShort.replace(/^-/,``)}`:o(n.name??``,r);s.push({flag:n.cliFlag??a(n.name??``,r),env:n.name??``,type:n.type??`string`,...e?{short:e}:{},...n.description?{description:n.description}:{},...n.secret?{secret:!0}:{},...n.default!==void 0&&!n.secret?{default:String(n.default)}:{}})}return typeof r.output==`string`&&n.writeFileSync(r.output,`${JSON.stringify(s,null,4)}\n`,`utf-8`),s}function l(e){return Object.fromEntries(e.map(e=>[e.flag.replace(/^--/,``),{type:`string`,...e.short?{short:e.short.replace(/^-/,``)}:{},...e.default?{default:e.default}:{}}]))}function u(e,t){let n=l(e);return{options:n,parse:(e=process.argv.slice(2))=>r({args:e,options:n,strict:t?.strict??!0}),toConfig:e=>{let t=e?.values??{},n={};for(let[e,r]of Object.entries(t))r!==void 0&&(n[e]=r);return n}}}export{s as cliFlagLabel,a as cliFlagOf,o as cliShortOf,u as createCliArgsParser,i as flagOf,l as generateCliArgsOptions,c as generateCliOptions};

package/dist/packages/config/src/generators/env.d.ts

@@ -1,11 +1,11 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigScopes } from "../types.js";
-import { CollectEnvVarsOptions } from "../collect.js";
+import { ConfigSchema } from "../types.js";
+import { CollectVarsOptions } from "../collect.js";
 //#region packages/config/src/generators/env.d.ts
 export interface GenerateEnvTypesOptions {
   /** Output directory. When omitted, nothing is written. */
-  outputDir?: string;
+  outputDir?: string | false;
   /** The env-var prefix (default `APP_`). */
   envPrefix?: string;
   /** The `process.env` interface name (default `AppEnv`). */
@@ -29,14 +29,14 @@ export interface GenerateEnvTypesOptions {
   /** Add a `declare module 'vite'` augmentation to the `.d.ts`. */
   augmentVite?: boolean;
   /** Custom env-name -> dotted-path derivation. */
-  envPathOf?: CollectEnvVarsOptions['envPathOf'];
+  envPathOf?: CollectVarsOptions['envPathOf'];
 }
 /** Render the `env.ts` content (the env + vite-env interfaces). */
-export declare function generateEnv(scopes: ConfigScopes, options?: GenerateEnvTypesOptions): string;
+export declare function generateEnv(schema: ConfigSchema, options?: GenerateEnvTypesOptions): string;
 /** Render the ambient `.d.ts` content. */
 export declare function generateEnvDts(options?: GenerateEnvTypesOptions): string;
-/** Generate `env.ts` + the ambient `.d.ts` into `outputDir`. Returns the paths. */
-export declare function generateEnvTypes(scopes: ConfigScopes, options: GenerateEnvTypesOptions & {
-  outputDir: string;
-}): string[];
+/** Generate env type file contents (and optionally write them). */
+export declare function generateConfigEnv(schema: ConfigSchema, options?: GenerateEnvTypesOptions): Record<string, string>;
+/** @deprecated Use {@link generateConfigEnv}. */
+export declare const generateEnvTypes: typeof generateConfigEnv;
 //#endregion

package/dist/packages/config/src/generators/env.js

@@ -1,4 +1,4 @@
-import{default as e}from"node:path";import"node:url";import.meta.url;import{collectEnvVars as t}from"../collect.js";import n from"node:fs";function r(e){return e??`Generated env typing — DO NOT EDIT.`}function i(e,n={}){let i=n.envPrefix??`APP_`,a=n.envInterfaceName??`AppEnv`,o=n.viteEnvInterfaceName??`AppViteEnv`,s=t(e,i,{envPathOf:n.envPathOf}),c=s.filter(e=>e.scope!==`frontend`),l=s.filter(e=>e.public),u=n.envHeader?[n.envHeader,``]:[`/**`,` * ${r(n.header)}`,` */`,``];u.push(`/** ${n.envComment??"Environment variables typed on `process.env`."} */`,`export interface ${a} {`);for(let e of c)u.push(`    /** ${(e.description??``).replace(/\n/g,` `)} */`),u.push(`    ${e.name}?: string;`);u.push(`}`),u.push(``),u.push("/** Public frontend environment variables typed on `import.meta.env`. */"),u.push(`export interface ${o} {`);for(let e of l)u.push(`    /** ${(e.description??``).replace(/\n/g,` `)} */`),u.push(`    ${e.name}?: string;`);return u.push(`}`),`${u.join(`
+import{default as e}from"node:path";import"node:url";import.meta.url;import{collectVars as t}from"../collect.js";import n from"node:fs";function r(e){return e??`Generated env typing — DO NOT EDIT.`}function i(e,n={}){let i=n.envPrefix??`APP_`,a=n.envInterfaceName??`AppEnv`,o=n.viteEnvInterfaceName??`AppViteEnv`,s=t(e,i,{envPathOf:n.envPathOf}).filter(e=>e.name),c=s.filter(e=>e.scope!==`frontend`),l=s.filter(e=>e.public),u=n.envHeader?[n.envHeader,``]:[`/**`,` * ${r(n.header)}`,` */`,``];u.push(`/** ${n.envComment??"Environment variables typed on `process.env`."} */`,`export interface ${a} {`);for(let e of c)u.push(`    /** ${(e.description??``).replace(/\n/g,` `)} */`),u.push(`    ${e.name}?: string;`);u.push(`}`),u.push(``),u.push("/** Public frontend environment variables typed on `import.meta.env`. */"),u.push(`export interface ${o} {`);for(let e of l)u.push(`    /** ${(e.description??``).replace(/\n/g,` `)} */`),u.push(`    ${e.name}?: string;`);return u.push(`}`),`${u.join(`
 `).trimEnd()}\n`}function a(e={}){let t=e.envInterfaceName??`AppEnv`,n=e.viteEnvInterfaceName??`AppViteEnv`,i=e.importPath??`./env.js`;return`${e.dtsHeader?`${e.dtsHeader}\n`:`/**
  * ${r(e.header)}
  *
@@ -20,4 +20,4 @@ declare module 'vite' {
 }`:``}
 
 export {};
-`}function o(t,r){let o=e.join(r.outputDir,r.envFile??`env.ts`),s=e.join(r.outputDir,r.dtsFile??`env.d.ts`);return n.mkdirSync(r.outputDir,{recursive:!0}),n.writeFileSync(o,i(t,r),`utf-8`),n.writeFileSync(s,a(r),`utf-8`),[o,s]}export{i as generateEnv,a as generateEnvDts,o as generateEnvTypes};
+`}function o(t,r={}){let o=r.envFile??`env.ts`,s=r.dtsFile??`env.d.ts`,c={[o]:i(t,r),[s]:a(r)};if(typeof r.outputDir==`string`){n.mkdirSync(r.outputDir,{recursive:!0});for(let[t,i]of Object.entries(c))n.writeFileSync(e.join(r.outputDir,t),i,`utf-8`)}return c}const s=o;export{o as generateConfigEnv,i as generateEnv,a as generateEnvDts,s as generateEnvTypes};

package/dist/packages/config/src/generators/index.d.ts

@@ -1,8 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CliArgsOptionConfig, CliArgsParser, CliArgsResult, CliArgsValues, CliFlagOptions, CliOptionDef, GenerateCliOptionsOptions, cliFlagLabel, cliFlagOf, cliShortOf, createCliArgsParser, flagOf, generateCliArgsOptions, generateCliOptions } from "./cli.js";
-import { GenerateEnvTypesOptions, generateEnv, generateEnvDts, generateEnvTypes } from "./env.js";
+import { GenerateEnvTypesOptions, generateConfigEnv, generateEnv, generateEnvDts, generateEnvTypes } from "./env.js";
 import { GenerateJsonSchemaOptions, generateConfigJsonSchema, generateJsonSchemaFile } from "./json.js";
-import { ConfigFileSection, GenerateMarkdownOptions, RenderConfigFileOptions, RenderMarkdownOptions, generateConfigMarkdown, renderConfigFileMarkdown, renderConfigIndex, renderScopeMarkdown } from "./markdown.js";
-import { GenerateTypesOptions, generateConfigTypes, renderAllConfigTypes, renderConfigImports, renderConfigTypes, resolveScopeSchema } from "./types.js";
-export { CliArgsOptionConfig, CliArgsParser, CliArgsResult, CliArgsValues, CliFlagOptions, CliOptionDef, ConfigFileSection, GenerateCliOptionsOptions, GenerateEnvTypesOptions, GenerateJsonSchemaOptions, GenerateMarkdownOptions, GenerateTypesOptions, RenderConfigFileOptions, RenderMarkdownOptions, cliFlagLabel, cliFlagOf, cliShortOf, createCliArgsParser, flagOf, generateCliArgsOptions, generateCliOptions, generateConfigJsonSchema, generateConfigMarkdown, generateConfigTypes, generateEnv, generateEnvDts, generateEnvTypes, generateJsonSchemaFile, renderAllConfigTypes, renderConfigFileMarkdown, renderConfigImports, renderConfigIndex, renderConfigTypes, renderScopeMarkdown, resolveScopeSchema };
+import { GenerateMarkdownOptions, RenderConfigFileOptions, RenderMarkdownFrontmatter, RenderMarkdownOptions, generateConfigMarkdown } from "./markdown.js";
+import { GenerateTypesOptions, generateConfigTypes } from "./types.js";
+export { CliArgsOptionConfig, CliArgsParser, CliArgsResult, CliArgsValues, CliFlagOptions, CliOptionDef, GenerateCliOptionsOptions, GenerateEnvTypesOptions, GenerateJsonSchemaOptions, GenerateMarkdownOptions, GenerateTypesOptions, RenderConfigFileOptions, RenderMarkdownFrontmatter, RenderMarkdownOptions, cliFlagLabel, cliFlagOf, cliShortOf, createCliArgsParser, flagOf, generateCliArgsOptions, generateCliOptions, generateConfigEnv, generateConfigJsonSchema, generateConfigMarkdown, generateConfigTypes, generateEnv, generateEnvDts, generateEnvTypes, generateJsonSchemaFile };

package/dist/packages/config/src/generators/index.js

@@ -1 +1 @@
-import"node:path";import"node:url";import.meta.url;import{cliFlagLabel as e,cliFlagOf as t,cliShortOf as n,createCliArgsParser as r,flagOf as i,generateCliArgsOptions as a,generateCliOptions as o}from"./cli.js";import{generateEnv as s,generateEnvDts as c,generateEnvTypes as l}from"./env.js";import{generateConfigJsonSchema as u,generateJsonSchemaFile as d}from"./json.js";import{generateConfigMarkdown as f,renderConfigFileMarkdown as p,renderConfigIndex as m,renderScopeMarkdown as h}from"./markdown.js";import{generateConfigTypes as g,renderAllConfigTypes as _,renderConfigImports as v,renderConfigTypes as y,resolveScopeSchema as b}from"./types.js";export{e as cliFlagLabel,t as cliFlagOf,n as cliShortOf,r as createCliArgsParser,i as flagOf,a as generateCliArgsOptions,o as generateCliOptions,u as generateConfigJsonSchema,f as generateConfigMarkdown,g as generateConfigTypes,s as generateEnv,c as generateEnvDts,l as generateEnvTypes,d as generateJsonSchemaFile,_ as renderAllConfigTypes,p as renderConfigFileMarkdown,v as renderConfigImports,m as renderConfigIndex,y as renderConfigTypes,h as renderScopeMarkdown,b as resolveScopeSchema};
+import"node:path";import"node:url";import.meta.url;import{cliFlagLabel as e,cliFlagOf as t,cliShortOf as n,createCliArgsParser as r,flagOf as i,generateCliArgsOptions as a,generateCliOptions as o}from"./cli.js";import{generateConfigEnv as s,generateEnv as c,generateEnvDts as l,generateEnvTypes as u}from"./env.js";import{generateConfigJsonSchema as d,generateJsonSchemaFile as f}from"./json.js";import{generateConfigMarkdown as p}from"./markdown.js";import{generateConfigTypes as m}from"./types.js";export{e as cliFlagLabel,t as cliFlagOf,n as cliShortOf,r as createCliArgsParser,i as flagOf,a as generateCliArgsOptions,o as generateCliOptions,s as generateConfigEnv,d as generateConfigJsonSchema,p as generateConfigMarkdown,m as generateConfigTypes,c as generateEnv,l as generateEnvDts,u as generateEnvTypes,f as generateJsonSchemaFile};

package/dist/packages/config/src/generators/json.d.ts

@@ -1,12 +1,10 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigScopes } from "../types.js";
+import { ConfigEngineOptions, ConfigSchema } from "../types.js";
 //#region packages/config/src/generators/json.d.ts
-export interface GenerateJsonSchemaOptions {
+export interface GenerateJsonSchemaOptions extends Pick<ConfigEngineOptions, 'baseGroup'> {
   /** Output file path. When omitted, nothing is written. */
-  output?: string;
-  /** The base group hoisted to the top level (default `base`). */
-  baseGroup?: string;
+  output?: string | false;
   /** Document metadata overrides. */
   id?: string;
   title?: string;
@@ -16,9 +14,9 @@ export interface GenerateJsonSchemaOptions {
  * Build the combined untyped JSON Schema document covering every scope, using
  * untyped's `resolveSchema` on the definitions lowered from the Zod schemas.
  */
-export declare function generateConfigJsonSchema(scopes: ConfigScopes, options?: GenerateJsonSchemaOptions): Promise<Record<string, unknown>>;
+export declare function generateConfigJsonSchema(schema: ConfigSchema, options?: GenerateJsonSchemaOptions): Promise<Record<string, unknown>>;
 /** Generate the JSON Schema document into `output`. Returns the path written. */
-export declare function generateJsonSchemaFile(scopes: ConfigScopes, options: GenerateJsonSchemaOptions & {
+export declare function generateJsonSchemaFile(schema: ConfigSchema, options: GenerateJsonSchemaOptions & {
   output: string;
 }): Promise<string>;
 //#endregion

package/dist/packages/config/src/generators/json.js

@@ -1 +1 @@
-import{default as e}from"node:path";import"node:url";import.meta.url;import{flattenBaseSchema as t,zodToUntypedDefinition as n}from"../schema.js";import r from"node:fs";import{resolveSchema as i}from"untyped";async function a(a,o={}){let s={};for(let[e,r]of Object.entries(a))s[e]=t(await i(n(r.zodSchema)),o.baseGroup);let c={$schema:`https://json-schema.org/draft/2020-12/schema`,$id:o.id??`https://example.com/schemas/config.json`,title:o.title??`Configuration`,description:o.description??`Every env-var-backed configuration value across all scopes.`,type:`object`,properties:s,required:Object.keys(a)};return o.output&&(r.mkdirSync(e.dirname(o.output),{recursive:!0}),r.writeFileSync(o.output,`${JSON.stringify(c,null,4)}\n`,`utf-8`)),c}async function o(e,t){return await a(e,t),t.output}export{a as generateConfigJsonSchema,o as generateJsonSchemaFile};
+import{default as e}from"node:path";import"node:url";import.meta.url;import{flattenBaseSchema as t,normalizeConfigSchema as n}from"../schema.js";import r from"node:fs";async function i(i,a={}){let o=n(i),s={};for(let[e]of Object.entries(o))s[e]=t(o[e],Array.isArray(a.baseGroup)?String(a.baseGroup[0]??`base`):String(a.baseGroup??`base`));let c={$schema:`https://json-schema.org/draft/2020-12/schema`,$id:a.id??`https://example.com/schemas/config.json`,title:a.title??`Configuration`,description:a.description??`Every env-var-backed configuration value across all scopes.`,type:`object`,properties:s,required:Object.keys(o)};return typeof a.output==`string`&&(r.mkdirSync(e.dirname(a.output),{recursive:!0}),r.writeFileSync(a.output,`${JSON.stringify(c,null,4)}\n`,`utf-8`)),c}async function a(e,t){return await i(e,t),t.output}export{i as generateConfigJsonSchema,a as generateJsonSchemaFile};

package/dist/packages/config/src/generators/markdown.d.ts

@@ -1,17 +1,24 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ConfigScopes } from "../types.js";
-import { CollectEnvVarsOptions } from "../collect.js";
-import { ZodType } from "zod";
-import { Schema } from "untyped";
+import { ConfigEngineOptions, ConfigSchema } from "../types.js";
+import { CollectVarsOptions } from "../collect.js";
 //#region packages/config/src/generators/markdown.d.ts
-export interface RenderMarkdownOptions {
-  /** Output directory. When omitted, nothing is written. */
-  outDir?: string;
+export interface RenderMarkdownFrontmatter {
+  options: GenerateMarkdownOptions;
+}
+export interface RenderMarkdownOptions extends Pick<ConfigEngineOptions, 'baseGroup'> {
+  /** Output directory. Set false (or omit it) to disable writing. */
+  outputDir?: string | false;
+  /** Frontmatter toggle, raw body, or callback. */
+  frontmatter?: boolean | string | ((ctx: RenderMarkdownFrontmatter) => string);
+  /** Render every scope into one file instead of one file per scope. */
+  combined?: boolean;
+  /** Show env var equivalents (default true). */
+  includeEnv?: boolean;
+  /** Show CLI flag equivalents (default true). */
+  includeCli?: boolean;
   /** Page outline (defaults to `[2, 3, 4]`). */
   outline?: number[];
-  /** The base group hoisted out of the nested groups (default `base`). */
-  baseGroup?: string;
   /** The scope whose env vars render as CLI flags (default `cli`). */
   cliScope?: string;
   /** Env-var prefix (default `APP_`). */
@@ -36,29 +43,34 @@ export interface RenderMarkdownOptions {
   /** Shorthand flags keyed by env var name (for the CLI scope). */
   shortFlags?: Record<string, string>;
   /** Custom env-name -> dotted-path derivation. */
-  envPathOf?: CollectEnvVarsOptions['envPathOf'];
+  envPathOf?: CollectVarsOptions['envPathOf'];
+  /** Emit `- **Required**` lines (default true). */
+  includeRequired?: boolean;
+  /** Emit `- **Deprecated**` lines (default true). */
+  includeDeprecated?: boolean;
+  /** Emit `**Example(s):**` blocks (default true). */
+  includeExamples?: boolean;
+  /** Emit `- **Since**` lines (default true). */
+  includeSince?: boolean;
+  /** Emit `- **See**` lines (default true). */
+  includeSee?: boolean;
+  /** Emit `**Remarks:**` blocks (default true). */
+  includeRemarks?: boolean;
+  /** Emit `- **Experimental**` lines (default true). */
+  includeExperimental?: boolean;
+  /** Emit `- **Alpha**` lines (default true). */
+  includeAlpha?: boolean;
+  /** Emit `- **Beta**` lines (default true). */
+  includeBeta?: boolean;
 }
 export interface GenerateMarkdownOptions extends RenderMarkdownOptions {
+  /** Document title (default `Configuration`). */
+  title?: string;
   /** Index file name (defaults to `index.md`). */
   indexFilename?: string;
 }
-/** Render the markdown reference for a single scope (base + grouped configs). */
-export declare function renderScopeMarkdown(scope: string, schema: Schema, options?: RenderMarkdownOptions): string;
-/** Render the index file: explains the env convention + lists required/core. */
-export declare function renderConfigIndex(scopes: ConfigScopes, options?: RenderMarkdownOptions): string;
-/** Generate the markdown reference (per-scope files + index) into `outDir`. */
-export declare function generateConfigMarkdown(scopes: ConfigScopes, options: GenerateMarkdownOptions & {
-  outDir: string;
-}): string[];
-/** A section of a config-file reference (its key + options schema). */
-export interface ConfigFileSection {
-  /** The config key, eg. `project`. */
-  key: string;
-  /** A short description shown under the heading. */
-  description?: string;
-  /** The section's options-object schema. */
-  schema: ZodType;
-}
+/** Generate markdown file contents (and optionally write them). */
+export declare function generateConfigMarkdown(schema: ConfigSchema, options?: GenerateMarkdownOptions): Record<string, string>;
 export interface RenderConfigFileOptions {
   /** Document title (default `Configuration`). */
   title?: string;
@@ -66,13 +78,23 @@ export interface RenderConfigFileOptions {
   intro?: string;
   /** Page outline (default `[2, 3, 4]`). */
   outline?: number[];
+  /** Emit `- **Required**` lines (default true). */
+  includeRequired?: boolean;
+  /** Emit `- **Deprecated**` lines (default true). */
+  includeDeprecated?: boolean;
+  /** Emit `**Example(s):**` blocks (default true). */
+  includeExamples?: boolean;
+  /** Emit `- **Since**` lines (default true). */
+  includeSince?: boolean;
+  /** Emit `- **See**` lines (default true). */
+  includeSee?: boolean;
+  /** Emit `**Remarks:**` blocks (default true). */
+  includeRemarks?: boolean;
+  /** Emit `- **Experimental**` lines (default true). */
+  includeExperimental?: boolean;
+  /** Emit `- **Alpha**` lines (default true). */
+  includeAlpha?: boolean;
+  /** Emit `- **Beta**` lines (default true). */
+  includeBeta?: boolean;
 }
-/**
- * Render a single markdown reference for a config **file** (no environment-var
- * language): one `## \`key\`` section per schema, with its fields, types,
- * defaults and descriptions. Named sub-schemas (`$defs`) are resolved and
- * expanded inline, so nested options (`changelog.versioning.target`, ...) are
- * documented too. This is what a `dbx.config.ts`-style reference is generated from.
- */
-export declare function renderConfigFileMarkdown(sections: ConfigFileSection[], options?: RenderConfigFileOptions): string;
 //#endregion

package/dist/packages/config/src/generators/markdown.js

@@ -1,27 +1,26 @@
-import{default as e}from"node:path";import"node:url";import.meta.url;import{sanitizeText as t,titleCase as n}from"../../../shared/src/string-utils.js";import"../../../shared/src/index.js";import{splitBaseSchema as r,zodToJsonSchema as i}from"../schema.js";import{collectEnvVars as a}from"../collect.js";import{cliFlagLabel as o}from"./cli.js";import s from"node:fs";import{z as c}from"zod";function l(e,n,r,i){let a=[`${r} ${n}`];return e.type===`object`&&e.properties?(a.push(...u(e,`${r}#`,i)),a):(e.env&&a.push(`- **Env**: \`${e.env}\``),a.push(`- **Type**: \`${e.tsType??(Array.isArray(e.type)?e.type.join(` | `):e.type)??`any`}\``),e.default!==void 0&&a.push(`- **Default**: \`${JSON.stringify(e.default)}\``),e.description&&a.push(``,t(e.description)),a)}function u(e,t,n){let r=[];for(let[i,a]of Object.entries(e.properties??{})){let e=n.useFlags&&a.env?o(a.env,n):`\`${i}\``;r.push(``,...l(a,e,t,n))}return r}function d(e,t,i={}){let a=i.outline??[2,3,4],o={useFlags:e===(i.cliScope??`cli`),baseGroup:i.baseGroup??`base`,...i.envPrefix?{envPrefix:i.envPrefix}:{},...i.shortFlags?{shortFlags:i.shortFlags}:{}},{base:s,groups:c}=r(t,o.baseGroup),l=[`---`,`title: ${n(e)} Configuration`,`outline: ${JSON.stringify(a)}`,`---`,``,`# ${n(e)} Configuration`,``,`Every setting below is configured through an environment variable.`,``,`## Base`,``,...u(s,`###`,o)];for(let[e,t]of Object.entries(c.properties??{}))l.push(``,`## ${n(e)}`,``,...u(t,`###`,o));return`${l.join(`
-`).trim()}\n`}function f(e){return e===void 0?`—`:Array.isArray(e)?`\`${e.join(`,`)}\``:typeof e==`object`?`\`${JSON.stringify(e)}\``:`\`${String(e)}\``}function p(e,t,n){for(let r of Object.values(e.properties??{})){let e=r;if(e.type===`object`&&e.properties)p(r,t,n);else if(e.env){let r=e.envDefault??e.default;n.push({name:e.env,scope:t,...e.description?{description:e.description}:{},...r===void 0?{}:{default:r},...e.required===!0?{required:!0}:{},...e.secret?{secret:!0}:{},...e.public?{public:!0}:{}})}}}function m(e,t={}){let n=t.outline??[2,3,4],o=t.baseGroup??`base`,s=t.labels??{},c=[],l=[];for(let[t,n]of Object.entries(e)){let e=n.jsonSchema??i(n.zodSchema);p(r(e,o).base,t,l)}for(let n of a(e,t.envPrefix??`APP_`,{envPathOf:t.envPathOf}))n.required&&c.push({name:n.name,scope:n.scope,...n.description?{description:n.description}:{},...n.default===void 0?{}:{default:n.default}});let u=e=>[`| Variable | Default | Description |`,`| -------- | ------- | ----------- |`,...e.map(e=>`| \`${e.name}\` | ${f(e.default)} | ${(e.description??``).replace(/\n/g,` `).replace(/\|/g,`\\|`)} |`)].join(`
-`),d=s.title??`Environment variables`,m=t.intro??`Environment variables are prefixed with \`${t.envPrefix??`APP_`}\`.
+import{default as e}from"node:path";import"node:url";import.meta.url;import{sanitizeText as t,titleCase as n}from"../../../shared/src/string-utils.js";import"../../../shared/src/index.js";import{isSchemaType as r,isZodSchema as i,metaOf as a,normalizeConfigSchema as o,splitBaseSchema as s}from"../schema.js";import{collectVars as c}from"../collect.js";import{cliFlagLabel as l}from"./cli.js";import u from"node:fs";function d(e){return e==null?[]:(Array.isArray(e)?e:[e]).map(e=>t(String(e))).filter(Boolean)}function f(e,n){if(e===void 0||e===!1)return;let r=typeof n==`string`?t(n.trim()):``;return r?`- **Deprecated**: ${r}`:`- **Deprecated**`}function p(e){let t=d(e);return t.length===0?[]:[``,`**Example(s):**`,``,...t.flatMap((e,t)=>t?[``,e]:[e])]}function m(e,t){return t.includeRequired!==!1&&e?`- **Required**`:void 0}function h(e,n){let r=[];if(n.includeDeprecated!==!1){let t=f(e.deprecated,e.deprecationMessage);t&&r.push(t)}if(n.includeSince!==!1&&typeof e.since==`string`&&e.since.trim()&&r.push(`- **Since**: ${t(e.since.trim())}`),n.includeSee!==!1)for(let t of d(e.see))r.push(`- **See**: ${t}`);return n.includeExperimental!==!1&&e.experimental&&r.push(`- **Experimental**`),n.includeAlpha!==!1&&e.alpha&&r.push(`- **Alpha**`),n.includeBeta!==!1&&e.beta&&r.push(`- **Beta**`),r}function g(e,n){if(n.includeRemarks===!1)return[];let r=typeof e==`string`?t(e.trim()):``;return r?[``,`**Remarks:**`,``,...r.split(`
+`)]:[]}function _(e,n,r,i){let a=[`${r} ${n}`];if(e.type===`object`&&e.properties)return a.push(...v(e,`${r}#`,i)),a;let o=typeof e.envName==`string`?e.envName:typeof e.env==`string`?e.env:void 0;i.includeEnv!==!1&&o&&a.push(`- **Env**: \`${o}\``),i.includeCli!==!1&&typeof e.cliFlag==`string`&&a.push(`- **CLI**: \`${e.cliFlag}\``);let s=m(e.required===!0,i);return s&&a.push(s),a.push(`- **Type**: \`${e.tsType??(Array.isArray(e.type)?e.type.join(` | `):e.type)??`any`}\``),a.push(...h(e,i)),e.default!==void 0&&a.push(`- **Default**: \`${JSON.stringify(e.default)}\``),e.description&&a.push(``,t(e.description)),a.push(...g(e.remarks,i)),i.includeExamples!==!1&&a.push(...p(e.example)),a}function v(e,t,n){let r=[];for(let[i,a]of Object.entries(e.properties??{})){let e=a.cliFlag??a.envName??a.env,o=n.useFlags&&e?l(e,n):`\`${i}\``;r.push(``,..._(a,o,t,n))}return r}function y(e,t,n){let r=e.frontmatter;return r===!1?[]:[`---`,...(typeof r==`function`?r({options:e}):typeof r==`string`?r:`title: ${t}\noutline: ${JSON.stringify(n)}`).split(`
+`),`---`,``]}function b(e,t,r={}){let i=r.outline??[2,3,4],a={useFlags:e===(r.cliScope??`cli`),baseGroup:Array.isArray(r.baseGroup)?String(r.baseGroup[0]??`base`):String(r.baseGroup??`base`),...r.envPrefix?{envPrefix:r.envPrefix}:{},...r.shortFlags?{shortFlags:r.shortFlags}:{},...r.includeRequired===void 0?{}:{includeRequired:r.includeRequired},...r.includeDeprecated===void 0?{}:{includeDeprecated:r.includeDeprecated},...r.includeExamples===void 0?{}:{includeExamples:r.includeExamples},...r.includeSince===void 0?{}:{includeSince:r.includeSince},...r.includeSee===void 0?{}:{includeSee:r.includeSee},...r.includeRemarks===void 0?{}:{includeRemarks:r.includeRemarks},...r.includeExperimental===void 0?{}:{includeExperimental:r.includeExperimental},...r.includeAlpha===void 0?{}:{includeAlpha:r.includeAlpha},...r.includeBeta===void 0?{}:{includeBeta:r.includeBeta}},{base:o,groups:c}=s(t,a.baseGroup),l=`${n(e)} Configuration`,u=[...y(r,l,i),`# ${l}`,``,`Every setting below is configured through a config value.`,``,`## Base`,``,...v(o,`###`,a)];for(let[e,t]of Object.entries(c.properties??{}))u.push(``,`## ${n(e)}`,``,...v(t,`###`,a));return`${u.join(`
+`).trim()}\n`}function x(e){return e===void 0?`—`:Array.isArray(e)?`\`${e.join(`,`)}\``:typeof e==`object`?`\`${JSON.stringify(e)}\``:`\`${String(e)}\``}function S(e,t,n){for(let r of Object.values(e.properties??{})){let e=r;if(e.type===`object`&&e.properties)S(r,t,n);else if(e.env){let r=e.envDefault??e.default;n.push({name:e.env,scope:t,...e.description?{description:e.description}:{},...r===void 0?{}:{default:r},...e.required===!0?{required:!0}:{},...e.secret?{secret:!0}:{},...e.public?{public:!0}:{}})}}}function C(e,t={}){let n=t.outline??[2,3,4],r=Array.isArray(t.baseGroup)?String(t.baseGroup[0]??`base`):String(t.baseGroup??`base`),i=t.labels??{},a=[],l=[],u=o(e);for(let[e,t]of Object.entries(u))S(s(t,r).base,e,l);for(let n of c(e,t.envPrefix??`APP_`,{envPathOf:t.envPathOf}))n.required&&n.name&&a.push({name:n.name,scope:n.scope,...n.description?{description:n.description}:{},...n.default===void 0?{}:{default:n.default}});let d=e=>[`| Variable | Default | Description |`,`| -------- | ------- | ----------- |`,...e.map(e=>`| \`${e.name}\` | ${x(e.default)} | ${(e.description??``).replace(/\n/g,` `).replace(/\|/g,`\\|`)} |`)].join(`
+`),f=i.title??`Environment variables`,p=t.intro??`Environment variables are prefixed with \`${t.envPrefix??`APP_`}\`.
 The underscore is a path separator, so every config value has an environment
-variable equivalent.`,h=t.requiredNote??`These variables have no safe default and **must** be set:`,g=t.coreNote??`The core (base) config values:`,_=t.references&&t.references.length?`\n## References\n\n${t.references.map(e=>`- [${e.label}](${e.href})`).join(`
-`)}\n`:``;return`---
-title: ${d}
-outline: ${JSON.stringify(n)}
----
+variable equivalent.`,m=t.requiredNote??`These variables have no safe default and **must** be set:`,h=t.coreNote??`The core (base) config values:`,g=t.references&&t.references.length?`\n## References\n\n${t.references.map(e=>`- [${e.label}](${e.href})`).join(`
+`)}\n`:``;return`${y(t,f,n).join(`
+`)}
+# ${f}
 
-# ${d}
+${p}
 
-${m}
-
-## ${s.required??`Required`}
+## ${i.required??`Required`}
 
-${h}
+${m}
 
-${u(c)}
+${d(a)}
 
-## ${s.core??`Core`}
+## ${i.core??`Core`}
 
-${g}
+${h}
 
-${u(l)}
-${_}`}function h(t,n){let r=n.outline??[2,3,4],a=Object.entries(t).map(([t,a])=>[e.resolve(n.outDir,`${t}.md`),d(t,a.jsonSchema??i(a.zodSchema),{...n,outline:r})]);a.push([e.resolve(n.outDir,n.indexFilename??`index.md`),m(t,{...n,outline:r})]);for(let[t,n]of a)s.mkdirSync(e.dirname(t),{recursive:!0}),s.writeFileSync(t,n,`utf-8`);return a.map(([e])=>e)}function g(e){return e.$ref?e.$ref.split(`/`).pop()??void 0:void 0}function _(e,t){let n=g(e);return n&&t[n]?t[n]:e}function v(e){return typeof e==`string`?`'${e}'`:String(e)}function y(e,t){if(e.$ref){let n=_(e,t);return n.properties||n.anyOf||n.oneOf?g(e):y(n,t)}if(e.const!==void 0)return v(e.const);if(Array.isArray(e.enum)&&e.enum.length>0)return e.enum.map(v).join(` | `);let n=e.anyOf??e.oneOf;if(n&&n.length>0)return n.map(e=>y(e,t)).join(` | `);if(e.properties)return`object`;let r=Array.isArray(e.type)?e.type:e.type?[e.type]:[];return r.includes(`array`)?`Array<${y(e.items??{},t)}>`:r.includes(`object`)?`Record<string, unknown>`:r.length===0?`unknown`:r.map(e=>e===`integer`?`number`:e).join(` | `)}function b(e,t,n){let r=g(e);if(r){if(n.has(r))return{properties:{},required:[]};n.add(r)}let i=_(e,t);if(i.properties)return{properties:i.properties,required:i.required??[]};let a=i.anyOf??i.oneOf;if(a){let e={},r=/* @__PURE__ */ new Set;for(let i of a){let a=b(i,t,n);Object.assign(e,a.properties);for(let e of a.required)r.add(e)}return{properties:e,required:[...r]}}return(Array.isArray(i.type)?i.type:i.type?[i.type]:[]).includes(`array`)&&i.items?b(i.items,t,n):{properties:{},required:[]}}function x(e,n,r,i,a,o){let s=_(n,i),c=[`${r} \`${e}\``];c.push(`- **Type**: \`${y(n,i)}\``),o&&c.push(`- **Required**`);let l=n.default??s.default;l!==void 0&&c.push(`- **Default**: \`${JSON.stringify(l)}\``);let u=t(n.description??s.description??``);u&&c.push(``,u);let d=b(n,i,a),f=r.length<6?`${r}#`:r;for(let[e,t]of Object.entries(d.properties))c.push(``,...x(e,t,f,i,a,d.required.includes(e)));return c}function S(e,t,n,r){let i=[],a=e.required??[];for(let[o,s]of Object.entries(e.properties??{}))i.push(``,...x(o,s,t,n,r,a.includes(o)));return i}function C(e,t={}){let n=t.title??`Configuration`,r=[`---`,`title: ${n}`,`outline: ${JSON.stringify(t.outline??[2,3,4])}`,`---`,``,`# ${n}`,``];t.intro&&r.push(t.intro,``);for(let t of e){r.push(`## \`${t.key}\``,``),t.description&&r.push(t.description,``);let e=c.toJSONSchema(t.schema,{target:`draft-2020-12`}),n=e.$defs??{},i=e.$ref?_(e,n):e;r.push(...S(i,`###`,n,/* @__PURE__ */ new Set),``)}return`${r.join(`
-`).trim()}\n`}export{h as generateConfigMarkdown,C as renderConfigFileMarkdown,m as renderConfigIndex,d as renderScopeMarkdown};
+${d(l)}
+${g}`}function w(e,t){let n=e=>i(e)?e.toJSONSchema({target:`draft-2020-12`}):void 0;if(Array.isArray(e))return t;let a=n(e);if(a){let[e]=Object.keys(t);return e?{[e]:a}:t}if(r(e))return t;let o={};for(let[r,i]of Object.entries(t)){let t=e[r];o[r]=!Array.isArray(t)&&n(t)||i}return o}function T(t,n={}){let r=n.outline??[2,3,4],i=o(t),a={};if(n.combined){let e=n.indexFilename??`index.md`;a[e]=P(w(t,i),{...n,outline:r})}else{for(let[e,t]of Object.entries(i))a[`${e}.md`]=b(e,t,{...n,outline:r});a[n.indexFilename??`index.md`]=C(t,{...n,outline:r})}if(typeof n.outputDir==`string`){u.mkdirSync(n.outputDir,{recursive:!0});for(let[t,r]of Object.entries(a))u.writeFileSync(e.resolve(n.outputDir,t),r,`utf-8`)}return a}function E(e){return e.$ref?e.$ref.split(`/`).pop()??void 0:void 0}function D(e,t){let n=E(e);return n&&t[n]?t[n]:e}function O(e){return typeof e==`string`?`'${e}'`:String(e)}function k(e,t){let n=D(e,t),r=e.required===!0||n.required===!0||void 0,i=e.deprecated??n.deprecated,a=e.deprecationMessage??n.deprecationMessage,o=e.example??n.example,s=e.since??n.since,c=e.see??n.see,l=e.remarks??n.remarks,u=e.experimental??n.experimental,d=e.alpha??n.alpha,f=e.beta??n.beta,p=[...n.anyOf??e.anyOf??[],...n.oneOf??e.oneOf??[]];for(let e of p){let n=D(e,t);r??=e.required===!0||n.required===!0||void 0,i??=e.deprecated??n.deprecated,a??=e.deprecationMessage??n.deprecationMessage,o??=e.example??n.example,s??=e.since??n.since,c??=e.see??n.see,l??=e.remarks??n.remarks,u??=e.experimental??n.experimental,d??=e.alpha??n.alpha,f??=e.beta??n.beta}return{...r===void 0?{}:{required:r},...i===void 0?{}:{deprecated:i},...a===void 0?{}:{deprecationMessage:a},...o===void 0?{}:{example:o},...s===void 0?{}:{since:s},...c===void 0?{}:{see:c},...l===void 0?{}:{remarks:l},...u===void 0?{}:{experimental:u},...d===void 0?{}:{alpha:d},...f===void 0?{}:{beta:f}}}function A(e,t){if(e.$ref){let n=D(e,t);return n.properties||n.anyOf||n.oneOf?E(e):A(n,t)}if(e.const!==void 0)return O(e.const);if(Array.isArray(e.enum)&&e.enum.length>0)return e.enum.map(O).join(` | `);let n=e.anyOf??e.oneOf;if(n&&n.length>0)return n.map(e=>A(e,t)).join(` | `);if(e.properties)return`object`;let r=Array.isArray(e.type)?e.type:e.type?[e.type]:[];if(r.includes(`array`))return`Array<${A(e.items??{},t)}>`;if(r.includes(`object`)){let n=e.additionalProperties;return n&&n!==!0?`Record<string, ${A(n,t)}>`:`Record<string, unknown>`}return r.length===0?`unknown`:r.map(e=>e===`integer`?`number`:e).join(` | `)}function j(e,t,n){let r=E(e);if(r){if(n.has(r))return{properties:{},required:[]};n.add(r)}let i=D(e,t);if(i.properties)return{properties:i.properties,required:Array.isArray(i.required)?i.required:[]};let a=i.anyOf??i.oneOf;if(a){let e={},r=/* @__PURE__ */ new Set;for(let i of a){let a=j(i,t,n);Object.assign(e,a.properties);for(let e of a.required)r.add(e)}return{properties:e,required:[...r]}}return(Array.isArray(i.type)?i.type:i.type?[i.type]:[]).includes(`array`)&&i.items?j(i.items,t,n):{properties:{},required:[]}}function M(e,n,r,i,a,o,s){let c=D(n,i),l=k(n,i),u=[`${r} \`${e}\``],d=m(o||l.required===!0,s);d&&u.push(d),u.push(`- **Type**: \`${A(n,i)}\``),u.push(...h(l,s));let f=n.default??c.default;f!==void 0&&u.push(`- **Default**: \`${JSON.stringify(f)}\``);let _=t(n.description??c.description??``);_&&u.push(``,_),u.push(...g(l.remarks,s)),s.includeExamples!==!1&&u.push(...p(l.example));let v=j(n,i,a),y=r.length<6?`${r}#`:r;for(let[e,t]of Object.entries(v.properties))u.push(``,...M(e,t,y,i,a,v.required.includes(e),s));return u}function N(e,t,n,r,i){let a=[],o=Array.isArray(e.required)?e.required:[];for(let[s,c]of Object.entries(e.properties??{}))a.push(``,...M(s,c,t,n,r,o.includes(s),i));return a}function P(e,t={}){let n=t.title??`Configuration`,r=[...y(t,n,t.outline??[2,3,4]),`# ${n}`,``];t.intro&&r.push(t.intro,``);for(let[n,i]of Object.entries(e)){let e=i,o=e.$defs??{},s=D(e,o),c=a(s);r.push(`## \`${n}\``,``),c?.description&&r.push(c.description,``);let l=m(c?.required===!0,t);l&&r.push(l,``);let u=h(c??{},t);u.length>0&&r.push(...u,``);let d=g(c?.remarks,t);if(d.length>0&&r.push(...d,``),t.includeExamples!==!1){let e=p(c?.example);e.length>0&&r.push(...e,``)}r.push(...N(s,`###`,o,/* @__PURE__ */ new Set,t),``)}return`${r.join(`
+`).trim()}\n`}export{T as generateConfigMarkdown};