@produck/agent-toolkit 0.4.0 → 0.6.0

package/bin/command/sync-editorconfig/index.mjs

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSingle, hasFlag } from '../shared/args.mjs';
+import { printTextResource } from '../shared/text-resource.mjs';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const EDITORCONFIG_FILE = '.editorconfig';
+const TEMPLATE_FILE = path.resolve(COMMAND_DIR, 'editorconfig.template');
+
+const REQUIRED_EDITORCONFIG_CONTENT = fs.readFileSync(TEMPLATE_FILE, 'utf8');
+
+// Required key-value pairs for validation
+const REQUIRED_SECTIONS = {
+  root: {
+    line: 'root = true',
+  },
+  '*': {
+    keys: {
+      charset: 'utf-8',
+      indent_style: 'space',
+      indent_size: '2',
+      trim_trailing_whitespace: 'true',
+    },
+  },
+  '*.{yml,yaml}': {
+    keys: {
+      indent_style: 'space',
+      indent_size: '2',
+    },
+  },
+  '*.md': {
+    keys: {
+      trim_trailing_whitespace: 'false',
+      max_line_length: '80',
+    },
+  },
+};
+
+export function printSyncEditorconfigHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function parseEditorconfig(content) {
+  const sections = {};
+  let currentSection = null;
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith(';')) {
+      continue;
+    }
+
+    // Check for section header
+    const sectionMatch = trimmed.match(/^\[(.+)\]$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      sections[currentSection] = {};
+      continue;
+    }
+
+    // Check for root = true
+    const rootMatch = trimmed.match(/^root\s*=\s*(.+)$/i);
+    if (rootMatch && !currentSection) {
+      sections._root = rootMatch[1].trim().toLowerCase();
+      continue;
+    }
+
+    // Parse key-value pair
+    if (currentSection) {
+      const kvMatch = trimmed.match(/^([^=]+)\s*=\s*(.+)$/);
+      if (kvMatch) {
+        sections[currentSection][kvMatch[1].trim().toLowerCase()] = kvMatch[2].trim().toLowerCase();
+      }
+    }
+  }
+
+  return sections;
+}
+
+function validateEditorconfig(sections) {
+  const mismatches = [];
+
+  // Check root
+  if (sections._root !== 'true') {
+    mismatches.push({ section: '_root', expected: 'true', actual: sections._root || 'missing' });
+  }
+
+  // Check each required section
+  for (const [sectionName, config] of Object.entries(REQUIRED_SECTIONS)) {
+    if (sectionName === 'root') continue;
+
+    if (!sections[sectionName]) {
+      mismatches.push({ section: `[${sectionName}]`, expected: 'present', actual: 'missing' });
+      continue;
+    }
+
+    if (config.keys) {
+      for (const [key, expectedValue] of Object.entries(config.keys)) {
+        const actualValue = sections[sectionName][key];
+        if (actualValue !== expectedValue) {
+          mismatches.push({
+            section: `[${sectionName}]`,
+            key,
+            expected: expectedValue,
+            actual: actualValue || 'missing',
+          });
+        }
+      }
+    }
+  }
+
+  return mismatches;
+}
+
+function buildUpdatedContent(existingContent) {
+  const existingSections = parseEditorconfig(existingContent);
+  const lines = [];
+
+  // Add root if missing
+  if (existingSections._root !== 'true') {
+    lines.push('root = true');
+  }
+
+  // Process each required section
+  for (const [sectionName, config] of Object.entries(REQUIRED_SECTIONS)) {
+    if (sectionName === 'root') continue;
+
+    const existingSection = existingSections[sectionName] || {};
+    const missingKeys = [];
+
+    if (config.keys) {
+      for (const [key, expectedValue] of Object.entries(config.keys)) {
+        if (existingSection[key] !== expectedValue) {
+          missingKeys.push({ key, value: expectedValue });
+        }
+      }
+    }
+
+    if (missingKeys.length > 0 || !existingSections[sectionName]) {
+      lines.push('');
+      lines.push(`[${sectionName}]`);
+      for (const { key, value } of missingKeys) {
+        lines.push(`${key} = ${value}`);
+      }
+    }
+  }
+
+  // If no updates needed, return original
+  // c8 ignore next 3
+  if (lines.length === 0) {
+    return existingContent;
+  }
+
+  // Append missing entries to existing content
+  return existingContent.trimEnd() + lines.join('\n') + '\n';
+}
+
+function readFileIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+export function runSyncEditorconfig(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const check = hasFlag(options, '--check');
+  const dryRun = hasFlag(options, '--dry-run') && !check;
+  const jsonFile = getSingle(options, '--json', '');
+  const mode = check ? 'check' : dryRun ? 'dry-run' : 'sync';
+
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  const editorconfigPath = path.resolve(cwd, EDITORCONFIG_FILE);
+  const currentContent = readFileIfExists(editorconfigPath);
+  const fileExists = currentContent !== null;
+
+  const sections = currentContent ? parseEditorconfig(currentContent) : {};
+  const mismatches = validateEditorconfig(sections);
+  const requiresUpdate = mismatches.length > 0 || !fileExists;
+
+  let plannedContent = null;
+  if (requiresUpdate) {
+    plannedContent = fileExists
+      ? buildUpdatedContent(currentContent)
+      : REQUIRED_EDITORCONFIG_CONTENT;
+  }
+
+  if (mode === 'sync' && requiresUpdate && plannedContent) {
+    fs.writeFileSync(editorconfigPath, plannedContent, 'utf8');
+  }
+
+  const report = {
+    cwd,
+    mode,
+    ok: true,
+    editorconfigPath,
+    required: {
+      file: EDITORCONFIG_FILE,
+    },
+    status: {
+      fileExistsBefore: fileExists,
+      mismatchesBefore: mismatches,
+      fileExistsAfter: requiresUpdate && mode === 'sync' ? true : fileExists,
+      mismatchesAfter: requiresUpdate && mode === 'sync' ? [] : mismatches,
+      updated: requiresUpdate && mode === 'sync',
+    },
+  };
+
+  if (mode === 'check' && requiresUpdate) {
+    report.ok = false;
+  }
+
+  if (jsonFile) {
+    const outPath = path.resolve(cwd, jsonFile);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) {
+    process.exit(2);
+  }
+}

package/bin/command/sync-eslint-config/help.txt

@@ -0,0 +1,18 @@
+Usage:
+  agent-toolkit sync-eslint-config [--cwd <dir>] [--check] [--dry-run]
+    [--json <file>]
+
+Behavior:
+  - Applies organization-required root lint script:
+    - scripts.produck:lint = npm exec -- eslint --fix . --max-warnings=0 && npm run lint --if-present
+  - Applies organization-required root ESLint config file:
+    - eslint.config.mjs
+  - If eslint.config.mjs exists and does not use @produck/eslint-rules,
+    append Produck integration at the tail of export default array
+  - Applies organization-required root managed devDependency:
+    - devDependencies.@produck/eslint-rules = <latest-version-resolved-at-runtime>
+
+Rules:
+  - --check validates without writing and exits non-zero on mismatch
+  - --dry-run prints planned changes without writing
+  - --check takes precedence over --dry-run

package/bin/command/sync-eslint-config/index.mjs

@@ -0,0 +1,248 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { getSingle, hasFlag } from '../shared/args.mjs';
+import { printTextResource } from '../shared/text-resource.mjs';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const PACKAGE_ROOT = path.resolve(COMMAND_DIR, '../../..');
+const TOOLKIT_PACKAGE_JSON = path.resolve(PACKAGE_ROOT, 'package.json');
+const ESLINT_CONFIG_FILE = 'eslint.config.mjs';
+
+const REQUIRED_LINT_SCRIPT_KEY = 'produck:lint';
+const REQUIRED_LINT_SCRIPT_VALUE =
+  'npm exec -- eslint --fix . --max-warnings=0 && npm run lint --if-present';
+const REQUIRED_ESLINT_CONFIG = `import globals from 'globals';
+import pluginJs from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import * as ProduckRule from '@produck/eslint-rules';
+
+export default [
+  { files: ['**/*.{js,mjs,cjs,ts,mts}'] },
+  { languageOptions: { globals: { ...globals.browser, ...globals.node } } },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  ProduckRule.config,
+  ProduckRule.excludeGitIgnore(import.meta.url),
+];
+`;
+
+export function printSyncEslintConfigHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function parseJsonFile(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    console.error(`${label} is not valid JSON: ${filePath}`);
+    process.exit(2);
+  }
+}
+
+function readFileIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function getRequiredEslintRulesDevDependency() {
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const latestResult = spawnSync(npmCommand, ['view', '@produck/eslint-rules', 'version'], {
+    encoding: 'utf8',
+  });
+
+  const latestVersion = String(latestResult.stdout || '').trim();
+  if (latestResult.status === 0 && latestVersion) {
+    return latestVersion;
+  }
+
+  const pkg = parseJsonFile(TOOLKIT_PACKAGE_JSON, 'Toolkit package.json');
+  const version = typeof pkg.version === 'string' ? pkg.version.trim() : '';
+
+  if (!version) {
+    console.error(`Toolkit package version is missing: ${TOOLKIT_PACKAGE_JSON}`);
+    process.exit(2);
+  }
+
+  return version;
+}
+
+function patchEslintConfig(existing) {
+  if (existing.includes('@produck/eslint-rules')) {
+    return { ok: true, patched: false, output: existing };
+  }
+
+  const importRegex = /^import\s.+;\s*$/gm;
+  let lastImport = null;
+  let match = importRegex.exec(existing);
+  while (match) {
+    lastImport = match;
+    match = importRegex.exec(existing);
+  }
+
+  if (!lastImport) {
+    return { ok: false, patched: false, output: existing };
+  }
+
+  const importInsertAt = lastImport.index + lastImport[0].length;
+  let output =
+    `${existing.slice(0, importInsertAt)}\nimport * as ProduckRule from '@produck/eslint-rules';` +
+    existing.slice(importInsertAt);
+
+  const exportStart = output.indexOf('export default [');
+  const exportEnd = output.lastIndexOf('];');
+  if (exportStart === -1 || exportEnd === -1 || exportEnd < exportStart) {
+    return { ok: false, patched: false, output: existing };
+  }
+
+  output =
+    `${output.slice(0, exportEnd)}  ProduckRule.config,\n  ProduckRule.excludeGitIgnore(import.meta.url),\n` +
+    output.slice(exportEnd);
+
+  if (!output.endsWith('\n')) {
+    output = `${output}\n`;
+  }
+
+  return { ok: true, patched: true, output };
+}
+
+export function runSyncEslintConfig(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const check = hasFlag(options, '--check');
+  const dryRun = hasFlag(options, '--dry-run') && !check;
+  const jsonFile = getSingle(options, '--json', '');
+  const mode = check ? 'check' : dryRun ? 'dry-run' : 'sync';
+
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  const rootPackageJsonPath = path.resolve(cwd, 'package.json');
+  if (!fs.existsSync(rootPackageJsonPath)) {
+    console.error(`Root package.json does not exist: ${rootPackageJsonPath}`);
+    process.exit(2);
+  }
+
+  const pkg = parseJsonFile(rootPackageJsonPath, 'Root package.json');
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === 'object' && !Array.isArray(pkg.scripts)
+      ? { ...pkg.scripts }
+      : {};
+  const devDependencies =
+    pkg.devDependencies &&
+    typeof pkg.devDependencies === 'object' &&
+    !Array.isArray(pkg.devDependencies)
+      ? { ...pkg.devDependencies }
+      : {};
+
+  const previousLint =
+    typeof scripts[REQUIRED_LINT_SCRIPT_KEY] === 'string'
+      ? scripts[REQUIRED_LINT_SCRIPT_KEY]
+      : null;
+  const previousEslintRules =
+    typeof devDependencies['@produck/eslint-rules'] === 'string'
+      ? devDependencies['@produck/eslint-rules']
+      : null;
+
+  const requiredEslintRulesDependency = getRequiredEslintRulesDevDependency();
+
+  const eslintConfigPath = path.resolve(cwd, ESLINT_CONFIG_FILE);
+  const previousEslintConfig = readFileIfExists(eslintConfigPath);
+
+  const matchesRequiredLint = previousLint === REQUIRED_LINT_SCRIPT_VALUE;
+  const matchesRequiredEslintRules = previousEslintRules === requiredEslintRulesDependency;
+
+  let eslintConfigAction = 'unchanged';
+  let matchesRequiredEslintConfig = false;
+  let nextEslintConfigText = previousEslintConfig;
+
+  if (previousEslintConfig === null) {
+    eslintConfigAction = 'initialized';
+    nextEslintConfigText = REQUIRED_ESLINT_CONFIG;
+  } else if (previousEslintConfig === REQUIRED_ESLINT_CONFIG) {
+    matchesRequiredEslintConfig = true;
+  } else if (previousEslintConfig.includes('@produck/eslint-rules')) {
+    matchesRequiredEslintConfig = true;
+  } else {
+    const patched = patchEslintConfig(previousEslintConfig);
+    if (patched.ok) {
+      eslintConfigAction = 'patched';
+      nextEslintConfigText = patched.output;
+    } else {
+      eslintConfigAction = 'unpatchable';
+    }
+  }
+
+  const requiresUpdate =
+    !matchesRequiredLint || !matchesRequiredEslintRules || !matchesRequiredEslintConfig;
+  const hasUnpatchableEslintConfig = eslintConfigAction === 'unpatchable';
+
+  if (mode === 'sync' && requiresUpdate && !hasUnpatchableEslintConfig) {
+    scripts[REQUIRED_LINT_SCRIPT_KEY] = REQUIRED_LINT_SCRIPT_VALUE;
+    pkg.scripts = scripts;
+
+    devDependencies['@produck/eslint-rules'] = requiredEslintRulesDependency;
+    pkg.devDependencies = devDependencies;
+
+    fs.writeFileSync(rootPackageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(eslintConfigPath, nextEslintConfigText || REQUIRED_ESLINT_CONFIG, 'utf8');
+  }
+
+  const report = {
+    cwd,
+    mode,
+    ok: true,
+    rootPackageJsonPath,
+    required: {
+      lintScriptKey: REQUIRED_LINT_SCRIPT_KEY,
+      lintScriptValue: REQUIRED_LINT_SCRIPT_VALUE,
+      eslintRulesVersion: requiredEslintRulesDependency,
+      eslintConfigPath: path.relative(cwd, eslintConfigPath),
+      eslintConfigAction,
+    },
+    status: {
+      matchesRequiredLintBefore: matchesRequiredLint,
+      matchesRequiredEslintRulesBefore: matchesRequiredEslintRules,
+      matchesRequiredEslintConfigBefore: matchesRequiredEslintConfig,
+      matchesRequiredLintAfter:
+        requiresUpdate && mode === 'sync' && !hasUnpatchableEslintConfig
+          ? true
+          : matchesRequiredLint,
+      matchesRequiredEslintRulesAfter:
+        requiresUpdate && mode === 'sync' && !hasUnpatchableEslintConfig
+          ? true
+          : matchesRequiredEslintRules,
+      matchesRequiredEslintConfigAfter:
+        requiresUpdate && mode === 'sync' && !hasUnpatchableEslintConfig
+          ? true
+          : matchesRequiredEslintConfig,
+      updated: requiresUpdate && mode === 'sync' && !hasUnpatchableEslintConfig,
+      hasUnpatchableEslintConfig,
+    },
+  };
+
+  if (mode === 'check' && (requiresUpdate || hasUnpatchableEslintConfig)) {
+    report.ok = false;
+  }
+  if ((mode === 'sync' || mode === 'dry-run') && hasUnpatchableEslintConfig) {
+    report.ok = false;
+  }
+
+  if (jsonFile) {
+    const outPath = path.resolve(cwd, jsonFile);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) {
+    process.exit(2);
+  }
+}

package/bin/command/sync-husky-hooks/help.txt

@@ -3,15 +3,7 @@ Usage:
     [--json <file>]
 
 Behavior:
-  - Applies organization-required root scripts for local hook gates:
-    - scripts.prepare = husky
-    - scripts.produck:precommit-check = npm run format:check && npm run lint
-  - Applies organization-required root managed devDependencies:
-    - devDependencies.c8 = <fixed-version-from-baseline>
-    - devDependencies.husky = <fixed-version-from-baseline>
-    - devDependencies.lerna = <fixed-version-from-baseline>
-    - devDependencies.@produck/agent-toolkit = <latest-version-resolved-at-runtime>
-  - Applies organization-required hook files:
+  - Applies organization-required hook files only:
     - .husky/pre-commit
     - .husky/commit-msg
   - commit-msg hook validates message via local node_modules toolkit path