create-foliokit 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saurabh Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,378 @@
-# Temporary Holding Version
+# FolioKit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.12.0-brightgreen.svg)](package.json)
+[![npm version](https://img.shields.io/npm/v/foliokit.svg)](https://www.npmjs.com/package/foliokit)
+
+> A modern, zero-config CLI generator that scaffolds high-performance, customizable developer portfolios built with React 19, TypeScript, and Vite.
+
+FolioKit enables developers to launch a sleek, production-ready portfolio in seconds. Instead of wrestling with complex UI code, your entire website—from bio and skills to featured projects and social links—is managed cleanly through a single configuration file: [`data.ts`](templates/default/data.ts).
+
+---
+
+## Features
+
+- **Instant Scaffolding** — Create a complete portfolio project with one command (`npx foliokit`).
+- **Single-File Customization** — Edit `data.ts` to update all content, projects, bio, skills, and layout ordering without touching React components.
+- **Modern Tech Stack** — Built with React 19, TypeScript, and Vite for fast development and lightweight production bundles (~80 kB gzip).
+- **Aesthetic Obsidian Theme** — Designed with a dark graphite palette, atmospheric canvas starfields, and metallic typography accents.
+- **Interactive 3D Magazine Carousel** — Showcase featured projects in a perspective-lifted cover gallery with mouse-tilt, touch swipe, trackpad wheel gestures, and keyboard navigation.
+- **Automatic Skill Icons** — Integrates with [Skill Icons](https://skillicons.dev) and Simple Icons for crisp vector technology and brand badges.
+- **Dynamic Local Time & Clock** — Real-time digital clock synced to your configured IANA time zone.
+- **Pre-Configured Content Sections** — Hero, About, Skills, Featured Projects, Work Experience, Education, Testimonials, and Contact.
+- **Automated SEO & Social Sharing** — Build script automatically injects personalized OpenGraph tags, Twitter cards, canonical links, and generates a valid `sitemap.xml` and `robots.txt`.
+- **Accessible & Responsive** — Verified across mobile (320px+), tablet, laptop, and ultra-wide screens. Full support for `prefers-reduced-motion` and WCAG touch targets.
+- **Static Hosting Ready** — Zero-config static deployment on Vercel, Netlify, Cloudflare Pages, and GitHub Pages.
+
+---
+
+## Preview
+
+<!-- Portfolio UI Preview Screenshot Placeholder -->
+<!-- Place your screenshot here: ![FolioKit Preview](https://raw.githubusercontent.com/saurabhhdev/foliokit/main/preview.png) -->
+
+The generated portfolio features a dark obsidian background (`#000000`), subtle starfield overlays, golden metallic accent highlights, and clean dotted framing inspired by modern developer terminals and developer tool aesthetic.
+
+---
+
+## Requirements
+
+Before running FolioKit, ensure your environment meets these requirements:
+
+- **Node.js**: Version `22.12.0` or higher
+- **npm**: Version `10.0.0` or higher (or compatible `pnpm` / `yarn`)
+- **Operating Systems**: macOS, Linux, and Windows 10/11
+
+To verify your installed Node.js version, run:
+
+```bash
+node --version
+```
+
+---
+
+## Quick Start
+
+Generate your developer portfolio in three steps:
+
+### 1. Run the CLI
+
+```bash
+npx foliokit
+```
+
+*Or install globally:*
+
+```bash
+npm install -g foliokit
+foliokit
+```
+
+### 2. Answer the Interactive Prompts
+
+```text
+FOLIOKIT
+Developer Portfolio Generator
+
+? What should your project be called? my-portfolio
+? Install dependencies? (Y/n) y
+```
+
+- **Project name**: Enter a folder name using lowercase letters, numbers, and single hyphens (default: `my-portfolio`).
+- **Install dependencies**: Choose whether FolioKit should automatically run `npm install` inside the created folder.
+
+### 3. Start Developing
+
+```bash
+cd my-portfolio
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) in your browser to view your live portfolio.
+
+---
+
+## CLI Commands & Options
+
+FolioKit provides a straightforward command-line interface:
+
+| Command / Option | Description |
+| :--- | :--- |
+| `npx foliokit` | Runs the interactive project creation wizard in the current directory. |
+| `foliokit create` | Explicit subcommand to start the setup wizard. |
+| `-v, --version` | Outputs the current installed FolioKit version. |
+| `-h, --help` | Displays help information, available flags, and usage syntax. |
+
+### Examples
+
+```bash
+# Check installed CLI version
+foliokit --version
+
+# View usage guidelines
+foliokit --help
+
+# Create a new project
+foliokit create
+```
+
+---
+
+## Customization Guide (`data.ts`)
+
+All portfolio content is centralized in the root `data.ts` file of your generated project. Open `data.ts` in your code editor to personalize your site.
+
+### 1. Personal Details & Hero
+
+```typescript
+profile: {
+  name: 'Alex Rivera',
+  headline: 'Full Stack Engineer & Open Source Contributor',
+  introduction: "Hey, there! I'm a",
+  about: `I build scalable web applications and developer tools.
+  
+I specialize in React, Node.js, and distributed systems.`,
+  location: 'San Francisco, CA',
+  timeZone: 'America/Los_Angeles',
+  timeZoneLabel: 'PST',
+  profileImage: '/avatar-placeholder.svg', // or '/my-photo.jpg' placed in public/
+  quote: 'Build with curiosity. Share what you learn.',
+}
+```
+
+### 2. Social Links
+
+Add or update your social media profiles in the `socialIcons` array:
+
+```typescript
+socialIcons: [
+  { label: 'GitHub', icon: 'github', url: 'https://github.com/your-username', color: '#f2f0e9' },
+  { label: 'LinkedIn', icon: 'linkedin', url: 'https://linkedin.com/in/your-username', color: '#0a66c2' },
+  { label: 'X', icon: 'x', url: 'https://x.com/your-username', color: '#f2f0e9' },
+]
+```
+
+### 3. Technical Skills
+
+Add, remove, or reorder technologies. Icons are automatically fetched from [Skill Icons](https://skillicons.dev) using the `icon` identifier:
+
+```typescript
+skills: [
+  { name: 'React', icon: 'react', category: 'Frontend' },
+  { name: 'TypeScript', icon: 'ts', category: 'Frontend' },
+  { name: 'Node.js', icon: 'nodejs', category: 'Backend' },
+  { name: 'PostgreSQL', icon: 'postgres', category: 'Backend' },
+  { name: 'Docker', icon: 'docker', category: 'Tools' },
+]
+```
+
+### 4. Featured Projects
+
+Projects with `featured: true` appear prominently in the interactive 3D magazine gallery as well as the detailed project cards below:
+
+```typescript
+projects: [
+  {
+    name: 'DevFlow',
+    category: 'DEVELOPER TOOLING',
+    description: 'An open-source terminal workflow engine designed to automate repetitive task pipelines.',
+    image: '/project-placeholder.svg', // Place your thumbnail in public/
+    imageAlt: 'DevFlow terminal preview',
+    technologies: [
+      { name: 'TypeScript', icon: 'ts' },
+      { name: 'Node.js', icon: 'nodejs' },
+    ],
+    liveUrl: 'https://devflow.example',
+    githubUrl: 'https://github.com/your-username/devflow',
+    featured: true,
+  },
+]
+```
+
+### 5. Work Experience & Education
+
+```typescript
+experience: [
+  {
+    title: 'Senior Software Engineer',
+    organization: 'Acme Corp',
+    date: '2023 – Present',
+    description: 'Architected microservices and improved core API latency by 35%.',
+  },
+],
+education: [
+  {
+    title: 'B.S. in Computer Science',
+    organization: 'University of California, Berkeley',
+    date: '2019 – 2023',
+    description: 'Focused on algorithms, distributed databases, and software engineering.',
+  },
+]
+```
+
+### 6. Optional Sections (Testimonials, Experience, Education)
+
+Content sections render dynamically based on whether items exist in their array. To omit any optional section from the portfolio, simply leave its array empty:
+
+```typescript
+// Leave empty to omit this section from the portfolio:
+testimonials: [],
+experience: [],
+education: [],
+```
+
+---
+
+## Images and Assets
+
+All static visual assets live inside the `public/` directory of your generated project:
+
+```text
+my-portfolio/
+└── public/
+    ├── avatar-placeholder.svg
+    ├── project-placeholder.svg
+    ├── footer-heart.png
+    ├── love-always-wins.png
+    └── robots.txt
+```
+
+### How to Use Your Own Images:
+
+1. Copy your image into the `public/` folder (e.g. `public/my-photo.jpg`).
+2. In `data.ts`, reference the image with a leading slash:
+   ```typescript
+   profileImage: '/my-photo.jpg'
+   ```
+3. For project thumbnails, copy images to `public/` (recommended aspect ratio: `16:9` or `1200x675` px) and set `image: '/project-one.png'`.
+4. **Supported Formats**: SVG, WebP, PNG, JPG/JPEG.
+5. **Fallbacks**: If an image fails to load or is omitted, FolioKit automatically renders accessible fallback elements (e.g., initial-letter monogram badges for avatars).
+
+---
+
+## Project Structure
+
+A portfolio generated by FolioKit has the following clean structure:
+
+```text
+my-portfolio/
+├── data.ts                   # Central content configuration (edit this!)
+├── index.html                # HTML entry point (title & metadata injected from data.ts)
+├── package.json              # Project scripts and dependencies
+├── vite.config.ts            # Vite configuration with automated metadata plugin
+├── tsconfig.json             # TypeScript configuration
+├── public/                   # Static assets (images, avatars, icons, robots.txt)
+│   ├── avatar-placeholder.svg
+│   └── project-placeholder.svg
+├── scripts/
+│   └── generate-seo.mjs      # Production SEO, canonical URL, and sitemap generator
+└── src/
+    ├── main.tsx              # React application entry point
+    ├── App.tsx               # Main portfolio layout and section renderers
+    ├── styles.css            # Responsive styles and theme variables
+    ├── utils.ts              # Lightweight DOM helpers
+    ├── BrandIcon.tsx         # Vector brand logo helper with fallbacks
+    ├── ProjectMagazineGallery.tsx  # 3D interactive carousel
+    └── ProjectMagazineGallery.css  # 3D perspective & carousel styling
+```
+
+---
+
+## Tech Stack
+
+### FolioKit CLI
+- **Runtime**: [Node.js](https://nodejs.org) (>= 22.12.0)
+- **CLI Framework**: [Commander.js](https://github.com/tj/commander.js)
+- **Interactive Prompts**: [Inquirer.js](https://github.com/SBoudrias/Inquirer.js)
+- **Terminal Styling**: [Chalk](https://github.com/chalk/chalk)
+- **Terminal Spinners**: [Ora](https://github.com/sindresorhus/ora)
+
+### Generated Portfolio
+- **UI Framework**: [React 19](https://react.dev)
+- **Language**: [TypeScript](https://www.typescriptlang.org)
+- **Bundler & Dev Server**: [Vite 8](https://vitejs.dev)
+- **Icons**: [Lucide React](https://lucide.dev) & [Simple Icons](https://simpleicons.org)
+- **Styling**: Native Modern CSS (CSS Grid, Flexbox, CSS Variables, 3D Transforms)
+
+---
+
+## Troubleshooting
+
+### 1. "Node.js version must be >=22.12.0"
+- **Cause**: An older Node.js runtime is active in your terminal.
+- **Solution**: Install or activate Node.js 22.12.0 or newer using [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm):
+  ```bash
+  nvm install 22
+  nvm use 22
+  ```
+
+### 2. Destination Folder Already Exists
+- **Cause**: A folder with the specified project name already exists in your current directory.
+- **Solution**: Choose a different name when prompted, or confirm the prompt to overwrite the existing folder.
+
+### 3. Dependency Installation Failed
+- **Cause**: Network timeout or strict corporate proxy blocked `npm install`.
+- **Solution**: Your generated project files are safely preserved. Navigate into the folder and manually install dependencies:
+  ```bash
+  cd my-portfolio
+  npm install
+  ```
+
+### 4. Development Port 5173 in Use
+- **Cause**: Another local development server is running on port 5173.
+- **Solution**: Vite automatically attempts the next available port (e.g. 5174). You can also specify a custom port:
+  ```bash
+  npm run dev -- --port 3000
+  ```
+
+### 5. TypeScript Error After Editing `data.ts`
+- **Cause**: A required field was removed or a type mismatch was introduced.
+- **Solution**: Check the terminal output or editor diagnostics. Run `npm test` inside the portfolio directory to validate your `data.ts` structure against the test suite.
+
+---
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+### Development Workflow
+
+1. Fork the repository on GitHub.
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/saurabhhdev/foliokit.git
+   cd foliokit
+   ```
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+4. Run CLI and generator tests:
+   ```bash
+   npm test
+   ```
+5. Test the default template:
+   ```bash
+   cd templates/default
+   npm test
+   npm run build
+   cd ../..
+   ```
+6. Create a feature branch (`git checkout -b feature/amazing-idea`), commit your changes, and submit a pull request.
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for complete details.
+
+Copyright (c) 2026 **Saurabh Pandey**.
+
+---
+
+## Author & Links
+
+- **Author**: Saurabh Pandey
+- **GitHub**: [@saurabhhdev](https://github.com/saurabhhdev)
+- **Repository**: [https://github.com/saurabhhdev/foliokit](https://github.com/saurabhhdev/foliokit)
+- **Issue Tracker**: [https://github.com/saurabhhdev/foliokit/issues](https://github.com/saurabhhdev/foliokit/issues)

package/bin/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js'
+import { reportCliError } from '../src/utils/errors.js'
+
+runCli().catch(reportCliError)

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "create-foliokit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Generate customizable React and TypeScript developer portfolios",
+  "type": "module",
+  "main": "./src/cli.js",
+  "exports": {
+    ".": "./src/cli.js",
+    "./generator": "./src/generator.js",
+    "./package.json": "./package.json"
+  },
+  "author": "Saurabh Pandey",
+  "scripts": {
+    "test": "node --test tests"
+  },
+  "bin": {
+    "foliokit": "./bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "portfolio",
+    "developer-portfolio",
+    "react",
+    "typescript",
+    "cli",
+    "generator"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saurabhhdev/foliokit.git"
+  },
+  "homepage": "https://github.com/saurabhhdev/foliokit#readme",
+  "bugs": {
+    "url": "https://github.com/saurabhhdev/foliokit/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^6.0.1",
+    "commander": "^15.0.0",
+    "inquirer": "^14.2.5",
+    "ora": "^9.4.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { Command } from 'commander'
+import chalk from 'chalk'
+import inquirer from 'inquirer'
+import { generatePortfolio } from './generator.js'
+import { promptForProjectOptions } from './prompts.js'
+import { getPackagePath } from './utils/paths.js'
+import { createProgress } from './utils/progress.js'
+
+const packageMetadata = JSON.parse(readFileSync(getPackagePath('package.json'), 'utf8'))
+
+function showWelcome() {
+  console.log(chalk.bold.cyan('FOLIOKIT'))
+  console.log(chalk.dim('Developer Portfolio Generator'))
+  console.log()
+}
+
+async function startSetup() {
+  showWelcome()
+  const options = await promptForProjectOptions()
+
+  if (!options) {
+    console.log(chalk.yellow('Setup cancelled.'))
+    return
+  }
+
+  let projectPath
+  try {
+    projectPath = await generatePortfolio(options)
+  } catch (error) {
+    if (!(error instanceof Error) || error.code !== 'EEXIST') throw error
+    let overwrite
+    try {
+      ({ overwrite } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'overwrite',
+        message: `The folder ${options.projectName} already exists. Replace it?`,
+        default: false,
+      }]))
+    } catch (promptError) {
+      if (promptError instanceof Error && promptError.name === 'ExitPromptError') {
+        console.log(chalk.yellow('Setup cancelled. Existing project was left unchanged.'))
+        return
+      }
+      throw promptError
+    }
+    if (!overwrite) {
+      console.log(chalk.yellow('Existing project was left unchanged.'))
+      return
+    }
+    projectPath = await generatePortfolio({ ...options, overwrite: true })
+  }
+
+  let dependenciesInstalled = false
+  if (options.installDependencies) {
+    const windows = process.platform === 'win32'
+    const install = spawn(windows ? (process.env.ComSpec || 'cmd.exe') : 'npm', windows ? ['/d', '/s', '/c', 'npm.cmd install'] : ['install'], {
+      cwd: projectPath,
+      stdio: 'inherit',
+      shell: false,
+    })
+    const installation = createProgress('Installing dependencies...').start()
+    const result = await new Promise((resolve) => {
+      install.once('error', (error) => resolve({ code: 1, error }))
+      install.once('close', (code) => resolve({ code: code ?? 1 }))
+    })
+    dependenciesInstalled = result.code === 0
+    if (dependenciesInstalled) installation.succeed('Dependencies installed')
+    else installation.fail('Dependency installation failed')
+    if (!dependenciesInstalled) {
+      console.error(chalk.red('Dependency installation failed. Your generated project is still available.'))
+      if (result.error) console.error(chalk.dim(result.error.message))
+      console.error(`Run ${chalk.bold('npm install')} inside ${options.projectName} to try again.`)
+    }
+  }
+
+  const configuration = { ...options, projectPath }
+  console.log()
+  console.log(chalk.green('✔ Portfolio generated successfully!'))
+  console.log()
+  console.log(chalk.bold('Next steps:'))
+  console.log(`  cd ${configuration.projectName}`)
+  if (!dependenciesInstalled) console.log('  npm install')
+  console.log('  npm run dev')
+  console.log()
+  console.log(`Customize your portfolio by editing ${chalk.bold('data.ts')}.`)
+  if (options.installDependencies && !dependenciesInstalled) process.exitCode = 1
+}
+
+export function createCli() {
+  const program = new Command()
+
+  program
+    .name('foliokit')
+    .description('Generate customizable developer portfolio websites')
+    .version(packageMetadata.version, '-v, --version')
+    .showHelpAfterError()
+    .action(startSetup)
+
+  program
+    .command('create')
+    .description('Create a portfolio project')
+    .action(startSetup)
+
+  return program
+}
+
+export async function runCli(argv = process.argv) {
+  await createCli().parseAsync(argv)
+}