shipfolio 1.0.9 → 1.1.0

package/README.md

@@ -8,7 +8,7 @@
 
 ## What is shipfolio?
 
-A CLI tool that turns your local projects into a personal portfolio website. It scans your git repositories, uses your local AI tools (Claude Code, Codex, or v0) to generate a production-ready site, and deploys it to Cloudflare Pages or Vercel -- all in one command.
+A CLI tool that turns your local projects into a personal portfolio website. It scans your git repositories, uses your local AI tools (Claude Code, Codex, or v0) to generate a production-ready Next.js site, and deploys it to Cloudflare Pages or Vercel -- all in one command.
 
 Built for developers who ship fast and need a way to showcase their work without spending hours on a portfolio.
 
@@ -18,156 +18,198 @@ Built for developers who ship fast and need a way to showcase their work without
 npx shipfolio --scan ~/Projects
 ```
 
-That's it. The tool walks you through everything interactively.
+The tool walks you through everything interactively: project selection, personal info, design preferences, and deployment.
 
 ## Prerequisites
 
 - Node.js >= 18
-- At least one AI engine installed locally:
+- At least one AI engine:
 
-| Engine | Install | Notes |
+| Engine | How to get it | Notes |
 |---|---|---|
 | Claude Code | `npm install -g @anthropic-ai/claude-code` | Recommended. Best overall generation quality. |
 | Codex | `npm install -g @openai/codex` | Alternative. |
-| v0 | Set `V0_API_KEY` env var | Best UI design quality. Requires paid v0 plan. Get your key at [v0.dev](https://v0.dev). |
+| v0 | Set `V0_API_KEY` environment variable | Best UI design quality. Requires paid v0 plan. Get your key at [v0.dev](https://v0.dev). |
 
-## Usage
+No need to install `wrangler` or `vercel` CLI -- shipfolio calls them via `npx` automatically.
 
-### 1. Generate a New Site
+## Commands
+
+### Generate a New Site
 
 ```bash
-# Interactive mode (recommended for first use)
 npx shipfolio --scan ~/Projects
-
-# Specify options upfront
-npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal
+npx shipfolio --scan ~/Projects --output ./my-site
+npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal --accent '#10b981'
+npx shipfolio --scan ~/Projects --auto --no-pdf
+npx shipfolio --scan ~/Projects --no-pdf --no-preview
 ```
 
-The tool will:
-1. Scan your directories for git repositories
-2. Ask you to select which projects to include
-3. Collect your personal info and design preferences
-4. Generate the site using your local AI
-5. Build and preview locally
-6. Export a PDF version
-7. Deploy to your chosen platform
-
-Output directory: `./shipfolio-site/` (override with `--output <dir>`)
+The pipeline:
+1. Scans directories for git repos (and non-git projects with package.json, Cargo.toml, etc.)
+2. Interactive interview: select projects, optionally merge related ones (e.g. web + mobile), enter personal info, pick theme/colors/font, and optionally enrich key projects with case-study details
+3. Generates the site using your local AI engine
+4. Builds, previews locally, exports PDF
+5. Deploys to Cloudflare Pages or Vercel
+6. Optionally creates a GitHub repo with a CI/CD workflow for auto-deploy on push
 
-### 2. Update an Existing Site
+### Update an Existing Site
 
 ```bash
+npx shipfolio update --site ./shipfolio-site
 npx shipfolio update --site ./shipfolio-site --scan ~/Projects
 ```
 
-Detects new/changed/removed projects and applies incremental updates. Preserves your existing design, layout, and any custom modifications.
+Detects new/changed/removed projects and applies incremental updates. Preserves existing design, layout, and custom modifications.
 
-### 3. Generate Spec Only (for Use Inside AI Sessions)
+### Generate Spec Only
 
-If you're already inside a Claude Code or Codex session:
+For use inside an existing Claude Code or Codex session:
 
 ```bash
 npx shipfolio spec --scan ~/Projects --output ./
 ```
 
-Outputs `shipfolio-spec.json` and `shipfolio-prompt.md`. Feed the prompt to your current AI session to generate the site directly.
+Outputs `shipfolio-spec.json` and `shipfolio-prompt.md`. Feed the prompt to your AI session to generate the site directly.
 
-### 4. Deploy an Existing Site
+### Deploy
 
 ```bash
 npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
 npx shipfolio deploy --site ./shipfolio-site --platform vercel
 ```
 
-### 5. Export PDF
+### Export PDF
 
 ```bash
 npx shipfolio pdf --site ./shipfolio-site
 ```
 
-Requires Playwright browsers: `npx playwright install chromium`
+Requires Playwright: `npx playwright install chromium`
 
-### 6. Preview Locally
+### Preview
 
 ```bash
-npx shipfolio preview --site ./shipfolio-site
+npx shipfolio preview --site ./shipfolio-site --port 3000
 ```
 
-## All Commands
+## CLI Reference
 
-| Command | Description |
+### `shipfolio init` (default)
+
+| Flag | Description | Default |
+|---|---|---|
+| `-s, --scan <dirs...>` | Directories to scan for projects | Current directory |
+| `-e, --engine <name>` | `claude`, `codex`, or `v0` | Auto-detect |
+| `-d, --deploy <platform>` | `cloudflare`, `vercel`, or `local` | Prompted |
+| `--style <theme>` | `dark-minimal`, `light-clean`, `monochrome`, or `custom` | Prompted |
+| `--accent <hex>` | Accent color like `#10b981` | Prompted |
+| `--auto` | Use safe defaults and skip prompts | `false` |
+| `-o, --output <dir>` | Output directory | `./shipfolio-site` |
+| `--no-pdf` | Skip PDF export | |
+| `--no-preview` | Skip local preview | |
+
+### `shipfolio update`
+
+| Flag | Description |
 |---|---|
-| `shipfolio` / `shipfolio init` | Generate a new portfolio site (interactive) |
-| `shipfolio update --site <path>` | Update an existing site with new projects |
-| `shipfolio spec --output <dir>` | Generate spec + prompt files only |
-| `shipfolio deploy --site <path>` | Deploy a built site |
-| `shipfolio pdf --site <path>` | Export site to PDF |
-| `shipfolio preview --site <path>` | Start local preview server |
+| `--site <path>` | Path to existing site directory (required) |
+| `-s, --scan <dirs...>` | Directories to scan |
+| `--no-pdf` | Skip PDF export |
+| `--no-preview` | Skip preview |
+| `--no-deploy` | Skip deployment |
 
-## All Flags
+### `shipfolio deploy`
 
-| Flag | Values | Default |
-|---|---|---|
-| `--scan <dir>` | Any directory path (repeatable) | Current directory |
-| `--engine <name>` | `claude` / `codex` / `v0` | Auto-detect |
-| `--deploy <platform>` | `cloudflare` / `vercel` / `local` | Prompted |
-| `--style <theme>` | `dark-minimal` / `light-clean` / `monochrome` | Prompted |
-| `--accent <hex>` | Hex color, e.g. `#7c3aed` | Prompted |
-| `--output <dir>` | Output directory path | `./shipfolio-site` |
-| `--auto` | Skip all prompts, use defaults | `false` |
-| `--no-pdf` | Skip PDF export | `false` |
-| `--no-preview` | Skip local preview | `false` |
+| Flag | Description |
+|---|---|
+| `--site <path>` | Path to site directory (required) |
+| `-p, --platform <name>` | `cloudflare` or `vercel` |
+
+### `shipfolio spec`
+
+| Flag | Description |
+|---|---|
+| `-s, --scan <dirs...>` | Directories to scan |
+| `-o, --output <dir>` | Output directory for spec files |
+
+### `shipfolio pdf`
+
+| Flag | Description |
+|---|---|
+| `--site <path>` | Path to site directory (required) |
+| `-o, --output <path>` | PDF output path |
+
+### `shipfolio preview`
+
+| Flag | Description |
+|---|---|
+| `--site <path>` | Path to site directory (required) |
+| `--port <port>` | Port number (default: 3000, auto-fallback if in use) |
+
+## Features
+
+### Project Merging
+
+When you have related projects (e.g. a web app and its mobile companion), shipfolio lets you merge them into a single portfolio entry. Tech stacks, commit histories, and READMEs are combined automatically, and update detection now tracks every merged project path instead of only the first one.
+
+### Featured Projects And Case Studies
+
+You can mark projects as featured and optionally add richer case-study inputs such as audience, problem, solution, impact, evidence, and screenshot URLs. These fields are passed directly into the generation prompt so the resulting site can emphasize your strongest work instead of flattening every project into the same card style.
 
-## Generated Site
+### Draft Recovery
 
-The output is a standard Next.js 15 project:
+If the process crashes or you cancel after the interview step, your answers are saved to `~/.shipfolio/draft.json`. Next time you run shipfolio, it offers to restore them.
 
-- Next.js 15 (App Router) with static export
+### i18n
+
+The CLI detects your system locale. Chinese (zh-CN, zh-TW) users see Chinese prompts; everyone else sees English.
+
+### Custom Domain
+
+During the deploy step, you can specify a custom domain. For Vercel, it is configured automatically via `vercel domains add`. For Cloudflare Pages, shipfolio prints a direct link to the dashboard with instructions.
+
+### GitHub Auto-Deploy
+
+After deployment, shipfolio can create a GitHub repo and add a `.github/workflows/deploy.yml` that redeploys on every push. You just need to add one or two secrets to the repo:
+
+**Cloudflare Pages:**
+```bash
+gh secret set CLOUDFLARE_API_TOKEN
+gh secret set CLOUDFLARE_ACCOUNT_ID
+```
+
+**Vercel:**
+```bash
+gh secret set VERCEL_TOKEN
+```
+
+## Generated Site Stack
+
+- Next.js 15 (App Router, static export `output: 'export'`)
 - Tailwind CSS v4
 - shadcn/ui components
 - TypeScript
 - Responsive (desktop + tablet + mobile)
 - Print-optimized CSS for PDF export
+- Build output: static `out/` directory
 
-Build output is a static `out/` directory deployable anywhere.
-
-## Deployment
+## Deployment Platforms
 
 ### Cloudflare Pages
 
-The tool runs `wrangler pages deploy` under the hood. On first run it opens a browser for authentication. Your site gets a `<project-name>.pages.dev` URL.
+No CLI pre-install needed. On first run, `npx wrangler login` opens a browser for authentication. The project is auto-created. Your site gets a `<project-name>.pages.dev` URL.
 
 Free tier: unlimited sites, 500 builds/month, unlimited bandwidth.
 
 ### Vercel
 
-The tool runs `vercel deploy --prod`. On first run it opens a browser for authentication. Your site gets a `<project-name>.vercel.app` URL.
-
-### GitHub Auto-Deploy
-
-After initial deployment, the tool optionally sets up a GitHub repo. Connect it to Cloudflare Pages or Vercel for push-to-deploy.
-
-## Project Structure
-
-```
-shipfolio/
-  src/
-    scanner/       -- Git repo detection, tech stack extraction
-    interviewer/   -- Interactive CLI prompts
-    spec/          -- Spec builder, diff computation
-    orchestrator/  -- AI engine dispatch (Claude/Codex/v0)
-    deployer/      -- Cloudflare Pages, Vercel, GitHub
-    pdf/           -- Playwright PDF export
-    commands/      -- CLI command handlers
-    utils/         -- Logger, exec, fs helpers
-  prompts/         -- AI prompt templates
-  bin/             -- CLI entry point
-```
+No CLI pre-install needed. On first run, `npx vercel login` opens a browser for authentication. Your site gets a `<project-name>.vercel.app` URL.
 
 ## Links
 
 - GitHub: [github.com/Octo-o-o-o/shipfolio](https://github.com/Octo-o-o-o/shipfolio)
-- npm: `npx shipfolio`
+- npm: [npmjs.com/package/shipfolio](https://www.npmjs.com/package/shipfolio)
 - Issues: [github.com/Octo-o-o-o/shipfolio/issues](https://github.com/Octo-o-o-o/shipfolio/issues)
 
 ## License
@@ -180,7 +222,7 @@ MIT
 
 ## shipfolio 是什么?
 
-一个 CLI 工具，将你本地的项目转化为个人作品集网站。它扫描你的 git 仓库，使用你本地的 AI 工具（Claude Code、Codex 或 v0）生成生产级网站，并一键部署到 Cloudflare Pages 或 Vercel。
+一个 CLI 工具，将你本地的项目转化为个人作品集网站。它扫描你的 git 仓库，使用你本地的 AI 工具（Claude Code、Codex 或 v0）生成生产级 Next.js 网站，并一键部署到 Cloudflare Pages 或 Vercel。
 
 为快速交付项目但没时间做作品集的开发者而建。
 
@@ -190,12 +232,12 @@ MIT
 npx shipfolio --scan ~/Projects
 ```
 
-工具会以交互方式引导你完成所有步骤。
+工具会以交互方式引导你完成所有步骤：项目选择、个人信息、设计偏好、部署。
 
 ## 前置条件
 
 - Node.js >= 18
-- 至少安装一个 AI 引擎:
+- 至少一个 AI 引擎:
 
 | 引擎 | 安装方式 | 说明 |
 |---|---|---|
@@ -203,126 +245,185 @@ npx shipfolio --scan ~/Projects
 | Codex | `npm install -g @openai/codex` | 备选。 |
 | v0 | 设置 `V0_API_KEY` 环境变量 | UI 设计质量最佳。需要 v0 付费订阅。在 [v0.dev](https://v0.dev) 获取 API key。 |
 
-## 使用方法
+不需要预装 `wrangler` 或 `vercel` CLI -- shipfolio 通过 `npx` 自动调用。
+
+## 命令
 
-### 1. 生成新网站
+### 生成新网站
 
 ```bash
-# 交互模式（首次使用推荐）
 npx shipfolio --scan ~/Projects
-
-# 预设参数
-npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal
+npx shipfolio --scan ~/Projects --output ./my-site
+npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal --accent '#10b981'
+npx shipfolio --scan ~/Projects --auto --no-pdf
+npx shipfolio --scan ~/Projects --no-pdf --no-preview
 ```
 
-工具流程:
-1. 扫描指定目录中的 git 仓库
-2. 让你选择要展示的项目
-3. 收集个人信息和设计偏好
-4. 调用本地 AI 生成网站
-5. 本地构建并预览
-6. 导出 PDF 版本
-7. 部署到选定平台
-
-输出目录: `./shipfolio-site/`（可通过 `--output <dir>` 修改）
+流程:
+1. 扫描目录中的 git 仓库（也支持没有 git 但有 package.json、Cargo.toml 等的项目）
+2. 交互式问答：选择项目、可选合并相关项目（如 web + mobile）、填写个人信息、选择主题/颜色/字体，并可为重点项目补充更完整的案例信息
+3. 调用本地 AI 引擎生成网站
+4. 构建、本地预览、导出 PDF
+5. 部署到 Cloudflare Pages 或 Vercel
+6. 可选创建 GitHub 仓库并配置 CI/CD workflow，实现 push 自动部署
 
-### 2. 更新已有网站
+### 更新已有网站
 
 ```bash
+npx shipfolio update --site ./shipfolio-site
 npx shipfolio update --site ./shipfolio-site --scan ~/Projects
 ```
 
-检测新增/变更/移除的项目，增量更新。保留现有设计、布局和所有自定义修改。
+检测新增/变更/移除的项目，增量更新。保留现有设计、布局和自定义修改。
 
-### 3. 仅生成 Spec（在 AI 会话中使用）
+### 仅生成 Spec
 
-如果你已经在 Claude Code 或 Codex 会话中:
+在 Claude Code 或 Codex 会话中使用:
 
 ```bash
 npx shipfolio spec --scan ~/Projects --output ./
 ```
 
-输出 `shipfolio-spec.json` 和 `shipfolio-prompt.md`。将 prompt 输入当前 AI 会话即可直接生成网站。
+输出 `shipfolio-spec.json` 和 `shipfolio-prompt.md`。将 prompt 输入 AI 会话即可直接生成网站。
 
-### 4. 部署已有网站
+### 部署
 
 ```bash
 npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
 npx shipfolio deploy --site ./shipfolio-site --platform vercel
 ```
 
-### 5. 导出 PDF
+### 导出 PDF
 
 ```bash
 npx shipfolio pdf --site ./shipfolio-site
 ```
 
-需要 Playwright 浏览器: `npx playwright install chromium`
+需要 Playwright: `npx playwright install chromium`
 
-### 6. 本地预览
+### 本地预览
 
 ```bash
-npx shipfolio preview --site ./shipfolio-site
+npx shipfolio preview --site ./shipfolio-site --port 3000
 ```
 
-## 所有命令
+## CLI 参考
+
+### `shipfolio init`（默认命令）
 
-| 命令 | 说明 |
+| 参数 | 说明 | 默认值 |
+|---|---|---|
+| `-s, --scan <dirs...>` | 扫描目录 | 当前目录 |
+| `-e, --engine <name>` | `claude`、`codex` 或 `v0` | 自动检测 |
+| `-d, --deploy <platform>` | `cloudflare`、`vercel` 或 `local` | 交互选择 |
+| `--style <theme>` | `dark-minimal`、`light-clean`、`monochrome` 或 `custom` | 交互选择 |
+| `--accent <hex>` | 强调色，如 `#10b981` | 交互选择 |
+| `--auto` | 使用安全默认值并跳过问答 | `false` |
+| `-o, --output <dir>` | 输出目录 | `./shipfolio-site` |
+| `--no-pdf` | 跳过 PDF 导出 | |
+| `--no-preview` | 跳过本地预览 | |
+
+### `shipfolio update`
+
+| 参数 | 说明 |
 |---|---|
-| `shipfolio` / `shipfolio init` | 生成新的作品集网站（交互式） |
-| `shipfolio update --site <path>` | 用新项目更新已有网站 |
-| `shipfolio spec --output <dir>` | 仅生成 spec + prompt 文件 |
-| `shipfolio deploy --site <path>` | 部署已构建的网站 |
-| `shipfolio pdf --site <path>` | 将网站导出为 PDF |
-| `shipfolio preview --site <path>` | 启动本地预览服务器 |
+| `--site <path>` | 已有网站目录（必填） |
+| `-s, --scan <dirs...>` | 扫描目录 |
+| `--no-pdf` | 跳过 PDF 导出 |
+| `--no-preview` | 跳过预览 |
+| `--no-deploy` | 跳过部署 |
 
-## 所有参数
+### `shipfolio deploy`
 
-| 参数 | 可选值 | 默认值 |
-|---|---|---|
-| `--scan <dir>` | 任意目录路径（可重复） | 当前目录 |
-| `--engine <name>` | `claude` / `codex` / `v0` | 自动检测 |
-| `--deploy <platform>` | `cloudflare` / `vercel` / `local` | 交互选择 |
-| `--style <theme>` | `dark-minimal` / `light-clean` / `monochrome` | 交互选择 |
-| `--accent <hex>` | Hex 颜色值，如 `#7c3aed` | 交互选择 |
-| `--output <dir>` | 输出目录路径 | `./shipfolio-site` |
-| `--auto` | 跳过所有提示，使用默认值 | `false` |
-| `--no-pdf` | 跳过 PDF 导出 | `false` |
-| `--no-preview` | 跳过本地预览 | `false` |
+| 参数 | 说明 |
+|---|---|
+| `--site <path>` | 网站目录（必填） |
+| `-p, --platform <name>` | `cloudflare` 或 `vercel` |
+
+### `shipfolio spec`
+
+| 参数 | 说明 |
+|---|---|
+| `-s, --scan <dirs...>` | 扫描目录 |
+| `-o, --output <dir>` | Spec 文件输出目录 |
+
+### `shipfolio pdf`
+
+| 参数 | 说明 |
+|---|---|
+| `--site <path>` | 网站目录（必填） |
+| `-o, --output <path>` | PDF 输出路径 |
+
+### `shipfolio preview`
+
+| 参数 | 说明 |
+|---|---|
+| `--site <path>` | 网站目录（必填） |
+| `--port <port>` | 端口号（默认 3000，占用时自动切换） |
+
+## 功能特性
+
+### 项目合并
+
+当你有关联项目时（如 web 端和 mobile 端），shipfolio 支持将它们合并为一个作品集条目。技术栈、提交历史和 README 会自动合并；更新检测也会追踪所有被合并项目的路径，不再只看第一个目录。
 
-## 生成的网站
+### 重点项目与案例信息
 
-输出是标准的 Next.js 15 项目:
+你可以把项目标记为重点项目，并可选补充 audience、problem、solution、impact、evidence、screenshot URL 等案例信息。这些结构化字段会直接进入生成 prompt，让最终网站更容易突出真正重要的作品，而不是把所有项目都做成同一种平铺卡片。
 
-- Next.js 15 (App Router) 静态导出
+### 草稿恢复
+
+如果流程中断或在问答环节后崩溃，你的回答会保存到 `~/.shipfolio/draft.json`。下次运行时会询问是否恢复。
+
+### 多语言
+
+CLI 自动检测系统语言。简体中文和繁体中文用户看到中文提示，其他语言看到英文。
+
+### 自定义域名
+
+部署时可指定自定义域名。Vercel 通过 `vercel domains add` 自动配置。Cloudflare Pages 会打印 dashboard 直链和操作指引。
+
+### GitHub 自动部署
+
+部署后，shipfolio 可创建 GitHub 仓库并添加 `.github/workflows/deploy.yml`，每次 push 自动重新部署。只需在仓库中添加 secrets:
+
+**Cloudflare Pages:**
+```bash
+gh secret set CLOUDFLARE_API_TOKEN
+gh secret set CLOUDFLARE_ACCOUNT_ID
+```
+
+**Vercel:**
+```bash
+gh secret set VERCEL_TOKEN
+```
+
+## 生成的网站技术栈
+
+- Next.js 15 (App Router, 静态导出 `output: 'export'`)
 - Tailwind CSS v4
 - shadcn/ui 组件
 - TypeScript
-- 响应式设计（桌面端 + 平板 + 移动端）
-- 针对 PDF 导出优化的打印样式
-
-构建输出为纯静态的 `out/` 目录，可部署到任何静态托管平台。
+- 响应式（桌面 + 平板 + 移动端）
+- PDF 导出优化的打印样式
+- 构建产物：纯静态 `out/` 目录
 
-## 部署说明
+## 部署平台
 
 ### Cloudflare Pages
 
-工具内部调用 `wrangler pages deploy`。首次运行会打开浏览器进行认证。网站获得 `<项目名>.pages.dev` 域名。
+不需要预装 CLI。首次运行时 `npx wrangler login` 会打开浏览器进行认证。项目自动创建。网站获得 `<项目名>.pages.dev` 域名。
 
 免费额度: 无限站点，500 次构建/月，无限带宽。
 
 ### Vercel
 
-工具内部调用 `vercel deploy --prod`。首次运行会打开浏览器进行认证。网站获得 `<项目名>.vercel.app` 域名。
-
-### GitHub 自动部署
-
-初始部署后，工具可选择性地创建 GitHub 仓库。将仓库连接到 Cloudflare Pages 或 Vercel 即可实现 push 自动部署。
+不需要预装 CLI。首次运行时 `npx vercel login` 会打开浏览器进行认证。网站获得 `<项目名>.vercel.app` 域名。
 
 ## 相关链接
 
 - GitHub: [github.com/Octo-o-o-o/shipfolio](https://github.com/Octo-o-o-o/shipfolio)
-- npm: `npx shipfolio`
+- npm: [npmjs.com/package/shipfolio](https://www.npmjs.com/package/shipfolio)
 - 问题反馈: [github.com/Octo-o-o-o/shipfolio/issues](https://github.com/Octo-o-o-o/shipfolio/issues)
 
 ## 许可证