@produck/agent-toolkit 0.1.5 → 0.2.1

package/bin/command/sync-instructions/user-space-bootstrap.md

@@ -0,0 +1,14 @@
+# Repository AI Instructions
+
+This repository uses organization baseline instructions from:
+
+- {{NAMESPACE_GLOB}}
+
+Repository-specific rules should be written in this file.
+Keep organization baseline rules in the produck namespace files above.
+
+Recommended usage:
+
+- Add local constraints and exceptions here.
+- Do not copy organization baseline content into this file.
+- Keep this file focused on repository-only behavior.

package/bin/command/validate-commit-msg/help.txt

@@ -0,0 +1,8 @@
+Usage:
+  agent-toolkit validate-commit-msg --file <message-file>
+
+Rules:
+  - 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
+  - Optional target form: [TAG] <target>: <summary>

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

@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSingle } from '../shared/args.mjs';
+import { printTextResource } from '../shared/text-resource.mjs';
+
+const ALLOWED_TAGS = ['INIT', 'ADD', 'REMOVE', 'FIX', 'REFACTOR', 'UPGRADE', 'PUBLISH'];
+const ALLOWED_TARGETS = ['docs', 'test', 'ci', 'deps', 'api', 'schema', 'infra', 'fmt'];
+const SECTION_HEADER_RE = /^(?:@[\w.-]+\/)?[\w.-]+:$/;
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HELP_FILE = path.resolve(COMMAND_DIR, 'help.txt');
+
+export function printValidateCommitMsgHelp() {
+  printTextResource(HELP_FILE);
+}
+
+function validateCommitLine(line, lineNo) {
+  if (line.trim() === '') {
+    return `Line ${lineNo}: empty line is not allowed`;
+  }
+
+  const head = line.match(/^\[([A-Z]+)\]\s+/);
+  if (!head) {
+    return `Line ${lineNo}: must start with [TAG] followed by a space`;
+  }
+
+  const tag = head[1];
+  if (!ALLOWED_TAGS.includes(tag)) {
+    return `Line ${lineNo}: tag [${tag}] is not allowed`;
+  }
+
+  const rest = line.slice(head[0].length);
+  if (rest.trim() === '') {
+    return `Line ${lineNo}: summary is required after tag`;
+  }
+
+  const targetMatch = rest.match(/^<([^>]+)>:\s+(.+)$/);
+  if (targetMatch) {
+    const target = targetMatch[1];
+    const summary = targetMatch[2];
+    if (!ALLOWED_TARGETS.includes(target)) {
+      return `Line ${lineNo}: target <${target}> is not allowed`;
+    }
+    if (summary.trim() === '') {
+      return `Line ${lineNo}: summary is required after target`;
+    }
+  }
+
+  return null;
+}
+
+function isSectionHeaderLine(line) {
+  return SECTION_HEADER_RE.test(line.trim());
+}
+
+function validateSectionFormat(lines) {
+  const errors = [];
+  let currentSection = '';
+  let currentSectionLineNo = 0;
+  let currentSectionHasTaggedLine = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const lineNo = i + 1;
+    const line = lines[i];
+
+    if (line.trim() === '') {
+      errors.push(`Line ${lineNo}: empty line is not allowed`);
+      continue;
+    }
+
+    if (isSectionHeaderLine(line)) {
+      if (currentSection && !currentSectionHasTaggedLine) {
+        errors.push(
+          `Line ${currentSectionLineNo}: section header "${currentSection}" must be followed by at least one tagged line`,
+        );
+      }
+
+      currentSection = line.trim();
+      currentSectionLineNo = lineNo;
+      currentSectionHasTaggedLine = false;
+      continue;
+    }
+
+    if (!currentSection) {
+      errors.push(
+        `Line ${lineNo}: section header is required before tagged lines when package/workspace sections are used`,
+      );
+      continue;
+    }
+
+    const err = validateCommitLine(line, lineNo);
+    if (err) {
+      errors.push(err);
+      continue;
+    }
+
+    currentSectionHasTaggedLine = true;
+  }
+
+  if (currentSection && !currentSectionHasTaggedLine) {
+    errors.push(
+      `Line ${currentSectionLineNo}: section header "${currentSection}" must be followed by at least one tagged line`,
+    );
+  }
+
+  return errors;
+}
+
+export function runValidateCommitMsg(options) {
+  const file = getSingle(options, '--file', '');
+  if (!file) {
+    printValidateCommitMsgHelp();
+    process.exit(2);
+  }
+
+  const filePath = path.resolve(file);
+  if (!fs.existsSync(filePath)) {
+    console.error(`Message file not found: ${filePath}`);
+    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');
+
+  if (lines.length === 0 || (lines.length === 1 && lines[0].trim() === '')) {
+    console.error('Commit message is empty');
+    process.exit(2);
+  }
+
+  const hasSectionHeaders = lines.some((line) => isSectionHeaderLine(line));
+
+  const errors = hasSectionHeaders ? validateSectionFormat(lines) : [];
+  if (!hasSectionHeaders) {
+    for (let i = 0; i < lines.length; i += 1) {
+      const err = validateCommitLine(lines[i], i + 1);
+      if (err) {
+        errors.push(err);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('Commit message validation failed:');
+    for (const err of errors) {
+      console.error(`- ${err}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Commit message validation passed');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produck/agent-toolkit",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Central CLI toolkit for organization AI execution workflows",
   "type": "module",
   "repository": {
@@ -12,12 +12,16 @@
     "agent-toolkit": "bin/agent-toolkit.mjs"
   },
   "scripts": {
+    "prepack": "node ./bin/build-publish-assets.mjs",
+    "coverage": "npm exec --yes -- c8 --reporter=lcov --reporter=html --reporter=text-summary node --test test/index.mjs",
+    "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"
   },
   "files": [
     "bin",
-    "templates"
+    "publish-assets"
   ],
   "publishConfig": {
     "access": "public"
@@ -26,5 +30,5 @@
     "node": ">=18.0.0"
   },
   "license": "MIT",
-  "gitHead": "13afa6b9d747360fedf569a619274d90a038c0f3"
+  "gitHead": "555d39b0f0ed95f59d457230f784c9dafe7b84d2"
 }

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

@@ -0,0 +1,331 @@
+---
+applyTo: '**'
+---
+
+<!-- managed-by: @produck/agent-toolkit -->
+<!-- source: .github/distribution/produck/00-produck-base.instructions.md -->
+
+# AI Collaboration
+
+This document defines a lightweight AI collaboration baseline for repositories
+in the `produck` organization.
+
+## Goals
+
+- Improve consistency when using AI tools across repositories
+- Keep the baseline lightweight and easy to adopt
+- Let repositories add stricter or more specific instructions when needed
+
+## 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:
+
+- Update downstream baseline rules directly in
+  `.github/distribution/produck/*.instructions.md`.
+- Update organization-only workflow/governance in
+  `.github/instructions/produck/`.
+
+## Default expectations
+
+- Default to Chinese for explanations and discussion unless the repository or
+  request requires another language.
+- Prefer existing repository patterns over introducing new abstractions or
+  frameworks.
+- Do not invent APIs, packages, configuration keys, commands, environment
+  variables, or files.
+- Do not add new dependencies unless necessary and explicitly justified.
+- When changing behavior, add or update tests when practical.
+- Treat authentication, authorization, secrets, infrastructure, and production
+  configuration as high-risk areas that require human review.
+- Repositories should include a root `.gitattributes` to normalize line endings
+  safely across platforms.
+
+## Git attributes conventions
+
+- All repositories should include a root `.gitattributes`.
+- Default text line ending policy is LF.
+- Recommended minimum template:
+
+```gitattributes
+* text=auto eol=lf
+
+# Windows script entrypoints
+*.bat text eol=crlf
+*.cmd text eol=crlf
+```
+
+- Repository-specific exceptions are allowed but must be documented in
+  repository instructions.
+
+## EditorConfig conventions
+
+- All repositories should include a root `.editorconfig`.
+- Recommended organization baseline:
+
+```editorconfig
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
+[*.yaml]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = 80
+```
+
+- Repository-specific exceptions are allowed but must be documented in
+  repository instructions.
+- Organization-wide requirement: all Markdown files should keep each line at 80
+  characters or fewer.
+
+### EditorConfig quick rule
+
+- Default action: directly copy the `.editorconfig` sample in this document.
+- If target repository has no root `.editorconfig`, create one from this sample
+  without modification.
+- If target repository already has a root `.editorconfig`, do not replace the
+  whole file; add only missing required keys from this sample.
+- Repository-documented exceptions override this sample.
+- If an exception applies, keep the exception and record it in change notes.
+- Do not include unrelated formatting-only changes in the same commit.
+
+## ESLint conventions
+
+- Repository owners generate `eslint.config.mjs` first (for example via
+  framework scaffolding or ESLint official initialization flow).
+- AI must not replace the existing config wholesale; it should only check the
+  current config and add missing `@produck/eslint-rules` integration.
+- `@produck/eslint-rules` is the organization-wide style consensus and should
+  be present in repository lint configuration.
+- Apply minimal patching only: keep existing repository/framework structure and
+  add the smallest necessary changes.
+- Repository-specific overrides are optional and should be added only when
+  behavior intentionally differs from shared presets.
+- In ESLint flat config, "layer on top" means local override items must appear
+  after shared preset items in exported order.
+- No-op overrides that repeat inherited values should be avoided.
+
+## Language conventions
+
+- Explanations, discussion, and review communication default to Chinese unless
+  the repository or request requires another language.
+- Commit messages keep the bracketed format and use English summaries.
+- PR descriptions and issue comments may use Chinese or English, but keep one
+  language per section and keep terminology consistent.
+- Code identifiers, filenames, and existing public API names should follow
+  existing repository conventions; do not translate existing symbols.
+- User-facing copy should follow the target product locale of the
+  repository/module.
+
+## 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 --package=@produck/agent-toolkit@latest agent-toolkit
+validate-commit-msg --file <message-file>`.
+- 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
+- `[UPGRADE] deps` is allowed for pure dependency upgrades; if IFF artifacts or
+  IPC-related artifacts/calls are updated, the summary must name those updates
+  explicitly.
+- 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
+
+## Terminal long-output protocol
+
+When a command may produce large output (for example 10k+ lines), use a
+two-phase flow instead of shell pipelines like `| grep` or `| tail`.
+
+Node-first policy:
+
+- MUST use Node scripts first for output processing, file processing, path
+  checks, and multi-step command orchestration.
+- MAY use direct shell commands only for short, read-only, atomic checks (for
+  example status/list/current-directory checks).
+- MUST avoid shell pipelines and stream redirection for long-output tasks.
+
+- Phase 1 (capture): run command and write full output to a file first.
+- Phase 2 (analyze): run a separate step to filter/summarize that file.
+
+Recommended three-step flow:
+
+1. Preflight: verify required files/paths and create output directories.
+2. Capture: execute command and persist full output.
+3. Analyze: summarize or filter captured output.
+
+Recommended local tools:
+
+- `npm exec --package=@produck/agent-toolkit@latest agent-toolkit preflight
+--cwd . --require package.json --ensure-dir logs`
+- `npm exec --package=@produck/agent-toolkit@latest agent-toolkit run-capture
+--out logs/run.log --cmd "<command>"`
+- `npm exec --package=@produck/agent-toolkit@latest agent-toolkit summarize-log
+--file logs/run.log --last 120`
+- `npm exec --package=@produck/agent-toolkit@latest agent-toolkit summarize-log
+--file logs/run.log --match "FAIL|ERROR"`
+
+Guardrails:
+
+- Always create output directories before capture.
+- Do not append fragile post-pipelines to the capture command.
+- If filtering fails, keep the captured raw log as the source of truth.
+
+Script placement and lifecycle policy:
+
+- Reusable repository scripts MUST be stored in `scripts/`.
+- Runtime outputs (logs, reports, captures) MUST be stored in `logs/` or
+  repository-defined output directories and ignored by git.
+- For organization-level policy repositories (for example this `.github`
+  repository), do not add runtime-output `.gitignore` only for local agent
+  execution; use session memory paths or local temp locations instead.
+- Temporary diagnostic scripts MUST NOT be committed and MUST use session
+  memory workspace paths when available.
+- Do not place ad-hoc execution scripts in `.git/`, `.github/`, or random root
+  paths.
+- `.github/` is reserved for GitHub platform config (workflows, templates,
+  issue forms), not for temporary run scripts.
+
+## Organization-level AI instruction scope
+
+This repository is the policy source for organization-wide AI instructions.
+
+What works across repositories:
+
+- Organization-level AI instruction text can guide agent behavior in all
+  repositories when configured at organization settings.
+- Rules in `.github/distribution/produck/` are the downstream-sync source.
+- Repository-specific rules may still add stricter constraints.
+
+What does not work automatically:
+
+- Scripts stored in this repository are not auto-mounted into other
+  repositories.
+- Agents in another repository cannot assume local file paths from this
+  repository exist.
+- Cross-repository script execution requires an explicit bridge mechanism.
+
+### Manual instruction distribution workflow
+
+When CI enforcement is deferred, use manual sync per repository:
+
+1. Sync organization downstream source
+   `.github/distribution/produck/*.instructions.md` into target repository
+   `.github/instructions/produck/`.
+2. Keep repository-specific exceptions in `.github/copilot-instructions.md`.
+3. Validate critical policies manually in each update cycle.
+4. After instruction sync, validate duplicated policy sections remain
+   consistent across instruction files, especially commit tag and target
+   whitelists.
+
+Recommended command:
+
+- `npm exec --package=@produck/agent-toolkit@latest -- agent-toolkit sync-instructions --cwd . --source <path-to-org>/.github/distribution/produck --force --prune`
+
+If the package has been published, `--source` can be omitted to use built-in
+assets from `@produck/agent-toolkit`.
+
+This keeps instruction entrypoints aligned without requiring submodule or
+automatic PR rollout.
+
+### Central package execution policy
+
+When bridge mechanism uses a central npm package, default execution strategy is
+`@latest` to deliver new capabilities quickly.
+
+Local implementation reference in this repository:
+
+- `packages/agent-toolkit` stores the central CLI bridge package source.
+- `packages/eslint-rules` stores the shared ESLint rule presets.
+- This local path is the implementation source, not an automatic runtime mount
+  for other repositories.
+
+Required safeguards for `@latest`:
+
+- Print resolved package version before running high-impact commands.
+- For high-risk operations, run dry-run/preview first, then execute.
+- Keep an emergency fallback path to a pinned version for incident mitigation.
+- Prefer `npm exec --package=<pkg>@latest <bin> ...` for predictable invocation.
+
+Version observability (required before high-impact operations):
+
+- `npm view @produck/agent-toolkit version`
+- Record the observed version in task notes or PR description.
+
+Post-release synchronization (required):
+
+- Push release commit: `git push`
+- Push release tag: `git push --tags`
+
+Rollback runbook (minimum):
+
+- Confirm latest published version:
+  `npm view @produck/agent-toolkit version`
+- If rollback is needed, bump from current source and republish a fixed version.
+- Do not republish an already-used version number.
+- Push corresponding commit and tags after rollback publish.
+
+### 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:
+  - Default to `<pkg>@latest` for organization tooling commands.
+  - 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`.
+- Do not assume scripts from organization `.github` repository exist in target
+  repositories.
+- If a repository provides stricter rules, repository rules override
+  organization defaults.
+
+## Precedence
+
+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).

package/publish-assets/instructions/produck/10-produck-node.instructions.md

@@ -0,0 +1,152 @@
+---
+applyTo: '**/*.{js,cjs,mjs,ts,tsx,json,yaml,yml}'
+---
+
+<!-- managed-by: @produck/agent-toolkit -->
+<!-- source: .github/distribution/produck/10-produck-node.instructions.md -->
+
+# Node.js Initialization Baseline
+
+This document defines the organization-level initialization baseline for Node.js
+repositories.
+
+## Scope
+
+- Applies to all Node.js repositories in the `produck` organization, including
+  services, CLI tools, and script/tooling repositories.
+- Supports two repository modes: monorepo and standalone.
+
+## Mode selection
+
+- Monorepo mode: one repository contains multiple Node.js packages/apps.
+- Standalone mode: one repository represents one Node.js package/app.
+- Repository owners should declare the selected mode in the repository README.
+
+## Common baseline (all modes)
+
+- Node.js version policy: LTS required (no fixed major version at organization
+  level).
+- Package manager: npm only.
+- Module system: ESM by default (`"type": "module"` in `package.json`).
+- Follow the organization `.gitattributes` baseline (LF default for text files).
+- Follow the organization `.editorconfig` baseline.
+
+Required script keys:
+
+- `deps:install`
+- `test`
+- `coverage`
+- `lint`
+- `publish`
+
+Notes:
+
+- Script key names are fixed and must match exactly.
+- `publish` may be a no-op when repository-specific release workflow does not
+  use npm publishing.
+
+- Testing strategy and framework are repository-defined.
+- Repositories must keep `npm run test` and `npm run coverage` executable.
+
+Test authoring baseline (required):
+
+- Prefer Node.js standard library test runner (`node:test`) with `describe` and
+  `it`.
+- Each test case must be independently executable.
+- Test cases must not depend on execution order or state from other cases.
+- New test debugging should use local `only` mode for scoped regression.
+- After debugging, remove all `only` markers before final validation.
+
+Recommended local debug flow:
+
+1. Add `{ only: true }` to the target `describe/it` and all ancestor
+   `describe` blocks.
+2. Run `node --test --test-only test/index.mjs`.
+3. Remove all `only` markers.
+4. Run full regression via repository standard test command.
+
+Script and output directory policy:
+
+- Reusable project scripts should be committed under root `scripts/`.
+- Organization-level shared tooling may use a central npm package bridge instead
+  of repository-local `scripts/` duplication.
+- Runtime command outputs should be written under root `logs/` (or a documented
+  equivalent) and ignored by git.
+- Temporary debug scripts should not be committed.
+- `.github/` should not be used as a temporary script workspace.
+
+Required ignore baseline:
+
+- Each Node.js repository must include a root `.gitignore`.
+- The root `.gitignore` must start from the GitHub default template for Node.js
+  projects (`Node.gitignore` from github/gitignore).
+- Team-specific ignore conventions should be appended on top of that baseline
+  template, not used as a replacement.
+- The root `.gitignore` should at minimum ignore:
+  - `node_modules/`
+  - `coverage/`
+  - `.env`
+  - `.env.*`
+  - npm logs (for example `npm-debug.log*`)
+  - OS/editor noise (for example `.DS_Store`, `Thumbs.db`, `.vscode/` when
+    workspace settings are not intended to be shared)
+
+Team conventions for `.gitignore`:
+
+- Keep organization-wide additions grouped under a dedicated comment block for
+  easy updates.
+- Do not remove baseline entries from the GitHub template unless repository
+  owners document a justified exception.
+- Organization-approved team extension entries are:
+  - `*.ign*` (manually created local directories/files that should not be
+    committed)
+  - `*.gen*` (generated artifacts created by program execution, for example
+    during tests)
+- Append these team entries under a dedicated team block at the end of the root
+  `.gitignore`.
+
+## Monorepo mode
+
+Repository layout:
+
+- Root-level `docs/` is required.
+- Each package/app should contain its own `src/` and `test/`.
+
+Script placement:
+
+- Root `package.json` must provide `deps:install`, `test`, `coverage`, and
+  `lint` orchestration scripts.
+- `publish` may be defined at root or package level based on release workflow.
+
+Ignore strategy:
+
+- Keep ignore rules centralized at repository root whenever possible.
+- Add package-level `.gitignore` only when a package has unique generated
+  artifacts.
+
+## Standalone mode
+
+Repository layout:
+
+- Top-level `src/`, `test/`, and `docs/` are required.
+
+Script placement:
+
+- The repository root `package.json` must define `deps:install`, `test`,
+  `coverage`, `lint`, and `publish`.
+
+Ignore strategy:
+
+- Keep project-specific generated files ignored in the repository root
+  `.gitignore`.
+
+## Enforcement strategy
+
+- This baseline is enforced by documentation first.
+- CI enforcement can be added later with repository checks.
+
+## Precedence
+
+- Repository-specific rules may add stricter requirements.
+- If repository-specific rules conflict with this document, repository owners
+  should explicitly document the exception.