tspl-cli 0.0.0-stage → 0.1.1

package/src/commands/find.command.js

@@ -0,0 +1,107 @@
+'use strict'
+
+const { setupProject, localRepos } = require('../workspace')
+const { refreshIndex } = require('../analysis/analyzer')
+const { createGraph } = require('../find/graph')
+const { createSearch } = require('../find/search')
+const { fetchDue, syncInBackground } = require('./sync.command')
+
+const CONFIDENCE = { high: 'HIGH', medium: 'MEDIUM', low: 'LOW' }
+
+const printResult = (result, context) => {
+  console.log(`Searched ${context.files.toLocaleString()} files in ${context.repos} repos of ${context.project} in ${context.ms}ms. AI tokens used: 0.\n`)
+  if (!result.files.length) {
+    console.log('Nothing matched. Try other words, e.g. a screen name, field name or API path.')
+    return
+  }
+
+  const { level, reasons } = result.confidence
+  console.log(`Confidence: ${CONFIDENCE[level]}  (${reasons.join('; ')})\n`)
+
+  const width = Math.max(...result.files.map(file => file.repo.length))
+  result.files.forEach((file, i) => {
+    console.log(`${String(i + 1).padStart(3)}. ${file.repo.padEnd(width)}  ${file.path}`)
+    if (file.symbols.length) {
+      console.log(`${' '.repeat(width + 7)}${file.symbols.map(symbol => (symbol.line ? `${symbol.name} (line ${symbol.line})` : symbol.name)).join(', ')}`)
+    }
+    if (file.why.length) {
+      console.log(`${' '.repeat(width + 7)}why: ${file.why.join(' · ')}`)
+    }
+    if (file.similar.length) {
+      console.log(`${' '.repeat(width + 7)}similar: ${file.similar.join(', ')}`)
+    }
+  })
+
+  if (result.searchSteps.length) {
+    console.log('\nAlso search for:')
+    result.searchSteps.forEach(step => console.log(`  ${step.pattern}   (${step.why})`))
+  }
+
+  if (result.chains.length) {
+    console.log('\nHow they connect:')
+    result.chains.forEach(chain => {
+      chain.forEach((step, i) => {
+        const arrow = i ? `  → ${step.detail ? `${step.detail} → ` : ''}` : '  '
+        console.log(`  ${arrow}${step.repo}  ${step.path}`)
+      })
+      console.log('')
+    })
+  }
+
+  if (result.placement.length) {
+    console.log(`${result.chains.length ? '' : '\n'}New files, if needed, usually go:`)
+    result.placement.forEach(place => console.log(`  ${place.repo}  ${place.pattern}  (${place.count} like this)`))
+  }
+
+  console.log(`\nWords used: ${result.terms.join(', ')}${result.unknown.length ? `  ·  not found in code: ${result.unknown.join(', ')}` : ''}`)
+}
+
+const find = async (words, options) => {
+  const task = words.join(' ').trim()
+  if (!task) {
+    throw new Error('Describe the task, e.g. tspl find "add notes when closing work orders"')
+  }
+
+  const setup = await setupProject(process.cwd(), {})
+  if (!setup) {
+    return
+  }
+  const repos = localRepos(setup.project)
+  if (!repos.length) {
+    throw new Error('No repos of this project are linked on this computer. Run tspl in the project folder first.')
+  }
+
+  const started = Date.now()
+  const failed = []
+  let changed = false
+  const index = await refreshIndex(setup.project, repos, (repo, repoIndex, err, isNew) => {
+    if (err) failed.push(`${repo.name}: ${err.message}`)
+    changed = changed || Boolean(isNew)
+  })
+  if (changed || fetchDue(setup.project._id)) syncInBackground(process.cwd())
+  const graph = createGraph(index)
+  const result = createSearch(graph).find(task, { limit: Number(options.limit) || 15 })
+
+  if (options.json) {
+    console.log(JSON.stringify({ ...result, files: result.files.map(({ id, ...file }) => file), skippedRepos: failed }, null, 2))
+    return
+  }
+  failed.forEach(message => console.log(`Skipped ${message}`))
+  printResult(result, {
+    project: setup.project.name,
+    repos: graph.repos.length,
+    files: graph.files.length,
+    ms: Date.now() - started,
+  })
+}
+
+module.exports = {
+  register(program) {
+    program
+      .command('find <task...>')
+      .description('Find the code a task is about, across all repos of the project (no AI, no tokens)')
+      .option('--limit <n>', 'how many files to show', '15')
+      .option('--json', 'print the result as JSON')
+      .action(find)
+  },
+}

package/src/commands/init.command.js

@@ -0,0 +1,79 @@
+'use strict'
+
+const Prompts = require('@inquirer/prompts')
+
+const { request } = require('../api-client')
+const config = require('../config-store')
+const { setupProject } = require('../workspace')
+const { initializeProject } = require('../project-init')
+const { organizationOfFolder } = require('../active-org')
+
+const defaultDeps = () => ({
+  prompts: Prompts,
+  request,
+  credentials: { read: config.readCredentials },
+  links: { read: config.readLinks, write: config.writeLinks },
+  setupProject,
+})
+
+/** The organization this project belongs to: the one already saved for the folder, else the one you pick. */
+const chooseOrganization = async (folder, options) => {
+  const known = organizationOfFolder(folder || process.cwd())
+  const accounts = [...new Map(config.listAccounts().map(account => [account.organization, config.accountFor(account.organization)])).values()]
+  const saved = options.org || known
+  const slugs = accounts.map(account => account.organization)
+  if (saved) {
+    if (!slugs.includes(saved)) throw new Error(`You are not logged in to "${saved}" on this computer. Run: tspl login --org ${saved}`)
+    return saved
+  }
+  if (slugs.length <= 1) return slugs[0] || null
+  const current = config.readCredentials().organization
+  return Prompts.select({
+    message: 'Which organization does this project belong to?',
+    choices: accounts.map(account => ({ name: `${account.organization} (${account.email})`, value: account.organization })),
+    default: slugs.includes(current) ? current : undefined,
+  })
+}
+
+const init = async (folder, options) => {
+  const organization = await chooseOrganization(folder, options)
+  if (organization) {
+    config.setActiveOrganization(organization)
+    console.log(`Organization: ${organization}`)
+  }
+  const result = await initializeProject(folder, options, defaultDeps())
+  if (!result) {
+    console.log('Nothing initialized.')
+    return
+  }
+  const { root, config: project, created, readiness } = result
+  if (project) {
+    console.log(`${created ? 'Initialized' : 'Adopted'} ${project.project.slug} in ${root}`)
+    console.log(`  ${project.repos.length} repo${project.repos.length === 1 ? '' : 's'}, ${project.checks.length} check${project.checks.length === 1 ? '' : 's'}`)
+    if (created) console.log('  Commit .tspl/ so the whole team shares it. Personal paths stay in ~/.tspl.')
+  }
+  readiness.warnings.forEach(line => console.log(`  ! ${line}`))
+  if (readiness.ready) {
+    console.log('\nReady. Next: tspl task new "<what should change>"')
+    return
+  }
+  console.log('\nNot ready for a tested-PR workflow yet:')
+  readiness.problems.forEach(line => console.log(`  ✗ ${line}`))
+  process.exitCode = 1
+}
+
+module.exports = {
+  init,
+  register(program) {
+    program
+      .command('init [folder]')
+      .description('Set up this project folder: link it, find its checks and save shared project rules in .tspl/')
+      .option('-y, --yes', 'accept supported suggestions without asking')
+      .option('--org <slug>', 'the organization this project belongs to, if you are logged in to several')
+      .option('--project <slug>', 'add this folder to an existing project instead of choosing or creating one')
+      .option('--name <name>', 'project name, if a new project is created')
+      .option('--manifest-home <repo>', 'for a folder of several repos: the repo that holds the shared .tspl files')
+      .option('--no-e2e', 'do not set up browser tests (Playwright) for web apps that have none')
+      .action(init)
+  },
+}

package/src/commands/link.command.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const Path = require('path')
+
+const { setupProject } = require('../workspace')
+const { readCredentials, readLinks, writeLinks } = require('../config-store')
+
+const printSetup = setup => {
+  if (!setup) {
+    console.log('Nothing linked.')
+    return
+  }
+  const { project, folder, linked } = setup
+  console.log(`${project.name} (${project.slug}): ${linked.length} of ${project.repos.length} repos linked from ${folder}`)
+  linked.forEach(repo => {
+    console.log(`  ${repo.name.padEnd(24)} [${repo.defaultBaseBranch}]  ${repo.stacks.join(', ') || 'unknown stack'}`)
+  })
+}
+
+const inside = (dir, folder) =>
+  Boolean(folder) && (dir === folder || dir.startsWith(folder + Path.sep))
+
+const unlink = async projectRef => {
+  const links = readLinks()
+  const cwd = process.cwd()
+  const keys = projectRef
+    ? [`${readCredentials().organization}/${projectRef}`].filter(key => links[key])
+    : Object.keys(links).filter(
+        key =>
+          inside(cwd, links[key].folder) ||
+          Object.values(links[key].repos || {}).some(repo => inside(cwd, repo.path)),
+      )
+
+  if (!keys.length) {
+    console.log(
+      projectRef
+        ? `"${projectRef}" is not linked on this machine.`
+        : 'This folder is not linked to any project on this machine.',
+    )
+    return
+  }
+
+  keys.forEach(key => delete links[key])
+  writeLinks(links)
+  console.log(
+    `Forgot ${keys.map(key => key.split('/')[1]).join(', ')} on this machine. Run tspl in the project folder to link again.`,
+  )
+}
+
+module.exports = {
+  printSetup,
+  register(program) {
+    program
+      .command('link [folder]', { hidden: true })
+      .description('Connect the repos in a folder to their project')
+      .option('-y, --yes', 'accept every suggestion without asking')
+      .option('--name <name>', 'project name, if a new project is created')
+      .action(async (folder, options) => printSetup(await setupProject(folder, options)))
+
+    program
+      .command('unlink [project]')
+      .description('Forget where a project\'s repos are on this machine (default: the project in this folder)')
+      .action(unlink)
+  },
+}

package/src/commands/mcp.command.js

@@ -0,0 +1,12 @@
+'use strict'
+
+const { startServer } = require('../mcp/server')
+
+module.exports = {
+  register(program) {
+    program
+      .command('mcp', { hidden: true })
+      .description('Run the tspl plug-in for AI tools (started by the AI tool, not by hand)')
+      .action(() => startServer(process.cwd()))
+  },
+}

package/src/commands/member.command.js

@@ -0,0 +1,82 @@
+'use strict'
+
+const { confirm } = require('@inquirer/prompts')
+const { ROLES } = require('../shared')
+
+const { request } = require('../api-client')
+
+const ROLE_NAMES = Object.values(ROLES)
+
+const checkRole = role => {
+  if (!ROLE_NAMES.includes(role)) {
+    throw new Error(`Role must be one of: ${ROLE_NAMES.join(', ')}`)
+  }
+  return role
+}
+
+const find = async email => {
+  const members = await request('GET', '/api/v1/members')
+  const member = members.find(item => item.email === email.toLowerCase())
+  if (!member) {
+    throw new Error(`${email} is not in your organization`)
+  }
+  return member
+}
+
+const add = async (email, options) => {
+  const member = await request('POST', '/api/v1/members', {
+    email,
+    name: options.name,
+    role: checkRole(options.role),
+  })
+  if (member.existingAccount) {
+    console.log(`${member.email} already had a TSPL account; they are now ${member.role} in your organization and log in with their own password.`)
+    return
+  }
+  console.log(`Added ${member.name} <${member.email}> as ${member.role}.`)
+  console.log(`Temporary password: ${member.temporaryPassword}`)
+  console.log('Send it to them privately (not by email with the address). They log in with "tspl login" and must then set their own with "tspl password".')
+}
+
+const list = async () => {
+  const members = await request('GET', '/api/v1/members')
+  const width = Math.max(...members.map(member => member.email.length))
+  members.forEach(member => {
+    const seen = member.lastLoginAt ? `last login ${new Date(member.lastLoginAt).toLocaleDateString()}` : 'never logged in'
+    console.log(`${member.email.padEnd(width)}  ${member.role.padEnd(9)}  ${member.name}  · ${seen}${member.passwordChangeRequired ? ' · temporary password' : ''}`)
+  })
+}
+
+const role = async (email, newRole) => {
+  const member = await find(email)
+  await request('PUT', `/api/v1/members/${member.userId}`, { role: checkRole(newRole) })
+  console.log(`${email} is now ${newRole}.`)
+}
+
+const remove = async (email, options) => {
+  const member = await find(email)
+  if (!options.yes && !(await confirm({ message: `Remove ${email} from the organization? They lose access at once.`, default: false }))) {
+    return
+  }
+  await request('DELETE', `/api/v1/members/${member.userId}`)
+  console.log(`${email} was removed and logged out.`)
+}
+
+module.exports = {
+  register(program) {
+    const member = program.command('member').description('People in your organization and their roles')
+    member
+      .command('add <email>')
+      .description('Add a person (owner or admin); new accounts get a temporary password')
+      .requiredOption('--name <name>', 'their name')
+      .requiredOption('--role <role>', `one of: ${ROLE_NAMES.join(', ')}`)
+      .action(add)
+    member.command('list').description('Everyone in the organization with their role (owner, admin or PM)').action(list)
+    member.command('role <email> <role>').description('Change a person\'s role (owner or admin)').action(role)
+    member
+      .command('remove <email>')
+      .description('Remove a person from the organization (owner or admin)')
+      .option('-y, --yes', 'do not ask to confirm')
+      .action(remove)
+  },
+}

package/src/commands/plan.command.js

@@ -0,0 +1,161 @@
+'use strict'
+
+const { spawn } = require('child_process')
+const { confirm } = require('@inquirer/prompts')
+
+const { request } = require('../api-client')
+const { findProject } = require('../workspace')
+const { writePlanPage } = require('../config-store')
+const { renderChecklist } = require('../task/plan')
+const { renderPlanPage } = require('../task/plan-page')
+
+const STATUS = {
+  draft: 'no plan yet',
+  'plan-review': 'waiting for the developer',
+  'pm-review': 'waiting for the PM',
+  approved: 'approved, ready to build',
+  'changes-requested': 'changes requested',
+  building: 'building',
+  done: 'done',
+}
+
+const projectOf = async options => {
+  if (options.project) {
+    return request('GET', `/api/v1/projects/${encodeURIComponent(options.project)}`)
+  }
+  try {
+    return (await findProject(process.cwd())).project
+  } catch (err) {
+    throw new Error('Run this inside a project folder, or add --project <name>')
+  }
+}
+
+const tasksUrl = (project, key = '') => `/api/v1/projects/${project._id}/tasks${key ? `/${encodeURIComponent(key)}` : ''}`
+
+const openFile = file => {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open'
+  const child = spawn(command, [file], { detached: true, stdio: 'ignore' })
+  child.on('error', () => {})
+  child.unref()
+}
+
+const decisionLines = task =>
+  (task.decisions || []).map(decision =>
+    `  ${decision.approved ? '✓' : '✗'} ${decision.stage} ${decision.approved ? 'approved' : 'asked for changes'} v${decision.planVersion || '-'}` +
+      `${decision.userName ? ` by ${decision.userName}` : ''}${decision.at ? ` on ${new Date(decision.at).toLocaleString()}` : ''}${decision.note ? ` — "${decision.note}"` : ''}`)
+
+const list = async options => {
+  const project = await projectOf(options)
+  const query = options.all ? '' : '?status=plan-review,pm-review,changes-requested,approved'
+  const tasks = await request('GET', `${tasksUrl(project)}${query}`)
+  if (!tasks.length) {
+    console.log(options.all ? 'No tasks yet.' : 'No plans waiting. Use --all to see every task.')
+    return
+  }
+  tasks.forEach(task => {
+    const version = task.plan && task.plan.version ? ` v${task.plan.version}` : ''
+    console.log(`${task.key.padEnd(18)} ${(STATUS[task.status] || task.status).padEnd(26)} ${task.ticket ? `${task.ticket} · ` : ''}${task.title || ''}${version}`)
+  })
+}
+
+const show = async (key, options) => {
+  const project = await projectOf(options)
+  const task = await request('GET', tasksUrl(project, key))
+  if (options.page) {
+    const file = writePlanPage(task.key, renderPlanPage(task, project.name))
+    openFile(file)
+    console.log(`Opened the plan page: ${file}`)
+    return
+  }
+  console.log(`${task.key} · ${STATUS[task.status] || task.status}${task.requirePmApproval === false ? ' · PM approval not required' : ''}`)
+  decisionLines(task).forEach(line => console.log(line))
+  console.log('')
+  if (!task.plan) {
+    console.log('No plan yet.')
+    return
+  }
+  const card = { apps: [], doneWhen: [], ...task.card }
+  const review = { edit: [], create: [], remove: [], screens: [], tests: [], warnings: [], companions: [], notes: '', ...task.plan }
+  console.log(renderChecklist(review, card, `${task.key} v${task.plan.version}`))
+  console.log(`\nSee it as a page: tspl plan show ${task.key} --page`)
+}
+
+const AI_SHELL = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_CI', 'GEMINI_CLI', 'CURSOR_AGENT']
+
+const atKeyboard = () => Boolean(process.stdin.isTTY && process.stdout.isTTY) && !AI_SHELL.some(name => process.env[name])
+
+const decide = approved => async (key, options) => {
+  if (!approved && !options.note) {
+    throw new Error('Say what should change: --note "…"')
+  }
+  if (!atKeyboard()) {
+    throw new Error('Plans are approved by a person: run this in your own terminal, or use the tspl console. It does not work from an AI tool.')
+  }
+  const project = await projectOf(options)
+  const task = await request('GET', tasksUrl(project, key))
+  const stage = task.status === 'pm-review' ? 'pm' : 'developer'
+  if (!['plan-review', 'changes-requested', 'pm-review'].includes(task.status)) {
+    throw new Error(`Nothing to decide: the plan is ${STATUS[task.status] || task.status}`)
+  }
+  const card = { apps: [], doneWhen: [], ...task.card }
+  const review = { edit: [], create: [], remove: [], screens: [], tests: [], warnings: [], companions: [], notes: '', ...task.plan }
+  console.log(`${renderChecklist(review, card, `${task.key} v${task.plan.version}`)}\n`)
+  const sure = await confirm({
+    message: approved ? `Approve plan v${task.plan.version} as ${stage === 'pm' ? 'PM' : 'developer'}?` : `Send plan v${task.plan.version} back with your note?`,
+    default: approved,
+  })
+  if (!sure) {
+    console.log('Nothing recorded.')
+    return
+  }
+  const updated = await request('POST', `${tasksUrl(project, key)}/decisions`, {
+    stage,
+    approved,
+    note: options.note || '',
+    planVersion: task.plan.version,
+  })
+  console.log(`${stage === 'pm' ? 'PM' : 'Developer'} ${approved ? 'approved' : 'asked for changes to'} plan v${updated.plan.version}. Now: ${STATUS[updated.status] || updated.status}.`)
+}
+
+const amend = async (key, options) => {
+  const project = await projectOf(options)
+  const result = await request('POST', `${tasksUrl(project, key)}/workflow/amend`, { note: options.note || '' })
+  console.log(`${key}: the run was cancelled and the plan can be changed. Status: ${STATUS[result.task.status] || result.task.status}. Ask your AI tool for a new plan version (/tspl ${key}).`)
+}
+
+module.exports = {
+  atKeyboard,
+  register(program) {
+    const plan = program.command('plan').description('See and approve task plans (developer, then PM)')
+    plan
+      .command('list')
+      .description('Plans waiting for a decision (--all for every task)')
+      .option('--all', 'every task, not only plans waiting for a decision')
+      .option('--project <name>', 'the project, if you are not in its folder')
+      .action(list)
+    plan
+      .command('show <task>')
+      .description('Show a plan: files to edit, create and remove per repo, tests, approvals')
+      .option('--page', 'open it as a page in the browser')
+      .option('--project <name>', 'the project, if you are not in its folder')
+      .action(show)
+    plan
+      .command('approve <task>')
+      .description('Approve a plan (as developer, or as PM when it waits for the PM)')
+      .option('--note <text>', 'a note to keep with the approval')
+      .option('--project <name>', 'the project, if you are not in its folder')
+      .action(decide(true))
+    plan
+      .command('amend <task>')
+      .description('Cancel a stopped build or run so a new plan version can be submitted (the old approvals and results no longer count)')
+      .option('--note <text>', 'why the plan changes')
+      .option('--project <name>', 'the project, if you are not in its folder')
+      .action(amend)
+    plan
+      .command('reject <task>')
+      .description('Send a plan back with what should change')
+      .requiredOption('--note <text>', 'what should change')
+      .option('--project <name>', 'the project, if you are not in its folder')
+      .action(decide(false))
+  },
+}