ai-ide-config 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# ai-ide-config
+
+Scaffold shared Cursor IDE / agent setup into a project: shared `.cursor` rules/commands, plus stack-specific `AGENTS.md` and stack rules when needed.
+
+## Install / run
+
+No global install required:
+
+```bash
+npx ai-ide-config init
+```
+
+From a local checkout:
+
+```bash
+cd ai-ide-config
+npm link
+cd /path/to/your-project
+npx ai-ide-config init
+```
+
+## Usage
+
+```bash
+# Interactive: pick a stack
+npx ai-ide-config init
+
+# Non-interactive
+npx ai-ide-config init --stack angular
+npx ai-ide-config init-angular
+
+# Options
+npx ai-ide-config init --force        # overwrite existing files
+npx ai-ide-config init --dry-run      # preview only
+npx ai-ide-config init --skip-skills  # skip angular/skills install
+npx ai-ide-config init ./apps/web     # target directory
+```
+
+Existing template files are **skipped** unless you pass `--force`.
+
+`.gitignore` is handled specially:
+
+- If missing → create it with `.cursor/` and `.agents/`
+- If present → append `.cursor/` and/or `.agents/` only when missing
+
+If `package.json` exists, init pins an **exact** `packageManager` / `devEngines.packageManager` to the installed pnpm version. That avoids Corepack failing on ranges like `^11.13.0` from `pnpm init`.
+
+After scaffolding, the CLI runs:
+
+```bash
+pnpx skills add https://github.com/angular/skills
+```
+
+(`pnpx` is used instead of `npx` because the skills package requires pnpm via `devEngines`.)
+
+Use `--skip-skills` to skip that step. On `--dry-run`, the command is only printed.
+
+In CI or non-TTY shells, pass `--stack` (or use `init-<stack>`). Interactive prompts require a terminal.
+
+## What gets written
+
+| Path | Source |
+|------|--------|
+| `.cursor/rules/conventional-commits.mdc` | shared |
+| `.cursor/commands/generate-pr-description.md` | shared |
+| `.cursor/rules/angular-20.mdc` | angular ([angular.dev](https://angular.dev/assets/context/angular-20.mdc)) |
+| `AGENTS.md` | angular |
+| `pnpm-workspace.yaml` | angular (`blockExoticSubdeps`, `minimumReleaseAge: 4320`) |
+| `.gitignore` | create or append `.cursor/` and `.agents/` |
+
+After init, edit `AGENTS.md` placeholders (`<PROJECT_NAME>`, package manager, domains, paths) for the target repo.
+
+## Stacks
+
+| Id | Label |
+|----|-------|
+| `angular` | Angular |
+
+### Adding a stack
+
+1. Add `templates/<stack>/AGENTS.md`
+2. Register it in [`src/stacks.mjs`](src/stacks.mjs)
+3. Document it here
+
+Shared Cursor rules/commands stay under `templates/shared/`.
+
+## Publishing to npm
+
+CD publishes to npm when you create a **GitHub Release** (workflow: [`.github/workflows/publish.yml`](.github/workflows/publish.yml)).
+
+### One-time setup
+
+1. Create an [npmjs.com](https://www.npmjs.com) account and verify your email.
+2. Create the package on npm (first publish can also create it), or claim the name `ai-ide-config`.
+3. In the package settings on npm → **Trusted Publisher**:
+   - **Organization or user:** `iraldoad`
+   - **Repository:** `ai-ide-config`
+   - **Workflow filename:** `publish.yml`
+   - Allow **npm publish**
+4. No `NPM_TOKEN` secret is required (OIDC Trusted Publishing).
+
+### Release a version
+
+1. Bump `version` in `package.json` (e.g. `0.1.1`).
+2. Commit and push.
+3. Create a GitHub Release for that commit (e.g. tag `v0.1.1`).
+4. The workflow runs `npm publish --access public --provenance`.
+
+After the first successful publish:
+
+```bash
+npx ai-ide-config init
+```
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { getStack, listStacks, stackIds } from '../src/stacks.mjs';
+import { promptForStack } from '../src/prompt.mjs';
+import { initStack, printReport } from '../src/init.mjs';
+import { runSkillsAdd, SKILLS_ADD_COMMAND } from '../src/skills.mjs';
+
+function printUsage() {
+  const stacks = listStacks()
+    .map((s) => `  init-${s.id}`.padEnd(18) + `# shortcut for init --stack ${s.id}`)
+    .join('\n');
+
+  console.log(`Usage:
+  ai-ide-config init [dir] [--stack <name>] [--force] [--dry-run] [--skip-skills]
+  ai-ide-config init-<stack> [dir] [--force] [--dry-run] [--skip-skills]
+
+Options:
+  --stack <name>   Skip interactive prompt (e.g. angular)
+  --force          Overwrite existing files
+  --dry-run        Show what would be written
+  --skip-skills    Do not run: ${SKILLS_ADD_COMMAND}
+
+Stacks:
+${listStacks()
+  .map((s) => `  ${s.id.padEnd(12)} ${s.label}`)
+  .join('\n')}
+
+Shortcuts:
+${stacks}
+`);
+}
+
+/**
+ * @param {string[]} argv
+ */
+function parseArgs(argv) {
+  const args = [...argv];
+  /** @type {{ command: string | null, targetDir: string, stackId: string | null, force: boolean, dryRun: boolean, skipSkills: boolean, help: boolean }} */
+  const result = {
+    command: null,
+    targetDir: process.cwd(),
+    stackId: null,
+    force: false,
+    dryRun: false,
+    skipSkills: false,
+    help: false,
+  };
+
+  const positionals = [];
+
+  while (args.length > 0) {
+    const token = args.shift();
+
+    if (token === '--help' || token === '-h') {
+      result.help = true;
+      continue;
+    }
+    if (token === '--force') {
+      result.force = true;
+      continue;
+    }
+    if (token === '--dry-run') {
+      result.dryRun = true;
+      continue;
+    }
+    if (token === '--skip-skills') {
+      result.skipSkills = true;
+      continue;
+    }
+    if (token === '--stack') {
+      const value = args.shift();
+      if (!value) {
+        throw new Error('--stack requires a value');
+      }
+      result.stackId = value;
+      continue;
+    }
+    if (token.startsWith('-')) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    positionals.push(token);
+  }
+
+  result.command = positionals[0] ?? null;
+  if (positionals[1]) {
+    result.targetDir = path.resolve(positionals[1]);
+  }
+
+  return result;
+}
+
+/**
+ * Resolve stack id from command name like init-angular.
+ * @param {string} command
+ * @returns {string | null}
+ */
+function stackFromInitAlias(command) {
+  const match = /^init-(.+)$/.exec(command);
+  if (!match) return null;
+  return match[1];
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    console.error(err.message);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.help || !parsed.command) {
+    printUsage();
+    process.exitCode = parsed.help ? 0 : 1;
+    return;
+  }
+
+  let stackId = parsed.stackId;
+
+  if (parsed.command === 'init') {
+    // stackId may already be set via --stack
+  } else {
+    const aliasStack = stackFromInitAlias(parsed.command);
+    if (aliasStack) {
+      if (stackId && stackId !== aliasStack) {
+        console.error(
+          `Conflicting stacks: command is init-${aliasStack} but --stack ${stackId} was passed.`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      stackId = aliasStack;
+    } else {
+      console.error(`Unknown command: ${parsed.command}`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (!stackId) {
+    try {
+      stackId = await promptForStack();
+    } catch (err) {
+      console.error(err.message);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const stack = getStack(stackId);
+  if (!stack) {
+    console.error(
+      `Unknown stack "${stackId}". Available: ${stackIds().join(', ')}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const report = initStack({
+      stack,
+      targetDir: parsed.targetDir,
+      force: parsed.force,
+      dryRun: parsed.dryRun,
+    });
+
+    console.log(
+      `${parsed.dryRun ? '[dry-run] ' : ''}Scaffolding ${stack.label} AI IDE config into ${parsed.targetDir}`,
+    );
+    printReport(report, { dryRun: parsed.dryRun });
+
+    runSkillsAdd(parsed.targetDir, {
+      dryRun: parsed.dryRun,
+      skip: parsed.skipSkills,
+    });
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ai-ide-config",
+  "version": "0.1.0",
+  "description": "Scaffold shared Cursor IDE / agent config (rules, commands, stack AGENTS.md)",
+  "type": "module",
+  "bin": {
+    "ai-ide-config": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iraldoad/ai-ide-config.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iraldoad/ai-ide-config/issues"
+  },
+  "homepage": "https://github.com/iraldoad/ai-ide-config#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cursor",
+    "agents",
+    "ai",
+    "ide",
+    "angular"
+  ],
+  "license": "MIT"
+}

package/src/init.mjs

@@ -0,0 +1,195 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { sharedTemplatesDir, stackTemplatesDir } from './paths.mjs';
+import { ensureExactPnpmEngines } from './package-manager.mjs';
+
+const GITIGNORE = '.gitignore';
+const GITIGNORE_ENTRIES = ['.cursor/', '.agents/'];
+
+/**
+ * Recursively collect relative file paths under dir.
+ * @param {string} dir
+ * @param {string} [base]
+ * @returns {string[]}
+ */
+function listFiles(dir, base = dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const absolute = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFiles(absolute, base));
+    } else if (entry.isFile()) {
+      files.push(path.relative(base, absolute));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * @typedef {{ created: string[], skipped: string[], overwritten: string[], updated: string[] }} CopyReport
+ */
+
+/**
+ * Whether .gitignore already ignores a directory entry (with or without trailing slash).
+ * @param {string} content
+ * @param {string} entry e.g. ".cursor/" or ".agents/"
+ */
+function hasIgnoreEntry(content, entry) {
+  const name = entry.replace(/\/$/, '').replace(/^\./, '\\.');
+  return new RegExp(`(?:^|\\n)\\s*${name}\\/?\\s*(?:\\n|$)`).test(content);
+}
+
+/**
+ * Create .gitignore with required entries, or append any that are missing.
+ * @param {string} targetDir
+ * @param {{ dryRun?: boolean }} options
+ * @param {CopyReport} report
+ */
+function ensureGitignore(targetDir, options, report) {
+  const filePath = path.join(targetDir, GITIGNORE);
+  const exists = fs.existsSync(filePath);
+
+  if (!exists) {
+    if (options.dryRun) {
+      report.created.push(`${GITIGNORE} (${GITIGNORE_ENTRIES.join(', ')})`);
+      return;
+    }
+    fs.writeFileSync(filePath, `${GITIGNORE_ENTRIES.join('\n')}\n`, 'utf8');
+    report.created.push(GITIGNORE);
+    return;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const missing = GITIGNORE_ENTRIES.filter(
+    (entry) => !hasIgnoreEntry(content, entry),
+  );
+
+  if (missing.length === 0) {
+    report.skipped.push(
+      `${GITIGNORE} (${GITIGNORE_ENTRIES.join(', ')} already listed)`,
+    );
+    return;
+  }
+
+  if (options.dryRun) {
+    report.updated.push(`${GITIGNORE} (append ${missing.join(', ')})`);
+    return;
+  }
+
+  const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+  fs.writeFileSync(
+    filePath,
+    `${content}${separator}${missing.join('\n')}\n`,
+    'utf8',
+  );
+  report.updated.push(`${GITIGNORE} (appended ${missing.join(', ')})`);
+}
+
+/**
+ * Copy all files from sourceRoot into targetDir.
+ * @param {string} sourceRoot
+ * @param {string} targetDir
+ * @param {{ force?: boolean, dryRun?: boolean }} options
+ * @param {CopyReport} report
+ */
+function copyTree(sourceRoot, targetDir, options, report) {
+  const relativeFiles = listFiles(sourceRoot);
+
+  for (const relative of relativeFiles) {
+    const from = path.join(sourceRoot, relative);
+    const to = path.join(targetDir, relative);
+    const exists = fs.existsSync(to);
+
+    if (exists && !options.force) {
+      report.skipped.push(relative);
+      continue;
+    }
+
+    if (options.dryRun) {
+      if (exists) {
+        report.overwritten.push(relative);
+      } else {
+        report.created.push(relative);
+      }
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+
+    if (exists) {
+      report.overwritten.push(relative);
+    } else {
+      report.created.push(relative);
+    }
+  }
+}
+
+/**
+ * Scaffold shared .cursor config + stack templates into targetDir.
+ * @param {{ stack: { id: string, agentsDir: string }, targetDir: string, force?: boolean, dryRun?: boolean }} opts
+ * @returns {CopyReport}
+ */
+export function initStack(opts) {
+  const { stack, targetDir, force = false, dryRun = false } = opts;
+  const options = { force, dryRun };
+  /** @type {CopyReport} */
+  const report = {
+    created: [],
+    skipped: [],
+    overwritten: [],
+    updated: [],
+  };
+
+  const shared = sharedTemplatesDir();
+  const stackDir = stackTemplatesDir(stack.agentsDir);
+
+  if (!fs.existsSync(shared)) {
+    throw new Error(`Shared templates missing: ${shared}`);
+  }
+  if (!fs.existsSync(stackDir)) {
+    throw new Error(`Stack templates missing for "${stack.id}": ${stackDir}`);
+  }
+
+  copyTree(shared, targetDir, options, report);
+  copyTree(stackDir, targetDir, options, report);
+  ensureGitignore(targetDir, options, report);
+  ensureExactPnpmEngines(targetDir, options, report);
+
+  return report;
+}
+
+export function printReport(report, { dryRun = false } = {}) {
+  const prefix = dryRun ? '[dry-run] ' : '';
+
+  const sections = [
+    ['Created', report.created],
+    ['Updated', report.updated],
+    ['Overwritten', report.overwritten],
+    ['Skipped (already exists)', report.skipped],
+  ];
+
+  for (const [label, files] of sections) {
+    if (!files || files.length === 0) continue;
+    console.log(`${prefix}${label}:`);
+    for (const file of files) {
+      console.log(`  ${file}`);
+    }
+  }
+
+  if (
+    report.created.length === 0 &&
+    report.overwritten.length === 0 &&
+    report.skipped.length === 0 &&
+    (report.updated?.length ?? 0) === 0
+  ) {
+    console.log(`${prefix}Nothing to do.`);
+  }
+}

package/src/package-manager.mjs

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Resolve pnpm version without using the target project as cwd.
+ * Running inside a project with `devEngines.packageManager.version: "^…"`
+ * makes Corepack/pnpm refuse to start.
+ * @returns {string | null} installed pnpm version (e.g. "11.13.0")
+ */
+export function detectPnpmVersion() {
+  const result = spawnSync('pnpm --version', {
+    cwd: os.tmpdir(),
+    encoding: 'utf8',
+    shell: true,
+    env: process.env,
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const version = (result.stdout ?? '').trim().split(/\s+/)[0];
+  return /^\d+\.\d+\.\d+/.test(version) ? version : null;
+}
+
+/**
+ * True if version is not an exact x.y.z (e.g. ^11.13.0, >=11).
+ * @param {string | undefined} version
+ */
+function isRangeOrInvalid(version) {
+  if (!version || typeof version !== 'string') return true;
+  return !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version.trim());
+}
+
+/**
+ * Pin packageManager / devEngines to an exact pnpm version so Corepack/pnpm
+ * do not fail on ranges like "^11.13.0" (from `pnpm init`).
+ *
+ * @param {string} targetDir
+ * @param {{ dryRun?: boolean }} options
+ * @param {{ created: string[], updated: string[], skipped: string[] }} report
+ */
+export function ensureExactPnpmEngines(targetDir, options, report) {
+  const pkgPath = path.join(targetDir, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    report.skipped.push('package.json (missing — skipped packageManager pin)');
+    return;
+  }
+
+  const version = detectPnpmVersion();
+  if (!version) {
+    report.skipped.push('package.json (pnpm not found — skipped packageManager pin)');
+    return;
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const expectedPackageManager = `pnpm@${version}`;
+  const currentDevVersion = pkg.devEngines?.packageManager?.version;
+  const needsPackageManager = pkg.packageManager !== expectedPackageManager;
+  const needsDevEngines =
+    !pkg.devEngines?.packageManager ||
+    pkg.devEngines.packageManager.name !== 'pnpm' ||
+    isRangeOrInvalid(currentDevVersion) ||
+    currentDevVersion !== version;
+
+  if (!needsPackageManager && !needsDevEngines) {
+    report.skipped.push('package.json (packageManager already exact)');
+    return;
+  }
+
+  if (options.dryRun) {
+    report.updated.push(
+      `package.json (pin packageManager to ${expectedPackageManager})`,
+    );
+    return;
+  }
+
+  pkg.packageManager = expectedPackageManager;
+  pkg.devEngines = {
+    ...pkg.devEngines,
+    packageManager: {
+      name: 'pnpm',
+      version,
+      onFail: 'download',
+    },
+  };
+
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+  report.updated.push(
+    `package.json (pinned packageManager to ${expectedPackageManager})`,
+  );
+}

package/src/paths.mjs

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+export function templatesRoot() {
+  return path.join(packageRoot(), 'templates');
+}
+
+export function sharedTemplatesDir() {
+  return path.join(templatesRoot(), 'shared');
+}
+
+export function stackTemplatesDir(agentsDir) {
+  return path.join(templatesRoot(), agentsDir);
+}

package/src/prompt.mjs

@@ -0,0 +1,49 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { listStacks } from './stacks.mjs';
+
+/**
+ * Interactively pick a stack. Throws if stdin is not a TTY.
+ * @returns {Promise<string>} stack id
+ */
+export async function promptForStack() {
+  const stacks = listStacks();
+
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error(
+      'Non-interactive terminal: pass --stack <name> (e.g. --stack angular).',
+    );
+  }
+
+  const rl = readline.createInterface({ input, output });
+
+  try {
+    output.write('Select stack:\n');
+    for (let i = 0; i < stacks.length; i++) {
+      output.write(`  ${i + 1}) ${stacks[i].label} (${stacks[i].id})\n`);
+    }
+
+    while (true) {
+      const answer = (await rl.question(`Enter number [1-${stacks.length}]: `)).trim();
+
+      // Empty Enter → default to first stack when only one option.
+      if (answer === '' && stacks.length === 1) {
+        return stacks[0].id;
+      }
+
+      const index = Number.parseInt(answer, 10);
+
+      if (
+        Number.isInteger(index) &&
+        index >= 1 &&
+        index <= stacks.length
+      ) {
+        return stacks[index - 1].id;
+      }
+
+      output.write(`Invalid choice. Enter a number between 1 and ${stacks.length}.\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}

package/src/skills.mjs

@@ -0,0 +1,46 @@
+import { spawnSync } from 'node:child_process';
+
+export const SKILLS_ADD_COMMAND =
+  'pnpx skills add https://github.com/angular/skills';
+
+/**
+ * Install Angular agent skills via the skills CLI (pnpm/pnpx required by devEngines).
+ * @param {string} targetDir
+ * @param {{ dryRun?: boolean, skip?: boolean }} [options]
+ * @returns {{ skipped: boolean, dryRun?: boolean, status?: number | null }}
+ */
+export function runSkillsAdd(targetDir, options = {}) {
+  const { dryRun = false, skip = false } = options;
+
+  if (skip) {
+    console.log('Skipping skills install (--skip-skills).');
+    return { skipped: true };
+  }
+
+  if (dryRun) {
+    console.log(`[dry-run] Would run: ${SKILLS_ADD_COMMAND}`);
+    return { skipped: false, dryRun: true };
+  }
+
+  console.log(`Running: ${SKILLS_ADD_COMMAND}`);
+
+  // Single command string + shell avoids DEP0190 (args + shell:true).
+  const result = spawnSync(SKILLS_ADD_COMMAND, {
+    cwd: targetDir,
+    stdio: 'inherit',
+    shell: true,
+    env: process.env,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(
+      `${SKILLS_ADD_COMMAND} failed with exit code ${result.status ?? 'unknown'}`,
+    );
+  }
+
+  return { skipped: false, status: result.status };
+}

package/src/stacks.mjs

@@ -0,0 +1,20 @@
+/** Known stacks. Add an entry + templates/<id>/AGENTS.md for each new stack. */
+export const STACKS = {
+  angular: {
+    id: 'angular',
+    label: 'Angular',
+    agentsDir: 'angular',
+  },
+};
+
+export function listStacks() {
+  return Object.values(STACKS);
+}
+
+export function getStack(id) {
+  return STACKS[id] ?? null;
+}
+
+export function stackIds() {
+  return Object.keys(STACKS);
+}

package/templates/angular/.cursor/rules/angular-20.mdc

@@ -0,0 +1,135 @@
+---
+description: This rule provides comprehensive best practices and coding standards for Angular development, focusing on modern TypeScript, standalone components, signals, and performance optimizations.
+globs: ["**/*.{ts,html,scss,css}"]
+---
+
+# Angular Best Practices
+
+This project adheres to modern Angular best practices, emphasizing maintainability, performance, accessibility, and scalability.
+
+## TypeScript Best Practices
+
+* **Strict Type Checking:** Always enable and adhere to strict type checking. This helps catch errors early and improves code quality.
+* **Prefer Type Inference:** Allow TypeScript to infer types when they are obvious from the context. This reduces verbosity while maintaining type safety.
+    * **Bad:**
+        ```typescript
+        let name: string = 'Angular';
+        ```
+    * **Good:**
+        ```typescript
+        let name = 'Angular';
+        ```
+* **Avoid `any`:** Do not use the `any` type unless absolutely necessary as it bypasses type checking. Prefer `unknown` when a type is uncertain and you need to handle it safely.
+
+## Angular Best Practices
+
+* **Standalone Components:** Always use standalone components, directives, and pipes. Avoid using `NgModules` for new features or refactoring existing ones.
+* **Implicit Standalone:** When creating standalone components, you do not need to explicitly set `standalone: true` inside the `@Component`, `@Directive` and `@Pipe` decorators, as it is implied by default.
+    * **Bad:**
+        ```typescript
+        @Component({
+          standalone: true,
+          // ...
+        })
+        export class MyComponent {}
+        ```
+    * **Good:**
+        ```typescript
+        @Component({
+          // `standalone: true` is implied
+          // ...
+        })
+        export class MyComponent {}
+        ```
+* **Signals for State Management:** Utilize Angular Signals for reactive state management within components and services.
+* **Lazy Loading:** Implement lazy loading for feature routes to improve initial load times of your application.
+* **NgOptimizedImage:** Use `NgOptimizedImage` for all static images to automatically optimize image loading and performance.
+* **Host bindings:** Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead.
+
+## Components
+
+* **Single Responsibility:** Keep components small, focused, and responsible for a single piece of functionality.
+* **`input()` and `output()` Functions:** Prefer `input()` and `output()` functions over the `@Input()` and `@Output()` decorators for defining component inputs and outputs.
+    * **Old Decorator Syntax:**
+        ```typescript
+        @Input() userId!: string;
+        @Output() userSelected = new EventEmitter<string>();
+        ```
+    * **New Function Syntax:**
+        ```typescript
+        import { input, output } from '@angular/core';
+
+        // ...
+        userId = input<string>('');
+        userSelected = output<string>();
+        ```
+* **`computed()` for Derived State:** Use the `computed()` function from `@angular/core` for derived state based on signals.
+* **Inline Templates:** Prefer inline templates (template: `...`) for small components to keep related code together. For larger templates, use external HTML files.
+* **Reactive Forms:** Prefer Reactive forms over Template-driven forms for complex forms, validation, and dynamic controls due to their explicit, immutable, and synchronous nature.
+* **No `ngClass` / `NgClass`:** Do not use the `ngClass` directive. Instead, use native `class` bindings for conditional styling.
+    * **Bad:**
+        ```html
+        <section [ngClass]="{'active': isActive}"></section>
+        ```
+    * **Good:**
+        ```html
+        <section [class.active]="isActive"></section>
+        <section [class]="{'active': isActive}"></section>
+        <section [class]="myClasses"></section>
+        ```
+* **No `ngStyle` / `NgStyle`:** Do not use the `ngStyle` directive. Instead, use native `style` bindings for conditional inline styles.
+    * **Bad:**
+        ```html
+        <section [ngStyle]="{'font-size': fontSize + 'px'}"></section>
+        ```
+    * **Good:**
+        ```html
+        <section [style.font-size.px]="fontSize"></section>
+        <section [style]="myStyles"></section>
+        ```
+
+## State Management
+
+* **Signals for Local State:** Use signals for managing local component state.
+* **`computed()` for Derived State:** Leverage `computed()` for any state that can be derived from other signals.
+* **Pure and Predictable Transformations:** Ensure state transformations are pure functions (no side effects) and predictable.
+* **Signal value updates:** Do NOT use `mutate` on signals, use `update` or `set` instead.
+
+## Templates
+
+* **Simple Templates:** Keep templates as simple as possible, avoiding complex logic directly in the template. Delegate complex logic to the component's TypeScript code.
+* **Native Control Flow:** Use the new built-in control flow syntax (`@if`, `@for`, `@switch`) instead of the older structural directives (`*ngIf`, `*ngFor`, `*ngSwitch`).
+    * **Old Syntax:**
+        ```html
+        <section *ngIf="isVisible">Content</section>
+        <section *ngFor="let item of items">{{ item }}</section>
+        ```
+    * **New Syntax:**
+        ```html
+        @if (isVisible) {
+          <section>Content</section>
+        }
+        @for (item of items; track item.id) {
+          <section>{{ item }}</section>
+        }
+        ```
+* **Async Pipe:** Use the `async` pipe to handle observables in templates. This automatically subscribes and unsubscribes, preventing memory leaks.
+
+## Services
+
+* **Single Responsibility:** Design services around a single, well-defined responsibility.
+* **`providedIn: 'root'`:** Use the `providedIn: 'root'` option when declaring injectable services to ensure they are singletons and tree-shakable.
+* **`inject()` Function:** Prefer the `inject()` function over constructor injection when injecting dependencies, especially within `provide` functions, `computed` properties, or outside of constructor context.
+    * **Old Constructor Injection:**
+        ```typescript
+        constructor(private myService: MyService) {}
+        ```
+    * **New `inject()` Function:**
+        ```typescript
+        import { inject } from '@angular/core';
+
+        export class MyComponent {
+          private myService = inject(MyService);
+          // ...
+        }
+        ```

package/templates/angular/AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md — Angular
+
+Project instructions for coding agents. Prefer the nearest `AGENTS.md` to the file being edited.
+
+Angular/TypeScript standards: `.cursor/rules/angular-20.mdc`. Keep this file project-specific — do not duplicate those rules.
+
+## At a glance
+
+- Project: `<PROJECT_NAME>`
+- Angular: `<VERSION>` (standalone) · SSR: `<yes|no>`
+- Styling: `<Tailwind|SCSS|…>`
+- Package manager: `pnpm` only — never `npm` or `yarn`
+- Domains: `<DOMAIN_LIST>`
+
+## Commands
+
+Inspect `package.json` if a script name differs.
+
+| Action | Command |
+|--------|---------|
+| Install | `pnpm install` |
+| Dev | `pnpm start` |
+| Test | `pnpm test` |
+| Lint | `pnpm lint` |
+| Build | `pnpm build` |
+
+Run lint/build (and tests when relevant) before committing. Fix failures you introduce.
+
+## Hard rules
+
+- Do not add dependencies unless asked
+- Prefer existing shared components/services over new ones
+- Match existing folder and file layout
+- Never commit secrets or API keys
+
+## Architecture
+
+- App: `src/app/`
+- Features: `<PATHS>`
+- Shared UI (prefer these): `<COMPONENTS>`
+- Path aliases: `<e.g. @app/*>`
+- API pattern: `<methods, response shape, error helper>`
+- Models: `<naming / base types>`
+- Guards / interceptors / env: `<PATHS>`
+
+## Done checklist
+
+- [ ] Lint and build pass
+- [ ] Tests updated when behavior changes
+- [ ] No secrets in the diff

package/templates/angular/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+packages:
+  - '.'
+
+blockExoticSubdeps: true
+minimumReleaseAge: 4320

package/templates/shared/.cursor/commands/generate-pr-description.md

@@ -0,0 +1,70 @@
+# Generate PR Description
+
+Generate a copy-paste PR description for the current branch.
+
+## Destination branch
+
+Use the destination (base) branch from the text after this command, if provided.
+
+Examples:
+- `/generate-pr-description` → base `origin/dev`
+- `/generate-pr-description integration-dev-3` → base `origin/integration-dev-3`
+- `/generate-pr-description latest-release` → base `origin/latest-release`
+
+Rules:
+1. If the user provides a branch name (with or without `origin/`), use that as the base.
+2. If none is provided, default to `origin/dev`.
+3. If the user did not provide a base and the default looks wrong for the branch (e.g. release / hotfix naming), ask once which destination branch to use, then continue.
+4. Normalize short names to remote refs when available (`dev` → `origin/dev`).
+
+## Steps
+
+1. Resolve the destination branch using the rules above.
+2. Gather context with git (do **not** create `pr-diff.txt` or other temp files):
+   - `git status -sb`
+   - `git log --oneline <base>...HEAD`
+   - `git diff --stat <base>...HEAD`
+   - `git diff <base>...HEAD`
+3. Prefer the three-dot range (`<base>...HEAD`) so the description matches what GitHub/Azure DevOps shows for the PR.
+4. Infer any Jira key from branch name or commit messages (e.g. `feature-31575`, `CRA10-30756`, `Refs: CRA-10`). If unknown, leave a placeholder.
+5. Write the PR description (max ~300 words). Omit empty optional sections.
+6. Output **only** the markdown below — no preamble, no tool commentary, no offer to create the PR unless asked.
+
+## Output format
+
+```markdown
+# <concise PR title>
+
+## Overview
+<1-3 sentences: what this PR does and why>
+
+## Changes
+- <high-level change>
+- <high-level change>
+
+## Breaking changes
+None.
+<!-- or a short list -->
+
+## Related
+Refs: <JIRA-KEY or leave blank after the colon>
+Base: `<destination-branch>`
+```
+
+Optional sections — include only when clearly relevant:
+
+```markdown
+## Architectural notes
+<short note on design/pattern changes>
+
+## Performance
+<short note only if there are real perf/ops improvements>
+```
+
+## Writing rules
+
+- Focus on why and what, not file-by-file commentary.
+- Prefer product/feature language over implementation trivia.
+- Do not invent features, tests, or breaking changes not supported by the diff/commits.
+- Keep bullets short and specific.
+- Match this repo’s ticket style (Jira), not `#123` GitHub issues, unless the commits clearly use GitHub issue numbers.

package/templates/shared/.cursor/rules/conventional-commits.mdc

@@ -0,0 +1,63 @@
+---
+description: Use Conventional Commits format for all git commit messages
+alwaysApply: true
+---
+
+# Git commit messages
+
+Use Conventional Commits format. Write clear, concise messages in imperative mood (e.g. `add feature`, not `added feature`). Do not capitalize the first letter of the subject. Enclose file names in backticks.
+
+## Required structure
+
+Every commit message must follow this exact structure:
+
+```
+<type>(<scope>): <subject>
+
+- <bullet 1>
+- <bullet 2>
+```
+
+1. **Subject line** — one line, imperative mood.
+2. **Blank line**
+3. **Bullets** (optional if a single change fits in the subject) — one concrete change per bullet.
+
+## Bullet rules
+
+- Start each bullet with a lowercase verb in imperative mood: `fix`, `update`, `remove`, `use`, not `Fixed`, `Updated`, `Simplified`.
+- One file or one logical change per bullet.
+- Keep bullets short — state what changed, not why it is better.
+- Do not append justification phrases like "to enhance readability", "for improved type safety", or "for consistency and clarity".
+
+## Do not include
+
+- A closing summary paragraph. Never end with lines like "These changes improve code maintainability and performance across multiple components."
+- Past-tense verbs in bullets (`Simplified`, `Updated`, `Refactored`, `Enhanced`, `Adjusted`).
+- Vague bullets that describe intent instead of the change (`Adjusted API calls for consistency` → `align API params in `PendingInvoicesComponent``).
+
+## Good example
+
+```
+refactor(pending-invoices): streamline country and cash control data handling
+
+- simplify country mapping in `CountryCityPostalSuburb`
+- rename API params in `CashControlPullService`
+- use `takeUntilDestroyed` in `PendingInvoicesComponent`
+- store customer id without transformation in `PendingInvoicesResultsComponent`
+- tighten types in `shipment-documents.types.ts`
+- fix shipment address type in `AddressValidationModalComponent`
+```
+
+## Bad example (do not generate this)
+
+```
+refactor: streamline country and cash control data handling
+
+- Simplified country data mapping in `CountryCityPostalSuburb` to enhance readability and performance.
+- Updated `CashControlPullService` to use more descriptive parameter names for API calls.
+- Refactored `PendingInvoicesComponent` to utilize `takeUntilDestroyed` for better memory management.
+
+These changes improve code maintainability and performance across multiple components.
+```
+
+Problems: past-tense bullets, verbose justifications, and a forbidden closing summary.