From fb31a696c99dc840514731e894e31ff46076af2a Mon Sep 17 00:00:00 2001 From: Santiago Molina Date: Thu, 30 Jul 2026 03:53:49 -0500 Subject: [PATCH 1/6] feat(setup): add project and editor setup --- .changeset/warm-pens-smile.md | 9 + .cspell.json | 3 + IMPROVEMENTS.md | 101 +++ apps/docs/public/llms-full.txt | 57 +- apps/docs/public/llms.txt | 4 + apps/docs/src/pages/docs.astro | 90 ++- packages/commitprompt/AI.md | 11 + packages/commitprompt/README.md | 82 ++- packages/commitprompt/bin/commitprompt.ts | 356 ++++++++- packages/commitprompt/package.json | 1 + packages/commitprompt/src/automation.ts | 13 +- packages/commitprompt/src/index.ts | 22 + packages/commitprompt/src/instructions.ts | 34 + packages/commitprompt/src/package-manager.ts | 34 + packages/commitprompt/src/project.ts | 694 ++++++++++++++++++ packages/commitprompt/src/vscode.ts | 96 ++- packages/commitprompt/src/workspace-editor.ts | 108 +++ packages/commitprompt/src/zed.ts | 43 +- packages/commitprompt/templates/AGENTS.md | 15 + .../templates/copilot-instructions.md | 15 + .../templates/skills/commitprompt/SKILL.md | 25 + .../commitprompt/tests/automation.test.ts | 24 + packages/commitprompt/tests/binary.test.ts | 139 ++++ .../tests/fixtures/vscode-settings.jsonc | 25 + .../commitprompt/tests/instructions.test.ts | 28 + packages/commitprompt/tests/project.test.ts | 466 ++++++++++++ .../commitprompt/tests/public-api.test.ts | 29 +- packages/commitprompt/tests/vscode.test.ts | 83 +++ .../tests/workspace-editor.test.ts | 134 ++++ packages/commitprompt/tests/zed.test.ts | 52 ++ scripts/check-packed-install.mjs | 263 ++++++- scripts/verify-published-package.mjs | 32 +- 32 files changed, 2995 insertions(+), 93 deletions(-) create mode 100644 .changeset/warm-pens-smile.md create mode 100644 IMPROVEMENTS.md create mode 100644 packages/commitprompt/src/instructions.ts create mode 100644 packages/commitprompt/src/package-manager.ts create mode 100644 packages/commitprompt/src/project.ts create mode 100644 packages/commitprompt/src/workspace-editor.ts create mode 100644 packages/commitprompt/templates/AGENTS.md create mode 100644 packages/commitprompt/templates/copilot-instructions.md create mode 100644 packages/commitprompt/templates/skills/commitprompt/SKILL.md create mode 100644 packages/commitprompt/tests/fixtures/vscode-settings.jsonc create mode 100644 packages/commitprompt/tests/instructions.test.ts create mode 100644 packages/commitprompt/tests/project.test.ts create mode 100644 packages/commitprompt/tests/workspace-editor.test.ts diff --git a/.changeset/warm-pens-smile.md b/.changeset/warm-pens-smile.md new file mode 100644 index 0000000..338b67b --- /dev/null +++ b/.changeset/warm-pens-smile.md @@ -0,0 +1,9 @@ +--- +"@santi020k/commitprompt": minor +--- + +Accept comments and trailing commas when adding commit-generation instructions to VS Code settings. + +Add `commitprompt setup project` to configure the development dependency, package script, Husky commit-message validation, and guarded AI instructions. Include check, dry-run, and JSON output modes for automation. + +Add repository-aware workspace editor setup, published AI instruction templates, reusable agent skills, and clearer blocked-commit diagnostics. diff --git a/.cspell.json b/.cspell.json index 63b11e2..858a248 100644 --- a/.cspell.json +++ b/.cspell.json @@ -9,12 +9,15 @@ "Autobuild", "autorelease", "Commitprompt", + "Commitizen", "commitlint", + "Czg", "domexception", "esbuild", "eslintcache", "knip", "lede", + "lockfiles", "publint", "santi", "Turborepo", diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md new file mode 100644 index 0000000..7e4adfa --- /dev/null +++ b/IMPROVEMENTS.md @@ -0,0 +1,101 @@ +# Commitprompt next-release improvements + +This document records the v1 adoption findings, what is implemented for the +next release, and the remaining work that should guide a later iteration. + +## Implemented for the next release + +### Valid VS Code JSONC + +- VS Code settings accept comments and trailing commas at every nesting level. +- Existing formatting, comments, custom instructions, and model preferences are + preserved. +- Realistic exported settings and repeat-run idempotency are covered by tests. + +### Repository setup + +`commitprompt setup project` now: + +- detects npm, pnpm, or Yarn from repository metadata and lockfiles; +- adds Commitprompt and Husky development dependencies; +- respects pnpm workspace catalogs; +- sets the neutral `commitprompt` package script; +- installs the canonical `commit-msg` validation hook while preserving + unrelated hook commands; +- updates the dependency installation and lockfile with the detected package + manager; +- writes guarded AGENTS.md and GitHub Copilot instructions; +- installs reusable Commitprompt skills for common agent layouts; +- reports obsolete Commitizen, Czg, and custom prompt configuration without + deleting it. + +The command supports independent `--only` actions, `--check`, `--dry-run`, +`--json`, `--cwd`, and `--skip-install`. + +### Repository-aware editor instructions + +`commitprompt setup editors` writes tracked VS Code and Zed workspace settings +using the repository's configured types and scopes. It preserves user-authored +instructions, never writes machine-specific model preferences, and supports +editor selection plus check, preview, JSON, and alternate-working-directory +modes. + +### Hook diagnostics and AI assets + +- Invalid hooks explicitly state that the commit was blocked, list violated + rules, and provide a correction-and-retry workflow. +- npm, pnpm, and Yarn hook examples use the same canonical validation command. +- A real Husky integration test accepts a valid message and rejects an invalid + one. +- Versioned AGENTS.md, GitHub Copilot, and agent-skill templates ship from one + canonical source. +- The instructions require repository and diff inspection, type and scope + discovery, structured formatting, exact validation, explicit authorization, + and normal Git hooks. + +### Release verification + +The consumer smoke test installs the artifact with npm, pnpm, and Yarn and +checks: + +1. the interactive binary; +2. `types`, `scopes`, `instructions`, `format`, and `validate`; +3. realistic VS Code and Zed JSONC; +4. project and editor setup idempotency; +5. generated hook enforcement; +6. published templates, declaration maps, and source maps. + +Published-package verification also checks the npm `latest` dist-tag and runs +the same consumer workflow against the registry artifact. + +## Remaining improvement: isolate Commitlint's TypeScript loader + +Yarn 1 reports unmet `@types/node` and `typescript` peers from +`cosmiconfig-typescript-loader`, a transitive dependency of `@commitlint/load`. +Version 6.3.0 declares both peers as mandatory and provides no +`peerDependenciesMeta` entries. + +Adding TypeScript and its Node types to Commitprompt would silence the warning, +but would violate the dependency-light goal for JavaScript-config consumers. +The warning is therefore documented rather than hidden. + +For a later release, evaluate these options in order: + +1. contribute optional peer metadata or lazy TypeScript loading upstream; +2. adopt an upstream Commitlint release after it makes the peers optional; +3. isolate configuration loading behind an optional adapter while retaining + JavaScript configuration support by default. + +Acceptance remains: minimal npm, pnpm, and Yarn consumers install without +dependency warnings and without adding TypeScript to Commitprompt's default +runtime dependencies. + +## Candidates for the following release + +- Add an explicitly confirmed cleanup mode for obsolete Commitizen/Czg + dependencies and configuration. +- Detect monorepo roots when setup starts from a nested workspace package and + report which manifest, catalog, and hook will be changed. +- Add a setup report format suitable for pull-request annotations. +- Explore editor-native validation feedback so generated messages can be + corrected before Git invokes the authoritative hook. diff --git a/apps/docs/public/llms-full.txt b/apps/docs/public/llms-full.txt index 675514c..73f88b0 100644 --- a/apps/docs/public/llms-full.txt +++ b/apps/docs/public/llms-full.txt @@ -99,7 +99,9 @@ import { createGitClient, formatCommitMessage, runAutomation, - runCommitFlow + runCommitFlow, + setupProject, + setupWorkspaceEditors } from '@santi020k/commitprompt' ``` @@ -107,7 +109,9 @@ import { `createCommitlintValidator(cwd)` returns cached `getTypes()`, `getScopes()`, and `validate(message)` operations. `createGitClient(cwd)` checks staged changes and commits through Git. `runAutomation(options)` powers the non-interactive commands. -`runCommitFlow(options)` powers the interactive workflow. +`runCommitFlow(options)` powers the interactive workflow. `setupProject(options)` +and `setupWorkspaceEditors(options)` provide non-interactive repository setup +and drift checking. The package is ESM-only. Every value and type exported from the package root is stable and follows semantic versioning. Source and `dist/` file paths are @@ -120,12 +124,46 @@ existing documented behavior and required inputs will not change incompatibly. ```sh commitprompt setup zed commitprompt setup vscode +commitprompt setup editors ``` -These commands add global Conventional Commit generation instructions while -preserving existing editor settings and model selection. VS Code uses GitHub -Copilot. Editor-generated messages do not pass through Commitprompt validation -unless separately validated. +The Zed and VS Code commands add global Conventional Commit generation +instructions while preserving existing settings and model selection. The +`editors` command creates tracked, repository-aware workspace settings using +configured types and scopes. It supports `--editor`, `--dry-run`, `--check`, +`--json`, and `--cwd`. + +Editor-generated messages do not pass through Commitprompt validation unless +the repository installs the hook below. + +## Project setup + +```sh +commitprompt setup project +``` + +This idempotent command detects npm, pnpm, or Yarn; adds Commitprompt and Husky; +sets the `commit` script; installs a `commit-msg` hook; adds guarded AGENTS.md +and GitHub Copilot instructions; and installs reusable agent skills. It reports +obsolete Commitizen, Czg, and custom prompt configuration without deleting it. +Run the detected package manager's install command afterward to update the +lockfile and activate Husky. + +Use `--dry-run` to preview, `--check` as a non-writing CI drift gate, `--json` +for machine-readable output, and `--only` to select actions. The canonical hook +is: + +```sh +commitprompt validate --input "$1" +``` + +Equivalent explicit npm, pnpm, and Yarn commands are: + +```sh +npx --no-install commitprompt validate --input "$1" +pnpm exec commitprompt validate --input "$1" +yarn exec commitprompt validate --input "$1" +``` ## Safety boundaries @@ -133,9 +171,10 @@ unless separately validated. - The interactive flow asks before committing. - The non-interactive flow requires `--yes`. - Commitprompt does not disable Git hooks. -- Commitprompt does not install a `commit-msg` hook. -- Enforce all Git-created messages by configuring Commitlint in a - repository `commit-msg` hook. +- Project setup installs a guarded `commit-msg` hook without deleting unrelated + hook commands. +- A failed hook states that the commit was blocked and reports violated rules. +- Never bypass validation with `--no-verify`. ## Links diff --git a/apps/docs/public/llms.txt b/apps/docs/public/llms.txt index 181e189..03b6706 100644 --- a/apps/docs/public/llms.txt +++ b/apps/docs/public/llms.txt @@ -8,6 +8,10 @@ the target repository and staged diff, run `commitprompt types --json` and committing. A non-interactive commit requires the explicit `--yes` flag and leaves Git hooks enabled. +Use `commitprompt setup project` for package-manager-neutral repository +enforcement and reusable AI instructions. Use `commitprompt setup editors` for +tracked, repository-aware Zed and VS Code generation guidance. + ## Documentation - [Documentation](https://commitprompt.santi020k.com/docs/): Installation, interactive use, repository rules, automation commands, and programmatic API. diff --git a/apps/docs/src/pages/docs.astro b/apps/docs/src/pages/docs.astro index 11d34e6..fc725ed 100644 --- a/apps/docs/src/pages/docs.astro +++ b/apps/docs/src/pages/docs.astro @@ -64,6 +64,27 @@ Closes #123` const usageCommand = 'git add src/\npnpm commit' +const hookItems = [ + { + code: 'npx --no-install commitprompt validate --input "$1"', + label: 'npm', + language: 'shell', + value: 'npm' + }, + { + code: 'pnpm exec commitprompt validate --input "$1"', + label: 'pnpm', + language: 'shell', + value: 'pnpm' + }, + { + code: 'yarn exec commitprompt validate --input "$1"', + label: 'Yarn', + language: 'shell', + value: 'yarn' + } +] as const + const automationExample = `commitprompt instructions --json commitprompt scopes --json commitprompt types --json @@ -111,6 +132,7 @@ await runCommitFlow({