AGENTS.md
+67 −23
https://raw.githubusercontent.com/cxmiloxx/tourwright/HEAD/AGENTS.md
− ## Map− | `bin/tourwright.js`, `src/cli.js` | CLI |− | `src/config.js` | Every setting: defaults < the user's `config.json` < `tourwright.config.json` < `TOURWRIGHT_*` env |− | `src/settings.js` | `tourwright config`: each person's defaults (quality, voice, fps, AI…), checked before saved |− | `src/install.js` | `tourwright install`: what the PC already has first (`locate.js`: folders outside PATH), then ffmpeg, Piper, voices, edge-tts, Chromium per OS and CPU |− | `src/lock.js` | `--lock`: one browser at a time on the machine (`flock` on Linux) |− | `src/script/` | Script formats: `schema.js` (zod, declarative), `expand.js` (vars, blocks, repeat), `load.js` (files, JS modules, secrets) |− | `src/render/` | `browser.js` (walkthroughs: recording and the `v` helpers), `steps.js` (step interpreter, `if`/`try`), `targets.js` (finding elements, fallbacks, errors that list what the page offers), `chromium.js` (which browser: configured, Playwright's, the system's), `mask.js` (invented data on screen), `review.js` (what went wrong on the page and in the video), `session.js` (off-camera login, saved sessions), `cursor.js`, `visuals.js` (title cards, captions, frames, callouts, zoom), `sli− | `src/voice/` | TTS engines, prosody, pauses, pronunciation, polish presets and the sentence cache; `effects.js` (built-in sounds); `piper_voice.py` (Piper kept loaded); `piper-voices.js` (voices already on the PC) |− | `src/record.js` | `tourwright record`: the tour done by hand becomes a script with a first narration |− | `src/guide.js` | `tourwright guide`: the script as a step-by-step guide with screenshots |− | `src/narrate.js`, `src/ai.js` | `tourwright narrate`: the narration rewritten by the AI the user brings (Claude via the official SDK, OpenAI-compatible, Ollama) |− | `src/repair.js` | `tourwright check` / `fix`: broken steps across scripts and the likely new target |− | `src/plugins.js` | Loads plugins: extra step actions, TTS engines, voices |− | `src/compose.js`, `src/timeline.js` | Raw recording → final mp4 (cuts, audio mix, subtitles, chapters) |− | `src/jobs/` | Job records + queue (`store.js`: local folder / Redis), files (`blobs.js`: local / S3), signed links |− | `src/worker.js`, `src/run-job.js` | Queue consumer; each render in its own process |− | `src/server/http.js` | HTTP API |− | `src/mcp.js` | MCP server |− - No machine-specific paths: everything comes from `loadConfig()`.− - A new step action: add it to `STEPS` in `src/script/schema.js`, to `runSteps` in `src/render/browser.js`− (and a no-op or plain version in `plainHelpers` for `setup`), to `docs/SCRIPTS.md`, then `npm run schema`.− npm run check # lint (Biome) + types (tsc on JSDoc) + tests + schema in sync+ ## Architecture+ `src/` is split by domain. Each domain is a folder with an alias in `package.json` (`imports`), and a domain+ imports only from the ones below it:+ ```text+ cli, server entry points: everything below+ authoring explore, record, check/fix (repair) → ai, render, script, video, voice, core+ ai, install the user's AI; tourwright install → render, script, video, voice, core+ render the browser and what it films → plugins, script, video, voice, core+ plugins extra steps, engines and voices → script, voice, core+ video ffmpeg: compose, loudness, review → voice, core+ script, voice script formats; text-to-speech → core+ core config, util, secrets, locks, paths → nothing+ ```+ | `bin/tourwright.js` | Calls `#cli/index.js` |+ | `src/index.js` | The library API (`import { render } from 'tourwright'`) |+ | `src/core/` | `config.js` (every setting: defaults < the user's `config.json` < `tourwright.config.json` < `TOURWRIGHT_*` env), `util.js`, `secrets.js`, `lock.js` (`--lock`: one browser at a time), `locate.js` (programs outside PATH), `paths.js` (the package root, its docs and version) |+ | `src/script/` | Script formats: `schema.js` (zod, declarative), `expand.js` (vars, blocks, repeat), `load.js` (files, JS modules, secrets), `mask-rule.js` |+ | `src/voice/` | Text-to-speech: `voices.js` (which voice, aliases, auto), `text.js` (pauses, marks, pronunciation), `sound.js` (polish presets, prosody filters), `narrate.js` (synthesis and sentence cache), `samples.js` (listing, samples), `engines.js`, `lexicon.js`, `effects.js` (built-in sounds), `python.js` (the Python helpers' processes), `piper_voice.py` (Piper kept loaded), `pocket.py`, `piper-voices.js`, `calibrated.json` (loudness per voice) |+ | `src/video/` | ffmpeg: `compose.js` (raw recording → mp4: cuts, mix, subtitles, chapters), `loudness.js` (each sentence leveled, true-peak limiter), `timeline.js`, `frame-filter.js`, `review.js` (blank screens, silence, loudness, clipping), `recompose.js` (`--keep` and `tourwright recompose`), `ffmpeg.js` (running ffmpeg), `quality.js` (encoding presets) |+ | `src/plugins/` | Loads plugins: extra step actions, TTS engines, voices |+ | `src/render/` | `index.js` (one entry for every kind of video), `slides.js` |+ | `src/render/walkthrough/` | A filmed walkthrough, one stage per module: `index.js` (runs them in order), `plan.js` (size, device, voice, capture; `DEVICES`), `studio.js` (browser, off-camera login, dressed page, recording), `clock.js` (captions, chapters, cuts, narration, effects), `stage.js` (what every filmed step shares), `helpers/` (the `v` helpers: `navigation`, `narration`, `pointer`, `camera`), `deliver.js` (compose, review, `--keep`) |+ | `src/render/steps/` | `index.js` (step interpreter, `if`/`try`), `targets.js` (finding elements: exact and visible first, `mask`, errors that list what the page offers), `lists.js` (lists that are not a `<select>`), `quick.js` (the quick helpers for `setup`) |+ | `src/render/browser/` | `chromium.js` (which browser), `launch.js`, `capture.js` (Xvfb / screencast), `network.js` (sandbox, host remapping), `guard-proxy.js` (the strict sandbox: every connection checked, redirects and WebSockets too), `session.js` (off-camera login, saved sessions) |+ | `src/render/page/` | What Tourwright draws or watches on the page: `visuals.js`, `cursor.js`, `overlay.js` + `theme.js`, `frame.js`, `mask.js`, `review.js` (page errors, clicks without effect, layout) |+ | `src/render/guide/` | `tourwright guide`: `collect.js` (a picture of each step), `write.js` (HTML and Markdown) |+ | `src/ai/` | The AI the user brings: `client.js` (Claude via the official SDK, OpenAI-compatible, Ollama), `narrate.js`, `translate.js` |+ | `src/authoring/` | Writing scripts: `explore/` (a site's sections and targets, `--draft`), `record/` (a tour done by hand becomes a script), `repair.js` (`check` / `fix`) |+ | `src/install/` | `tourwright install`: `plan.js`, `parts.js` (ffmpeg, Piper, voices, edge-tts, Chromium), `python.js` (the venv), `download.js`, `sources.js` (pinned URLs and hashes), `clean.js` |+ | `src/server/` | `http.js` (HTTP API), `mcp.js` (MCP server), `worker.js` + `run-job.js` (queue consumer; each render in its own process), `jobs/` (`service.js` jobs and queue, `store.js` records, `blobs.js` files on disk or S3, `links.js` signed links) |+ | `src/cli/` | `index.js` reads the options (`args.js`) and hands each command to its group in `commands/` (`videos`, `sites`, `voices`, `machine`); `help.js`, `doctor.js`, `progress.js`, `settings.js` (`tourwright config`) |+ | `scripts/check-architecture.js` | The rules below that a machine can check, run by `npm run check` |+ ## Where new code goes+ | Adding… | Goes in |+ |---|---|+ | A step action | `script/schema.js` + `render/steps/index.js` + a helper in `render/walkthrough/helpers/` (see Rules) |+ | How an element is found | `render/steps/targets.js` |+ | Something drawn on or read from the page | `render/page/` (one file per thing) |+ | Browser start, capture, network, login | `render/browser/` |+ | A stage of a filmed video (before/after the steps) | `render/walkthrough/` |
Showing the first 40 of each.