client-handover 1.0.5 → 1.1.0

package/prompts.js

@@ -0,0 +1,185 @@
+export function technicalHandoverPrompt(projectInfo, developerInfo) {
+  const { name, company, email, phone } = developerInfo
+  const date = new Date().toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' })
+
+  return `
+You are an expert technical writer generating a TECHNICAL HANDOVER DOCUMENT for a developer taking over a client website project.
+
+This document is written for a DEVELOPER (future maintainer) — be precise, thorough, and technically complete. They need to be able to pick this project up cold with no prior knowledge.
+
+Developer who built this project:
+- Name: ${name || '[Developer Name]'}
+${company ? `- Company: ${company}` : ''}
+- Email: ${email || '[Developer Email]'}
+${phone ? `- Phone: ${phone}` : ''}
+- Handover date: ${date}
+
+The following context has been automatically scanned from the project files (package.json, config files, folder structure, environment variable keys, deploy configs, README, CSS colors, etc.). Use this to generate a document specific to THIS project. Do not invent or use generic placeholders — if a specific detail is not in the scanned data, note it as "[to be confirmed]".
+
+${projectInfo || '[No project data available]'}
+
+Generate a complete technical handover document with ALL of the following sections:
+
+---
+
+# [Project Name] — Technical Handover Document
+
+**Prepared by:** ${name || '[Developer Name]'}${company ? ` · ${company}` : ''}${email ? ` · ${email}` : ''}${phone ? ` · ${phone}` : ''}
+**Handover Date:** ${date}
+**Project URL:** [Live URL — to be confirmed]
+**Repository:** [Repo URL — to be confirmed]
+
+---
+
+## 1. Tech Stack
+- List every technology, framework, library, and tool used
+- Include versions where known
+- Briefly explain the role of each in the project
+
+## 2. Project Structure
+- Full folder/file structure with explanations of what each directory contains
+- Location of key config files and what they control
+- Entry points and routing overview
+
+## 3. Local Development Setup
+- Prerequisites (Node version, package manager, etc.)
+- Step-by-step install and run instructions using exact terminal commands in code blocks
+- All environment variables required (keys only, no values) — what each one does
+
+## 4. Build & Deployment
+- Build command and output directory
+- Hosting provider and deployment method
+- CI/CD pipeline if applicable
+- Domain, DNS, and SSL details
+- How to roll back a broken deployment
+
+## 5. Third-Party Integrations & Services
+- Every external service, API, or plugin used
+- What each one does and where it is configured
+- Which accounts own these services
+
+## 6. Credentials & Access
+- Table of all accounts needed (service, URL, account owner, how to request access)
+- Environment variable names and their purpose
+- Access transfer checklist
+
+## 7. Known Issues & Technical Debt
+- Any bugs, limitations, or workarounds in the current codebase
+- TODO items or deferred improvements
+- Performance or SEO considerations
+
+## 8. Maintenance Guide
+- How to update npm dependencies safely
+- What to check after deploying changes
+- Renewal dates for domain, hosting, or licences if known
+
+## 9. Developer Handover Checklist
+- [ ] Repository access transferred or shared
+- [ ] All environment variables documented
+- [ ] Hosting and domain access transferred
+- [ ] Third-party service accounts handed over
+- [ ] Local dev environment tested and documented
+- [ ] Live site tested across browsers and devices
+- [ ] Analytics verified working
+- [ ] README updated
+
+---
+
+Format the entire document in clean, well-structured Markdown.
+Use code blocks for all terminal commands and code snippets.
+Use tables where appropriate (especially for credentials and dependencies).
+Be thorough and precise — this document is the sole reference for the incoming developer.
+`.trim()
+}
+
+export function nonTechnicalHandoverPrompt(projectInfo, developerInfo) {
+  const { name, company, email, phone } = developerInfo
+  const date = new Date().toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' })
+
+  return `
+You are an expert writer generating a NON-TECHNICAL HANDOVER DOCUMENT for a CLIENT receiving their completed website.
+
+This document is written for the BUSINESS OWNER or CLIENT — use plain English, a warm and reassuring tone, and absolutely no technical jargon. The client should feel confident and informed about what they own.
+
+Developer contact details:
+- Name: ${name || '[Developer Name]'}
+${company ? `- Company: ${company}` : ''}
+- Email: ${email || '[Developer Email]'}
+${phone ? `- Phone: ${phone}` : ''}
+- Handover date: ${date}
+
+The following context has been automatically scanned from the project files. Use this to generate a document specific to THIS project. Focus on what the client needs to know — not how it was built. If a specific detail is not available, note it as "[to be confirmed]".
+
+${projectInfo || '[No project data available]'}
+
+Generate a complete non-technical handover document with ALL of the following sections:
+
+---
+
+# [Project Name] — Your Website Handover Guide
+
+**Prepared by:** ${name || '[Developer Name]'}${company ? ` · ${company}` : ''}${email ? ` · ${email}` : ''}${phone ? ` · ${phone}` : ''}
+**Date:** ${date}
+
+---
+
+## 1. About Your Website
+- What your website does and who it is for (1–2 paragraphs, plain English)
+- The main pages or sections and what each one is for
+- Any special features the site has (contact forms, booking, e-commerce, blog, etc.)
+
+## 2. Your Website's Look & Feel
+- The overall design style and visual identity
+- Colours used on the site (mention specific colours by name and hex code if detected in the project)
+- Fonts used
+- Any branding guidelines to keep in mind when making future updates
+
+## 3. What You Own
+- A plain-English summary of everything handed over: the website, domain, hosting, code, and content
+- Who owns what and what that means for you
+
+## 4. Logging Into Your Website
+- How to access and log in to any admin area or CMS (plain steps, no jargon)
+- What you can safely update yourself
+- What you should NOT change without speaking to a developer first
+
+## 5. How to Update Your Content
+- Step-by-step instructions for common tasks (e.g. updating text, adding images, publishing a blog post)
+- Keep instructions simple and numbered
+- Include a note about backing up before making changes
+
+## 6. Your Accounts & Passwords
+- List of all accounts the client now owns (hosting, domain, CMS, email, analytics, etc.)
+- Reminder to store passwords securely and change them after handover
+- Note: actual passwords should be shared separately and securely — not in this document
+
+## 7. Keeping Your Website Healthy
+- What needs renewing and approximately when (domain name, hosting plan, SSL certificate, any paid plugins)
+- How to tell if something on the site is broken
+- Simple monthly and yearly maintenance checklist
+
+## 8. Getting Help
+- When and how to contact your developer: ${name || '[Developer Name]'}${company ? ` (${company})` : ''}${email ? `, ${email}` : ''}${phone ? `, ${phone}` : ''}
+- What kinds of changes require a developer
+- Recommended process for requesting future updates
+
+## 9. Handover Sign-Off
+### Developer confirms:
+- [ ] All accounts and login details have been transferred
+- [ ] The live site has been reviewed and approved
+- [ ] This document has been discussed with the client
+
+### Client acknowledges:
+- [ ] I have received all login credentials securely
+- [ ] I understand how to update my website content
+- [ ] I know what I should not change without developer help
+- [ ] I know how to contact my developer for support
+
+---
+
+Write the entire document in plain, friendly English. Use short sentences and simple words.
+Avoid ALL technical jargon — if a technical term must be used, explain it in brackets immediately after.
+Use numbered lists for any step-by-step instructions.
+The tone should be warm, professional, and reassuring — the client should feel proud of their new website.
+`.trim()
+}

package/scanner.js

@@ -0,0 +1,250 @@
+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
+    }
+  }
+
+  // --- CSS color detection ---
+  const cssColors = extractColors(dir)
+  if (cssColors.length) {
+    sections.push(`\n## Detected colours (from CSS/config files)`)
+    cssColors.forEach(c => sections.push(`  ${c}`))
+  }
+
+  // --- Folder structure ---
+  const structure = getFolderStructure(dir)
+  if (structure.length) {
+    sections.push(`\n## Project folder structure`)
+    sections.push(structure.join('\n'))
+  }
+
+  return sections.join('\n')
+}
+
+function extractColors(dir) {
+  const colors = new Set()
+  const hexPattern = /#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g
+  const cssVarColorPattern = /(--[\w-]*color[\w-]*|--[\w-]*bg[\w-]*|--[\w-]*primary[\w-]*|--[\w-]*secondary[\w-]*):\s*([^;}\n]+)/gi
+  const cssExtensions = ['.css', '.scss', '.sass', '.less']
+
+  function scanFile(filePath) {
+    const content = readFileSafe(filePath)
+    if (!content) return
+    let match
+    while ((match = hexPattern.exec(content)) !== null) {
+      colors.add(`#${match[1].toUpperCase()}`)
+    }
+    while ((match = cssVarColorPattern.exec(content)) !== null) {
+      colors.add(`${match[1].trim()}: ${match[2].trim()}`)
+    }
+  }
+
+  function walkDir(d, depth = 0) {
+    if (depth > 3) return
+    const ignore = new Set(['node_modules', '.git', '.next', '.nuxt', 'dist', 'build', '.cache'])
+    try {
+      const items = fs.readdirSync(d, { withFileTypes: true })
+      for (const item of items) {
+        if (ignore.has(item.name) || item.name.startsWith('.')) continue
+        const full = path.join(d, item.name)
+        if (item.isDirectory()) {
+          walkDir(full, depth + 1)
+        } else if (cssExtensions.includes(path.extname(item.name).toLowerCase())) {
+          scanFile(full)
+        }
+      }
+    } catch {}
+  }
+
+  walkDir(dir)
+
+  // Also check tailwind config for color definitions
+  for (const twConfig of ['tailwind.config.js', 'tailwind.config.ts']) {
+    const content = readFileSafe(path.join(dir, twConfig))
+    if (!content) continue
+    let match
+    while ((match = hexPattern.exec(content)) !== null) {
+      colors.add(`#${match[1].toUpperCase()}`)
+    }
+  }
+
+  return [...colors].slice(0, 40) // cap at 40 to avoid flooding context
+}

package/credentials.js

@@ -1,50 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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/handover.js

@@ -1,96 +0,0 @@
-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/setup.js

@@ -1,31 +0,0 @@
-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()
-}