shipfolio 1.0.0

package/README.md

@@ -0,0 +1,330 @@
+# shipfolio
+
+[English](#english) | [中文](#中文)
+
+---
+
+<a id="english"></a>
+
+## 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.
+
+Built for developers who ship fast and need a way to showcase their work without spending hours on a portfolio.
+
+## Quick Start
+
+```bash
+npx shipfolio --scan ~/Projects
+```
+
+That's it. The tool walks you through everything interactively.
+
+## Prerequisites
+
+- Node.js >= 18
+- At least one AI engine installed locally:
+
+| Engine | Install | 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). |
+
+## Usage
+
+### 1. 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
+```
+
+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>`)
+
+### 2. Update an Existing Site
+
+```bash
+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.
+
+### 3. Generate Spec Only (for Use Inside AI Sessions)
+
+If you're already inside a 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.
+
+### 4. Deploy an Existing Site
+
+```bash
+npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
+npx shipfolio deploy --site ./shipfolio-site --platform vercel
+```
+
+### 5. Export PDF
+
+```bash
+npx shipfolio pdf --site ./shipfolio-site
+```
+
+Requires Playwright browsers: `npx playwright install chromium`
+
+### 6. Preview Locally
+
+```bash
+npx shipfolio preview --site ./shipfolio-site
+```
+
+## All Commands
+
+| Command | 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 |
+
+## All Flags
+
+| 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` |
+
+## Generated Site
+
+The output is a standard Next.js 15 project:
+
+- Next.js 15 (App Router) with static export
+- Tailwind CSS v4
+- shadcn/ui components
+- TypeScript
+- Responsive (desktop + tablet + mobile)
+- Print-optimized CSS for PDF export
+
+Build output is a static `out/` directory deployable anywhere.
+
+## Deployment
+
+### 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.
+
+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
+```
+
+## Links
+
+- GitHub: [github.com/Octo-o-o-o/shipfolio](https://github.com/Octo-o-o-o/shipfolio)
+- npm: `npx shipfolio`
+- Issues: [github.com/Octo-o-o-o/shipfolio/issues](https://github.com/Octo-o-o-o/shipfolio/issues)
+
+## License
+
+MIT
+
+---
+
+<a id="中文"></a>
+
+## shipfolio 是什么?
+
+一个 CLI 工具，将你本地的项目转化为个人作品集网站。它扫描你的 git 仓库，使用你本地的 AI 工具（Claude Code、Codex 或 v0）生成生产级网站，并一键部署到 Cloudflare Pages 或 Vercel。
+
+为快速交付项目但没时间做作品集的开发者而建。
+
+## 快速开始
+
+```bash
+npx shipfolio --scan ~/Projects
+```
+
+工具会以交互方式引导你完成所有步骤。
+
+## 前置条件
+
+- Node.js >= 18
+- 至少安装一个 AI 引擎:
+
+| 引擎 | 安装方式 | 说明 |
+|---|---|---|
+| Claude Code | `npm install -g @anthropic-ai/claude-code` | 推荐。综合生成质量最佳。 |
+| Codex | `npm install -g @openai/codex` | 备选。 |
+| v0 | 设置 `V0_API_KEY` 环境变量 | UI 设计质量最佳。需要 v0 付费订阅。在 [v0.dev](https://v0.dev) 获取 API key。 |
+
+## 使用方法
+
+### 1. 生成新网站
+
+```bash
+# 交互模式（首次使用推荐）
+npx shipfolio --scan ~/Projects
+
+# 预设参数
+npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal
+```
+
+工具流程:
+1. 扫描指定目录中的 git 仓库
+2. 让你选择要展示的项目
+3. 收集个人信息和设计偏好
+4. 调用本地 AI 生成网站
+5. 本地构建并预览
+6. 导出 PDF 版本
+7. 部署到选定平台
+
+输出目录: `./shipfolio-site/`（可通过 `--output <dir>` 修改）
+
+### 2. 更新已有网站
+
+```bash
+npx shipfolio update --site ./shipfolio-site --scan ~/Projects
+```
+
+检测新增/变更/移除的项目，增量更新。保留现有设计、布局和所有自定义修改。
+
+### 3. 仅生成 Spec（在 AI 会话中使用）
+
+如果你已经在 Claude Code 或 Codex 会话中:
+
+```bash
+npx shipfolio spec --scan ~/Projects --output ./
+```
+
+输出 `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
+
+```bash
+npx shipfolio pdf --site ./shipfolio-site
+```
+
+需要 Playwright 浏览器: `npx playwright install chromium`
+
+### 6. 本地预览
+
+```bash
+npx shipfolio preview --site ./shipfolio-site
+```
+
+## 所有命令
+
+| 命令 | 说明 |
+|---|---|
+| `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>` | 启动本地预览服务器 |
+
+## 所有参数
+
+| 参数 | 可选值 | 默认值 |
+|---|---|---|
+| `--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` |
+
+## 生成的网站
+
+输出是标准的 Next.js 15 项目:
+
+- Next.js 15 (App Router) 静态导出
+- Tailwind CSS v4
+- shadcn/ui 组件
+- TypeScript
+- 响应式设计（桌面端 + 平板 + 移动端）
+- 针对 PDF 导出优化的打印样式
+
+构建输出为纯静态的 `out/` 目录，可部署到任何静态托管平台。
+
+## 部署说明
+
+### Cloudflare Pages
+
+工具内部调用 `wrangler pages deploy`。首次运行会打开浏览器进行认证。网站获得 `<项目名>.pages.dev` 域名。
+
+免费额度: 无限站点，500 次构建/月，无限带宽。
+
+### Vercel
+
+工具内部调用 `vercel deploy --prod`。首次运行会打开浏览器进行认证。网站获得 `<项目名>.vercel.app` 域名。
+
+### GitHub 自动部署
+
+初始部署后，工具可选择性地创建 GitHub 仓库。将仓库连接到 Cloudflare Pages 或 Vercel 即可实现 push 自动部署。
+
+## 相关链接
+
+- GitHub: [github.com/Octo-o-o-o/shipfolio](https://github.com/Octo-o-o-o/shipfolio)
+- npm: `npx shipfolio`
+- 问题反馈: [github.com/Octo-o-o-o/shipfolio/issues](https://github.com/Octo-o-o-o/shipfolio/issues)
+
+## 许可证
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";