client-handover 1.0.4 → 1.0.6

package/README.md

@@ -163,7 +163,9 @@ All prompt builders accept an optional `projectInfo` string. If omitted, Claude
 ## Requirements
 
 - Node.js 18+
-- An Anthropic API key — [get one free at console.anthropic.com](https://console.anthropic.com)
+- One of the following:
+  - [Claude Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) installed (zero config — credentials detected automatically)
+  - Or an Anthropic API key — [get one free at console.anthropic.com](https://console.anthropic.com)
 
 ---
 
@@ -196,6 +198,32 @@ client-handover/
 
 ---
 
+## Changelog
+
+### 1.0.6
+- Auto-scans your actual project files on every run — reads package.json, config files, env variable keys, deploy configs, folder structure, and more
+- Generated documents are now tailored to your real project, not generic templates
+- Extra notes file still supported as optional additional context
+
+### 1.0.5
+- Interactive API key setup prompt on install — no manual config needed
+- Added `handover key <api-key>` command to save key at any time
+- Key is stored in `~/.handover/config.json` and persists across all sessions
+
+### 1.0.4
+- Auto-detects Claude Code credentials — no API key setup needed if you have Claude Code installed
+
+### 1.0.3
+- Commands now work with or without a leading `/` — fixes Git Bash path conversion issues on Windows
+
+### 1.0.2
+- Added `all` command — generates every section as separate files in a single named folder
+
+### 1.0.1
+- Initial release
+
+---
+
 ## Contributing
 
 Pull requests are welcome. For major changes, open an issue first.

package/cli.js

@@ -5,7 +5,8 @@ import { deploy } from './deploy.js'
 import { credentials } from './credentials.js'
 import { handover } from './handover.js'
 import { license } from './license.js'
-import { generateDoc } from './generator.js'
+import { generateDoc, saveApiKey } from './generator.js'
+import { scanProject } from './scanner.js'
 import chalk from 'chalk'
 import fs from 'fs'
 import path from 'path'
@@ -33,6 +34,7 @@ function printHelp() {
     console.log(`  ${chalk.cyan(cmd.padEnd(16))} ${label}`)
   })
   console.log(`  ${chalk.cyan('all'.padEnd(16))} All sections in a single folder`)
+  console.log(`  ${chalk.cyan('key <api-key>'.padEnd(16))} Save your Anthropic API key (one-time setup)`)
   console.log('\n' + chalk.dim('Examples:'))
   console.log('  handover handover                               # Full doc with placeholders')
   console.log('  handover setup project-info.txt                # Setup section using your notes')
@@ -41,7 +43,7 @@ function printHelp() {
   console.log()
 }
 
-async function runAll(projectInfo, folderName) {
+async function runAll(projectInfo, folderName, outputName) {
   const sections = [
     { key: 'handover',     fn: handover,     label: 'Full Handover Document' },
     { key: 'setup',        fn: setup,        label: 'Project Setup & Dependencies' },
@@ -74,17 +76,34 @@ async function main() {
 
   const command = normalizeCommand(rawCommand)
 
-  // Read optional project info file
-  let projectInfo = ''
+  if (command === 'key') {
+    const key = infoFile // second arg is the key
+    if (!key) {
+      console.error(chalk.red('\n❌ Usage: handover key <your-api-key>\n'))
+      process.exit(1)
+    }
+    saveApiKey(key)
+    console.log(chalk.green('\n✅ API key saved. You\'re all set — run any handover command.\n'))
+    process.exit(0)
+  }
+
+  // Scan the current project directory
+  console.log(chalk.dim('\n🔍 Scanning project...'))
+  const scannedContext = scanProject(process.cwd())
+
+  // Read optional extra project info file
+  let extraInfo = ''
   if (infoFile) {
     if (!fs.existsSync(infoFile)) {
       console.error(chalk.red(`\n❌ File not found: ${infoFile}\n`))
       process.exit(1)
     }
-    projectInfo = fs.readFileSync(infoFile, 'utf-8')
-    console.log(chalk.green(`\n📄 Loaded project info from: ${infoFile}`))
+    extraInfo = fs.readFileSync(infoFile, 'utf-8')
+    console.log(chalk.green(`📄 Loaded extra info from: ${infoFile}`))
   }
 
+  const projectInfo = [scannedContext, extraInfo].filter(Boolean).join('\n\n---\n\n')
+
   if (command === 'all') {
     const folderName = outputName || 'all'
     try {

package/credentials.js

@@ -4,8 +4,9 @@ You are a technical documentation writer creating a CREDENTIALS section for a fr
 
 ⚠️ IMPORTANT: Never include real passwords, keys, or secrets. All sensitive values must use placeholder format: YOUR_VALUE_HERE or [REPLACE_WITH_ACTUAL_VALUE]
 
-Using the following project information:
-${projectInfo || '[No project info provided — use placeholder examples]'}
+The following context has been automatically scanned from the developer's actual project files. Use the real environment variable keys and detected services to build the credentials table for THIS specific project. Do not invent services that are not present. Mark values as "[to be filled in]".
+
+${projectInfo || '[No project data available — use placeholder examples]'}
 
 Generate a CREDENTIALS & ACCESS section that includes:
 

package/deploy.js

@@ -6,8 +6,9 @@ The audience is TWO types of readers:
 1. A NON-TECHNICAL CLIENT — plain English, no jargon
 2. A DEVELOPER — exact technical steps
 
-Using the following project information:
-${projectInfo || '[No project info provided — use placeholder examples]'}
+The following context has been automatically scanned from the developer's actual project files (deploy configs, package.json scripts, workflow files, etc.). Use it to generate deployment documentation specific to THIS project — do not use generic placeholders. Mark any missing details as "[to be filled in]".
+
+${projectInfo || '[No project data available — use placeholder examples]'}
 
 Generate a DEPLOYMENT section that includes:
 

package/generator.js

@@ -7,6 +7,17 @@ import os from 'os'
 function resolveApiKey() {
   if (process.env.ANTHROPIC_API_KEY) return process.env.ANTHROPIC_API_KEY
 
+  // Check saved key from `handover key <your-key>`
+  const configPath = path.join(os.homedir(), '.handover', 'config.json')
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+      if (config?.apiKey) return config.apiKey
+    } catch {
+      // ignore malformed config file
+    }
+  }
+
   const credentialsPath = path.join(os.homedir(), '.claude', '.credentials.json')
   if (fs.existsSync(credentialsPath)) {
     try {
@@ -24,6 +35,13 @@ function resolveApiKey() {
   return null
 }
 
+export function saveApiKey(key) {
+  const configDir = path.join(os.homedir(), '.handover')
+  const configPath = path.join(configDir, 'config.json')
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, JSON.stringify({ apiKey: key }, null, 2), 'utf-8')
+}
+
 const apiKey = resolveApiKey()
 if (!apiKey) {
   console.error('\n❌ No API key found. Set ANTHROPIC_API_KEY or install Claude Code (code.visualstudio.com/download).\n')

package/handover.js

@@ -6,8 +6,9 @@ This document is for TWO audiences:
 1. NON-TECHNICAL CLIENT — plain English, reassuring tone, no jargon. They need to feel confident owning this site.
 2. DEVELOPER (future maintainer) — precise, technical, complete. They need to be able to pick this up cold.
 
-Using the following project information from the developer:
-${projectInfo || '[No project info provided — use placeholder examples throughout]'}
+The following context has been automatically scanned from the developer's actual project files (package.json, config files, folder structure, environment variable keys, deploy configs, README, etc.). Use this to generate a document specific to THIS project — do not invent or use generic placeholder examples. If a specific detail is not available in the scanned data, note it as "[to be filled in]" rather than guessing.
+
+${projectInfo || '[No project data available — use placeholder examples throughout]'}
 
 Generate a full handover document with ALL of the following sections:
 

package/license.js

@@ -2,8 +2,9 @@ export function license(projectInfo = '') {
   return `
 You are a technical documentation writer creating a LICENSING & ATTRIBUTION section for a frontend website handover document.
 
-Using the following project information:
-${projectInfo || '[No project info provided — use placeholder examples]'}
+The following context has been automatically scanned from the developer's actual project files. Use the real dependencies, license file, and detected libraries to generate licensing documentation specific to THIS project — do not use generic placeholder libraries.
+
+${projectInfo || '[No project data available — use placeholder examples]'}
 
 Generate a LICENSING & ATTRIBUTION section that includes:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-handover",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "AI-powered handover document generator for frontend developers handing off client websites",
   "type": "module",
   "main": "index.js",
@@ -16,10 +16,13 @@
     "deploy.js",
     "credentials.js",
     "license.js",
+    "postinstall.js",
+    "scanner.js",
     "README.md"
   ],
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js",
+    "postinstall": "node postinstall.js"
   },
   "keywords": [
     "handover",

package/postinstall.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import readline from 'readline'
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+const configDir = path.join(os.homedir(), '.handover')
+const configPath = path.join(configDir, 'config.json')
+const claudeCredsPath = path.join(os.homedir(), '.claude', '.credentials.json')
+
+function alreadyConfigured() {
+  if (process.env.ANTHROPIC_API_KEY) return true
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+      if (config?.apiKey) return true
+    } catch {}
+  }
+
+  if (fs.existsSync(claudeCredsPath)) {
+    try {
+      const creds = JSON.parse(fs.readFileSync(claudeCredsPath, 'utf-8'))
+      const token = creds?.claudeAiOauth?.accessToken
+      const expiresAt = creds?.claudeAiOauth?.expiresAt
+      if (token && (!expiresAt || expiresAt > Date.now())) return true
+    } catch {}
+  }
+
+  return false
+}
+
+function saveKey(key) {
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, JSON.stringify({ apiKey: key }, null, 2), 'utf-8')
+}
+
+// Skip if already set up or not in an interactive terminal
+if (alreadyConfigured() || !process.stdin.isTTY) {
+  process.exit(0)
+}
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+console.log('\n──────────────────────────────────────────')
+console.log(' client-handover setup')
+console.log('──────────────────────────────────────────')
+console.log(' To generate documents, you need an Anthropic API key.')
+console.log(' Get one free at: https://console.anthropic.com\n')
+
+rl.question(' Enter your Anthropic API key (or press Enter to skip): ', (answer) => {
+  rl.close()
+  const key = answer.trim()
+
+  if (!key) {
+    console.log('\n Skipped. Run "handover key <your-api-key>" at any time to set it.\n')
+    process.exit(0)
+  }
+
+  saveKey(key)
+  console.log('\n✅ API key saved. Run "handover handover" to get started.\n')
+  process.exit(0)
+})

package/scanner.js

@@ -0,0 +1,193 @@
+import fs from 'fs'
+import path from 'path'
+
+const CONFIG_FILES = [
+  'vite.config.js', 'vite.config.ts',
+  'next.config.js', 'next.config.ts', 'next.config.mjs',
+  'nuxt.config.js', 'nuxt.config.ts',
+  'astro.config.js', 'astro.config.ts', 'astro.config.mjs',
+  'svelte.config.js',
+  'remix.config.js',
+  'tailwind.config.js', 'tailwind.config.ts',
+  'postcss.config.js',
+  'netlify.toml',
+  'vercel.json',
+  'render.yaml',
+  'railway.json',
+  '.htaccess',
+  'Dockerfile',
+  'docker-compose.yml',
+  'firebase.json',
+]
+
+const DEPLOY_WORKFLOW_DIR = '.github/workflows'
+
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+function getEnvKeys(filePath) {
+  const content = readFileSafe(filePath)
+  if (!content) return []
+  return content
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#') && l.includes('='))
+    .map(l => l.split('=')[0].trim())
+}
+
+function getFolderStructure(dir, depth = 0, maxDepth = 2) {
+  if (depth > maxDepth) return []
+  const ignore = new Set(['node_modules', '.git', '.next', '.nuxt', 'dist', 'build', '.cache', 'coverage', '.turbo'])
+  let entries = []
+  try {
+    const items = fs.readdirSync(dir, { withFileTypes: true })
+    for (const item of items) {
+      if (ignore.has(item.name) || item.name.startsWith('.')) continue
+      const indent = '  '.repeat(depth)
+      if (item.isDirectory()) {
+        entries.push(`${indent}${item.name}/`)
+        entries.push(...getFolderStructure(path.join(dir, item.name), depth + 1, maxDepth))
+      } else {
+        entries.push(`${indent}${item.name}`)
+      }
+    }
+  } catch {}
+  return entries
+}
+
+function detectFramework(deps = {}, devDeps = {}) {
+  const all = { ...deps, ...devDeps }
+  if (all['next']) return 'Next.js'
+  if (all['nuxt'] || all['nuxt3']) return 'Nuxt'
+  if (all['@astrojs/core'] || all['astro']) return 'Astro'
+  if (all['@sveltejs/kit']) return 'SvelteKit'
+  if (all['svelte']) return 'Svelte'
+  if (all['@remix-run/react']) return 'Remix'
+  if (all['gatsby']) return 'Gatsby'
+  if (all['react']) return 'React'
+  if (all['vue']) return 'Vue'
+  if (all['angular']) return 'Angular'
+  return null
+}
+
+export function scanProject(dir = process.cwd()) {
+  const sections = []
+
+  // --- package.json ---
+  const pkgPath = path.join(dir, 'package.json')
+  let pkg = null
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(readFileSafe(pkgPath))
+      const framework = detectFramework(pkg.dependencies, pkg.devDependencies)
+      sections.push(`## package.json`)
+      sections.push(`Name: ${pkg.name || 'unknown'}`)
+      if (pkg.description) sections.push(`Description: ${pkg.description}`)
+      if (pkg.version) sections.push(`Version: ${pkg.version}`)
+      if (framework) sections.push(`Detected framework: ${framework}`)
+      if (pkg.engines?.node) sections.push(`Node requirement: ${pkg.engines.node}`)
+
+      if (pkg.scripts && Object.keys(pkg.scripts).length) {
+        sections.push(`\nScripts:`)
+        for (const [k, v] of Object.entries(pkg.scripts)) {
+          sections.push(`  ${k}: ${v}`)
+        }
+      }
+
+      const deps = Object.keys(pkg.dependencies || {})
+      const devDeps = Object.keys(pkg.devDependencies || {})
+      if (deps.length) sections.push(`\nDependencies: ${deps.join(', ')}`)
+      if (devDeps.length) sections.push(`Dev dependencies: ${devDeps.join(', ')}`)
+    } catch {}
+  }
+
+  // --- Package manager ---
+  let pm = 'npm'
+  if (fs.existsSync(path.join(dir, 'yarn.lock'))) pm = 'yarn'
+  else if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) pm = 'pnpm'
+  else if (fs.existsSync(path.join(dir, 'bun.lockb'))) pm = 'bun'
+  sections.push(`\nPackage manager: ${pm}`)
+
+  // --- Environment variables ---
+  const envExampleKeys = getEnvKeys(path.join(dir, '.env.example'))
+  const envLocalKeys = getEnvKeys(path.join(dir, '.env.local'))
+  const envKeys = getEnvKeys(path.join(dir, '.env'))
+  const allEnvKeys = [...new Set([...envExampleKeys, ...envLocalKeys, ...envKeys])]
+  if (allEnvKeys.length) {
+    sections.push(`\n## Environment Variables (keys only)`)
+    allEnvKeys.forEach(k => sections.push(`  ${k}`))
+  }
+
+  // --- Config files ---
+  for (const file of CONFIG_FILES) {
+    const filePath = path.join(dir, file)
+    if (fs.existsSync(filePath)) {
+      const content = readFileSafe(filePath)
+      if (content && content.length < 4000) {
+        sections.push(`\n## ${file}`)
+        sections.push('```')
+        sections.push(content.trim())
+        sections.push('```')
+      } else if (content) {
+        sections.push(`\n## ${file} (truncated)`)
+        sections.push('```')
+        sections.push(content.trim().slice(0, 4000) + '\n...')
+        sections.push('```')
+      }
+    }
+  }
+
+  // --- GitHub Actions workflows ---
+  const workflowDir = path.join(dir, DEPLOY_WORKFLOW_DIR)
+  if (fs.existsSync(workflowDir)) {
+    try {
+      const files = fs.readdirSync(workflowDir).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+      for (const file of files) {
+        const content = readFileSafe(path.join(workflowDir, file))
+        if (content) {
+          sections.push(`\n## .github/workflows/${file}`)
+          sections.push('```yaml')
+          sections.push(content.trim().slice(0, 3000))
+          sections.push('```')
+        }
+      }
+    } catch {}
+  }
+
+  // --- README ---
+  const readmePath = path.join(dir, 'README.md')
+  if (fs.existsSync(readmePath)) {
+    const content = readFileSafe(readmePath)
+    if (content) {
+      sections.push(`\n## README.md`)
+      sections.push(content.trim().slice(0, 3000))
+    }
+  }
+
+  // --- License ---
+  for (const f of ['LICENSE', 'LICENSE.md', 'LICENSE.txt']) {
+    const p = path.join(dir, f)
+    if (fs.existsSync(p)) {
+      const content = readFileSafe(p)
+      if (content) {
+        sections.push(`\n## ${f}`)
+        sections.push(content.trim().slice(0, 500))
+      }
+      break
+    }
+  }
+
+  // --- Folder structure ---
+  const structure = getFolderStructure(dir)
+  if (structure.length) {
+    sections.push(`\n## Project folder structure`)
+    sections.push(structure.join('\n'))
+  }
+
+  return sections.join('\n')
+}

package/setup.js

@@ -6,8 +6,9 @@ The audience is TWO types of readers:
 1. A NON-TECHNICAL CLIENT — who needs plain-English explanations of what everything is and why it matters
 2. A DEVELOPER — who needs exact commands, file paths, and technical detail
 
-Using the following project information provided by the developer:
-${projectInfo || '[No project info provided — use placeholder examples]'}
+The following context has been automatically scanned from the developer's actual project files. Use it to generate documentation specific to THIS project — do not use generic placeholders. If something is unclear from the scanned data, mark it as "[to be filled in]".
+
+${projectInfo || '[No project data available — use placeholder examples]'}
 
 Generate a SETUP section that includes: