diff --git a/README.md b/README.md index 09f8c8c..0218da0 100644 --- a/README.md +++ b/README.md @@ -46,43 +46,43 @@ The output is **one `.html` file**. No server. No build step. Drag it into a bro ## Install -### With npm / npx (recommended) +Free, and hosted only on GitHub — no npm package to install. -No install needed — run it on demand with `npx` (requires [Node.js](https://nodejs.org) ≥ 18): +### Clone + wire the adapter (recommended) -```bash -# Wire the AI adapter into your current project (auto-detects Claude Code, Cursor, Codex) -npx think-in-html init -``` - -Or install it globally to use the `think-in-html` command anywhere: +Requires [Node.js](https://nodejs.org) ≥ 18: ```bash -npm install -g think-in-html +git clone https://github.com/vibhusharma101/Think-In-HTML.git +node Think-In-HTML/bin/cli.mjs init ``` -That's the whole setup. The package contains the engine; your AI tool calls it via -`npx think-in-html` under the hood — nothing is copied into your repo. +`init` auto-detects your AI tool (Claude Code, Cursor, Codex), copies the engine into +`think-in-html/core/` in your project, and wires up the adapter. Nothing else to configure. -### CLI commands +### One-liner (no manual clone step) ```bash -think-in-html init # wire the adapter into this project -think-in-html instructions code # print freeform generation guidance (code|thinking|text) -think-in-html instructions code --blocks # print the legacy schema/blocks guidance instead -think-in-html check output.html # verify a generated file is self-contained -think-in-html build analysis.json -o output.html # build HTML from JSON (--blocks mode only) -think-in-html --help +curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash ``` -### Without npm (curl one-liner) +Does the same thing as `init` above — clones the repo to a temp dir, copies the engine into +`think-in-html/core/` in your current project, and wires up whichever AI tool it detects. -No Node? This copies the engine + adapter into your project: +### CLI commands (run from inside the clone) ```bash -curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash +node bin/cli.mjs init # wire the adapter into this project +node bin/cli.mjs instructions code # print freeform generation guidance (code|thinking|text) +node bin/cli.mjs instructions code --blocks # print the legacy schema/blocks guidance instead +node bin/cli.mjs check output.html # verify a generated file is self-contained +node bin/cli.mjs build analysis.json -o output.html # build HTML from JSON (--blocks mode only) +node bin/cli.mjs --help ``` +Want the shorter `think-in-html ` form? Add a shell alias: +`alias think-in-html="node $(pwd)/Think-In-HTML/bin/cli.mjs"`. + ## Usage ### Claude Code @@ -195,7 +195,8 @@ The [schema reference](docs/schema-reference.md) documents the `analysis.json` c ## Maintainers -Publishing a new version to npm? See [PUBLISHING.md](PUBLISHING.md). +npm publishing is paused for now — the repo itself is the distribution channel (see +[Install](#install) above). [PUBLISHING.md](PUBLISHING.md) is kept for when that resumes. ## License diff --git a/adapters/README.md b/adapters/README.md index 977f538..ef42602 100644 --- a/adapters/README.md +++ b/adapters/README.md @@ -12,13 +12,16 @@ This folder contains **reference copies** and installation guides for each suppo ## Automatic installation -The recommended way (requires Node.js ≥ 18) auto-detects your tools and writes the adapter: +No npm package — clone the repo (requires Node.js ≥ 18) and let the CLI auto-detect your +tools and write the adapter: ```bash -npx think-in-html init +git clone https://github.com/vibhusharma101/Think-In-HTML.git +node Think-In-HTML/bin/cli.mjs init ``` -No Node? The curl one-liner copies the engine + adapter into your project instead: +Or the curl one-liner, which does the same thing without a manual clone step — copies the +engine + adapter into your project: ```bash curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash @@ -30,12 +33,9 @@ To support a new AI coding tool: 1. Create a folder under `adapters/` with the tool name 2. Write an adapter that tells the tool to: - - Run `npx think-in-html instructions ` and follow it (it prints the analysis guide + schema) - - Produce JSON conforming to that schema and write it to `analysis.json` - - Run `npx think-in-html build analysis.json -o output.html` -3. Add detection for the tool to the `init` command in `bin/cli.mjs` + - Read `core/instructions/FREEFORM.md` and `core/instructions/mode-.md` and follow them + - Write a complete self-contained `output.html`, then run `node core/build/check-html.mjs output.html` and fix any reported error +3. Add detection for the tool to the `cmdInit` function in `bin/cli.mjs` 4. Open a PR -The adapter is always thin — it only tells the tool *which CLI commands to run*. All logic lives in `core/`. - The adapter is always thin — it only tells the tool *where to find the instructions*. All logic lives in `core/`. diff --git a/adapters/claude-code/SKILL.md b/adapters/claude-code/SKILL.md index 9f7338a..f73bc1c 100644 --- a/adapters/claude-code/SKILL.md +++ b/adapters/claude-code/SKILL.md @@ -8,15 +8,22 @@ Claude Code loads skills from `.claude/commands/` in your project root. When a u ## Installation -Recommended — wire the adapter automatically: +No npm package — clone the repo and let the CLI wire the adapter automatically: ```bash -npx think-in-html init +git clone https://github.com/vibhusharma101/Think-In-HTML.git +node Think-In-HTML/bin/cli.mjs init ``` -This writes `.claude/commands/think-in-html.md` pointing at the `npx think-in-html` CLI -(`instructions` to read the analysis guide, `build` to produce the HTML). Nothing is copied -into your repo. +Or the curl one-liner (no manual clone step): + +```bash +curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash +``` + +Either copies the engine into `think-in-html/core/` in your project and writes +`.claude/commands/think-in-html.md` pointing at it directly via `node` — nothing to install +globally. ## Usage diff --git a/adapters/codex/AGENTS.md b/adapters/codex/AGENTS.md index 08a0a0a..c2e1bc2 100644 --- a/adapters/codex/AGENTS.md +++ b/adapters/codex/AGENTS.md @@ -8,13 +8,22 @@ Codex reads `AGENTS.md` in your project root. The Think-In-HTML instructions tel ## Installation -Recommended — append the adapter automatically (run in a project that has an `AGENTS.md`): +Recommended — clone the repo and let the CLI wire the adapter (no npm package needed): ```bash -npx think-in-html init +git clone https://github.com/vibhusharma101/Think-In-HTML.git +node Think-In-HTML/bin/cli.mjs init ``` -This appends the section below. To do it by hand, add this to your `AGENTS.md`: +Or the curl one-liner (no manual clone step): + +```bash +curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash +``` + +Either copies the engine into `think-in-html/core/` in your project and appends the section +below to `AGENTS.md`. To do it by hand instead, add this (adjusting the `core/` paths to +wherever you placed the engine): --- @@ -22,10 +31,12 @@ This appends the section below. To do it by hand, add this to your `AGENTS.md`: When asked to generate an interactive HTML lesson: -1. Run `npx think-in-html instructions code` (or `thinking` / `text`) and follow it — it prints - the analysis guide and the schema. -2. Think like a teacher and compose teaching blocks; write valid JSON to `analysis.json`. -3. Run `npx think-in-html build analysis.json -o output.html`. +1. Read `core/instructions/ANALYZE.md` and `core/instructions/mode-code.md` (or + `mode-thinking.md` / `mode-text.md`) and follow them — the analysis guide and + input-type guidance. +2. Think like a teacher and compose teaching blocks; write valid JSON to `analysis.json` + conforming to `core/schema/analysis.schema.json`. +3. Run `node core/build/inline.mjs analysis.json -o output.html`. Rules: - Teacher voice — explain like the reader has never seen the code before diff --git a/bin/cli.mjs b/bin/cli.mjs index 14e72b9..422f7d0 100644 --- a/bin/cli.mjs +++ b/bin/cli.mjs @@ -9,7 +9,7 @@ // // Zero npm dependencies — Node stdlib only. -import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'fs'; +import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, cpSync } from 'fs'; import { resolve, dirname, join } from 'path'; import { fileURLToPath } from 'url'; import { inlineToFile } from '../core/build/inline.mjs'; @@ -18,6 +18,9 @@ import { checkSelfContained } from '../core/build/check-html.mjs'; const __dirname = dirname(fileURLToPath(import.meta.url)); const PKG_ROOT = resolve(__dirname, '..'); const CORE = resolve(PKG_ROOT, 'core'); +const CLAUDE_ADAPTER_SRC = resolve(PKG_ROOT, '.claude', 'commands', 'think-in-html.md'); +const CURSOR_ADAPTER_SRC = resolve(PKG_ROOT, '.cursor', 'rules', 'think-in-html.mdc'); +const CODEX_ADAPTER_SRC = resolve(PKG_ROOT, 'adapters', 'codex', 'AGENTS.md'); function version() { try { @@ -27,6 +30,9 @@ function version() { const HELP = `Think-In-HTML — turn code, thinking, or text into one bespoke interactive HTML lesson +No npm package — clone the repo and run this file directly: + node bin/cli.mjs + Usage: think-in-html instructions [code|thinking|text] [--blocks] Print generation instructions think-in-html check Verify a file is self-contained @@ -115,68 +121,18 @@ function cmdCheck(args) { } // ── init ── -const CLAUDE_ADAPTER = `# /think-in-html - -Generate a bespoke, interactive HTML explainer from code, an AI thinking transcript, or -text — a different design and a different working interactive model every time. The -output is one self-contained \`.html\` file. - -## Arguments -$ARGUMENTS — target file/folder to explain. Optional \`--mode code|thinking|text\` (default -code). Optional \`--blocks\` to use the legacy templated engine instead. - -## Default flow — Freeform (author the whole page) -1. Run \`npx think-in-html instructions \` and follow \`FREEFORM.md\` exactly: read the - target's real logic, pick the one mechanic to make tangible, choose a bespoke design - from the domain, and write a complete self-contained \`output.html\` (inline CSS/JS, the - CSP meta tag, no external resources). -2. Verify: \`npx think-in-html check output.html\`. Fix any reported error and re-check. -3. Tell the user where the file is and what the interactive centerpiece lets them do. - -## Legacy flow — Blocks (\`--blocks\`) -1. Run \`npx think-in-html instructions --blocks\` and follow it exactly. -2. Compose an ordered list of teaching blocks; write valid JSON to \`analysis.json\` - (schemaVersion 2). -3. Run \`npx think-in-html build analysis.json -o output.html\`. -4. Tell the user where the output is, and that they can switch skins in the top-right. -`; - -const CURSOR_ADAPTER = `--- -description: Generate a bespoke interactive HTML explainer from code, thinking, or text — a different design and interactive model every time. Use when asked to explain code visually or create an interactive walkthrough. -alwaysApply: false ---- - -# Think-In-HTML - -Default — Freeform (author the whole page): -1. Run \`npx think-in-html instructions code\` (or \`thinking\` / \`text\`) and follow - \`FREEFORM.md\`: real logic, one tangible mechanic, a bespoke design, one self-contained - \`output.html\`. -2. Verify with \`npx think-in-html check output.html\`; fix and re-check on error. -3. Tell the user where the output is. - -Legacy — Blocks (\`--blocks\`, only if asked for the templated engine): -1. Run \`npx think-in-html instructions code --blocks\` and follow it. -2. Compose teaching blocks; write valid JSON to \`analysis.json\`. -3. Run \`npx think-in-html build analysis.json -o output.html\`. -`; +// Adapter content is read from the real per-tool files (dogfooded inside this +// repo, where `core/` sits at the repo root) and reference-rewritten to +// `think-in-html/core/` — where copyCore() below places the engine inside an +// external project. Mirrors install.sh's `sed 's|core/|think-in-html/core/|g'` +// so the CLI and the curl installer never drift apart again. +function rewriteCorePaths(content) { + return content.replace(/core\//g, 'think-in-html/core/'); +} -const CODEX_ADAPTER = ` -### Think-In-HTML - -Default — Freeform (author the whole page, a different design + interactive model -every time): -1. Run \`npx think-in-html instructions code\` (or \`thinking\` / \`text\`) and follow - \`FREEFORM.md\`. -2. Write one self-contained \`output.html\` with the real subject's logic driving an - interactive centerpiece. -3. Verify with \`npx think-in-html check output.html\`; fix and re-check on error. - -Legacy — Blocks (\`--blocks\`, only if asked for the templated engine): -1. Run \`npx think-in-html instructions code --blocks\` and follow it. -2. Compose teaching blocks and write valid JSON to \`analysis.json\`. -3. Run \`npx think-in-html build analysis.json -o output.html\`. -`; +function copyCore(cwd) { + cpSync(CORE, join(cwd, 'think-in-html', 'core'), { recursive: true }); +} function writeFileSafe(path, content) { mkdirSync(dirname(path), { recursive: true }); @@ -188,29 +144,44 @@ function cmdInit() { let installed = false; console.log(`Wiring Think-In-HTML into: ${cwd}\n`); + copyCore(cwd); + if (existsSync(join(cwd, '.claude'))) { - writeFileSafe(join(cwd, '.claude', 'commands', 'think-in-html.md'), CLAUDE_ADAPTER); + writeFileSafe( + join(cwd, '.claude', 'commands', 'think-in-html.md'), + rewriteCorePaths(readFileSync(CLAUDE_ADAPTER_SRC, 'utf-8')), + ); console.log(' ✓ Claude Code: .claude/commands/think-in-html.md'); installed = true; } if (existsSync(join(cwd, '.cursor'))) { - writeFileSafe(join(cwd, '.cursor', 'rules', 'think-in-html.mdc'), CURSOR_ADAPTER); + writeFileSafe( + join(cwd, '.cursor', 'rules', 'think-in-html.mdc'), + rewriteCorePaths(readFileSync(CURSOR_ADAPTER_SRC, 'utf-8')), + ); console.log(' ✓ Cursor: .cursor/rules/think-in-html.mdc'); installed = true; } if (existsSync(join(cwd, 'AGENTS.md'))) { - appendFileSync(join(cwd, 'AGENTS.md'), CODEX_ADAPTER, 'utf-8'); + appendFileSync( + join(cwd, 'AGENTS.md'), + '\n' + rewriteCorePaths(readFileSync(CODEX_ADAPTER_SRC, 'utf-8')), + 'utf-8', + ); console.log(' ✓ Codex: appended to AGENTS.md'); installed = true; } if (!installed) { - writeFileSafe(join(cwd, '.claude', 'commands', 'think-in-html.md'), CLAUDE_ADAPTER); + writeFileSafe( + join(cwd, '.claude', 'commands', 'think-in-html.md'), + rewriteCorePaths(readFileSync(CLAUDE_ADAPTER_SRC, 'utf-8')), + ); console.log(' ✓ Claude Code (default): .claude/commands/think-in-html.md'); console.log(' (No tool detected — installed the Claude Code adapter by default)'); } console.log('\nDone! Ask your AI tool to "use think-in-html to explain ".'); - console.log('The adapter runs `npx think-in-html` under the hood — no files copied into your repo.'); + console.log('Copied the engine into think-in-html/core/ — the adapter calls it directly via node, no npm package needed.'); } // ── router ── diff --git a/docs/extending.md b/docs/extending.md index e48369c..7f4fe63 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -11,16 +11,16 @@ to touch more than one: ## 1. Add a tool adapter -An adapter only tells a host tool *which CLI commands to run*. All logic lives in +An adapter only tells a host tool *where to find the instructions*. All logic lives in `core/`, so adapters are declarative and thin. See [`adapters/README.md`](../adapters/README.md) for the full walkthrough. In short: 1. Create `adapters//` with a reference copy of the adapter. 2. The adapter instructs the tool to: - - run `npx think-in-html instructions ` and follow it, - - write JSON conforming to the schema to `analysis.json`, - - run `npx think-in-html build analysis.json -o output.html`. -3. Add detection for the tool to the `init` command in + - read `core/instructions/FREEFORM.md` and `core/instructions/mode-.md` and follow them, + - write a complete self-contained `output.html`, + - run `node core/build/check-html.mjs output.html` and fix any reported error. +3. Add detection for the tool to the `cmdInit` function in [`bin/cli.mjs`](../bin/cli.mjs). 4. Open a PR. diff --git a/install.sh b/install.sh index 57711f6..95367ec 100755 --- a/install.sh +++ b/install.sh @@ -1,12 +1,9 @@ #!/usr/bin/env bash set -euo pipefail -# Think-In-HTML installer (no-npm fallback) -# Copies the core engine + tool adapter into your project. -# -# RECOMMENDED if you have Node.js ≥ 18: use the npm package instead — -# npx think-in-html init -# This script exists for environments without Node/npm. +# Think-In-HTML installer +# Copies the core engine + tool adapter into your project. No npm package — +# get it straight from the GitHub repo. # # Usage: # curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash