aienvmp 0.1.2 → 0.1.4

package/BUGFIXES.md

@@ -0,0 +1,38 @@
+# Bugfix Log
+
+Short record of bugs, fixes, and follow-up checks.
+
+## 2026-07-08
+
+### CLI version was hardcoded
+
+- Issue: `npm run smoke` printed `0.1.0` after the package version changed.
+- Fix: CLI now reads the version from `package.json`.
+- Verification: `npm run smoke` prints the package version.
+
+### AGENTS.md default generation conflicted with product focus
+
+- Issue: default agent instruction file generation made `aienvmp` look like an AGENTS.md generator.
+- Fix: `sync` now focuses on `AIENV.md`, manifest, intent log, timeline, and dashboard. Agent instruction integration is explicit through `aienvmp snippet`.
+- Verification: `node --test` confirms `sync` does not create `AGENTS.md` by default and `snippet --write` only updates the marker block.
+
+### npm publish metadata appeared stale
+
+- Issue: npm publish returned success for `0.1.2`, but `npm view aienvmp version` briefly returned `0.1.1`.
+- Fix: verified with `npm view aienvmp versions --json` and `npm dist-tag ls aienvmp`; registry later reported `0.1.2`.
+- Verification: `npm view aienvmp version` returns `0.1.2`.
+
+### macOS SSH PATH did not expose Node/npm
+
+- Issue: remote macOS non-interactive SSH command did not find `node` or `npm`.
+- Fix: test command used `/bin/zsh -lc` to load login shell PATH.
+- Verification: remote test detected Node `v25.3.0`, npm `11.11.0`, and completed `aienvmp sync`.
+
+## Template
+
+### Title
+
+- Issue:
+- Fix:
+- Verification:
+- Follow-up:

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.4
+
+- Added `aienvmp handoff` for next-agent environment handoff summaries.
+- Added an AI Handoff card to the dashboard.
+- Added handoff test coverage.
+
+## 0.1.3
+
+- Strengthened the dashboard audit summary with AI decision, open intents, warnings, and recent changes.
+- Added dashboard render coverage for the audit summary surface.
+
 ## 0.1.2
 
 - Added `aienvmp sync` as the simple one-step command for init, scan, `AIENV.md`, manifest, ledger, and dashboard generation.
@@ -8,6 +19,7 @@
 - Added machine-readable sync/context improvements for AI and CI integrations.
 - Simplified README for faster first-time understanding.
 - Kept AGENTS.md, CLAUDE.md, and GEMINI.md integration explicit through `aienvmp snippet`.
+- Added troubleshooting and bugfix logs for operational issue tracking.
 
 ## 0.1.1
 

package/README.md

@@ -48,6 +48,7 @@ npx aienvmp snippet agents
 aienvmp sync              # update env map, light SBOM, ledger, dashboard
 aienvmp context           # AI preflight brief
 aienvmp context --json    # machine-readable AI decision context
+aienvmp handoff           # next-agent handoff summary
 aienvmp intent            # record a planned env change
 aienvmp record            # record what changed
 aienvmp doctor --ci       # strict CI check
@@ -70,6 +71,6 @@ npm pack --dry-run
 
 ## Links
 
-[Roadmap](ROADMAP.md) / [Security](SECURITY.md) / [Contributing](CONTRIBUTING.md)
+[Roadmap](ROADMAP.md) / [Security](SECURITY.md) / [Troubleshooting](TROUBLESHOOTING.md) / [Bugfix Log](BUGFIXES.md) / [Contributing](CONTRIBUTING.md)
 
 Apache-2.0

package/TROUBLESHOOTING.md

@@ -0,0 +1,103 @@
+# Troubleshooting
+
+Known operational issues and quick fixes for `aienvmp`.
+
+## npm publish succeeds but `npm view` still shows the old version
+
+Symptom:
+
+```text
+npm publish
++ aienvmp@0.1.2
+npm view aienvmp version
+0.1.1
+```
+
+Cause:
+
+- npm registry metadata can lag briefly after publish.
+
+Check:
+
+```bash
+npm view aienvmp versions --json
+npm dist-tag ls aienvmp
+```
+
+Fix:
+
+- Wait briefly and re-check `npm view aienvmp version`.
+
+## Windows `npm exec --package ... -- aienvmp --help` cannot find the command
+
+Symptom:
+
+```text
+'aienvmp' is not recognized as an internal or external command
+```
+
+Notes:
+
+- The package bin metadata can still be valid.
+- A direct temporary install creates the expected `.bin/aienvmp.cmd` shim.
+
+Check:
+
+```bash
+npm view aienvmp bin --json
+npm install aienvmp@latest --prefix ./tmp-aienvmp-check
+```
+
+Workaround:
+
+```bash
+npx aienvmp@latest --version
+```
+
+or install first:
+
+```bash
+npm install -g aienvmp
+aienvmp --version
+```
+
+## macOS SSH session cannot find `node` or `npm`
+
+Symptom:
+
+```text
+command -v node
+# empty in non-interactive SSH command
+```
+
+Cause:
+
+- Node may be configured only in the login shell environment.
+
+Fix:
+
+```bash
+/bin/zsh -lc 'node --version && npm --version'
+```
+
+For automation, make sure the shell PATH includes the Node/npm location.
+
+## Missing manifest
+
+Symptom:
+
+```text
+aienvmp: missing manifest; run `aienvmp sync` first
+```
+
+Fix:
+
+```bash
+npx aienvmp sync
+```
+
+Then retry:
+
+```bash
+npx aienvmp context
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {
@@ -20,8 +20,10 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "BUGFIXES.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
+    "TROUBLESHOOTING.md",
     "ROADMAP.md",
     "action.yml",
     "examples",

package/src/cli.js

@@ -10,6 +10,7 @@ import { intentWorkspace } from "./commands/intent.js";
 import { resolveWorkspace } from "./commands/resolve.js";
 import { syncWorkspace } from "./commands/sync.js";
 import { snippetWorkspace } from "./commands/snippet.js";
+import { handoffWorkspace } from "./commands/handoff.js";
 import { readFileSync } from "node:fs";
 
 const commands = new Map([
@@ -24,7 +25,8 @@ const commands = new Map([
   ["intent", intentWorkspace],
   ["resolve", resolveWorkspace],
   ["sync", syncWorkspace],
-  ["snippet", snippetWorkspace]
+  ["snippet", snippetWorkspace],
+  ["handoff", handoffWorkspace]
 ]);
 
 const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -74,10 +76,12 @@ function printUsage() {
 Usage:
   aienvmp sync [--dir .] [--json] [--quiet]
   aienvmp context [--dir .] [--json]
+  aienvmp handoff [--dir .] [--json]
 
 Common:
   aienvmp sync      update AIENV.md, manifest, ledger, intents, and dashboard
   aienvmp context   print the AI preflight brief
+  aienvmp handoff   print the next-agent handoff summary
   aienvmp snippet   print an AGENTS.md pointer snippet
   aienvmp dash      regenerate/open the lightweight dashboard
 

package/src/commands/handoff.js

@@ -0,0 +1,55 @@
+import { diagnose } from "../doctor.js";
+import { readJson } from "../fsutil.js";
+import { loadPolicy, policyWarnings } from "../policy.js";
+import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
+import { renderHandoff } from "../render.js";
+import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+
+export async function handoffWorkspace(args) {
+  const dir = workspaceDir(args);
+  const manifest = await readJson(manifestPath(dir));
+  if (!manifest) throw new Error("missing manifest; run `aienvmp sync` first");
+  const timeline = await readTimeline(timelinePath(dir));
+  const intents = openIntents(await readJsonl(intentsPath(dir)));
+  const policy = await loadPolicy(dir);
+  const warnings = [...diagnose(manifest), ...policyWarnings(manifest, policy)];
+  const handoff = buildHandoff(manifest, timeline, warnings, intents, policy);
+
+  if (args.json) {
+    console.log(JSON.stringify(handoff, null, 2));
+  } else {
+    console.log(renderHandoff(handoff));
+  }
+  return handoff;
+}
+
+export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
+  const reviewRequired = warnings.length > 0 || intents.length > 0;
+  return {
+    status: reviewRequired ? "review-required" : "clear",
+    workspace: manifest.workspace,
+    safeRuntime: {
+      node: manifest.runtimes?.node || "not detected",
+      python: manifest.runtimes?.python || manifest.runtimes?.python3 || "not detected",
+      docker: manifest.containers?.docker ? "available" : "not detected"
+    },
+    policy: {
+      node: policy.node || "not set",
+      python: policy.python || "not set",
+      packageManager: policy.packageManager || "not set",
+      runtimeChanges: policy.runtimeChanges || "ask-first",
+      globalInstalls: policy.globalInstalls || "ask-first"
+    },
+    openIntents: intents.slice(-5).reverse(),
+    warnings,
+    recentChanges: timeline.slice(-5).reverse(),
+    mustNotDo: [
+      "do not change global runtimes without user approval",
+      "do not install or remove global package managers without user approval",
+      "do not change Docker daemon/context assumptions without user approval"
+    ],
+    recommendedNext: reviewRequired
+      ? "review warnings and open intents before environment changes"
+      : "continue with project-local work; record intent before environment changes"
+  };
+}

package/src/render.js

@@ -111,6 +111,36 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
   ].join("\n");
 }
 
+export function renderHandoff(handoff) {
+  const lines = [
+    "# AI Handoff",
+    "",
+    `Status: ${handoff.status}`,
+    `Workspace: ${handoff.workspace?.path || "unknown"}`,
+    "",
+    "Safe runtime:",
+    `- Node: ${handoff.safeRuntime.node}`,
+    `- Python: ${handoff.safeRuntime.python}`,
+    `- Docker: ${handoff.safeRuntime.docker}`,
+    "",
+    "Open intents:",
+    ...(handoff.openIntents.length ? handoff.openIntents.map((i) => `- ${i.actor}: ${i.action}${i.target ? ` (${i.target})` : ""}`) : ["- none"]),
+    "",
+    "Warnings:",
+    ...(handoff.warnings.length ? handoff.warnings.map((w) => `- ${w.message}`) : ["- none"]),
+    "",
+    "Recent changes:",
+    ...(handoff.recentChanges.length ? handoff.recentChanges.map((t) => `- ${formatTimeline(t)}`) : ["- none"]),
+    "",
+    "Must not do:",
+    ...handoff.mustNotDo.map((item) => `- ${item}`),
+    "",
+    `Recommended next: ${handoff.recommendedNext}`,
+    ""
+  ];
+  return lines.join("\n");
+}
+
 export function renderDashboard(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const data = JSON.stringify({ manifest, timeline, warnings, intents, policy });
   return `<!doctype html>
@@ -131,6 +161,13 @@ h1,h2,h3,p{margin:0}h1{font-size:clamp(28px,4vw,46px);line-height:1.02;margin-to
 .sub{color:var(--muted);margin-top:12px;max-width:680px;line-height:1.55}
 .stamp{min-width:220px;border:1px solid var(--line2);background:#091310;border-radius:8px;padding:14px}
 .stamp b{display:block;color:var(--green);font-size:24px;margin-bottom:3px}.stamp span{display:block;color:var(--muted);font-size:12px;overflow-wrap:anywhere}
+.audit{display:grid;grid-template-columns:1.2fr repeat(3,minmax(0,.8fr));gap:12px;margin:14px 0}
+.audit-item{border:1px solid var(--line);background:rgba(13,24,21,.92);border-radius:8px;padding:14px;min-width:0}
+.audit-item.primary{background:linear-gradient(135deg,rgba(19,61,42,.88),rgba(9,19,16,.95))}
+.audit-item.review{background:linear-gradient(135deg,rgba(81,53,17,.88),rgba(9,19,16,.95));border-color:rgba(244,191,95,.42)}
+.audit-k{color:var(--muted);font-size:12px;font-weight:700;text-transform:uppercase;letter-spacing:.08em}
+.audit-v{margin-top:7px;font-size:20px;font-weight:800;color:var(--text);overflow-wrap:anywhere}
+.audit-hint{margin-top:6px;color:var(--muted);font-size:12px;line-height:1.4}
 .metrics{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px;margin:14px 0 18px}
 .metric,.card{border:1px solid var(--line);background:rgba(13,24,21,.9);border-radius:8px}
 .metric{padding:14px}.metric .num{font-size:28px;font-weight:800;color:var(--green);line-height:1}.metric .label{margin-top:7px;color:var(--muted);font-size:12px}
@@ -147,7 +184,9 @@ code{color:var(--code);background:#0a2017;border:1px solid #17462f;padding:2px 6
 .timeline{display:grid;gap:10px}.event{display:grid;grid-template-columns:108px 1fr;gap:12px;border-top:1px solid var(--line2);padding-top:10px}.event time{color:var(--muted);font-size:12px}.event b{color:var(--green)}
 .path{font-family:ui-monospace,SFMono-Regular,Consolas,monospace;color:var(--muted);font-size:12px;overflow-wrap:anywhere}
 @media (max-width:860px){header,.layout{grid-template-columns:1fr}.metrics{grid-template-columns:repeat(2,1fr)}.grid{grid-template-columns:1fr}.agents{grid-template-columns:1fr}}
+@media (max-width:860px){.audit{grid-template-columns:1fr 1fr}}
 @media (max-width:520px){.shell{padding:14px}.metrics{grid-template-columns:1fr}.event{grid-template-columns:1fr}h1{font-size:32px}}
+@media (max-width:520px){.audit{grid-template-columns:1fr}}
 </style>
 </head>
 <body>
@@ -167,6 +206,11 @@ const timelineHtml=timeline.length?'<div class="timeline">'+timeline.slice(-8).r
 const intentsHtml=intents.length?'<div class="timeline">'+intents.slice(-6).reverse().map(i=>\`<div class="event"><time>\${esc(i.at.replace('T',' ').slice(0,16))}</time><div><b>\${esc(i.actor)}</b> plans \${esc(i.action)}</div></div>\`).join('')+'</div>':'<div class="okline">No pending agent intents recorded.</div>';
 const policyHtml=entries(policy).length?\`<table>\${rows(policy)}</table>\`:'<div class="okline">No explicit version policy set.</div>';
 const card=(title,badge,body)=>\`<section class="card"><div class="card-head"><h2>\${title}</h2>\${badge||''}</div>\${body}</section>\`;
+const reviewRequired=warnings.length>0||intents.length>0;
+const recentChanges=timeline.slice(-8).length;
+const nextAction=reviewRequired?'Review before environment changes':'Proceed with project-local work';
+const auditItem=(key,value,hint,klass='')=>\`<div class="audit-item \${klass}"><div class="audit-k">\${key}</div><div class="audit-v">\${value}</div><div class="audit-hint">\${hint}</div></div>\`;
+const handoffHtml=\`<table><tr><th>Status</th><td>\${reviewRequired?'review-required':'clear'}</td></tr><tr><th>Node</th><td><code>\${esc(manifest.runtimes.node||'not detected')}</code></td></tr><tr><th>Python</th><td><code>\${esc(manifest.runtimes.python||manifest.runtimes.python3||'not detected')}</code></td></tr><tr><th>Docker</th><td>\${manifest.containers?.docker?'available':'not detected'}</td></tr><tr><th>Next</th><td>\${reviewRequired?'Review warnings and open intents':'Continue project-local work'}</td></tr></table>\`;
 document.getElementById('app').innerHTML=\`
 <header>
   <div>
@@ -176,6 +220,12 @@ document.getElementById('app').innerHTML=\`
   </div>
   <div class="stamp"><b>\${warnings.length?'review':'clear'}</b><span>\${esc(manifest.workspace.name)}</span><span>\${esc(manifest.generatedAt)}</span></div>
 </header>
+<section class="audit" aria-label="Audit summary">
+  \${auditItem('AI decision',reviewRequired?'review required':'can proceed',nextAction,reviewRequired?'review':'primary')}
+  \${auditItem('Open intents',String(intents.length),intents.length?'Resolve or coordinate before changes':'No pending env changes')}
+  \${auditItem('Warnings',String(warnings.length),warnings.length?'Policy or drift needs attention':'No warnings detected')}
+  \${auditItem('Recent changes',String(recentChanges),recentChanges?'Check ledger before continuing':'No recent env ledger entries')}
+</section>
 <section class="metrics">
   <div class="metric"><div class="num">\${entries(manifest.runtimes).length}</div><div class="label">runtimes</div></div>
   <div class="metric"><div class="num">\${entries(manifest.packageManagers).length}</div><div class="label">package managers</div></div>
@@ -196,6 +246,8 @@ document.getElementById('app').innerHTML=\`
     <div style="height:14px"></div>
     \${card('Agent Intents','<span class="pill">'+intents.length+' open</span>',intentsHtml)}
     <div style="height:14px"></div>
+    \${card('AI Handoff',reviewRequired?'<span class="pill warn">review</span>':'<span class="pill">ready</span>',handoffHtml)}
+    <div style="height:14px"></div>
     \${card('Agent Pointers','<span class="pill">'+entries(manifest.agentFiles).filter(([,v])=>v).length+' detected</span>','<div class="agents">'+agentCards+'</div>')}
     <div style="height:14px"></div>
     \${card('Snapshot','',\`<table><tr><th>OS</th><td>\${esc(manifest.os.platform)} \${esc(manifest.os.release)} \${esc(manifest.os.arch)}</td></tr><tr><th>Shell</th><td>\${esc(manifest.os.shell||'unknown')}</td></tr><tr><th>Workspace</th><td><div class="path">\${esc(manifest.workspace.path)}</div></td></tr></table>\`)}