starter-structure-cli 0.2.0 → 0.2.2

package/README.md

@@ -1,92 +1,359 @@
 # starter-structure-cli
 
-Scaffold your own starter templates from a stack combination such as `react vite ts tailwind express prisma mysql`, `nextjs tailwind mongoose mongodb`, or `vue vite ts tailwind express mongoose`.
+CLI for scaffolding starter projects from stack-based templates.
 
-The CLI discovers templates directly from your local `templates/` folder, so you only maintain the template code once. Naming the template folder with stack tokens is enough for the generator to match it.
+It lets you generate projects by template name or by natural stack combinations such as `react vite ts tailwind express prisma mysql`.
 
-## Template layout
+## What It Generates
 
-Put each starter inside:
+The package currently ships templates in these categories:
 
-```text
-templates/
-  fullstack/
-    react-vite-ts-tailwind-express-prisma-mysql/
-    react-vite-ts-tailwind-express-sequelize-mysql/
-    nextjs-tailwind-mongoose-mongodb/
-  single/
-    react-vite-ts-tailwind/
-    vue-vite-ts-tailwind/
-  backend-only/
-    express-mongoose-jwt/
-  monorepo-client-server/
-    react-vite-ts-express-mongoose/
-  monorepo-turbo-pnpm/
-    nextjs-api-express-prisma/
-```
+- `backend-only`
+- `frontend-only`
+- `single`
+- `fullstack`
+- `monorepo-client-server`
+- `monorepo-turbo-pnpm`
 
-Your folder names become the searchable stack tokens.
+Generated templates come from [template-sources](./template-sources). The [templates](./templates) folder is build output and should not be edited by hand.
 
-## Usage
+## Install And Run
 
-Interactive:
+Use it directly with `npx`:
 
 ```bash
 npx starter-structure-cli my-app
 ```
 
-Direct stack query:
+Or install it globally:
 
 ```bash
-npx starter-structure-cli my-pos react vite ts tailwind express sequelize mysql
+npm install -g starter-structure-cli
+starter-structure-cli my-app
 ```
 
-With explicit flags:
+## Quick Start
+
+Interactive mode:
 
 ```bash
-npx starter-structure-cli my-saas --category fullstack --frontend react --backend express --orm prisma --database mysql --styling tailwind
+npx starter-structure-cli my-app
 ```
 
 Exact template:
 
 ```bash
-npx starter-structure-cli my-gym --template fullstack/react-vite-ts-tailwind-express-sequelize-mysql
+npx starter-structure-cli my-app --template fullstack/react-vite-ts-tailwind-express-prisma-mysql
+```
+
+Stack query:
+
+```bash
+npx starter-structure-cli my-app react vite ts tailwind express prisma mysql
+```
+
+Natural language style query:
+
+```bash
+npx starter-structure-cli my-app reactjs tailwind css nodejs prisma mysql
 ```
 
-List discovered templates:
+List all templates:
 
 ```bash
 npx starter-structure-cli --list
 ```
 
-## Supported filters
+## How Template Matching Works
+
+You can select templates in three ways:
+
+1. Interactive prompts
+2. Exact template path with `--template`
+3. Stack tokens like `react vite ts tailwind`
+
+The matcher also normalizes common aliases:
+
+- `reactjs` -> `react`
+- `vuejs` -> `vue`
+- `next` -> `nextjs`
+- `typescript` -> `ts`
+- `javascript` -> `js`
+- `tailwindcss` -> `tailwind`
+
+It ignores filler words such as `css`, `app`, `project`, `template`, and `with`.
+
+If both JavaScript and TypeScript variants exist for the same stack, the CLI prefers TypeScript unless you pass `--language js`.
+
+## Common Commands
+
+Choose category and features:
+
+```bash
+npx starter-structure-cli my-app --category fullstack --frontend react --backend express --orm prisma --database mysql
+```
+
+Force JavaScript:
+
+```bash
+npx starter-structure-cli my-app react vite tailwind --language js
+```
+
+Force TypeScript:
+
+```bash
+npx starter-structure-cli my-app react vite tailwind --language ts
+```
+
+Skip prompts when the match is already clear:
+
+```bash
+npx starter-structure-cli my-app react vite ts tailwind -y
+```
+
+Install dependencies immediately:
+
+```bash
+npx starter-structure-cli my-app react vite ts tailwind --install
+```
+
+## CLI Options
+
+```text
+-h, --help
+--list
+-y, --yes
+--install
+--no-install
+-p, --package-manager npm | pnpm | yarn
+-c, --category fullstack | frontend-only | single | backend-only | monorepo | turbo
+-t, --template <category/slug>
+--stack, --combo "<tokens>"
+--frontend react | nextjs | vue
+--backend express | nestjs | fastify
+--styling tailwind | shadcn
+--orm prisma | mongoose | sequelize
+--database mongodb | mysql | postgres
+--auth jwt | nextauth
+--language ts | js
+```
+
+## Current Template Catalog
+
+```text
+backend-only/
+  express-mongoose-jwt
+  express-prisma-mysql-jwt
+  express-prisma-mysql-jwt-ts
+
+frontend-only/
+  react-admin-dashboard
+
+single/
+  nextjs-tailwind
+  nextjs-ts-tailwind
+  react-vite-tailwind
+  react-vite-ts-tailwind
+  react-vite-shadcn-tailwind
+  react-vite-ts-shadcn-tailwind
+  react-vite-tailwind-landing
+  react-vite-ts-tailwind-landing
+  vue-vite-tailwind
+  vue-vite-ts-tailwind
+
+fullstack/
+  nextjs-tailwind-mongoose-mongodb
+  nextjs-tailwind-nextauth-prisma
+  nextjs-tailwind-prisma-mysql
+  nextjs-tailwind-prisma-postgres
+  react-vite-ts-tailwind-express-mongoose
+  react-vite-ts-tailwind-express-prisma-mysql
+  react-vite-ts-tailwind-express-prisma-postgres
+  react-vite-ts-tailwind-express-sequelize-mysql
+  vue-vite-ts-tailwind-express-mongoose
+  vue-vite-ts-tailwind-express-prisma-mysql
+
+monorepo-client-server/
+  nextjs-express-prisma
+  react-vite-ts-express-mongoose
+  react-vite-ts-express-prisma
+  vue-vite-ts-express-mongoose
+
+monorepo-turbo-pnpm/
+  nextjs-api-express-prisma
+  nextjs-api-nestjs-prisma
+  react-vite-api-express-mongoose
+```
+
+## Generated Project Structure
+
+Depending on the chosen template, generated projects may look like:
+
+Fullstack:
+
+```text
+my-app/
+  client/
+  server/
+```
+
+Client/server monorepo:
+
+```text
+my-app/
+  apps/
+    client/
+    server/
+```
+
+Turbo monorepo:
+
+```text
+my-app/
+  apps/
+    web/
+    api/
+```
+
+Many templates now include deeper folder scaffolding with starter `index.tsx` files for modules such as components, routes, views, hooks, services, controllers, and data folders.
+
+## Placeholder Replacement
+
+During generation the CLI replaces `__APP_NAME__` inside:
 
-- `--category`: `fullstack`, `frontend-only`, `single`, `backend-only`, `monorepo`, `turbo`
-- `--frontend`: `react`, `nextjs`, `vue`
-- `--backend`: `express`, `nestjs`, `fastify`
-- `--styling`: `tailwind`, `shadcn`
-- `--orm`: `prisma`, `mongoose`, `sequelize`
-- `--database`: `mongodb`, `mysql`, `postgres`
-- `--auth`: `jwt`, `nextauth`
-- `--language`: `ts`, `js`
+- file contents
+- file names
+- folder names
 
-## Placeholder replacement
+## For Template Authors
 
-The CLI replaces `__APP_NAME__` in copied file contents and file/folder names.
+Source of truth:
+
+```text
+template-sources/
+  bases/
+  layers/
+  presets/
+  components/
+```
+
+Build output:
+
+```text
+templates/
+```
 
-## Publish to npm
+Workflow:
+
+1. Edit files in `template-sources/`
+2. Generate architecture stubs if needed
+3. Build templates
+4. Validate templates
+
+Commands:
 
 ```bash
 npm install
-npm publish
+npm run build:architecture-stubs
+npm run build:templates
+npm run check:templates
+node ./bin/starter-structure-cli.js --list
+```
+
+## Reusable Source System
+
+Templates are composed from:
+
+- `bases`: shared starter files
+- `layers`: stack-specific or architecture-specific additions
+- `presets`: mapping files that define final output paths
+
+This keeps authored files small and lets multiple templates share the same structure blocks.
+
+## Includes In Text Files
+
+Text files in `template-sources/` can include reusable snippets:
+
+```text
+{{ include: components/readme/getting-started-vite.md }}
+```
+
+Relative includes also work:
+
+```text
+{{ include: ./shared-snippet.md }}
 ```
 
-`prepack` validates that every template directory contains at least one file. This prevents publishing a package that ships no starter templates.
+## Publishing
 
-## Development
+Before publishing:
 
 ```bash
 npm install
-node ./scripts/check-templates.js
+npm run build:architecture-stubs
+npm run build:templates
+npm run check:templates
 node ./bin/starter-structure-cli.js --list
+npm pack --dry-run
+```
+
+Publish locally:
+
+```bash
+npm publish
+```
+
+For GitHub Actions publishing, configure `NPM_TOKEN` and make sure the token allows publish access.
+
+## How To Check Usage
+
+Important: npm does not give you true unique user counts. What you can measure reliably is download count.
+
+Ways to check usage:
+
+1. Open the npm package page and look at weekly downloads.
+2. Run the local download stats script:
+
+```bash
+npm run stats:downloads
 ```
+
+You can also check another package name:
+
+```bash
+node ./scripts/check-package-usage.js starter-structure-cli
+```
+
+The script prints:
+
+- last week downloads
+- last month downloads
+- package page URL
+
+If you want deeper analytics beyond downloads, use:
+
+- GitHub traffic for repo clones and views
+- a custom API or telemetry endpoint in the CLI
+- issue counts, stars, and dependent repos as secondary signals
+
+## Notes About User Counting
+
+Download count is not the same as:
+
+- unique developers
+- unique companies
+- active projects
+- repeat usage
+
+One developer can download many times, and CI pipelines can also increase the count.
+
+## Development Notes
+
+- Node.js `18+` is required
+- `templates/` is generated output
+- avoid editing generated templates directly
+- use `npm run build:templates` after changing presets, bases, or layers
+
+## License
+
+MIT

package/bin/starter-structure-cli.js

@@ -4,7 +4,6 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
 
 import {
   cancel,
@@ -17,10 +16,7 @@ import {
   text
 } from "@clack/prompts";
 import pc from "picocolors";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const templatesRoot = path.resolve(__dirname, "..", "templates");
+import { ensureTemplatesReady, templatesRoot } from "../lib/template-builder.js";
 
 const CATEGORY_LABELS = {
   fullstack: "Fullstack",
@@ -140,8 +136,10 @@ const TOKEN_ALIASES = {
   next: "nextjs",
   "next-js": "nextjs",
   reactjs: "react",
+  "react-js": "react",
   "react.js": "react",
   vuejs: "vue",
+  "vue-js": "vue",
   "vue.js": "vue",
   tailwindcss: "tailwind",
   "tailwind-css": "tailwind",
@@ -150,10 +148,32 @@ const TOKEN_ALIASES = {
   postgresql: "postgres",
   mongo: "mongodb",
   mongodb: "mongodb",
+  node: "backend",
+  nodejs: "backend",
+  "node-js": "backend",
+  mono: "monorepo",
   turborepo: "turbo",
   monorepo: "monorepo"
 };
 
+const NOISE_TOKENS = new Set([
+  "and",
+  "app",
+  "apps",
+  "application",
+  "boilerplate",
+  "css",
+  "database",
+  "db",
+  "for",
+  "project",
+  "repo",
+  "stack",
+  "starter",
+  "template",
+  "with"
+]);
+
 const SUPPORTED_PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn"]);
 
 function normalizeToken(value) {
@@ -166,7 +186,12 @@ function normalizeToken(value) {
     .replace(/-+/g, "-")
     .replace(/^-|-$/g, "");
 
-  return TOKEN_ALIASES[cleaned] ?? cleaned;
+  const normalized = TOKEN_ALIASES[cleaned] ?? cleaned;
+  if (!normalized || NOISE_TOKENS.has(normalized)) {
+    return "";
+  }
+
+  return normalized;
 }
 
 function tokenize(value) {
@@ -309,6 +334,10 @@ function resolveCategories(input) {
 function addDerivedTokens(tokenSet, category) {
   tokenSet.add(category);
 
+  if (!tokenSet.has("ts") && !tokenSet.has("js")) {
+    tokenSet.add("js");
+  }
+
   if (category === "fullstack") {
     tokenSet.add("frontend");
     tokenSet.add("backend");
@@ -658,6 +687,45 @@ function getAvailableFeatureValues(templates, group) {
   ];
 }
 
+function hasExplicitLanguageSelection(comboTokens) {
+  return comboTokens.includes("ts") || comboTokens.includes("js");
+}
+
+function getComparableTemplateSignature(template) {
+  return JSON.stringify({
+    category: template.category,
+    frontend: template.features.frontend,
+    frontendTool: template.features.frontendTool,
+    styling: template.features.styling,
+    backend: template.features.backend,
+    orm: template.features.orm,
+    database: template.features.database,
+    auth: template.features.auth
+  });
+}
+
+function preferTypeScriptCandidates(templates, comboTokens) {
+  if (hasExplicitLanguageSelection(comboTokens) || templates.length <= 1) {
+    return templates;
+  }
+
+  const languageValues = new Set(
+    templates.map((template) => template.features.language).filter(Boolean)
+  );
+
+  if (!languageValues.has("ts") || !languageValues.has("js")) {
+    return templates;
+  }
+
+  const signatures = new Set(templates.map(getComparableTemplateSignature));
+  if (signatures.size !== 1) {
+    return templates;
+  }
+
+  const tsTemplates = templates.filter((template) => template.features.language === "ts");
+  return tsTemplates.length > 0 ? tsTemplates : templates;
+}
+
 async function chooseCategory(templates) {
   const categories = getAvailableCategories(templates);
 
@@ -684,11 +752,23 @@ async function chooseByFeatures(templates) {
   let candidates = [...templates];
 
   for (const group of FILTER_GROUPS) {
-    const values = getAvailableFeatureValues(candidates, group);
+    const values = getAvailableFeatureValues(candidates, group).sort((left, right) => {
+      if (group.key === "language") {
+        if (left === "ts") return -1;
+        if (right === "ts") return 1;
+      }
+
+      return left.localeCompare(right);
+    });
     if (values.length <= 1) {
       continue;
     }
 
+    const initialValue =
+      group.key === "language" && values.includes("ts")
+        ? "ts"
+        : values[0];
+
     const selection = await select({
       message: `Choose ${group.label.toLowerCase()}:`,
       options: [
@@ -697,7 +777,8 @@ async function chooseByFeatures(templates) {
           value,
           label: humanizeToken(value)
         }))
-      ]
+      ],
+      initialValue
     });
 
     if (isCancel(selection)) {
@@ -776,6 +857,7 @@ function formatTemplateSummary(templates) {
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  ensureTemplatesReady();
   const templates = discoverTemplates(templatesRoot);
 
   if (args.help) {
@@ -784,7 +866,9 @@ async function main() {
   }
 
   if (templates.length === 0) {
-    throw new Error(`No templates found in ${templatesRoot}`);
+    throw new Error(
+      `No templates found in ${templatesRoot}. Build them with "npm run build:templates".`
+    );
   }
 
   if (args.list) {
@@ -824,6 +908,8 @@ async function main() {
     ? [selectedTemplate]
     : filterTemplates(templates, args.category, [...new Set(args.comboTokens)]);
 
+  candidates = preferTypeScriptCandidates(candidates, args.comboTokens);
+
   if (!selectedTemplate && candidates.length === 0) {
     note(
       formatTemplateSummary(templates),
@@ -841,6 +927,7 @@ async function main() {
         return cancel("Cancelled.");
       }
       candidates = candidates.filter((template) => template.category === chosenCategory);
+      candidates = preferTypeScriptCandidates(candidates, args.comboTokens);
     }
 
     if (candidates.length > 1 && args.comboTokens.length === 0) {