feat: add React 19 support, shared components, utilities, and CLI tooling

packages/core/CLI_README.md

@@ -0,0 +1,159 @@
+# nextjs-htk CLI
+
+The `@nextjs-htk/core` package includes a CLI tool to help standardize project setup and maintain consistency across all nextjs-htk projects.
+
+## Installation
+
+The CLI is automatically available when you install `@nextjs-htk/core`:
+
+```bash
+npm install @nextjs-htk/core
+```
+
+## Usage
+
+### Initialize a new project
+
+Copy all standard files (Makefile, scripts, etc.) to your project:
+
+```bash
+npx htk init
+```
+
+Or if you have the package installed locally:
+
+```bash
+npm exec htk init
+```
+
+### Sync existing project
+
+Update your project with the latest templates from nextjs-htk:
+
+```bash
+npx htk sync
+```
+
+### Sync specific files
+
+Sync only the Makefile:
+
+```bash
+npx htk sync:makefile
+```
+
+Sync only the scripts directory:
+
+```bash
+npx htk sync:scripts
+```
+
+### Force overwrite
+
+By default, the CLI will not overwrite existing files. Use `--force` or `-f` to overwrite:
+
+```bash
+npx htk init --force
+npx htk sync:makefile -f
+```
+
+### Help
+
+Show all available commands:
+
+```bash
+npx htk help
+```
+
+## What files are synced?
+
+### Makefile
+Standard Makefile with common targets:
+- `make help` - Show all available targets
+- `make install` - Install dependencies
+- `make dev` - Start development server
+- `make build` - Build for production
+- `make deploy` - Build and deploy to GitHub Pages
+- `make clean` - Clean build artifacts
+
+### Scripts
+- `src/scripts/generate_sitemap.ts` - Generate sitemap.xml during build
+
+## Using shared utilities
+
+The package also exports utilities you can use in your code:
+
+```typescript
+import { generateSitemap } from '@nextjs-htk/core/utils'
+import type { SitemapConfig } from '@nextjs-htk/core/utils'
+
+const config: SitemapConfig = {
+  siteUrl: 'https://example.com',
+  pages: [
+    { name: 'Home', path: '/' },
+    { name: 'About', path: '/about/' }
+  ]
+}
+
+const sitemap = generateSitemap(config)
+```
+
+## Adding to package.json scripts
+
+You can add convenience scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "htk:init": "htk init",
+    "htk:sync": "htk sync",
+    "htk:sync:makefile": "htk sync:makefile"
+  }
+}
+```
+
+Then run with:
+
+```bash
+npm run htk:init
+npm run htk:sync
+```
+
+## Integration with build process
+
+The sitemap generation script integrates with your Next.js build:
+
+1. Make sure your `htk.config.ts` is properly configured
+2. Add the sitemap generation to your build script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "next build && tsx src/scripts/generate_sitemap.ts"
+  }
+}
+```
+
+3. The sitemap will be automatically generated in your build directory
+
+## Examples
+
+### First time setup
+
+```bash
+cd my-nextjs-htk-project
+npm install @nextjs-htk/core
+npx htk init
+```
+
+### Update to latest templates
+
+```bash
+npx htk sync --force
+```
+
+### Just update the Makefile
+
+```bash
+npx htk sync:makefile --force
+```

packages/core/README.md

@@ -17,6 +17,55 @@ This package requires:
 - react >= 19.0.0
 - react-dom >= 19.0.0
 
+## CLI Tool
+
+The package includes a CLI tool for project standardization and template management.
+
+### Quick Start
+
+```bash
+# Initialize a new project with standard files
+npx htk init
+
+# Sync templates from latest version
+npx htk sync
+
+# Show all available commands
+npx htk help
+```
+
+### Available Commands
+
+- **`htk init`** - Initialize new project with Makefile, scripts, and configs
+- **`htk sync`** - Update all templates to latest version
+- **`htk sync:makefile`** - Sync only the Makefile
+- **`htk sync:scripts`** - Sync only the scripts directory
+
+### Force Overwrite
+
+By default, existing files won't be overwritten. Use `--force` or `-f`:
+
+```bash
+npx htk sync --force
+npx htk init -f
+```
+
+### What Gets Installed
+
+**Makefile** - Standard targets for development and deployment:
+- `make dev` - Start development server
+- `make build` - Build for production
+- `make deploy` - Deploy to GitHub Pages
+- `make help` - Show all available targets
+
+**Scripts** - Utility scripts for your project:
+- `src/scripts/generate_sitemap.ts` - Auto-generate sitemap.xml
+
+**Next.js Config Template** - React 19 compatible configuration with:
+- Webpack alias configuration for single React instance
+- Static export settings for GitHub Pages
+- Source maps enabled for debugging
+
 ## Usage
 
 ### Configuration
@@ -44,6 +93,36 @@ export default defineConfig({
 })
 ```
 
+## Utilities
+
+### Sitemap Generator
+
+Generate SEO-friendly sitemaps from your site configuration:
+
+```typescript
+import { generateSitemap } from '@nextjs-htk/core/utils'
+import type { SitemapConfig } from '@nextjs-htk/core/utils'
+
+const config: SitemapConfig = {
+  siteUrl: 'https://example.com',
+  pages: [
+    { name: 'Home', path: '/', showInNav: true },
+    { name: 'About', path: '/about/', showInNav: true }
+  ],
+  additionalPages: [
+    {
+      path: '/blog/post-1/',
+      priority: 0.7,
+      changefreq: 'weekly'
+    }
+  ]
+}
+
+const sitemap = generateSitemap(config)
+```
+
+The generated script (`src/scripts/generate_sitemap.ts`) automatically uses your `htk.config.ts` to generate the sitemap during build.
+
 ## Components
 
 Components will be added in upcoming releases:

packages/core/bin/htk.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates')
+const commands = {
+  init: 'Initialize a new nextjs-htk project with standard files',
+  sync: 'Sync standard files from nextjs-htk templates',
+  'sync:makefile': 'Sync only the Makefile',
+  'sync:scripts': 'Sync only the scripts directory',
+  help: 'Show this help message'
+}
+
+function showHelp() {
+  console.log('\n@nextjs-htk/core CLI\n')
+  console.log('Usage: npx @nextjs-htk/core <command>\n')
+  console.log('Available commands:\n')
+  Object.entries(commands).forEach(([cmd, desc]) => {
+    console.log(`  ${cmd.padEnd(20)} ${desc}`)
+  })
+  console.log()
+}
+
+function copyFile(src, dest, options = {}) {
+  const { force = false } = options
+
+  if (fs.existsSync(dest) && !force) {
+    console.log(`  ⚠️  ${path.basename(dest)} already exists, skipping (use --force to overwrite)`)
+    return false
+  }
+
+  fs.copyFileSync(src, dest)
+  console.log(`  ✓ ${path.basename(dest)}`)
+  return true
+}
+
+function copyDirectory(src, dest, options = {}) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true })
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath, options)
+    } else {
+      copyFile(srcPath, destPath, options)
+    }
+  }
+}
+
+function syncMakefile(options) {
+  console.log('\nSyncing Makefile...')
+  const src = path.join(TEMPLATES_DIR, 'Makefile')
+  const dest = path.join(process.cwd(), 'Makefile')
+  copyFile(src, dest, options)
+}
+
+function syncScripts(options) {
+  console.log('\nSyncing scripts...')
+  const src = path.join(TEMPLATES_DIR, 'scripts')
+  const dest = path.join(process.cwd(), 'src', 'scripts')
+
+  if (!fs.existsSync(src)) {
+    console.log('  ⚠️  No scripts template directory found')
+    return
+  }
+
+  copyDirectory(src, dest, options)
+}
+
+function init(options) {
+  console.log('\nInitializing nextjs-htk project...\n')
+  syncMakefile(options)
+  syncScripts(options)
+  console.log('\n✓ Project initialized successfully!\n')
+}
+
+function sync(options) {
+  console.log('\nSyncing all templates...\n')
+  syncMakefile(options)
+  syncScripts(options)
+  console.log('\n✓ Sync complete!\n')
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2)
+const command = args[0]
+const flags = args.slice(1)
+const options = {
+  force: flags.includes('--force') || flags.includes('-f')
+}
+
+// Execute command
+switch (command) {
+  case 'init':
+    init(options)
+    break
+  case 'sync':
+    sync(options)
+    break
+  case 'sync:makefile':
+    syncMakefile(options)
+    break
+  case 'sync:scripts':
+    syncScripts(options)
+    break
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp()
+    break
+  default:
+    console.log(`\n❌ Unknown command: ${command}\n`)
+    showHelp()
+    process.exit(1)
+}