@produck/agent-toolkit 0.4.0 → 0.6.0

package/README.md

@@ -19,9 +19,16 @@ What it does (in order):
 
 1. Syncs organization AI instruction files into `.github/instructions/produck/`
 2. Runs preflight to verify required files and directories
-3. Deploys the pinned `produck:coverage` script and `c8` devDependency
-4. Deploys `.husky/pre-commit` and `.husky/commit-msg`, and pins `c8`, `husky`,
-   `lerna`, `@produck/agent-toolkit` in root `devDependencies`
+3. Syncs root `produck:format` script and initializes `.prettierrc`
+4. Syncs root `produck:lint` script, initializes/patches `eslint.config.mjs`,
+   and ensures `@produck/eslint-rules`
+5. Syncs root shared governance (`produck:baseline`,
+   `produck:coverage`, `produck:precommit-check`), initializes `.c8rc.json`,
+   and syncs shared pinned devDependencies
+   (`c8`, `husky`, `lerna`, `@produck/agent-toolkit`)
+6. Deploys the pinned `produck:coverage` script and `c8` devDependency to each workspace package, and enforces `scripts.test` (generates a default `test` script when missing).
+   **Note:** The `produck:coverage` script in subpackages is for local and AI development use only. It is NOT enforced by organization CI or `.c8rc.json`. Only the root workspace (monorepo root) is subject to org-level coverage enforcement and `.c8rc.json`.
+7. Deploys `.husky/pre-commit` and `.husky/commit-msg`
 
 After running, add the persistent enforcement entry to the repository
 `package.json`:
@@ -43,6 +50,9 @@ npm run produck:baseline
 - agent-toolkit run-capture
 - agent-toolkit summarize-log
 - agent-toolkit sync-coverage-script
+- agent-toolkit sync-prettier-config
+- agent-toolkit sync-eslint-config
+- agent-toolkit sync-workspace-config
 - agent-toolkit sync-husky-hooks
 - agent-toolkit validate-commit-msg
 - agent-toolkit sync-instructions
@@ -61,17 +71,25 @@ Equivalent explicit form:
 npm exec -- agent-toolkit enforce-node-baseline --cwd .
 ```
 
-`enforce-node-baseline` runs four steps in fixed order and stops at the first
+`enforce-node-baseline` runs seven steps in fixed order and stops at the first
 failure:
 
 1. `sync-instructions` — distribute organization AI instruction files into
    `.github/instructions/produck/`
 2. `preflight` — verify required files and directories exist
-3. `sync-coverage-script` — deploy pinned `produck:coverage` script and `c8`
-   devDependency into each workspace package
-4. `sync-husky-hooks` — deploy `.husky/pre-commit` and `.husky/commit-msg`,
-   and pin `c8`, `husky`, `lerna`, `@produck/agent-toolkit` in root
-   `devDependencies`
+3. `sync-prettier-config` — deploy organization format gate script
+   (`produck:format`) and initialize `.prettierrc`
+4. `sync-eslint-config` — deploy organization lint gate script
+   (`produck:lint`), initialize/patch `eslint.config.mjs`, and ensure
+   `@produck/eslint-rules` integration
+5. `sync-workspace-config` — deploy shared root governance scripts
+   (`produck:baseline`, `produck:coverage`, `produck:precommit-check`),
+   initialize root `.c8rc.json`, and sync shared pinned root devDependencies
+   (`c8`, `husky`, `lerna`, `@produck/agent-toolkit`)
+6. `sync-coverage-script` — deploy pinned `produck:coverage` script and `c8`
+   devDependency into each workspace package, and ensure each workspace
+   package has `scripts.test` (auto-generate a default value when missing)
+7. `sync-husky-hooks` — deploy `.husky/pre-commit` and `.husky/commit-msg`
 
 Add to downstream repository root `package.json` for one-command enforcement:
 
@@ -121,22 +139,59 @@ Summarize captured output:
 npm exec -- agent-toolkit summarize-log --file logs/test.log --match "FAIL|ERROR"
 ```
 
-Deploy organization coverage script and pinned local c8 devDependency to
-workspace packages:
+Deploy organization coverage script and pinned local c8 devDependency to workspace packages:
 
 ```
 npm exec -- agent-toolkit sync-coverage-script --cwd .
 ```
 
+This command also enforces `scripts.test` in each workspace package.
+If missing, it generates:
+
+```
+node -e "console.log('No tests configured')"
+```
+
+**Note:** The `produck:coverage` script in subpackages is for local and AI development use only. It is NOT enforced by organization CI or `.c8rc.json`. Only the root workspace (monorepo root) is subject to org-level coverage enforcement and `.c8rc.json`.
+
+Deploy organization format config and script baseline to repository root:
+
+```
+npm exec -- agent-toolkit sync-prettier-config --cwd .
+```
+
+This command manages `scripts.produck:format` and `.prettierrc` only.
+
+Deploy organization lint config and script baseline to repository root:
+
+```
+npm exec -- agent-toolkit sync-eslint-config --cwd .
+```
+
+This command manages `scripts.produck:lint`, `eslint.config.mjs`, and
+`devDependencies.@produck/eslint-rules`. If `eslint.config.mjs` exists without
+`@produck/eslint-rules`, it appends Produck integration to the exported config
+array.
+
+Deploy organization root shared scripts and shared pinned dependencies to
+repository root:
+
+```
+npm exec -- agent-toolkit sync-workspace-config --cwd .
+```
+
+This command manages `scripts.produck:baseline`,
+`scripts.produck:coverage`, `scripts.produck:precommit-check`, initializes
+`.c8rc.json`, and pins `c8`, `husky`, `lerna`, and `@produck/agent-toolkit`
+in root `devDependencies`.
+
 Deploy organization local anti-drift husky hooks to repository root:
 
 ```
 npm exec -- agent-toolkit sync-husky-hooks --cwd .
 ```
 
-This command pins root local hook dependencies (`c8`, `husky`, `lerna`, and
-`@produck/agent-toolkit`) to organization baseline fixed versions and syncs
-`.husky/pre-commit` and `.husky/commit-msg`.
+This command syncs only `.husky/pre-commit` and `.husky/commit-msg`.
 
 Validate commit message format:
 
@@ -185,11 +240,18 @@ Organization-only instruction source (not published):
 
 ## Local verification
 
+`verify` is an optional package-level health check and is not a commit gate.
+Use repository style gates first, then run package checks when needed.
+
 From repository root:
 
 ```bash
-npm --workspace @produck/agent-toolkit run verify
+npm run format:check
+npm run lint
+npm --workspace @produck/agent-toolkit run test
 npm --workspace @produck/agent-toolkit run pack:check
+# optional health check
+npm --workspace @produck/agent-toolkit run verify
 ```
 
 ## Publishing
@@ -220,7 +282,7 @@ Repository includes manual workflow:
 
 Workflow behavior:
 
-- Always runs verify and pack:check for `@produck/agent-toolkit`.
+- Runs test and pack:check for `@produck/agent-toolkit`.
 - Does not publish to npm.
 - Used as release gate before workspace-level publish.
 

package/bin/agent-toolkit.mjs

@@ -16,6 +16,22 @@ import {
   printSyncInstructionsHelp,
   runSyncInstructions,
 } from './command/sync-instructions/index.mjs';
+import {
+  printSyncPrettierConfigHelp,
+  runSyncPrettierConfig,
+} from './command/sync-prettier-config/index.mjs';
+import {
+  printSyncEditorconfigHelp,
+  runSyncEditorconfig,
+} from './command/sync-editorconfig/index.mjs';
+import {
+  printSyncEslintConfigHelp,
+  runSyncEslintConfig,
+} from './command/sync-eslint-config/index.mjs';
+import {
+  printSyncWorkspaceConfigHelp,
+  runSyncWorkspaceConfig,
+} from './command/sync-workspace-config/index.mjs';
 import { hasFlag, parseCommonArgs } from './command/shared/args.mjs';
 import {
   printValidateCommitMsgHelp,
@@ -43,6 +59,18 @@ const COMMANDS = {
     printHelp: printSyncCoverageScriptHelp,
     run: runSyncCoverageScript,
   },
+  'sync-prettier-config': {
+    printHelp: printSyncPrettierConfigHelp,
+    run: runSyncPrettierConfig,
+  },
+  'sync-eslint-config': {
+    printHelp: printSyncEslintConfigHelp,
+    run: runSyncEslintConfig,
+  },
+  'sync-workspace-config': {
+    printHelp: printSyncWorkspaceConfigHelp,
+    run: runSyncWorkspaceConfig,
+  },
   'sync-husky-hooks': {
     printHelp: printSyncHuskyHooksHelp,
     run: runSyncHuskyHooks,
@@ -55,6 +83,10 @@ const COMMANDS = {
     printHelp: printSyncInstructionsHelp,
     run: runSyncInstructions,
   },
+  'sync-editorconfig': {
+    printHelp: printSyncEditorconfigHelp,
+    run: runSyncEditorconfig,
+  },
 };
 
 const DEFAULT_COMMAND = 'enforce-node-baseline';

package/bin/command/enforce-node-baseline/help.txt

@@ -7,13 +7,16 @@ Behavior:
   - Runs mandatory baseline flow in fixed order:
     1) sync-instructions
     2) preflight
-    3) sync-coverage-script
-    4) sync-husky-hooks
+    3) sync-prettier-config
+    4) sync-eslint-config
+    5) sync-workspace-config
+    6) sync-coverage-script
+    7) sync-husky-hooks
   - Stops at first failed step and exits non-zero
   - Prints one combined JSON report for all executed steps
 
 Rules:
-  - --check runs non-mutating validation mode for step 1, step 3, and step 4
-  - --dry-run runs non-mutating preview mode for step 1, step 3, and step 4
+  - --check runs non-mutating validation mode for step 1, step 3, step 4, step 5, step 6, and step 7
+  - --dry-run runs non-mutating preview mode for step 1, step 3, step 4, step 5, step 6, and step 7
   - --check takes precedence over --dry-run
-  - --workspace filters coverage sync targets in step 3
+  - --workspace filters coverage sync targets in step 6

package/bin/command/enforce-node-baseline/index.mjs

@@ -120,9 +120,41 @@ export function runEnforceNodeBaseline(options) {
     syncHuskyArgs.push('--dry-run');
   }
 
+  const syncWorkspaceConfigArgs = ['sync-workspace-config', '--cwd', cwd];
+  if (check) {
+    syncWorkspaceConfigArgs.push('--check');
+  } else if (dryRun) {
+    syncWorkspaceConfigArgs.push('--dry-run');
+  }
+
+  const syncEditorconfigArgs = ['sync-editorconfig', '--cwd', cwd];
+  if (check) {
+    syncEditorconfigArgs.push('--check');
+  } else if (dryRun) {
+    syncEditorconfigArgs.push('--dry-run');
+  }
+
+  const syncPrettierConfigArgs = ['sync-prettier-config', '--cwd', cwd];
+  if (check) {
+    syncPrettierConfigArgs.push('--check');
+  } else if (dryRun) {
+    syncPrettierConfigArgs.push('--dry-run');
+  }
+
+  const syncEslintConfigArgs = ['sync-eslint-config', '--cwd', cwd];
+  if (check) {
+    syncEslintConfigArgs.push('--check');
+  } else if (dryRun) {
+    syncEslintConfigArgs.push('--dry-run');
+  }
+
   const plan = [
     { name: 'sync-instructions', args: syncInstructionsArgs },
     { name: 'preflight', args: preflightArgs },
+    { name: 'sync-editorconfig', args: syncEditorconfigArgs },
+    { name: 'sync-prettier-config', args: syncPrettierConfigArgs },
+    { name: 'sync-eslint-config', args: syncEslintConfigArgs },
+    { name: 'sync-workspace-config', args: syncWorkspaceConfigArgs },
     { name: 'sync-coverage-script', args: syncCoverageArgs },
     { name: 'sync-husky-hooks', args: syncHuskyArgs },
   ];

package/bin/command/main/help.txt

@@ -4,6 +4,10 @@ agent-toolkit commands:
   run-capture
   summarize-log
   sync-coverage-script
+  sync-editorconfig
+  sync-prettier-config
+  sync-eslint-config
+  sync-workspace-config
   sync-husky-hooks
   validate-commit-msg
   sync-instructions

package/bin/command/preflight/index.mjs

@@ -4,10 +4,10 @@ import { fileURLToPath } from 'node:url';
 
 import { getSingle, hasFlag } from '../shared/args.mjs';
 import { printTextResource } from '../shared/text-resource.mjs';
+import { validateWorkspaceShape } from '../shared/workspace-validation.mjs';
 
 const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
 const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
-const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
 const REQUIRED_WORKSPACE_FIELDS = ['private', 'workspaces', 'scripts'];
 const REQUIRED_WORKSPACE_SCRIPTS = ['deps:install', 'test', 'produck:coverage', 'lint'];
 
@@ -43,40 +43,12 @@ function validateWorkspacePackageJson(cwd, checkPath) {
     return check;
   }
 
-  check.missingFields = REQUIRED_WORKSPACE_FIELDS.filter((field) => {
-    return !(field in json);
-  });
-
-  if (typeof json.scripts !== 'object' || json.scripts === null || Array.isArray(json.scripts)) {
-    check.scriptTypeValid = false;
-    check.ok = false;
-  } else {
-    check.missingScripts = REQUIRED_WORKSPACE_SCRIPTS.filter((scriptName) => {
-      return !(scriptName in json.scripts);
-    });
-  }
-
-  const workspaceList = Array.isArray(json.workspaces)
-    ? json.workspaces.map((entry) => String(entry))
-    : [];
-  if (!Array.isArray(json.workspaces)) {
-    check.wildcardWorkspaces = ['<non-array-workspaces>'];
-    check.ok = false;
-  } else {
-    check.wildcardWorkspaces = workspaceList.filter((entry) => GLOB_TOKEN_PATTERN.test(entry));
-  }
-
-  if (json.private !== true) {
-    check.ok = false;
-  }
-
-  if (check.missingFields.length > 0 || check.missingScripts.length > 0) {
-    check.ok = false;
-  }
-
-  if (check.wildcardWorkspaces.length > 0) {
-    check.ok = false;
-  }
+  const shape = validateWorkspaceShape(json, REQUIRED_WORKSPACE_FIELDS, REQUIRED_WORKSPACE_SCRIPTS);
+  check.missingFields = shape.missingFields;
+  check.scriptTypeValid = shape.scriptTypeValid;
+  check.missingScripts = shape.missingScripts;
+  check.wildcardWorkspaces = shape.wildcardWorkspaces;
+  check.ok = shape.ok;
 
   return check;
 }

package/bin/command/shared/workspace-validation.mjs

@@ -0,0 +1,63 @@
+const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
+
+export function toObjectRecord(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return { ...value };
+  }
+
+  return {};
+}
+
+export function findMissingKeys(record, requiredKeys) {
+  return requiredKeys.filter((key) => {
+    return !(key in record);
+  });
+}
+
+export function validateWorkspaceShape(pkg, requiredFields, requiredScripts) {
+  const missingFields = findMissingKeys(pkg, requiredFields);
+  const scripts = toObjectRecord(pkg.scripts);
+  const scriptTypeValid =
+    typeof pkg.scripts === 'object' && pkg.scripts !== null && !Array.isArray(pkg.scripts);
+  const missingScripts = scriptTypeValid ? findMissingKeys(scripts, requiredScripts) : [];
+
+  const workspacesIsArray = Array.isArray(pkg.workspaces);
+  const wildcardWorkspaces = workspacesIsArray
+    ? pkg.workspaces.map((entry) => String(entry)).filter((entry) => GLOB_TOKEN_PATTERN.test(entry))
+    : ['<non-array-workspaces>'];
+
+  const privateIsTrue = pkg.private === true;
+  const ok =
+    missingFields.length === 0 &&
+    scriptTypeValid &&
+    missingScripts.length === 0 &&
+    workspacesIsArray &&
+    wildcardWorkspaces.length === 0 &&
+    privateIsTrue;
+
+  return {
+    ok,
+    missingFields,
+    scriptTypeValid,
+    missingScripts,
+    wildcardWorkspaces,
+  };
+}
+
+export function validateRequiredExactEntries(currentRecord, requiredRecord) {
+  const mismatches = {};
+
+  for (const [name, expectedValue] of Object.entries(requiredRecord)) {
+    if (currentRecord[name] !== expectedValue) {
+      mismatches[name] = {
+        expected: expectedValue,
+        actual: name in currentRecord ? currentRecord[name] : null,
+      };
+    }
+  }
+
+  return {
+    ok: Object.keys(mismatches).length === 0,
+    mismatches,
+  };
+}

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

@@ -3,10 +3,14 @@ Usage:
     [--workspace <path>] ... [--check] [--dry-run] [--json <file>]
 
 Behavior:
-  - Applies organization-required coverage script to workspace package.json files
+  - Adds or updates scripts.produck:coverage and devDependencies.c8 in each workspace package.json.
+  - Enforces scripts.test in each workspace package.json.
+  - If scripts.test is missing, generates:
+    node -e "console.log('No tests configured')"
+  - The produck:coverage script in subpackages is for local and AI development use only.
+  - Subpackage produck:coverage is NOT enforced by organization CI or .c8rc.json.
+  - Only the root workspace (monorepo root) is subject to org-level coverage enforcement and .c8rc.json.
   - 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
@@ -17,6 +21,9 @@ Behavior:
 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 include scripts.test
   - Workspace package.json files must pin devDependencies.c8 to baseline version
+  - Subpackage produck:coverage is not a CI or org gate; it is for local/dev use only
+  - Only the root workspace is enforced by org CI and .c8rc.json
   - --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

@@ -15,6 +15,8 @@ const TOOLING_BASELINE_CANDIDATE_PATHS = [
 ];
 const GLOB_TOKEN_PATTERN = /[*?{}[\]]/;
 const REQUIRED_COVERAGE_SCRIPT_KEY = 'produck:coverage';
+const REQUIRED_TEST_SCRIPT_KEY = 'test';
+const DEFAULT_TEST_SCRIPT_VALUE = 'node -e "console.log(\'No tests configured\')"';
 
 export function printSyncCoverageScriptHelp() {
   printTextResource(HELP_FILE);
@@ -132,10 +134,14 @@ function reconcileCoverageScript(
     validJson: false,
     previousCoverage: null,
     coverageScript: null,
+    previousTestScript: null,
+    testScript: null,
     previousC8DevDependency: null,
     c8DevDependency: null,
     matchesRequiredCoverageBefore: false,
     matchesRequiredCoverageAfter: false,
+    hasRequiredTestScriptBefore: false,
+    hasRequiredTestScriptAfter: false,
     matchesRequiredC8DevDependencyBefore: false,
     matchesRequiredC8DevDependencyAfter: false,
     updated: false,
@@ -172,18 +178,30 @@ function reconcileCoverageScript(
     typeof scripts[REQUIRED_COVERAGE_SCRIPT_KEY] === 'string'
       ? scripts[REQUIRED_COVERAGE_SCRIPT_KEY]
       : null;
+  const previousTestScript =
+    typeof scripts[REQUIRED_TEST_SCRIPT_KEY] === 'string' &&
+    scripts[REQUIRED_TEST_SCRIPT_KEY].trim() !== ''
+      ? scripts[REQUIRED_TEST_SCRIPT_KEY]
+      : null;
   const previousC8DevDependency =
     typeof devDependencies.c8 === 'string' ? devDependencies.c8 : null;
   result.previousCoverage = previousCoverage;
+  result.previousTestScript = previousTestScript;
   result.previousC8DevDependency = previousC8DevDependency;
   result.matchesRequiredCoverageBefore = previousCoverage === requiredCoverageScript;
+  result.hasRequiredTestScriptBefore = previousTestScript !== null;
   result.matchesRequiredC8DevDependencyBefore = previousC8DevDependency === requiredC8Version;
 
   if (
-    (!result.matchesRequiredCoverageBefore || !result.matchesRequiredC8DevDependencyBefore) &&
+    (!result.matchesRequiredCoverageBefore ||
+      !result.hasRequiredTestScriptBefore ||
+      !result.matchesRequiredC8DevDependencyBefore) &&
     mode === 'sync'
   ) {
     scripts[REQUIRED_COVERAGE_SCRIPT_KEY] = requiredCoverageScript;
+    if (!result.hasRequiredTestScriptBefore) {
+      scripts[REQUIRED_TEST_SCRIPT_KEY] = DEFAULT_TEST_SCRIPT_VALUE;
+    }
     devDependencies.c8 = requiredC8Version;
     pkg.scripts = scripts;
     pkg.devDependencies = devDependencies;
@@ -195,12 +213,18 @@ function reconcileCoverageScript(
     mode === 'sync' && !result.matchesRequiredCoverageBefore
       ? requiredCoverageScript
       : previousCoverage;
+  result.testScript =
+    mode === 'sync' && !result.hasRequiredTestScriptBefore
+      ? DEFAULT_TEST_SCRIPT_VALUE
+      : previousTestScript;
   result.c8DevDependency =
     mode === 'sync' && !result.matchesRequiredC8DevDependencyBefore
       ? requiredC8Version
       : previousC8DevDependency;
 
   result.matchesRequiredCoverageAfter = result.updated || result.matchesRequiredCoverageBefore;
+  result.hasRequiredTestScriptAfter =
+    (mode === 'sync' && !result.hasRequiredTestScriptBefore) || result.hasRequiredTestScriptBefore;
   result.matchesRequiredC8DevDependencyAfter =
     result.updated || result.matchesRequiredC8DevDependencyBefore;
   return result;
@@ -232,6 +256,7 @@ export function runSyncCoverageScript(options) {
       c8Version: toolingBaseline.tools.c8.version,
     },
     requiredCoverageScript,
+    requiredTestScript: DEFAULT_TEST_SCRIPT_VALUE,
     requiredC8DevDependency: requiredC8Version,
     workspaces: workspacePaths,
     results: [],
@@ -256,7 +281,9 @@ export function runSyncCoverageScript(options) {
 
     if (
       mode === 'check' &&
-      (!item.matchesRequiredCoverageAfter || !item.matchesRequiredC8DevDependencyAfter)
+      (!item.matchesRequiredCoverageAfter ||
+        !item.hasRequiredTestScriptAfter ||
+        !item.matchesRequiredC8DevDependencyAfter)
     ) {
       report.ok = false;
     }

package/bin/command/sync-editorconfig/editorconfig.template

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = 80

package/bin/command/sync-editorconfig/help.txt

@@ -0,0 +1,13 @@
+Usage:
+  agent-toolkit sync-editorconfig [--cwd <dir>] [--check] [--dry-run]
+    [--json <file>]
+
+Behavior:
+  - Applies organization-required root .editorconfig file
+  - Creates .editorconfig if missing, or merges missing required entries
+    if file already exists
+
+Rules:
+  - --check validates without writing and exits non-zero on mismatch
+  - --dry-run prints planned changes without writing
+  - --check takes precedence over --dry-run