agentme 0.3.1 → 0.3.3

package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md

@@ -8,7 +8,7 @@ What tooling and project structure should JavaScript/TypeScript projects follow
 
 ## Decision Outcome
 
-**Use pnpm, tsc, esbuild, eslint, and jest with a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
+**Use a Mise-managed Node.js and pnpm toolchain together with pnpm, tsc, esbuild, eslint, and jest in a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
 
 Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelines, and a predictable developer experience across projects.
 
@@ -18,30 +18,40 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
 
 | Tool | Purpose |
 |------|---------|
+| **Mise** | Tool version management for Node.js, pnpm, and project CLIs |
 | **pnpm** | Package manager — strict linking, workspace support, fast installs |
 | **tsc** | TypeScript compilation — type checking, declaration generation |
 | **esbuild** | Bundling — fast bundling for distribution or single-binary outputs |
 | **eslint** | Linting — code style and quality enforcement |
 | **jest** | Testing — unit and integration test runner |
 
-All commands are run exclusively through Makefiles, not through `package.json` scripts.
+All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root must define a `.mise.toml` that pins at least Node.js and pnpm, and Makefile targets must run through `mise exec --` or an activated Mise shell.
 
 #### ESLint
 
-Use `@stutzlab/eslint-config` as the base ESLint config. Use ESLint 9 flat config format (`lib/eslint.config.js`).
+Use `lib/eslint.config.mjs` as the ESLint entry point and configure it with `@stutzlab/eslint-config` plus `FlatCompat` from `@eslint/eslintrc`. Keep `package.json` in CommonJS mode without adding `"type": "module"`.
+
+In flat-config mode, Makefile lint targets MUST NOT use `--ext`; file matching is defined in `eslint.config.mjs` instead. The flat config MUST declare TypeScript file globs such as `src/**/*.ts` and point `parserOptions.project` to `./tsconfig.json`.
+
+#### TypeScript and Jest
+
+Use a single `lib/tsconfig.json` for both build and type-aware linting. Keep co-located `*.test.ts` files included in that config so ESLint can resolve them through `parserOptions.project`, and rely on the Makefile cleanup step to remove compiled test artifacts from `dist/` after `tsc` runs.
+
+When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `module` is `nodenext`. `ts-jest` still runs in CommonJS mode by default, so `lib/jest.config.js` MUST configure the `ts-jest` transform with an inline `tsconfig` override that sets `module: 'commonjs'`. Do not use the deprecated `globals['ts-jest']` configuration style.
 
 #### Project structure
 
 ```
 /                          # workspace root
+├── .mise.toml             # pinned Node.js and pnpm versions
 ├── Makefile               # delegates build/lint/test to /lib and /examples
 ├── README.md              # Quick Start first; used as npm registry page
 ├── lib/                   # the published npm package
 │   ├── Makefile           # build, lint, test, publish targets
 │   ├── package.json       # package manifest
-│   ├── tsconfig.json      # TypeScript config
+│   ├── tsconfig.json      # TypeScript config for build and linting
 │   ├── jest.config.js     # Jest config
-│   ├── eslint.config.js   # ESLint config (ESLint 9 flat config)
+│   ├── eslint.config.mjs  # ESLint config (ESLint 9 flat config)
 │   └── src/               # all TypeScript source files
 │       ├── index.ts       # public API re-exports
 │       └── *.test.ts      # test files co-located with source
@@ -53,7 +63,9 @@ Use `@stutzlab/eslint-config` as the base ESLint config. Use ESLint 9 flat confi
         └── package.json
 ```
 
-The root `Makefile` delegates every target to `/lib` then `/examples` in sequence.
+The root `Makefile` delegates every target to `/lib` then `/examples` in sequence and is expected to execute module commands inside the repository's Mise-managed environment.
+
+The commands below assume they are invoked through `mise exec -- make <target>` or from an activated Mise shell.
 
 #### lib/Makefile targets
 

package/.xdrs/agentme/edrs/application/skills/001-create-javascript-project/SKILL.md

@@ -2,7 +2,7 @@
 name: 001-create-javascript-project
 description: >
   Scaffolds the initial boilerplate structure for a JavaScript/TypeScript library project following
-  the standard tooling and layout defined in _core-edr-003. Activate this skill when the user
+  the standard tooling and layout defined in agentme-edr-003. Activate this skill when the user
   asks to create, scaffold, or initialize a new JavaScript or TypeScript library project, npm
   package, or similar project structure.
 metadata:
@@ -42,27 +42,30 @@ Delegates every make target to `/lib` then `/examples` in sequence:
 
 ```makefile
 SHELL := /bin/bash
+MISE := mise exec --
 %:
 	@echo ''
 	@echo '>>> Running /lib:$@...'
-	@cd lib && make $@
+  @$(MISE) $(MAKE) -C lib $@
 	@echo ''
 	@echo '>>> Running /examples:$@...'
-	@cd examples && STAGE=dev make $@
+  @STAGE=dev $(MISE) $(MAKE) -C examples $@
 
 publish:
-	cd lib && make publish
+  @$(MISE) $(MAKE) -C lib publish
 
-prepare:
-	@echo "Run 'nvm use; corepack enable'"
+setup:
+  mise install
 ```
 
-**`./.nvmrc`**
+**`./.mise.toml`**
 
 ```
-24
+[tools]
+node = "24.0.0"
+pnpm = "10.14.0"
 ```
-(Replace `24` with the chosen Node.js version.)
+(Replace `24.0.0` with the chosen Node.js version and pin any additional project CLIs here.)
 
 **`./.gitignore`**
 
@@ -101,30 +104,31 @@ describe('hello', () => {
 
 ```makefile
 SHELL := /bin/bash
+MISE := mise exec --
 
 build: install
 	@rm -rf dist
-	pnpm exec tsc --outDir dist
+  $(MISE) pnpm exec tsc --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 	@# Create pack for use by examples to simulate real external usage
-	pnpm pack --pack-destination dist
+  $(MISE) pnpm pack --pack-destination dist
 
 build-module: install
 	@rm -rf dist
-	pnpm exec tsc --outDir dist
+  $(MISE) pnpm exec tsc --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 
 lint:
-	pnpm exec eslint ./src --ext .ts
+  $(MISE) pnpm exec eslint ./src
 
 lint-fix:
-	pnpm exec eslint . --ext .ts --fix
+  $(MISE) pnpm exec eslint ./src --fix
 
 test-watch:
-	pnpm exec jest --watch
+  $(MISE) pnpm exec jest --watch
 
 test:
-	pnpm exec jest --verbose
+  $(MISE) pnpm exec jest --verbose
 
 clean:
 	rm -rf node_modules
@@ -133,22 +137,25 @@ clean:
 all: build lint test
 
 install:
-	pnpm install --frozen-lockfile --config.dedupe-peer-dependents=false
+  mise install
+  $(MISE) pnpm install --frozen-lockfile --config.dedupe-peer-dependents=false
 
 publish:
-	npx -y monotag@1.26.0 current --bump-action=latest --prefix=
-	@VERSION=$$(node -p "require('./package.json').version"); \
+  $(MISE) npx -y monotag@1.26.0 current --bump-action=latest --prefix=
+  @VERSION=$$($(MISE) node -p "require('./package.json').version"); \
 	if echo "$$VERSION" | grep -q '-'; then \
 		TAG=$$(echo "$$VERSION" | sed 's/[0-9]*\.[0-9]*\.[0-9]*-\([a-zA-Z][a-zA-Z0-9]*\).*/\1/'); \
 		echo "Prerelease version $$VERSION detected, publishing with --tag $$TAG"; \
-		npm publish --no-git-checks --provenance --tag "$$TAG"; \
+    $(MISE) npm publish --no-git-checks --provenance --tag "$$TAG"; \
 	else \
-		npm publish --no-git-checks --provenance; \
+    $(MISE) npm publish --no-git-checks --provenance; \
 	fi
 ```
 
 **`lib/package.json`** (replace `[package-name]`, `[description]`, `[author]`, `[owner]`, `[repo]`):
 
+Use this dependency set.
+
 ```json
 {
   "name": "[package-name]",
@@ -161,7 +168,7 @@ publish:
     "package.json",
     "README.md"
   ],
-  "packageManager": "pnpm@8.9.0",
+  "packageManager": "pnpm@10.14.0",
   "scripts": {},
   "repository": {
     "type": "git",
@@ -174,19 +181,23 @@ publish:
   },
   "homepage": "https://github.com/[owner]/[repo]#readme",
   "devDependencies": {
-    "@babel/preset-typescript": "^7.21.0",
+    "@eslint/eslintrc": "^3.3.1",
     "@stutzlab/eslint-config": "^3.2.1",
-    "@tsconfig/node24": "^24.0.0",
-    "@types/jest": "^29.5.0",
+    "@tsconfig/node24": "^24.0.1",
+    "@types/jest": "^29.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.31.0",
+    "@typescript-eslint/parser": "^8.31.0",
     "esbuild": "^0.20.0",
-    "eslint": "^8.57.0",
+    "eslint": "^9.25.1",
     "jest": "^29.7.0",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.3.0"
+    "ts-jest": "^29.4.0",
+    "typescript": "^5.9.0"
   }
 }
 ```
 
+Keep `package.json` without `"type": "module"`. Use `eslint.config.mjs` as the ESLint entry point so Jest can continue to run with its default CommonJS runtime.
+
 **`lib/tsconfig.json`**:
 
 ```json
@@ -200,39 +211,65 @@ publish:
     "sourceMap": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+  "exclude": ["node_modules", "dist"]
 }
 ```
 
+Use this single tsconfig for both build and type-aware linting. Keep `*.test.ts` included so ESLint can resolve them through `parserOptions.project`, and rely on the existing `dist/` cleanup in the Makefile to remove emitted test files after compilation.
+
 **`lib/jest.config.js`**:
 
 ```javascript
 module.exports = {
-  preset: 'ts-jest',
   testEnvironment: 'node',
   testMatch: ['**/*.test.ts'],
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'commonjs',
+        },
+      },
+    ],
+  },
 };
 ```
 
-**`lib/eslint.config.js`** (ESLint 9 flat config format):
+This avoids the deprecated `globals['ts-jest']` configuration style while forcing `ts-jest` to transpile with CommonJS instead of the `nodenext` default inherited from `@tsconfig/node24`.
+
+**`lib/eslint.config.mjs`** (ESLint 9 flat config format):
 
 ```js
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FlatCompat } from '@eslint/eslintrc';
 import baseConfig from '@stutzlab/eslint-config';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
 export default [
-  ...baseConfig,
+  ...compat.config(baseConfig),
   {
+    files: ['src/**/*.ts'],
     languageOptions: {
       parserOptions: {
         project: ['./tsconfig.json'],
-        tsconfigRootDir: process.cwd(),
+        tsconfigRootDir: __dirname,
       },
     },
   },
 ];
 ```
 
+Do not name this file `eslint.config.js` unless the generated package also opts into ESM with `"type": "module"`, because that produces Node.js warnings and conflicts with the recommended Jest CommonJS setup.
+
 ---
 
 ### Phase 4: Create `examples/`
@@ -335,17 +372,19 @@ Review all created files and confirm:
 - [ ] `lib/src/index.ts` exports at least one symbol
 - [ ] `lib/src/index.test.ts` has at least one passing test
 - [ ] `lib/package.json` has `main`, `types`, and `files` set correctly
+- [ ] `lib/tsconfig.json` includes co-located `src/**/*.test.ts` files for ESLint type-aware parsing
+- [ ] `lib/eslint.config.mjs` points `parserOptions.project` to `tsconfig.json`
 - [ ] `README.md` starts with Quick Start containing a code example
 - [ ] All `[package-name]` placeholders are replaced with the actual name
-- [ ] Structure matches the layout in [_core-edr-003](../../003-javascript-project-tooling.md)
+- [ ] Structure matches the layout in [agentme-edr-003](../../003-javascript-project-tooling.md)
 
 ## Examples
 
 **User:** "Create a new TypeScript library project called `retry-client`"
 
 **Agent action:** Gathers: name=`retry-client`, default Node.js 24, then creates:
-- `./Makefile`, `./.nvmrc`, `./.gitignore`
-- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.js`
+- `./Makefile`, `./.mise.toml`, `./.gitignore`
+- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.mjs`
 - `examples/Makefile`, `examples/usage-basic/package.json`, `examples/usage-basic/index.js`
 - `README.md` (Quick Start first)
 
@@ -354,7 +393,7 @@ All `[package-name]` replaced with `retry-client`.
 ## Edge Cases
 
 - **Existing files** — skip creation; adapt references to the existing structure
-- **Different Node.js version** — update `.nvmrc` and `tsconfig.json` `extends` (e.g. `@tsconfig/node22`)
+- **Different Node.js version** — update `.mise.toml` and `tsconfig.json` `extends` (e.g. `@tsconfig/node22`)
 - **CLI tool** — add `"bin": "dist/main.js"` to `package.json` and create `lib/src/main.ts` as the CLI entry point; add `esbuild` bundle target in `lib/Makefile`
 - **No examples needed** — omit the `examples/` directory; remove the `examples` delegation from root `Makefile`
 - **Binary bundling (Lambda/browser)** — add an esbuild step to `lib/Makefile`: `pnpm exec esbuild src/main.ts --bundle --platform=node --outfile=dist/bundle.js`

package/.xdrs/index.md

@@ -9,7 +9,7 @@ XDRs in scopes listed last override the ones listed first
 ### _core
 
 Decisions about how XDRs work
-[View general ADRs Index](_core/adrs/index.md)
+[View _core ADRs Index](_core/adrs/index.md)
 
 ---
 
@@ -23,8 +23,4 @@ Opiniated set of decisions and skills for common development tasks
 
 ### _local (reserved)
 
-Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Add specific `_local` ADR/BDR/EDR index links here when present.
-
-[View _local BDRs Index](_local/bdrs/index.md)
-
-[View _local ADRs Index](_local/adrs/index.md)
+Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Keep `_local` canonical indexes in the workspace tree only; do not link them from this shared index. Readers and tools should still try to discover existing `_local` indexes in the current workspace by default.

package/README.md

@@ -17,9 +17,9 @@ npx agentme
 If you want the version pinned in a project, add `agentme` to a repository that already has a `package.json` and run it through the local dependency:
 
 ```sh
-pnpm add -D agentme
-pnpm exec agentme extract --output . --presets basic
-pnpm exec agentme check --output . --presets basic
+mise exec -- pnpm add -D agentme
+mise exec -- pnpm exec agentme extract --output . --presets basic
+mise exec -- pnpm exec agentme check --output . --presets basic
 ```
 
 ## Overview
@@ -80,19 +80,27 @@ This is useful when you want to:
 
 ## Development
 
-Use the root `Makefile` as the entry point for local verification:
+Install [Mise](https://mise.jdx.dev/getting-started.html), then sync the pinned toolchain:
 
 ```sh
-make build
-make lint
-make test
+mise install
 ```
 
+Use the root `Makefile` as the entry point for local verification inside the Mise-managed environment:
+
+```sh
+mise exec -- make build
+mise exec -- make lint
+mise exec -- make test
+```
+
+Running `make build`, `make lint`, or `make test` from an already activated Mise shell is equivalent.
+
 What these targets do:
 
-- `make build` installs dependencies and creates a local npm package in `dist/`.
-- `make lint` runs the repository lint target.
-- `make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.
+- `mise exec -- make build` installs dependencies and creates a local npm package in `dist/`.
+- `mise exec -- make lint` runs the repository lint target.
+- `mise exec -- make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.
 
 ## Repository Map
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentme",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "",
   "dependencies": {
     "filedist": "^0.26.0",
-    "xdrs-core": "^0.7.1"
+    "xdrs-core": "^0.14.5"
   },
   "bin": "bin/filedist.js",
   "files": [