@ak--47/dungeon-master 1.5.2 → 1.5.3

package/.claude/skills/analyze-soup/SKILL.md

@@ -134,7 +134,12 @@ FROM (
 
 ## Step 3: Write Report
 
-Create `soup-analysis.md` in the project root with:
+Create `soup-analysis.md` with the structure below. For a user dungeon
+(`dungeons/user/<name>/<name>.js`) write it into the dungeon's folder
+(`dungeons/user/<name>/soup-analysis.md`) — everything about a dungeon lives in
+its folder. Otherwise write it to the project root. (The generated
+`./data/soup-analysis-EVENTS.json` is throwaway verification data — leave it in
+`./data/`.) Contents:
 
 1. **Config**: The soup parameters used (peaks, deviation, mean, numDays)
 2. **Summary stats**: Total events, event count, avg EPS

package/.claude/skills/create-dungeon/SKILL.md

@@ -18,7 +18,7 @@ box. It does **NOT** engineer story trends or magic numbers — those are the
 should be:
 
 ```
-/write-hooks dungeons/user/<your-dungeon>.js "describe the trends to engineer"
+/write-hooks dungeons/user/<name>/<name>.js "describe the trends to engineer"
 ```
 
 In scope here:
@@ -63,7 +63,7 @@ Before writing any code, scan:
 - `lib/utils/utils.js` — `pickAWinner`, `weighNumRange`, `initChance`, `exhaust`,
   `takeSome` for property value distributions
 - `dungeons/vertical/sass.js` — B2B reference dungeon with full identity model
-- `dungeons/user/my-buddy.js` — consumer-app reference (gitignored)
+- `dungeons/user/my-buddy/my-buddy.js` — consumer-app reference (gitignored)
 - `dungeons/technical/identity-model-verify.js` — minimal identity-model fixture
 
 ## File structure
@@ -524,9 +524,9 @@ userProps:  { Plan: PLANS, Region: REGIONS, Role: ROLES, ... },
 
 After writing the file:
 
-1. Smoke-test: `node scripts/verify-runner.mjs dungeons/user/<file>.js verify-<file> --small`. Confirm zero errors.
-2. Hand to the next skill: `/write-hooks dungeons/user/<file>.js "describe trends"`.
-3. After hooks land: `/verify-dungeon dungeons/user/<file>.js`.
+1. Smoke-test: `node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name> --small`. Confirm zero errors.
+2. Hand to the next skill: `/write-hooks dungeons/user/<name>/<name>.js "describe trends"`.
+3. After hooks land: `/verify-dungeon dungeons/user/<name>/<name>.js`.
 
 ## Property Type Reference
 
@@ -550,8 +550,20 @@ When designing event properties, always consider which Mixpanel type best repres
 
 ## Output
 
-Write the file to `dungeons/user/<descriptive-name>.js`. Do NOT inject hooks.
-Do NOT use `subscription`, `attribution`, `geo`, `features`, or `anomalies`
-(the engine will silently strip them and warn).
+**One folder per customer/dungeon.** Pick a short, kebab-case `<name>` from the
+app/customer, then **create `dungeons/user/<name>/` if it doesn't already exist**
+(`mkdir -p dungeons/user/<name>`) and write the dungeon to
+`dungeons/user/<name>/<name>.js` (e.g. `dungeons/user/acme/acme.js`). Folder and
+file share the name, matching `kodiak/kodiak.js`, `my-buddy/my-buddy.js`.
+
+This keeps `dungeons/user/` organized — EVERYTHING about this dungeon lives in
+the same folder: `hook-results.md` + `hook-query-log.txt` +
+`<name>-verifications.sql` (from `verify-dungeon`), `soup-analysis.md` (from
+`analyze-soup`), briefs, schema CSV/JSON, example data. The only thing kept
+outside is the throwaway verification data the runs write to `./data/` (cleaned
+after).
+
+Do NOT inject hooks. Do NOT use `subscription`, `attribution`, `geo`,
+`features`, or `anomalies` (the engine will silently strip them and warn).
 
 When done, tell the user the next skill to run.

package/.claude/skills/verify-dungeon/SKILL.md

@@ -102,13 +102,33 @@ For emulator details, identity-model dungeons (must pass `profiles`), and time-s
 - Experiment invariants (variant distribution, exposure timing, deterministic assignment) when any funnel uses `experiment:`
 - SuperProp consistency, SuperProp/UserProp mirror, Mixpanel default-property casing, funnel-pre dilution
 
-### Step 5: Stash query log (optional)
+### Artifact location
 
-If `./research/` exists locally, write every DuckDB query execution to `./research/hook-query-log.txt`. Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format). If `./research/` does not exist, skip — do not create the directory.
+**Everything about a dungeon lives in its folder.** When the dungeon being
+verified is a user dungeon at `dungeons/user/<name>/<name>.js`, write ALL
+generated artifacts into `dungeons/user/<name>/`:
+- `hook-results.md` (Step 6)
+- `hook-query-log.txt` (Step 5)
+- `<name>-verifications.sql` (Step 6b)
 
-### Step 6: Write `./research/hook-results.md`
+The ONLY exception is the throwaway verification data the run writes to
+`./data/` (`verify-*` event/user files) — that stays in `./data/` and is
+deleted in Step 7.
 
-Use the templates in [report-format.md](references/report-format.md):
+For non-user dungeons (technical/vertical) or batch runs across many dungeons,
+fall back to `./research/` for `hook-results.md` / `hook-query-log.txt`.
+
+### Step 5: Stash query log
+
+Write every DuckDB query execution to `hook-query-log.txt`:
+- **User dungeon:** always write to `dungeons/user/<name>/hook-query-log.txt`.
+- **Otherwise:** if `./research/` exists locally, write to `./research/hook-query-log.txt`; if it doesn't exist, skip — do not create the directory.
+
+Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format).
+
+### Step 6: Write `hook-results.md`
+
+Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./research/hook-results.md`. Use the templates in [report-format.md](references/report-format.md):
 - Single-dungeon report structure
 - Multi-dungeon report structure (when batch mode)
 - Per-hook detail block
@@ -118,7 +138,7 @@ Use the templates in [report-format.md](references/report-format.md):
 
 ### Step 6b: Write verification SQL (mandatory for user dungeons)
 
-When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file at `dungeons/user/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
+When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
 
 ### Step 7: Cleanup
 
@@ -148,9 +168,9 @@ Return-value behavior:
 ## Final output
 
 Tell the user:
-1. Report path: `./research/hook-results.md`
-2. Verification SQL path (for user dungeons): `dungeons/user/<name>-verifications.sql`
-3. Query log path (if written): `./research/hook-query-log.txt`
+1. Report path: `dungeons/user/<name>/hook-results.md` (user dungeon) or `./research/hook-results.md`
+2. Verification SQL path (for user dungeons): `dungeons/user/<name>/<name>-verifications.sql`
+3. Query log path (if written): alongside the report (`dungeons/user/<name>/hook-query-log.txt`, else `./research/hook-query-log.txt`)
 4. Pass/weak/fail counts (per dungeon if batch mode)
 5. One-line summary of the most interesting finding
 

package/.claude/skills/verify-dungeon/references/report-format.md

@@ -1,6 +1,6 @@
 # Report Format
 
-Templates and conventions for writing `./research/hook-results.md` and per-dungeon verification SQL.
+Templates and conventions for writing `hook-results.md` and per-dungeon verification SQL. For user dungeons these live in the dungeon's folder (`dungeons/user/<name>/`); otherwise in `./research/`. See [SKILL.md "Artifact location"](../SKILL.md).
 
 ## Verdict criteria (5-tier)
 
@@ -147,9 +147,7 @@ Each hook's detailed section follows this template (same for single and multi-du
 
 ## Query log format
 
-If `./research/` exists locally, write a plain-text log of every DuckDB query execution to `./research/hook-query-log.txt`. If `./research/` does not exist, skip this step entirely — do not create the directory.
-
-Check with: `ls -d ./research/ 2>/dev/null`
+Write a plain-text log of every DuckDB query execution to `hook-query-log.txt`. For a user dungeon, write it to the dungeon's folder (`dungeons/user/<name>/hook-query-log.txt`). Otherwise, only if `./research/` exists locally write `./research/hook-query-log.txt` — if it doesn't exist, skip this step entirely (don't create the directory; check with `ls -d ./research/ 2>/dev/null`).
 
 Use a consistent delimited format — one block per query, separated by a ruler line. DuckDB table output is preserved verbatim:
 
@@ -191,7 +189,7 @@ grep "^DUNGEON:" research/hook-query-log.txt           # list of dungeons querie
 
 ## Verification SQL file (mandatory for user dungeons)
 
-When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon at `dungeons/user/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
+When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
 
 Follow the format in `verification/verticals/`:
 
@@ -200,8 +198,8 @@ Follow the format in `verification/verticals/`:
 -- <name>.js — Hook Verification SQL (N hooks)
 -- ============================================================================
 -- USAGE:
---   1. node scripts/verify-runner.mjs dungeons/user/<name>.js verify-<name>
---   2. duckdb < dungeons/user/<name>-verifications.sql
+--   1. node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name>
+--   2. duckdb < dungeons/user/<name>/<name>-verifications.sql
 --   3. rm -f verify-<name>-*
 -- ============================================================================
 

package/.claude/skills/write-hooks/SKILL.md

@@ -36,8 +36,8 @@ Out of scope:
 - `lib/hook-patterns/index.js` — high-level recipes (one per Mixpanel
   analysis type).
 - `lib/verify/emulate-breakdown.js` — what `verify-dungeon` will check.
-- `dungeons/user/my-buddy.js` — reference dungeon using a mix of atoms and
-  hand-rolled logic.
+- `dungeons/user/my-buddy/my-buddy.js` — reference dungeon using a mix of atoms
+  and hand-rolled logic.
 - `dungeons/technical/pattern-*.js` — five minimal pattern fixtures, one per
   recipe.
 - `HOOKS.md` — encyclopedia of hook recipes organized by story pattern. Contains

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.5.3 — 2026-06-04
+
+Adds two JSON/source interop helpers to the public API. No breaking changes —
+existing exports and behavior are untouched.
+
+### Added
+
+- **`dungeonToJSON(input, options?)`** export. The inverse of `parseJSONDungeon`:
+  turns a dungeon into the `{ schema, hooks, timestamp, version }` JSON/UI wrapper
+  format. Accepts the same input flavors as the default export — a config object,
+  a `.js`/`.mjs`/`.json` file path, a raw JS source string, or an array of file
+  paths (returns an array). Output round-trips: `parseJSONDungeon(await
+  dungeonToJSON(x))` yields a runnable config. Best effort — arrow functions and
+  bound `chance.*` methods survive the round trip; detected utility calls
+  (`weighArray`, `weighNumRange`, …) are serialized by name without their
+  arguments and revive to `null` (handled gracefully by the validator). To keep
+  the field's **type** even when the generator can't be revived, every function
+  is sampled at serialization time (closures are still live) and its inferred
+  output type is recorded as `dataType` on the serialized object (e.g.
+  `{ functionName: "weighNumRange", args: [], dataType: "number" }`).
+  **Credentials (`token`, `serviceAccount`, `serviceSecret`, `projectId`,
+  `secret`) are stripped by default** so tokens never leak into JSON — pass
+  `{ includeCredentials: true }` to keep them.
+- **`DungeonJSON`, `DungeonComments`, and `SerializedFunction` types** in
+  `types.d.ts` — the JSON-representation shapes are now formally specced.
+- **`extractComments(input)`** export. Pulls the human-readable doc blocks out of
+  a dungeon's **source** — the `// ── OVERVIEW ──` and `// ── HOOK STORIES ──`
+  blocks plus every other `// ── LABEL ──` header that is immediately followed by
+  a block comment. Returns `{ overview, hookStories, sections }` with the comment
+  scaffolding (`// ──`, `/* */`, leading ` * `) stripped to readable prose.
+  Operates on a file path or raw source string — it never imports the dungeon,
+  since importing discards comments. Best effort: relies on the canonical
+  header + block-comment convention emitted by the `create-dungeon` /
+  `write-hooks` skills.
+
+### Changed
+
+- **`scripts/dungeon-to-json.mjs`** is now a thin CLI wrapper over the exported
+  `dungeonToJSON` (passing `includeCredentials: true` to preserve its legacy
+  full-config UI round-trip output). The inline `convertToJSON` /
+  `convertFunctionToObject` logic moved into `lib/core/dungeon-to-json.js`.
+
+### Why
+
+The package could ingest JSON dungeons (`parseJSONDungeon`, `loadFromFile`,
+`loadFromText`) but had no exported way to go the other direction, and no way to
+programmatically read a dungeon's OVERVIEW / HOOK STORIES documentation. Both
+existed only as un-importable script internals. Exporting them completes
+best-effort JSON interop and lets tools (UIs, LLM pipelines) read dungeon docs
+directly.
+
 ## 1.5.2 — 2026-05-21
 
 Docs-only patch. Aligns the `.claude/skills/` authoring + verification

package/README.md

@@ -155,6 +155,32 @@ import { createTextGenerator, generateBatch } from '@ak--47/dungeon-master/text'
 
 these are the same functions used internally. `pickAWinner` creates weighted distributions, `weighNumRange` generates realistic numeric ranges with configurable skew, and the text generators produce organic-looking strings with sentiment analysis and keyword injection.
 
+### named exports
+
+alongside the default `DUNGEON_MASTER` export, the package root exports loader + interop helpers:
+
+```javascript
+import DUNGEON_MASTER, {
+    loadFromFile,          // (path)            → Promise<Dungeon>   load+validate a .js/.mjs/.json dungeon
+    loadFromText,          // (code)            → Promise<Dungeon>   load+validate a raw JS source string
+    parseJSONDungeon,      // (json)            → Dungeon            revive a JSON dungeon into a runnable config
+    validateDungeonShape,  // (config)          → void               throw if config isn't dungeon-shaped
+    dungeonToJSON,         // (input, options?) → Promise<DungeonJSON>     serialize a dungeon → JSON (inverse of parseJSONDungeon)
+    extractComments,       // (input)           → DungeonComments    pull OVERVIEW / HOOK STORIES doc blocks from source
+} from '@ak--47/dungeon-master';
+```
+
+`dungeonToJSON` accepts a config object, a file path, raw JS source, or an array of paths, and returns the `{ schema, hooks, timestamp, version }` wrapper format. it round-trips with `parseJSONDungeon`:
+
+```javascript
+const json   = await dungeonToJSON('./dungeons/vertical/ecommerce.js');  // creds stripped by default
+const config = parseJSONDungeon(json);                                   // back to a runnable dungeon
+```
+
+it's best effort — arrow functions and `chance.*` methods survive the round trip; detected utility calls (`weighArray`, `weighNumRange`, …) serialize by name without their args. pass `{ includeCredentials: true }` to keep `token` / `serviceAccount` / etc. in the output (stripped by default).
+
+`extractComments` reads a dungeon's **source** (file path or raw text — never the imported module, since importing discards comments) and returns `{ overview, hookStories, sections }` with the comment scaffolding stripped to readable prose.
+
 ## how it works
 
 one call to `DUNGEON_MASTER(config)` runs through these phases in order:

package/index.js

@@ -15,6 +15,8 @@ import { createContext, updateContextWithStorage } from './lib/core/context.js';
 import { validateDungeonConfig } from './lib/core/config-validator.js';
 import { StorageManager } from './lib/core/storage.js';
 import { detectInputType, loadFromFile, loadFromText, parseJSONDungeon, validateDungeonShape } from './lib/core/dungeon-loader.js';
+import { dungeonToJSON } from './lib/core/dungeon-to-json.js';
+import { extractComments } from './lib/core/extract-comments.js';
 
 // Orchestrators
 import { userLoop } from './lib/orchestrators/user-loop.js';
@@ -597,5 +599,5 @@ function extractStorageData(storage) {
 
 // ES Module exports
 export default DUNGEON_MASTER;
-export { parseJSONDungeon, validateDungeonShape, loadFromFile, loadFromText };
+export { parseJSONDungeon, validateDungeonShape, loadFromFile, loadFromText, dungeonToJSON, extractComments };
 

package/lib/core/dungeon-to-json.js

@@ -0,0 +1,220 @@
+/**
+ * dungeon → JSON serialization.
+ *
+ * The inverse of `parseJSONDungeon` (lib/core/dungeon-loader.js): turns a runnable
+ * dungeon into the UI/JSON wrapper format `{ schema, hooks, timestamp, version }`.
+ * Functions in the schema are serialized to `{ functionName, body }` / `{ functionName, args }`
+ * objects that `reviveJSONConfig` knows how to revive — so the output round-trips:
+ *
+ *   parseJSONDungeon(await dungeonToJSON(cfg))  →  runnable config
+ *
+ * This is BEST EFFORT. Arrow functions and bound `chance.*` methods round-trip cleanly;
+ * detected utility calls (weighArray, weighNumRange, …) are serialized without their
+ * arguments and revive to null, which the config validator handles gracefully.
+ *
+ * To preserve the field's TYPE even when the generator can't be revived, every function
+ * is sampled at serialization time (when its closure is still live) and the inferred
+ * output type is recorded as `dataType` (e.g. "number", "string", "boolean", "number[]").
+ * So a field that loses its `weighNumRange(1,10)` generator still records `dataType: "number"`.
+ */
+
+import { detectInputType, loadFromFile, loadFromText } from './dungeon-loader.js';
+
+/** Credential keys stripped from JSON output unless `includeCredentials` is set. */
+const CREDENTIAL_KEYS = ['token', 'serviceAccount', 'serviceSecret', 'projectId', 'secret'];
+
+/**
+ * Convert a dungeon into its JSON representation.
+ *
+ * Accepts the same input flavors as the default export: a config object, a path to a
+ * `.js`/`.mjs`/`.json` dungeon file, a raw JS source string (must `export default`), or
+ * an array of file paths (returns an array of results).
+ *
+ * @param {import('../../types').Dungeon | string | string[]} input
+ * @param {{ includeCredentials?: boolean }} [options]
+ * @returns {Promise<import('../../types').DungeonJSON | import('../../types').DungeonJSON[]>}
+ */
+export async function dungeonToJSON(input, options = {}) {
+	const { includeCredentials = false } = options;
+	const { type, value } = detectInputType(input);
+
+	switch (type) {
+		case 'object':
+			return serializeConfig(value, includeCredentials);
+		case 'file':
+			return serializeConfig(await loadFromFile(value), includeCredentials);
+		case 'text':
+			return serializeConfig(await loadFromText(value), includeCredentials);
+		case 'files':
+			return Promise.all(
+				value.map(async (p) => serializeConfig(await loadFromFile(p), includeCredentials))
+			);
+		default:
+			throw new Error(`dungeon-master: dungeonToJSON cannot handle input type "${type}".`);
+	}
+}
+
+/**
+ * Build the `{ schema, hooks, timestamp, version }` wrapper from a runnable config.
+ * @param {import('../../types').Dungeon} config
+ * @param {boolean} includeCredentials
+ * @returns {import('../../types').DungeonJSON}
+ */
+function serializeConfig(config, includeCredentials) {
+	// Hook may be a live function (from .js/text/object) or already a string (from .json).
+	const hook = config.hook;
+	const hooks = typeof hook === 'function'
+		? hook.toString()
+		: (typeof hook === 'string' ? hook : null);
+
+	// Strip the hook (serialized separately) and, by default, credentials (don't leak tokens).
+	const cleanConfig = { ...config };
+	delete cleanConfig.hook;
+	if (!includeCredentials) {
+		for (const key of CREDENTIAL_KEYS) delete cleanConfig[key];
+	}
+
+	return {
+		schema: convertToJSON(cleanConfig),
+		hooks,
+		timestamp: new Date().toISOString(),
+		version: '4.0'
+	};
+}
+
+/**
+ * Convert a JavaScript value to a JSON-serializable form, turning functions into
+ * `{ functionName, body | args }` objects that `reviveJSONConfig` can revive.
+ * @param {any} value
+ * @returns {any}
+ */
+export function convertToJSON(value) {
+	// Null/undefined
+	if (value === null || value === undefined) {
+		return null;
+	}
+
+	// Primitives
+	if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+		return value;
+	}
+
+	// Functions - convert to object representation
+	if (typeof value === 'function') {
+		return convertFunctionToObject(value);
+	}
+
+	// Arrays
+	if (Array.isArray(value)) {
+		return value.map(item => convertToJSON(item));
+	}
+
+	// Objects
+	if (typeof value === 'object') {
+		const result = {};
+		for (const [key, val] of Object.entries(value)) {
+			result[key] = convertToJSON(val);
+		}
+		return result;
+	}
+
+	// Fallback
+	return null;
+}
+
+/**
+ * Convert a function to its object representation.
+ * Arrow functions and bound `chance.*` methods round-trip cleanly; detected utility
+ * functions are stored by name without args (best effort). Every form also carries a
+ * sampled `dataType` so the field's output type survives even when the generator can't.
+ * @param {Function} func
+ * @returns {import('../../types').SerializedFunction}
+ */
+function convertFunctionToObject(func) {
+	const funcString = func.toString();
+	// Sample now, while the closure is still live — the only reliable time to learn the type.
+	const dataType = inferDataType(func);
+
+	// Arrow function
+	if (funcString.startsWith('(') || funcString.startsWith('_') || funcString.includes('=>')) {
+		return withDataType({ functionName: 'arrow', body: funcString }, dataType);
+	}
+
+	// Bound chance methods (e.g., chance.name.bind(chance))
+	if (funcString.includes('.bind(')) {
+		const match = funcString.match(/chance\.(\w+)\.bind/);
+		if (match) {
+			return withDataType({ functionName: `chance.${match[1]}`, args: [] }, dataType);
+		}
+	}
+
+	// Try to detect common utility functions
+	// This is a best-effort approach - some complex functions might not be detected
+	const commonFunctions = [
+		'weighNumRange',
+		'weighArray',
+		'weighChoices',
+		'pickAWinner',
+		'date',
+		'integer',
+		'uid',
+		'comma'
+	];
+
+	for (const fnName of commonFunctions) {
+		if (funcString.includes(fnName)) {
+			// Args can't be recovered from a stringified function, but dataType is captured.
+			return withDataType({ functionName: fnName, args: [] }, dataType);
+		}
+	}
+
+	// Generic function - just store as arrow function
+	return withDataType({ functionName: 'arrow', body: funcString }, dataType);
+}
+
+/**
+ * Attach a `dataType` field if one was inferred (omitted otherwise).
+ * @param {import('../../types').SerializedFunction} obj
+ * @param {string | undefined} dataType
+ * @returns {import('../../types').SerializedFunction}
+ */
+function withDataType(obj, dataType) {
+	if (dataType) obj.dataType = dataType;
+	return obj;
+}
+
+/**
+ * Sample a function (no args) and classify its return type. Best effort — returns
+ * undefined if the call throws or yields an indeterminate value.
+ * @param {Function} func
+ * @returns {string | undefined}
+ */
+function inferDataType(func) {
+	let value;
+	try {
+		value = func();
+	} catch {
+		return undefined;
+	}
+	return classifyValue(value);
+}
+
+/**
+ * Map a sampled value to a type label: "number" | "string" | "boolean" | "date" |
+ * "object" | "<elementType>[]" | "array". Returns undefined for null/undefined/functions.
+ * @param {any} value
+ * @returns {string | undefined}
+ */
+function classifyValue(value) {
+	if (value === null || value === undefined) return undefined;
+	if (Array.isArray(value)) {
+		const el = value.find((v) => v !== null && v !== undefined);
+		const elType = el === undefined ? undefined : classifyValue(el);
+		return elType ? `${elType}[]` : 'array';
+	}
+	if (value instanceof Date) return 'date';
+	const t = typeof value;
+	if (t === 'number' || t === 'string' || t === 'boolean') return t;
+	if (t === 'object') return 'object';
+	return undefined;
+}

package/lib/core/extract-comments.js

@@ -0,0 +1,120 @@
+/**
+ * Best-effort extraction of the human-readable doc blocks from a dungeon's SOURCE.
+ *
+ * Generated/authored dungeons separate sections with box-drawing headers followed by a
+ * block comment, e.g.:
+ *
+ *   // ── OVERVIEW ──
+ *   /* ... *\/
+ *   // ── HOOK STORIES ──
+ *   /* ... *\/
+ *
+ * This pulls those blocks out as cleaned prose. It operates on RAW SOURCE TEXT — it never
+ * imports the dungeon, because importing a module discards its comments.
+ *
+ * Returns `{ overview, hookStories, sections }`:
+ *   - `overview`    — cleaned text of the OVERVIEW block (or null)
+ *   - `hookStories` — cleaned text of the HOOK STORIES block (or null)
+ *   - `sections`    — every `// ── LABEL ──` header that is immediately followed by a
+ *                     block comment, keyed by the exact label as written.
+ */
+
+import { readFileSync } from 'fs';
+import { detectInputType } from './dungeon-loader.js';
+
+// A `// ── LABEL ──` header line. Anchored to `//` at line start so that the inner
+// ` * ───────` dividers inside a block comment are NOT mistaken for section headers.
+const HEADER_RE = /^[ \t]*\/\/[ \t]*─+[ \t]*(.+?)[ \t]*─+[ \t]*$/gm;
+
+/**
+ * @param {string | string[]} input - A dungeon file path, raw dungeon source, or array of paths.
+ * @returns {import('../../types').DungeonComments | import('../../types').DungeonComments[]}
+ */
+export function extractComments(input) {
+	const { type, value } = detectInputType(input);
+
+	switch (type) {
+		case 'file':
+			return parseSource(readFileSync(value, 'utf-8'));
+		case 'text':
+			return parseSource(value);
+		case 'files':
+			return value.map((p) => parseSource(readFileSync(p, 'utf-8')));
+		case 'object':
+			throw new Error(
+				'dungeon-master: extractComments needs source text or a file path, not a config object (comments are lost once a dungeon is imported).'
+			);
+		default:
+			throw new Error(`dungeon-master: extractComments cannot handle input type "${type}".`);
+	}
+}
+
+/**
+ * Parse a single source string into `{ overview, hookStories, sections }`.
+ * @param {string} source
+ * @returns {import('../../types').DungeonComments}
+ */
+function parseSource(source) {
+	/** @type {Record<string, string>} */
+	const sections = {};
+
+	// Collect every header with its label and the position right after its line.
+	const headers = [];
+	HEADER_RE.lastIndex = 0;
+	let m;
+	while ((m = HEADER_RE.exec(source)) !== null) {
+		headers.push({ label: m[1].trim(), end: HEADER_RE.lastIndex });
+	}
+
+	for (let i = 0; i < headers.length; i++) {
+		const { label, end } = headers[i];
+		// Only look between this header and the next one.
+		const sliceEnd = i + 1 < headers.length ? headers[i + 1].end : source.length;
+		const slice = source.slice(end, sliceEnd);
+
+		// Accept the block only if a `/* ... */` comment is the first non-whitespace content
+		// after the header (so headers followed by code — IMPORTS, SCALE — are skipped).
+		const block = slice.match(/^\s*\/\*([\s\S]*?)\*\//);
+		if (block) {
+			sections[label] = cleanBlock(block[1]);
+		}
+	}
+
+	return {
+		overview: findSection(sections, ['OVERVIEW']),
+		hookStories: findSection(sections, ['HOOK STORIES', 'HOOK STORY']),
+		sections
+	};
+}
+
+/**
+ * Strip block-comment scaffolding (` * `) and trim blank edges, leaving readable prose.
+ * @param {string} inner - The text between `/*` and `*\/`.
+ * @returns {string}
+ */
+function cleanBlock(inner) {
+	const lines = inner
+		.split('\n')
+		// Drop a leading ` * ` (or bare ` *`) from each line; preserve content indentation.
+		.map((line) => line.replace(/^[ \t]*\*[ \t]?/, '').replace(/\s+$/, ''));
+
+	// Trim leading/trailing blank lines.
+	while (lines.length && lines[0] === '') lines.shift();
+	while (lines.length && lines[lines.length - 1] === '') lines.pop();
+
+	return lines.join('\n');
+}
+
+/**
+ * Case-insensitive lookup of the first matching label.
+ * @param {Record<string, string>} sections
+ * @param {string[]} candidates
+ * @returns {string | null}
+ */
+function findSection(sections, candidates) {
+	const wanted = candidates.map((c) => c.toUpperCase());
+	for (const [label, text] of Object.entries(sections)) {
+		if (wanted.includes(label.toUpperCase())) return text;
+	}
+	return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.5.2",
+	"version": "1.5.3",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -107,4 +107,4 @@
 			"tmp/"
 		]
 	}
-}
+}

package/scripts/dungeon-to-json.mjs

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * Converts a JavaScript dungeon file to JSON that can be loaded into the UI
+ * Converts a JavaScript dungeon file to JSON that can be loaded into the UI.
+ * Thin CLI wrapper around the exported `dungeonToJSON` (lib/core/dungeon-to-json.js).
  * Usage: node scripts/dungeon-to-json.js <input.js> [output-name]
  */
 
 import { writeFileSync } from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { dungeonToJSON } from '../lib/core/dungeon-to-json.js';
 
 // Get command line arguments
 const args = process.argv.slice(2);
@@ -25,34 +24,10 @@ const inputPath = path.resolve(args[0]);
 const outputName = args[1] || path.basename(inputPath, '.js');
 
 try {
-    // Import the JavaScript module
     console.log(`📖 Loading ${inputPath}...`);
-    const module = await import(`file://${inputPath}`);
-    const config = module.default;
-
-    if (!config) {
-        throw new Error('No default export found in the module');
-    }
-
-    // Extract hooks if they exist
-    const hooksFunction = config.hook;
-    const hooksString = hooksFunction ? hooksFunction.toString() : null;
-
-    // Create a clean config without the hook function
-    const cleanConfig = { ...config };
-    delete cleanConfig.hook;
-
-    // Convert to JSON-serializable format
     console.log('🔄 Converting to JSON format...');
-    const schema = convertToJSON(cleanConfig);
-
-    // Create the dungeon state object (same format as UI saves)
-    const dungeonState = {
-        schema,
-        hooks: hooksString,
-        timestamp: new Date().toISOString(),
-        version: '4.0'
-    };
+    // includeCredentials: true preserves the legacy UI round-trip behavior (full config).
+    const dungeonState = await dungeonToJSON(inputPath, { includeCredentials: true });
 
     // Write to JSON file
     const outputPath = path.join(path.dirname(inputPath), `${outputName}.json`);
@@ -67,97 +42,3 @@ try {
     console.error(error.stack);
     process.exit(1);
 }
-
-/**
- * Convert JavaScript config to JSON-serializable format
- * Detects functions and converts them to object representation
- */
-function convertToJSON(value) {
-    // Null/undefined
-    if (value === null || value === undefined) {
-        return null;
-    }
-
-    // Primitives
-    if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
-        return value;
-    }
-
-    // Functions - convert to object representation
-    if (typeof value === 'function') {
-        return convertFunctionToObject(value);
-    }
-
-    // Arrays
-    if (Array.isArray(value)) {
-        return value.map(item => convertToJSON(item));
-    }
-
-    // Objects
-    if (typeof value === 'object') {
-        const result = {};
-        for (const [key, val] of Object.entries(value)) {
-            result[key] = convertToJSON(val);
-        }
-        return result;
-    }
-
-    // Fallback
-    return null;
-}
-
-/**
- * Convert a function to its object representation
- * Tries to detect the function type and extract parameters
- */
-function convertFunctionToObject(func) {
-    const funcString = func.toString();
-
-    // Arrow function
-    if (funcString.startsWith('(') || funcString.startsWith('_') || funcString.includes('=>')) {
-        return {
-            functionName: 'arrow',
-            body: funcString
-        };
-    }
-
-    // Bound chance methods (e.g., chance.name.bind(chance))
-    if (funcString.includes('.bind(')) {
-        const match = funcString.match(/chance\.(\w+)\.bind/);
-        if (match) {
-            return {
-                functionName: `chance.${match[1]}`,
-                args: []
-            };
-        }
-    }
-
-    // Try to detect common utility functions
-    // This is a best-effort approach - some complex functions might not be detected
-    const commonFunctions = [
-        'weighNumRange',
-        'weighArray',
-        'weighChoices',
-        'pickAWinner',
-        'date',
-        'integer',
-        'uid',
-        'comma'
-    ];
-
-    for (const fnName of commonFunctions) {
-        if (funcString.includes(fnName)) {
-            // Extract args (this is simplified - real parsing would be more complex)
-            return {
-                functionName: fnName,
-                args: [] // Args would need to be extracted, but that's complex
-            };
-        }
-    }
-
-    // Generic function - just store as arrow function
-    return {
-        functionName: 'arrow',
-        body: funcString
-    };
-}

package/types.d.ts

@@ -1508,6 +1508,79 @@ export declare function parseJSONDungeon(json: object): Dungeon;
 /** Validate that an object has the minimum shape of a dungeon config. Throws on shape violations. */
 export declare function validateDungeonShape(config: unknown): void;
 
+/**
+ * The serialized form of a function found in a dungeon schema. Produced by `dungeonToJSON`
+ * and revived by `parseJSONDungeon`.
+ *
+ * - `functionName: "arrow"` with a `body` — an inline/closure function, re-eval'd on revive.
+ * - `functionName: "chance.<method>"` — a bound chance method, e.g. `chance.name.bind(chance)`.
+ * - `functionName: "<utility>"` (weighNumRange, weighArray, …) — a detected utility; args are
+ *   not recoverable from the stringified source, so it revives to null (best effort).
+ *
+ * `dataType` records the function's sampled output type so the field's type is preserved even
+ * when the generator itself can't be revived.
+ */
+export interface SerializedFunction {
+	/** "arrow", "chance.<method>", or a known utility name. */
+	functionName: string;
+	/** Stringified function source (present for arrow/closure forms). */
+	body?: string;
+	/** Captured call arguments (best effort; usually empty for detected utilities). */
+	args?: unknown[];
+	/**
+	 * Inferred output type, sampled at serialization time:
+	 * "number" | "string" | "boolean" | "date" | "object" | "<elementType>[]" | "array".
+	 * Omitted when sampling failed (e.g. the function threw).
+	 */
+	dataType?: string;
+}
+
+/**
+ * The JSON/UI wrapper representation of a dungeon, as produced by `dungeonToJSON` and
+ * consumed by `parseJSONDungeon`. Functions in `schema` are serialized to
+ * {@link SerializedFunction} objects; everything else is plain JSON.
+ */
+export interface DungeonJSON {
+	/** The dungeon config with functions converted to {@link SerializedFunction} objects (hook excluded). */
+	schema: Record<string, unknown>;
+	/** The `hook` function stringified, or null if the dungeon has no hook. */
+	hooks: string | null;
+	/** ISO timestamp of when the JSON was produced. */
+	timestamp: string;
+	/** UI schema format version. */
+	version: string;
+}
+
+/** The doc blocks extracted from a dungeon's source by `extractComments`. */
+export interface DungeonComments {
+	/** Cleaned text of the `// ── OVERVIEW ──` block, or null if absent. */
+	overview: string | null;
+	/** Cleaned text of the `// ── HOOK STORIES ──` block, or null if absent. */
+	hookStories: string | null;
+	/** Every `// ── LABEL ──` header followed by a block comment, keyed by exact label. */
+	sections: Record<string, string>;
+}
+
+/**
+ * Convert a dungeon into its JSON representation (the inverse of `parseJSONDungeon`).
+ * Accepts a config object, a file path, raw JS source, or an array of file paths
+ * (returns an array). Credentials are stripped unless `includeCredentials` is set.
+ * Best effort: arrow functions and `chance.*` methods round-trip; detected utility
+ * calls lose their arguments. Always async.
+ */
+export declare function dungeonToJSON(input: Dungeon, options?: { includeCredentials?: boolean }): Promise<DungeonJSON>;
+export declare function dungeonToJSON(input: string, options?: { includeCredentials?: boolean }): Promise<DungeonJSON>;
+export declare function dungeonToJSON(input: string[], options?: { includeCredentials?: boolean }): Promise<DungeonJSON[]>;
+
+/**
+ * Extract the human-readable doc blocks (OVERVIEW, HOOK STORIES, …) from a dungeon's
+ * SOURCE. Operates on a file path or raw source string — never imports the dungeon
+ * (importing discards comments). Best effort: relies on the canonical `// ── LABEL ──`
+ * header + block-comment convention.
+ */
+export declare function extractComments(input: string): DungeonComments;
+export declare function extractComments(input: string[]): DungeonComments[];
+
 // ============= Text Generator Types =============
 
 /**