From aec5136ebc03f43cdb852e33988eb9efa8300f69 Mon Sep 17 00:00:00 2001 From: vibhusharma101 Date: Thu, 23 Jul 2026 00:14:04 +0530 Subject: [PATCH] Remove npm/npx as the recommended install path; GitHub clone + install.sh only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Publishing to npm isn't happening right now, so npm/npx should no longer be the primary story for free users. The repo (via git clone or the install.sh curl one-liner) is now the one recommended install path everywhere: README, adapters/README.md, adapters/claude-code/SKILL.md, adapters/codex/AGENTS.md, docs/extending.md. bin/cli.mjs required a real fix, not just doc changes: `cmdInit()` wrote adapter templates that told the AI tool to shell out to `npx think-in-html` for instructions/check/build — which would now be flat-out broken advice. Replaced those embedded, already-drifted template strings with logic that: - copies the engine into /think-in-html/core/ (cpSync), same as install.sh's cp step - reads the real, dogfooded adapter files (.claude/commands/think-in-html.md, .cursor/rules/think-in-html.mdc, adapters/codex/AGENTS.md) and rewrites their bare `core/` references to `think-in-html/core/` — mirroring install.sh's `sed 's|core/|think-in-html/core/|g'` This makes `node bin/cli.mjs init` produce the exact same result as the curl installer, and the two paths can no longer drift apart since cli.mjs now reads the same source files instead of maintaining its own copies. Verified: ran `node bin/cli.mjs init` against a scratch project — engine copied, all three adapters wired, paths rewritten correctly, zero `npx` references anywhere in the output. `npm test` still 18/18. Left PUBLISHING.md and LANDING-PLAN.md as historical/maintainer reference (not user-facing install instructions); softened the README's pointer to PUBLISHING.md to note publishing is paused. Co-Authored-By: Claude Opus 4.8 --- README.md | 45 ++++++++------- adapters/README.md | 18 +++--- adapters/claude-code/SKILL.md | 17 ++++-- adapters/codex/AGENTS.md | 25 +++++--- bin/cli.mjs | 105 ++++++++++++---------------------- docs/extending.md | 10 ++-- install.sh | 9 +-- 7 files changed, 108 insertions(+), 121 deletions(-) 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