playlist-data-engine 1.7.3 → 1.8.0

package/README.md

@@ -26,6 +26,20 @@ npm install
 
 </details>
 
+### Documentation
+
+Full docs ship inside the package — no GitHub trip needed:
+
+| Where | What |
+|---|---|
+| `node_modules/playlist-data-engine/docs/` | The whole docs folder, version-matched to your install |
+| `npx playlist-data-engine docs` | List every doc — `npx playlist-data-engine docs <topic>` reads one |
+| `engineHelp()` from the package | Same index, returned as markdown — built for AI agents |
+
+**Table of contents:** [Data Engine Reference](docs/DATA_ENGINE_REFERENCE.md) (every function, one row each) · [Usage in Other Projects](docs/USAGE_IN_OTHER_PROJECTS.md) · [Playlist Parsing](docs/features/PLAYLIST_PARSING.md) (tracks, mixes, quality) · [Gateway Resolution](docs/features/GATEWAY_RESOLUTION.md) · [Audio Analysis](docs/features/AUDIO_ANALYSIS.md) · [Beat Detection](docs/features/BEAT_DETECTION.md) — plus the game systems (combat, equipment, XP, sensors, seeds) in `docs/features/`.
+
+Building with Claude or another coding agent? `npx playlist-data-engine skill` prints the companion Claude Code skill; `engineHelp('skill')` returns it from inside the package.
+
 ### The Vision: An Intelligent Music Player
 
 The original idea — five years ago — was a music player that goes beyond playing static audio. Think of how the best Nintendo games use dynamic music — different arrangements and mixes depending on what the player does. That's a whole category of experiencing recorded music, but only a handful of games have ever explored it. This engine opens that door for any music. It listens to your tracks and reacts to you — the genre, the mood, the beats, the groove, where you are, what you're doing, the weather outside, the time of day. Every song comes with a character, a combat encounter, a rhythm game chart — all generated from the music itself.

package/bin/cli.cjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Docs CLI — `npx playlist-data-engine docs [topic]`
+ *
+ * Plain CommonJS on purpose: it runs straight from the published tarball
+ * with zero dependencies and no build step.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_DIR = path.join(__dirname, '..', 'docs');
+const SKILL_PATH = path.join(__dirname, '..', 'skills', 'playlist-data-engine', 'SKILL.md');
+
+function collectDocs(dir, prefix = '') {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) out.push(...collectDocs(path.join(dir, entry.name), rel));
+        else if (entry.name.endsWith('.md')) out.push(rel);
+    }
+    return out.sort();
+}
+
+function topics() {
+    return collectDocs(DOCS_DIR).map(rel => ({
+        rel,
+        slug: rel.replace(/\.md$/i, '').replace(/^features\//, '').toLowerCase(),
+    }));
+}
+
+function usage() {
+    const list = topics().map(t => `  ${t.slug.padEnd(24)} docs/${t.rel}`).join('\n');
+    return [
+        'playlist-data-engine — docs reader',
+        '',
+        'USAGE',
+        '  npx playlist-data-engine docs            List every doc',
+        '  npx playlist-data-engine docs <topic>    Print one doc (slug or file path)',
+        '  npx playlist-data-engine skill           Print the Claude Code skill file',
+        '',
+        'TOPICS',
+        list,
+        '',
+        'Full docs also ship inside the package: node_modules/playlist-data-engine/docs/',
+    ].join('\n');
+}
+
+const [command, topic] = process.argv.slice(2);
+
+if (!command || ['-h', '--help', 'help'].includes(command)) {
+    console.log(usage());
+    process.exit(0);
+}
+
+if (command === 'skill') {
+    try {
+        console.log(fs.readFileSync(SKILL_PATH, 'utf8'));
+    } catch {
+        console.error('Skill file not found in this install (expected skills/playlist-data-engine/SKILL.md).');
+        process.exit(1);
+    }
+    process.exit(0);
+}
+
+if (command !== 'docs') {
+    console.error(`Unknown command "${command}".\n\n${usage()}`);
+    process.exit(1);
+}
+
+if (!topic) {
+    console.log(usage());
+    process.exit(0);
+}
+
+const all = topics();
+const needle = topic.toLowerCase();
+const hit =
+    all.find(t => t.slug === needle) ||
+    all.find(t => t.rel.toLowerCase() === needle) ||
+    all.find(t => t.slug.startsWith(needle));
+if (!hit) {
+    console.error(`No doc matches "${topic}".\n\n${usage()}`);
+    process.exit(1);
+}
+console.log(fs.readFileSync(path.join(DOCS_DIR, hit.rel), 'utf8'));