tspl-cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# tspl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`tspl` is the command-line tool for the TSPL AI feature-development tool. It reads your repositories (no AI, nothing leaves your machine), turns a task into a clear brief, plans the change with you, enforces the approved plan while an AI tool builds it, runs the tests and opens the pull request.
+
+```text
+npm i -g tspl-cli → tspl setup → tspl init → tspl task new "…" → tspl t-xxxx → tspl plan approve t-xxxx → tspl task run t-xxxx
+```
+
+## Requirements
+
+- Node 22 or newer
+- git
+- A TSPL account and the address of your TSPL API (ask your team)
+- An AI tool such as Claude Code, Codex, Cursor or Gemini, using your own subscription
+
+## 1. Install (once per computer)
+
+```bash
+npm install -g tspl-cli
+tspl --version
+```
+
+Update later with `npm install -g tspl-cli@latest`.
+
+## 2. Configure (once per computer)
+
+```bash
+tspl setup --api https://<your-tspl-api> --connect claude
+tspl whoami
+```
+
+`tspl setup` walks you through:
+
+- logging in to the TSPL API with your email and password
+- choosing which AI engine does each step
+- connecting your AI tool: the `/tspl` command, the edit lock and the MCP plug-in
+
+Connect other tools with `--connect codex cursor gemini antigravity vscode`, or later with `tspl connect <tool>`. Restart your AI tool after connecting it.
+
+Several organizations:
+
+```bash
+tspl login --org <slug>   # log in to a specific organization
+tspl org use <slug>       # switch to one you are already logged in to
+```
+
+## 3. Set up a project (once per project folder)
+
+Run inside the project folder:
+
+```bash
+cd path/to/your/project
+tspl init
+```
+
+This links the folder to a TSPL project, finds its test and lint checks, and saves `.tspl/project.json`. Commit that file so the whole team shares the same rules. tspl then reads the code into a local map (no AI, nothing uploaded).
+
+Running `tspl` with no arguments sets the folder up if needed, or shows its open tasks.
+
+## 4. Work on a task
+
+```bash
+tspl task new "Add a Contact page at /contact"   # answer a few questions; prints the task id, e.g. t-xxxx
+tspl t-xxxx                                      # compare approaches, pick one, write the plan
+tspl plan show t-xxxx                            # files to edit, create and remove, and tests
+tspl plan approve t-xxxx                         # developer approves, then the PM approves
+tspl task run t-xxxx                             # code, run checks, repair, review, draft pull requests, CI
+```
+
+Other ways to start a task:
+
+```bash
+tspl task new --ticket TEST-1 "Add About page"   # with a ticket id
+tspl task new --file ticket.txt                  # ticket text from a file
+```
+
+`tspl task run` asks which branch each repo starts from and the name of the new branch. Skip the questions with:
+
+```bash
+tspl task run t-xxxx --base main --branch feature/contact-page
+```
+
+Run `tspl task run t-xxxx` again to resume after a stop. To retry one stage, add `--stage testing` or `--stage reviewing`.
+
+From your AI tool, type `/tspl <what should change>` to do the same steps there.
+
+## Everyday commands
+
+| What | Command |
+| --- | --- |
+| Where a task is and the next command | `tspl task status t-xxxx` |
+| Tasks on this computer | `tspl task list` |
+| Show a task brief | `tspl task show t-xxxx` |
+| Change a task | `tspl task edit t-xxxx` |
+| Plans waiting for a decision | `tspl plan list` |
+| Send a plan back | `tspl plan reject t-xxxx --note "..."` |
+| PM confirms scope / sends it back | `tspl task scope t-xxxx` / `tspl task scope t-xxxx --back --note "..."` |
+| Keep going through approvals and CI | `tspl task watch t-xxxx` |
+| Builds in progress | `tspl build status` |
+| Stop a build and lift its edit lock | `tspl build stop t-xxxx` |
+| Allow a new plan after a stop | `tspl plan amend t-xxxx` |
+| Delete a task | `tspl task delete t-xxxx --reason "..."` |
+| Who is logged in | `tspl whoami` |
+| AI engine per step | `tspl engines` |
+
+## Team and projects
+
+```bash
+tspl project list                                # projects you can see
+tspl member list                                 # people and their roles
+tspl member add <email>                          # owner or admin
+tspl member role <email> <role>
+tspl project add-member <project> <email>
+tspl project remove-member <project> <email>
+```
+
+## Where tspl keeps data
+
+- `~/.tspl`: your login, settings and the local code map of each repo. The map is built from git and never uploaded.
+- `.tspl/project.json` in your project: the project's checks and settings, meant to be committed.
+- The TSPL server stores tasks, plans, approvals, reports and AI usage, never your code.
+
+## Help
+
+```bash
+tspl --help
+tspl <command> --help
+```

package/bin/tspl.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+'use strict'
+
+const problem = require('../src/runtime-check').checkRuntime()
+if (problem) {
+  console.error(problem)
+  process.exit(1)
+}
+
+require('../src/index').run(process.argv)

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "tspl-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "TSPL command-line tool: learns your code, plans changes with you, builds, tests and opens pull requests",
+  "keywords": [
+    "tspl",
+    "cli",
+    "ai",
+    "mcp",
+    "claude",
+    "code-review",
+    "planning"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meet2amit/tspl-pm-aitool.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "tspl": "bin/tspl.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.9",
+    "@inquirer/prompts": "^8.7.2",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "commander": "^15.0.0",
+    "zod": "^4.6.5"
+  },
+  "scripts": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/active-org.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const Fs = require('fs')
+const Path = require('path')
+
+const { readLinks, accountFor, setActiveOrganization } = require('./config-store')
+const { findProjectConfig } = require('./project-config')
+
+const inside = (dir, parent) => Boolean(parent) && (dir === parent || dir.startsWith(`${parent}${Path.sep}`))
+
+const real = dir => {
+  try {
+    return Fs.realpathSync(dir)
+  } catch (err) {
+    return Path.resolve(dir)
+  }
+}
+
+/**
+ * The organization a folder belongs to: the one named in its .tspl/project.json, else the one whose linked project
+ * contains the folder. null when the folder is not part of a project or the link is ambiguous.
+ */
+const organizationOfFolder = cwd => {
+  try {
+    const found = findProjectConfig(cwd)
+    if (found) return found.config.organization
+  } catch (err) {
+    // a broken project file is reported by the command that needs it
+  }
+  const dir = real(cwd)
+  const orgs = new Set(
+    Object.entries(readLinks())
+      .filter(([, link]) => inside(dir, link.folder && real(link.folder)) || Object.values(link.repos || {}).some(repo => inside(dir, repo.path && real(repo.path))))
+      .map(([key]) => key.split('/')[0]),
+  )
+  return orgs.size === 1 ? [...orgs][0] : null
+}
+
+/** Makes every command in this folder use the login of the folder's organization (when this machine has one). */
+const useFolderOrganization = cwd => {
+  const organization = organizationOfFolder(cwd)
+  if (organization && accountFor(organization)) setActiveOrganization(organization)
+  return organization
+}
+
+module.exports = {
+  organizationOfFolder,
+  useFolderOrganization,
+}

package/src/analysis/analyzer.js

@@ -0,0 +1,61 @@
+'use strict'
+
+const { readIndex, writeIndex } = require('../config-store')
+const { buildRepoIndex } = require('./repo-index')
+
+const COUNTED = ['routes', 'models', 'uiRoutes', 'screens', 'components', 'httpCalls']
+
+const refreshIndex = async (project, repos, onRepo = () => {}, saved = readIndex(project._id)) => {
+  const index = { projectId: project._id, repos: { ...(saved.repos || {}) } }
+  let changed = false
+  for (const repo of repos) {
+    try {
+      const repoIndex = await buildRepoIndex(repo, index.repos[repo._id])
+      const isNew = Boolean(repoIndex.newlyParsed || !index.repos[repo._id] || index.repos[repo._id].commitSha !== repoIndex.commitSha)
+      changed = changed || isNew
+      index.repos[repo._id] = repoIndex
+      onRepo(repo, repoIndex, null, isNew)
+    } catch (err) {
+      onRepo(repo, null, err)
+    }
+  }
+  const linked = new Set(repos.map(repo => repo._id))
+  Object.keys(index.repos)
+    .filter(id => !linked.has(id))
+    .forEach(id => {
+      delete index.repos[id]
+      changed = true
+    })
+  if (changed) {
+    writeIndex(project._id, index)
+  }
+  return index
+}
+
+const describeRepo = repoIndex => {
+  const stats = { byStatus: {} }
+  COUNTED.forEach(key => { stats[key] = 0 })
+  repoIndex.files.forEach(file => {
+    stats.byStatus[file.status] = (stats.byStatus[file.status] || 0) + 1
+  })
+  Object.values(repoIndex.facts).forEach(facts => {
+    if (!facts) return
+    COUNTED.forEach(key => {
+      if (Array.isArray(facts[key])) stats[key] += facts[key].length
+    })
+  })
+  const codeFiles = Object.keys(repoIndex.facts).length
+  return {
+    branch: repoIndex.branch,
+    commitSha: repoIndex.commitSha,
+    date: repoIndex.date,
+    codeFiles,
+    newlyAnalyzed: repoIndex.newlyParsed || 0,
+    stats,
+  }
+}
+
+module.exports = {
+  refreshIndex,
+  describeRepo,
+}

package/src/analysis/extract.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const Path = require('path')
+const { extractJs } = require('./js-parser')
+const { extractPy } = require('./py-parser')
+const { extractHtml } = require('./html-parser')
+
+const PARSER_VERSION = 3
+
+const LANGUAGES = {
+  '.js': 'javascript',
+  '.jsx': 'javascript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.ts': 'typescript',
+  '.tsx': 'typescript',
+  '.py': 'python',
+  '.html': 'html',
+}
+
+const withoutEmpty = facts =>
+  Object.fromEntries(
+    Object.entries(facts).filter(([, value]) => !(Array.isArray(value) && !value.length)),
+  )
+
+const extractFacts = (path, code) => {
+  const ext = Path.extname(path).toLowerCase()
+  const language = LANGUAGES[ext]
+  const parsers = { python: extractPy, html: extractHtml }
+  const facts = parsers[language] ? parsers[language](code) : extractJs(code, ext)
+  return withoutEmpty({ language, lines: code.split('\n').length, ...facts })
+}
+
+module.exports = {
+  PARSER_VERSION,
+  extractFacts,
+}

package/src/analysis/file-filter.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const Path = require('path')
+
+const MAX_BYTES = 512 * 1024
+
+const CODE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.py', '.html'])
+
+const SECRET_PATTERNS = [
+  /(^|\/)\.env(\.[^/]*)?$/i,
+  /\.(pem|key|p12|pfx|jks|keystore|p8|mobileprovision|cer|crt|der|asc|gpg)$/i,
+  /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i,
+  /(^|\/)\.(npmrc|pypirc|netrc)$/i,
+  /(^|\/)google-services\.json$/i,
+  /(^|\/)GoogleService-Info\.plist$/i,
+  /(^|\/)service-account[^/]*\.json$/i,
+  /(^|\/)\.(aws|ssh)\//i,
+]
+
+const SECRET_NAME = /(^|[._-])(secrets?|credentials?)([._-]|$)/i
+
+const GENERATED_PATTERNS = [
+  /(^|\/)(node_modules|bower_components|dist|build|coverage|vendor|\.next|\.expo|\.nuxt|Pods|\.gradle)\//,
+  /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|npm-shrinkwrap\.json|Podfile\.lock)$/,
+  /\.(min\.js|min\.css|map|snap|lock)$/i,
+]
+
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.bmp', '.tif', '.tiff', '.heic',
+  '.mp4', '.mov', '.avi', '.mp3', '.wav', '.ogg', '.m4a',
+  '.pdf', '.zip', '.gz', '.tgz', '.rar', '.7z', '.jar', '.war', '.tar',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.psd', '.ai', '.sketch', '.fig', '.xls', '.xlsx', '.doc', '.docx', '.ppt', '.pptx',
+  '.exe', '.dll', '.so', '.dylib', '.bin', '.dat', '.db', '.sqlite', '.apk', '.ipa', '.aab',
+])
+
+const SECRET_VALUE_NAME = /(key|secret|token|passw|pwd|auth|credential|private|salt|signature|cert|bearer|session|cookie|dsn)/i
+const SECRET_VALUE = /-----BEGIN|^(sk|pk|rk|ghp|gho|xox[abp])[-_]|^AKIA|^eyJ|:\/\/[^\s/]*:[^\s/]*@|(password|pwd|secret|token)=/i
+
+const isSecretValue = (name, value) => {
+  const text = String(value)
+  if ((name && SECRET_VALUE_NAME.test(name)) || SECRET_VALUE.test(text)) return true
+  return !/\s/.test(text) && text.length >= 20 && /[a-z]/i.test(text) && /\d/.test(text)
+}
+
+const classify = (path, size) => {
+  if (
+    SECRET_PATTERNS.some(pattern => pattern.test(path)) ||
+    SECRET_NAME.test(Path.basename(path))
+  ) {
+    return 'skipped-secret'
+  }
+  if (GENERATED_PATTERNS.some(pattern => pattern.test(path))) {
+    return 'skipped-generated'
+  }
+  const ext = Path.extname(path).toLowerCase()
+  if (BINARY_EXTENSIONS.has(ext)) {
+    return 'skipped-binary'
+  }
+  if (size > MAX_BYTES) {
+    return 'skipped-large'
+  }
+  return CODE_EXTENSIONS.has(ext) ? 'parsed' : 'listed'
+}
+
+module.exports = {
+  classify,
+  isSecretValue,
+}

package/src/analysis/git-reader.js

@@ -0,0 +1,108 @@
+'use strict'
+
+const { execFileSync, spawn } = require('child_process')
+
+const git = (dir, args, options = {}) =>
+  execFileSync('git', ['-C', dir, ...args], {
+    encoding: options.encoding || 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  })
+
+const verify = (dir, ref) => {
+  try {
+    return git(dir, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).trim()
+  } catch (err) {
+    return null
+  }
+}
+
+const resolveRef = (dir, branch) => {
+  const candidates = branch
+    ? [`refs/remotes/origin/${branch}`, `refs/heads/${branch}`]
+    : ['HEAD']
+  for (const ref of candidates) {
+    const commitSha = verify(dir, ref)
+    if (commitSha) {
+      const date = git(dir, ['log', '-1', '--format=%cs', commitSha]).trim()
+      return { ref, commitSha, date }
+    }
+  }
+  throw new Error(branch ? `branch "${branch}" not found` : 'no commits found')
+}
+
+const listFiles = (dir, ref) =>
+  git(dir, ['ls-tree', '-r', '-l', '-z', ref])
+    .split('\0')
+    .filter(Boolean)
+    .map(line => {
+      const tab = line.indexOf('\t')
+      const [, type, blobHash, size] = line.slice(0, tab).split(/\s+/)
+      return { type, blobHash, size: Number(size) || 0, path: line.slice(tab + 1) }
+    })
+    .filter(entry => entry.type === 'blob')
+    .map(({ blobHash, size, path }) => ({ blobHash, size, path }))
+
+const HISTORY_COMMITS = 4000
+const HISTORY_PER_FILE = 40
+const HISTORY_MAX_FILES = 30
+
+const fileHistory = (dir, ref, wanted) => {
+  const history = {}
+  const log = git(dir, ['-c', 'core.quotePath=false', 'log', ref, '--no-merges', '-n', String(HISTORY_COMMITS), '--name-only', '--format=%x00%s'])
+  log
+    .split('\0')
+    .filter(Boolean)
+    .forEach(block => {
+      const [message, ...paths] = block.split('\n').map(line => line.trim())
+      const files = paths.filter(path => path && wanted.has(path))
+      if (!message || /^(merge|squashed commit)/i.test(message) || paths.filter(Boolean).length > HISTORY_MAX_FILES) return
+      files.forEach(path => {
+        const messages = history[path] || (history[path] = [])
+        if (messages.length < HISTORY_PER_FILE && !messages.includes(message)) messages.push(message)
+      })
+    })
+  return history
+}
+
+const readBlobs = (dir, hashes) =>
+  new Promise((resolve, reject) => {
+    const child = spawn('git', ['-C', dir, 'cat-file', '--batch'], {
+      stdio: ['pipe', 'pipe', 'ignore'],
+    })
+    const chunks = []
+    child.stdout.on('data', chunk => chunks.push(chunk))
+    child.on('error', reject)
+    child.on('close', code => {
+      if (code !== 0) {
+        reject(new Error(`git cat-file failed in ${dir}`))
+        return
+      }
+      const buffer = Buffer.concat(chunks)
+      const blobs = new Map()
+      let offset = 0
+      while (offset < buffer.length) {
+        const newline = buffer.indexOf(0x0a, offset)
+        if (newline === -1) {
+          break
+        }
+        const [hash, type, size] = buffer.toString('utf8', offset, newline).split(' ')
+        offset = newline + 1
+        if (type === 'missing') {
+          continue
+        }
+        const length = Number(size)
+        blobs.set(hash, buffer.toString('utf8', offset, offset + length))
+        offset += length + 1
+      }
+      resolve(blobs)
+    })
+    child.stdin.end(`${hashes.join('\n')}\n`)
+  })
+
+module.exports = {
+  resolveRef,
+  listFiles,
+  fileHistory,
+  readBlobs,
+}

package/src/analysis/html-parser.js

@@ -0,0 +1,46 @@
+'use strict'
+
+const LIMIT = 500
+const LABEL_LIMIT = 150
+
+const CUSTOM_TAG = /<([a-z][a-z0-9]*(?:-[a-z0-9]+)+)[\s/>]/g
+const LABEL_ATTRIBUTE = /\s(?:title|placeholder|label|alt|aria-label|matTooltip|ngbTooltip)\s*=\s*"([^"{}]+)"/g
+const ROUTER_LINK = /\srouterLink\s*=\s*"(\/[^"{}]*)"/g
+
+const labelText = value => {
+  const label = value.replace(/&nbsp;/g, ' ').replace(/\s+/g, ' ').trim()
+  return label.length >= 2 && label.length <= 80 && /[a-z]/i.test(label) ? label : null
+}
+
+const extractHtml = code => {
+  const tags = new Set()
+  const labels = new Set()
+  const links = new Set()
+  const markup = code
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<(script|style)[\s\S]*?<\/\1>/gi, ' ')
+
+  for (const match of markup.matchAll(CUSTOM_TAG)) tags.add(match[1])
+  for (const match of markup.matchAll(ROUTER_LINK)) links.add(match[1])
+  for (const match of markup.matchAll(LABEL_ATTRIBUTE)) {
+    const label = labelText(match[1])
+    if (label) labels.add(label)
+  }
+  markup
+    .replace(/\{\{[\s\S]*?\}\}/g, ' ')
+    .split(/<[^>]*>/)
+    .forEach(chunk => {
+      const label = labelText(chunk)
+      if (label) labels.add(label)
+    })
+
+  return {
+    tags: [...tags].slice(0, LIMIT),
+    links: [...links].slice(0, LIMIT),
+    labels: [...labels].slice(0, LABEL_LIMIT),
+  }
+}
+
+module.exports = {
+  extractHtml,
+}