create-alistt69-kit 0.3.1 → 0.3.2

package/README.md

@@ -38,6 +38,7 @@ It generates a ready-to-run **React + TypeScript + Webpack** starter with a prac
 | [Stylelint](https://stylelint.io/) | Stylesheet linting               | Optional |
 | [Autoprefixer](https://github.com/postcss/autoprefixer) | Automatic CSS vendor prefixes    | Optional |
 | [React Router](https://reactrouter.com/) | Client-side routing              | Optional |
+| [AGENTS.md](https://agents.md/) | Root instructions file for AI coding agents | Optional |
 | [Puppeteer](https://pptr.dev/) + [serve-handler](https://github.com/vercel/serve-handler) | Static HTML prerender after production build | Optional |
 
 ## 🎯 Why use it?
@@ -166,14 +167,14 @@ npm create alistt69-kit@latest my-app -- --defaults --overwrite
 
 ## ⚙️ CLI options
 
-| Option | Alias  | Description |
-|--------|--------|-------------|
-| `--defaults` | `-def` | Skip prompts, use defaults |
-| `--overwrite` | —      | Overwrite target directory if it exists |
-| `--no-install` | —      | Skip dependency installation |
-| `--features <list>` | —      | Enable specific features (`eslint`, `react-router`, `all`) |
-| `--pm <name>` | —      | Choose package manager (`npm`, `pnpm`, `yarn`) |
-| `--help` | `-h`   | Show help |
+| Option              | Alias  | Description |
+|---------------------|--------|-------------|
+| `--defaults`        | `-def` | Skip prompts, use defaults |
+| `--overwrite`       | —      | Overwrite target directory if it exists |
+| `--no-install`      | —      | Skip dependency installation |
+| `--features <list>` | — | Enable specific features (`agents-md`, `eslint`, `stylelint`, `autoprefixer`, `react-router`, `prerender`) |
+| `--pm <name>`       | —      | Choose package manager (`npm`, `pnpm`, `yarn`) |
+| `--help`            | `-h`   | Show help |
 
 ## 🧪 Default behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-alistt69-kit",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Opinionated React + TypeScript + Webpack project generator by alistt69",
   "keywords": [
     "create",

package/src/core/parse-cli-args.js

@@ -31,7 +31,7 @@ export function formatHelpMessage() {
         '  -def, --defaults             Skip prompts and use defaults',
         '  --overwrite                  Overwrite target directory if it exists',
         '  --no-install                 Do not install dependencies',
-        '  --features <comma-list>      Example: eslint,stylelint,react-router,prerender',
+        '  --features <comma-list>      Example: agents-md,eslint,stylelint,react-router,prerender',
         '  --features all               Enable all features',
         '  --pm <npm|pnpm|yarn>         Package manager',
         '  -h, --help                   Show help',

package/src/core/render-project-readme.js

@@ -150,6 +150,17 @@ function formatProjectStructure(selectedFeatureIds) {
 function formatFeatureSpecificSections({ selectedFeatureIds, packageManager }) {
     const sections = [];
 
+    if (selectedFeatureIds.includes('agents-md')) {
+        sections.push([
+            '## AGENTS.md',
+            '',
+            'When `AGENTS.md` is enabled, the project includes a root instruction file for AI coding agents.',
+            '',
+            '- Base file: `AGENTS.md`',
+            '- Other selected features may append their own sections into this file automatically during scaffolding.',
+        ].join('\n'));
+    }
+
     if (selectedFeatureIds.includes('react-router')) {
         sections.push([
             '## Page generator',

package/src/features/agents-md/files/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Overview
+
+This project was scaffolded with `create-alistt69-kit`.
+
+## Setup
+
+- Install dependencies with the selected package manager.
+- Start dev server with `npm run start`.
+- Type-check with `npm run typecheck`.
+
+## Base stack
+
+- React
+- TypeScript
+- Webpack
+- SCSS Modules
+
+## General rules
+
+- Keep code readable and explicit.
+- Prefer small targeted changes over broad refactors.
+- Do not rename public files or exported symbols unless required.
+- Reuse existing project structure and conventions.
+
+## Validation
+
+Before finishing a task, run the relevant checks available in `package.json`.
+
+## Project structure
+
+- `src/app/` — app bootstrap and providers
+- `src/styles/` — global styles
+- `config/build/` — webpack config parts
+
+<!-- @agents-sections -->

package/src/features/agents-md/index.js

@@ -0,0 +1,14 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { defineFeature } from '../define-feature.js';
+
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDirPath = dirname(currentFilePath);
+
+export const agentsMdFeature = defineFeature({
+    id: 'agents-md',
+    title: 'AGENTS.md',
+    hint: 'Root instructions file for AI coding agents',
+    copyFiles: resolve(currentDirPath, 'files'),
+});

package/src/features/autoprefixer/index.js

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { defineFeature } from '../define-feature.js';
+import { appendAgentsSection } from '../../utils/agents-md.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
@@ -16,4 +17,16 @@ export const autoprefixerFeature = defineFeature({
         },
     },
     copyFiles: resolve(currentDirPath, 'files'),
+    async apply({ projectPath }) {
+        await appendAgentsSection(
+            projectPath,
+            'autoprefixer',
+            `
+                ## CSS compatibility
+                
+                - Vendor prefixing is handled by Autoprefixer.
+                - Do not add manual prefixes unless there is a confirmed need.
+            `,
+        );
+    },
 });

package/src/features/eslint/index.js

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { defineFeature } from '../define-feature.js';
+import { appendAgentsSection } from '../../utils/agents-md.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
@@ -27,4 +28,17 @@ export const eslintFeature = defineFeature({
         },
     },
     copyFiles: resolve(currentDirPath, 'files'),
+    async apply({ projectPath }) {
+        await appendAgentsSection(
+            projectPath,
+            'eslint',
+            `
+                ## ESLint
+                
+                - Lint code with \`npm run lint\`.
+                - Apply safe autofixes with \`npm run lint:fix\`.
+                - Prefer fixing root-cause issues instead of disabling rules.
+            `,
+        );
+    },
 });

package/src/features/index.js

@@ -1,3 +1,4 @@
+import { agentsMdFeature } from './agents-md/index.js';
 import { autoprefixerFeature } from './autoprefixer/index.js';
 import { eslintFeature } from './eslint/index.js';
 import { prerenderFeature } from './prerender/index.js';
@@ -5,6 +6,7 @@ import { reactRouterFeature } from './react-router/index.js';
 import { stylelintFeature } from './stylelint/index.js';
 
 export const features = [
+    agentsMdFeature,
     autoprefixerFeature,
     eslintFeature,
     prerenderFeature,

package/src/features/prerender/index.js

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { defineFeature } from '../define-feature.js';
+import { appendAgentsSection } from '../../utils/agents-md.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
@@ -16,10 +17,25 @@ export const prerenderFeature = defineFeature({
             'serve-handler': '^6.1.6',
         },
         scripts: {
+            build: 'npm run build:assets && npm run prerender',
             'build:assets': 'webpack --env mode=production',
+            'build:prod': 'npm run build',
             prerender: 'node ./scripts/prerender.mjs',
-            build: 'npm run build:assets && npm run prerender',
         },
     },
     copyFiles: resolve(currentDirPath, 'files'),
+    async apply({ projectPath }) {
+        await appendAgentsSection(
+            projectPath,
+            'prerender',
+            `
+                ## Prerender
+                
+                - Production build runs in two steps: \`npm run build:assets\` then \`npm run prerender\`.
+                - Prerender route manifest lives in \`prerender.routes.mjs\`.
+                - Prerender script lives in \`scripts/prerender.mjs\`.
+                - When adding static routes, keep \`prerender.routes.mjs\` updated.
+            `,
+        );
+    },
 });

package/src/features/react-router/index.js

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { defineFeature } from '../define-feature.js';
+import { appendAgentsSection } from '../../utils/agents-md.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
@@ -19,4 +20,18 @@ export const reactRouterFeature = defineFeature({
         },
     },
     copyFiles: resolve(currentDirPath, 'files'),
+    async apply({ projectPath }) {
+        await appendAgentsSection(
+            projectPath,
+            'react-router',
+            `
+                ## React Router
+                
+                - Routing is configured under \`src/app/providers/router/\`.
+                - Route-level pages live in \`src/pages/\`.
+                - Generate a new page with \`npm run generate:page -- <page-name>\`.
+                - Do not remove router marker comments used by the page generator unless you also disable auto-registration.
+            `,
+        );
+    },
 });

package/src/features/stylelint/index.js

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { defineFeature } from '../define-feature.js';
+import { appendAgentsSection } from '../../utils/agents-md.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
@@ -21,4 +22,17 @@ export const stylelintFeature = defineFeature({
         },
     },
     copyFiles: resolve(currentDirPath, 'files'),
+    async apply({ projectPath }) {
+        await appendAgentsSection(
+            projectPath,
+            'stylelint',
+            `
+                ## Stylelint
+                
+                - Lint styles with \`npm run lint:styles\`.
+                - Apply autofixes with \`npm run lint:styles:fix\`.
+                - Keep styles compatible with the existing SCSS modules setup.
+            `,
+        );
+    },
 });

package/src/utils/agents-md.js

@@ -0,0 +1,53 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const AGENTS_MD_PATH = 'AGENTS.md';
+const SECTIONS_MARKER = '<!-- @agents-sections -->';
+
+export function getAgentsMdPath(projectPath) {
+    return resolve(projectPath, AGENTS_MD_PATH);
+}
+
+export async function hasAgentsMd(projectPath) {
+    try {
+        await access(getAgentsMdPath(projectPath));
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
+
+export async function appendAgentsSection(projectPath, sectionKey, content) {
+    if (!(await hasAgentsMd(projectPath))) {
+        return false;
+    }
+
+    const filepath = getAgentsMdPath(projectPath);
+    const fileContent = await readFile(filepath, 'utf8');
+
+    if (fileContent.includes(`<!-- @agents:${sectionKey} -->`)) {
+        return false;
+    }
+
+    const block = [
+        `<!-- @agents:${sectionKey} -->`,
+        content.trim(),
+        `<!-- /@agents:${sectionKey} -->`,
+    ].join('\n');
+
+    let nextContent;
+
+    if (fileContent.includes(SECTIONS_MARKER)) {
+        nextContent = fileContent.replace(
+            SECTIONS_MARKER,
+            `${block}\n\n${SECTIONS_MARKER}`,
+        );
+    } else {
+        const trimmed = fileContent.trimEnd();
+        nextContent = `${trimmed}\n\n${block}\n`;
+    }
+
+    await writeFile(filepath, nextContent, 'utf8');
+
+    return true;
+}