tspl-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# 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.
+
+## Requirements
+
+- Node 22 or newer
+- git
+- Access to a TSPL API server (ask your team for its address)
+
+## Install
+
+```bash
+npm install -g tspl-cli
+tspl --help
+```
+
+## Get started
+
+```bash
+tspl setup --api https://your-tspl-api.example.com   # log in and check your machine
+cd path/to/your/project
+tspl init                                             # link this folder to a TSPL project
+tspl connect                                          # add tspl to your AI tool (MCP)
+tspl task new                                         # describe a task
+```
+
+`tspl setup` with no `--api` uses `http://localhost:1500`, for a TSPL API running on your own machine.
+
+## 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.
+
+## Update
+
+```bash
+npm install -g tspl-cli@latest
+```

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.0",
+  "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,
+}