tap-the-sign 0.2.0

package/hooks-bin/run-hook.mjs

@@ -0,0 +1,175 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  FOLLOW_UP_MESSAGE,
+  PHASE_DONE,
+  PHASE_PLANNING,
+  PHASE_PREFLIGHT,
+  SENTINEL_DISABLE,
+  SENTINEL_ENABLE,
+  SENTINEL_STATUS,
+  SKILL_MISSING_WARNING,
+} from './constants.mjs';
+import { getEnabledPath } from './paths.mjs';
+import { isThermoSkillInstalled } from './skill-check.mjs';
+import {
+  getSessionId,
+  readState,
+  transitionPhase,
+} from './state.mjs';
+
+function readStdin() {
+  return fs.readFileSync(0, 'utf8');
+}
+
+function isEnabled() {
+  return fs.existsSync(getEnabledPath());
+}
+
+function isPlanMode(input, host) {
+  if (host === 'cursor') {
+    return input.composer_mode === 'plan';
+  }
+  return input.permission_mode === 'plan';
+}
+
+function handleToggle(prompt, host) {
+  const enabledPath = getEnabledPath();
+  const dir = path.dirname(enabledPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (prompt.includes(SENTINEL_ENABLE)) {
+    fs.writeFileSync(enabledPath, '1\n');
+    return respondToggle(host, 'tap-the-sign hook enabled.');
+  }
+  if (prompt.includes(SENTINEL_DISABLE)) {
+    if (fs.existsSync(enabledPath)) fs.unlinkSync(enabledPath);
+    return respondToggle(host, 'tap-the-sign hook disabled.');
+  }
+  if (prompt.includes(SENTINEL_STATUS)) {
+    const status = isEnabled() ? 'enabled' : 'disabled';
+    const skill = isThermoSkillInstalled() ? 'installed' : 'missing';
+    return respondToggle(
+      host,
+      `tap-the-sign hook is ${status}. Thermo skill is ${skill}.`,
+    );
+  }
+  return null;
+}
+
+function respondToggle(host, message) {
+  if (host === 'cursor') {
+    return JSON.stringify({ continue: false, user_message: message });
+  }
+  return JSON.stringify({ decision: 'block', reason: message });
+}
+
+function respondEmpty() {
+  return '{}';
+}
+
+function respondFollowUp(host, message) {
+  if (host === 'cursor') {
+    return JSON.stringify({ followup_message: message });
+  }
+  return JSON.stringify({
+    decision: 'block',
+    reason: message,
+    systemMessage: message,
+  });
+}
+
+function respondWarning(host, warning) {
+  console.error(warning);
+  if (host === 'cursor') {
+    return respondEmpty();
+  }
+  return JSON.stringify({ systemMessage: warning });
+}
+
+export async function runHook({ event, host }) {
+  const raw = readStdin();
+  let input = {};
+  try {
+    input = JSON.parse(raw || '{}');
+  } catch {
+    input = {};
+  }
+
+  const prompt = input.prompt ?? '';
+
+  const toggleResponse = handleToggle(prompt, host);
+  if (toggleResponse) {
+    process.stdout.write(toggleResponse);
+    return;
+  }
+
+  if (!isEnabled()) {
+    process.stdout.write(respondEmpty());
+    return;
+  }
+
+  const sessionId = getSessionId(input);
+
+  if (event === 'arm') {
+    if (!isPlanMode(input, host)) {
+      process.stdout.write(respondEmpty());
+      return;
+    }
+    transitionPhase(sessionId, PHASE_PLANNING, { host });
+    process.stdout.write(respondEmpty());
+    return;
+  }
+
+  if (event === 'stop') {
+    const status = input.status ?? 'completed';
+    if (status !== 'completed') {
+      process.stdout.write(respondEmpty());
+      return;
+    }
+
+    const state = readState(sessionId);
+    const phase = state.phase ?? PHASE_DONE;
+
+    if (phase === PHASE_PLANNING) {
+      if (!isThermoSkillInstalled()) {
+        transitionPhase(sessionId, PHASE_DONE);
+        process.stdout.write(respondWarning(host, SKILL_MISSING_WARNING));
+        return;
+      }
+      transitionPhase(sessionId, PHASE_PREFLIGHT);
+      process.stdout.write(respondFollowUp(host, FOLLOW_UP_MESSAGE));
+      return;
+    }
+
+    if (phase === PHASE_PREFLIGHT) {
+      transitionPhase(sessionId, PHASE_DONE);
+      process.stdout.write(respondEmpty());
+      return;
+    }
+
+    process.stdout.write(respondEmpty());
+    return;
+  }
+
+  process.stdout.write(respondEmpty());
+}
+
+const isDirectRun = process.argv[1]?.includes('run-hook.mjs') ||
+  process.argv[1]?.includes('runner.mjs');
+
+if (isDirectRun) {
+  const args = process.argv.slice(2);
+  let event = 'arm';
+  let host = 'cursor';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--event' && args[i + 1]) event = args[++i];
+    if (args[i] === '--host' && args[i + 1]) host = args[++i];
+  }
+
+  runHook({ event, host }).catch((err) => {
+    console.error(err);
+    process.stdout.write('{}');
+    process.exit(1);
+  });
+}

package/hooks-bin/skill-check.mjs

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SKILL_NAME } from './constants.mjs';
+import { getProjectRoot } from './paths.mjs';
+
+function walkForSkill(dir, maxDepth = 6, depth = 0) {
+  if (!fs.existsSync(dir) || depth > maxDepth) {
+    return null;
+  }
+
+  const skillFile = path.join(
+    dir,
+    'skills',
+    SKILL_NAME,
+    'SKILL.md',
+  );
+  if (fs.existsSync(skillFile)) {
+    return skillFile;
+  }
+
+  const directSkill = path.join(dir, SKILL_NAME, 'SKILL.md');
+  if (fs.existsSync(directSkill)) {
+    return directSkill;
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const found = walkForSkill(path.join(dir, entry.name), maxDepth, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+export function findThermoSkill() {
+  const home = os.homedir();
+  const projectRoot = getProjectRoot();
+
+  const searchRoots = [
+    path.join(projectRoot, '.agents', 'skills'),
+    path.join(projectRoot, '.cursor', 'skills'),
+    path.join(projectRoot, '.claude', 'skills'),
+    path.join(home, '.cursor', 'skills'),
+    path.join(home, '.codex', 'skills'),
+    path.join(home, '.cursor', 'plugins'),
+    path.join(home, '.claude', 'plugins'),
+    path.join(home, '.cursor', 'plugins', 'cache'),
+  ];
+
+  for (const root of searchRoots) {
+    const found = walkForSkill(root);
+    if (found) {
+      return { found: true, path: found };
+    }
+  }
+
+  return { found: false, path: null };
+}
+
+export function isThermoSkillInstalled() {
+  return findThermoSkill().found;
+}

package/hooks-bin/state.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  PHASE_DONE,
+  PHASE_IDLE,
+  PHASE_PLANNING,
+  PHASE_PREFLIGHT,
+} from './constants.mjs';
+import { getStateDir } from './paths.mjs';
+
+export function getSessionId(input) {
+  return (
+    input.conversation_id ??
+    input.session_id ??
+    input.parent_conversation_id ??
+    'unknown'
+  );
+}
+
+function statePath(sessionId) {
+  const safe = sessionId.replace(/[^a-zA-Z0-9._-]/g, '_');
+  return path.join(getStateDir(), `${safe}.json`);
+}
+
+export function readState(sessionId) {
+  const file = statePath(sessionId);
+  if (!fs.existsSync(file)) {
+    return { phase: PHASE_IDLE };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { phase: PHASE_IDLE };
+  }
+}
+
+export function writeState(sessionId, state) {
+  const dir = getStateDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(statePath(sessionId), JSON.stringify(state, null, 2) + '\n');
+}
+
+export function transitionPhase(sessionId, phase, extra = {}) {
+  const current = readState(sessionId);
+  writeState(sessionId, { ...current, phase, ...extra, updatedAt: new Date().toISOString() });
+}
+
+export { PHASE_IDLE, PHASE_PLANNING, PHASE_PREFLIGHT, PHASE_DONE };

package/hooks-bin/tap-the-sign-env.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Sourced by tap-the-sign hook wrappers.
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export TAP_THE_SIGN_ROOT="$HOOKS_DIR"
+
+if [[ -n "${TAP_THE_SIGN_GLOBAL:-}" ]]; then
+  export TAP_THE_SIGN_GLOBAL=1
+  export TAP_THE_SIGN_PROJECT_ROOT="${HOME}"
+elif [[ -n "${CURSOR_PROJECT_DIR:-}" ]]; then
+  export TAP_THE_SIGN_PROJECT_ROOT="${CURSOR_PROJECT_DIR}"
+elif [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  export TAP_THE_SIGN_PROJECT_ROOT="${CLAUDE_PROJECT_DIR}"
+elif [[ -n "${CODEX_PROJECT_DIR:-}" ]]; then
+  export TAP_THE_SIGN_PROJECT_ROOT="${CODEX_PROJECT_DIR}"
+elif [[ -f "${HOOKS_DIR}/tap-the-sign.env" ]]; then
+  # shellcheck source=/dev/null
+  source "${HOOKS_DIR}/tap-the-sign.env"
+elif [[ -f "${HOOKS_DIR}/plan-sandwich.env" ]]; then
+  # Legacy env from plan-sandwich installs
+  # shellcheck source=/dev/null
+  source "${HOOKS_DIR}/plan-sandwich.env"
+else
+  export TAP_THE_SIGN_PROJECT_ROOT="$(pwd)"
+fi
+
+# Prefer Bun when available (faster cold start); Node 18+ is the fallback.
+if command -v bun >/dev/null 2>&1; then
+  export TAP_THE_SIGN_RUNTIME=bun
+else
+  export TAP_THE_SIGN_RUNTIME=node
+fi

package/install.bun.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# tap-the-sign Bun installer (from repo clone)
+# Usage: ./install.bun.sh [--global] [--no-claude] [--no-codex]
+#
+# One-liner without cloning (after publish to npm):
+#   bunx tap-the-sign install
+#   bunx tap-the-sign install-thermo
+#   bunx tap-the-sign on
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$REPO_ROOT"
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "error: Bun is required (https://bun.sh)" >&2
+  exit 1
+fi
+
+bun scripts/sync-hooks-bin.mjs
+bun src/cli.mjs install "$@"
+
+echo ""
+echo "Next steps:"
+echo "  bun src/cli.mjs install-thermo"
+echo "  bun src/cli.mjs on        # or: bunx tap-the-sign on"
+echo "  bun src/cli.mjs doctor    # verify thermo skill"

package/install.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# tap-the-sign curl installer
+# Usage: curl -fsSL https://raw.githubusercontent.com/your-org/tap-the-sign/main/install.sh | bash
+#    or: ./install.sh [--global] [--no-claude] [--no-codex]
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$REPO_ROOT"
+
+RUNTIME=node
+if command -v bun >/dev/null 2>&1; then
+  RUNTIME=bun
+elif ! command -v node >/dev/null 2>&1; then
+  echo "error: Node.js 18+ or Bun is required" >&2
+  echo "  Node: https://nodejs.org" >&2
+  echo "  Bun:  https://bun.sh (or use ./install.bun.sh)" >&2
+  exit 1
+fi
+
+"$RUNTIME" scripts/sync-hooks-bin.mjs
+"$RUNTIME" src/cli.mjs install "$@"
+
+echo ""
+echo "Next steps:"
+echo "  $RUNTIME src/cli.mjs install-thermo"
+echo "  $RUNTIME src/cli.mjs on       # or: npx tap-the-sign on / bunx tap-the-sign on"
+echo "  $RUNTIME src/cli.mjs doctor   # verify thermo skill"

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "tap-the-sign",
+  "version": "0.2.0",
+  "description": "Auto thermo sign-off after Plan mode plans. Requires thermo-nuclear-code-quality-review skill.",
+  "type": "module",
+  "bin": {
+    "tap-the-sign": "./src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "hooks-bin/",
+    "commands/",
+    ".cursor-plugin/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    "hooks/",
+    "install.sh",
+    "install.bun.sh",
+    "scripts/",
+    "README.md",
+    "docs/",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "prepare": "node scripts/sync-hooks-bin.mjs",
+    "sync-runtime": "node scripts/sync-hooks-bin.mjs",
+    "test": "node test/smoke.test.mjs",
+    "test:bun": "bun test/smoke.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/tap-the-sign.git"
+  },
+  "homepage": "https://github.com/your-org/tap-the-sign#readme",
+  "bugs": {
+    "url": "https://github.com/your-org/tap-the-sign/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "cursor",
+    "claude-code",
+    "codex",
+    "hooks",
+    "plan-mode",
+    "thermonuclear",
+    "tap-the-sign"
+  ]
+}

package/scripts/sync-hooks-bin.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const dest = path.join(root, 'hooks-bin');
+
+const copies = [
+  ['src/hooks/runner.mjs', 'run-hook.mjs'],
+  ['src/constants.mjs', 'constants.mjs'],
+  ['src/paths.mjs', 'paths.mjs'],
+  ['src/state.mjs', 'state.mjs'],
+  ['src/skill-check.mjs', 'skill-check.mjs'],
+];
+
+for (const [from, to] of copies) {
+  fs.copyFileSync(path.join(root, from), path.join(dest, to));
+}
+
+console.log('Synced hook runtime into hooks-bin/');

package/src/cli.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { install } from './install.mjs';
+import { installThermo } from './install-thermo.mjs';
+import { getConfigRoots, getEnabledPath, setInstallScope } from './paths.mjs';
+import { findThermoSkill } from './skill-check.mjs';
+import { uninstall } from './uninstall.mjs';
+
+function parseFlags(argv) {
+  const flags = {
+    global: false,
+    cursor: true,
+    claude: true,
+    codex: true,
+    projectRoot: null,
+    fix: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--global') flags.global = true;
+    if (arg === '--project') flags.global = false;
+    if (arg === '--no-cursor') flags.cursor = false;
+    if (arg === '--no-claude') flags.claude = false;
+    if (arg === '--no-codex') flags.codex = false;
+    if (arg === '--fix') flags.fix = true;
+    if (arg === '--project-root' && argv[i + 1]) {
+      flags.projectRoot = argv[++i];
+    }
+  }
+  return flags;
+}
+
+function cmdOn(flags) {
+  setInstallScope({ global: flags.global, projectRoot: flags.projectRoot });
+  const enabled = getEnabledPath();
+  fs.mkdirSync(path.dirname(enabled), { recursive: true });
+  fs.writeFileSync(enabled, '1\n');
+  console.log(`tap-the-sign enabled (${flags.global ? 'global' : 'project'}).`);
+}
+
+function cmdOff(flags) {
+  setInstallScope({ global: flags.global, projectRoot: flags.projectRoot });
+  const enabled = getEnabledPath();
+  if (fs.existsSync(enabled)) fs.unlinkSync(enabled);
+  console.log(`tap-the-sign disabled (${flags.global ? 'global' : 'project'}).`);
+}
+
+function cmdStatus(flags) {
+  setInstallScope({ global: flags.global, projectRoot: flags.projectRoot });
+  const roots = getConfigRoots();
+  const enabled = fs.existsSync(getEnabledPath());
+  const skill = findThermoSkill();
+  console.log('tap-the-sign status');
+  console.log(`  scope: ${flags.global ? 'global' : 'project'}`);
+  console.log(`  project root: ${roots.projectRoot}`);
+  console.log(`  hook: ${enabled ? 'enabled' : 'disabled'}`);
+  console.log(
+    `  thermo skill: ${skill.found ? `found at ${skill.path}` : 'NOT FOUND'}`,
+  );
+}
+
+function cmdDoctor(flags) {
+  cmdStatus(flags);
+  const skill = findThermoSkill();
+  if (!skill.found) {
+    console.log('');
+    if (flags.fix) {
+      const ok = installThermo({ global: flags.global });
+      process.exitCode = ok ? 0 : 1;
+      return;
+    }
+    console.log('Action required: install thermo-nuclear-code-quality-review');
+    console.log('  tap-the-sign install-thermo');
+    console.log('  tap-the-sign doctor --fix');
+    console.log('  /add-plugin cursor-team-kit (full plugin + subagent)');
+    console.log('Without the skill, planning works but auto pre-flight is skipped.');
+    process.exitCode = 1;
+  }
+}
+
+function cmdInstallThermo(flags) {
+  const ok = installThermo({ global: flags.global });
+  process.exitCode = ok ? 0 : 1;
+}
+
+function printHelp() {
+  console.log(`tap-the-sign — thermo sign-off hook for Plan mode
+
+Usage:
+  tap-the-sign install [--global] [--no-claude] [--no-codex] [--no-cursor]
+  tap-the-sign uninstall [--global] [...]
+  tap-the-sign install-thermo [--global]
+  tap-the-sign on|off|status|doctor [--global] [--fix]
+
+Defaults: project-local install, all three IDEs.
+`);
+}
+
+const [subcommand, ...rest] = process.argv.slice(2);
+const flags = parseFlags(rest);
+
+switch (subcommand) {
+  case 'install':
+    install(flags);
+    console.log('tap-the-sign hooks installed.');
+    console.log('Run: tap-the-sign install-thermo');
+    console.log('Run: tap-the-sign on');
+    console.log('Run: tap-the-sign doctor');
+    break;
+  case 'uninstall':
+    uninstall(flags);
+    console.log('tap-the-sign hooks uninstalled.');
+    break;
+  case 'install-thermo':
+    cmdInstallThermo(flags);
+    break;
+  case 'on':
+    cmdOn(flags);
+    break;
+  case 'off':
+    cmdOff(flags);
+    break;
+  case 'status':
+    cmdStatus(flags);
+    break;
+  case 'doctor':
+    cmdDoctor(flags);
+    break;
+  default:
+    printHelp();
+    if (subcommand) process.exitCode = 1;
+}

package/src/constants.mjs

@@ -0,0 +1,33 @@
+export const SKILL_NAME = 'thermo-nuclear-code-quality-review';
+
+export const SENTINEL_ENABLE = '<!-- TAP_THE_SIGN_ENABLE -->';
+export const SENTINEL_DISABLE = '<!-- TAP_THE_SIGN_DISABLE -->';
+export const SENTINEL_STATUS = '<!-- TAP_THE_SIGN_STATUS -->';
+
+export const PHASE_IDLE = 'idle';
+export const PHASE_PLANNING = 'planning';
+export const PHASE_PREFLIGHT = 'preflight';
+export const PHASE_DONE = 'done';
+
+export const TAP_THE_SIGN_MARKER = '_tapTheSign';
+export const LEGACY_MARKERS = ['_planSandwich', TAP_THE_SIGN_MARKER];
+
+export const FOLLOW_UP_MESSAGE = `@thermo-nuclear-code-quality-review
+
+Read and apply the full rubric from the thermo-nuclear-code-quality-review skill
+(code judo, 1k-line rule, spaghetti growth, HIGH/MID/LOW bar) to **this plan**
+(not a diff yet).
+
+Will this pass the next thermonuclear code review with no new items (especially HIGH or MID)?
+Did you find all the code judo opportunities?
+What changes would you make to improve confidence to high that this plan would pass
+thermonuclear code review cleanly?
+Include a **Thermonuclear pre-flight** section with this assessment in the plan.
+Be careful to not introduce any blocker higher than LOW and checking three times
+(three separate passes) for code judo opportunities.
+On Pass 3: Thermo-nuclear subagent on final diff; zero HIGH/MID.`;
+
+export const SKILL_MISSING_WARNING =
+  'tap-the-sign: thermo-nuclear-code-quality-review skill not found. ' +
+  'Run: tap-the-sign install-thermo (or /add-plugin cursor-team-kit). ' +
+  'Skipping auto pre-flight follow-up.';