Codex-generated pull request

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Tests
+        run: npm test

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Thanks for your interest in improving Web Learning Kit Generator.
+
+## Development setup
+
+1. Install dependencies:
+   - `npm install`
+2. Run checks:
+   - `npm run typecheck`
+   - `npm test`
+3. Run the interactive generator:
+   - `npm run init`
+
+## Contribution guidelines
+
+- Keep changes small and focused.
+- Prefer TypeScript-safe updates.
+- Add or update tests when behavior changes.
+- Update README/docs when UX or command flow changes.
+
+## Commit and PR guidance
+
+- Use clear, imperative commit messages.
+- Include a short summary of what changed and why.
+- Mention any behavior changes for generated projects.

README.md

@@ -1,117 +1,159 @@
-<div style="display: flex; align-items: flex-start;">
-  <div style="flex: 1;">
-    <h1>Web Learning Kit Generator</h1>
-    <p>Web Learning Kit Generator is a tool designed for beginners who want to build static websites with minimal configuration. The application creates a Gulp build process dynamically based on the user's choice of markup language(HTML/Pug), stylesheet language(SASS/SCSS), and scripting language(Javascript/Typescript). It's an easy and fast way to get started with a more realistic development environment on your local machine, beyond online IDEs</p>
-
-    This project is based on a simple and fast workflow focused mainly on the front-end task. It gives a solid starting point for newcomers who wants a ready-to-deploy local environment setup. The sources used to build this project includes:
-  </div>
-  <div style="flex: 0 0 300px; margin-left: 20px;">
-    <img src="./_gulp/logo.png">
-  </div>
-</div>
-
-  * [H5BP Project](https://github.com/h5bp/html5-boilerplate)
-  * [React Redux Starter Kit](https://github.com/davezuko/react-redux-starter-kit)
-  * [Mark Goodyear's Blog](https://markgoodyear.com/2014/01/getting-started-with-gulp/)
-  * [Web Starter Kit](https://github.com/google/web-starter-kit)
+# Web Learning Kit Generator
 
-## Features
+Web Learning Kit Generator helps beginners generate a **local, realistic front-end workflow** (not a browser sandbox) using Gulp, with interactive choices for:
+
+- Markup: **HTML** or **Pug**
+- Styles: **Sass** or **SCSS**
+- Scripts: **JavaScript** or **TypeScript**
 
-  * Dynamic Configuration: Choose your preferred markup (**Pug/HTML**), stylesheet (**Sass/SCSS/CSS**), and script (**JavaScript/TypeScript**) languages, and the tool will generate a customized Gulpfile for you.
-
-  * Beginner-Friendly: Ideal for those new to web development who want to experiment with real-world tools and workflows.
-
-  * Extensible: Start simple, and gradually explore more advanced features as you become comfortable.
-
-  * Minimal Setup: Get up and running quickly without the need for complex configuration.
-
-  * Realistic Environment: Experience coding outside of online IDEs, and start using Git or other tools as you grow your skills.
+It is designed to teach how real projects are structured, built, and shipped from your own machine.
+
+---
 
-  * Bonus: you can add **Josh Comeau** css reset and **Necolas** css normalize
+## Why this project exists
 
-## Prerequisites
+Most beginners start in online playgrounds and miss practical workflows such as:
 
-Before you begin, ensure you have the following installed on your system:
+- Local tooling setup
+- Build pipelines
+- Static asset optimization
+- Source organization
+- Deployment-ready `dist` outputs
 
-* Node.js (v14 or later)
-* **npm** (comes with Node.js) or **Yarn**
+This generator creates a beginner-friendly starting point while still exposing real-world build concepts.
 
-## Getting Started
+## Features
 
-After [Node.js](https://nodejs.org/en/download/), [npm](https://docs.npmjs.com/getting-started/installing-node), [Gulp](https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md) and [Bower](https://bower.io/#install-bower)(optional) installation, you can create a new project based on `pug-sass-boilerplate-starter-kit` by doing the following:
+- **Interactive project bootstrap** for language/tool choices
+- **Generated Gulp pipeline** for styles, scripts, markup, and images
+- **Live reload dev server** via BrowserSync
+- **Production build output** in `dist/`
+- Optional CSS starter files:
+  - Josh Comeau-style reset
+  - Nicolas Gallagher normalize
 
-## Installation
+## Requirements
 
-### 1 - Clone or download this repository
+- Node.js 18+ (Node.js 20 recommended)
+- npm (or Yarn)
 
-### 2 - Install dependencies:
+## Quick start
 
-Using npm:
 ```bash
 npm install
+npm run init
+npm start
 ```
 
-Or using Yarn:
+Build for production:
+
 ```bash
-yarn install
+npm run build
 ```
 
-## Usage
+Quality checks:
 
-### Development
+```bash
+npm run typecheck
+npm test
+```
 
-To start the development server with live reloading:
+## Project structure
 
-```bash
-gulp
+```text
+.
+├── src/                # Generated source files (created after npm run init)
+│   ├── img/            # Image assets
+│   ├── js|ts/          # Script entry and modules
+│   ├── sass|scss/      # Styling source
+│   └── html|pug/       # Markup source
+├── dist/               # Build output
+├── _gulp/              # Generator modules and task templates
+├── gulpfile.js         # Generated Gulp pipeline
+└── README.md
 ```
 
-This will run the `gulp` command, which starts a local server and watches for file changes.
+## Current quality/devops baseline
 
-### Production Build
+This repository now includes:
 
-To create a production-ready build:
+- Type checking (`npm run typecheck`)
+- Unit tests for filesystem utilities (`npm test`)
+- CI workflow for typecheck + tests (GitHub Actions)
+- Contributing and security documentation
 
-```bash
-npm run build
-```
-or
-```bash
-yarn build
-```
+---
 
-This will generate optimized files in the `dist` directory.
+## Deep improvement roadmap
 
-### Running Your Local Server With Gulp
+If your goal is to make this starter more production-realistic for learners, implement the following in phases.
 
-This task will open the browser window usually with the URL http://localhost:3000/. Any saved changes made to the project files, will reflect automatically over the browser.
+### Phase 1 — Reliability and maintainability (short term)
 
-## Project Structure
+1. **Refactor generator templates into composable modules**
+   - Move generated gulpfile snippets into dedicated template files.
+   - Add snapshot tests for generated output.
+2. **Introduce a config schema**
+   - Validate user choices with a typed schema (e.g., Zod).
+3. **Error handling and UX improvements**
+   - Improve setup error messages and recovery paths.
+   - Add non-interactive flags for automation (`--script ts --style scss --markup pug`).
 
-```
-.
-├── src/                # ** Your code folder! **
-│   ├── img/            # Image files
-│   ├── js/             # JS/TS files
-│   ├── styles/         # Sass/SCSS files
-│   └── templates/      # Pug/HTML files
-│   
-├── _gulp/              # Gulp configuration and tasks
-├── dist/               # Production build output
-├── gulpfile.js         # Gulp entry point
-├── package.json        # Project dependencies and scripts
-└── README.md           # Project documentation
-```
-The src/ directory is created after the Yarn or npm install, **this is where your code journey begins**. The dist/ and build/ folders can be used to host your web project in a simple and convenient way. there are a lot of options to host it, including **Github Pages**
+### Phase 2 — Security and supply chain
 
-## Contributing
+1. **Automated dependency security**
+   - Enable Dependabot/Renovate.
+   - Add `npm audit --audit-level=high` in CI (non-blocking at first).
+2. **Secure generated defaults**
+   - Include optional security headers guidance (CSP, X-Content-Type-Options) in deployment docs.
+3. **Harden build tooling**
+   - Pin and regularly review toolchain versions.
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+### Phase 3 — Better learning outcomes for users
 
-## License
+1. **Preset modes**
+   - `beginner`, `intermediate`, `production-lite` presets.
+2. **Educational comments in generated files**
+   - Explain each Gulp task and where to customize.
+3. **Project recipes**
+   - Add examples: landing page, docs site, multi-page static site.
+
+### Phase 4 — DevOps and deployment excellence
+
+1. **Deployment templates**
+   - Add one-click workflows for GitHub Pages / Netlify / Vercel static output.
+2. **Release automation**
+   - Semantic versioning + changelog generation.
+3. **Performance checks**
+   - Add Lighthouse CI or static asset budget checks.
+
+### Phase 5 — Ecosystem growth
 
-This project is open source and available under the [MIT License](LICENSE).
+1. **Plugin architecture** for additional features (ESLint, Prettier, Vitest, Playwright)
+2. **CLI packaging** (`npx web-learning-kit-generator`)
+3. **Template marketplace** for community starter packs
 
 ---
 
-For more detailed information about the gulp tasks and project configuration, please refer to the comments in the `gulpfile.js` and the files in the `_gulp` directory.
+## Suggested next features (high impact)
+
+- Add generated **ESLint + Prettier** setup.
+- Add optional **testing scaffold** (Vitest + basic smoke tests).
+- Add generated `.editorconfig`, `.gitignore`, `.nvmrc`.
+- Add optional accessibility starter checks (axe/lint guidance).
+
+## Documentation
+
+- [Contributing guide](./CONTRIBUTING.md)
+- [Security policy](./SECURITY.md)
+
+## Inspiration
+
+- [H5BP Project](https://github.com/h5bp/html5-boilerplate)
+- [React Redux Starter Kit](https://github.com/davezuko/react-redux-starter-kit)
+- [Mark Goodyear's Blog](https://markgoodyear.com/2014/01/getting-started-with-gulp/)
+- [Web Starter Kit](https://github.com/google/web-starter-kit)
+
+## License
+
+MIT

SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+This project is currently maintained on the latest `main` branch.
+
+## Reporting a Vulnerability
+
+If you discover a security issue, please open a private security advisory in GitHub when possible.
+If that's not available, open an issue without exploit details and request a private follow-up channel.
+
+Please include:
+
+- A clear description of the impact.
+- Reproduction steps.
+- Suggested mitigations (if known).
+
+## Secure-by-default guidance for generated projects
+
+The generated boilerplate is a learning-focused starter and should be hardened before production use.
+At minimum:
+
+- Keep dependencies updated (`npm audit`, Dependabot/Renovate).
+- Add Content Security Policy headers at deployment time.
+- Review third-party scripts and assets.
+- Use environment-specific configuration and secret management.

_gulp/types/custom.d.ts

@@ -0,0 +1,7 @@
+declare module 'gulp-imagemin';
+declare module 'browserify';
+declare module 'gulp-rename';
+declare module 'gulp-uglify';
+declare module 'vinyl-buffer';
+declare module 'vinyl-source-stream';
+declare module 'gulp-plumber';

_gulp/utils/fileSystem.test.ts

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  copyFile,
+  createDirectory,
+  deleteDirectory,
+  fileExists,
+  writeFile,
+} from './fileSystem';
+
+test('createDirectory/writeFile/fileExists/deleteDirectory lifecycle', () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'wlk-'));
+  const nestedDir = path.join(tmpRoot, 'src', 'sass');
+  const filePath = path.join(nestedDir, 'main.sass');
+
+  createDirectory(nestedDir);
+  writeFile(filePath, 'body\n  color: #222');
+
+  assert.equal(fileExists(nestedDir), true);
+  assert.equal(fileExists(filePath), true);
+
+  deleteDirectory(path.join(tmpRoot, 'src'));
+  assert.equal(fileExists(path.join(tmpRoot, 'src')), false);
+
+  deleteDirectory(tmpRoot);
+});
+
+test('copyFile copies source content into destination path', () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'wlk-copy-'));
+  const sourceDir = path.join(tmpRoot, 'source');
+  const targetDir = path.join(tmpRoot, 'target');
+
+  createDirectory(sourceDir);
+  createDirectory(targetDir);
+
+  const sourceFile = path.join(sourceDir, 'normalize.scss');
+  const destFile = path.join(targetDir, '_normalize.scss');
+  const content = 'html { line-height: 1.15; }';
+
+  writeFile(sourceFile, content);
+  copyFile(sourceFile, destFile);
+
+  assert.equal(fs.readFileSync(destFile, 'utf8'), content);
+
+  deleteDirectory(tmpRoot);
+});

package.json

@@ -5,9 +5,11 @@
   "main": "gulpfile.js",
   "type": "commonjs",
   "scripts": {
-    "postinstall": "ts-node _gulp/gulpSetup.ts",
+    "init": "ts-node _gulp/gulpSetup.ts",
     "start": "NODE_OPTIONS=--no-deprecation gulp",
-    "build": "NODE_OPTIONS=--no-deprecation gulp build"
+    "build": "NODE_OPTIONS=--no-deprecation gulp build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test -r ts-node/register _gulp/**/*.test.ts"
   },
   "author": "Raniro Coelho",
   "license": "MIT",