client-handover 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# handover-cli
+
+AI-powered handover document generator for frontend developers handing off websites to clients.
+
+Run one command. Get a professional handover document in Markdown, plain text, and HTML — written for both your client and the next developer.
+
+---
+
+## Install
+
+```bash
+npm install -g client-handover
+```
+
+Set your Anthropic API key:
+
+```bash
+export ANTHROPIC_API_KEY=your_key_here
+```
+
+Get a free API key at [console.anthropic.com](https://console.anthropic.com)
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/handover` | Full handover document (all sections) |
+| `/setup` | Project setup & dependencies |
+| `/deploy` | Deployment & hosting info |
+| `/credentials` | Logins & API keys template |
+| `/license` | Licensing & attribution |
+
+---
+
+## Usage
+
+### Quick start (placeholder content)
+```bash
+handover /handover
+```
+
+### With your project notes
+Create a plain text file with your project details:
+
+```
+project-info.txt
+----------------
+Project: Acme Corp website
+Stack: Vue 3, Vite, Netlify
+Repo: https://github.com/you/acme
+Live URL: https://acmecorp.com
+Hosting: Netlify (free tier)
+Domain: Namecheap, auto-renews Jan 2026
+CMS: Netlify CMS
+Analytics: Google Analytics 4
+APIs: Mailchimp (newsletter), Stripe (payments)
+```
+
+Then run:
+```bash
+handover /handover project-info.txt acme-handover
+```
+
+This generates:
+```
+output/
+├── acme-handover.md
+├── acme-handover.txt
+└── acme-handover.html
+```
+
+### Individual sections
+```bash
+handover /setup project-info.txt
+handover /deploy project-info.txt
+handover /credentials project-info.txt
+handover /license project-info.txt
+```
+
+---
+
+## Output formats
+
+All commands produce three files:
+
+- **`.md`** — Markdown, ready to paste into Notion, GitHub, or a README
+- **`.txt`** — Plain text, clean for email or printing
+- **`.html`** — Styled HTML, ready to send directly to a client
+
+---
+
+## Use as a library
+
+```js
+import { handover, setup, generateDoc } from 'client-handover'
+
+const prompt = handover('Vue 3 project hosted on Vercel...')
+await generateDoc(prompt, 'my-client', './docs')
+```
+
+---
+
+## Requirements
+
+- Node.js 18+
+- An [Anthropic API key](https://console.anthropic.com) (free tier available)
+
+---
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { setup } from './setup.js'
+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 chalk from 'chalk'
+import fs from 'fs'
+
+const COMMANDS = {
+  '/setup':       { fn: setup,       label: 'Project Setup & Dependencies' },
+  '/deploy':      { fn: deploy,      label: 'Deployment & Hosting' },
+  '/credentials': { fn: credentials, label: 'Credentials & Access' },
+  '/handover':    { fn: handover,    label: 'Full Handover Document' },
+  '/license':     { fn: license,     label: 'Licensing & Attribution' },
+}
+
+function printHelp() {
+  console.log(chalk.bold('\n🚀 handover-cli — Frontend Website Handover Document Generator\n'))
+  console.log(chalk.dim('Usage:'))
+  console.log('  handover <command> [project-info-file] [output-name]\n')
+  console.log(chalk.dim('Commands:'))
+  Object.entries(COMMANDS).forEach(([cmd, { label }]) => {
+    console.log(`  ${chalk.cyan(cmd.padEnd(16))} ${label}`)
+  })
+  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')
+  console.log('  handover /handover project-info.txt my-client  # Full doc, custom filename')
+  console.log()
+}
+
+async function main() {
+  const [,, command, infoFile, outputName] = process.argv
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp()
+    process.exit(0)
+  }
+
+  const entry = COMMANDS[command]
+  if (!entry) {
+    console.error(chalk.red(`\n❌ Unknown command: ${command}\n`))
+    printHelp()
+    process.exit(1)
+  }
+
+  // Read optional project info file
+  let projectInfo = ''
+  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}`))
+  }
+
+  const docName = outputName || command.replace('/', '')
+  const prompt = entry.fn(projectInfo)
+
+  console.log(chalk.bold(`\n📝 Generating: ${entry.label}`))
+  console.log(chalk.dim(`   Output: ./output/${docName}.{md,txt,html}\n`))
+
+  try {
+    await generateDoc(prompt, docName, './output')
+  } catch (err) {
+    if (err.status === 401) {
+      console.error(chalk.red('\n❌ Invalid API key. Set your ANTHROPIC_API_KEY environment variable.\n'))
+    } else {
+      console.error(chalk.red(`\n❌ Error: ${err.message}\n`))
+    }
+    process.exit(1)
+  }
+}
+
+main()

package/credentials.js

@@ -0,0 +1,50 @@
+export function credentials(projectInfo = '') {
+  return `
+You are a technical documentation writer creating a CREDENTIALS section for a frontend website handover document.
+
+⚠️ 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]'}
+
+Generate a CREDENTIALS & ACCESS section that includes:
+
+## Credentials & Access
+
+### For the Client (Plain English)
+- What accounts exist and what each one is for
+- Who currently has admin access
+- How to reset a password if they get locked out
+- Reminder to store credentials in a password manager (suggest 1Password, Bitwarden, etc.)
+- What NOT to share over email
+
+### For the Developer (Technical)
+Generate a credentials table template with these categories (use placeholders for all values):
+
+| Service | Purpose | URL | Username/Email | Notes |
+|---------|---------|-----|----------------|-------|
+
+Include rows for:
+- Hosting provider (e.g. Vercel, Netlify, cPanel)
+- Domain registrar
+- CMS or admin panel (if applicable)
+- Database access (if applicable)
+- Third-party APIs (list each one)
+- Email/SMTP service
+- Analytics (e.g. Google Analytics)
+- Version control (GitHub/GitLab repo URL)
+- Any other relevant service
+
+### API Keys & Environment Variables
+List all .env variables used with placeholder values and a description of each.
+
+### Access Transfer Checklist
+- [ ] Client has been added as admin to hosting
+- [ ] Client has been added to domain registrar
+- [ ] Developer has been removed or downgraded after handover
+- [ ] 2FA has been set up for client accounts
+- [ ] All credentials have been shared via secure method (not email)
+
+Format as clean Markdown with tables.
+`.trim()
+}

package/deploy.js

@@ -0,0 +1,34 @@
+export function deploy(projectInfo = '') {
+  return `
+You are a technical documentation writer creating a DEPLOYMENT section for a frontend website handover document.
+
+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]'}
+
+Generate a DEPLOYMENT section that includes:
+
+## Deployment & Hosting
+
+### For the Client (Plain English)
+- Where the website is hosted and what that means
+- How updates get published (automatic or manual?)
+- What happens if the site goes down — who to call, what to check
+- Estimated monthly/yearly hosting costs if known
+
+### For the Developer (Technical)
+- Hosting provider and account details (use placeholders for sensitive info)
+- Deployment method (e.g. Vercel push-to-deploy, FTP, CI/CD pipeline)
+- Step-by-step deploy process with exact commands
+- Domain/DNS setup and where it's managed
+- SSL certificate info
+- Build command and output directory
+- Any environment-specific configs (staging vs production)
+- Rollback procedure if a deployment fails
+
+Format as clean Markdown. Use code blocks for terminal commands.
+`.trim()
+}

package/generator.js

@@ -0,0 +1,127 @@
+import Anthropic from '@anthropic-ai/sdk'
+import { marked } from 'marked'
+import fs from 'fs'
+import path from 'path'
+
+const client = new Anthropic()
+
+/**
+ * Generate a handover document using the Claude API
+ * @param {string} prompt - The command prompt to send
+ * @param {string} outputName - Base filename (without extension)
+ * @param {string} outputDir - Directory to save files
+ */
+export async function generateDoc(prompt, outputName = 'handover', outputDir = './output') {
+  console.log('⏳ Generating document with Claude...\n')
+
+  // Call Claude API
+  const message = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 4096,
+    messages: [{ role: 'user', content: prompt }]
+  })
+
+  const markdown = message.content[0].text
+
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true })
+  }
+
+  const basePath = path.join(outputDir, outputName)
+
+  // --- 1. Save as Markdown ---
+  const mdPath = `${basePath}.md`
+  fs.writeFileSync(mdPath, markdown, 'utf-8')
+  console.log(`✅ Markdown saved:  ${mdPath}`)
+
+  // --- 2. Save as Plain Text ---
+  const plainText = markdown
+    .replace(/#{1,6}\s+/g, '')         // Remove headings
+    .replace(/\*\*(.*?)\*\*/g, '$1')   // Remove bold
+    .replace(/\*(.*?)\*/g, '$1')       // Remove italic
+    .replace(/`{1,3}[^`]*`{1,3}/g, (m) => m.replace(/`/g, '')) // Remove code ticks
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // Remove links, keep text
+    .replace(/[-*+] /g, '• ')          // Convert bullets
+    .replace(/\n{3,}/g, '\n\n')        // Clean extra blank lines
+    .trim()
+
+  const txtPath = `${basePath}.txt`
+  fs.writeFileSync(txtPath, plainText, 'utf-8')
+  console.log(`✅ Plain text saved: ${txtPath}`)
+
+  // --- 3. Save as HTML ---
+  const htmlBody = marked(markdown)
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Handover Document</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 860px;
+      margin: 0 auto;
+      padding: 2rem;
+      color: #1a1a1a;
+      line-height: 1.7;
+    }
+    h1 { border-bottom: 2px solid #e0e0e0; padding-bottom: 0.5rem; }
+    h2 { margin-top: 2.5rem; color: #2c2c2c; }
+    h3 { color: #444; }
+    code {
+      background: #f4f4f4;
+      padding: 0.2em 0.4em;
+      border-radius: 4px;
+      font-size: 0.9em;
+    }
+    pre {
+      background: #f4f4f4;
+      padding: 1rem;
+      border-radius: 6px;
+      overflow-x: auto;
+    }
+    pre code { background: none; padding: 0; }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 1rem 0;
+    }
+    th, td {
+      border: 1px solid #ddd;
+      padding: 0.6rem 0.8rem;
+      text-align: left;
+    }
+    th { background: #f0f0f0; font-weight: 600; }
+    blockquote {
+      border-left: 4px solid #ccc;
+      margin: 0;
+      padding-left: 1rem;
+      color: #555;
+    }
+    .badge {
+      display: inline-block;
+      background: #e8f4fd;
+      color: #0969da;
+      padding: 0.2em 0.6em;
+      border-radius: 4px;
+      font-size: 0.8em;
+      font-weight: 600;
+    }
+    input[type="checkbox"] { margin-right: 0.4rem; }
+  </style>
+</head>
+<body>
+${htmlBody}
+</body>
+</html>`
+
+  const htmlPath = `${basePath}.html`
+  fs.writeFileSync(htmlPath, html, 'utf-8')
+  console.log(`✅ HTML saved:       ${htmlPath}`)
+
+  console.log('\n🎉 All formats generated successfully!\n')
+
+  return { markdown, plainText, html }
+}

package/handover.js

@@ -0,0 +1,96 @@
+export function handover(projectInfo = '') {
+  return `
+You are an expert technical writer generating a COMPLETE CLIENT WEBSITE HANDOVER DOCUMENT.
+
+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]'}
+
+Generate a full handover document with ALL of the following sections:
+
+---
+
+# [Project Name] — Website Handover Document
+**Prepared by:** [Developer Name]
+**Handover Date:** [Date]
+**Project URL:** [Live URL]
+**Repository:** [Repo URL]
+
+---
+
+## 1. Project Overview
+- What the site does (1 paragraph, plain English)
+- Tech stack summary (with one-line plain English explanation of each)
+- Key contacts (developer, hosting support, etc.)
+
+## 2. Project Setup & Dependencies
+*(Follow the dual-audience format: client section + developer section)*
+- Prerequisites, install steps, local dev commands, environment variables
+
+## 3. Deployment & Hosting
+*(Dual-audience format)*
+- Hosting provider, deploy method, domain/DNS, SSL, build config, rollback steps
+
+## 4. Credentials & Access
+*(Dual-audience format)*
+- All accounts, credentials table with placeholders, .env variables, access transfer checklist
+
+## 5. Site Structure & Content Management
+### For the Client
+- How to update content (CMS, direct file edits, or contact developer)
+- What they should NEVER touch without developer help
+- How to add new pages or blog posts (if applicable)
+
+### For the Developer
+- Folder structure overview
+- Where key config files live
+- Component/template structure
+- Any custom hooks, stores, or utilities worth knowing about
+
+## 6. Maintenance & Updates
+### For the Client
+- What needs renewing and when (domain, hosting, licences)
+- How to know if something is broken
+- Recommended monthly/yearly maintenance tasks
+
+### For the Developer
+- How to update npm dependencies safely
+- Any known technical debt or TODO items
+- Performance and SEO considerations
+
+## 7. Licensing & Attribution
+*(Dual-audience format)*
+- Ownership summary, third-party licences table, attribution requirements, portfolio rights
+
+## 8. Handover Checklist
+A final sign-off checklist for both parties:
+
+### Developer Checklist (before handover)
+- [ ] All credentials transferred securely
+- [ ] Client added to hosting & domain accounts
+- [ ] Repository access transferred or shared
+- [ ] Live site tested across browsers and devices
+- [ ] Analytics verified working
+- [ ] All placeholder content replaced
+- [ ] .env.example file committed to repo
+- [ ] README updated
+- [ ] Handover document reviewed with client
+
+### Client Acknowledgement
+- [ ] I have received all login credentials
+- [ ] I understand how to update content
+- [ ] I know who to contact for technical support
+- [ ] I have been shown the live site and approve it
+
+---
+
+Format the entire document in clean, well-structured Markdown.
+Use code blocks for all terminal commands.
+Use tables where appropriate.
+Keep client sections warm, clear, and jargon-free.
+Keep developer sections precise and thorough.
+`.trim()
+}

package/index.js

@@ -0,0 +1,6 @@
+export { generateDoc } from './generator.js'
+export { handover } from './handover.js'
+export { setup } from './setup.js'
+export { deploy } from './deploy.js'
+export { credentials } from './credentials.js'
+export { license } from './license.js'

package/license.js

@@ -0,0 +1,50 @@
+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]'}
+
+Generate a LICENSING & ATTRIBUTION section that includes:
+
+## Licensing & Attribution
+
+### For the Client (Plain English)
+- What they legally own after handover (code, design, content)
+- What they do NOT own and must continue to pay for (fonts, stock images, plugins, themes)
+- Any content they must credit or attribute publicly
+- Whether the developer retains any rights to show the work in their portfolio
+- Plain-English summary of what they can and cannot do with the site
+
+### For the Developer (Technical)
+
+#### Project License
+- License type for the custom code written (e.g. MIT, proprietary, client-owned)
+- Copyright notice template
+
+#### Third-Party Licenses
+Generate a table of all third-party assets and their licenses:
+
+| Asset / Library | Type | License | Requires Attribution? | Renewal Required? |
+|----------------|------|---------|----------------------|-------------------|
+
+Include rows for:
+- npm packages (key ones, not all)
+- Fonts (Google Fonts, Adobe, licensed)
+- Stock images or icons
+- UI component libraries
+- Paid plugins or themes
+- Any SaaS tools baked into the site
+
+#### Attribution Requirements
+List any assets that require visible credit on the site (e.g. Unsplash photo credits, open source notices)
+
+#### Developer Portfolio Rights
+Confirm whether the developer has permission to:
+- [ ] Show the site in their portfolio
+- [ ] Use screenshots in case studies
+- [ ] Reference the client by name publicly
+
+Format as clean Markdown with tables.
+`.trim()
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "client-handover",
+  "version": "1.0.0",
+  "description": "AI-powered handover document generator for frontend developers handing off client websites",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "handover": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "index.js",
+    "generator.js",
+    "handover.js",
+    "setup.js",
+    "deploy.js",
+    "credentials.js",
+    "license.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "handover",
+    "frontend",
+    "client",
+    "documentation",
+    "developer",
+    "claude",
+    "ai"
+  ],
+  "author": "sabrkei",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "chalk": "^5.3.0",
+    "marked": "^12.0.0"
+  }
+}

package/setup.js

@@ -0,0 +1,31 @@
+export function setup(projectInfo = '') {
+  return `
+You are a technical documentation writer creating a SETUP section for a frontend website handover document.
+
+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]'}
+
+Generate a SETUP section that includes:
+
+## Project Setup & Dependencies
+
+### For the Client (Plain English)
+- What tech stack is used and a simple one-line explanation of each part
+- What they'll need to pay for or maintain (hosting, domain, licences)
+- Who to contact if something breaks
+
+### For the Developer (Technical)
+- Prerequisites (Node version, package manager, etc.)
+- Step-by-step install instructions with exact terminal commands
+- Environment variables needed (use placeholder values like YOUR_VALUE_HERE)
+- How to run locally (dev server command, expected URL)
+- Any known gotchas or first-time setup issues
+
+Format this as clean, well-structured Markdown with clear headings.
+Keep the client section jargon-free. Keep the developer section precise.
+`.trim()
+}