@technomoron/agent-run 0.99.1

package/CHANGES

@@ -0,0 +1,23 @@
+CHANGES
+=======
+
+Unreleased (2026-04-08)
+-----------------------
+
+Version 0.99.1 (2026-04-08)
+---------------------------
+* Expand `{{AGENT_DIR}}`, `{{AGENTS_PATH}}`, and related placeholders from `AGENTS-MODS.md` when generating `AGENTS.md`.
+* Make `pnpm release` create and push the release tag so GitHub Actions owns npm publishing.
+
+Version 0.99.0 (2026-03-19)
+---------------------------
+* Normalize package metadata and license copyright text to `Technomoron.com`.
+
+Version 0.99.0 (2026-03-19)
+---------------------------
+* Replace the shell wrapper with the Node and TypeScript-based `agent-run` utility.
+* Add `check` and `init` commands, source-root support, and external agent-config mapping.
+* Add `.agent-run-ignore` and `.agent-run.env` support for explicit ignore and profile overrides.
+* Add a full README describing the tool, workflow, and mapping model.
+* Add `edit` support for opening mapped `AGENTS-MODS.md`, including VS Code terminal handling and editor fallbacks.
+* Move bundled project agent configs out of this repo into the external `agent-configs` tree.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn Erik Jacobsen / Technomoron.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# agent-run
+
+Small wrapper for AI coding CLIs like Codex and Claude.
+
+It keeps agent files out of normal repos and stores them in a separate
+`agent-configs` tree. That tree can live anywhere; it does not need to sit
+inside the source tree.
+
+## Model
+
+There are three things:
+
+- the source tree
+- the `agent-configs` tree
+- this `agent-run` wrapper
+
+Example:
+
+```text
+~/source/
+  org/
+    my-api/
+
+~/source/agent-configs/
+  org/
+    my-api/
+      AGENTS-MODS.md
+      AGENTS.md
+      CLAUDE.md
+```
+
+If your source repo is `~/source/org/my-api`, `agent-run` can map it to:
+
+```text
+~/source/agent-configs/org/my-api
+```
+
+The source repo stays clean. The agent files live in the matching path under
+`agent-configs`.
+
+## File Roles
+
+- `AGENTS-MODS.md`: source file you edit
+- `AGENTS.md`: generated from `AGENTS-MODS.md`
+- `CLAUDE.md`: pointer file containing only `@AGENTS.md`
+
+Edit `AGENTS-MODS.md`. `agent-run` keeps `AGENTS.md` and `CLAUDE.md` in sync.
+
+## Profile Resolution
+
+The mapped path is:
+
+```text
+<config-root>/<profile>
+```
+
+`profile` is resolved in this order:
+
+1. `AGENT_RUN_PROFILE` in `.agent-run.env`
+2. `package.json.name`
+
+Examples:
+
+- `AGENT_RUN_PROFILE=org/my-api` -> `org/my-api`
+- `AGENT_RUN_PROFILE=unrelated/hello` -> `unrelated/hello`
+- `package.json.name = "@org/my-api"` -> `org/my-api`
+- `package.json.name = "my-api"` -> `my-api`
+
+`AGENT_RUN_PROFILE` is relative to the config root. It is not a filesystem
+path, so values like `/tmp/foo`, `C:/tmp/foo`, or `../foo` are rejected.
+
+If neither exists, `agent-run` fails instead of guessing.
+
+## Overrides
+
+Local override for a repo:
+
+```dotenv
+# .agent-run.env
+AGENT_RUN_PROFILE=org/my-api
+```
+
+Config root:
+
+- default: `~/source/agent-configs` on Unix
+- default: `~/Documents/source/agent-configs` on Windows
+- override with `--config-root /path/to/agent-configs`
+- override with `AGENT_CONFIG_ROOT=/path/to/agent-configs`
+- or set `AGENT_CONFIG_ROOT=/path/to/agent-configs` in `.agent-run.env`
+
+## Commands
+
+Global flag:
+
+- `-v`, `--verbose`: print path resolution, file creation, include expansion,
+  generated file writes, and spawned commands
+
+Initialize mapped files for the current repo:
+
+```sh
+agent-run init
+```
+
+This creates the mapped profile directory if needed and ensures these files
+exist:
+
+- `AGENTS-MODS.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+
+Edit the source file for the current repo:
+
+```sh
+agent-run edit
+```
+
+This creates missing files, syncs generated files, then opens
+`AGENTS-MODS.md` in your editor.
+
+Regenerate the generated files for the current repo:
+
+```sh
+agent-run update
+```
+
+This reads `AGENTS-MODS.md` from the mapped profile directory and rewrites:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+
+Supported placeholders in `AGENTS-MODS.md` are expanded when `AGENTS.md` is generated:
+
+- `{{AGENT_DIR}}`: mapped config directory for the current repo
+- `{{AGENTS_MODS_PATH}}`: source `AGENTS-MODS.md` path
+- `{{AGENTS_PATH}}`: generated `AGENTS.md` path
+- `{{CLAUDE_PATH}}`: generated `CLAUDE.md` path
+- `{{CONFIG_ROOT}}`: resolved config root
+- `{{PROFILE}}`: mapped profile such as `technomoron/apicore`
+
+Check the current repo:
+
+```sh
+agent-run check
+```
+
+This reports:
+
+- local AI files accidentally present in the source repo
+- missing mapped files
+- stale `AGENTS.md`
+- invalid `CLAUDE.md`
+- profile resolution problems
+
+Check every repo under a source tree:
+
+```sh
+agent-run check --all ~/source
+```
+
+## Install
+
+```sh
+npm install -g @technomoron/agent-run
+```
+
+## Release
+
+Releases publish from GitHub Actions, not from a local `npm publish`.
+
+After updating `package.json` and `CHANGES`, run:
+
+```sh
+pnpm release
+```
+
+This validates the repo, creates the annotated tag matching the package version,
+and pushes that tag to `origin`. The tag push triggers the release workflow,
+which verifies, packs, publishes to npm, and creates the GitHub release.