aienvmp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial AI-first env map prototype.
+- Added scan, context, intent, record, compile, doctor, diff, and dash commands.
+- Added `AIENV.md`, agent file injection, append-only timeline, and lightweight dashboard output.

package/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Thanks for helping improve `aienvmp`.
+
+## Development
+
+```bash
+node --test
+node bin/aienvmp.js scan --dir sample-app
+node bin/aienvmp.js context --dir sample-app
+```
+
+## Design Principles
+
+- AI agents are the primary consumers.
+- Human dashboards are derived views.
+- Environment-changing actions should be visible in an append-only ledger.
+- Scanner failures should degrade gracefully unless the manifest would become misleading.

package/LICENSE

@@ -0,0 +1,134 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS"
+      BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+      or implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work, even if such Contributor has been advised of the possibility
+      of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility.

package/README.md

@@ -0,0 +1,298 @@
+# aienvmp
+
+[![CI](https://github.com/soovwv/aienvmp/actions/workflows/ci.yml/badge.svg)](https://github.com/soovwv/aienvmp/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](package.json)
+
+**aienvmp = AI Environment Map**
+
+`aienvmp` is an AI-first environment map and change ledger for shared AI coding workspaces.
+
+It helps multiple AI coding agents read the same runtime state, avoid installing or using conflicting software versions, declare environment-changing intent, record what changed, and keep humans informed through a lightweight dashboard.
+
+It is intentionally small: use it beside SBOM scanners, vulnerability scanners, version managers, and CI systems.
+
+## Why
+
+Shared development machines drift.
+
+One person upgrades Node. Another AI agent installs a global Python tool. A different agent assumes Docker is available. A third agent uses the wrong package manager because it did not see the project lockfile.
+
+After a few sessions, nobody is quite sure which runtime is safe to use.
+
+`aienvmp` is designed to prevent that kind of AI-driven version drift.
+
+It is also designed to stay out of the operator's way. By default, `aienvmp` reports warnings and review-required states instead of taking locks, blocking commands, or changing the machine.
+
+`aienvmp` turns that machine state into:
+
+- `AIENV.md`: an AI-readable environment protocol
+- `.aienvmp/manifest.json`: a lightweight runtime SBOM
+- `.aienvmp/timeline.jsonl`: an append-only environment change ledger
+- `.aienvmp/intents.jsonl`: planned and resolved environment-changing actions
+- `.aienvmp/dashboard.html`: a small human-readable dashboard
+
+## Core Idea
+
+Before an AI changes the environment, it should know the environment.
+
+Before an AI installs or uses a runtime, it should check the shared policy.
+
+The policy is advisory by default. It should guide AI agents and humans, not unexpectedly interrupt production or shared workspace operations.
+
+```bash
+aienvmp context
+aienvmp intent --actor agent:codex --action "install pnpm" --target pnpm
+# make the change
+aienvmp scan
+aienvmp compile
+aienvmp record --actor agent:codex --summary "installed pnpm" --target pnpm --evidence "pnpm --version"
+aienvmp resolve --actor human:you --id int_abc123
+```
+
+## Quickstart
+
+Install with npm:
+
+```bash
+npm install -g aienvmp
+```
+
+Or run without installing:
+
+```bash
+npx aienvmp init
+npx aienvmp scan
+npx aienvmp context
+npx aienvmp compile --agents all
+npx aienvmp dash
+```
+
+Run locally from this repository while developing:
+
+```bash
+node bin/aienvmp.js init
+node bin/aienvmp.js scan
+node bin/aienvmp.js context
+node bin/aienvmp.js compile --agents all
+node bin/aienvmp.js dash
+```
+
+Try the included sample app:
+
+```bash
+node bin/aienvmp.js scan --dir sample-app
+node bin/aienvmp.js context --dir sample-app
+node bin/aienvmp.js dash --dir sample-app
+```
+
+## AI Agent Workflow
+
+1. Read `AIENV.md` or run `aienvmp context`.
+2. Prefer project-local version files such as `.nvmrc`, `.python-version`, `mise.toml`, and `.tool-versions`.
+3. Do not install or switch to a different runtime version when it conflicts with `.aienvmp/policy.yml`.
+4. Ask the user before changing global runtimes, global packages, Docker settings, or package managers.
+5. Record planned environment changes with `aienvmp intent`.
+6. After changes, run `aienvmp scan && aienvmp compile`.
+7. Record what changed with `aienvmp record`.
+8. Resolve the intent with `aienvmp resolve`.
+
+Agent files can be injected automatically:
+
+```bash
+aienvmp compile --agents codex,claude,gemini
+```
+
+Generated agent targets:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+
+## What AI Agents See
+
+`aienvmp context` returns a compact preflight brief:
+
+```text
+# AI Preflight Context
+
+Status: clear
+Node: 24.14.1
+Python: 3.11.0
+Docker: available
+
+Must follow:
+- Ask the user before global runtime, package manager, Docker, or global package changes.
+- Prefer project-local version files and local environments.
+- Before planned env changes, run `aienvmp intent --actor <agent:id> --action <planned-change>`.
+- After env changes, run `aienvmp scan && aienvmp compile`.
+- Then run `aienvmp record --actor <agent:id> --summary <what-changed>`.
+```
+
+For tool integrations:
+
+```bash
+aienvmp context --json
+aienvmp doctor --json
+aienvmp doctor --ci
+```
+
+`doctor --ci` is the explicit strict path. Normal `doctor` output is advisory and exits successfully so it does not disrupt shared operations.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `init` | Create `.aienvmp/` |
+| `scan` | Collect runtime/tooling versions and write `.aienvmp/manifest.json` |
+| `context` | Print short AI preflight context |
+| `intent` | Record a planned environment-impacting action |
+| `resolve` | Mark an intent as resolved or cancelled |
+| `record` | Append an agent/human environment change to the ledger |
+| `compile` | Write `AIENV.md` and optionally inject agent files |
+| `diff` | Compare current and previous manifests |
+| `doctor` | Report environment warnings |
+| `dash` | Generate `.aienvmp/dashboard.html` |
+
+Intent IDs are short and prefix-matchable, so `aienvmp resolve --id int_mabc` works when it matches one open intent.
+
+## What It Scans Today
+
+- OS: platform, release, arch, hostname, shell
+- Runtimes: Node.js, Python, Go, Java, Rust
+- Package managers and version managers: npm, pnpm, yarn, uv, pip, pipx, mise, asdf, pyenv, nvm, fnm, volta
+- Containers: Docker and Docker Compose
+- Project hints: `.nvmrc`, `.python-version`, `mise.toml`, `.tool-versions`, lockfiles, `package.json`, `pyproject.toml`, `Dockerfile`
+- Agent integration files: Codex, Claude, Gemini, Cursor, Copilot targets
+
+## Version Drift Prevention
+
+The highest-priority use case is preventing multiple AI agents from installing or using different software versions in the same workspace.
+
+`aienvmp` checks project hints and policy against the currently detected environment.
+
+Example `.aienvmp/policy.yml`:
+
+```yaml
+node: 24
+python: 3.11
+packageManager: npm
+globalInstalls: ask-first
+runtimeChanges: ask-first
+```
+
+If an AI tries to use Node 22 when policy requires Node 24, `aienvmp doctor` and `aienvmp context` should surface that mismatch before work continues.
+
+Example warning:
+
+```text
+.aienvmp/policy.yml requires node 24, but detected 22.11.0.
+```
+
+Normal commands remain non-blocking. Use CI/strict mode only when you explicitly want a warning to fail automation.
+
+## Output Layout
+
+```text
+.aienvmp/
+  manifest.json
+  timeline.jsonl
+  intents.jsonl
+  dashboard.html
+AIENV.md
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+```
+
+## Dashboard
+
+The dashboard is a static HTML file. It is derived from the manifest, warnings, intents, and ledger.
+
+```bash
+aienvmp dash
+```
+
+Open:
+
+```text
+.aienvmp/dashboard.html
+```
+
+## GitHub Action
+
+Use `aienvmp` in CI without making it disruptive by default:
+
+```yaml
+- uses: soovwv/aienvmp@main
+  with:
+    directory: "."
+    agents: "codex,claude,gemini"
+    strict: "false"
+```
+
+Set `strict: "true"` only when you want policy warnings to fail automation.
+
+See [examples/github-action.yml](examples/github-action.yml).
+
+## How This Differs From SBOM Tools
+
+`aienvmp` is not trying to replace full SBOM or security scanners.
+
+Tools like Syft, Trivy, Dependency-Track, and osquery are excellent for component inventory, vulnerability scanning, and system instrumentation.
+
+`aienvmp` focuses on a narrower AI workflow:
+
+- What environment should this AI agent assume?
+- What must it avoid changing globally?
+- What changed recently?
+- Which agent planned or performed the change?
+- What should the next agent read before continuing?
+
+Think of it as an **AI coordination layer over a lightweight runtime SBOM**.
+
+## Why It Is Different
+
+- **AI-first**: the primary consumer is an AI coding agent, not only a human operator.
+- **Version drift prevention**: policy warnings are designed to stop agents from silently using different Node, Python, Docker, or package manager assumptions.
+- **Change intent before change**: agents can declare intent before touching shared environment state.
+- **Append-only ledger**: environment-impacting changes are recorded for the next agent.
+- **Non-blocking operations**: normal warnings do not lock or break the machine; strict mode is opt-in.
+- **Small surface area**: no daemon, no database, no hosted service required.
+
+## Project Links
+
+- [Roadmap](ROADMAP.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Status
+
+This is an early prototype.
+
+Good fit today:
+
+- shared development servers
+- AI coding workspaces
+- local projects using Codex, Claude, Gemini, Cursor, or Copilot
+- self-hosted runner experiments
+
+Planned next:
+
+- deeper policy enforcement
+- deeper nvm/fnm/volta/pyenv/mise/asdf scans
+- global npm, pipx, and uv tool inventory
+
+See [ROADMAP.md](ROADMAP.md) for the longer plan.
+
+## Development
+
+```bash
+node --test
+npm pack --dry-run
+npm run smoke
+```
+
+## License
+
+Apache-2.0

package/ROADMAP.md

@@ -0,0 +1,44 @@
+# Roadmap
+
+`aienvmp` focuses on AI coding workspace operations: helping multiple AI agents avoid runtime/version drift while keeping humans in control.
+
+## Near Term
+
+- Policy checks for Node, Python, and package manager drift
+- Intent lifecycle: open, resolve, cancel
+- JSON output for AI/tool integrations
+- Non-blocking by default, strict only with `--ci`
+- Dashboard improvements for policy and agent coordination
+
+## Next
+
+- Deeper runtime discovery:
+  - nvm, fnm, volta
+  - pyenv, uv, conda
+  - mise, asdf
+- Global tool inventory:
+  - `npm -g`
+  - `pipx list`
+  - `uv tool list`
+- Conflict detection:
+  - multiple open intents for the same target
+  - stale unresolved intents
+  - package manager policy vs lockfile mismatch
+- CI mode:
+  - stable exit codes
+  - GitHub Action example
+
+## Later
+
+- CycloneDX/SPDX export
+- Optional Syft/Trivy integration
+- Team dashboard mode
+- Signed/attested environment snapshots
+- Policy presets for common AI coding workspaces
+
+## Non-goals
+
+- Replacing full SBOM generators
+- Replacing vulnerability scanners
+- Taking hard locks on shared machines by default
+- Installing or modifying runtime versions automatically

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+`aienvmp` is designed to be non-invasive by default.
+
+It scans local environment metadata, writes local project files, and does not intentionally upload environment data to a remote service.
+
+## Reporting a Vulnerability
+
+Please report security issues through GitHub Security Advisories if available, or open a private contact channel with the maintainer.
+
+Do not include secrets, private environment dumps, access tokens, or production hostnames in public issues.
+
+## Operational Safety
+
+- Normal warnings are advisory and non-blocking.
+- `aienvmp doctor --ci` is the explicit strict mode for automation.
+- `aienvmp` should not install, upgrade, downgrade, or remove software by itself.
+- Generated files should be reviewed before committing in sensitive repositories.
+
+## Sensitive Data
+
+Current manifests may include local paths, hostnames, shell paths, and runtime versions. Treat generated `.aienvmp/` outputs as workspace metadata and decide whether they belong in your repository.

package/action.yml

@@ -0,0 +1,42 @@
+name: aienvmp
+description: AI-first environment map and policy check for coding workspaces
+author: soovwv
+
+inputs:
+  directory:
+    description: Workspace directory to scan
+    required: false
+    default: "."
+  agents:
+    description: Agent files to inject during compile
+    required: false
+    default: ""
+  strict:
+    description: Fail when doctor reports warnings
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Scan environment
+      shell: bash
+      run: node "$GITHUB_ACTION_PATH/bin/aienvmp.js" scan --dir "${{ inputs.directory }}"
+
+    - name: Compile agent context
+      shell: bash
+      run: |
+        if [ -n "${{ inputs.agents }}" ]; then
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" compile --dir "${{ inputs.directory }}" --agents "${{ inputs.agents }}"
+        else
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" compile --dir "${{ inputs.directory }}"
+        fi
+
+    - name: Doctor
+      shell: bash
+      run: |
+        if [ "${{ inputs.strict }}" = "true" ]; then
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" doctor --dir "${{ inputs.directory }}" --ci
+        else
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" doctor --dir "${{ inputs.directory }}"
+        fi

package/bin/aienvmp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`aienvmp: ${error.message}`);
+  process.exit(1);
+});

package/examples/github-action.yml

@@ -0,0 +1,17 @@
+name: Environment Map
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  aienvmp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: soovwv/aienvmp@main
+        with:
+          directory: "."
+          agents: "codex,claude,gemini"
+          strict: "false"

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "aienvmp",
+  "version": "0.1.0",
+  "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
+  "type": "module",
+  "bin": {
+    "aienvmp": "bin/aienvmp.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soovwv/aienvmp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/soovwv/aienvmp/issues"
+  },
+  "homepage": "https://github.com/soovwv/aienvmp#readme",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "ROADMAP.md",
+    "action.yml",
+    "examples"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:dry": "npm pack --dry-run",
+    "smoke": "node bin/aienvmp.js --version && node bin/aienvmp.js --help"
+  },
+  "keywords": [
+    "ai",
+    "environment",
+    "env-map",
+    "sbom",
+    "runtime",
+    "agent",
+    "agentic",
+    "devops",
+    "codex",
+    "claude",
+    "gemini"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  }
+}