front-end-dev-standards 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# front-end-dev-standards
+
+Company-wide Angular coding standards packaged for **Cursor AI** and **GitHub Copilot**.
+
+## What It Does
+
+When installed in an Angular project, the postinstall script automatically:
+
+1. Creates `.ai-standards/` with standards markdown files
+2. Creates `.cursor/rules/company.mdc` for Cursor
+3. Creates `.github/copilot-instructions.md` for GitHub Copilot
+
+```
+npm install -D front-end-dev-standards
+        ↓
+postinstall runs setup.js
+        ↓
+.ai-standards/          ← standards source of truth (local copy)
+.cursor/rules/          ← Cursor reads this automatically
+.github/                ← Copilot reads copilot-instructions.md
+        ↓
+AI tools generate standardized Angular code
+```
+
+## Installation
+
+### From npm registry (production)
+
+```bash
+npm install -D front-end-dev-standards
+```
+
+### Local development (this monorepo)
+
+```bash
+# Already wired via file: dependency in root package.json
+npm install
+npm run standards:setup
+```
+
+## Manual Commands
+
+```bash
+# Idempotent setup (skips existing files)
+npm run standards:setup
+
+# Force overwrite all generated files
+npm run standards:setup:force
+
+# Preview changes without writing
+node packages/dev-standards/scripts/setup.js --dry-run
+```
+
+## Configuration
+
+Create `.standardsrc.json` in your project root:
+
+```json
+{
+  "overwrite": false,
+  "targets": {
+    "standardsDir": ".ai-standards",
+    "cursorRulesFile": ".cursor/rules/company.mdc",
+    "copilotInstructionsFile": ".github/copilot-instructions.md"
+  }
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `overwrite` | `false` | When `true`, replaces existing generated files |
+| `targets.standardsDir` | `.ai-standards` | Where standards MD files are copied |
+| `targets.cursorRulesFile` | `.cursor/rules/company.mdc` | Cursor rules output path |
+| `targets.copilotInstructionsFile` | `.github/copilot-instructions.md` | Copilot instructions path |
+
+CLI flag `--force` overrides `overwrite` to `true` for a single run.
+
+## Adding a New Standards File
+
+1. Create any `*.md` file in `packages/dev-standards/standards/` (e.g. `security.md`)
+2. Run `npm run standards:setup` (or `npm install` — postinstall runs automatically)
+
+All `.md` files in `standards/` are **auto-discovered** — no need to edit `config/default.json`.
+
+When a new file is added, Cursor and Copilot config files are refreshed automatically.
+To update **existing** standards content, run `npm run standards:setup:force`.
+
+## Standards Files
+
+| File | Purpose |
+|---|---|
+| `standards/angular.md` | Angular 20+ patterns: standalone, signals, inject, forms |
+| `standards/architecture.md` | Feature-based folder structure, layers, data flow |
+| `standards/coding-style.md` | TypeScript naming, formatting, review checklist |
+| `standards/testing.md` | Vitest conventions, coverage expectations |
+
+## How Cursor Reads Rules
+
+Cursor automatically loads `.cursor/rules/*.mdc` files from your project.
+
+The generated `company.mdc` has `alwaysApply: true`, so every AI interaction in the project follows your standards.
+
+## How GitHub Copilot Reads Standards
+
+Copilot reads `.github/copilot-instructions.md` at the repository root.
+
+It does **not** read `.cursor/rules/` — that's why the postinstall script generates a separate Copilot file from the same standards.
+
+## Versioning & Upgrades
+
+```bash
+npm update front-end-dev-standards
+npm run standards:setup:force   # refresh generated files
+```
+
+## Publishing as npm Package
+
+Registry: **https://registry.npmjs.org/** (configured in `.npmrc` and `publishConfig`)
+
+```bash
+# From repo root
+npm login
+npm run standards:validate
+npm run standards:pack
+npm run standards:publish
+
+# Version bumps + publish
+npm run standards:publish:patch
+npm run standards:publish:minor
+npm run standards:publish:major
+```
+
+Consumer projects install with:
+
+```json
+{
+  "devDependencies": {
+    "front-end-dev-standards": "^1.0.0"
+  }
+}
+```
+
+The package's own `postinstall` hook runs `setup.js` automatically on `npm install`.
+
+## Package Structure
+
+```
+packages/dev-standards/
+├── config/
+│   └── default.json
+├── scripts/
+│   └── setup.js
+├── standards/
+│   ├── angular.md
+│   ├── architecture.md
+│   ├── coding-style.md
+│   └── testing.md
+├── templates/
+│   ├── company.mdc.template
+│   └── copilot-instructions.md.template
+├── package.json
+└── README.md
+```
+
+## License
+
+UNLICENSED — internal company use only.

package/config/default.json

@@ -0,0 +1,8 @@
+{
+  "overwrite": false,
+  "targets": {
+    "standardsDir": ".ai-standards",
+    "cursorRulesFile": ".cursor/rules/company.mdc",
+    "copilotInstructionsFile": ".github/copilot-instructions.md"
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "front-end-dev-standards",
+  "version": "1.0.0",
+  "description": "Company-wide Angular coding standards for Cursor AI and GitHub Copilot",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./scripts/setup.js",
+  "bin": {
+    "front-end-dev-standards-setup": "./scripts/setup.js"
+  },
+  "files": [
+    "standards/",
+    "templates/",
+    "scripts/",
+    "config/",
+    "README.md",
+    ".npmrc"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/setup.js",
+    "setup": "node scripts/setup.js",
+    "setup:force": "node scripts/setup.js --force",
+    "prepublishOnly": "node scripts/validate-package.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "angular",
+    "standards",
+    "cursor",
+    "copilot",
+    "ai"
+  ]
+}

package/scripts/npm-cmd.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * Run npm commands from the dev-standards package directory.
+ * Ensures pack/publish only includes package files (not the Angular workspace root).
+ *
+ * Usage (from repo root):
+ *   node packages/dev-standards/scripts/npm-cmd.js pack --ignore-scripts
+ *   node packages/dev-standards/scripts/npm-cmd.js publish --ignore-scripts
+ */
+
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const npmArgs = process.argv.slice(2);
+
+if (npmArgs.length === 0) {
+  console.error('[dev-standards] Usage: npm-cmd.js <npm-args...>');
+  process.exit(1);
+}
+
+process.chdir(PACKAGE_ROOT);
+execSync(`npm ${npmArgs.join(' ')}`, { stdio: 'inherit', shell: true });

package/scripts/setup.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * dev-standards — postinstall setup script
+ *
+ * Copies company standards into the consuming Angular project and generates
+ * AI tool configuration files for Cursor and GitHub Copilot.
+ *
+ * Idempotent by default: existing files are skipped unless --force is passed
+ * or .standardsrc.json sets "overwrite": true.
+ *
+ * Usage:
+ *   node scripts/setup.js           # safe, idempotent install
+ *   node scripts/setup.js --force   # overwrite all generated files
+ *   node scripts/setup.js --dry-run # preview without writing
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Directory where this package lives (packages/dev-standards or node_modules/dev-standards) */
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+/** Parse CLI flags */
+const args = process.argv.slice(2);
+const FORCE = args.includes('--force');
+const DRY_RUN = args.includes('--dry-run');
+const VERBOSE = args.includes('--verbose') || args.includes('-v');
+
+/**
+ * Resolve the consuming project root.
+ * Walks up from cwd until it finds a package.json that is NOT this standards package.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+
+  while (current !== path.dirname(current)) {
+    const pkgPath = path.join(current, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        // If this package.json belongs to dev-standards, keep walking up
+        if (pkg.name === 'front-end-dev-standards' || pkg.name === 'dev-standards') {
+          current = path.dirname(current);
+          continue;
+        }
+        return current;
+      } catch {
+        // malformed package.json — keep searching
+      }
+    }
+    current = path.dirname(current);
+  }
+
+  return process.cwd();
+}
+
+/**
+ * Load merged configuration: package defaults + project .standardsrc.json
+ */
+function loadConfig(projectRoot) {
+  const defaultsPath = path.join(PACKAGE_ROOT, 'config', 'default.json');
+  const defaults = JSON.parse(fs.readFileSync(defaultsPath, 'utf8'));
+
+  const rcPath = path.join(projectRoot, '.standardsrc.json');
+  if (!fs.existsSync(rcPath)) {
+    return { ...defaults, overwrite: FORCE || defaults.overwrite };
+  }
+
+  const rc = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
+  return {
+    ...defaults,
+    ...rc,
+    targets: { ...defaults.targets, ...rc.targets },
+    overwrite: FORCE || rc.overwrite === true || defaults.overwrite === true,
+  };
+}
+
+/**
+ * Resolve which standards files to copy.
+ * Default: all *.md files in packages/dev-standards/standards/ (auto-discovered).
+ * Optional: set "standardsFiles" in .standardsrc.json to copy a specific subset only.
+ */
+function resolveStandardsFiles(sourceStandardsDir, config) {
+  if (Array.isArray(config.standardsFiles) && config.standardsFiles.length > 0) {
+    return config.standardsFiles;
+  }
+
+  if (!fs.existsSync(sourceStandardsDir)) {
+    warn(`Standards directory not found: ${sourceStandardsDir}`);
+    return [];
+  }
+
+  return fs
+    .readdirSync(sourceStandardsDir)
+    .filter((file) => file.endsWith('.md') && fs.statSync(path.join(sourceStandardsDir, file)).isFile())
+    .sort();
+}
+
+/** Ensure directory exists */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    if (DRY_RUN) {
+      log(`[dry-run] mkdir ${dirPath}`);
+      return;
+    }
+    fs.mkdirSync(dirPath, { recursive: true });
+    log(`Created directory: ${rel(dirPath)}`);
+  }
+}
+
+/** Copy file if missing or overwrite enabled */
+function copyFile(src, dest, overwrite) {
+  const destExists = fs.existsSync(dest);
+
+  if (destExists && !overwrite) {
+    log(`Skipped (exists): ${rel(dest)}`);
+    return false;
+  }
+
+  if (DRY_RUN) {
+    log(`[dry-run] copy ${rel(src)} → ${rel(dest)}${destExists ? ' (overwrite)' : ''}`);
+    return true;
+  }
+
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+  log(`${destExists ? 'Updated' : 'Created'}: ${rel(dest)}`);
+  return true;
+}
+
+/** Generate file from template with token replacement */
+function generateFromTemplate(templatePath, destPath, tokens, overwrite) {
+  if (!fs.existsSync(templatePath)) {
+    warn(`Template not found: ${rel(templatePath)}`);
+    return false;
+  }
+
+  const destExists = fs.existsSync(destPath);
+  if (destExists && !overwrite) {
+    log(`Skipped (exists): ${rel(destPath)}`);
+    return false;
+  }
+
+  let content = fs.readFileSync(templatePath, 'utf8');
+  for (const [key, value] of Object.entries(tokens)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+
+  if (DRY_RUN) {
+    log(`[dry-run] generate ${rel(destPath)}${destExists ? ' (overwrite)' : ''}`);
+    return true;
+  }
+
+  ensureDir(path.dirname(destPath));
+  fs.writeFileSync(destPath, content, 'utf8');
+  log(`${destExists ? 'Updated' : 'Created'}: ${rel(destPath)}`);
+  return true;
+}
+
+/** Paths relative to project root for readable logs */
+let projectRoot = process.cwd();
+function rel(absPath) {
+  return path.relative(projectRoot, absPath) || absPath;
+}
+
+function log(message) {
+  console.log(`[dev-standards] ${message}`);
+}
+
+function warn(message) {
+  console.warn(`[dev-standards] WARN: ${message}`);
+}
+
+/**
+ * Main setup routine
+ */
+function run() {
+  projectRoot = findProjectRoot();
+  const config = loadConfig(projectRoot);
+  const overwrite = config.overwrite === true;
+
+  log(`Project root: ${projectRoot}`);
+  log(`Mode: ${DRY_RUN ? 'dry-run' : overwrite ? 'overwrite' : 'idempotent'}`);
+
+  const standardsDir = path.join(projectRoot, config.targets.standardsDir);
+  const cursorRulesFile = path.join(projectRoot, config.targets.cursorRulesFile);
+  const copilotFile = path.join(projectRoot, config.targets.copilotInstructionsFile);
+
+  ensureDir(standardsDir);
+  ensureDir(path.dirname(cursorRulesFile));
+  ensureDir(path.dirname(copilotFile));
+
+  // 1. Copy standards markdown files (auto-discover all *.md in standards/)
+  const sourceStandardsDir = path.join(PACKAGE_ROOT, 'standards');
+  const standardsFiles = resolveStandardsFiles(sourceStandardsDir, config);
+
+  if (standardsFiles.length === 0) {
+    warn('No standards .md files found to copy.');
+  } else if (VERBOSE) {
+    log(`Standards files: ${standardsFiles.join(', ')}`);
+  }
+
+  let copiedCount = 0;
+  let anyNewStandard = false;
+
+  for (const file of standardsFiles) {
+    const src = path.join(sourceStandardsDir, file);
+    const dest = path.join(standardsDir, file);
+    const destExists = fs.existsSync(dest);
+
+    if (!fs.existsSync(src)) {
+      warn(`Standard file missing in package: ${file}`);
+      continue;
+    }
+
+    if (copyFile(src, dest, overwrite)) {
+      copiedCount++;
+      if (!destExists) {
+        anyNewStandard = true;
+      }
+    }
+  }
+
+  // 2. Generate Cursor rules (.mdc) — refresh when new standards are added or --force
+  const standardsRelativePaths = standardsFiles.map((f) =>
+    path.join(config.targets.standardsDir, f).replace(/\\/g, '/'),
+  );
+
+  const templateTokens = {
+    STANDARDS_VERSION: readPackageVersion(),
+    STANDARDS_PATHS: standardsRelativePaths.map((p) => `- \`${p}\``).join('\n'),
+    GENERATED_AT: new Date().toISOString(),
+  };
+
+  const regenAiConfig = overwrite || anyNewStandard || !fs.existsSync(cursorRulesFile);
+
+  generateFromTemplate(
+    path.join(PACKAGE_ROOT, 'templates', 'company.mdc.template'),
+    cursorRulesFile,
+    templateTokens,
+    regenAiConfig,
+  );
+
+  // 3. Generate GitHub Copilot instructions
+  generateFromTemplate(
+    path.join(PACKAGE_ROOT, 'templates', 'copilot-instructions.md.template'),
+    copilotFile,
+    templateTokens,
+    regenAiConfig,
+  );
+
+  log(`Setup complete. ${copiedCount} standard file(s) processed.`);
+  log(`Cursor rules: ${rel(cursorRulesFile)}`);
+  log(`Copilot instructions: ${rel(copilotFile)}`);
+
+  if (!overwrite && !anyNewStandard) {
+    log('Tip: run with --force or set "overwrite": true in .standardsrc.json to refresh existing standards files.');
+  }
+}
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+try {
+  run();
+} catch (error) {
+  console.error('[dev-standards] Setup failed:', error.message);
+  process.exit(1);
+}

package/scripts/validate-package.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-publish validation — ensures required package files exist before npm publish.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const REQUIRED_PATHS = [
+  'package.json',
+  'README.md',
+  'scripts/setup.js',
+  'config/default.json',
+  'templates/company.mdc.template',
+  'templates/copilot-instructions.md.template',
+  'standards/angular.md',
+  'standards/architecture.md',
+  'standards/coding-style.md',
+  'standards/testing.md',
+];
+
+const missing = REQUIRED_PATHS.filter((rel) => !fs.existsSync(path.join(PACKAGE_ROOT, rel)));
+
+if (missing.length > 0) {
+  console.error('[dev-standards] Publish validation failed. Missing files:');
+  missing.forEach((file) => console.error(`  - ${file}`));
+  process.exit(1);
+}
+
+const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+
+if (pkg.private === true) {
+  console.error('[dev-standards] Publish validation failed: "private": true must be removed from package.json');
+  process.exit(1);
+}
+
+console.log(`[dev-standards] Publish validation passed (v${pkg.version}).`);