tspl-cli 0.0.0-stage → 0.1.1

package/src/providers/github.js

@@ -0,0 +1,249 @@
+'use strict'
+
+const Fs = require('fs')
+const Os = require('os')
+const Path = require('path')
+
+const { runProcess } = require('../workflow/process')
+const { mergeBody } = require('../workflow/pr-body')
+
+const TIMEOUT = 60 * 1000
+const REPOSITORY = /^[\w.-]+\/[\w.-]+$/
+const PR_FIELDS = 'number,url,headRefOid,headRefName,baseRefName,isDraft,state,body,title,headRepositoryOwner'
+
+class ProviderError extends Error {
+  /** code: missing-cli, auth, permission, not-found, rate-limit, unsupported, ambiguous, closed-history, invalid, failed */
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+const classify = (result, what) => {
+  const text = `${result.stderr}\n${result.stdout}`
+  if (result.error && /ENOENT/.test(result.error)) return new ProviderError('missing-cli', 'The GitHub CLI (gh) is not installed. Install it from https://cli.github.com and run: gh auth login')
+  if (/gh auth login|not logged in|authentication (failed|required)|bad credentials|HTTP 401/i.test(text)) return new ProviderError('auth', 'The GitHub CLI is not logged in. Run: gh auth login')
+  if (/HTTP 403|Resource not accessible|must have admin|forbidden/i.test(text)) return new ProviderError('permission', `GitHub refused ${what}: your account lacks permission (${firstLine(text)})`)
+  if (/rate limit/i.test(text)) return new ProviderError('rate-limit', 'GitHub rate limit reached; try again later')
+  if (/HTTP 404|Not Found|Could not resolve/i.test(text)) return new ProviderError('not-found', `GitHub could not find it while ${what}: ${firstLine(text)}`)
+  return new ProviderError('failed', `${what} failed: ${firstLine(text) || `exit code ${result.exitCode}`}`)
+}
+
+const firstLine = text => String(text || '').trim().split('\n').find(Boolean) || ''
+
+/** Splits `gh api --paginate` output (several JSON documents back to back) into values. */
+const parseJsonStream = text => {
+  const values = []
+  const source = String(text || '').trim()
+  let index = 0
+  while (index < source.length) {
+    while (index < source.length && /\s/.test(source[index])) index++
+    if (index >= source.length) break
+    const open = source[index]
+    if (open !== '{' && open !== '[') throw new ProviderError('failed', 'GitHub returned something that is not JSON')
+    let depth = 0
+    let inString = false
+    let end = -1
+    for (let i = index; i < source.length; i++) {
+      const char = source[i]
+      if (inString) {
+        if (char === '\\') i++
+        else if (char === '"') inString = false
+      } else if (char === '"') inString = true
+      else if (char === '{' || char === '[') depth++
+      else if ((char === '}' || char === ']') && --depth === 0) { end = i; break }
+    }
+    if (end === -1) throw new ProviderError('failed', 'GitHub returned cut-off JSON')
+    values.push(JSON.parse(source.slice(index, end + 1)))
+    index = end + 1
+  }
+  return values
+}
+
+const normalizePr = (pr, repository) => ({
+  number: pr.number,
+  url: pr.url,
+  headSha: pr.headRefOid,
+  head: pr.headRefName,
+  base: pr.baseRefName,
+  draft: Boolean(pr.isDraft),
+  state: String(pr.state || '').toLowerCase(),
+  body: pr.body || '',
+  title: pr.title || '',
+  repository,
+})
+
+const encode = branch => branch.split('/').map(encodeURIComponent).join('%2F')
+
+const CHECK_RUN_FINAL = new Set(['completed'])
+
+const fromCheckRun = run => ({
+  name: run.name,
+  appId: run.app && run.app.id ? run.app.id : null,
+  headSha: run.head_sha,
+  status: run.status,
+  conclusion: run.conclusion || null,
+  url: run.html_url || null,
+})
+
+const fromStatus = (status, sha) => ({
+  name: status.context,
+  appId: null,
+  headSha: sha,
+  status: status.state === 'pending' ? 'in_progress' : 'completed',
+  conclusion: status.state === 'success' ? 'success' : status.state === 'pending' ? null : 'failure',
+  url: status.target_url || null,
+})
+
+const createGitHubProvider = (repoConfig, deps = {}) => {
+  const delivery = repoConfig.delivery || {}
+  const repository = delivery.repository
+  if (delivery.provider !== 'github') throw new ProviderError('unsupported', `Automatic pull requests support GitHub only, not "${delivery.provider}".`)
+  if (!REPOSITORY.test(repository || '')) throw new ProviderError('invalid', `"${repository}" is not an owner/name GitHub repository`)
+  const run = deps.run || runProcess
+  const owner = repository.split('/')[0]
+
+  const gh = async (args, what, { allow } = {}) => {
+    const result = await run('gh', args, { timeoutMs: TIMEOUT, cwd: deps.cwd, env: { GH_PROMPT_DISABLED: '1', NO_COLOR: '1' } })
+    if (result.exitCode === 0 && !result.error) return result
+    if (allow && allow(result)) return result
+    throw classify(result, what)
+  }
+
+  const api = async (path, what, options) => {
+    const result = await gh(['api', '--paginate', `repos/${repository}/${path}`], what, options)
+    return result.exitCode === 0 ? parseJsonStream(result.stdout) : { failed: result }
+  }
+
+  const view = async number => {
+    const result = await gh(['pr', 'view', String(number), '--repo', repository, '--json', PR_FIELDS], `reading pull request #${number}`)
+    return normalizePr(JSON.parse(result.stdout), repository)
+  }
+
+  const provider = {
+    name: 'github',
+    supported: true,
+    repository,
+
+    async authenticate() {
+      const result = await gh(['auth', 'status', '--hostname', 'github.com'], 'checking GitHub login')
+      return { ok: true, detail: firstLine(result.stdout || result.stderr) }
+    },
+
+    async findPr({ base, head }) {
+      const result = await gh(
+        ['pr', 'list', '--repo', repository, '--head', head, '--base', base, '--state', 'all', '--limit', '100', '--json', PR_FIELDS],
+        'looking for an existing pull request',
+      )
+      const all = JSON.parse(result.stdout || '[]')
+        .filter(pr => pr.headRefName === head && pr.baseRefName === base)
+        .filter(pr => !pr.headRepositoryOwner || !pr.headRepositoryOwner.login || pr.headRepositoryOwner.login.toLowerCase() === owner.toLowerCase())
+        .map(pr => normalizePr(pr, repository))
+      if (!all.length) return null
+      const open = all.filter(pr => pr.state === 'open')
+      if (open.length > 1) throw new ProviderError('ambiguous', `Several open pull requests exist for ${head} → ${base}: ${open.map(pr => `#${pr.number}`).join(', ')}. Close the extra ones.`)
+      if (!open.length) {
+        throw new ProviderError('closed-history', `Pull request #${all[0].number} for ${head} → ${base} is ${all[0].state}. tspl will not reopen it; use a new branch or reopen it yourself.`)
+      }
+      return open[0]
+    },
+
+    async upsertDraft({ base, head, title, body }) {
+      const dir = Fs.mkdtempSync(Path.join(Os.tmpdir(), 'tspl-pr-'))
+      try {
+        let existing = await provider.findPr({ base, head })
+        if (!existing) {
+          const file = Path.join(dir, 'body.md')
+          Fs.writeFileSync(file, body, 'utf8')
+          const created = await gh(
+            ['pr', 'create', '--repo', repository, '--base', base, '--head', head, '--draft', '--title', title, '--body-file', file],
+            'creating the pull request',
+            { allow: result => /already exists/i.test(`${result.stderr}${result.stdout}`) },
+          )
+          if (created.exitCode === 0) {
+            const number = Number((created.stdout.match(/\/pull\/(\d+)/) || [])[1])
+            if (!number) throw new ProviderError('failed', `GitHub created the pull request but returned no number: ${firstLine(created.stdout)}`)
+            return { ...(await view(number)), created: true }
+          }
+          existing = await provider.findPr({ base, head })
+          if (!existing) throw new ProviderError('failed', 'GitHub says the pull request exists but it could not be found')
+        }
+        const merged = mergeBody(existing.body, body)
+        if (merged !== existing.body) {
+          const file = Path.join(dir, 'body.md')
+          Fs.writeFileSync(file, merged, 'utf8')
+          await gh(['pr', 'edit', String(existing.number), '--repo', repository, '--body-file', file], 'updating the pull request description')
+        }
+        return { ...(await view(existing.number)), created: false }
+      } finally {
+        Fs.rmSync(dir, { recursive: true, force: true })
+      }
+    },
+
+    /**
+     * Required status checks of the base branch from rulesets and classic protection. `determined` is false when
+     * GitHub would not tell us (permissions), which is different from "nothing is required".
+     */
+    async requiredChecks(base) {
+      const requirements = []
+      const problems = []
+      const add = (name, appId) => {
+        if (name && !requirements.some(item => item.name === name && item.appId === (appId || null))) requirements.push({ name, appId: appId || null })
+      }
+      let seen = 0
+
+      try {
+        const pages = await api(`rules/branches/${encode(base)}`, 'reading branch rules')
+        seen++
+        pages.flat().filter(rule => rule.type === 'required_status_checks').forEach(rule => {
+          ;((rule.parameters && rule.parameters.required_status_checks) || []).forEach(item => add(item.context, item.integration_id))
+        })
+      } catch (err) {
+        if (!['permission', 'not-found'].includes(err.code)) throw err
+        problems.push(`Branch rules for ${base} could not be read (${err.message})`)
+      }
+
+      try {
+        const classic = await api(`branches/${encode(base)}/protection/required_status_checks`, 'reading branch protection', {
+          allow: result => /HTTP 404/.test(`${result.stderr}${result.stdout}`) && /Branch not protected|Required status checks not enabled/i.test(`${result.stderr}${result.stdout}`),
+        })
+        seen++
+        if (!classic.failed) {
+          classic.forEach(entry => {
+            ;(entry.checks || []).forEach(item => add(item.context, item.app_id > 0 ? item.app_id : null))
+            ;(entry.contexts || []).filter(name => !(entry.checks || []).some(item => item.context === name)).forEach(name => add(name, null))
+          })
+        }
+      } catch (err) {
+        if (!['permission', 'not-found'].includes(err.code)) throw err
+        problems.push(`Branch protection for ${base} could not be read (${err.message})`)
+      }
+      return { requirements, determined: problems.length === 0 && seen === 2, problems }
+    },
+
+    async observePr(number) {
+      const pr = await view(number)
+      const runs = (await api(`commits/${pr.headSha}/check-runs`, 'reading check runs')).flatMap(page => page.check_runs || []).map(fromCheckRun)
+      const statuses = (await api(`commits/${pr.headSha}/status`, 'reading commit statuses')).flatMap(page => page.statuses || []).map(item => fromStatus(item, pr.headSha))
+      return { ...pr, checks: [...runs, ...statuses], observedAt: new Date().toISOString() }
+    },
+
+    async markReady(number, { headSha }) {
+      const before = await view(number)
+      if (before.headSha !== headSha) throw new ProviderError('invalid', `The pull request head moved to ${before.headSha}; it is no longer the tested commit ${headSha}.`)
+      if (before.state !== 'open') throw new ProviderError('closed-history', `Pull request #${number} is ${before.state}`)
+      if (before.draft) await gh(['pr', 'ready', String(number), '--repo', repository], 'marking the pull request ready')
+      const after = await view(number)
+      if (after.draft || after.headSha !== headSha) throw new ProviderError('failed', 'GitHub did not mark the pull request ready on the tested commit')
+      return after
+    },
+  }
+  return provider
+}
+
+module.exports = {
+  ProviderError,
+  CHECK_RUN_FINAL,
+  parseJsonStream,
+  createGitHubProvider,
+}

package/src/providers/index.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const { createGitHubProvider, ProviderError } = require('./github')
+
+const unsupported = repoConfig => {
+  const reason = `Automatic pull requests support GitHub only, not "${repoConfig.delivery.provider}". tspl can still print a compare link, but that cannot make a task ready.`
+  const refuse = async () => { throw new ProviderError('unsupported', reason) }
+  return { name: repoConfig.delivery.provider, supported: false, reason, authenticate: refuse, findPr: refuse, upsertDraft: refuse, requiredChecks: refuse, observePr: refuse, markReady: refuse }
+}
+
+const createProvider = (repoConfig, deps = {}) => (repoConfig.delivery.provider === 'github' ? createGitHubProvider(repoConfig, deps) : unsupported(repoConfig))
+
+const same = (a, b) => a.name === b.name && (a.appId || null) === (b.appId || null)
+
+/**
+ * The CI requirements for a repo: the project's configured checks plus whatever the provider reports. An empty set is
+ * never "no CI needed" unless the project confirmed that policy.
+ */
+const resolveRequirements = (repoConfig, discovered) => {
+  const delivery = repoConfig.delivery
+  if (delivery.ciPolicy === 'none' && delivery.noCiConfirmed === true) {
+    return { requirements: [], determined: true, confirmedNone: true, problems: [] }
+  }
+  const requirements = [...(delivery.requiredChecks || []).map(item => ({ name: item.name, appId: item.appId || null }))]
+  ;(discovered.requirements || []).forEach(item => {
+    if (!requirements.some(existing => same(existing, item))) requirements.push(item)
+  })
+  const configured = delivery.requiredChecks || []
+  const determined = requirements.length > 0 && (Boolean(discovered.determined) || configured.length > 0)
+  const problems = []
+  if (!determined) {
+    problems.push(...(discovered.problems || []))
+    problems.push(
+      requirements.length
+        ? 'GitHub would not show the branch requirements; add delivery.requiredChecks to .tspl/project.json.'
+        : discovered.determined
+          ? 'No required CI checks are configured on the branch or in the project file. Add delivery.requiredChecks to .tspl/project.json, or confirm that no CI is required.'
+          : 'GitHub would not show the branch requirements and none are configured in the project file; add delivery.requiredChecks.',
+    )
+  }
+  return { requirements, determined, confirmedNone: false, problems }
+}
+
+const FAILED = new Set(['failure', 'cancelled', 'timed_out', 'skipped', 'neutral', 'action_required', 'stale', 'startup_failure'])
+
+/** One requirement against the provider's observations of the tested commit: success, pending or failed. */
+const requirementState = (requirement, observations, headSha) => {
+  const matching = observations.filter(
+    item => item.name === requirement.name && (!requirement.appId || item.appId === requirement.appId) && item.headSha === headSha,
+  )
+  if (!matching.length) return { state: 'pending', reason: 'not reported yet' }
+  const failed = matching.find(item => item.status === 'completed' && FAILED.has(item.conclusion))
+  if (failed) return { state: 'failed', reason: `${failed.conclusion}${failed.url ? ` (${failed.url})` : ''}` }
+  if (matching.every(item => item.status === 'completed' && item.conclusion === 'success')) return { state: 'success' }
+  return { state: 'pending', reason: 'still running' }
+}
+
+const evaluateCi = (requirements, observations, headSha) => {
+  const states = requirements.map(requirement => ({ requirement, ...requirementState(requirement, observations, headSha) }))
+  const state = states.some(item => item.state === 'failed') ? 'failed' : states.some(item => item.state === 'pending') || !states.length ? 'pending' : 'success'
+  return { state, states }
+}
+
+/** Polls for at most maxMs, then returns pending so the run can resume later. */
+const pollCi = async ({ provider, number, requirements, headSha, maxMs = 30000, intervalMs = 5000 }, deps = {}) => {
+  const sleep = deps.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)))
+  const clock = deps.now || Date.now
+  const deadline = clock() + maxMs
+  for (;;) {
+    const pr = await provider.observePr(number)
+    const result = evaluateCi(requirements, pr.checks, headSha)
+    if (pr.headSha !== headSha) return { pr, ...result, state: 'stale' }
+    if (result.state !== 'pending' || clock() + intervalMs > deadline) return { pr, ...result }
+    await sleep(intervalMs)
+  }
+}
+
+module.exports = {
+  createProvider,
+  resolveRequirements,
+  evaluateCi,
+  pollCi,
+}

package/src/runtime-check.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const MIN_NODE_MAJOR = 22
+
+const nodeVersion = () => process.env.TSPL_TEST_NODE_VERSION || process.versions.node
+
+const checkRuntime = (version = nodeVersion()) => {
+  const major = Number.parseInt(String(version).split('.')[0], 10)
+  if (!(major >= MIN_NODE_MAJOR)) {
+    return `tspl needs Node ${MIN_NODE_MAJOR} or newer, but this is Node ${version}. Install a newer Node (https://nodejs.org) and run tspl again.`
+  }
+  return null
+}
+
+module.exports = {
+  MIN_NODE_MAJOR,
+  checkRuntime,
+}

package/src/setup.js

@@ -0,0 +1,180 @@
+'use strict'
+
+const { ENGINE_STEPS } = require('./shared')
+
+const { checkRuntime } = require('./runtime-check')
+
+const REQUIRED_FAILURES = new Set(['failed', 'missing', 'manual'])
+
+const step = (id, label, status, detail, extra = {}) => ({ id, label, status, detail, required: true, ...extra })
+
+const classify = err => (err && err.statusCode === 0 ? 'unreachable' : err && err.statusCode === 401 ? 'expired' : 'error')
+
+const checkApi = async (deps, options, steps, next) => {
+  const config = deps.config.read()
+  const credentials = deps.credentials.read()
+  let apiUrl = config.apiUrl
+  let loggedIn = false
+  let note = ''
+
+  if (credentials.accessToken) {
+    try {
+      const me = await deps.request('GET', '/api/v1/auth/me')
+      loggedIn = true
+      note = `${me.user.email} (${me.role}) in ${me.organization.name} at ${apiUrl}`
+    } catch (err) {
+      const kind = classify(err)
+      if (kind === 'unreachable') {
+        steps.push(step('login', 'TSPL API login', 'failed', `${err.message}. Your saved login was kept; try again when the API is reachable.`))
+        return
+      }
+      note = kind === 'expired' ? 'Your saved login has expired.' : err.message
+    }
+  }
+
+  let change = Boolean(options.api && options.api.replace(/\/+$/, '') !== apiUrl)
+  if (loggedIn && !change && !options.yes) {
+    change = await deps.prompts.confirm({ message: `Logged in: ${note}. Change the API address or account?`, default: false })
+  }
+  if (loggedIn && !change) {
+    steps.push(step('login', 'TSPL API login', 'ok', note))
+    return
+  }
+  if (options.yes && !options.api && !options.email) {
+    steps.push(step('login', 'TSPL API login', 'missing', note || 'Not logged in.'))
+    next.push('Log in: tspl login')
+    return
+  }
+
+  const wanted = options.api || (await deps.prompts.input({ message: 'TSPL API address:', default: apiUrl }))
+  const target = wanted.replace(/\/+$/, '')
+  if (deps.originOf(target) !== deps.originOf(apiUrl)) {
+    deps.credentials.clear()
+  }
+  deps.config.write({ ...config, apiUrl: target })
+  apiUrl = target
+
+  const email = options.email || (await deps.prompts.input({ message: 'Email:' }))
+  const secret = options.password || (await deps.prompts.password({ message: 'Password:', mask: '*' }))
+  try {
+    const result = await deps.login({ api: target, email, password: secret, org: options.org })
+    steps.push(step('login', 'TSPL API login', 'ok', `${result.user.email} (${result.role}) in ${result.organization.name} at ${apiUrl}`))
+  } catch (err) {
+    steps.push(step('login', 'TSPL API login', 'failed', `${err.message} (API ${apiUrl}). Run: tspl login`))
+    next.push('Log in: tspl login')
+  }
+}
+
+const chooseEngines = async (deps, options, steps) => {
+  const installed = deps.engines.detectAll()
+  const names = Object.keys(installed).filter(name => installed[name].installed)
+  if (!names.length) {
+    steps.push(step('engines', 'AI engine', 'missing', 'No AI engine is installed. Install one: npm install -g @anthropic-ai/claude-code (or codex, gemini).'))
+    return
+  }
+  const saved = deps.engines.read()
+  const keep = saved.assignments && Object.values(saved.assignments).every(name => names.includes(name))
+  let assignments = keep ? saved.assignments : null
+  let models = saved.models || {}
+
+  if (assignments && !options.yes) {
+    const change = await deps.prompts.confirm({ message: `Engines are set (${Object.entries(assignments).map(([k, v]) => `${k}: ${v}`).join(', ')}). Change them?`, default: false })
+    if (change) assignments = null
+  }
+  if (!assignments) {
+    const defaults = deps.engines.defaultAssignments(installed)
+    let main = defaults.build
+    if (!options.yes && names.length > 1) {
+      main = await deps.prompts.select({ message: 'Which AI engine should write code?', choices: names.map(name => ({ name, value: name })), default: main })
+    }
+    assignments = { plan: main, build: main, verify: main, bulk: main }
+    const others = names.filter(name => name !== main && name !== 'ollama')
+    if (!options.yes && others.length) {
+      const separate = await deps.prompts.confirm({ message: `Review the code with a different engine than ${main}? (otherwise ${main} reviews in a fresh session)`, default: false })
+      if (separate) assignments.verify = await deps.prompts.select({ message: 'Which engine should review?', choices: others.map(name => ({ name, value: name })) })
+    }
+    if (!options.yes && (await deps.prompts.confirm({ message: 'Choose the engine and model for each step yourself?', default: false }))) {
+      models = {}
+      for (const key of Object.keys(ENGINE_STEPS)) {
+        assignments[key] = await deps.prompts.select({ message: `Engine for ${key} (${ENGINE_STEPS[key]}):`, choices: names.map(name => ({ name, value: name })), default: assignments[key] })
+        const model = await deps.prompts.input({ message: `Model for ${key} (blank for the engine's default):` })
+        if (model.trim()) models[key] = model.trim()
+      }
+    }
+    deps.engines.write({ ...saved, assignments, models })
+  }
+
+  const separate = assignments.build !== assignments.verify
+  const verifyNote = separate
+    ? `review uses ${assignments.verify}, a different engine from ${assignments.build}`
+    : `review uses ${assignments.verify} in a fresh session; it is the same provider as the coding engine, not an independent one`
+  steps.push(step('engines', 'AI engines', 'ok', `code: ${assignments.build}; ${verifyNote}`))
+  return assignments
+}
+
+const probeEngines = async (deps, options, assignments, steps) => {
+  if (!assignments || options.yes) return
+  const ok = await deps.prompts.confirm({ message: 'Send one tiny test prompt to each engine you use? This makes a real AI request.', default: false })
+  if (!ok) {
+    steps.push(step('probe', 'Engine check', 'skipped', 'Not run. Installed is not the same as logged in; run: tspl engines test', { required: false }))
+    return
+  }
+  const models = deps.engines.read().models || {}
+  const targets = new Map(Object.entries(assignments).map(([key, name]) => [name, models[key]]))
+  const failures = []
+  for (const [name, model] of targets) {
+    const result = await deps.engines.run(name, 'Reply with just the word OK.', { model, timeoutMs: 90000 })
+    if (!result.ok) failures.push(`${name}: ${result.limitHit ? 'usage limit reached' : result.error}`)
+  }
+  steps.push(failures.length ? step('probe', 'Engine check', 'failed', failures.join('; ')) : step('probe', 'Engine check', 'ok', 'Every engine answered.'))
+}
+
+const connectTools = async (deps, options, steps, next) => {
+  const tools = options.connect || (options.yes ? [] : await deps.prompts.checkbox({
+    message: 'Add tspl to which AI tools?',
+    choices: Object.entries(deps.tools).filter(([key]) => key !== 'agy').map(([value, name]) => ({ name, value })),
+  }))
+  if (!tools.length) {
+    steps.push(step('connect', 'AI tool integrations', 'skipped', 'None selected. Add one later: tspl connect <tool>', { required: false }))
+    return
+  }
+  for (const tool of tools) {
+    const result = await deps.connect(tool, {})
+    if (result.error) steps.push(step(`connect:${tool}`, `Connect ${tool}`, 'failed', result.error))
+    else if (!result.configured) {
+      steps.push(step(`connect:${tool}`, `Connect ${tool}`, 'manual', 'Could not be configured automatically.'))
+      next.push(...result.manualSteps)
+    } else {
+      steps.push(step(`connect:${tool}`, `Connect ${tool}`, 'ok', 'Configured.'))
+      next.push(...result.manualSteps)
+    }
+  }
+}
+
+/**
+ * Configures this machine as a TSPL developer client. It never looks at projects: that is `tspl init`.
+ * Returns { ready, steps, next }; `ready` is false while any required step failed or needs a manual action.
+ */
+const configureMachine = async (options = {}, deps) => {
+  const steps = []
+  const next = []
+
+  const runtime = checkRuntime(deps.nodeVersion)
+  steps.push(runtime ? step('node', 'Node.js', 'failed', runtime) : step('node', 'Node.js', 'ok', `Node ${deps.nodeVersion || process.versions.node}`))
+  const git = deps.gitVersion()
+  steps.push(git ? step('git', 'Git', 'ok', git) : step('git', 'Git', 'failed', 'Git was not found. Install Git, then run tspl setup again.'))
+
+  await checkApi(deps, options, steps, next)
+  const assignments = await chooseEngines(deps, options, steps)
+  await probeEngines(deps, options, assignments, steps)
+  await connectTools(deps, options, steps, next)
+
+  const ready = !steps.some(item => item.required && REQUIRED_FAILURES.has(item.status))
+  if (ready) next.unshift('Run tspl init inside a project folder.')
+  else next.push('Fix the items above and run tspl setup again.')
+  return { ready, steps, next }
+}
+
+module.exports = {
+  configureMachine,
+}

package/src/shared/approaches.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const { hashValue } = require('./workflow')
+const string = (value, name, max) => {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > max) throw new Error(`${name} must be nonempty and at most ${max} characters`)
+  return value.trim()
+}
+const strings = (value, name, maxItems, maxLength, min = 1) => {
+  if (!Array.isArray(value) || value.length < min || value.length > maxItems) throw new Error(`${name} must contain ${min}-${maxItems} items`)
+  return value.map(item => string(item, name, maxLength))
+}
+const validateApproachProposal = value => {
+  if (!value || !Array.isArray(value.options) || value.options.length < 2 || value.options.length > 3) throw new Error('Offer two or three implementation approaches')
+  const options = value.options.map(item => ({
+    id: string(item.id, 'Option ID', 60), title: string(item.title, 'Title', 200),
+    summary: string(item.summary, 'Summary', 2000), benefits: strings(item.benefits, 'Benefits', 10, 1000),
+    drawbacks: strings(item.drawbacks, 'Drawbacks', 10, 1000), files: strings(item.files || [], 'Files', 100, 1000, 0),
+  }))
+  const ids = new Set(options.map(item => item.id))
+  if (ids.size !== options.length) throw new Error('Option IDs must be unique')
+  if (!ids.has(value.recommendedId)) throw new Error('Recommend exactly one of the offered options')
+  const notes = value.codeNotes || []
+  if (!Array.isArray(notes) || notes.length > 12) throw new Error('Code notes must contain at most 12 items')
+  const codeNotes = notes.map(item => ({ file: string(item && item.file, 'Code note file', 1000), lines: item.lines ? string(item.lines, 'Code note lines', 40) : null, note: string(item.note, 'Code note', 600) }))
+  return { options, recommendedId: value.recommendedId, reason: string(value.reason, 'Recommendation reason', 2000), ...(codeNotes.length ? { codeNotes } : {}) }
+}
+const approachBasis = card => {
+  const value = card || {}
+  const doneWhen = value.doneWhen || []
+  return hashValue({ ...value, apps: value.apps || [], doneWhen, testCases: doneWhen.map((text, i) => {
+    const item = (value.testCases || [])[i] || {}
+    return { steps: item.steps || [], expected: item.expected || text }
+  }) })
+}
+const bindApproach = (approaches, card, reference) => {
+  if (!approaches || !approaches.selection) throw new Error('Choose an implementation approach before submitting a plan')
+  if (approaches.basis !== approachBasis(card)) throw new Error('Requirements changed; propose approaches again and ask the user to choose')
+  const selection = approaches.selection
+  if (!reference || reference.version !== approaches.version || reference.optionId !== selection.optionId || selection.version !== approaches.version) throw new Error('The approach selection is stale or does not match this plan; refresh the task')
+  const option = approaches.options.find(item => item.id === selection.optionId)
+  if (!option) throw new Error('Selected approach not found')
+  return { version: approaches.version, optionId: option.id, option, recommendedId: approaches.recommendedId, reason: approaches.reason, selection, basis: approaches.basis }
+}
+module.exports = { validateApproachProposal, approachBasis, bindApproach }

package/src/shared/constants.js

@@ -0,0 +1,89 @@
+'use strict'
+
+const ROLES = {
+  OWNER: 'owner',
+  ADMIN: 'admin',
+  PM: 'pm',
+  DEVELOPER: 'developer',
+  VIEWER: 'viewer',
+}
+
+const PROJECT_MANAGER_ROLES = [ROLES.OWNER, ROLES.ADMIN, ROLES.PM]
+
+const ORG_WIDE_ROLES = [ROLES.OWNER, ROLES.ADMIN]
+
+const PROJECT_CONTRIBUTOR_ROLES = [
+  ROLES.OWNER,
+  ROLES.ADMIN,
+  ROLES.PM,
+  ROLES.DEVELOPER,
+]
+
+const ENGINE_STEPS = {
+  plan: 'questions and plans',
+  build: 'writing code',
+  verify: 'checking the work (should differ from build)',
+  bulk: 'bulk reading during analysis',
+}
+
+const CLIENT_TYPES = {
+  CLI: 'cli',
+  WEB: 'web',
+}
+
+const USER_STATUS = {
+  ACTIVE: 'active',
+  DISABLED: 'disabled',
+}
+
+const MEMBERSHIP_STATUS = {
+  INVITED: 'invited',
+  ACTIVE: 'active',
+  REMOVED: 'removed',
+}
+
+const ORG_STATUS = {
+  ACTIVE: 'active',
+  SUSPENDED: 'suspended',
+}
+
+const PROJECT_STATUS = {
+  ACTIVE: 'active',
+  ARCHIVED: 'archived',
+}
+
+const TASK_STATUS = {
+  DRAFT: 'draft',
+  PLAN_REVIEW: 'plan-review',
+  PM_REVIEW: 'pm-review',
+  APPROVED: 'approved',
+  CHANGES_REQUESTED: 'changes-requested',
+  BUILDING: 'building',
+  DONE: 'done',
+}
+
+const APPROVAL_STAGES = {
+  DEVELOPER: 'developer',
+  PM: 'pm',
+}
+
+const USAGE_STEPS = ['intake', 'plan', 'build', 'verify', 'other']
+
+const TEST_FILE = /(^|\/)(tests?|__tests__|spec)\/|\.(spec|test)\.[^/]+$/
+
+module.exports = {
+  ROLES,
+  PROJECT_MANAGER_ROLES,
+  ORG_WIDE_ROLES,
+  PROJECT_CONTRIBUTOR_ROLES,
+  ENGINE_STEPS,
+  CLIENT_TYPES,
+  USER_STATUS,
+  MEMBERSHIP_STATUS,
+  ORG_STATUS,
+  PROJECT_STATUS,
+  TASK_STATUS,
+  APPROVAL_STAGES,
+  USAGE_STEPS,
+  TEST_FILE,
+}

package/src/shared/index.js

@@ -0,0 +1,8 @@
+'use strict'
+
+module.exports = {
+  ...require('./constants'),
+  ...require('./approaches'),
+  ...require('./workflow'),
+  ...require('./workflow-progress'),
+}