aienvmp 0.1.48 → 0.1.50

package/BUGFIXES.md

@@ -76,6 +76,24 @@ Short record of bugs, fixes, and follow-up checks.
 - Fix: `aienvmp sbom --format cyclonedx-lite` and `.aienvmp/sbom.cdx.json` now export project-manifest packages in a CycloneDX-compatible shape with explicit limitations.
 - Verification: tests cover component mapping, vulnerability hints, sync output, schema metadata, and dashboard links.
 
+### CI example did not surface SBOM artifacts clearly
+
+- Issue: sync could generate SBOM artifacts, but the GitHub Action and example upload list did not make them explicit.
+- Fix: the Action now has `write-sbom` and the example uploads both native and CycloneDX-lite SBOM artifacts.
+- Verification: Action tests cover input metadata, SBOM write commands, and example artifact paths.
+
+### CI and AI review still needed a short handoff view
+
+- Issue: `status.json` was AI-friendly, but GitHub Actions and quick human review still required opening JSON artifacts or the dashboard.
+- Fix: `aienvmp summary` now writes `.aienvmp/summary.md`, `sync` creates it by default, and the GitHub Action appends it to `GITHUB_STEP_SUMMARY`.
+- Verification: tests cover summary rendering, sync artifact creation, schema metadata, Action wiring, and example upload paths.
+
+### Windows-created JSON files could be missed
+
+- Issue: UTF-8 BOM JSON files created by some Windows tools could fail JSON parsing and make dependency snapshots look empty.
+- Fix: `readJson` now strips a leading UTF-8 BOM before parsing.
+- Verification: regression tests cover BOM JSON parsing and Windows smoke testing confirmed dependency counts in `summary.md`.
+
 ## Template
 
 ### Title

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.50
+
+- Added `aienvmp summary` for a compact Markdown AI/CI handoff view.
+- Added `.aienvmp/summary.md` writing through the default `sync` flow.
+- Added `summary` to preflight artifacts and the stable output contract.
+- Added a GitHub Action `write-summary` input.
+- Appended `.aienvmp/summary.md` to GitHub Step Summary when the Action runs in GitHub Actions.
+- Updated the GitHub Action example and README to include the summary artifact.
+- Fixed UTF-8 BOM JSON parsing so Windows-created `package.json` files are scanned correctly.
+- Added regression tests for summary rendering, sync output, schema metadata, Action Step Summary wiring, and BOM JSON parsing.
+
+## 0.1.49
+
+- Added a `write-sbom` GitHub Action input for explicit SBOM artifact generation.
+- Added Action steps for writing `.aienvmp/sbom.json` and `.aienvmp/sbom.cdx.json`.
+- Updated the GitHub Action example to enable SBOM writing.
+- Added native light SBOM artifact upload paths to the example workflow.
+- Added CycloneDX-lite artifact upload paths to the example workflow.
+- Updated README CI usage to mention SBOM artifacts.
+- Added regression coverage for Action SBOM inputs, commands, and example upload paths.
+
 ## 0.1.48
 
 - Added `aienvmp sbom --format cyclonedx-lite` for a lightweight CycloneDX-compatible export.

package/README.md

@@ -34,6 +34,7 @@ Warnings are advisory by default. Use `doctor --strict <scope>` only when you wa
 ```text
 AIENV.md                 # Markdown env map for AI agents
 .aienvmp/status.json     # first AI read: clear/review, next command, nextAgent hint
+.aienvmp/summary.md      # compact AI/CI summary
 .aienvmp/manifest.json   # runtime map + light SBOM
 .aienvmp/sbom.json       # standalone AI-readable light SBOM
 .aienvmp/sbom.cdx.json   # CycloneDX-lite export from project manifests
@@ -47,6 +48,7 @@ AIENV.md                 # Markdown env map for AI agents
 
 - `status`, `context`, `plan`, and `handoff` share one preflight contract.
 - `schema --json` prints the stable AI-readable output contract without scanning.
+- `summary.md` is the short CI/AI handoff view.
 - `status.json.nextAgent` tells the next AI what to read and whether to review first.
 - `dependencyReadSet` lists manifests and lockfiles before package or security changes.
 - `sbomRisk` gives AI a compact light-SBOM risk level, signals, and next command.
@@ -71,8 +73,9 @@ npx aienvmp snippet gemini
 ## Commands
 
 ```bash
-aienvmp sync                    # update env map, status, ledger, dashboard
+aienvmp sync                    # update env map, status, summary, SBOM, dashboard
 aienvmp status --write          # refresh compact AI status
+aienvmp summary --write         # refresh compact Markdown summary
 aienvmp context --json          # AI decision contract
 aienvmp sbom --json             # standalone light SBOM
 aienvmp sbom --format cyclonedx-lite --json
@@ -87,13 +90,15 @@ aienvmp doctor --strict security|policy|coordination|all
 
 ## CI
 
-The GitHub Action writes status, schema, doctor, plan, and dashboard artifacts. `strict: "off"` reports warnings without failing the job.
+The GitHub Action writes status, summary, schema, doctor, plan, SBOM, and dashboard artifacts. `strict: "off"` reports warnings without failing the job.
 
 ```yaml
 - uses: soovwv/aienvmp@main
   with:
     write-status: "true"
     write-plan: "true"
+    write-sbom: "true"
+    write-summary: "true"
     strict: "off"
 ```
 

package/action.yml

@@ -27,6 +27,14 @@ inputs:
     description: Write doctor JSON with advisory/strict exit behavior
     required: false
     default: "true"
+  write-sbom:
+    description: Write standalone light SBOM and CycloneDX-lite artifacts
+    required: false
+    default: "true"
+  write-summary:
+    description: Write compact Markdown summary and append it to GitHub Step Summary
+    required: false
+    default: "true"
 
 runs:
   using: composite
@@ -65,6 +73,24 @@ runs:
           node "$GITHUB_ACTION_PATH/bin/aienvmp.js" doctor --dir "${{ inputs.directory }}" --json > "${{ inputs.directory }}/.aienvmp/doctor.json"
         fi
 
+    - name: Write SBOM artifacts
+      shell: bash
+      run: |
+        if [ "${{ inputs.write-sbom }}" = "true" ]; then
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" sbom --dir "${{ inputs.directory }}" --write --quiet
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" sbom --dir "${{ inputs.directory }}" --format cyclonedx-lite --write --quiet
+        fi
+
+    - name: Write AI summary
+      shell: bash
+      run: |
+        if [ "${{ inputs.write-summary }}" = "true" ]; then
+          node "$GITHUB_ACTION_PATH/bin/aienvmp.js" summary --dir "${{ inputs.directory }}" --write --quiet
+          if [ -n "$GITHUB_STEP_SUMMARY" ]; then
+            cat "${{ inputs.directory }}/.aienvmp/summary.md" >> "$GITHUB_STEP_SUMMARY"
+          fi
+        fi
+
     - name: Doctor
       shell: bash
       run: |

package/examples/github-action.yml

@@ -16,6 +16,8 @@ jobs:
           write-plan: "true"
           write-schema: "true"
           write-doctor-json: "true"
+          write-sbom: "true"
+          write-summary: "true"
           strict: "off" # security, policy, coordination, all, or off
 
       - uses: actions/upload-artifact@v4
@@ -26,6 +28,9 @@ jobs:
             AIENV.md
             .aienvmp/manifest.json
             .aienvmp/status.json
+            .aienvmp/summary.md
+            .aienvmp/sbom.json
+            .aienvmp/sbom.cdx.json
             .aienvmp/schema.json
             .aienvmp/doctor.json
             .aienvmp/plan.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -16,6 +16,7 @@ import { statusWorkspace } from "./commands/status.js";
 import { schemaWorkspace } from "./commands/schema.js";
 import { checkpointWorkspace } from "./commands/checkpoint.js";
 import { sbomWorkspace } from "./commands/sbom.js";
+import { summaryWorkspace } from "./commands/summary.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -36,7 +37,8 @@ const commands = new Map([
   ["status", statusWorkspace],
   ["schema", schemaWorkspace],
   ["checkpoint", checkpointWorkspace],
-  ["sbom", sbomWorkspace]
+  ["sbom", sbomWorkspace],
+  ["summary", summaryWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -115,16 +117,18 @@ Usage:
   aienvmp checkpoint [--dir .] --actor agent:id --summary "what changed" [--target dependency] [--json]
   aienvmp plan [--dir .] [--json] [--write]
   aienvmp sbom [--dir .] [--json] [--write]
+  aienvmp summary [--dir .] [--write]
   aienvmp schema [--json]
 
 Common:
-  aienvmp sync      update AIENV.md, manifest, status, ledger, intents, and dashboard
+  aienvmp sync      update AIENV.md, manifest, status, summary, SBOM, ledger, intents, and dashboard
   aienvmp status    print one simple environment decision; --write saves .aienvmp/status.json
   aienvmp context   print the AI preflight brief
   aienvmp handoff   print the next-agent handoff summary
   aienvmp checkpoint record, sync, status, and handoff after an env change
   aienvmp plan      print a read-only AI environment action plan
   aienvmp sbom      print/write standalone light SBOM artifact
+  aienvmp summary   print/write a compact Markdown summary for AI and CI
   aienvmp schema    print the stable AI-readable output contract
   aienvmp snippet   print an AGENTS.md pointer snippet
   aienvmp dash      regenerate/open the lightweight dashboard
@@ -141,6 +145,7 @@ Advanced:
   aienvmp diff [--dir .]
   aienvmp doctor [--dir .] [--json] [--ci] [--strict security|policy|coordination|all]
   aienvmp sbom [--dir .] [--json] [--write]
+  aienvmp summary [--dir .] [--write]
   aienvmp dash [--dir .] [--open]
 `);
 }

package/src/commands/summary.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJson } from "../fsutil.js";
+import { manifestPath, statusJsonPath, summaryMdPath, workspaceDir } from "../paths.js";
+import { statusWorkspace } from "./status.js";
+
+export async function summaryWorkspace(args) {
+  const dir = workspaceDir(args);
+  let status = await readJson(statusJsonPath(dir));
+  if (!status) {
+    status = await statusWorkspace({ ...args, dir, json: false, write: true, quiet: true });
+  }
+  const manifest = await readJson(manifestPath(dir), {});
+  const markdown = renderSummary(status, manifest);
+  const artifact = args.write ? await writeSummaryArtifact(dir, markdown) : "";
+  const output = { artifact, summary: markdown, state: status.state || "unknown", sbomRisk: status.sbomRisk || {}, nextCommand: status.nextCommand || "" };
+
+  if (args.json) {
+    console.log(JSON.stringify(output, null, 2));
+  } else if (!args.quiet) {
+    console.log(markdown.trimEnd());
+    if (artifact) console.log(`\nsummary: ${artifact}`);
+  }
+
+  return output;
+}
+
+export async function writeSummaryArtifact(dir, markdown) {
+  const out = summaryMdPath(dir);
+  await fs.mkdir(path.dirname(out), { recursive: true });
+  await fs.writeFile(out, `${markdown.trimEnd()}\n`, "utf8");
+  return out;
+}
+
+export function renderSummary(status = {}, manifest = {}) {
+  const counts = status.counts || {};
+  const sbomRisk = status.sbomRisk || manifest.lightSbom?.riskSummary || {};
+  const coordination = status.coordination || {};
+  const activity = status.agentActivity || {};
+  const workspace = manifest.workspace?.root || manifest.workspace?.name || ".";
+  const next = status.nextCommand || status.decision?.nextCommand || "aienvmp status";
+  const readFirst = status.nextAgent?.readFirst || ".aienvmp/status.json";
+  const detail = status.quickstart?.detailCommand || "aienvmp context --json";
+  const strict = status.enforcement?.recommendedCommand || "aienvmp doctor --strict all";
+  const riskLevel = sbomRisk.level || "unknown";
+  const riskScore = valueOrZero(sbomRisk.score);
+  const scanner = sbomRisk.scanner || manifest.lightSbom?.source?.scanner || "not run";
+  const riskSignals = toList(sbomRisk.signals).slice(0, 3);
+  const conflictTargets = toList(coordination.conflictTargets);
+  const multiActorTargets = toList(activity.multiActorTargets);
+
+  return [
+    "# aienvmp summary",
+    "",
+    `- state: ${status.state || "unknown"}`,
+    `- workspace: ${workspace}`,
+    `- warnings: ${valueOrZero(counts.warnings)} / open intents: ${valueOrZero(counts.openIntents)}`,
+    `- runtimes: ${valueOrZero(counts.runtimes)} / dependencies: ${valueOrZero(counts.dependencies)} / vulnerabilities: ${valueOrZero(counts.vulnerabilities)}`,
+    `- light SBOM risk: ${riskLevel} (${riskScore}) / scanner: ${scanner}`,
+    `- next: ${next}`,
+    `- AI read first: ${readFirst}, then ${detail}`,
+    `- mode: advisory by default; strict is opt-in with ${strict}`,
+    "",
+    "## AI handoff",
+    "",
+    `- environment changes: ${status.agentUse?.environmentChanges || "intent-and-review-first"}`,
+    `- coordination: ${coordination.next || "No open environment intents."}`,
+    `- recent agent activity: ${activity.next || "No environment records need coordination."}`,
+    `- conflict targets: ${conflictTargets.length ? conflictTargets.join(", ") : "none"}`,
+    `- multi-actor targets: ${multiActorTargets.length ? multiActorTargets.join(", ") : "none"}`,
+    "",
+    "## SBOM",
+    "",
+    `- source: ${manifest.lightSbom?.source?.dependencies || "project manifests"}`,
+    `- confidence: transitive ${manifest.lightSbom?.confidence?.transitiveDependencies || "not-resolved"}`,
+    `- signals: ${riskSignals.length ? riskSignals.join("; ") : "none"}`,
+    `- verify: ${sbomRisk.next || "Use a dedicated scanner for security decisions."}`,
+    "",
+    "## Artifacts",
+    "",
+    "- AIENV.md",
+    "- .aienvmp/status.json",
+    "- .aienvmp/manifest.json",
+    "- .aienvmp/sbom.json",
+    "- .aienvmp/sbom.cdx.json",
+    "- .aienvmp/dashboard.html"
+  ].join("\n");
+}
+
+function valueOrZero(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function toList(value) {
+  return Array.isArray(value) ? value.filter(Boolean) : [];
+}

package/src/commands/sync.js

@@ -4,6 +4,7 @@ import { compileWorkspace } from "./compile.js";
 import { dashWorkspace } from "./dash.js";
 import { statusWorkspace } from "./status.js";
 import { sbomWorkspace } from "./sbom.js";
+import { summaryWorkspace } from "./summary.js";
 
 export async function syncWorkspace(args) {
   const quiet = args.quiet || args.json;
@@ -16,6 +17,7 @@ export async function syncWorkspace(args) {
   const status = await statusWorkspace({ ...next, json: false, write: true, quiet: true });
   const sbom = await sbomWorkspace({ ...next, json: false, write: true, quiet: true });
   const cyclonedx = await sbomWorkspace({ ...next, json: false, write: true, quiet: true, format: "cyclonedx-lite" });
+  const summary = await summaryWorkspace({ ...next, json: false, write: true, quiet: true });
 
   const result = {
     status: "ok",
@@ -26,6 +28,7 @@ export async function syncWorkspace(args) {
       status: status.artifact,
       sbom: sbom.artifact,
       cyclonedx: cyclonedx.artifact,
+      summary: summary.artifact,
       dashboard: dashboard.dashboard
     },
     changes: scanned.changes,
@@ -35,7 +38,7 @@ export async function syncWorkspace(args) {
   if (args.json) {
     console.log(JSON.stringify(result, null, 2));
   } else if (!quiet) {
-    console.log("sync complete: AIENV.md, manifest, status, ledger, intents, and dashboard are up to date");
+    console.log("sync complete: AIENV.md, manifest, status, SBOM, summary, ledger, intents, and dashboard are up to date");
   }
 
   return result;

package/src/contract.js

@@ -20,6 +20,12 @@ export function schemaContract() {
         command: "aienvmp status --json",
         contract: preflightContract()
       },
+      summary: {
+        file: ".aienvmp/summary.md",
+        command: "aienvmp summary --write",
+        format: "markdown",
+        purpose: "Compact AI and CI step summary for quick review."
+      },
       context: {
         command: "aienvmp context --json",
         rootFields: ["status", "preflight", "coordination", "decision", "recommendedActions", "workspace", "dependencySnapshot", "lightSbom", "warnings"]

package/src/fsutil.js

@@ -12,12 +12,16 @@ export async function exists(file) {
 
 export async function readJson(file, fallback = null) {
   try {
-    return JSON.parse(await fs.readFile(file, "utf8"));
+    return JSON.parse(stripBom(await fs.readFile(file, "utf8")));
   } catch {
     return fallback;
   }
 }
 
+export function stripBom(value) {
+  return String(value).replace(/^\uFEFF/, "");
+}
+
 export async function writeJson(file, data) {
   await fs.mkdir(path.dirname(file), { recursive: true });
   await fs.writeFile(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");

package/src/paths.js

@@ -48,6 +48,10 @@ export function planMdPath(dir) {
   return path.join(stateDir(dir), "plan.md");
 }
 
+export function summaryMdPath(dir) {
+  return path.join(stateDir(dir), "summary.md");
+}
+
 export function aiEnvPath(dir) {
   return path.join(dir, "AIENV.md");
 }

package/src/preflight.js

@@ -351,6 +351,7 @@ function agentQuickstart(reviewRequired) {
 export function preflightArtifacts() {
   return {
     status: ".aienvmp/status.json",
+    summary: ".aienvmp/summary.md",
     envMap: "AIENV.md",
     manifest: ".aienvmp/manifest.json",
     sbom: ".aienvmp/sbom.json",