@produck/agent-toolkit 0.6.0 → 0.8.0

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

@@ -0,0 +1,157 @@
+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 LERNA_CONFIG_FILE = 'lerna.json';
+
+const REQUIRED_PUBLISH_CHECK_SCRIPT_KEY = 'produck:publish:check';
+const REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE =
+  'npm run produck:install && npm run produck:format && npm run produck:lint && npm run produck:coverage';
+const USER_PUBLISH_SCRIPT_KEY = 'publish';
+const REQUIRED_PUBLISH_SCRIPT_KEY = 'produck:publish';
+const REQUIRED_PUBLISH_SCRIPT_FALLBACK_VALUE = 'npm run produck:publish:check && lerna publish';
+
+const REQUIRED_LERNA_DEFAULT_CONFIG = `${JSON.stringify(
+  {
+    $schema: 'node_modules/lerna/schemas/lerna-schema.json',
+    version: 'independent',
+  },
+  null,
+  2,
+)}\n`;
+
+export function printSyncPublishHelp() {
+  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 buildRequiredPublishScriptValue(hasUserPublishScript) {
+  if (hasUserPublishScript) {
+    return 'npm run produck:publish:check && npm run publish --';
+  }
+
+  return REQUIRED_PUBLISH_SCRIPT_FALLBACK_VALUE;
+}
+
+export function runSyncPublish(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 lernaConfigPath = path.resolve(cwd, LERNA_CONFIG_FILE);
+  const lernaExistedBefore = fs.existsSync(lernaConfigPath);
+  let lernaDefaultCreated = false;
+
+  if (!lernaExistedBefore) {
+    if (mode === 'sync') {
+      fs.writeFileSync(lernaConfigPath, REQUIRED_LERNA_DEFAULT_CONFIG, 'utf8');
+      lernaDefaultCreated = true;
+    }
+  } else {
+    const lernaConfig = parseJsonFile(lernaConfigPath, 'lerna.json');
+
+    if (typeof lernaConfig.version !== 'string') {
+      console.error(`lerna.json must have a "version" field: ${lernaConfigPath}`);
+      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 hasUserPublishScript =
+    typeof scripts[USER_PUBLISH_SCRIPT_KEY] === 'string' &&
+    scripts[USER_PUBLISH_SCRIPT_KEY].trim() !== '';
+  const requiredPublishScriptValue = buildRequiredPublishScriptValue(hasUserPublishScript);
+
+  const previousPublishCheck =
+    typeof scripts[REQUIRED_PUBLISH_CHECK_SCRIPT_KEY] === 'string'
+      ? scripts[REQUIRED_PUBLISH_CHECK_SCRIPT_KEY]
+      : null;
+  const previousPublish =
+    typeof scripts[REQUIRED_PUBLISH_SCRIPT_KEY] === 'string'
+      ? scripts[REQUIRED_PUBLISH_SCRIPT_KEY]
+      : null;
+
+  const matchesRequiredPublishCheck = previousPublishCheck === REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE;
+  const matchesRequiredPublish = previousPublish === requiredPublishScriptValue;
+  const lernaRequiresCreation = !lernaExistedBefore && !lernaDefaultCreated;
+  const requiresUpdate =
+    !matchesRequiredPublishCheck || !matchesRequiredPublish || lernaRequiresCreation;
+
+  if (mode === 'sync' && (!matchesRequiredPublishCheck || !matchesRequiredPublish)) {
+    scripts[REQUIRED_PUBLISH_CHECK_SCRIPT_KEY] = REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE;
+    scripts[REQUIRED_PUBLISH_SCRIPT_KEY] = requiredPublishScriptValue;
+    pkg.scripts = scripts;
+    fs.writeFileSync(rootPackageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+  }
+
+  const report = {
+    cwd,
+    mode,
+    ok: true,
+    lernaConfigPath,
+    rootPackageJsonPath,
+    required: {
+      publishCheckScriptKey: REQUIRED_PUBLISH_CHECK_SCRIPT_KEY,
+      publishCheckScriptValue: REQUIRED_PUBLISH_CHECK_SCRIPT_VALUE,
+      publishScriptKey: REQUIRED_PUBLISH_SCRIPT_KEY,
+      publishScriptValue: requiredPublishScriptValue,
+    },
+    status: {
+      hasUserPublishScript,
+      lernaExistedBefore,
+      lernaDefaultCreated,
+      matchesRequiredPublishCheckBefore: matchesRequiredPublishCheck,
+      matchesRequiredPublishCheckAfter:
+        !matchesRequiredPublishCheck && mode === 'sync' ? true : matchesRequiredPublishCheck,
+      matchesRequiredPublishBefore: matchesRequiredPublish,
+      matchesRequiredPublishAfter:
+        !matchesRequiredPublish && mode === 'sync' ? true : matchesRequiredPublish,
+      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/index.mjs

@@ -13,6 +13,7 @@ const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
 const ROOT_PACKAGE_FILE = path.resolve(COMMAND_DIR, '../../../../../package.json');
 const WORKSPACE_SCOPE = 'workspace';
 const WILDCARD_SCOPE = '*';
+const DEFAULT_COMMENT_CHAR = '#';
 
 export function printValidateCommitMsgHelp() {
   printTextResource(HELP_FILE);
@@ -170,6 +171,33 @@ function validateSectionFormat(lines, allowedSectionScopes = null) {
   return errors;
 }
 
+function getCommentCharFromConfig() {
+  const configured = String(process.env.GIT_COMMENT_CHAR || '').trim();
+  return configured || DEFAULT_COMMENT_CHAR;
+}
+
+function normalizeCommitMessageLines(raw, commentChar = DEFAULT_COMMENT_CHAR) {
+  const normalizedRaw = raw.replace(/\r\n/g, '\n');
+  const rawLines = normalizedRaw.split('\n');
+  const lines = [];
+
+  for (const line of rawLines) {
+    if (commentChar && line.startsWith(commentChar)) {
+      continue;
+    }
+    lines.push(line);
+  }
+
+  while (lines.length > 0 && lines[0].trim() === '') {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+    lines.pop();
+  }
+
+  return lines;
+}
+
 export function runValidateCommitMsg(options) {
   const file = getSingle(options, '--file', '');
   if (!file) {
@@ -183,8 +211,8 @@ export function runValidateCommitMsg(options) {
     process.exit(2);
   }
 
-  const raw = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
-  const lines = raw.endsWith('\n') ? raw.slice(0, -1).split('\n') : raw.split('\n');
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const lines = normalizeCommitMessageLines(raw, getCommentCharFromConfig());
 
   if (lines.length === 0 || (lines.length === 1 && lines[0].trim() === '')) {
     console.error('Commit message is empty');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produck/agent-toolkit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Central CLI toolkit for organization AI execution workflows",
   "type": "module",
   "repository": {
@@ -13,9 +13,7 @@
   },
   "scripts": {
     "prepack": "node ./bin/build-publish-assets.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",
+    "test": "node test/index.mjs",
     "produck:coverage": "c8 --reporter=lcov --reporter=html --reporter=text-summary npm test"
   },
   "files": [
@@ -32,5 +30,5 @@
   "devDependencies": {
     "c8": "11.0.0"
   },
-  "gitHead": "8618167ffe15e39c5a7b350903f0fd8861902a62"
+  "gitHead": "a9e160249f664b28fa5971246e61d9e641c16586"
 }

package/publish-assets/gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+
+# Windows script entrypoints
+*.bat text eol=crlf
+*.cmd text eol=crlf

package/publish-assets/gitignore

@@ -0,0 +1,137 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# Vscode
+.vscode
+
+# Specific ignored / generated.
+*.ign*
+*.gen*

package/publish-assets/instructions/produck/00-produck-base.instructions.md

@@ -18,20 +18,26 @@ in the `produck` organization.
 
 ## Instruction source split
 
-To separate organization-only governance from downstream-distributable
-baseline, policy sources are split as follows:
-
-- Downstream-distributable source:
-  `.github/distribution/produck/*.instructions.md`
-- Organization-only source (not distributed):
-  `.github/instructions/produck/*.instructions.md`
-
-Editing rule:
+Path semantics differ between the upstream policy repository and downstream
+repositories:
+
+- Upstream policy repository (this `produck/.github` repo):
+  - `.github/distribution/produck/*.instructions.md` — canonical baseline,
+    distributed to downstream repositories.
+  - `.github/instructions/produck/*.instructions.md` — reserved for
+    organization-only governance that should NOT be distributed.
+- Downstream repositories (consumers of the baseline):
+  - `.github/instructions/produck/*.instructions.md` — synced copy of the
+    upstream canonical baseline (managed by `agent-toolkit sync-instructions`).
+  - `.github/copilot-instructions.md` — repository-specific exceptions and
+    stricter local constraints.
+
+Editing rule (upstream only):
 
 - Update downstream baseline rules directly in
   `.github/distribution/produck/*.instructions.md`.
-- Update organization-only workflow/governance in
-  `.github/instructions/produck/`.
+- Add organization-only governance under
+  `.github/instructions/produck/` only when it must not be distributed.
 
 ## Default expectations
 
@@ -134,27 +140,15 @@ max_line_length = 80
 
 ## Commit and PR conventions
 
-- Commit messages use bracketed tags: `[TAG] summary`.
-- Every non-empty commit message line must start with `[TAG]`.
-- Empty lines are not allowed between commit message lines.
-- Do not use untagged bullet lines in commit message body.
-- If details are needed, use additional tagged lines.
-- Do not keep summary as an untagged standalone line.
-- Recommended local validation:
-  `npm exec -- agent-toolkit validate-commit-msg --file <message-file>`.
-- Commit precheck policy follows
+- Commit and commit-precheck rules are defined in
   `.github/distribution/produck/20-produck-commit.instructions.md`.
-- Canonical source for commit tag/target whitelists, legacy mapping, and
-  target syntax is
-  `.github/distribution/produck/20-produck-commit.instructions.md`.
-- Do not redefine commit tag or target whitelists in other instruction files.
-- For non-monorepo repositories, use `[TAG] summary` directly (no
-  package/workspace section headers).
-- Bracketed commit summaries should be in English
-- PR title format is repository-defined; no organization-level title format
-  restriction
-- In PR descriptions, summarize what changed, why it changed, how it was
-  validated, and any known risks or follow-up work
+- Use commit message validator before commit and amend:
+  `npm exec -- agent-toolkit validate-commit-msg --file <message-file>`.
+- Do not redefine commit tag, target, or monorepo section rules outside
+  `20-produck-commit.instructions.md`.
+- PR title format is repository-defined (no organization-level restriction).
+- PR descriptions should summarize what changed, why, validation, and known
+  risks or follow-up work.
 
 ## Terminal long-output protocol
 
@@ -255,7 +249,8 @@ locally in downstream repositories at a fixed version managed by the
 organization baseline.
 
 - Local install and pinned version are deployed by
-  `agent-toolkit sync-husky-hooks`.
+  `agent-toolkit sync-git` (root devDependency pinning) and
+  `agent-toolkit sync-install` (root install script baseline).
 - Invocation uses the locally installed copy:
   `npm exec -- <bin> ...`.
 - Do not use `npm exec --package=<pkg>@latest` for routine invocations.
@@ -294,31 +289,21 @@ Rollback runbook (minimum):
 
 ### Recommended organization AI instruction template
 
-Use the following template text in organization AI instructions:
-
-- Use Chinese for discussion unless repository rules require another language.
-- Follow existing repository patterns; do not invent APIs, files, commands, or
-  config keys.
-- Node-first execution policy:
-  - Use Node scripts first for file/path/output processing.
-  - For large output tasks, use two phases: capture full output, then analyze.
-  - Avoid fragile shell pipeline post-processing for long-output commands.
-- Central package policy:
-  - Central package is installed locally at a fixed organization-baseline version.
-  - Invoke via `npm exec -- <bin> ...` to use the locally installed copy.
-  - Print resolved package version before high-impact execution.
-  - Use dry-run first for risky operations; keep rollback path to pinned version.
-- Commit message policy:
-  - Every non-empty commit message line must start with `[TAG]`.
-  - Empty lines are not allowed between commit message lines.
-  - Use only allowed tags: `[INIT]`, `[ADD]`, `[REMOVE]`, `[FIX]`,
-    `[REFACTOR]`, `[UPGRADE]`.
-  - Optional target syntax is `[TAG] <target>: <summary>` with target in:
-    `docs`, `test`, `ci`, `deps`, `api`, `schema`, `infra`, `fmt`.
-- Do not assume scripts from organization `.github` repository exist in target
-  repositories.
-- If a repository provides stricter rules, repository rules override
-  organization defaults.
+When authoring organization-level AI instruction text (for example in
+organization settings), reference the canonical sources in this baseline
+instead of duplicating their content:
+
+- Language and default expectations: see `Default expectations` and
+  `Language conventions` sections above.
+- Node-first execution policy: see `Terminal long-output protocol` above.
+- Central package policy: see `Central package execution policy` above.
+- Commit message policy: see
+  [Commit Convention](20-produck-commit.instructions.md) (canonical source
+  for tag whitelist, target whitelist, and validator usage).
+- Cross-repository assumptions: do not assume scripts from the organization
+  `.github` repository exist in target repositories.
+- Precedence: repository-specific stricter rules override organization
+  defaults.
 
 ## Precedence
 
@@ -326,4 +311,5 @@ If a repository provides more specific instructions, follow the repository
 instructions over this organization baseline.
 
 For Node.js repositories, also follow [Node.js Initialization
-Baseline](10-produck-node.instructions.md).
+Baseline](10-produck-node.instructions.md) and [Test Authoring
+Baseline](12-produck-test.instructions.md).