tspl-cli 0.0.0-stage → 0.1.1

package/src/config-store.js

@@ -0,0 +1,255 @@
+'use strict'
+
+const Fs = require('fs')
+const Os = require('os')
+const Path = require('path')
+
+const DEFAULT_API_URL = 'http://localhost:1500'
+
+const homeDir = () => process.env.TSPL_HOME || Path.join(Os.homedir(), '.tspl')
+
+const readJson = file => {
+  try {
+    return JSON.parse(Fs.readFileSync(file, 'utf8'))
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return {}
+    }
+    throw err
+  }
+}
+
+const writeJson = (file, data, mode) => {
+  Fs.mkdirSync(homeDir(), { recursive: true, mode: 0o700 })
+  Fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode })
+  Fs.chmodSync(file, mode)
+}
+
+const configFile = () => Path.join(homeDir(), 'config.json')
+
+const credentialsFile = () => Path.join(homeDir(), 'credentials.json')
+
+const readConfig = () => ({ apiUrl: DEFAULT_API_URL, ...readJson(configFile()) })
+
+const writeConfig = config => writeJson(configFile(), config, 0o600)
+
+const accountsFile = () => Path.join(homeDir(), 'accounts.json')
+
+/** Saved logins, one per person and organization, so you can switch account or organization without a password. */
+const readAccounts = () => readJson(accountsFile())
+
+const accountKey = account => `${account.organization}|${String(account.email || '').toLowerCase()}`
+
+const listAccounts = () => Object.values(readAccounts()).filter(account => account && account.organization)
+
+const saveAccount = credentials => {
+  if (!credentials.organization) return
+  const accounts = readAccounts()
+  if (accounts[credentials.organization] && accounts[credentials.organization].email === credentials.email) delete accounts[credentials.organization]
+  accounts[accountKey(credentials)] = { ...credentials, lastUsedAt: new Date().toISOString() }
+  writeJson(accountsFile(), accounts, 0o600)
+}
+
+const forgetAccount = account => {
+  if (!account || !account.organization) return
+  const accounts = readAccounts()
+  delete accounts[accountKey(account)]
+  if (accounts[account.organization] && accounts[account.organization].email === account.email) delete accounts[account.organization]
+  writeJson(accountsFile(), accounts, 0o600)
+}
+
+/** The login to use for an organization: the default login's person if they belong to it, else the latest one used. */
+const accountFor = organization => {
+  const candidates = listAccounts().filter(account => account.organization === organization)
+  const current = readJson(credentialsFile())
+  return (
+    candidates.find(account => account.email === current.email) ||
+    candidates.sort((a, b) => String(b.lastUsedAt || '').localeCompare(String(a.lastUsedAt || '')))[0] ||
+    null
+  )
+}
+
+let activeOrganization = null
+
+/** Which organization this process works in. Set once per command from the project folder (or `tspl init --org`). */
+const setActiveOrganization = organization => {
+  activeOrganization = organization || null
+}
+
+const getActiveOrganization = () => activeOrganization
+
+const readCredentials = () => {
+  if (activeOrganization) {
+    const saved = accountFor(activeOrganization)
+    if (saved) return saved
+  }
+  return readJson(credentialsFile())
+}
+
+const writeCredentials = credentials => {
+  saveAccount(credentials)
+  const current = readJson(credentialsFile())
+  if (!activeOrganization || !current.organization || current.organization === credentials.organization) {
+    writeJson(credentialsFile(), credentials, 0o600)
+  }
+}
+
+const clearCredentials = () => {
+  const account = readCredentials()
+  forgetAccount(account)
+  const current = readJson(credentialsFile())
+  if (!activeOrganization || (current.organization === account.organization && current.email === account.email)) Fs.rmSync(credentialsFile(), { force: true })
+}
+
+const enginesFile = () => Path.join(homeDir(), 'engines.json')
+
+const readEngines = () => readJson(enginesFile())
+
+const writeEngines = engines => writeJson(enginesFile(), engines, 0o600)
+
+const indexFile = projectId => Path.join(homeDir(), 'index', `${projectId}.json`)
+
+const readIndex = projectId => readJson(indexFile(projectId))
+
+const writeIndex = (projectId, index) => {
+  Fs.mkdirSync(Path.join(homeDir(), 'index'), { recursive: true, mode: 0o700 })
+  const file = indexFile(projectId)
+  const temp = `${file}.${process.pid}.tmp`
+  Fs.writeFileSync(temp, JSON.stringify(index), { mode: 0o600 })
+  Fs.renameSync(temp, file)
+}
+
+const taskFile = taskId => Path.join(homeDir(), 'tasks', `${taskId}.json`)
+
+const currentOrg = () => readCredentials().organization || null
+
+/** A task written under one login is not shown under another organization's login. Older files without an owner stay visible. */
+const visible = task => !task.owner || !currentOrg() || task.owner === currentOrg()
+
+const readTask = taskId => {
+  const task = readJson(taskFile(taskId))
+  return visible(task) ? task : {}
+}
+
+const writeTask = task => {
+  Fs.mkdirSync(Path.join(homeDir(), 'tasks'), { recursive: true, mode: 0o700 })
+  Fs.writeFileSync(taskFile(task.id), `${JSON.stringify({ ...task, owner: task.owner || currentOrg(), updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 })
+}
+
+const removeTask = taskId => Fs.rmSync(taskFile(taskId), { force: true })
+
+const listTasks = () => {
+  const dir = Path.join(homeDir(), 'tasks')
+  try {
+    return Fs.readdirSync(dir)
+      .filter(name => name.endsWith('.json'))
+      .map(name => readJson(Path.join(dir, name)))
+      .filter(task => task.id && visible(task))
+  } catch (err) {
+    if (err.code === 'ENOENT') return []
+    throw err
+  }
+}
+
+const runFile = taskId => Path.join(homeDir(), 'runs', `${taskId}.json`)
+
+const readRun = taskId => readJson(runFile(taskId))
+
+const writeRun = (taskId, run) => {
+  Fs.mkdirSync(Path.join(homeDir(), 'runs'), { recursive: true, mode: 0o700 })
+  Fs.writeFileSync(runFile(taskId), `${JSON.stringify(run, null, 2)}\n`, { mode: 0o600 })
+}
+
+const activeFile = () => Path.join(homeDir(), 'active.json')
+
+const readActive = () => readJson(activeFile())
+
+const writeActive = active => writeJson(activeFile(), active, 0o600)
+
+const feedbackFile = projectId => Path.join(homeDir(), 'feedback', `${projectId}.json`)
+
+const readFeedback = projectId => readJson(feedbackFile(projectId))
+
+const writeFeedback = (projectId, feedback) => {
+  Fs.mkdirSync(Path.join(homeDir(), 'feedback'), { recursive: true, mode: 0o700 })
+  Fs.writeFileSync(feedbackFile(projectId), JSON.stringify(feedback), { mode: 0o600 })
+}
+
+const writePlanPage = (taskKey, html) => {
+  const dir = Path.join(homeDir(), 'plans')
+  Fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const file = Path.join(dir, `${taskKey}.html`)
+  Fs.writeFileSync(file, html, { mode: 0o600 })
+  return file
+}
+
+const SYNC_LOCK_MINUTES = 15
+
+const syncLockFile = () => Path.join(homeDir(), 'sync.lock')
+
+const lockSync = () => {
+  const file = syncLockFile()
+  try {
+    if (Date.now() - Fs.statSync(file).mtimeMs > SYNC_LOCK_MINUTES * 60 * 1000) Fs.rmSync(file, { force: true })
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+  try {
+    Fs.mkdirSync(homeDir(), { recursive: true, mode: 0o700 })
+    Fs.writeFileSync(file, String(process.pid), { flag: 'wx', mode: 0o600 })
+    return true
+  } catch (err) {
+    if (err.code === 'EEXIST') return false
+    throw err
+  }
+}
+
+const unlockSync = () => Fs.rmSync(syncLockFile(), { force: true })
+
+const syncStateFile = () => Path.join(homeDir(), 'sync.json')
+
+const readSyncState = () => readJson(syncStateFile())
+
+const writeSyncState = state => writeJson(syncStateFile(), state, 0o600)
+
+const linksFile = () => Path.join(homeDir(), 'links.json')
+
+const readLinks = () => readJson(linksFile())
+
+const writeLinks = links => writeJson(linksFile(), links, 0o600)
+
+module.exports = {
+  readConfig,
+  writeConfig,
+  readCredentials,
+  writeCredentials,
+  clearCredentials,
+  setActiveOrganization,
+  getActiveOrganization,
+  readAccounts,
+  listAccounts,
+  accountFor,
+  saveAccount,
+  forgetAccount,
+  readLinks,
+  writeLinks,
+  readEngines,
+  writeEngines,
+  readIndex,
+  writeIndex,
+  readRun,
+  writeRun,
+  readTask,
+  writeTask,
+  removeTask,
+  listTasks,
+  readActive,
+  writeActive,
+  readFeedback,
+  writeFeedback,
+  lockSync,
+  unlockSync,
+  readSyncState,
+  writeSyncState,
+  writePlanPage,
+}

package/src/connect/claude-skill.md

@@ -0,0 +1,30 @@
+---
+name: tspl
+description: Work on a tspl task: read its brief, plan, get approval, build and report. Tasks are prepared with "tspl task new" in a terminal (no AI tokens) and have an id like t-abc123-9f2e.
+argument-hint: <task id> or <what should change>
+disable-model-invocation: true
+---
+
+Task from the user: $ARGUMENTS
+
+Keep messages short and plain.
+
+## A. The argument is a tspl task id (starts with "t-")
+
+1. Call `get_brief` with it. The brief has the task, the "done when" checks, whether the PM confirmed the scope, and the files tspl found (no AI). Read those files at the "look at" places. If confidence is LOW, do one short, targeted search for the names tspl lists and the task's words. Do not read whole repos. If the brief says the PM sent the scope back, tell the user and stop.
+2. Compare two or three meaningful implementation approaches from the code. If the brief has unanswered saved options, show those instead of generating new ones. Call `propose_approaches` with unique option IDs, titles, summaries, benefits, drawbacks, affected files, exactly one `recommendedId`, the recommendation reason, and `expectedVersion` (0 initially). Show the options through your question UI or a numbered list, marking one **Recommended**. Wait for the user's explicit answer; never automatically choose or treat silence as consent. Record the answer with `select_approach` using its version and option ID. If the brief already has a valid selection, use it without asking again. This choice does not approve the plan.
+3. Call `submit_plan` with `approach: {version, optionId}` matching the saved choice, and: files to edit, create and remove (repo/path and what changes), screen changes, and tests (with the "done when" numbers each proves and the command that runs each test from its repo folder). tspl returns a checklist by repo; fix the checks that are real problems.
+4. Show the whole checklist. A person approves it, never this chat: the user runs `tspl plan approve <task id>` in their own terminal, or decides in the tspl console; then the PM does the same if the project needs it. When the user says they decided, call `plan_status`. For changes, update the same task and submit the next version. Build nothing until `plan_status` says approved.
+5. When approved: either call `start_build` here (show the branch and where each repo starts, ask the user, then call it again with `confirm: true`), or suggest `tspl build start <task id> --open` in a terminal, which opens a fresh AI session with only the checklist. Only checklist files and test files can change: git refuses commits and pushes with other files. Build the checklist the way the surrounding code is written, run the tests, check every "done when" item.
+6. Do not commit or push. When the checklist is built, call `finish_build` with each "done when" result, each test result and a two-sentence summary; report failures honestly. tspl runs the plan's test commands itself on the files as they are and the server decides whether the task is done. If it PASSED, show the report: the task is done. Committing, pushing (`tspl build push <task id>`) and the pull request are the user's own choice afterwards. If it lists problems, fix them and call `finish_build` again. If tspl cannot reach its server, say so and stop; do not commit instead.
+   In a project with a `.tspl/` folder (set up with `tspl init`) `finish_build` ignores what you report as proof: tspl commits nothing for you, runs the approved checks on your committed branch itself, has a separate AI session review it, and then waits for the person to confirm the push (`tspl task run <task id>` in their terminal opens the draft pull requests and watches CI). Never tell the user the task is done: say what stage tspl reports and the next step it prints. Done-when items no executed check covers are checked by the person with `tspl task verify <task id> --check <n>`, never by you.
+
+## B. The argument is free text, a ticket id, or empty
+
+The cheapest way is outside this chat. Tell the user to run, in a terminal in this project folder:
+
+    tspl task new "<what should change>"
+
+It asks only what is missing (options come from the code), suggests "done when" checks, finds the files, and saves the task so the PM can confirm the scope; it uses no AI tokens. Then they come back with `/tspl <task id>`.
+
+If they prefer to continue here: fill a task card with only what the user said or showed (ticket, type, what, who, where, how, steps, now, expected, doneWhen, details) and call `check_task`. "needs answers": ask all listed questions in one go with your question tool, put the answers in the named fields and call `check_task` again with the returned card ("skip" from the user: set `skip: true`). "ready": show the summary, ask the user to confirm, then continue at A1 with the task id it returned.

package/src/engines.js

@@ -0,0 +1,218 @@
+'use strict'
+
+const { spawn, execFileSync } = require('child_process')
+
+const LIMIT_PATTERN = /usage limit|rate limit|limit reached|limit exceeded|quota|too many requests|\b429\b/i
+
+const ENGINES = {
+  claude: {
+    label: 'Claude Code',
+    command: 'claude',
+    uses: 'your Claude Pro/Max subscription',
+    install: 'npm install -g @anthropic-ai/claude-code',
+    login: 'run "claude" once and sign in',
+  },
+  codex: {
+    label: 'Codex CLI',
+    command: 'codex',
+    uses: 'your ChatGPT Plus/Pro subscription',
+    install: 'npm install -g @openai/codex',
+    login: 'run "codex" once and choose Sign in with ChatGPT',
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    command: 'gemini',
+    uses: 'your Google account',
+    install: 'npm install -g @google/gemini-cli@latest',
+    login: 'run "gemini" once and sign in with Google',
+  },
+  ollama: {
+    label: 'Ollama',
+    command: 'ollama',
+    uses: 'free local models on this machine',
+    install: 'brew install ollama',
+    login: 'download a model, e.g. "ollama pull qwen2.5-coder"',
+  },
+}
+
+const PREFERENCE = ['claude', 'codex', 'gemini', 'ollama']
+
+const detect = name => {
+  try {
+    const out = execFileSync(ENGINES[name].command, ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10000,
+    })
+    return { installed: true, version: out.trim().split('\n')[0] }
+  } catch (err) {
+    return { installed: false, version: null }
+  }
+}
+
+const detectAll = () =>
+  Object.fromEntries(Object.keys(ENGINES).map(name => [name, detect(name)]))
+
+const defaultAssignments = installed => {
+  const available = PREFERENCE.filter(name => installed[name] && installed[name].installed)
+  if (!available.length) {
+    return {}
+  }
+  const main = available[0]
+  return { plan: main, build: main, verify: main, bulk: main }
+}
+
+const commandFor = (name, prompt, model, { noTools = false } = {}) => {
+  switch (name) {
+    case 'claude':
+      return ['claude', ['-p', prompt, '--output-format', 'json', ...(model ? ['--model', model] : []), ...(noTools ? ['--tools', ''] : [])]]
+    case 'codex':
+      return ['codex', ['exec', ...(model ? ['-m', model] : []), ...(noTools ? ['--sandbox', 'read-only'] : []), prompt]]
+    case 'gemini':
+      return ['gemini', [...(model ? ['-m', model] : []), '-p', prompt]]
+    case 'ollama':
+      return ['ollama', ['run', model || 'qwen2.5-coder', prompt]]
+    default:
+      throw new Error(`Unknown engine "${name}"`)
+  }
+}
+
+const NOISE = /DeprecationWarning|--trace-deprecation|^\(node:\d+\)|ExperimentalWarning|^\s*$/
+
+/** The first line that is an actual error, skipping Node warnings the provider CLIs print on stderr. */
+const firstError = text => String(text || '').split('\n').find(line => !NOISE.test(line)) || ''
+
+const READ_TOOLS = ['Read', 'Grep', 'Glob']
+const EDIT_TOOLS = ['Read', 'Edit', 'Write', 'Glob', 'Grep', 'Bash']
+
+/**
+ * What each engine can do headless. enforcedReadOnly means the provider itself refuses edits for plan/review runs
+ * (checked in the provider's own help); where it is false tspl still detects and rejects changes afterwards.
+ */
+const CAPABILITIES = {
+  claude: { plan: true, edit: true, review: true, enforcedReadOnly: true },
+  codex: { plan: true, edit: true, review: true, enforcedReadOnly: true },
+  gemini: { plan: true, edit: true, review: true, enforcedReadOnly: false },
+  ollama: { plan: true, edit: false, review: true, enforcedReadOnly: true },
+}
+
+const agentCapabilities = name => {
+  if (!CAPABILITIES[name]) throw new Error(`Unknown engine "${name}"`)
+  return { ...CAPABILITIES[name] }
+}
+
+/**
+ * The command for a structured agent run. role is plan, edit or review; plan and review runs get read-only tools where the
+ * provider can enforce that. sessionId is generated by the caller so a review can be proven to be a different session.
+ */
+const agentCommand = (name, role, { prompt, model, dirs = [], sessionId, schema }) => {
+  const capability = agentCapabilities(name)
+  if (!capability[role]) throw new Error(`${ENGINES[name].label} cannot do the "${role}" step on its own`)
+  const readOnly = role !== 'edit'
+  switch (name) {
+    case 'claude':
+      return ['claude', [
+        '-p', prompt,
+        '--output-format', 'json',
+        ...(model ? ['--model', model] : []),
+        ...(sessionId ? ['--session-id', sessionId] : []),
+        ...(role === 'review' ? ['--no-session-persistence'] : []),
+        ...(schema ? ['--json-schema', JSON.stringify(schema)] : []),
+        ...(readOnly ? ['--tools', READ_TOOLS.join(',')] : ['--permission-mode', 'acceptEdits', '--allowedTools', ...EDIT_TOOLS]),
+        ...dirs.slice(1).flatMap(dir => ['--add-dir', dir]),
+      ]]
+    case 'codex':
+      return ['codex', [
+        'exec',
+        '--sandbox', readOnly ? 'read-only' : 'workspace-write',
+        ...(model ? ['-m', model] : []),
+        ...dirs.slice(1).flatMap(dir => ['--add-dir', dir]),
+        prompt,
+      ]]
+    case 'gemini':
+      return ['gemini', [
+        ...(model ? ['-m', model] : []),
+        '--approval-mode', readOnly ? 'default' : 'auto_edit',
+        ...(dirs.length > 1 ? ['--include-directories', dirs.slice(1).join(',')] : []),
+        '-p', prompt,
+      ]]
+    case 'ollama':
+      return ['ollama', ['run', model || 'qwen2.5-coder', prompt]]
+    default:
+      throw new Error(`Unknown engine "${name}"`)
+  }
+}
+
+const AUTH_PATTERN = /not logged in|please (log ?in|sign in|authenticate)|unauthori[sz]ed|authentication (failed|required)|invalid api key|\b401\b|run .{0,20}login/i
+
+const parseOutput = (name, stdout) => {
+  if (name === 'claude') {
+    try {
+      const data = JSON.parse(stdout)
+      return {
+        text: data.structured_output ? JSON.stringify(data.structured_output) : data.result || '',
+        failed: Boolean(data.is_error),
+        usage: data.usage
+          ? {
+              inputTokens: data.usage.input_tokens || 0,
+              outputTokens: data.usage.output_tokens || 0,
+              cacheReadTokens: data.usage.cache_read_input_tokens || 0,
+            }
+          : null,
+        sessionId: data.session_id || null,
+      }
+    } catch (err) {
+      return { text: stdout.trim(), failed: false, usage: null, sessionId: null }
+    }
+  }
+  return { text: stdout.trim(), failed: false, usage: null, sessionId: null }
+}
+
+const run = (name, prompt, { model, cwd, timeoutMs = 120000, noTools = false } = {}) =>
+  new Promise(resolve => {
+    const [command, args] = commandFor(name, prompt, model, { noTools })
+    const started = Date.now()
+    const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs)
+
+    child.stdout.on('data', chunk => {
+      stdout += chunk
+    })
+    child.stderr.on('data', chunk => {
+      stderr += chunk
+    })
+    child.on('error', err => {
+      clearTimeout(timer)
+      resolve({ ok: false, error: err.message, limitHit: false, ms: Date.now() - started })
+    })
+    child.on('close', code => {
+      clearTimeout(timer)
+      const parsed = parseOutput(name, stdout)
+      const problem = code !== 0 || parsed.failed
+      const message = `${parsed.text}\n${stderr}`
+      resolve({
+        ok: !problem,
+        text: parsed.text,
+        usage: parsed.usage,
+        sessionId: parsed.sessionId,
+        limitHit: problem && LIMIT_PATTERN.test(message),
+        error: problem ? firstError(stderr) || firstError(parsed.text) || `exited with code ${code}` : null,
+        ms: Date.now() - started,
+      })
+    })
+  })
+
+module.exports = {
+  firstError,
+  AUTH_PATTERN,
+  agentCapabilities,
+  agentCommand,
+  ENGINES,
+  detectAll,
+  defaultAssignments,
+  commandFor,
+  parseOutput,
+  run,
+}