@final-commerce/common 1.1.4-beta.4

package/bin/gate-setup.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * gate-setup — postinstall scaffolder.
+ *
+ * Runs automatically when a consumer installs @final-commerce/common.
+ * Creates missing governance config files and wires Husky hooks.
+ * Non-destructive: skips any file that already exists.
+ *
+ * Repo type is detected from dependencies:
+ *   @nestjs/core → backend-nestjs
+ *   react        → frontend-react
+ *   otherwise    → library
+ *
+ * Skips silently when:
+ *   - CI=true (no scaffolding needed in pipelines)
+ *   - No package.json found at project root
+ *   - Running inside @final-commerce/common itself
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ── guards ────────────────────────────────────────────────────────────────────
+
+// INIT_CWD is set by npm to the directory where npm install was invoked.
+// npm_config_local_prefix is a reliable fallback.
+const root = process.env.INIT_CWD ?? process.env.npm_config_local_prefix;
+
+if (!root) process.exit(0);
+if (process.env.CI) process.exit(0);
+
+const pkgPath = join(root, 'package.json');
+if (!existsSync(pkgPath)) process.exit(0);
+
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+if (pkg.name === '@final-commerce/common') process.exit(0);
+
+// ── detect repo type ──────────────────────────────────────────────────────────
+
+const allDeps = {
+  ...pkg.dependencies,
+  ...pkg.devDependencies,
+  ...pkg.peerDependencies,
+};
+
+const type = allDeps['@nestjs/core'] ? 'backend-nestjs' : allDeps['react'] ? 'frontend-react' : 'library';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+const ok = (msg) => process.stdout.write(`\x1b[32m✔  gate-setup: ${msg}\x1b[0m\n`);
+const skip = (msg) => process.stdout.write(`\x1b[90m–  gate-setup: ${msg} (already exists)\x1b[0m\n`);
+const warn = (msg) => process.stdout.write(`\x1b[33m⚠  gate-setup: ${msg}\x1b[0m\n`);
+const info = (msg) => process.stdout.write(`\x1b[36mℹ  gate-setup: ${msg}\x1b[0m\n`);
+
+function writeIfMissing(filePath, content, label) {
+  if (existsSync(filePath)) {
+    skip(label);
+    return;
+  }
+  writeFileSync(filePath, content, 'utf8');
+  ok(`Created ${label}`);
+}
+
+// ── 1. eslint.config.mjs ──────────────────────────────────────────────────────
+
+writeIfMissing(
+  join(root, 'eslint.config.mjs'),
+  `import config from '@final-commerce/common/eslint/${type}';\nexport default config;\n`,
+  'eslint.config.mjs',
+);
+
+// ── 2. tsconfig.json ──────────────────────────────────────────────────────────
+
+writeIfMissing(
+  join(root, 'tsconfig.json'),
+  JSON.stringify({ extends: `@final-commerce/common/typescript/${type}` }, null, 2) + '\n',
+  'tsconfig.json',
+);
+
+// ── 3. commitlint.config.mjs ──────────────────────────────────────────────────
+
+writeIfMissing(
+  join(root, 'commitlint.config.mjs'),
+  `import config from '@final-commerce/common/commitlint';\nexport default config;\n`,
+  'commitlint.config.mjs',
+);
+
+// ── 4. .nvmrc ────────────────────────────────────────────────────────────────
+
+writeIfMissing(join(root, '.nvmrc'), '22\n', '.nvmrc');
+
+// ── 5. husky hooks ────────────────────────────────────────────────────────────
+
+const huskyDir = join(root, '.husky');
+if (!existsSync(huskyDir)) mkdirSync(huskyDir, { recursive: true });
+
+function writeHook(name, content) {
+  const hookPath = join(huskyDir, name);
+  if (existsSync(hookPath)) {
+    skip(`.husky/${name}`);
+    return;
+  }
+  writeFileSync(hookPath, `#!/usr/bin/env sh\n\n${content}\n`, 'utf8');
+  chmodSync(hookPath, 0o755);
+  ok(`Created .husky/${name}`);
+}
+
+writeHook('pre-commit', 'npx gate-save');
+writeHook('pre-push', 'npx gate-done');
+
+const prepareCommitMsgHook = join(huskyDir, 'prepare-commit-msg');
+if (existsSync(prepareCommitMsgHook)) {
+  skip('.husky/prepare-commit-msg');
+} else {
+  writeFileSync(prepareCommitMsgHook, readFileSync(join(import.meta.dirname, 'prepare-commit-msg.sh'), 'utf8'), 'utf8');
+  chmodSync(prepareCommitMsgHook, 0o755);
+  ok('Created .husky/prepare-commit-msg');
+}
+
+writeHook('commit-msg', 'npx --no -- commitlint --edit "$1"');
+
+// ── 6. package.json mutations ─────────────────────────────────────────────────
+
+let dirty = false;
+
+// Prettier via package.json key — no separate config file needed.
+if (!pkg.prettier) {
+  pkg.prettier = '@final-commerce/common/prettier';
+  dirty = true;
+  ok('Added prettier key to package.json');
+}
+
+// prepare script.
+pkg.scripts ??= {};
+if (!pkg.scripts.prepare) {
+  pkg.scripts.prepare = 'husky';
+  dirty = true;
+  ok('Added prepare script to package.json');
+} else if (!pkg.scripts.prepare.includes('husky')) {
+  warn(`prepare script ("${pkg.scripts.prepare}") doesn't include husky — add it manually`);
+}
+
+// lint-staged config.
+if (!pkg['lint-staged']) {
+  const codeGlob = type === 'backend-nestjs' ? '*.{ts,js}' : '*.{ts,tsx}';
+  pkg['lint-staged'] = {
+    [codeGlob]: ['eslint --fix', 'prettier --write'],
+    '*.{json,md,yml,yaml}': ['prettier --write'],
+  };
+  dirty = true;
+  ok('Added lint-staged config to package.json');
+}
+
+// devDependencies — add husky, lint-staged, commitlint, and jira hook if missing.
+pkg.devDependencies ??= {};
+const devDepsToAdd = [
+  ['husky', '^9.0.0'],
+  ['lint-staged', '^15.0.0'],
+  ['@commitlint/cli', '^19.0.0'],
+  ['@commitlint/config-conventional', '^19.0.0'],
+];
+for (const [dep, version] of devDepsToAdd) {
+  if (!pkg.devDependencies[dep] && !pkg.dependencies?.[dep]) {
+    pkg.devDependencies[dep] = version;
+    dirty = true;
+    ok(`Added ${dep} to devDependencies`);
+  }
+}
+
+if (dirty) {
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  info('package.json updated — run npm install to activate new devDependencies');
+}
+
+// ── 7. i18n config (frontend-react + react-i18next only) ─────────────────────
+
+if (type === 'frontend-react' && allDeps['react-i18next']) {
+  // i18next-parser config — controls where the extractor looks for t() calls.
+  writeIfMissing(
+    join(root, 'i18next-parser.config.cjs'),
+    `/**
+ * i18next-parser config — used by gate-i18n-sync to extract t() keys.
+ * Output goes to node_modules/.cache/ — the canonical bundles in src/locales/
+ * are written by the sync script after a round-trip with the mt server.
+ */
+module.exports = {
+  input: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.test.{ts,tsx}',
+    '!src/**/*.spec.{ts,tsx}',
+    '!src/test/**',
+  ],
+  output: 'node_modules/.cache/i18next-extract/$LOCALE.json',
+  locales: ['en'],
+  defaultNamespace: 'translation',
+  keySeparator: false,
+  namespaceSeparator: false,
+  keepRemoved: false,
+  createOldCatalogs: false,
+  sort: true,
+  verbose: false,
+  failOnWarnings: false,
+  failOnUpdate: false,
+};\n`,
+    'i18next-parser.config.cjs',
+  );
+
+  // fc-i18n config in package.json — gate-save reads this to activate the sync.
+  if (!pkg['fc-i18n']) {
+    const slug = pkg.name?.replace(/^@[^/]+\//, '') ?? pkg.name ?? 'my-project';
+    pkg['fc-i18n'] = { slug };
+    ok(
+      `Added fc-i18n config to package.json (slug: "${slug}") — set i18nIndexPath if you use a SUPPORTED_LOCALES marker`,
+    );
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  } else {
+    skip('fc-i18n config in package.json');
+  }
+}
+
+info(`Done (${type})`);

package/bin/gate-start.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * gate-start — Developer session initialiser.
+ *
+ * 1. Verifies @final-commerce/common in node_modules matches latest registry release.
+ * 2. Prompts for (or accepts via arg/env) a Jira ticket ID.
+ *
+ * Branch checkout is handled by the tasks-manager workspace tooling.
+ *
+ * Usage:
+ *   gate-start [TICKET-ID]
+ *   JIRA_TICKET_ID=FI-1234 gate-start
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const PKG_NAME = '@final-commerce/common';
+const TICKET_RE = /^[A-Z]+-\d+$/;
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function capture(cmd) {
+  return spawnSync(cmd, { shell: true, encoding: 'utf8' });
+}
+
+function fail(msg) {
+  process.stderr.write(`\x1b[31m✖  ${msg}\x1b[0m\n`);
+  process.exit(1);
+}
+
+function info(msg) {
+  process.stdout.write(`\x1b[36mℹ  ${msg}\x1b[0m\n`);
+}
+
+function ok(msg) {
+  process.stdout.write(`\x1b[32m✔  ${msg}\x1b[0m\n`);
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// ── 1. upstream version check ─────────────────────────────────────────────────
+
+info(`Checking ${PKG_NAME} upstream version…`);
+
+const localPkgPath = resolve(process.cwd(), 'node_modules', PKG_NAME, 'package.json');
+
+if (!existsSync(localPkgPath)) {
+  fail(`${PKG_NAME} is not installed locally.\nRun: npm install ${PKG_NAME}`);
+}
+
+const localVersion = JSON.parse(readFileSync(localPkgPath, 'utf8')).version;
+
+// Rely on .npmrc scope mapping — do not override with --registry flag,
+// which would bypass the @final-commerce → npm.pkg.github.com mapping.
+const regResult = capture(`npm view ${PKG_NAME} version 2>&1`);
+
+if (regResult.status !== 0) {
+  fail(
+    `Could not fetch latest version of ${PKG_NAME} from registry.\n` +
+      `Error: ${regResult.stdout.trim()}\n` +
+      `Ensure .npmrc is present and NPM_REGISTRY_TOKEN is set.`,
+  );
+}
+
+const latestVersion = regResult.stdout.trim();
+
+if (localVersion !== latestVersion) {
+  fail(
+    `${PKG_NAME} is out of date.\n` +
+      `  Installed : ${localVersion}\n` +
+      `  Registry  : ${latestVersion}\n` +
+      `Run: npm install ${PKG_NAME}@latest`,
+  );
+}
+
+ok(`${PKG_NAME}@${localVersion} is current.`);
+
+// ── 2. Jira ticket ID ─────────────────────────────────────────────────────────
+
+let ticketId = (process.env.JIRA_TICKET_ID ?? process.argv[2] ?? '').toUpperCase();
+
+if (!ticketId) {
+  ticketId = (await ask('\nJira ticket ID (e.g. FI-1234): ')).toUpperCase();
+}
+
+if (!TICKET_RE.test(ticketId)) {
+  fail(`"${ticketId}" is not a valid Jira ticket ID. Expected format: PROJECT-123`);
+}
+
+ok(`Ticket ${ticketId} confirmed. Ready to work.`);

package/bin/prepare-commit-msg.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
+if [ -z "$BRANCH" ]; then exit 0; fi
+
+# Skip protected branches
+if echo "$BRANCH" | grep -qE '^(main|master|develop|pre-prod|release-staging.*)$'; then exit 0; fi
+
+TICKET=$(echo "$BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+if [ -z "$TICKET" ]; then exit 0; fi
+
+MSG_FILE="$1"
+CURRENT=$(cat "$MSG_FILE")
+if echo "$CURRENT" | grep -q "$TICKET"; then exit 0; fi
+
+awk -v ticket="[$TICKET]" 'NR==1{print $0 " " ticket; next}{print}' "$MSG_FILE" > "$MSG_FILE.tmp" && mv "$MSG_FILE.tmp" "$MSG_FILE"

package/commitlint/index.mjs

@@ -0,0 +1,14 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'refactor', 'style', 'docs', 'test', 'chore', 'build', 'ci', 'perf', 'revert'],
+    ],
+    'subject-empty':      [2, 'never'],
+    'type-empty':         [2, 'never'],
+    'subject-min-length': [2, 'always', 10],
+    'header-max-length':  [2, 'always', 120],
+  },
+};