create-foliokit 0.0.0-stage → 1.0.1

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,112 @@
-# 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.
+[![npm](https://img.shields.io/npm/v/create-foliokit.svg)](https://www.npmjs.com/package/create-foliokit)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.12.0-brightgreen.svg)](package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+FolioKit is a CLI for creating a customizable developer portfolio. It scaffolds a responsive **React 19**, **TypeScript**, and **Vite** website with a dark grid background, framed sections, social links, and an interactive project gallery.
+
+Created and maintained by [Saurabh Pandey](https://github.com/saurabhhdev) · [GitHub repository](https://github.com/saurabhhdev/foliokit)
+
+---
+
+## ✨ Make It Yours
+
+Most portfolio content is edited in one file: `data.ts` in the generated project.
+
+| What | Where |
+| --- | --- |
+| Name, headline, bio, photo, location, time zone, resume | `data.ts` → `profile` |
+| Social profiles and links | `data.ts` → `socialIcons` |
+| Work history and organization logos | `data.ts` → `experience` |
+| Schools, programs, dates, locations | `data.ts` → `education` |
+| Skill names, icons, and categories | `data.ts` → `skills` |
+| Project details, screenshots, technologies, URLs | `data.ts` → `projects` |
+| Recommendations | `data.ts` → `testimonials` |
+| Contact email | `data.ts` → `contact` |
+| Browser and social preview metadata | `data.ts` → `seo` |
+
+Copy images into `public/` and use paths such as `'/my-photo.jpg'` in `data.ts`. The template includes avatar, project, and experience logo placeholders. Leave an optional section array empty (`[]`) to hide that section.
+
+Interface labels are beside the components in `src/App.tsx` and `src/ProjectMagazineGallery.tsx`. Colors, grid, spacing, and responsive styles are in `src/styles.css` and `src/ProjectMagazineGallery.css`.
+
+---
+
+## 🛠 Run Locally
+
+You need Node.js **22.12.0 or newer** to run the CLI. No global installation is required.
+
+```bash
+npx create-foliokit@latest
+```
+
+Choose a project folder name and whether to install dependencies. Then:
+
+```bash
+cd my-portfolio
+npm run dev
+```
+
+Open the local address printed by Vite, usually `http://localhost:5173`. If you skipped dependency installation, run `npm install` in the project folder first.
+
+To install the CLI globally instead:
+
+```bash
+npm install --global create-foliokit
+foliokit
+```
+
+### Available commands
+
+| Command | Action |
+| --- | --- |
+| `foliokit` | Start the setup wizard. |
+| `foliokit create` | Start the wizard with the explicit `create` command. |
+| `foliokit --help` | Show CLI help. |
+| `foliokit --version` | Print the installed version. |
+
+---
+
+## 📦 Build and Deploy
+
+Run the generated portfolio's checks and create a production build:
+
+```bash
+npm test
+npm run build
+npm run preview
+```
+
+Vite writes the static site to `dist/`. Deploy it to a static host such as **Vercel** or **Netlify** with build command `npm run build` and output directory `dist`.
+
+For canonical URLs and sitemap generation, set `SITE_URL` in the hosting environment to your HTTPS origin, for example `https://portfolio.example` (no path or query string). You can also set `seo.siteUrl` in `data.ts`.
+
+---
+
+## 🧰 Stack and Project Files
+
+The generated site uses React, TypeScript, Vite, Lucide icons, and CSS. The CLI package uses Commander, Inquirer, Chalk, and Ora.
+
+```text
+my-portfolio/
+├── data.ts                 # Edit your portfolio content
+├── types.ts                # Shared TypeScript types
+├── public/                 # Images and robots.txt
+├── scripts/generate-seo.mjs
+├── tests/portfolio.test.js
+└── src/
+    ├── App.tsx
+    ├── BrandIcon.tsx
+    ├── ProjectMagazineGallery.tsx
+    ├── ProjectMagazineGallery.css
+    ├── styles.css
+    └── main.tsx
+```
+
+---
+
+## 🙌 Contributing and License
+
+For CLI development, run `npm install` and `npm test` at the repository root. To check the bundled website template, run `npm test` and `npm run build` inside `templates/default/`.
+
+FolioKit is open source under the [MIT License](LICENSE).

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.1",
+  "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)
+}

package/src/generator.js

@@ -0,0 +1,133 @@
+import { copyFile, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises'
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { getDefaultTemplatePath } from './utils/paths.js'
+import { validateProjectName } from './utils/project-name.js'
+import { createProgress } from './utils/progress.js'
+
+const excludedDirectories = new Set([
+  '.angular', '.cache', '.git', '.netlify', '.next', '.parcel-cache', '.svelte-kit',
+  '.turbo', '.vercel', '.vite', 'build', 'coverage', 'dist', 'node_modules', 'tmp', 'temp',
+])
+const excludedExtensions = new Set([
+  '.bak', '.log', '.orig', '.pem', '.p12', '.pfx', '.key', '.secret', '.token',
+  '.swp', '.swo', '.tsbuildinfo',
+])
+const excludedFiles = new Set([
+  '.ds_store', '.envrc', '.npmignore', '.npmrc', '.netrc', '.pypirc', 'credentials', 'credentials.json',
+  'id_ed25519', 'id_rsa', 'secrets.json', 'thumbs.db',
+])
+
+function isWithin(parent, child) {
+  const path = relative(parent, child)
+  return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path))
+}
+
+function shouldExclude(name, isDirectory) {
+  const lower = name.toLowerCase()
+  if (isDirectory && excludedDirectories.has(lower)) return true
+  if (excludedFiles.has(lower) || excludedExtensions.has(extname(lower))) return true
+  if (lower === '.env' || (lower.startsWith('.env.') && lower !== '.env.example')) return true
+  if (/\.(?:tmp|temp|swp|swo|orig|bak|log)$/.test(lower)) return true
+  return false
+}
+
+export function resolveProjectDestination(projectName, workingDirectory = process.cwd()) {
+  const validation = validateProjectName(projectName)
+  if (validation !== true) throw new Error(`Invalid project name: ${validation}`)
+  const base = resolve(workingDirectory)
+  const destination = resolve(base, projectName)
+  if (!isWithin(base, destination) || destination === base) {
+    throw new Error('The project destination must be a new child of the working directory.')
+  }
+  return destination
+}
+
+async function copyTree(source, destination) {
+  await mkdir(destination, { recursive: true })
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    if (shouldExclude(entry.name, entry.isDirectory())) continue
+    const from = join(source, entry.name)
+    const to = join(destination, entry.name)
+    if (entry.isSymbolicLink()) throw new Error(`Template contains an unsupported symbolic link: ${from}`)
+    if (entry.isDirectory()) {
+      await copyTree(from, to)
+    } else if (entry.isFile()) {
+      await copyFile(from, to)
+    }
+  }
+}
+
+async function updatePackageNames(destination, projectName) {
+  const packagePath = join(destination, 'package.json')
+  const packageData = JSON.parse(await readFile(packagePath, 'utf8'))
+  packageData.name = projectName
+  await writeFile(packagePath, `${JSON.stringify(packageData, null, 2)}\n`)
+
+  const lockPath = join(destination, 'package-lock.json')
+  try {
+    const lock = JSON.parse(await readFile(lockPath, 'utf8'))
+    lock.name = projectName
+    if (lock.packages?.['']) lock.packages[''].name = projectName
+    await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`)
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+}
+
+export function getDefaultTemplateDirectory() {
+  return getDefaultTemplatePath()
+}
+
+export async function generatePortfolio(options, context = {}) {
+  const projectName = options?.projectName
+  const workingDirectory = resolve(context.workingDirectory ?? process.cwd())
+  const templatePath = resolve(context.templateDirectory ?? getDefaultTemplateDirectory())
+
+  const [workingStats, templateStats] = await Promise.all([lstat(workingDirectory), lstat(templatePath)])
+  if (!workingStats.isDirectory()) throw new Error(`Working directory is not a directory: ${workingDirectory}`)
+  if (!templateStats.isDirectory()) throw new Error(`Portfolio template directory was not found: ${templatePath}`)
+  const [realDestinationParent, realTemplate] = await Promise.all([realpath(workingDirectory), realpath(templatePath)])
+  const destination = resolveProjectDestination(projectName, realDestinationParent)
+  if (isWithin(realTemplate, destination) || isWithin(destination, realTemplate)) {
+    throw new Error('The project destination cannot overlap the bundled template directory.')
+  }
+
+  const creating = createProgress('Creating project...').start()
+  try {
+    await mkdir(destination)
+  } catch (error) {
+    creating.fail('Could not create project directory')
+    if (error.code === 'EEXIST' && options.overwrite === true) {
+      const existing = await lstat(destination)
+      if (!existing.isDirectory() || existing.isSymbolicLink()) {
+        throw new Error(`The destination exists and is not a regular directory: ${destination}`)
+      }
+      await rm(destination, { recursive: true })
+      await mkdir(destination)
+    } else if (error.code === 'EEXIST') {
+      const conflict = new Error(`The destination already exists: ${destination}`)
+      conflict.code = 'EEXIST'
+      conflict.projectPath = destination
+      throw conflict
+    } else {
+      throw error
+    }
+  }
+  creating.succeed('Project directory created')
+
+  const progress = createProgress('Copying portfolio template...').start()
+  let configuring
+  try {
+    await copyTree(templatePath, destination)
+    progress.succeed('Copying portfolio template')
+    configuring = createProgress('Configuring package.json...').start()
+    await updatePackageNames(destination, projectName)
+    configuring.succeed('Configuring package.json')
+    return destination
+  } catch (error) {
+    progress.fail('Could not create portfolio')
+    configuring?.fail('Could not configure project')
+    await rm(destination, { recursive: true, force: true })
+    throw error
+  }
+}

package/src/prompts.js

@@ -0,0 +1,44 @@
+import inquirer from 'inquirer'
+import {
+  DEFAULT_PROJECT_NAME,
+  normalizeProjectName,
+  validateProjectName,
+} from './utils/project-name.js'
+
+export function createProjectQuestions() {
+  return [
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'What should your project be called?',
+      default: DEFAULT_PROJECT_NAME,
+      filter: normalizeProjectName,
+      validate: validateProjectName,
+    },
+    {
+      type: 'confirm',
+      name: 'installDependencies',
+      message: 'Install dependencies?',
+      default: true,
+    },
+  ]
+}
+
+export async function promptForProjectOptions(prompt = (questions) => inquirer.prompt(questions)) {
+  try {
+    const answers = await prompt(createProjectQuestions())
+    if (!answers) return null
+
+    const projectName = normalizeProjectName(answers.projectName)
+    const validation = validateProjectName(projectName)
+    if (validation !== true) throw new Error(validation)
+
+    return {
+      projectName,
+      installDependencies: Boolean(answers.installDependencies),
+    }
+  } catch (error) {
+    if (error instanceof Error && error.name === 'ExitPromptError') return null
+    throw error
+  }
+}

package/src/utils/errors.js

@@ -0,0 +1,7 @@
+import chalk from 'chalk'
+
+export function reportCliError(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`${chalk.red('FolioKit error:')} ${message}\n`)
+  process.exitCode = 1
+}

package/src/utils/paths.js

@@ -0,0 +1,12 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+
+export function getPackagePath(...segments) {
+  return resolve(packageRoot, ...segments)
+}
+
+export function getDefaultTemplatePath() {
+  return getPackagePath('templates', 'default')
+}

package/src/utils/progress.js

@@ -0,0 +1,5 @@
+import ora from 'ora'
+
+export function createProgress(message) {
+  return ora(message)
+}

package/src/utils/project-name.js

@@ -0,0 +1,30 @@
+export const DEFAULT_PROJECT_NAME = 'my-portfolio'
+
+const projectNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const reservedNames = new Set([
+  'node_modules',
+  'con',
+  'prn',
+  'aux',
+  'nul',
+  ...Array.from({ length: 9 }, (_, index) => `com${index + 1}`),
+  ...Array.from({ length: 9 }, (_, index) => `lpt${index + 1}`),
+])
+
+export function normalizeProjectName(value) {
+  if (typeof value !== 'string') return DEFAULT_PROJECT_NAME
+  return value.trim() || DEFAULT_PROJECT_NAME
+}
+
+export function validateProjectName(value) {
+  const name = typeof value === 'string' ? value.trim() : ''
+
+  if (!name) return 'Enter a project name.'
+  if (name.length > 214) return 'Project names must be 214 characters or fewer.'
+  if (!projectNamePattern.test(name)) {
+    return 'Use lowercase letters and numbers separated by single hyphens.'
+  }
+  if (reservedNames.has(name)) return 'That name is reserved by the operating system or npm.'
+
+  return true
+}