agents-md-kit 0.1.1 → 0.2.1

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,7 +88,7 @@ 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.
@@ -94,8 +97,7 @@ Verified on 2026-11-11 (Windows 11, Node 22.18, npm 11.19, Python 3.13):
 
 **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.
+- 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-md-kit",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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') {