@x-withu/page-withu 0.0.5 → 0.1.1

package/bin/page-withu.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createHash } from 'node:crypto';
 import { Command } from 'commander';
 import inquirer from 'inquirer';
 import fs from 'fs-extra';
@@ -12,131 +13,368 @@ const pkg = await fs.readJson(new URL('../package.json', import.meta.url));
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const templateDir = path.resolve(__dirname, '../template');
+const manifestName = '.page-withu.json';
+const managedRoots = ['src'];
+const managedFiles = ['.gitignore', 'index.html', 'vite.config.js'];
 
 const program = new Command();
 
-program
-  .name('page-withu')
-  .description('CLI to scaffold a lightweight, elegant personal homepage')
-  .version(pkg.version);
+function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
 
-program
-  .command('create [project-name]')
-  .description('create a new WithU project')
-  .option('-t, --title <title>', 'site title')
-  .option('--tab-title <title>', 'browser tab title')
-  .option('--favicon <path-or-url>', 'browser tab favicon path or URL')
-  .option('-a, --author <author>', 'author name')
-  .option('-g, --github <github>', 'github url')
-  .option('-e, --email <email>', 'email address')
-  .action(async (projectName, options) => {
-    let targetDir = projectName;
-
-    if (!targetDir) {
-      const answers = await inquirer.prompt([
-        {
-          type: 'input',
-          name: 'projectName',
-          message: 'What is your project named?',
-          default: 'my-homepage',
-        },
-      ]);
-      targetDir = answers.projectName;
+async function hashFile(filePath) {
+    return hashContent(await fs.readFile(filePath));
+}
+
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+
+async function listFiles(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await listFiles(entryPath));
+        } else if (entry.isFile()) {
+            files.push(entryPath);
+        }
+    }
+
+    return files;
+}
+
+async function listManagedTemplateFiles() {
+    const files = [...managedFiles];
+
+    for (const root of managedRoots) {
+        const rootPath = path.join(templateDir, root);
+        if (!await fs.pathExists(rootPath)) continue;
+        const rootFiles = await listFiles(rootPath);
+        files.push(...rootFiles.map((file) => toPosixPath(path.relative(templateDir, file))));
     }
 
-    const fullPath = path.resolve(process.cwd(), targetDir);
+    return files.sort((a, b) => a.localeCompare(b));
+}
 
-    if (fs.existsSync(fullPath)) {
-      console.error(chalk.red(`\nError: Directory ${targetDir} already exists.`));
-      process.exit(1);
+async function createManifest(projectDir, previousManifest = null) {
+    const files = {};
+
+    for (const file of await listManagedTemplateFiles()) {
+        const projectFile = path.join(projectDir, file);
+        const templateFile = path.join(templateDir, file);
+        if (!await fs.pathExists(projectFile)) continue;
+
+        const projectHash = await hashFile(projectFile);
+        const templateHash = await hashFile(templateFile);
+        if (projectHash === templateHash) {
+            files[file] = templateHash;
+        } else if (previousManifest?.files?.[file]) {
+            files[file] = previousManifest.files[file];
+        }
+    }
+
+    return {
+        templateVersion: pkg.version,
+        updatedAt: new Date().toISOString(),
+        files,
+    };
+}
+
+async function writeManifest(projectDir, dryRun, previousManifest = null) {
+    const manifest = await createManifest(projectDir, previousManifest);
+    if (!dryRun) {
+        await fs.writeJson(path.join(projectDir, manifestName), manifest, { spaces: 2 });
     }
+    return manifest;
+}
 
-    const title = options.title || (await inquirer.prompt([{
-      type: 'input',
-      name: 'title',
-      message: 'Site Title:',
-      default: 'WithU',
-    }])).title;
-
-    const author = options.author || (await inquirer.prompt([{
-      type: 'input',
-      name: 'author',
-      message: 'Author Name:',
-      default: 'Your Name',
-    }])).author;
-
-    const tabTitle = options.tabTitle || (await inquirer.prompt([{
-      type: 'input',
-      name: 'tabTitle',
-      message: 'Browser Tab Title:',
-      default: title,
-    }])).tabTitle;
-
-    const favicon = options.favicon || (await inquirer.prompt([{
-      type: 'input',
-      name: 'favicon',
-      message: 'Favicon path or URL:',
-      default: '/src/assets/bulb.svg',
-    }])).favicon;
-
-    const github = options.github !== undefined ? options.github : (await inquirer.prompt([{
-      type: 'input',
-      name: 'github',
-      message: 'GitHub URL (optional):',
-    }])).github;
-
-    const email = options.email !== undefined ? options.email : (await inquirer.prompt([{
-      type: 'input',
-      name: 'email',
-      message: 'Email (optional):',
-    }])).email;
-
-    const spinner = ora('Creating project...').start();
-
-    try {
-      // 1. Copy template
-      await fs.copy(templateDir, fullPath);
-
-      // 2. Generate config.js based on answers
-      const footerLinks = [];
-      if (github) footerLinks.push(`{ label: 'GitHub', url: '${github}' }`);
-      if (email) footerLinks.push(`{ label: 'Email', url: 'mailto:${email}' }`);
-
-      const configContent = `export default {
-    title: "${title}",
-    tabTitle: "${tabTitle}",
-    favicon: "${favicon}",
-    author: "${author}",
+function renderConfig({ title, tabTitle, favicon, author, footerLinks }) {
+    const links = footerLinks.map((link) => `        { label: ${JSON.stringify(link.label)}, url: ${JSON.stringify(link.url)} }`);
+    return `export default {
+    title: ${JSON.stringify(title)},
+    tabTitle: ${JSON.stringify(tabTitle)},
+    favicon: ${JSON.stringify(favicon)},
+    author: ${JSON.stringify(author)},
     year: new Date().getFullYear(),
     footerLinks: [
-        ${footerLinks.join(',\n        ')}
+${links.join(',\n')}
     ],
     pagination: {
         pageSize: 5
     }
 }`;
-      await fs.writeFile(path.join(fullPath, 'config.js'), configContent);
-
-      // 3. Rename package.json project name
-      const pkgPath = path.join(fullPath, 'package.json');
-      const pkg = await fs.readJson(pkgPath);
-      pkg.name = targetDir.toLowerCase().replace(/[^a-z0-9-]/g, '-');
-      await fs.writeJson(pkgPath, pkg, { spaces: 2 });
-
-      // 4. Create empty default directories
-      await fs.ensureDir(path.join(fullPath, 'content/blog'));
-
-      spinner.succeed(chalk.green(`Successfully created WithU project in ${targetDir}!`));
-      console.log('\nNext steps:');
-      console.log(chalk.cyan(`  cd ${targetDir}`));
-      console.log(chalk.cyan('  npm install'));
-      console.log(chalk.cyan('  npm run dev\n'));
-
-    } catch (err) {
-      spinner.fail(chalk.red('Failed to create project.'));
-      console.error(err);
-      process.exit(1);
+}
+
+async function detectProject(projectDir) {
+    const required = ['package.json', 'config.js', 'content', 'src', 'vite.config.js'];
+    const missing = [];
+
+    for (const item of required) {
+        if (!await fs.pathExists(path.join(projectDir, item))) missing.push(item);
+    }
+
+    return missing;
+}
+
+async function loadManifest(projectDir) {
+    const manifestPath = path.join(projectDir, manifestName);
+    if (!await fs.pathExists(manifestPath)) return null;
+    return fs.readJson(manifestPath);
+}
+
+async function shouldOverwriteConflict(file, options) {
+    if (options.force) return true;
+    if (options.yes || options.dryRun) return false;
+
+    const answer = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'overwrite',
+        message: `${file} has local changes. Overwrite it?`,
+        default: false,
+    }]);
+
+    return answer.overwrite;
+}
+
+async function planTemplateUpdates(projectDir, options) {
+    const manifest = await loadManifest(projectDir);
+    const files = await listManagedTemplateFiles();
+    const result = {
+        added: [],
+        updated: [],
+        skipped: [],
+        unchanged: [],
+    };
+
+    for (const file of files) {
+        const sourceFile = path.join(templateDir, file);
+        const targetFile = path.join(projectDir, file);
+        const sourceHash = await hashFile(sourceFile);
+        const exists = await fs.pathExists(targetFile);
+
+        if (!exists) {
+            result.added.push(file);
+            if (!options.dryRun) await fs.copy(sourceFile, targetFile);
+            continue;
+        }
+
+        const currentHash = await hashFile(targetFile);
+        if (currentHash === sourceHash) {
+            result.unchanged.push(file);
+            continue;
+        }
+
+        const previousHash = manifest?.files?.[file];
+        const safeToUpdate = previousHash && currentHash === previousHash;
+        const overwrite = safeToUpdate || await shouldOverwriteConflict(file, options);
+
+        if (overwrite) {
+            result.updated.push(file);
+            if (!options.dryRun) await fs.copy(sourceFile, targetFile);
+        } else {
+            result.skipped.push(file);
+        }
+    }
+
+    return result;
+}
+
+function mergeSection(projectPkg, templatePkg, key) {
+    const next = { ...(projectPkg[key] || {}) };
+    let changed = false;
+
+    for (const [name, value] of Object.entries(templatePkg[key] || {})) {
+        if (next[name] !== value) {
+            next[name] = value;
+            changed = true;
+        }
+    }
+
+    if (changed) projectPkg[key] = next;
+    return changed;
+}
+
+async function mergePackage(projectDir, dryRun) {
+    const projectPkgPath = path.join(projectDir, 'package.json');
+    const templatePkg = await fs.readJson(path.join(templateDir, 'package.json'));
+    const projectPkg = await fs.readJson(projectPkgPath);
+    const before = JSON.stringify(projectPkg);
+
+    mergeSection(projectPkg, templatePkg, 'scripts');
+    mergeSection(projectPkg, templatePkg, 'dependencies');
+    mergeSection(projectPkg, templatePkg, 'devDependencies');
+
+    const changed = JSON.stringify(projectPkg) !== before;
+    if (changed && !dryRun) {
+        await fs.writeJson(projectPkgPath, projectPkg, { spaces: 2 });
     }
-  });
 
-program.parse();
+    return changed;
+}
+
+function printUpdateSummary(summary, dryRun) {
+    const label = dryRun ? 'Would update' : 'Updated';
+
+    if (summary.added.length) console.log(chalk.green(`${label} ${summary.added.length} missing file(s).`));
+    if (summary.updated.length) console.log(chalk.green(`${label} ${summary.updated.length} template file(s).`));
+    if (summary.packageChanged) console.log(chalk.green(`${label} package.json dependencies and scripts.`));
+    if (summary.skipped.length) {
+        console.log(chalk.yellow(`Skipped ${summary.skipped.length} file(s) with local changes:`));
+        for (const file of summary.skipped) console.log(chalk.yellow(`  - ${file}`));
+    }
+    if (!summary.added.length && !summary.updated.length && !summary.packageChanged && !summary.skipped.length) {
+        console.log(chalk.green('Page With U project is already up to date.'));
+    }
+    if (!dryRun && (summary.added.length || summary.updated.length || summary.packageChanged)) {
+        console.log(chalk.cyan('\nNext steps:'));
+        console.log(chalk.cyan('  npm install'));
+        console.log(chalk.cyan('  npm run build'));
+    }
+}
+
+program
+    .name('page-withu')
+    .description('CLI to scaffold a lightweight, elegant personal homepage')
+    .version(pkg.version);
+
+program
+    .command('create [project-name]')
+    .description('create a new PageWithU project')
+    .option('-t, --title <title>', 'site title')
+    .option('--tab-title <title>', 'browser tab title')
+    .option('--favicon <path-or-url>', 'browser tab favicon path or URL')
+    .option('-a, --author <author>', 'author name')
+    .option('-g, --github <github>', 'github url')
+    .option('-e, --email <email>', 'email address')
+    .action(async (projectName, options) => {
+        let targetDir = projectName;
+
+        if (!targetDir) {
+            const answers = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'projectName',
+                    message: 'What is your project named?',
+                    default: 'my-homepage',
+                },
+            ]);
+            targetDir = answers.projectName;
+        }
+
+        const fullPath = path.resolve(process.cwd(), targetDir);
+
+        if (fs.existsSync(fullPath)) {
+            console.error(chalk.red(`\nError: Directory ${targetDir} already exists.`));
+            process.exit(1);
+        }
+
+        const title = options.title || (await inquirer.prompt([{
+            type: 'input',
+            name: 'title',
+            message: 'Site Title:',
+            default: 'PageWithU',
+        }])).title;
+
+        const author = options.author || (await inquirer.prompt([{
+            type: 'input',
+            name: 'author',
+            message: 'Author Name:',
+            default: 'Your Name',
+        }])).author;
+
+        const tabTitle = options.tabTitle || (await inquirer.prompt([{
+            type: 'input',
+            name: 'tabTitle',
+            message: 'Browser Tab Title:',
+            default: title,
+        }])).tabTitle;
+
+        const favicon = options.favicon || (await inquirer.prompt([{
+            type: 'input',
+            name: 'favicon',
+            message: 'Favicon path or URL:',
+            default: '/src/assets/bulb.svg',
+        }])).favicon;
+
+        const github = options.github !== undefined ? options.github : (await inquirer.prompt([{
+            type: 'input',
+            name: 'github',
+            message: 'GitHub URL (optional):',
+        }])).github;
+
+        const email = options.email !== undefined ? options.email : (await inquirer.prompt([{
+            type: 'input',
+            name: 'email',
+            message: 'Email (optional):',
+        }])).email;
+
+        const spinner = ora('Creating project...').start();
+
+        try {
+            await fs.copy(templateDir, fullPath);
+
+            const footerLinks = [];
+            if (github) footerLinks.push({ label: 'GitHub', url: github });
+            if (email) footerLinks.push({ label: 'Email', url: `mailto:${email}` });
+
+            await fs.writeFile(path.join(fullPath, 'config.js'), renderConfig({ title, tabTitle, favicon, author, footerLinks }));
+
+            const pkgPath = path.join(fullPath, 'package.json');
+            const projectPkg = await fs.readJson(pkgPath);
+            projectPkg.name = targetDir.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+            await fs.writeJson(pkgPath, projectPkg, { spaces: 2 });
+
+            await fs.ensureDir(path.join(fullPath, 'content/blog'));
+            await writeManifest(fullPath, false);
+
+            spinner.succeed(chalk.green(`Successfully created PageWithU project in ${targetDir}!`));
+            console.log('\nNext steps:');
+            console.log(chalk.cyan(`  cd ${targetDir}`));
+            console.log(chalk.cyan('  npm install'));
+            console.log(chalk.cyan('  npm run dev\n'));
+
+        } catch (err) {
+            spinner.fail(chalk.red('Failed to create project.'));
+            console.error(err);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('update')
+    .description('update an existing PageWithU project with the latest template')
+    .option('--dry-run', 'show what would change without writing files')
+    .option('--yes', 'skip prompts and apply safe updates')
+    .option('--force', 'overwrite changed template-managed files')
+    .action(async (options) => {
+        const projectDir = process.cwd();
+        const spinner = ora(options.dryRun ? 'Checking project update...' : 'Updating project...').start();
+
+        try {
+            const missing = await detectProject(projectDir);
+            if (missing.length) {
+                spinner.fail(chalk.red('Current directory does not look like a PageWithU project.'));
+                console.error(chalk.yellow(`Missing: ${missing.join(', ')}`));
+                process.exit(1);
+            }
+
+            spinner.stop();
+            const previousManifest = await loadManifest(projectDir);
+            const updates = await planTemplateUpdates(projectDir, options);
+            const packageChanged = await mergePackage(projectDir, options.dryRun);
+
+            if (!options.dryRun) await writeManifest(projectDir, false, previousManifest);
+
+            printUpdateSummary({ ...updates, packageChanged }, options.dryRun);
+        } catch (err) {
+            spinner.fail(chalk.red('Failed to update project.'));
+            console.error(err);
+            process.exit(1);
+        }
+    });
+
+program.parse();

package/docs/deploy.md

@@ -38,19 +38,60 @@ npm run preview
 
 ## 部署到 GitHub Pages
 
-本仓库已经内置 GitHub Pages 自动部署流程：
+GitHub Pages 适合把你生成好的个人主页托管到 GitHub 仓库中。
+
+### 方式一：使用 GitHub Actions 自动部署
+
+在你自己的主页项目中创建部署工作流：
 
 ```text
 .github/workflows/deploy-pages.yml
 ```
 
-它会在推送到 `main` 分支时自动执行：
-
-1. 进入 `template/`。
-2. 执行 `npm ci` 安装模板依赖。
-3. 使用 `BASE_PATH=/page-withu/ npm run build` 构建模板。
-4. 上传 `template/dist/`。
-5. 发布到 GitHub Pages。
+示例内容：
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
 
 首次使用前，需要在 GitHub 仓库中打开：
 
@@ -58,24 +99,23 @@ npm run preview
 Settings → Pages → Build and deployment → Source → GitHub Actions
 ```
 
-配置完成后，每次推送到 `main` 分支都会自动更新：
+配置完成后，每次推送到 `main` 分支都会自动构建并发布你的站点。
 
-```text
-https://explorer-dong.github.io/page-withu/
-```
+如果仓库名不是用于根域名的 `用户名.github.io`，通常需要给构建命令设置子路径。例如仓库名是 `my-homepage`：
 
-如果想手动触发部署，也可以在 GitHub Actions 页面选择 `Deploy Template to GitHub Pages`，然后点击 `Run workflow`。
+```yaml
+- run: BASE_PATH=/my-homepage/ npm run build
+```
 
-### 手动上传 dist
+### 方式二：手动上传 dist
 
 如果不想使用 GitHub Actions，也可以本地构建后手动上传 `dist/`。
 
 ```bash
-cd template
-BASE_PATH=/page-withu/ npm run build
+npm run build
 ```
 
-然后把 `template/dist/` 内容上传到用于 GitHub Pages 的发布分支或目录。
+然后把 `dist/` 内容上传到用于 GitHub Pages 的发布分支或目录。
 
 ## 部署到 Cloudflare Pages
 

package/docs/develop.md

@@ -57,6 +57,7 @@ bin/page-withu.js
 ```bash
 node bin/page-withu.js --help
 node bin/page-withu.js create my-homepage
+node bin/page-withu.js update --dry-run
 ```
 
 如果想全局挂载本地版本：

package/docs/setup.md

@@ -83,6 +83,37 @@ index_img: https://example.com/cover.jpg
 - `tags`：文章标签。
 - `index_img`：博客列表封面图，可选；不填会保留占位布局。
 
+## 更新项目
+
+如果你已经用 `page-withu create` 创建过项目，后续升级 CLI 后可以在项目目录中更新模板能力：
+
+```bash
+npm install -g @x-withu/page-withu
+cd my-homepage
+page-withu update --dry-run
+page-withu update
+```
+
+`page-withu update` 会更新模板管理的文件，例如 `src/`、`index.html` 和 `vite.config.js`，并合并 `package.json` 中模板需要的脚本和依赖。
+
+为了避免覆盖你的内容，以下文件默认不会被更新：
+
+- `config.js`
+- `content/`
+
+如果你修改过模板源码，更新时会跳过有冲突的文件并在终端列出来。确认要覆盖这些模板源码时，可以使用：
+
+```bash
+page-withu update --force
+```
+
+更新完成后建议执行：
+
+```bash
+npm install
+npm run build
+```
+
 ## Markdown
 
 文章中可以使用常见 Markdown 语法，也支持以下增强能力：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-withu/page-withu",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "description": "A lightweight, elegant personal homepage generator.",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
     "template/content/",
     "template/src/",
     "template/index.html",
+    "template/.gitignore",
     "template/package.json",
     "template/vite.config.js",
     "docs/",

package/template/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+
+.env
+.env.*
+!.env.example
+*.local
+
+.DS_Store
+.idea/

package/template/src/components/blog-list.vue

@@ -84,7 +84,7 @@ const activeMonth = ref('')
 const monthRefs = new Map()
 
 const orderedPosts = computed(() => {
-    return [...props.posts].sort((a, b) => new Date(a.date) - new Date(b.date))
+    return [...props.posts].sort((a, b) => new Date(b.date) - new Date(a.date))
 })
 
 const tags = computed(() => {