tap-the-sign 0.2.0

package/src/hooks/runner.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/src/install-thermo.mjs

@@ -0,0 +1,62 @@
+import { spawnSync } from 'node:child_process';
+import { SKILL_NAME } from './constants.mjs';
+import { findThermoSkill } from './skill-check.mjs';
+
+const SKILLS_REPO = 'cursor/plugins';
+const SKILL_FALLBACK_URL =
+  'https://github.com/cursor/plugins/tree/main/cursor-team-kit/skills/thermo-nuclear-code-quality-review';
+
+function runSkillsAdd(args) {
+  const result = spawnSync('npx', ['skills', 'add', ...args], {
+    stdio: 'inherit',
+    shell: false,
+  });
+  return result.status === 0;
+}
+
+export function installThermo({ global = false } = {}) {
+  const baseArgs = [
+    SKILLS_REPO,
+    '--skill',
+    SKILL_NAME,
+    '-a',
+    'cursor',
+    '-a',
+    'claude-code',
+    '-a',
+    'codex',
+    '--copy',
+    '-y',
+  ];
+
+  if (global) {
+    baseArgs.push('-g');
+  }
+
+  console.log('Installing thermo skill via npx skills add...');
+  let ok = runSkillsAdd(baseArgs);
+
+  if (!ok) {
+    console.log('Retrying with direct skill path...');
+    const fallbackArgs = [SKILL_FALLBACK_URL, '-y'];
+    if (global) fallbackArgs.push('-g');
+    ok = runSkillsAdd(fallbackArgs);
+  }
+
+  if (!ok) {
+    console.error('Failed to install thermo skill.');
+    return false;
+  }
+
+  const skill = findThermoSkill();
+  if (!skill.found) {
+    console.error(
+      'skills add completed but thermo skill was not found in expected locations.',
+    );
+    console.error('Try: /add-plugin cursor-team-kit');
+    return false;
+  }
+
+  console.log(`Thermo skill found at: ${skill.path}`);
+  return true;
+}

package/src/install.mjs

@@ -0,0 +1,171 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TAP_THE_SIGN_MARKER } from './constants.mjs';
+import {
+  copyDirRecursive,
+  mergeClaudeStyleHooks,
+  mergeCursorHooks,
+  readJsonFile,
+  writeJsonFile,
+} from './merge-config.mjs';
+import {
+  PACKAGE_ROOT,
+  getConfigRoots,
+  setInstallScope,
+} from './paths.mjs';
+
+function hookScript(event, host, hooksDir) {
+  return path.join(hooksDir, `${host}-${event}.sh`);
+}
+
+function buildCursorFragment(hooksDir) {
+  return {
+    version: 1,
+    hooks: {
+      beforeSubmitPrompt: [
+        {
+          [TAP_THE_SIGN_MARKER]: true,
+          command: hookScript('arm', 'cursor', hooksDir),
+        },
+      ],
+      stop: [
+        {
+          [TAP_THE_SIGN_MARKER]: true,
+          command: hookScript('stop', 'cursor', hooksDir),
+          loop_limit: 1,
+        },
+      ],
+    },
+  };
+}
+
+function claudeHookEntry(command) {
+  return {
+    hooks: [
+      {
+        [TAP_THE_SIGN_MARKER]: true,
+        type: 'command',
+        command,
+        timeout: 30,
+      },
+    ],
+  };
+}
+
+function buildClaudeFragment(hooksDir) {
+  return {
+    hooks: {
+      UserPromptSubmit: [
+        claudeHookEntry(hookScript('arm', 'claude', hooksDir)),
+      ],
+      Stop: [claudeHookEntry(hookScript('stop', 'claude', hooksDir))],
+    },
+  };
+}
+
+function buildCodexFragment(hooksDir) {
+  return {
+    hooks: {
+      UserPromptSubmit: [
+        claudeHookEntry(hookScript('arm', 'codex', hooksDir)),
+      ],
+      Stop: [claudeHookEntry(hookScript('stop', 'codex', hooksDir))],
+    },
+  };
+}
+
+function installHookPayload(roots) {
+  const srcHooks = path.join(PACKAGE_ROOT, 'src', 'hooks');
+  const srcLib = path.join(PACKAGE_ROOT, 'src');
+
+  for (const dir of [roots.cursorHooksDir, roots.codexHooksDir]) {
+    fs.mkdirSync(dir, { recursive: true });
+    copyDirRecursive(path.join(PACKAGE_ROOT, 'hooks-bin'), dir);
+
+    fs.copyFileSync(
+      path.join(srcHooks, 'runner.mjs'),
+      path.join(dir, 'run-hook.mjs'),
+    );
+
+    for (const file of [
+      'constants.mjs',
+      'paths.mjs',
+      'state.mjs',
+      'skill-check.mjs',
+    ]) {
+      fs.copyFileSync(path.join(srcLib, file), path.join(dir, file));
+    }
+
+    const envFile = path.join(dir, 'tap-the-sign.env');
+    const envLines = [
+      `TAP_THE_SIGN_ROOT=${dir}`,
+      roots.global
+        ? 'TAP_THE_SIGN_GLOBAL=1'
+        : `TAP_THE_SIGN_PROJECT_ROOT=${roots.projectRoot}`,
+    ];
+    fs.writeFileSync(envFile, envLines.join('\n') + '\n');
+  }
+}
+
+function installCursorCommands(roots) {
+  const src = path.join(PACKAGE_ROOT, 'commands');
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(roots.cursorCommandsDir, { recursive: true });
+  for (const file of fs.readdirSync(src)) {
+    fs.copyFileSync(
+      path.join(src, file),
+      path.join(roots.cursorCommandsDir, file),
+    );
+  }
+}
+
+function removeLegacyHookDirs(roots) {
+  const legacyDirs = [
+    path.join(roots.projectRoot, '.cursor', 'hooks', 'plan-sandwich'),
+    path.join(roots.projectRoot, '.codex', 'hooks', 'plan-sandwich'),
+  ];
+  for (const dir of legacyDirs) {
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+}
+
+export function install({
+  global = false,
+  projectRoot = null,
+  cursor = true,
+  claude = true,
+  codex = true,
+} = {}) {
+  setInstallScope({ global, projectRoot });
+  const roots = getConfigRoots();
+
+  fs.mkdirSync(roots.tapTheSignDir, { recursive: true });
+  fs.mkdirSync(path.join(roots.tapTheSignDir, 'state'), { recursive: true });
+
+  installHookPayload(roots);
+  removeLegacyHookDirs(roots);
+
+  if (cursor) {
+    const fragment = buildCursorFragment(roots.cursorHooksDir);
+    const existing = readJsonFile(roots.cursorHooksJson);
+    writeJsonFile(roots.cursorHooksJson, mergeCursorHooks(existing, fragment));
+    installCursorCommands(roots);
+  }
+
+  if (claude) {
+    const fragment = buildClaudeFragment(roots.cursorHooksDir);
+    const existing = readJsonFile(roots.claudeSettings) ?? {};
+    const merged = { ...existing, ...mergeClaudeStyleHooks(existing, fragment) };
+    writeJsonFile(roots.claudeSettings, merged);
+  }
+
+  if (codex) {
+    const fragment = buildCodexFragment(roots.codexHooksDir);
+    const existing = readJsonFile(roots.codexHooksJson);
+    writeJsonFile(roots.codexHooksJson, mergeClaudeStyleHooks(existing, fragment));
+  }
+
+  return roots;
+}

package/src/merge-config.mjs

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { LEGACY_MARKERS } from './constants.mjs';
+
+export function isTapTheSignEntry(entry) {
+  if (!entry) return false;
+  return LEGACY_MARKERS.some((marker) => entry[marker] === true);
+}
+
+function filterTapTheSignOwned(entries) {
+  if (!Array.isArray(entries)) return [];
+  return entries.filter((e) => !isTapTheSignEntry(e));
+}
+
+export function mergeCursorHooks(existing, fragment) {
+  const base = existing ?? { version: 1, hooks: {} };
+  const merged = { version: 1, hooks: { ...base.hooks } };
+  for (const [event, entries] of Object.entries(fragment.hooks ?? {})) {
+    merged.hooks[event] = [...filterTapTheSignOwned(base.hooks?.[event]), ...entries];
+  }
+  return merged;
+}
+
+export function mergeClaudeStyleHooks(existing, fragment) {
+  const base = existing ?? { hooks: {} };
+  const merged = { hooks: { ...base.hooks } };
+
+  for (const [event, newGroups] of Object.entries(fragment.hooks ?? {})) {
+    const existingGroups = base.hooks?.[event] ?? [];
+    const cleaned = existingGroups
+      .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((h) => !isTapTheSignEntry(h)),
+      }))
+      .filter((group) => (group.hooks ?? []).length > 0);
+
+    merged.hooks[event] = [...cleaned, ...newGroups];
+  }
+  return merged;
+}
+
+export function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeJsonFile(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+export function stripTapTheSignFromCursorHooks(config) {
+  if (!config?.hooks) return { version: 1, hooks: {} };
+  const hooks = {};
+  for (const [event, entries] of Object.entries(config.hooks)) {
+    const filtered = filterTapTheSignOwned(entries);
+    if (filtered.length) hooks[event] = filtered;
+  }
+  return { version: 1, hooks };
+}
+
+export function stripTapTheSignFromClaudeHooks(config) {
+  if (!config?.hooks) return { hooks: {} };
+  const hooks = {};
+  for (const [event, list] of Object.entries(config.hooks)) {
+    const cleaned = (list ?? [])
+      .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((h) => !isTapTheSignEntry(h)),
+      }))
+      .filter((group) => (group.hooks ?? []).length > 0);
+    if (cleaned.length) hooks[event] = cleaned;
+  }
+  return { hooks };
+}
+
+export function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const name of fs.readdirSync(src)) {
+    const from = path.join(src, name);
+    const to = path.join(dest, name);
+    if (fs.statSync(from).isDirectory()) {
+      copyDirRecursive(from, to);
+    } else {
+      fs.copyFileSync(from, to);
+      if (name.endsWith('.sh')) {
+        fs.chmodSync(to, 0o755);
+      }
+    }
+  }
+}

package/src/paths.mjs

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+let installScope = { global: false, projectRoot: null };
+
+function initScopeFromEnv() {
+  if (process.env.TAP_THE_SIGN_GLOBAL === '1' || process.env.PLAN_SANDWICH_GLOBAL === '1') {
+    installScope = { global: true, projectRoot: os.homedir() };
+    return;
+  }
+  const projectRoot =
+    process.env.TAP_THE_SIGN_PROJECT_ROOT ?? process.env.PLAN_SANDWICH_PROJECT_ROOT;
+  if (projectRoot) {
+    installScope = { global: false, projectRoot };
+  }
+}
+
+initScopeFromEnv();
+
+export function setInstallScope({ global = false, projectRoot = null } = {}) {
+  installScope = {
+    global,
+    projectRoot: projectRoot ?? findProjectRoot(process.cwd()),
+  };
+}
+
+export function getInstallScope() {
+  return { ...installScope };
+}
+
+export function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (
+      fs.existsSync(path.join(dir, '.git')) ||
+      fs.existsSync(path.join(dir, '.cursor')) ||
+      fs.existsSync(path.join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return path.resolve(startDir);
+}
+
+export function getProjectRoot() {
+  return installScope.projectRoot ?? findProjectRoot(process.cwd());
+}
+
+export function getConfigRoots() {
+  if (installScope.global) {
+    const home = os.homedir();
+    return {
+      projectRoot: home,
+      cursorHooksDir: path.join(home, '.cursor', 'hooks', 'tap-the-sign'),
+      cursorHooksJson: path.join(home, '.cursor', 'hooks.json'),
+      cursorCommandsDir: path.join(home, '.cursor', 'commands'),
+      claudeSettings: path.join(home, '.claude', 'settings.json'),
+      codexHooksDir: path.join(home, '.codex', 'hooks', 'tap-the-sign'),
+      codexHooksJson: path.join(home, '.codex', 'hooks.json'),
+      tapTheSignDir: path.join(home, '.config', 'tap-the-sign'),
+      global: true,
+    };
+  }
+
+  const projectRoot = getProjectRoot();
+  return {
+    projectRoot,
+    cursorHooksDir: path.join(projectRoot, '.cursor', 'hooks', 'tap-the-sign'),
+    cursorHooksJson: path.join(projectRoot, '.cursor', 'hooks.json'),
+    cursorCommandsDir: path.join(projectRoot, '.cursor', 'commands'),
+    claudeSettings: path.join(projectRoot, '.claude', 'settings.json'),
+    codexHooksDir: path.join(projectRoot, '.codex', 'hooks', 'tap-the-sign'),
+    codexHooksJson: path.join(projectRoot, '.codex', 'hooks.json'),
+    tapTheSignDir: path.join(projectRoot, '.tap-the-sign'),
+    global: false,
+  };
+}
+
+export function getEnabledPath() {
+  return path.join(getConfigRoots().tapTheSignDir, 'enabled');
+}
+
+export function getStateDir() {
+  return path.join(getConfigRoots().tapTheSignDir, 'state');
+}
+
+export function resolveInstalledRunner() {
+  const roots = getConfigRoots();
+  const runner = path.join(roots.cursorHooksDir, 'run-hook.mjs');
+  if (fs.existsSync(runner)) {
+    return runner;
+  }
+  return path.join(PACKAGE_ROOT, 'src', 'hooks', 'runner.mjs');
+}

package/src/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;
+}