@produck/agent-toolkit 0.2.1 → 0.4.0

package/bin/command/sync-coverage-script/help.txt

@@ -0,0 +1,22 @@
+Usage:
+  agent-toolkit sync-coverage-script [--cwd <dir>]
+    [--workspace <path>] ... [--check] [--dry-run] [--json <file>]
+
+Behavior:
+  - Applies organization-required coverage script to workspace package.json files
+  - Organization-reserved script key is scripts.produck:coverage
+  - Applies organization-required pinned local c8 devDependency to workspace
+    package.json files
+  - Target script is rendered from organization tooling baseline file
+    (lookup order):
+    1) .github/distribution/produck/tooling-version-baseline.json
+    2) publish-assets/instructions/produck/tooling-version-baseline.json
+  - Baseline template:
+    c8 --reporter=lcov --reporter=html --reporter=text-summary npm test
+
+Rules:
+  - When --workspace is omitted, root package.json workspaces are used
+  - Root workspaces must be explicit paths (no glob tokens)
+  - Workspace package.json files must pin devDependencies.c8 to baseline version
+  - --check validates without writing and exits non-zero on mismatch
+  - --dry-run prints planned changes without writing

package/bin/command/sync-coverage-script/index.mjs

@@ -0,0 +1,275 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getMulti, 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 REPO_ROOT = path.resolve(PACKAGE_ROOT, '../..');
+const TOOLING_BASELINE_CANDIDATE_PATHS = [
+  path.resolve(REPO_ROOT, '.github/distribution/produck/tooling-version-baseline.json'),
+  path.resolve(PACKAGE_ROOT, 'publish-assets/instructions/produck/tooling-version-baseline.json'),
+];
+const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
+const REQUIRED_COVERAGE_SCRIPT_KEY = 'produck:coverage';
+
+export function printSyncCoverageScriptHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function loadToolingBaseline() {
+  const toolingBaselinePath = TOOLING_BASELINE_CANDIDATE_PATHS.find((candidatePath) => {
+    return fs.existsSync(candidatePath);
+  });
+
+  if (!toolingBaselinePath) {
+    console.error('Tooling baseline file does not exist in expected locations:');
+    for (const candidatePath of TOOLING_BASELINE_CANDIDATE_PATHS) {
+      console.error(`- ${candidatePath}`);
+    }
+    process.exit(2);
+  }
+
+  const baseline = parseJsonFile(toolingBaselinePath, 'Tooling baseline file');
+  const c8Version = baseline?.tools?.c8?.version;
+  const coverageTemplate = baseline?.coverage?.scriptTemplate;
+
+  if (typeof baseline.schemaVersion !== 'number') {
+    console.error(`Tooling baseline schemaVersion must be a number: ${toolingBaselinePath}`);
+    process.exit(2);
+  }
+
+  if (typeof c8Version !== 'string' || c8Version.trim() === '') {
+    console.error(
+      `Tooling baseline tools.c8.version must be a non-empty string: ${toolingBaselinePath}`,
+    );
+    process.exit(2);
+  }
+
+  if (typeof coverageTemplate !== 'string' || coverageTemplate.trim() === '') {
+    console.error(
+      `Tooling baseline coverage.scriptTemplate must be a non-empty string: ${toolingBaselinePath}`,
+    );
+    process.exit(2);
+  }
+
+  return {
+    baseline,
+    toolingBaselinePath,
+  };
+}
+
+function buildRequiredCoverageScript(baseline) {
+  const c8Version = String(baseline.tools.c8.version);
+  const coverageTemplate = String(baseline.coverage.scriptTemplate);
+  return coverageTemplate.replace(/\{c8\.version\}/g, c8Version);
+}
+
+function buildRequiredC8DevDependency(baseline) {
+  return String(baseline.tools.c8.version);
+}
+
+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 resolveWorkspacePaths(cwd, options) {
+  const manual = getMulti(options, '--workspace');
+  if (manual.length > 0) {
+    return manual;
+  }
+
+  const rootPackageJsonPath = path.resolve(cwd, 'package.json');
+  if (!fs.existsSync(rootPackageJsonPath)) {
+    console.error(`Root package.json does not exist: ${rootPackageJsonPath}`);
+    process.exit(2);
+  }
+
+  const rootPackageJson = parseJsonFile(rootPackageJsonPath, 'Root package.json');
+  if (!Array.isArray(rootPackageJson.workspaces)) {
+    console.error('Root package.json `workspaces` must be an explicit array');
+    process.exit(2);
+  }
+
+  const workspaces = rootPackageJson.workspaces.map((entry) => String(entry));
+  if (workspaces.length === 0) {
+    console.error('Root package.json `workspaces` must not be empty');
+    process.exit(2);
+  }
+
+  const hasGlob = workspaces.some((entry) => GLOB_TOKEN_PATTERN.test(entry));
+  if (hasGlob) {
+    console.error('Root package.json `workspaces` must use explicit paths without glob tokens');
+    process.exit(2);
+  }
+
+  return workspaces;
+}
+
+function reconcileCoverageScript(
+  cwd,
+  workspacePath,
+  mode,
+  requiredCoverageScript,
+  requiredC8Version,
+) {
+  const packageDir = path.resolve(cwd, workspacePath);
+  const packageJsonPath = path.resolve(packageDir, 'package.json');
+
+  const result = {
+    workspacePath,
+    packageDir,
+    packageJsonPath,
+    exists: false,
+    validJson: false,
+    previousCoverage: null,
+    coverageScript: null,
+    previousC8DevDependency: null,
+    c8DevDependency: null,
+    matchesRequiredCoverageBefore: false,
+    matchesRequiredCoverageAfter: false,
+    matchesRequiredC8DevDependencyBefore: false,
+    matchesRequiredC8DevDependencyAfter: false,
+    updated: false,
+    error: '',
+  };
+
+  if (!fs.existsSync(packageJsonPath)) {
+    result.error = `Workspace package.json does not exist: ${workspacePath}`;
+    return result;
+  }
+  result.exists = true;
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    result.validJson = true;
+  } catch {
+    result.error = `Workspace package.json is not valid JSON: ${workspacePath}`;
+    return result;
+  }
+
+  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 previousCoverage =
+    typeof scripts[REQUIRED_COVERAGE_SCRIPT_KEY] === 'string'
+      ? scripts[REQUIRED_COVERAGE_SCRIPT_KEY]
+      : null;
+  const previousC8DevDependency =
+    typeof devDependencies.c8 === 'string' ? devDependencies.c8 : null;
+  result.previousCoverage = previousCoverage;
+  result.previousC8DevDependency = previousC8DevDependency;
+  result.matchesRequiredCoverageBefore = previousCoverage === requiredCoverageScript;
+  result.matchesRequiredC8DevDependencyBefore = previousC8DevDependency === requiredC8Version;
+
+  if (
+    (!result.matchesRequiredCoverageBefore || !result.matchesRequiredC8DevDependencyBefore) &&
+    mode === 'sync'
+  ) {
+    scripts[REQUIRED_COVERAGE_SCRIPT_KEY] = requiredCoverageScript;
+    devDependencies.c8 = requiredC8Version;
+    pkg.scripts = scripts;
+    pkg.devDependencies = devDependencies;
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+    result.updated = true;
+  }
+
+  result.coverageScript =
+    mode === 'sync' && !result.matchesRequiredCoverageBefore
+      ? requiredCoverageScript
+      : previousCoverage;
+  result.c8DevDependency =
+    mode === 'sync' && !result.matchesRequiredC8DevDependencyBefore
+      ? requiredC8Version
+      : previousC8DevDependency;
+
+  result.matchesRequiredCoverageAfter = result.updated || result.matchesRequiredCoverageBefore;
+  result.matchesRequiredC8DevDependencyAfter =
+    result.updated || result.matchesRequiredC8DevDependencyBefore;
+  return result;
+}
+
+export function runSyncCoverageScript(options) {
+  const cwd = path.resolve(getSingle(options, '--cwd', process.cwd()));
+  const check = hasFlag(options, '--check');
+  const dryRun = hasFlag(options, '--dry-run');
+  const jsonFile = getSingle(options, '--json', '');
+  const { baseline: toolingBaseline, toolingBaselinePath } = loadToolingBaseline();
+  const requiredCoverageScript = buildRequiredCoverageScript(toolingBaseline);
+  const requiredC8Version = buildRequiredC8DevDependency(toolingBaseline);
+
+  if (!fs.existsSync(cwd)) {
+    console.error(`CWD does not exist: ${cwd}`);
+    process.exit(2);
+  }
+
+  const workspacePaths = resolveWorkspacePaths(cwd, options);
+  const mode = dryRun ? 'dry-run' : check ? 'check' : 'sync';
+
+  const report = {
+    cwd,
+    mode,
+    toolingBaselinePath,
+    toolingBaseline: {
+      schemaVersion: toolingBaseline.schemaVersion,
+      c8Version: toolingBaseline.tools.c8.version,
+    },
+    requiredCoverageScript,
+    requiredC8DevDependency: requiredC8Version,
+    workspaces: workspacePaths,
+    results: [],
+    ok: true,
+  };
+
+  for (const workspacePath of workspacePaths) {
+    const effectiveMode = mode === 'sync' ? 'sync' : 'check';
+    const item = reconcileCoverageScript(
+      cwd,
+      workspacePath,
+      effectiveMode,
+      requiredCoverageScript,
+      requiredC8Version,
+    );
+    report.results.push(item);
+
+    if (item.error) {
+      report.ok = false;
+      continue;
+    }
+
+    if (
+      mode === 'check' &&
+      (!item.matchesRequiredCoverageAfter || !item.matchesRequiredC8DevDependencyAfter)
+    ) {
+      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

@@ -0,0 +1,22 @@
+Usage:
+  agent-toolkit sync-husky-hooks [--cwd <dir>] [--check] [--dry-run]
+    [--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:
+    - .husky/pre-commit
+    - .husky/commit-msg
+  - commit-msg hook validates message via local node_modules toolkit path
+
+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-husky-hooks/index.mjs

@@ -0,0 +1,267 @@
+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 REPO_ROOT = path.resolve(PACKAGE_ROOT, '../..');
+const TOOLKIT_PACKAGE_JSON = path.resolve(PACKAGE_ROOT, 'package.json');
+const TOOLING_BASELINE_CANDIDATE_PATHS = [
+  path.resolve(REPO_ROOT, '.github/distribution/produck/tooling-version-baseline.json'),
+  path.resolve(PACKAGE_ROOT, 'publish-assets/instructions/produck/tooling-version-baseline.json'),
+];
+
+const REQUIRED_PREPARE_SCRIPT = 'husky';
+const REQUIRED_PRECOMMIT_CHECK_SCRIPT_KEY = 'produck:precommit-check';
+const REQUIRED_PRECOMMIT_CHECK_SCRIPT_VALUE = 'npm run format:check && npm run lint';
+
+const REQUIRED_PRE_COMMIT_HOOK = '#!/usr/bin/env sh\nnpm run produck:precommit-check\n';
+const REQUIRED_COMMIT_MSG_HOOK =
+  '#!/usr/bin/env sh\nnode ./node_modules/@produck/agent-toolkit/bin/agent-toolkit.mjs validate-commit-msg --file "$1"\n';
+
+export function printSyncHuskyHooksHelp() {
+  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 getRequiredToolkitDevDependency() {
+  const overrideVersion = String(process.env.PRODUCK_TOOLKIT_VERSION_OVERRIDE || '').trim();
+  if (overrideVersion) {
+    return overrideVersion;
+  }
+
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const latestResult = spawnSync(npmCommand, ['view', '@produck/agent-toolkit', '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 loadToolingBaseline() {
+  const toolingBaselinePath = TOOLING_BASELINE_CANDIDATE_PATHS.find((candidatePath) => {
+    return fs.existsSync(candidatePath);
+  });
+
+  if (!toolingBaselinePath) {
+    console.error('Tooling baseline file does not exist in expected locations:');
+    for (const candidatePath of TOOLING_BASELINE_CANDIDATE_PATHS) {
+      console.error(`- ${candidatePath}`);
+    }
+    process.exit(2);
+  }
+
+  const baseline = parseJsonFile(toolingBaselinePath, 'Tooling baseline file');
+  const c8Version = String(baseline?.tools?.c8?.version || '').trim();
+  const huskyVersion = String(baseline?.tools?.husky?.version || '').trim();
+  const lernaVersion = String(baseline?.tools?.lerna?.version || '').trim();
+
+  if (!c8Version || !huskyVersion || !lernaVersion) {
+    console.error(
+      `Tooling baseline must define fixed tools.c8/husky/lerna.version: ${toolingBaselinePath}`,
+    );
+    process.exit(2);
+  }
+
+  return {
+    toolingBaselinePath,
+    c8Version,
+    huskyVersion,
+    lernaVersion,
+  };
+}
+
+function readFileIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function buildScriptState(pkg) {
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === 'object' && !Array.isArray(pkg.scripts)
+      ? { ...pkg.scripts }
+      : {};
+
+  return {
+    scripts,
+    previousPrepare: typeof scripts.prepare === 'string' ? scripts.prepare : null,
+    previousPrecommitCheck:
+      typeof scripts[REQUIRED_PRECOMMIT_CHECK_SCRIPT_KEY] === 'string'
+        ? scripts[REQUIRED_PRECOMMIT_CHECK_SCRIPT_KEY]
+        : null,
+  };
+}
+
+function buildDevDependencyState(pkg) {
+  const devDependencies =
+    pkg.devDependencies &&
+    typeof pkg.devDependencies === 'object' &&
+    !Array.isArray(pkg.devDependencies)
+      ? { ...pkg.devDependencies }
+      : {};
+
+  return {
+    devDependencies,
+    previousManaged: {
+      c8: typeof devDependencies.c8 === 'string' ? devDependencies.c8 : null,
+      husky: typeof devDependencies.husky === 'string' ? devDependencies.husky : null,
+      lerna: typeof devDependencies.lerna === 'string' ? devDependencies.lerna : null,
+      '@produck/agent-toolkit':
+        typeof devDependencies['@produck/agent-toolkit'] === 'string'
+          ? devDependencies['@produck/agent-toolkit']
+          : null,
+    },
+  };
+}
+
+export function runSyncHuskyHooks(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 toolingBaseline = loadToolingBaseline();
+  const requiredToolkitDependency = getRequiredToolkitDevDependency();
+  const requiredDevDependencies = {
+    c8: toolingBaseline.c8Version,
+    husky: toolingBaseline.huskyVersion,
+    lerna: toolingBaseline.lernaVersion,
+    '@produck/agent-toolkit': requiredToolkitDependency,
+  };
+  const scriptState = buildScriptState(pkg);
+  const dependencyState = buildDevDependencyState(pkg);
+
+  const huskyDir = path.resolve(cwd, '.husky');
+  const preCommitHookPath = path.resolve(huskyDir, 'pre-commit');
+  const commitMsgHookPath = path.resolve(huskyDir, 'commit-msg');
+
+  const previousPreCommitHook = readFileIfExists(preCommitHookPath);
+  const previousCommitMsgHook = readFileIfExists(commitMsgHookPath);
+
+  const matchesRequiredPrepare = scriptState.previousPrepare === REQUIRED_PREPARE_SCRIPT;
+  const matchesRequiredPrecommitCheck =
+    scriptState.previousPrecommitCheck === REQUIRED_PRECOMMIT_CHECK_SCRIPT_VALUE;
+  const matchesRequiredManagedDevDependencies = Object.entries(requiredDevDependencies).every(
+    ([name, version]) => {
+      return dependencyState.previousManaged[name] === version;
+    },
+  );
+  const matchesRequiredPreCommitHook = previousPreCommitHook === REQUIRED_PRE_COMMIT_HOOK;
+  const matchesRequiredCommitMsgHook = previousCommitMsgHook === REQUIRED_COMMIT_MSG_HOOK;
+
+  const requiresUpdate =
+    !matchesRequiredPrepare ||
+    !matchesRequiredPrecommitCheck ||
+    !matchesRequiredManagedDevDependencies ||
+    !matchesRequiredPreCommitHook ||
+    !matchesRequiredCommitMsgHook;
+
+  if (mode === 'sync' && requiresUpdate) {
+    scriptState.scripts.prepare = REQUIRED_PREPARE_SCRIPT;
+    scriptState.scripts[REQUIRED_PRECOMMIT_CHECK_SCRIPT_KEY] =
+      REQUIRED_PRECOMMIT_CHECK_SCRIPT_VALUE;
+    pkg.scripts = scriptState.scripts;
+
+    for (const [name, version] of Object.entries(requiredDevDependencies)) {
+      dependencyState.devDependencies[name] = version;
+    }
+    pkg.devDependencies = dependencyState.devDependencies;
+
+    fs.writeFileSync(rootPackageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+
+    fs.mkdirSync(huskyDir, { recursive: true });
+    fs.writeFileSync(preCommitHookPath, REQUIRED_PRE_COMMIT_HOOK, 'utf8');
+    fs.writeFileSync(commitMsgHookPath, REQUIRED_COMMIT_MSG_HOOK, 'utf8');
+  }
+
+  const report = {
+    cwd,
+    mode,
+    ok: true,
+    rootPackageJsonPath,
+    toolingBaselinePath: toolingBaseline.toolingBaselinePath,
+    required: {
+      prepareScript: REQUIRED_PREPARE_SCRIPT,
+      precommitCheckScriptKey: REQUIRED_PRECOMMIT_CHECK_SCRIPT_KEY,
+      precommitCheckScriptValue: REQUIRED_PRECOMMIT_CHECK_SCRIPT_VALUE,
+      managedDevDependencies: requiredDevDependencies,
+      preCommitHookPath: path.relative(cwd, preCommitHookPath),
+      commitMsgHookPath: path.relative(cwd, commitMsgHookPath),
+    },
+    status: {
+      matchesRequiredPrepareBefore: matchesRequiredPrepare,
+      matchesRequiredPrecommitCheckBefore: matchesRequiredPrecommitCheck,
+      matchesRequiredManagedDevDependenciesBefore: matchesRequiredManagedDevDependencies,
+      matchesRequiredPreCommitHookBefore: matchesRequiredPreCommitHook,
+      matchesRequiredCommitMsgHookBefore: matchesRequiredCommitMsgHook,
+      matchesRequiredPrepareAfter:
+        requiresUpdate && mode === 'sync' ? true : matchesRequiredPrepare,
+      matchesRequiredPrecommitCheckAfter:
+        requiresUpdate && mode === 'sync' ? true : matchesRequiredPrecommitCheck,
+      matchesRequiredManagedDevDependenciesAfter:
+        requiresUpdate && mode === 'sync' ? true : matchesRequiredManagedDevDependencies,
+      matchesRequiredPreCommitHookAfter:
+        requiresUpdate && mode === 'sync' ? true : matchesRequiredPreCommitHook,
+      matchesRequiredCommitMsgHookAfter:
+        requiresUpdate && mode === 'sync' ? true : matchesRequiredCommitMsgHook,
+      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/validate-commit-msg/help.txt

@@ -2,6 +2,7 @@ Usage:
   agent-toolkit validate-commit-msg --file <message-file>
 
 Rules:
+  - In monorepo mode, a section header is required before tagged lines
   - Non-empty lines must be either a section header (for example workspace: or @scope/pkg:) or start with [TAG]
   - If section headers are used, each section header must be followed by at least one tagged line
   - No empty lines are allowed

package/bin/command/validate-commit-msg/index.mjs

@@ -10,6 +10,7 @@ const ALLOWED_TARGETS = ['docs', 'test', 'ci', 'deps', 'api', 'schema', 'infra',
 const SECTION_HEADER_RE = /^(?:@[\w.-]+\/)?[\w.-]+:$/;
 const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
 const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+const ROOT_PACKAGE_FILE = path.resolve(COMMAND_DIR, '../../../../../package.json');
 
 export function printValidateCommitMsgHelp() {
   printTextResource(HELP_FILE);
@@ -54,6 +55,19 @@ function isSectionHeaderLine(line) {
   return SECTION_HEADER_RE.test(line.trim());
 }
 
+function isMonorepoRoot() {
+  if (!fs.existsSync(ROOT_PACKAGE_FILE)) {
+    return false;
+  }
+
+  try {
+    const rootPackage = JSON.parse(fs.readFileSync(ROOT_PACKAGE_FILE, 'utf8'));
+    return Array.isArray(rootPackage.workspaces) && rootPackage.workspaces.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 function validateSectionFormat(lines) {
   const errors = [];
   let currentSection = '';
@@ -128,8 +142,25 @@ export function runValidateCommitMsg(options) {
     process.exit(2);
   }
 
+  const mustUseSectionHeaders = isMonorepoRoot();
   const hasSectionHeaders = lines.some((line) => isSectionHeaderLine(line));
 
+  // [PUBLISH] is generated by lerna and is always a repo-wide tag.
+  // In independent mode lerna appends package/version lines after the tag.
+  // Neither section headers nor a summary are required for this special tag.
+  const isPublishOnlyMessage = /^\[PUBLISH\](\s+.*)?$/.test(lines[0].trim());
+
+  if (isPublishOnlyMessage) {
+    console.log('Commit message validation passed');
+    return;
+  }
+
+  if (mustUseSectionHeaders && !hasSectionHeaders) {
+    console.error('Commit message validation failed:');
+    console.error('- Line 1: section header is required before tagged lines in monorepo mode');
+    process.exit(1);
+  }
+
   const errors = hasSectionHeaders ? validateSectionFormat(lines) : [];
   if (!hasSectionHeaders) {
     for (let i = 0; i < lines.length; i += 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produck/agent-toolkit",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Central CLI toolkit for organization AI execution workflows",
   "type": "module",
   "repository": {
@@ -17,7 +17,8 @@
     "coverage:check": "npm exec --yes -- c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100 node --test test/index.mjs",
     "test": "node --test test/index.mjs",
     "verify": "node ./bin/agent-toolkit.mjs --help && node ./bin/agent-toolkit.mjs preflight --cwd . --require package.json",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "produck:coverage": "c8@11.0.0 --reporter=lcov --reporter=html --reporter=text-summary npm test"
   },
   "files": [
     "bin",
@@ -30,5 +31,8 @@
     "node": ">=18.0.0"
   },
   "license": "MIT",
-  "gitHead": "555d39b0f0ed95f59d457230f784c9dafe7b84d2"
+  "gitHead": "c0aabcec12d70234cfc15cb741fe4ffcf5e4601e",
+  "devDependencies": {
+    "c8": "11.0.0"
+  }
 }