costrix 1.0.0

package/bin/costrix.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const { main } = require("../src/cli");
+
+main().catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`[ERROR] Failed to scaffold project: ${message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "costrix",
+  "version": "1.0.0",
+  "description": "npx initializer for a TypeScript + Webpack + Jest project",
+  "bin": {
+    "costrix": "./bin/costrix.js"
+  },
+  "type": "commonjs",
+  "license": "MIT"
+}

package/src/args.js

@@ -0,0 +1,42 @@
+function parseCliArgs(argv) {
+  const flags = {
+    install: true,
+    dev: true,
+    help: false
+  };
+  let projectArg = "";
+
+  argv.forEach((arg) => {
+    if (arg === "--no-install") {
+      flags.install = false;
+      return;
+    }
+    if (arg === "--no-dev") {
+      flags.dev = false;
+      return;
+    }
+    if (arg === "--help" || arg === "-h") {
+      flags.help = true;
+      return;
+    }
+    if (!arg.startsWith("-") && projectArg === "") {
+      projectArg = arg;
+    }
+  });
+
+  return { projectArg, flags };
+}
+
+function printHelp() {
+  console.log("\nUsage:");
+  console.log("  costrix [app-name] [--no-install] [--no-dev]");
+  console.log("\nFlags:");
+  console.log("  --no-install   Scaffold only, skip npm install");
+  console.log("  --no-dev       Skip auto-starting dev server");
+  console.log("  -h, --help     Show this help message\n");
+}
+
+module.exports = {
+  parseCliArgs,
+  printHelp
+};

package/src/cli.js

@@ -0,0 +1,53 @@
+const path = require("path");
+const { parseCliArgs, printHelp } = require("./args");
+const { askProjectArg } = require("./prompt");
+const { scaffoldProject } = require("./scaffold");
+const { runCommand } = require("./run");
+const { printBanner, logInfo, logWarn, logSuccess, logError } = require("./logger");
+
+async function main() {
+  printBanner();
+
+  const { projectArg: parsedProjectArg, flags } = parseCliArgs(process.argv.slice(2));
+
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  let projectArg = parsedProjectArg;
+  if (!projectArg) {
+    projectArg = await askProjectArg();
+  }
+
+  if (!projectArg) {
+    logError("No app name provided.");
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(process.cwd(), projectArg);
+  logInfo(`Preparing folder ${projectDir}`);
+  logInfo("Generating project files...");
+  scaffoldProject(projectDir, projectArg);
+
+  logSuccess(`Scaffold complete for ${projectArg}`);
+  logInfo(`Options: install=${String(flags.install)} dev=${String(flags.dev)}`);
+
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+
+  if (flags.install) {
+    await runCommand(npmCmd, ["install"], projectDir, "Installing dependencies");
+  } else {
+    logWarn("Skipping dependency installation (--no-install)");
+  }
+
+  if (flags.dev) {
+    await runCommand(npmCmd, ["run", "dev"], projectDir, "Starting development server");
+  } else {
+    logWarn("Skipping development server startup (--no-dev)");
+  }
+}
+
+module.exports = {
+  main
+};

package/src/logger.js

@@ -0,0 +1,66 @@
+const color = {
+  reset: "\x1b[0m",
+  cyan: "\x1b[36m",
+  blue: "\x1b[34m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+  gray: "\x1b[90m"
+};
+
+const paint = (tone, text) => `${color[tone]}${text}${color.reset}`;
+
+function printBanner() {
+  const lines = [
+    "",
+    paint("cyan", " ██████╗ ██████╗ ███████╗████████╗██████╗ ██╗██╗  ██╗"),
+    paint("cyan", "██╔════╝██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██║╚██╗██╔╝"),
+    paint("cyan", "██║     ██║   ██║███████╗   ██║   ██████╔╝██║ ╚███╔╝ "),
+    paint("cyan", "██║     ██║   ██║╚════██║   ██║   ██╔══██╗██║ ██╔██╗ "),
+    paint("cyan", "╚██████╗╚██████╔╝███████║   ██║   ██║  ██║██║██╔╝ ██╗"),
+    paint("cyan", " ╚═════╝ ╚═════╝ ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝"),
+    paint("gray", "Scaffold TypeScript projects with guardrails"),
+    paint("gray", "Created with care by Kaustubh"),
+    ""
+  ];
+  console.log(lines.join("\n"));
+}
+
+const logInfo = (text) => console.log(`${paint("cyan", "ℹ")} ${text}`);
+const logStep = (text) => console.log(`${paint("blue", "🧩")} ${text}`);
+const logSuccess = (text) => console.log(`${paint("green", "✅")} ${text}`);
+const logWarn = (text) => console.log(`${paint("yellow", "⚠️")} ${text}`);
+const logError = (text) => console.error(`${paint("red", "❌")} ${text}`);
+
+function startLoader(label) {
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let index = 0;
+  process.stdout.write(`${paint("cyan", frames[index])} ${label}`);
+
+  const timer = setInterval(() => {
+    index = (index + 1) % frames.length;
+    process.stdout.write(`\r${paint("cyan", frames[index])} ${label}`);
+  }, 90);
+
+  const stop = (icon, tone, text) => {
+    clearInterval(timer);
+    process.stdout.write(`\r${paint(tone, icon)} ${text}\n`);
+  };
+
+  return {
+    done: (text) => stop("✅", "green", text),
+    fail: (text) => stop("❌", "red", text),
+    info: (text) => stop("ℹ", "cyan", text)
+  };
+}
+
+module.exports = {
+  printBanner,
+  logInfo,
+  logStep,
+  logSuccess,
+  logWarn,
+  logError,
+  startLoader
+};

package/src/prompt.js

@@ -0,0 +1,19 @@
+const readline = require("readline");
+
+function askProjectArg() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    rl.question("Enter app name (folder): ", (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+module.exports = {
+  askProjectArg
+};

package/src/run.js

@@ -0,0 +1,55 @@
+const { spawn } = require("child_process");
+const { logInfo, logError, startLoader } = require("./logger");
+
+function spawnWithOptions(command, args, cwd, useShell) {
+  return spawn(command, args, {
+    cwd,
+    stdio: "inherit",
+    shell: useShell
+  });
+}
+
+function runCommand(command, args, cwd, label) {
+  const loader = startLoader(label);
+
+  const execute = (useShell) =>
+    new Promise((resolve, reject) => {
+      const child = spawnWithOptions(command, args, cwd, useShell);
+
+      child.on("error", (error) => {
+        reject(error);
+      });
+
+      child.on("close", (code) => {
+        if (code === 0) {
+          resolve();
+          return;
+        }
+        reject(new Error(`${label} failed with exit code ${String(code)}`));
+      });
+    });
+
+  return execute(false)
+    .then(() => {
+      loader.done(`${label} complete`);
+    })
+    .catch((error) => {
+      if (process.platform === "win32" && error && error.code === "EINVAL") {
+        loader.info(`${label}: retrying with Windows shell fallback...`);
+        logInfo(`${label}: retrying with Windows shell fallback...`);
+        return execute(true).then(() => {
+          loader.done(`${label} complete`);
+        });
+      }
+      throw error;
+    })
+    .catch((error) => {
+      loader.fail(`${label} failed`);
+      logError(`${label} failed: ${error.message}`);
+      throw error;
+    });
+}
+
+module.exports = {
+  runCommand
+};

package/src/scaffold.js

@@ -0,0 +1,83 @@
+const fs = require("fs");
+const path = require("path");
+const { logWarn, logStep } = require("./logger");
+const { toPackageName } = require("./utils");
+
+const TEMPLATE_ROOT = path.resolve(__dirname, "..", "templates");
+
+function ensureDirForFile(filePath) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeTextFileSafe(targetPath, content) {
+  if (fs.existsSync(targetPath)) {
+    return false;
+  }
+
+  ensureDirForFile(targetPath);
+  fs.writeFileSync(targetPath, content, "utf8");
+  return true;
+}
+
+function copyFileSafe(sourcePath, targetPath) {
+  if (fs.existsSync(targetPath)) {
+    return false;
+  }
+
+  ensureDirForFile(targetPath);
+  fs.copyFileSync(sourcePath, targetPath);
+  return true;
+}
+
+function renderFile(relativePath, sourceContent, appName) {
+  if (relativePath === "package.json") {
+    const parsed = JSON.parse(sourceContent);
+    parsed.name = toPackageName(appName);
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+  }
+
+  return sourceContent;
+}
+
+function copyTemplateDir(templateDir, projectDir, appName, rootTemplateDir) {
+  const entries = fs.readdirSync(templateDir, { withFileTypes: true });
+
+  entries.forEach((entry) => {
+    const sourcePath = path.join(templateDir, entry.name);
+    const relativePath = path.relative(rootTemplateDir, sourcePath);
+    const targetPath = path.join(projectDir, relativePath);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(targetPath, { recursive: true });
+      copyTemplateDir(sourcePath, projectDir, appName, rootTemplateDir);
+      return;
+    }
+
+    const normalizedRelativePath = relativePath.replace(/\\/g, "/");
+    let created = false;
+    if (normalizedRelativePath === "package.json") {
+      const rawContent = fs.readFileSync(sourcePath, "utf8");
+      const content = renderFile(normalizedRelativePath, rawContent, appName);
+      created = writeTextFileSafe(targetPath, content);
+    } else {
+      created = copyFileSafe(sourcePath, targetPath);
+    }
+
+    if (created) {
+      logStep(`Created ${normalizedRelativePath}`);
+      return;
+    }
+
+    logWarn(`Skipped ${normalizedRelativePath} (already exists)`);
+  });
+}
+
+function scaffoldProject(projectDir, appName) {
+  fs.mkdirSync(projectDir, { recursive: true });
+  copyTemplateDir(TEMPLATE_ROOT, projectDir, appName, TEMPLATE_ROOT);
+}
+
+module.exports = {
+  scaffoldProject
+};

package/src/utils.js

@@ -0,0 +1,16 @@
+function toPackageName(input) {
+  const normalized = String(input || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[_\s]+/g, "-")
+    .replace(/[^a-z0-9.-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "");
+
+  return normalized || "my-costrix-app";
+}
+
+module.exports = {
+  toPackageName
+};

package/templates/eslint.config.cjs

@@ -0,0 +1,69 @@
+const js = require("@eslint/js");
+const globals = require("globals");
+const tsParser = require("@typescript-eslint/parser");
+const tsPlugin = require("@typescript-eslint/eslint-plugin");
+
+module.exports = [
+  {
+    ignores: ["dist/**", "coverage/**", "node_modules/**"]
+  },
+  js.configs.recommended,
+  {
+    files: ["src/**/*.ts", "tests/**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: ["./tsconfig.eslint.json"],
+        tsconfigRootDir: __dirname,
+        ecmaVersion: "latest",
+        sourceType: "module"
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.jest
+      }
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin
+    },
+    rules: {
+      ...tsPlugin.configs.recommended.rules,
+      ...tsPlugin.configs["recommended-type-checked"].rules,
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unsafe-assignment": "error",
+      "@typescript-eslint/no-unsafe-argument": "error",
+      "@typescript-eslint/no-unsafe-member-access": "error",
+      "@typescript-eslint/no-unsafe-call": "error",
+      "@typescript-eslint/no-unsafe-return": "error",
+      "@typescript-eslint/explicit-function-return-type": [
+        "error",
+        { allowExpressions: true, allowTypedFunctionExpressions: true }
+      ],
+      "@typescript-eslint/consistent-type-imports": ["error", { prefer: "type-imports" }],
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": "error",
+      "@typescript-eslint/strict-boolean-expressions": "error",
+      "@typescript-eslint/switch-exhaustiveness-check": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_", caughtErrorsIgnorePattern: "^_" }
+      ],
+      "@typescript-eslint/require-await": "error",
+      "no-console": ["error", { allow: ["warn", "error"] }]
+    }
+  },
+  {
+    files: ["*.js", "*.cjs", "scripts/**/*.cjs"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "commonjs",
+      globals: {
+        ...globals.node
+      }
+    },
+    rules: {
+      "no-console": "off"
+    }
+  }
+];

package/templates/jest.config.cjs

@@ -0,0 +1,20 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "jsdom",
+  roots: ["<rootDir>/tests"],
+  collectCoverage: true,
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts"],
+  coverageDirectory: "coverage",
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100
+    }
+  },
+  moduleNameMapper: {
+    "\\.module\\.css$": "<rootDir>/tests/styleMock.ts"
+  }
+};

package/templates/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "my-costrix-app",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "predev": "node scripts/banner.cjs dev",
+    "dev": "webpack serve --mode development",
+    "prebuild": "node scripts/banner.cjs build",
+    "build": "npm run prod",
+    "preprod": "node scripts/banner.cjs prod",
+    "prod": "npm run lint && npm run typecheck && npm run test:ci && webpack --mode production",
+    "test": "jest",
+    "test:ci": "jest --coverage",
+    "lint": "eslint . --ext .ts,.js,.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "@typescript-eslint/eslint-plugin": "^8.18.1",
+    "@typescript-eslint/parser": "^8.18.1",
+    "copy-webpack-plugin": "^13.0.0",
+    "css-loader": "^7.1.2",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "globals": "^15.0.0",
+    "html-webpack-plugin": "^5.6.3",
+    "jest": "^30.0.0",
+    "jest-environment-jsdom": "^30.0.0",
+    "mini-css-extract-plugin": "^2.9.2",
+    "style-loader": "^4.0.0",
+    "ts-jest": "^29.4.6",
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.7.2",
+    "webpack": "^5.97.1",
+    "webpack-cli": "^6.0.1",
+    "webpack-dev-server": "^5.2.0"
+  }
+}

package/templates/public/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Costrix TypeScript starter template with strict guardrails for linting, testing, and production builds." />
+    <meta name="robots" content="index,follow" />
+    <meta name="theme-color" content="#0b1020" />
+    <meta name="application-name" content="Costrix App" />
+
+    <link rel="icon" href="favicon.ico" sizes="any" />
+    <link rel="apple-touch-icon" href="favicon.ico" />
+
+    <meta property="og:type" content="website" />
+    <meta property="og:title" content="Costrix TypeScript Starter" />
+    <meta property="og:description" content="Bootstrap a strict TypeScript project with production-ready guardrails." />
+    <meta property="og:image" content="ogimage.jpg" />
+    <meta property="og:image:alt" content="Costrix TypeScript starter preview" />
+
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="Costrix TypeScript Starter" />
+    <meta name="twitter:description" content="Bootstrap a strict TypeScript project with production-ready guardrails." />
+    <meta name="twitter:image" content="ogimage.jpg" />
+
+    <title>Costrix App</title>
+  </head>
+  <body></body>
+</html>

package/templates/scripts/banner.cjs

@@ -0,0 +1,26 @@
+const mode = process.argv[2] || "run";
+
+const color = {
+  reset: "\x1b[0m",
+  cyan: "\x1b[36m",
+  magenta: "\x1b[35m",
+  gray: "\x1b[90m"
+};
+
+const paint = (tone, text) => `${color[tone]}${text}${color.reset}`;
+
+const lines = [
+  "",
+  paint("cyan", " ██████╗ ██████╗ ███████╗████████╗██████╗ ██╗██╗  ██╗"),
+  paint("cyan", "██╔════╝██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██║╚██╗██╔╝"),
+  paint("cyan", "██║     ██║   ██║███████╗   ██║   ██████╔╝██║ ╚███╔╝ "),
+  paint("cyan", "██║     ██║   ██║╚════██║   ██║   ██╔══██╗██║ ██╔██╗ "),
+  paint("cyan", "╚██████╗╚██████╔╝███████║   ██║   ██║  ██║██║██╔╝ ██╗"),
+  paint("cyan", " ╚═════╝ ╚═════╝ ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝"),
+  paint("magenta", `Running: ${mode.toUpperCase()}`),
+  paint("gray", "TypeScript + Guardrails + Webpack"),
+  paint("gray", "Crafted with care by Kaustubh"),
+  ""
+];
+
+console.log(lines.join("\n"));

package/templates/src/App.module.css

@@ -0,0 +1,339 @@
+:global(*) {
+  -webkit-box-sizing: border-box;
+  -moz-box-sizing: border-box;
+  box-sizing: border-box;
+}
+
+:global(body) {
+  margin: 0;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-family: "Segoe UI", "Trebuchet MS", sans-serif;
+  color: #e7ecff;
+  background: radial-gradient(circle at 20% 10%, #1c2f66 0%, #0b1020 42%, #070a14 100%);
+  overflow-x: hidden;
+}
+
+.app {
+  min-height: 100vh;
+  display: -webkit-box;
+  display: -moz-box;
+  display: -ms-flexbox;
+  display: flex;
+  -webkit-box-align: center;
+  -moz-box-align: center;
+  -ms-flex-align: center;
+  align-items: center;
+  -webkit-box-pack: center;
+  -moz-box-pack: center;
+  -ms-flex-pack: center;
+  justify-content: center;
+  padding: 1.2rem;
+}
+
+@supports (display: grid) and (place-items: center) {
+  .app {
+    display: grid;
+    place-items: center;
+  }
+}
+
+.page {
+  position: relative;
+  width: 100%;
+  max-width: 980px;
+  overflow: hidden;
+  border: 1px solid rgba(163, 179, 255, 0.28);
+  -webkit-border-radius: 20px;
+  -moz-border-radius: 20px;
+  border-radius: 20px;
+  background: linear-gradient(155deg, rgba(19, 29, 59, 0.9), rgba(16, 20, 40, 0.92));
+  -webkit-box-shadow: 0 26px 60px rgba(0, 0, 0, 0.45);
+  -moz-box-shadow: 0 26px 60px rgba(0, 0, 0, 0.45);
+  box-shadow: 0 26px 60px rgba(0, 0, 0, 0.45);
+}
+
+.ambientGlowOne,
+.ambientGlowTwo {
+  position: absolute;
+  border-radius: 999px;
+  filter: blur(2px);
+  pointer-events: none;
+}
+
+.ambientGlowOne {
+  top: -90px;
+  left: -100px;
+  width: 260px;
+  height: 260px;
+  background: radial-gradient(circle, rgba(90, 231, 255, 0.48), rgba(90, 231, 255, 0));
+  animation: floatA 7s ease-in-out infinite;
+}
+
+.ambientGlowTwo {
+  right: -120px;
+  bottom: -120px;
+  width: 300px;
+  height: 300px;
+  background: radial-gradient(circle, rgba(255, 143, 112, 0.42), rgba(255, 143, 112, 0));
+  animation: floatB 8s ease-in-out infinite;
+}
+
+.gridOverlay {
+  position: absolute;
+  inset: 0;
+  opacity: 0.22;
+  background-image:
+    linear-gradient(rgba(130, 145, 213, 0.3) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(130, 145, 213, 0.3) 1px, transparent 1px);
+  background-size: 34px 34px;
+  pointer-events: none;
+}
+
+@supports ((-webkit-mask-image: radial-gradient(circle at center, black 40%, transparent 100%)) or
+    (mask-image: radial-gradient(circle at center, black 40%, transparent 100%))) {
+  .gridOverlay {
+    -webkit-mask-image: radial-gradient(circle at center, black 40%, transparent 100%);
+    mask-image: radial-gradient(circle at center, black 40%, transparent 100%);
+  }
+}
+
+.contentShell {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  grid-template-columns: 1.1fr 0.9fr;
+  gap: 1.2rem;
+  padding: 1.4rem;
+}
+
+.leftCol,
+.rightCol {
+  border: 1px solid rgba(180, 190, 255, 0.2);
+  -webkit-border-radius: 14px;
+  -moz-border-radius: 14px;
+  border-radius: 14px;
+  background: rgba(7, 12, 30, 0.55);
+  padding: 1rem;
+}
+
+@supports ((-webkit-backdrop-filter: blur(8px)) or (backdrop-filter: blur(8px))) {
+  .leftCol,
+  .rightCol {
+    -webkit-backdrop-filter: blur(8px);
+    backdrop-filter: blur(8px);
+  }
+}
+
+.leftCol {
+  animation: rise 650ms ease-out both;
+}
+
+.rightCol {
+  animation: rise 650ms 120ms ease-out both;
+}
+
+.header {
+  margin-bottom: 1rem;
+}
+
+.pill {
+  margin: 0;
+  width: fit-content;
+  padding: 0.26rem 0.7rem;
+  border: 1px solid rgba(134, 223, 255, 0.6);
+  -webkit-border-radius: 999px;
+  -moz-border-radius: 999px;
+  border-radius: 999px;
+  color: #8fe4ff;
+  font-size: 0.78rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.title {
+  margin: 0.75rem 0 0;
+  color: #f4f6ff;
+  font-size: clamp(1.45rem, 3.2vw, 2.2rem);
+  line-height: 1.12;
+}
+
+.subtitle {
+  margin: 0.75rem 0 0;
+  color: #cfd8ff;
+  line-height: 1.55;
+  max-width: 58ch;
+}
+
+.sectionTitle {
+  margin: 0;
+  margin-top: 0.9rem;
+  color: #e5eaff;
+  font-size: 1rem;
+}
+
+.guardrailList,
+.commandList {
+  margin: 0.8rem 0 0;
+  padding: 0;
+  list-style: none;
+  display: grid;
+  gap: 0.62rem;
+}
+
+.guardrailItem {
+  border: 1px solid rgba(179, 189, 255, 0.24);
+  -webkit-border-radius: 10px;
+  -moz-border-radius: 10px;
+  border-radius: 10px;
+  padding: 0.8rem;
+  background: linear-gradient(145deg, rgba(17, 25, 50, 0.8), rgba(13, 18, 37, 0.86));
+  animation: reveal 550ms ease both;
+}
+
+.guardrailItem:nth-child(2) {
+  animation-delay: 120ms;
+}
+
+.guardrailItem:nth-child(3) {
+  animation-delay: 220ms;
+}
+
+.guardrailTitle {
+  margin: 0;
+  color: #f0f4ff;
+  font-size: 0.95rem;
+}
+
+.guardrailDetail {
+  margin: 0.35rem 0 0;
+  color: #bec8ef;
+  line-height: 1.45;
+  font-size: 0.92rem;
+}
+
+.commandItem {
+  border: 1px solid rgba(130, 151, 255, 0.35);
+  -webkit-border-radius: 10px;
+  -moz-border-radius: 10px;
+  border-radius: 10px;
+  padding: 0.58rem 0.72rem;
+  font-family: "Consolas", "Courier New", monospace;
+  font-size: 0.92rem;
+  color: #d8e0ff;
+  background: rgba(24, 33, 67, 0.72);
+}
+
+.docsButton {
+  display: inline-block;
+  margin-top: 0.9rem;
+  padding: 0.6rem 0.78rem;
+  border: 1px solid rgba(116, 228, 255, 0.48);
+  -webkit-border-radius: 10px;
+  -moz-border-radius: 10px;
+  border-radius: 10px;
+  color: #9feeff;
+  background: rgba(9, 24, 44, 0.6);
+  text-decoration: none;
+  font-weight: 600;
+  transition: transform 180ms ease, background-color 180ms ease, border-color 180ms ease;
+}
+
+.docsButton:hover {
+  transform: translateY(-1px);
+  border-color: rgba(116, 228, 255, 0.8);
+  background: rgba(12, 34, 61, 0.85);
+}
+
+.noteCard {
+  margin-top: 1rem;
+  border: 1px solid rgba(160, 177, 255, 0.24);
+  -webkit-border-radius: 10px;
+  -moz-border-radius: 10px;
+  border-radius: 10px;
+  padding: 0.85rem;
+  background: linear-gradient(170deg, rgba(22, 27, 53, 0.88), rgba(15, 18, 35, 0.86));
+}
+
+.noteTitle {
+  margin: 0;
+  color: #f0f4ff;
+  font-size: 0.95rem;
+}
+
+.noteText {
+  margin: 0.4rem 0 0;
+  color: #c2cbef;
+  line-height: 1.5;
+  font-size: 0.9rem;
+}
+
+.footer {
+  margin: 1rem 0 0;
+  color: #9cabde;
+  font-size: 0.9rem;
+}
+
+@keyframes rise {
+  from {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes reveal {
+  from {
+    opacity: 0;
+    transform: translateY(8px) scale(0.98);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes floatA {
+  0%,
+  100% {
+    transform: translate(0, 0);
+  }
+
+  50% {
+    transform: translate(14px, 10px);
+  }
+}
+
+@keyframes floatB {
+  0%,
+  100% {
+    transform: translate(0, 0);
+  }
+
+  50% {
+    transform: translate(-12px, -10px);
+  }
+}
+
+@media (max-width: 860px) {
+  .contentShell {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 640px) {
+  .page {
+    -webkit-border-radius: 14px;
+    -moz-border-radius: 14px;
+    border-radius: 14px;
+  }
+
+  .contentShell {
+    padding: 0.9rem;
+  }
+}

package/templates/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module "*.module.css" {
+  const classes: Readonly<Record<string, string>>;
+  export default classes;
+}

package/templates/src/index.ts

@@ -0,0 +1,155 @@
+import * as stylesImport from "./App.module.css";
+
+export type GuardrailItem = {
+  readonly title: string;
+  readonly detail: string;
+};
+
+type StylesMap = Readonly<Record<string, string>>;
+
+export const DEFAULT_GUARDRAILS: ReadonlyArray<GuardrailItem> = [
+  { title: "Strict TypeScript", detail: "Compiler options are strict and tuned for safer refactors." },
+  { title: "Strict ESLint", detail: "Linting blocks unsafe patterns and explicit any usage." },
+  { title: "Quality Build", detail: "Production build runs lint, typecheck, tests, and coverage gates." }
+];
+
+const toStringMap = (source: Record<string, unknown>): StylesMap => {
+  const entries = Object.entries(source).filter((entry): entry is [string, string] => typeof entry[1] === "string");
+  return Object.fromEntries(entries);
+};
+
+export const resolveStyles = (source: unknown): StylesMap => {
+  if (source === null || typeof source !== "object") {
+    return {};
+  }
+
+  const directMap = toStringMap(source as Record<string, unknown>);
+  if (Object.keys(directMap).length > 0) {
+    return directMap;
+  }
+
+  const wrappedDefault = (source as { default?: unknown }).default;
+  if (wrappedDefault !== null && typeof wrappedDefault === "object") {
+    return toStringMap(wrappedDefault as Record<string, unknown>);
+  }
+
+  return {};
+};
+
+export const cls = (styles: StylesMap, key: string): string => styles[key] ?? key;
+
+export const createEl = <K extends keyof HTMLElementTagNameMap>(
+  doc: Document,
+  tag: K,
+  className?: string,
+  text?: string
+): HTMLElementTagNameMap[K] => {
+  const element = doc.createElement(tag);
+  if (className !== undefined && className.length > 0) {
+    element.className = className;
+  }
+  if (text !== undefined && text.length > 0) {
+    element.textContent = text;
+  }
+  return element;
+};
+
+export const buildGuardrailItem = (doc: Document, styles: StylesMap, item: GuardrailItem): HTMLElement => {
+  const card = createEl(doc, "li", cls(styles, "guardrailItem"));
+  const title = createEl(doc, "h3", cls(styles, "guardrailTitle"), item.title);
+  const detail = createEl(doc, "p", cls(styles, "guardrailDetail"), item.detail);
+  card.append(title, detail);
+  return card;
+};
+
+export const buildGuardrailList = (
+  doc: Document,
+  styles: StylesMap,
+  items: ReadonlyArray<GuardrailItem>
+): HTMLElement => {
+  const section = createEl(doc, "ul", cls(styles, "guardrailList"));
+  const cards = items.map((item) => buildGuardrailItem(doc, styles, item));
+  section.append(...cards);
+  return section;
+};
+
+export const buildCommandList = (doc: Document, styles: StylesMap): HTMLElement => {
+  const list = createEl(doc, "ul", cls(styles, "commandList"));
+  const commands = ["npm run dev", "npm run test", "npm run build"];
+  const items = commands.map((command) => createEl(doc, "li", cls(styles, "commandItem"), command));
+  list.append(...items);
+  return list;
+};
+
+export const buildPage = (
+  doc: Document,
+  styles: StylesMap,
+  guardrails: ReadonlyArray<GuardrailItem> = DEFAULT_GUARDRAILS
+): HTMLElement => {
+  const page = createEl(doc, "div", cls(styles, "page"));
+  const ambientGlowOne = createEl(doc, "div", cls(styles, "ambientGlowOne"));
+  const ambientGlowTwo = createEl(doc, "div", cls(styles, "ambientGlowTwo"));
+  const gridOverlay = createEl(doc, "div", cls(styles, "gridOverlay"));
+
+  const shell = createEl(doc, "div", cls(styles, "contentShell"));
+  const leftCol = createEl(doc, "section", cls(styles, "leftCol"));
+  const rightCol = createEl(doc, "section", cls(styles, "rightCol"));
+
+  const header = createEl(doc, "header", cls(styles, "header"));
+  const pill = createEl(doc, "p", cls(styles, "pill"), "Costrix Starter");
+  const title = createEl(doc, "h1", cls(styles, "title"), "Costrix TypeScript Starter");
+  const subtitle = createEl(
+    doc,
+    "p",
+    cls(styles, "subtitle"),
+    "This template sets up a minimal TypeScript codebase that compiles to vanilla JavaScript with strict quality gates."
+  );
+  header.append(pill, title, subtitle);
+
+  const guardrailHeading = createEl(doc, "h2", cls(styles, "sectionTitle"), "Build Guardrails");
+  const guardrailList = buildGuardrailList(doc, styles, guardrails);
+  leftCol.append(header, guardrailHeading, guardrailList);
+
+  const commandsHeading = createEl(doc, "h2", cls(styles, "sectionTitle"), "Available Commands");
+  const commandList = buildCommandList(doc, styles);
+  const docsButton = createEl(doc, "a", cls(styles, "docsButton"), "Read Costrix Documentation");
+  docsButton.setAttribute("href", "https://costrix.kaustubhvats.in");
+  docsButton.setAttribute("target", "_blank");
+  docsButton.setAttribute("rel", "noopener noreferrer");
+
+  const noteCard = createEl(doc, "div", cls(styles, "noteCard"));
+  const noteTitle = createEl(doc, "h3", cls(styles, "noteTitle"), "Ready for real app code");
+  const noteText = createEl(
+    doc,
+    "p",
+    cls(styles, "noteText"),
+    "Edit src/index.ts, add modules in src/, and keep guardrails on while shipping to dist/."
+  );
+  noteCard.append(noteTitle, noteText);
+
+  const footer = createEl(
+    doc,
+    "p",
+    cls(styles, "footer"),
+    "Start with src/index.ts and build your app. Crafted with care by Kaustubh."
+  );
+  rightCol.append(commandsHeading, commandList, docsButton, noteCard, footer);
+
+  shell.append(leftCol, rightCol);
+  page.append(ambientGlowOne, ambientGlowTwo, gridOverlay, shell);
+  return page;
+};
+
+export const mountApp = (
+  doc: Document = document,
+  stylesSource: unknown = stylesImport
+): HTMLElement => {
+  const styles = resolveStyles(stylesSource);
+  const root = createEl(doc, "main", cls(styles, "app"));
+  root.setAttribute("data-costrix-root", "true");
+  root.append(buildPage(doc, styles));
+  doc.body.append(root);
+  return root;
+};
+
+mountApp();

package/templates/tests/index.test.ts

@@ -0,0 +1,103 @@
+import type { GuardrailItem } from "../src/index";
+import type * as IndexModule from "../src/index";
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+
+const loadModule = async (): Promise<typeof IndexModule> => import("../src/index");
+
+describe("app module", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    jest.resetModules();
+  });
+
+  it("mounts by default on import", async () => {
+    await loadModule();
+    const root = document.querySelector('[data-costrix-root="true"]');
+    expect(root).not.toBeNull();
+  });
+
+  it("resolves direct style objects and class fallback", async () => {
+    const mod = await loadModule();
+    const resolved = mod.resolveStyles({ app: "app_hash" });
+    expect(mod.cls(resolved, "app")).toBe("app_hash");
+    expect(mod.cls(resolved, "missing")).toBe("missing");
+  });
+
+  it("resolves wrapped default style objects and invalid input", async () => {
+    const mod = await loadModule();
+    const wrapped = mod.resolveStyles({ default: { page: "page_hash" } });
+    const empty = mod.resolveStyles(null);
+    const fallbackEmpty = mod.resolveStyles({ default: 7, page: 1 });
+    expect(mod.cls(wrapped, "page")).toBe("page_hash");
+    expect(mod.cls(empty, "page")).toBe("page");
+    expect(mod.cls(fallbackEmpty, "page")).toBe("page");
+  });
+
+  it("creates elements with optional class and text", async () => {
+    const mod = await loadModule();
+    const withAll = mod.createEl(document, "button", "cta", "Launch");
+    const bare = mod.createEl(document, "div");
+    expect(withAll.className).toBe("cta");
+    expect(withAll.textContent).toBe("Launch");
+    expect(bare.className).toBe("");
+    expect(bare.textContent).toBe("");
+  });
+
+  it("builds guardrail item and list", async () => {
+    const mod = await loadModule();
+    const styles = mod.resolveStyles({
+      guardrailItem: "card",
+      guardrailTitle: "cardTitle",
+      guardrailDetail: "cardDetail",
+      guardrailList: "grid"
+    });
+    const item: GuardrailItem = { title: "Rule", detail: "Detail" };
+    const card = mod.buildGuardrailItem(document, styles, item);
+    const grid = mod.buildGuardrailList(document, styles, [item]);
+    expect(card.className).toBe("card");
+    expect(card.querySelector("h3")?.className).toBe("cardTitle");
+    expect(card.querySelector("p")?.className).toBe("cardDetail");
+    expect(grid.className).toBe("grid");
+    expect(grid.querySelectorAll("li").length).toBe(1);
+  });
+
+  it("builds command list", async () => {
+    const mod = await loadModule();
+    const styles = mod.resolveStyles({ commandList: "commands", commandItem: "command" });
+    const list = mod.buildCommandList(document, styles);
+    expect(list.className).toBe("commands");
+    expect(list.querySelectorAll("li").length).toBe(3);
+  });
+
+  it("builds page and mounts with provided styles", async () => {
+    const mod = await loadModule();
+    const styles = mod.resolveStyles({
+      app: "appHash",
+      page: "pageHash",
+      header: "headerHash",
+      title: "titleHash",
+      subtitle: "subtitleHash",
+      sectionTitle: "sectionTitleHash",
+      guardrailList: "guardrailListHash",
+      guardrailItem: "guardrailItemHash",
+      guardrailTitle: "guardrailTitleHash",
+      guardrailDetail: "guardrailDetailHash",
+      commandList: "commandListHash",
+      commandItem: "commandItemHash",
+      docsButton: "docsButtonHash",
+      footer: "footerHash"
+    });
+    const page = mod.buildPage(document, styles);
+    expect(page.className).toBe("pageHash");
+    expect(page.querySelector("h1")?.textContent).toBe("Costrix TypeScript Starter");
+    expect(page.querySelector('a[href="https://costrix.kaustubhvats.in"]')?.className).toBe("docsButtonHash");
+
+    const defaultPage = mod.buildPage(document, styles);
+    expect(defaultPage.querySelectorAll("li").length).toBeGreaterThan(3);
+
+    document.body.innerHTML = "";
+    const mounted = mod.mountApp(document, styles);
+    expect(mounted.className).toBe("appHash");
+    expect(document.querySelectorAll('[data-costrix-root="true"]').length).toBe(1);
+  });
+});

package/templates/tests/styleMock.ts

@@ -0,0 +1,8 @@
+const styles = new Proxy<Record<string, string>>(
+  {},
+  {
+    get: (_target, prop: string | symbol): string => String(prop)
+  }
+);
+
+export default styles;

package/templates/tsconfig.eslint.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/templates/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "sourceMap": true,
+    "outDir": "dist"
+  },
+  "include": ["src", "tests"]
+}

package/templates/webpack.config.js

@@ -0,0 +1,72 @@
+const path = require("path");
+const HtmlWebpackPlugin = require("html-webpack-plugin");
+const MiniCssExtractPlugin = require("mini-css-extract-plugin");
+const CopyWebpackPlugin = require("copy-webpack-plugin");
+
+module.exports = (_env, argv) => {
+  const isProduction = argv.mode === "production";
+
+  return {
+    entry: "./src/index.ts",
+    output: {
+      path: path.resolve(__dirname, "dist"),
+      filename: "bundle.[contenthash].js",
+      clean: true
+    },
+    devtool: isProduction ? "source-map" : "eval-cheap-module-source-map",
+    resolve: {
+      extensions: [".ts", ".js"]
+    },
+    module: {
+      rules: [
+        {
+          test: /\.ts$/,
+          exclude: /node_modules/,
+          use: "ts-loader"
+        },
+        {
+          test: /\.module\.css$/,
+          use: [
+            isProduction ? MiniCssExtractPlugin.loader : "style-loader",
+            {
+              loader: "css-loader",
+              options: {
+                modules: true
+              }
+            }
+          ]
+        }
+      ]
+    },
+    plugins: [
+      new HtmlWebpackPlugin({
+        template: "./public/index.html"
+      }),
+      new CopyWebpackPlugin({
+        patterns: [
+          {
+            from: "public",
+            to: "public",
+            globOptions: {
+              ignore: ["**/index.html"]
+            }
+          }
+        ]
+      }),
+      ...(isProduction ? [new MiniCssExtractPlugin({ filename: "styles.[contenthash].css" })] : [])
+    ],
+    devServer: {
+      static: [
+        {
+          directory: path.join(__dirname, "public"),
+          publicPath: "/",
+          watch: true
+        }
+      ],
+      watchFiles: ["public/**/*"],
+      hot: true,
+      port: 3000,
+      open: true
+    }
+  };
+};