tspl-cli 0.0.0-stage → 0.1.1

package/src/commands/build.command.js

@@ -0,0 +1,267 @@
+'use strict'
+
+const Fs = require('fs')
+const Path = require('path')
+const { execFileSync, spawn } = require('child_process')
+const { confirm, input, search } = require('@inquirer/prompts')
+
+const { request } = require('../api-client')
+const { ENGINES } = require('../engines')
+const { findProject } = require('../workspace')
+const { readLinks, readActive, listTasks } = require('../config-store')
+const { projectInstructionsText } = require('../project-config')
+const { prepareBuild, describeProposal, blockers, runBuild, stopBuild, checkBuild, renderBuildBrief, planRepos } = require('../task/build')
+const { askBranchChoice } = require('../task/branch-choice')
+const { conventionsFor } = require('../task/conventions')
+const { createContext } = require('../mcp/server')
+const { checkEdit, checkFiles } = require('../task/gate')
+const { engineFor } = require('../task/refine')
+
+const taskUrl = (project, taskKey) => `/api/v1/projects/${project._id}/tasks/${encodeURIComponent(taskKey)}`
+
+const openSession = (brief, cwd) => {
+  const { name, model } = engineFor('build')
+  const args = {
+    claude: ['claude', [brief, ...(model ? ['--model', model] : [])]],
+    codex: ['codex', [...(model ? ['-m', model] : []), brief]],
+    gemini: ['gemini', [...(model ? ['-m', model] : []), '-i', brief]],
+  }[name]
+  if (!args) throw new Error(`${ENGINES[name].label} cannot open an interactive session; paste the brief above into your AI tool`)
+  const env = { ...process.env }
+  delete env.CLAUDECODE
+  console.log(`\nOpening ${ENGINES[name].label} with the build brief…\n`)
+  const child = spawn(args[0], args[1], { cwd, stdio: 'inherit', env })
+  return new Promise(resolve => child.on('close', resolve).on('error', err => {
+    console.log(`Could not start ${args[0]}: ${err.message}`)
+    resolve(1)
+  }))
+}
+
+const start = async (taskKey, options) => {
+  const { project, repos } = await findProject(process.cwd())
+  const task = await request('GET', `/api/v1/projects/${project._id}/tasks/${encodeURIComponent(taskKey)}`)
+  if (!['approved', 'building'].includes(task.status)) {
+    throw new Error(`The plan is ${task.status}; building starts after approval (tspl plan show ${taskKey})`)
+  }
+  const prepare = choice =>
+    prepareBuild({
+      taskKey,
+      task,
+      project,
+      paths: new Map(repos.map(repo => [repo.name, repo.path])),
+      branch: options.branch,
+      base: options.base,
+      fromCurrent: options.fromCurrent,
+      ...choice,
+    })
+  let proposal = prepare()
+  const ask = !options.yes && !options.branch && !options.base && !options.fromCurrent && process.stdin.isTTY
+  if (ask) {
+    const choice = await askBranchChoice(proposal, { input, confirm, search })
+    if (!choice) return
+    proposal = prepare(choice)
+  }
+  console.log(describeProposal(proposal))
+  const problems = blockers(proposal)
+  if (problems.length) {
+    problems.forEach(problem => console.log(`✗ ${problem}`))
+    process.exitCode = 1
+    return
+  }
+  if (!ask && !options.yes && !(await confirm({ message: 'Create this branch in these repos and start building?', default: true }))) {
+    return
+  }
+  const result = await runBuild({ projectId: project._id, taskKey, task, proposal })
+  result.repos.forEach(repo => console.log(`✓ ${repo.name}: on ${proposal.branch} from ${repo.base}@${repo.baseSha.slice(0, 7)}${repo.notes.length ? ` (${repo.notes.join('; ')})` : ''}`))
+  console.log('\nCommits and pushes in these repos are limited to the files on the approved checklist.\n')
+  const loaded = await createContext(process.cwd()).load().catch(() => null)
+  const conventions = loaded ? conventionsFor(loaded.graph, loaded.index, { focus: planRepos(task.plan) }) : []
+  const brief = renderBuildBrief({ ...task, build: { branch: proposal.branch, repos: result.repos } }, result.repos, conventions, projectInstructionsText(process.cwd()))
+  console.log(brief)
+  if (options.open) {
+    process.exitCode = await openSession(brief, process.cwd())
+    return
+  }
+  console.log(`\nPaste the brief above into a fresh AI session, or run: tspl build start ${taskKey} --open`)
+}
+
+const check = async taskKey => {
+  const { project, repos } = await findProject(process.cwd())
+  const task = await request('GET', taskUrl(project, taskKey))
+  if (!task.build) throw new Error(`No build has started for ${taskKey}`)
+  const paths = new Map(repos.map(repo => [repo.name, repo.path]))
+  const results = checkBuild({ taskKey, build: { ...task.build, ticket: task.ticket, files: [...['edit', 'create', 'remove'].flatMap(kind => (task.plan[kind] || []).map(item => item.file)), ...(task.plan.tests || []).map(test => test.file).filter(Boolean)] }, paths })
+  results.forEach(repo => {
+    console.log(`${repo.allow ? '✓' : '✗'} ${repo.name}: ${repo.files.length} file(s) changed since the base`)
+    repo.reasons.forEach(reason => console.log(`    ${reason}`))
+  })
+  if (results.some(repo => !repo.allow)) process.exitCode = 1
+}
+
+const push = async taskKey => {
+  const { project, repos } = await findProject(process.cwd())
+  const task = await request('GET', taskUrl(project, taskKey))
+  if (!task.build) throw new Error(`No build has started for ${taskKey}`)
+  const paths = new Map(repos.map(repo => [repo.name, repo.path]))
+  for (const entry of task.build.repos || []) {
+    const dir = paths.get(entry.name)
+    if (!dir) {
+      console.log(`✗ ${entry.name}: not linked on this computer`)
+      continue
+    }
+    const result = execFileSync('git', ['-C', dir, 'push', '-u', 'origin', task.build.branch], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+    console.log(`✓ ${entry.name}: pushed ${task.build.branch}${result.trim() ? `\n${result.trim()}` : ''}`)
+    const link = (task.report && (task.report.repos || []).find(repo => repo.name === entry.name) || {}).pullRequest
+    if (link) console.log(`    pull request: ${link}`)
+  }
+}
+
+const guard = async hook => {
+  const top = real(tryGit(process.cwd(), ['rev-parse', '--show-toplevel']) || process.cwd())
+  const found = Object.entries(readActive()).find(([, build]) => build.repos.some(repo => real(repo.path) === top))
+  if (!found) return
+  const [taskKey, build] = found
+  const repo = build.repos.find(entry => real(entry.path) === top)
+  const branch = tryGit(top, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  let files
+  if (hook === 'pre-commit') {
+    files = (tryGit(top, ['-c', 'core.quotePath=false', 'diff', '--cached', '--name-only', '--diff-filter=ACDMRT']) || '').split('\n').filter(Boolean)
+  } else {
+    const zero = /^0+$/
+    const ranges = (await readStdin())
+      .split('\n')
+      .map(line => line.trim().split(/\s+/))
+      .filter(parts => parts.length === 4 && !zero.test(parts[1]))
+      .map(([, localSha, , remoteSha]) => `${zero.test(remoteSha) ? repo.baseSha || repo.base : remoteSha}..${localSha}`)
+    files = [...new Set((ranges.length ? ranges : [`${repo.baseSha || repo.base}..HEAD`]).flatMap(range =>
+      (tryGit(top, ['-c', 'core.quotePath=false', 'diff', '--name-only', range]) || '').split('\n').filter(Boolean)))]
+  }
+  const decision = checkFiles({ taskKey, build, repoName: repo.name, branch, files })
+  if (!decision.allow) {
+    process.stderr.write(`${decision.reasons.join('\n')}\n`)
+    process.exit(1)
+  }
+}
+
+const tryGit = (dir, args) => {
+  try {
+    return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch (err) {
+    return null
+  }
+}
+
+const status = () => {
+  const active = Object.entries(readActive())
+  if (!active.length) {
+    console.log('No build in progress.')
+    return
+  }
+  active.forEach(([taskKey, build]) => {
+    console.log(`${taskKey}${build.ticket ? ` · ${build.ticket}` : ''} · branch ${build.branch} · ${build.repos.map(repo => repo.name).join(', ')} · ${build.files.length} files on the checklist`)
+  })
+}
+
+const stop = async taskKey => {
+  const local = stopBuild(taskKey)
+  let server = ''
+  try {
+    const { project } = await findProject(process.cwd())
+    const url = `${taskUrl(project, taskKey)}/workflow`
+    const current = await request('GET', url)
+    if (current.workflow && !['ready'].includes(current.workflow.stage)) {
+      await request('POST', `${url}/stop`)
+      server = ` The task is stopped on the server too (resume with: tspl task run ${taskKey}; change the plan with: tspl plan amend ${taskKey}).`
+    } else if (!current.workflow && current.task && current.task.status === 'building') {
+      await request('POST', `${url}/amend`, { note: 'build stopped on a developer computer' })
+      server = ' The task is open for a new plan on the server too.'
+    }
+  } catch (err) {
+    server = ` Could not tell the server (${err.message}); run: tspl plan amend ${taskKey} when you can.`
+  }
+  console.log((local
+    ? `Stopped ${taskKey}: its edit lock is lifted on this computer. The branches stay as they are.`
+    : `No task ${taskKey} on this computer.`) + server)
+}
+
+const readStdin = () =>
+  new Promise(resolve => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', chunk => { data += chunk })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+  })
+
+const real = file => {
+  try {
+    return Fs.realpathSync(file)
+  } catch (err) {
+    try {
+      return Path.join(Fs.realpathSync(Path.dirname(file)), Path.basename(file))
+    } catch (inner) {
+      return file
+    }
+  }
+}
+
+const gate = async () => {
+  let input = {}
+  try {
+    input = JSON.parse((await readStdin()) || '{}')
+  } catch (err) {
+    return
+  }
+  const toolInput = input.tool_input || {}
+  const target = toolInput.file_path || toolInput.notebook_path
+  if (!target) return
+  const repos = Object.values(readLinks()).flatMap(link =>
+    Object.values(link.repos || {}).map(repo => ({ projectId: link.projectId, name: repo.name, path: real(repo.path) })))
+  const decision = checkEdit({
+    file: real(Path.resolve(input.cwd || process.cwd(), target)),
+    repos,
+    active: readActive(),
+    tasks: listTasks(),
+    currentBranch: dir => {
+      try {
+        return execFileSync('git', ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+      } catch (err) {
+        return null
+      }
+    },
+  })
+  if (!decision.allow) {
+    process.stderr.write(`${decision.reason}\n`)
+    process.exit(2)
+  }
+}
+
+module.exports = {
+  register(program) {
+    const build = program.command('build').description('Start building an approved plan on a new branch, see or stop builds')
+    build
+      .command('start <task>')
+      .description('Create the branch in every repo on the approved plan (checks for uncommitted work first)')
+      .option('--branch <name>', 'name of the new branch (otherwise you are asked; default: from the ticket and title)')
+      .option('--base <branch>', 'branch every repo starts from (otherwise you are asked; default: the project base branch)')
+      .option('--from-current', 'start from the branch each repo has checked out, not the project base branch')
+      .option('-y, --yes', 'do not ask to confirm')
+      .option('--open', 'open a fresh AI session with only the build brief')
+      .action(start)
+    build.command('status').description('Builds in progress on this computer').action(status)
+    build
+      .command('check <task>')
+      .description('Compare the commits on the build branch with the approved checklist (for CI too)')
+      .action(check)
+    build
+      .command('push <task>')
+      .description('Push the build branch of every repo on the plan')
+      .action(push)
+    program.command('guard <hook>', { hidden: true }).description('Git hook: refuses commits and pushes outside the approved checklist').action(guard)
+    build
+      .command('stop <task>')
+      .description('Stop a task on this computer: lifts its edit lock (branches are kept)')
+      .action(stop)
+    program.command('gate', { hidden: true }).description('Edit lock used by the AI tool before each file edit').action(gate)
+  },
+}

package/src/commands/connect.command.js

@@ -0,0 +1,270 @@
+'use strict'
+
+const Fs = require('fs')
+const Os = require('os')
+const Path = require('path')
+const { spawnSync } = require('child_process')
+
+const BIN = Path.join(__dirname, '..', '..', 'bin', 'tspl.js')
+const CLAUDE_SKILL = Path.join(__dirname, '..', 'connect', 'claude-skill.md')
+const MARK_START = '<!-- tspl:start -->'
+const MARK_END = '<!-- tspl:end -->'
+const TOOLS = {
+  claude: 'Claude Code',
+  codex: 'Codex CLI',
+  antigravity: 'Antigravity CLI',
+  agy: 'Antigravity CLI',
+  gemini: 'Gemini CLI',
+  cursor: 'Cursor',
+  vscode: 'VS Code (Copilot)',
+}
+
+const claudeDir = () => process.env.CLAUDE_CONFIG_DIR || Path.join(Os.homedir(), '.claude')
+
+const runClaude = args => {
+  const env = { ...process.env }
+  delete env.CLAUDECODE
+  return spawnSync('claude', args, { encoding: 'utf8', env })
+}
+
+const quote = value => (/\s/.test(value) ? `"${value}"` : value)
+
+const GATE_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit'
+const isGate = entry => (entry.hooks || []).some(hook => /tspl(\.js)?"?\s+gate\b/.test(hook.command || ''))
+
+const updateSettings = change => {
+  const file = Path.join(claudeDir(), 'settings.json')
+  let settings = {}
+  if (Fs.existsSync(file)) {
+    settings = JSON.parse(Fs.readFileSync(file, 'utf8'))
+  }
+  change(settings)
+  Fs.mkdirSync(claudeDir(), { recursive: true })
+  Fs.writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`)
+  return file
+}
+
+const isUsage = entry => (entry.hooks || []).some(hook => /tspl(\.js)?"?\s+usage\b/.test(hook.command || ''))
+
+const setGate = on =>
+  updateSettings(settings => {
+    const hooks = settings.hooks || {}
+    const others = (hooks.PreToolUse || []).filter(entry => !isGate(entry))
+    const gate = { matcher: GATE_MATCHER, hooks: [{ type: 'command', command: `"${process.execPath}" "${BIN}" gate` }] }
+    hooks.PreToolUse = on ? [...others, gate] : others
+    if (!hooks.PreToolUse.length) delete hooks.PreToolUse
+    const stops = (hooks.Stop || []).filter(entry => !isUsage(entry))
+    const usage = { hooks: [{ type: 'command', command: `"${process.execPath}" "${BIN}" usage` }] }
+    hooks.Stop = on ? [...stops, usage] : stops
+    if (!hooks.Stop.length) delete hooks.Stop
+    if (Object.keys(hooks).length) settings.hooks = hooks
+    else delete settings.hooks
+  })
+
+const connectClaude = options => {
+  const skillDir = Path.join(claudeDir(), 'skills', 'tspl')
+
+  if (options.remove) {
+    Fs.rmSync(skillDir, { recursive: true, force: true })
+    setGate(false)
+    runClaude(['mcp', 'remove', '--scope', 'user', 'tspl'])
+    console.log('Removed tspl from Claude Code. Restart Claude Code to finish.')
+    return { configured: true, manualSteps: ['Restart Claude Code to finish removing tspl.'] }
+  }
+
+  Fs.mkdirSync(skillDir, { recursive: true })
+  Fs.copyFileSync(CLAUDE_SKILL, Path.join(skillDir, 'SKILL.md'))
+  console.log(`✓ /tspl command added (${Path.join(skillDir, 'SKILL.md')})`)
+  console.log(`✓ edit lock and usage record added (${setGate(true)})`)
+
+  runClaude(['mcp', 'remove', '--scope', 'user', 'tspl'])
+  const added = runClaude(['mcp', 'add', '--scope', 'user', 'tspl', '--', process.execPath, BIN, 'mcp'])
+  if (added.error || added.status !== 0) {
+    console.log('✗ Could not add the tspl plug-in automatically. Run this once:')
+    const command = `claude mcp add --scope user tspl -- ${quote(process.execPath)} ${quote(BIN)} mcp`
+    console.log(`  ${command}`)
+    return { configured: false, manualSteps: [`Run once: ${command}`] }
+  }
+  console.log('✓ tspl plug-in added for all your projects')
+  console.log('\nRestart Claude Code, open it in a project folder, then type:  /tspl <what should change>')
+  return { configured: true, manualSteps: ['Restart Claude Code, then type /tspl <what should change> in a project folder.'] }
+}
+
+const serverArgs = () => [process.execPath, BIN, 'mcp']
+
+const runTool = (command, args) => {
+  const env = { ...process.env }
+  delete env.CLAUDECODE
+  return spawnSync(command, args, { encoding: 'utf8', env })
+}
+
+const skillBody = () => Fs.readFileSync(CLAUDE_SKILL, 'utf8').replace(/^---[\s\S]*?---\n/, '')
+
+const instructionsBlock = () =>
+  [
+    MARK_START,
+    '## tspl: planned, approved AI changes',
+    'When the user types "/tspl <something>" or asks to work on a tspl task, follow these steps with the tspl MCP tools (check_task, get_brief, find_code, propose_approaches, select_approach, submit_plan, plan_status, start_build, finish_build).',
+    '',
+    skillBody().replace('Task from the user: $ARGUMENTS', 'Task from the user: the text after /tspl').trim(),
+    MARK_END,
+    '',
+  ].join('\n')
+
+const writeBlock = (file, on) => {
+  const current = Fs.existsSync(file) ? Fs.readFileSync(file, 'utf8') : ''
+  const pattern = new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}\\n?`, 'g')
+  const stripped = current.replace(pattern, '')
+  const next = on ? `${stripped.trimEnd()}${stripped.trim() ? '\n\n' : ''}${instructionsBlock()}` : stripped.trim() ? `${stripped.trimEnd()}\n` : ''
+  Fs.mkdirSync(Path.dirname(file), { recursive: true })
+  Fs.writeFileSync(file, next)
+  return file
+}
+
+const writeServers = (file, key, on, entry) => {
+  let data = {}
+  if (Fs.existsSync(file)) {
+    try {
+      data = JSON.parse(Fs.readFileSync(file, 'utf8')) || {}
+    } catch (err) {
+      throw new Error(`${file} is not valid JSON; fix it first`)
+    }
+  }
+  const servers = { ...(data[key] || {}) }
+  if (on) servers.tspl = entry
+  else delete servers.tspl
+  data[key] = servers
+  Fs.mkdirSync(Path.dirname(file), { recursive: true })
+  Fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`)
+  return file
+}
+
+const enforcementNote = label => {
+  console.log(`✓ tspl plug-in added to ${label}`)
+  console.log('  Approved files are enforced by git hooks during a build (same for every tool); plan approval happens in a terminal or the console.')
+}
+
+const connectCodex = options => {
+  const agents = Path.join(Os.homedir(), '.codex', 'AGENTS.md')
+  runTool('codex', ['mcp', 'remove', 'tspl'])
+  if (options.remove) {
+    writeBlock(agents, false)
+    console.log('Removed tspl from Codex CLI.')
+    return { configured: true, manualSteps: [] }
+  }
+  const added = runTool('codex', ['mcp', 'add', 'tspl', '--', ...serverArgs()])
+  if (added.error || added.status !== 0) {
+    throw new Error(`Could not add the tspl plug-in to Codex: ${(added.stderr || added.error && added.error.message || '').trim()}. Run once: codex mcp add tspl -- ${serverArgs().map(quote).join(' ')}`)
+  }
+  enforcementNote('Codex CLI')
+  console.log(`✓ /tspl instructions added to ${writeBlock(agents, true)}`)
+  console.log('\nStart codex in a project folder and type:  /tspl <task id>')
+  return { configured: true, manualSteps: ['Start codex in a project folder and type /tspl <task id>.'] }
+}
+
+const connectAntigravity = options => {
+  const skillDir = Path.join(Os.homedir(), '.gemini', 'config', 'skills', 'tspl')
+  if (options.remove) {
+    runTool('agy', ['mcp', 'remove', 'tspl'])
+    Fs.rmSync(skillDir, { recursive: true, force: true })
+    console.log('Removed tspl from the Antigravity CLI.')
+    return { configured: true, manualSteps: [] }
+  }
+  const added = runTool('agy', ['mcp', 'add', 'tspl', ...serverArgs()])
+  if (added.error || added.status !== 0) {
+    throw new Error(`Could not add the tspl plug-in to Antigravity: ${(added.stderr || added.error && added.error.message || '').trim()}. Run once: agy mcp add tspl ${serverArgs().map(quote).join(' ')}`)
+  }
+  enforcementNote('the Antigravity CLI')
+  Fs.mkdirSync(skillDir, { recursive: true })
+  Fs.copyFileSync(CLAUDE_SKILL, Path.join(skillDir, 'SKILL.md'))
+  console.log(`✓ /tspl skill added (${Path.join(skillDir, 'SKILL.md')})`)
+  console.log('\nStart agy in a project folder and type:  /tspl <task id>')
+  return { configured: true, manualSteps: ['Start agy in a project folder and type /tspl <task id>.'] }
+}
+
+const connectGemini = options => {
+  const settings = Path.join(Os.homedir(), '.gemini', 'settings.json')
+  const memory = Path.join(Os.homedir(), '.gemini', 'GEMINI.md')
+  writeServers(settings, 'mcpServers', !options.remove, { command: process.execPath, args: [BIN, 'mcp'] })
+  writeBlock(memory, !options.remove)
+  if (options.remove) {
+    console.log('Removed tspl from the Gemini CLI.')
+    return { configured: true, manualSteps: [] }
+  }
+  enforcementNote('the Gemini CLI')
+  console.log(`✓ /tspl instructions added to ${memory}`)
+  console.log('\nStart gemini in a project folder and type:  /tspl <task id>')
+  return { configured: true, manualSteps: ['Start gemini in a project folder and type /tspl <task id>.'] }
+}
+
+const connectCursor = options => {
+  const file = Path.join(Os.homedir(), '.cursor', 'mcp.json')
+  const rule = Path.join(Os.homedir(), '.tspl', 'tspl-instructions.md')
+  writeServers(file, 'mcpServers', !options.remove, { command: process.execPath, args: [BIN, 'mcp'] })
+  if (options.remove) {
+    console.log('Removed tspl from Cursor.')
+    return { configured: true, manualSteps: [] }
+  }
+  Fs.mkdirSync(Path.dirname(rule), { recursive: true })
+  Fs.writeFileSync(rule, instructionsBlock())
+  enforcementNote('Cursor')
+  console.log(`✓ MCP server written to ${file}`)
+  console.log(`  Cursor has no user-wide skill file: paste ${rule} into Cursor Settings → Rules → User Rules once.`)
+  return { configured: true, manualSteps: [`Paste ${rule} into Cursor Settings → Rules → User Rules once.`, 'Restart Cursor.'] }
+}
+
+const vscodeUserDir = () => {
+  if (process.platform === 'darwin') return Path.join(Os.homedir(), 'Library', 'Application Support', 'Code', 'User')
+  if (process.platform === 'win32') return Path.join(process.env.APPDATA || Path.join(Os.homedir(), 'AppData', 'Roaming'), 'Code', 'User')
+  return Path.join(Os.homedir(), '.config', 'Code', 'User')
+}
+
+const connectVscode = options => {
+  const file = Path.join(vscodeUserDir(), 'mcp.json')
+  const rule = Path.join(Os.homedir(), '.tspl', 'tspl-instructions.md')
+  writeServers(file, 'servers', !options.remove, { type: 'stdio', command: process.execPath, args: [BIN, 'mcp'] })
+  if (options.remove) {
+    console.log('Removed tspl from VS Code.')
+    return { configured: true, manualSteps: [] }
+  }
+  Fs.mkdirSync(Path.dirname(rule), { recursive: true })
+  Fs.writeFileSync(rule, instructionsBlock())
+  enforcementNote('VS Code (Copilot agent mode)')
+  console.log(`✓ MCP server written to ${file}`)
+  console.log(`  Add ${rule} as a Copilot instructions file (Settings → "chat.instructionsFilesLocations") once. The Claude Code extension needs only: tspl connect claude.`)
+  return { configured: true, manualSteps: [`Add ${rule} as a Copilot instructions file (chat.instructionsFilesLocations) once.`, 'Restart VS Code.'] }
+}
+
+const CONNECTORS = { claude: connectClaude, codex: connectCodex, antigravity: connectAntigravity, agy: connectAntigravity, gemini: connectGemini, cursor: connectCursor, vscode: connectVscode }
+
+const connect = (tool, options = {}) => {
+  const name = String(tool).toLowerCase()
+  const run = CONNECTORS[name]
+  if (!run) throw new Error(`Unknown tool "${tool}". Tools: ${Object.keys(TOOLS).join(', ')}`)
+  const result = run(options) || {}
+  return { configured: result.configured !== false, manualSteps: result.manualSteps || [], error: null }
+}
+
+const connectTool = (tool, options = {}) => {
+  try {
+    return connect(tool, options)
+  } catch (err) {
+    return { configured: false, manualSteps: [], error: err.message }
+  }
+}
+
+module.exports = {
+  TOOLS,
+  connectTool,
+  writeBlock,
+  writeServers,
+  register(program) {
+    program
+      .command('connect <tool>')
+      .description('Add tspl to your AI tool so /tspl works there (claude, codex, antigravity, gemini, cursor, vscode)')
+      .option('--remove', 'take tspl out of that tool again')
+      .action((tool, options) => {
+        connect(tool, options)
+      })
+  },
+}

package/src/commands/engines.command.js

@@ -0,0 +1,136 @@
+'use strict'
+
+const { ENGINE_STEPS } = require('../shared')
+
+const { readEngines, writeEngines } = require('../config-store')
+const { ENGINES, detectAll, defaultAssignments, run } = require('../engines')
+
+const currentSetup = installed => {
+  const saved = readEngines()
+  return {
+    assignments: saved.assignments || defaultAssignments(installed),
+    models: saved.models || {},
+    saved: Boolean(saved.assignments),
+  }
+}
+
+const describe = (setup, step) => {
+  const engine = setup.assignments[step]
+  const model = engine && setup.models[step]
+  return engine ? `${engine}${model ? ` (${model})` : ''}` : '(none)'
+}
+
+const list = () => {
+  const installed = detectAll()
+  const setup = currentSetup(installed)
+
+  console.log('AI engines on this machine')
+  Object.entries(ENGINES).forEach(([name, engine]) => {
+    const found = installed[name]
+    const status = found.installed
+      ? `installed ${found.version ? `(${found.version})` : ''}`.padEnd(34) + `uses ${engine.uses}`
+      : `not installed`.padEnd(34) + `install: ${engine.install}, then ${engine.login}`
+    console.log(`  ${name.padEnd(8)}${status}`)
+  })
+
+  console.log(`\nWhich engine does each step${setup.saved ? '' : ' (suggested; nothing saved yet)'}`)
+  Object.entries(ENGINE_STEPS).forEach(([step, purpose]) => {
+    console.log(`  ${step.padEnd(8)}${describe(setup, step).padEnd(22)}${purpose}`)
+  })
+  if (setup.assignments.build && setup.assignments.build === setup.assignments.verify) {
+    console.log('\n  Note: build and verify use the same engine. Install a second engine so the work is checked by a different AI.')
+  }
+  if (!Object.keys(setup.assignments).length) {
+    console.log('\n  No AI engine is installed yet. Install one of the engines above first.')
+  }
+
+  console.log('\nChange a step:  tspl engines set <step> <engine> [--model <name>]')
+  console.log('Check they work: tspl engines test   (sends one tiny prompt to each engine you use)')
+}
+
+const set = (step, engine, options) => {
+  if (!ENGINE_STEPS[step]) {
+    throw new Error(`Unknown step "${step}". Steps: ${Object.keys(ENGINE_STEPS).join(', ')}`)
+  }
+  if (!ENGINES[engine]) {
+    throw new Error(`Unknown engine "${engine}". Engines: ${Object.keys(ENGINES).join(', ')}`)
+  }
+
+  const installed = detectAll()
+  if (!installed[engine].installed) {
+    throw new Error(`${ENGINES[engine].label} is not installed. Install: ${ENGINES[engine].install}`)
+  }
+
+  const setup = currentSetup(installed)
+  const assignments = { ...setup.assignments, [step]: engine }
+  const models = { ...setup.models }
+  if (options.model) {
+    models[step] = options.model
+  } else {
+    delete models[step]
+  }
+  writeEngines({ assignments, models })
+
+  console.log(`${step} now uses ${engine}${options.model ? ` (${options.model})` : ''}.`)
+  if (assignments.build && assignments.build === assignments.verify) {
+    console.log('Note: build and verify now use the same engine.')
+  }
+}
+
+const test = async engineArg => {
+  const installed = detectAll()
+  const setup = currentSetup(installed)
+  const targets = engineArg
+    ? [[engineArg, undefined]]
+    : [...new Map(Object.keys(ENGINE_STEPS)
+        .filter(step => setup.assignments[step])
+        .map(step => [setup.assignments[step], setup.models[step]])).entries()]
+
+  if (!targets.length) {
+    console.log('No engines to test. Install one first; see: tspl engines')
+    return
+  }
+
+  for (const [name, model] of targets) {
+    if (!ENGINES[name]) {
+      console.log(`  ✗ ${name}: unknown engine`)
+      continue
+    }
+    if (!installed[name].installed) {
+      console.log(`  ✗ ${name}: not installed (${ENGINES[name].install})`)
+      continue
+    }
+    process.stdout.write(`  … ${name}${model ? ` (${model})` : ''}: sending a tiny test prompt`)
+    const result = await run(name, 'Reply with just the word OK.', { model, timeoutMs: 90000 })
+    process.stdout.write('\r')
+    if (result.ok) {
+      const tokens = result.usage ? `, ${result.usage.inputTokens + result.usage.outputTokens} tokens` : ''
+      console.log(`  ✓ ${name}${model ? ` (${model})` : ''}: answered "${result.text.slice(0, 20)}" in ${(result.ms / 1000).toFixed(1)}s${tokens}`)
+    } else if (result.limitHit) {
+      console.log(`  ✗ ${name}: your subscription's usage limit is reached. Tasks using it will pause and resume later.`)
+    } else {
+      console.log(`  ✗ ${name}: ${result.error}. Is it logged in? ${ENGINES[name].login}`)
+    }
+  }
+}
+
+module.exports = {
+  currentSetup,
+  register(program) {
+    const engines = program
+      .command('engines')
+      .description('Choose which AI engine (your own subscription) does each step')
+      .action(list)
+
+    engines
+      .command('set <step> <engine>')
+      .description(`Use an engine for a step (${Object.keys(ENGINE_STEPS).join(', ')})`)
+      .option('--model <name>', 'a specific model of that engine, e.g. sonnet or opus for claude')
+      .action(set)
+
+    engines
+      .command('test [engine]')
+      .description('Send one tiny prompt to each engine you use, to check it is logged in')
+      .action(test)
+  },
+}