agents-md-kit 0.1.0 → 0.2.0

package/README.md

@@ -23,8 +23,11 @@ Requires Node 20 or newer to run the installer. Your project does not need Node
 npx agents-md-kit install [--preset <name>]... [--pack <name>]... [--target <dir>] [--apply]
 npx agents-md-kit validate [--target <dir>] [--template]
 npx agents-md-kit list
+npx agents-md-kit --help
 ```
 
+`--help` prints the usage, every pack and preset with a short description, and examples. `list` prints just the packs and presets.
+
 Exit codes: `0` success, `1` error, `2` install finished with conflicts (review the `.new` files).
 
 ## What gets installed
@@ -85,17 +88,17 @@ Run the same install command again with a newer kit. Managed blocks update in pl
 ## What is verified, and what is not
 
 Verified on 2026-11-11 (Windows 11, Node 22.18, npm 11.19, Python 3.13):
-- **Test suite:** `npm test` (installer and validator, run in temp directories).
+- **Test suite:** `npm test` (installer and validator, run in temp directories). CI runs the type-check, the tests and `validate --template` on Node 20, 22 and 24 on Linux, macOS and Windows. On the Node 20 runners all 45 tests ran with none skipped, including the real exec-bit and file-symlink checks.
 - **react-typescript:** a planted bad component yields exactly 7 ESLint problems (5 errors, 2 warnings). A clean component passes ESLint and Prettier. husky rejects a bad commit message, accepts a good one and blocks a staged lint error.
 - **node-backend:** the same commitlint/husky checks pass. ESLint catches planted errors in a TypeScript sample.
 - **python:** `ruff check`, `ruff format --check`, `pytest` and `mypy` pass on a sample. pre-commit rejects a bad commit message, accepts a good one and blocks a staged Ruff error.
 - **Clean install:** every preset installs, validates, and re-installs as a no-op.
+- **From the npm registry:** `npx agents-md-kit` (v0.1.0) lists the units, installs the `python` preset with the `github` pack, validates, and a second `--apply` writes nothing.
 
 **Untested:**
 - GitHub Actions workflows (`ci.yml`, `pr-title.yml`, `release-please.yml`), Dependabot configs and release-please behavior. They parse (light check only for YAML) but have never run. The pinned action majors (`actions/checkout@v4`, `setup-node@v4`, `setup-python@v5`, `release-please-action@v4`, `action-semantic-pull-request@v5`) are behind the latest majors. Dependabot will propose updates; review their changelogs before merging.
-- Node 20 (only Node 22 was run).
-- macOS and Linux. Setting the exec bit and refusing file symlinks were exercised only through simulation and Windows junctions.
-- pnpm/yarn variants, and running from the npm registry (`npx agents-md-kit` was run from a local `npm pack` tarball only).
+- The presets' real-tool checks (ESLint, husky, Ruff, pre-commit) were run on Windows only. On Linux and macOS, only the installer's test suite has run, not the presets' tools.
+- pnpm/yarn variants.
 
 `.claude/settings.json` deny rules use the documented `Bash(cmd *)` and `Read(./path)` forms (checked against the Claude Code permissions docs on 2026-11-11). Prefix deny rules are a guard rail, not a sandbox: a reordered command (`git push origin main --force`) is not matched.
 
@@ -132,6 +135,19 @@ npm run check       # type-check, tests and template validation
 
 The source is plain JavaScript with JSDoc types, checked by `tsc --noEmit`. There is no build step: the files in `src/` are the files that ship.
 
+### Releasing
+
+Releases are published from GitHub Actions with npm trusted publishing: no npm token is stored, and the run authenticates over OIDC. One-time setup, on npmjs.com under the package's Settings > Trusted Publisher > GitHub Actions: user `Rumpz`, repository `agents-md-kit`, workflow filename `publish.yml`, no environment. (A new trusted-publisher entry expires unless its first publish succeeds within 2 days.)
+
+Then, for each release:
+
+```bash
+npm version patch          # or minor / major; bumps package.json and creates the vX.Y.Z tag
+git push --follow-tags
+```
+
+`.github/workflows/publish.yml` runs type-check, tests and template validation, checks the tag matches `package.json`, and publishes. To rehearse everything except the upload, run the workflow by hand from the Actions tab (it ends in `npm publish --dry-run`). That only passes when `package.json` holds a version that isn't on npm yet, so bump it first (`npm version patch --no-git-tag-version`, commit and push); on an already-published version it stops with "You cannot publish over the previously published versions".
+
 Installed files keep the short `agent-kit` name in two places: the managed-block markers (`agent-kit:<id>`) and the `docs/agent-kit/` folder.
 
 ## How this kit was built

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-md-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Installs AI-agent configuration (AGENTS.md, skills, memory, presets) into a repository. Dry run by default, never overwrites.",
   "keywords": [
     "agents-md",

package/src/cli.js

@@ -12,9 +12,16 @@ const USAGE = `Usage:
   agents-md-kit install [--preset <name>]... [--pack <name>]... [--target <dir>] [--apply]
   agents-md-kit validate [--target <dir>] [--template]
   agents-md-kit list
+  agents-md-kit --help
 
 install is a dry run unless --apply is given. core is always installed.`;
 
+const EXAMPLES = `Examples:
+  agents-md-kit install --preset react-typescript --pack github   preview, writes nothing
+  agents-md-kit install --preset python --pack github --apply     install into this directory
+  agents-md-kit install --pack web --target ../my-repo --apply    core + web into another repo
+  agents-md-kit validate                                          check what was installed`;
+
 export function parseArgs(/** @type {string[]} */ argv) {
   const [command, ...rest] = argv;
   /** @type {{ command: string, presets: string[], packs: string[], target: string, apply: boolean, template: boolean, help: boolean }} */
@@ -63,6 +70,44 @@ export function parseArgs(/** @type {string[]} */ argv) {
 
 /** @typedef {(line: string) => void} Print */
 
+const WRAP_COLUMNS = 100;
+
+/** Wrap `text` after a `prefix`, indenting continuation lines under the text. */
+function wrapAfter(/** @type {string} */ prefix, /** @type {string} */ text) {
+  const pad = ' '.repeat(prefix.length);
+  /** @type {string[]} */
+  const lines = [];
+  let line = '';
+  for (const word of text.split(/\s+/).filter(Boolean)) {
+    if (line && prefix.length + line.length + 1 + word.length > WRAP_COLUMNS) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  lines.push(line);
+  return lines.map((l, i) => (i === 0 ? prefix : pad) + l).join('\n');
+}
+
+/** Print core, packs and presets with their descriptions (shared by `list` and `--help`). */
+function printUnits(/** @type {import('./manifest.js').Units} */ units, /** @type {Print} */ out) {
+  out('core (always installed)');
+  out(wrapAfter('  ', units.core.description));
+  for (const [label, map] of /** @type {const} */ ([
+    ['packs (--pack)', units.packs],
+    ['presets (--preset)', units.presets],
+  ])) {
+    out('');
+    out(`${label}:`);
+    if (map.size === 0) out('  (none)');
+    for (const u of map.values()) {
+      const inc = u.implies.length ? ` (also installs pack ${u.implies.join(', ')})` : '';
+      out(wrapAfter(`  ${u.name.padEnd(18)} `, `${u.description}${inc}`));
+    }
+  }
+}
+
 function printReport(
   /** @type {{ errors: string[], warnings: string[], notes: string[] }} */ { errors, warnings, notes },
   /** @type {Print} */ out,
@@ -81,25 +126,23 @@ export function main(/** @type {string[]} */ argv, { out = console.log, err = co
     return 1;
   }
   if (opts.help) {
+    out('agents-md-kit: install AI-agent config (AGENTS.md, skills, memory, tooling) into a repo.');
+    out('');
     out(USAGE);
+    try {
+      out('');
+      printUnits(loadUnits(kitRoot), out);
+    } catch {
+      // A damaged kit still gets the usage text; `validate --template` explains what is wrong.
+    }
+    out('');
+    out(EXAMPLES);
     return 0;
   }
   const target = path.resolve(cwd, opts.target);
   try {
     if (opts.command === 'list') {
-      const units = loadUnits(kitRoot);
-      out(`core (always installed)\n  ${units.core.description}`);
-      for (const [label, map] of /** @type {const} */ ([
-        ['packs (--pack)', units.packs],
-        ['presets (--preset)', units.presets],
-      ])) {
-        out(`\n${label}:`);
-        if (map.size === 0) out('  (none)');
-        for (const u of map.values()) {
-          const inc = u.implies.length ? ` (also installs pack ${u.implies.join(', ')})` : '';
-          out(`  ${u.name.padEnd(18)} ${u.description}${inc}`);
-        }
-      }
+      printUnits(loadUnits(kitRoot), out);
       return 0;
     }
     if (opts.command === 'validate') {