moondesk 0.8.0 → 0.9.1

package/README.md

@@ -9,7 +9,7 @@ npm install -g moondesk
 ```
 
 > [!IMPORTANT]
-> MoonDesk runs tools on your computer with your user account's permissions. Use a VM or container when you need strong isolation.
+> MoonDesk runs tools locally on your computer. Review commands before running them, and use an isolated environment for untrusted projects or code.
 
 ## Why MoonDesk?
 

package/npm/moondesk.js

@@ -7,15 +7,18 @@ const {
   UPDATE_EXIT_CODE,
   acquireUpdateLock,
   cleanupOldUpdateVersions,
+  changelogNoticePath,
   compareStableVersions,
   createUpdateRequestPath,
   createUpdateStatePath,
   installExactVersion,
   installedWrapperVersion,
   readUpdateRequest,
+  refreshUpdateRequestToLatest,
   restartUpdatedWrapper,
   startUpdateMonitor,
   verifyInstalledWrapperVersion,
+  writePostUpdateNotice,
 } = require("./update-manager");
 
 function cleanManagedUpdateEnv(source = process.env) {
@@ -23,6 +26,7 @@ function cleanManagedUpdateEnv(source = process.env) {
   delete env.MOONDESK_NPM_MANAGED;
   delete env.MOONDESK_UPDATE_REQUEST_PATH;
   delete env.MOONDESK_UPDATE_STATE_PATH;
+  delete env.MOONDESK_CHANGELOG_NOTICE_PATH;
   return env;
 }
 
@@ -132,11 +136,14 @@ async function orchestrate(options = {}) {
   const startUpdateMonitorImpl = options.startUpdateMonitorImpl ?? startUpdateMonitor;
   const runNativeImpl = options.runNativeImpl ?? runNative;
   const readUpdateRequestImpl = options.readUpdateRequestImpl ?? readUpdateRequest;
+  const refreshUpdateRequestToLatestImpl =
+    options.refreshUpdateRequestToLatestImpl ?? refreshUpdateRequestToLatest;
   const acquireUpdateLockImpl = options.acquireUpdateLockImpl ?? acquireUpdateLock;
   const installedWrapperVersionImpl = options.installedWrapperVersionImpl ?? installedWrapperVersion;
   const installExactVersionImpl = options.installExactVersionImpl ?? installExactVersion;
   const verifyInstalledWrapperVersionImpl =
     options.verifyInstalledWrapperVersionImpl ?? verifyInstalledWrapperVersion;
+  const writePostUpdateNoticeImpl = options.writePostUpdateNoticeImpl ?? writePostUpdateNotice;
   const restartUpdatedWrapperImpl = options.restartUpdatedWrapperImpl ?? restartUpdatedWrapper;
   const wrapperPath = options.wrapperPath ?? __filename;
 
@@ -180,6 +187,11 @@ async function orchestrate(options = {}) {
       MOONDESK_UPDATE_REQUEST_PATH: updateRequestPath,
       MOONDESK_UPDATE_STATE_PATH: updateStatePath,
     });
+    try {
+      childEnv.MOONDESK_CHANGELOG_NOTICE_PATH = changelogNoticePath();
+    } catch (error) {
+      logger.warn?.(`MoonDesk could not prepare its optional changelog notice path: ${error.message}`);
+    }
   }
 
   let result;
@@ -227,7 +239,7 @@ async function orchestrate(options = {}) {
     return { code: 1, signal: null };
   }
 
-  logger.log(`Updating MoonDesk ${request.currentVersion} -> ${request.targetVersion}...`);
+  let effectiveRequest = request;
   let releaseUpdateLock = null;
   let restartVersion = request.targetVersion;
   try {
@@ -236,26 +248,44 @@ async function orchestrate(options = {}) {
       env: baseEnv,
     });
 
+    try {
+      const refreshedRequest = await refreshUpdateRequestToLatestImpl(effectiveRequest);
+      if (compareStableVersions(refreshedRequest.targetVersion, effectiveRequest.targetVersion) > 0) {
+        logger.log(
+          `MoonDesk ${refreshedRequest.targetVersion} became available while this update was pending; updating directly to the newest version.`,
+        );
+        effectiveRequest = refreshedRequest;
+        restartVersion = effectiveRequest.targetVersion;
+      }
+    } catch (error) {
+      logger.warn?.(
+        `MoonDesk could not refresh the latest version before updating; continuing with ${effectiveRequest.targetVersion}: ${error.message}`,
+      );
+    }
+
+    logger.log(
+      `Updating MoonDesk ${effectiveRequest.currentVersion} -> ${effectiveRequest.targetVersion}...`,
+    );
     const alreadyInstalled = installedWrapperVersionImpl();
-    const comparison = compareStableVersions(alreadyInstalled, request.targetVersion);
+    const comparison = compareStableVersions(alreadyInstalled, effectiveRequest.targetVersion);
     if (comparison < 0) {
-      await installExactVersionImpl(request.targetVersion, {
+      await installExactVersionImpl(effectiveRequest.targetVersion, {
         cwd: originalCwd,
         env: baseEnv,
       });
-      verifyInstalledWrapperVersionImpl(request.targetVersion);
+      verifyInstalledWrapperVersionImpl(effectiveRequest.targetVersion);
     } else if (comparison === 0) {
-      logger.log(`MoonDesk ${request.targetVersion} was already installed by another process.`);
+      logger.log(`MoonDesk ${effectiveRequest.targetVersion} was already installed by another process.`);
     } else {
       restartVersion = alreadyInstalled;
       logger.log(
-        `MoonDesk ${alreadyInstalled} is already installed, so the updater will not downgrade it to ${request.targetVersion}.`,
+        `MoonDesk ${alreadyInstalled} is already installed, so the updater will not downgrade it to ${effectiveRequest.targetVersion}.`,
       );
     }
   } catch (error) {
     logger.error(`MoonDesk update failed: ${error.message}`);
     logger.error(
-      `Run 'npm install -g moondesk@${request.targetVersion}' manually to retry this exact version.`,
+      `Run 'npm install -g moondesk@${effectiveRequest.targetVersion}' manually to retry this exact version.`,
     );
     return { code: 1, signal: null };
   } finally {
@@ -266,6 +296,14 @@ async function orchestrate(options = {}) {
     }
   }
 
+  if (restartVersion === effectiveRequest.targetVersion) {
+    try {
+      writePostUpdateNoticeImpl(effectiveRequest, restartVersion);
+    } catch (error) {
+      logger.warn?.(`MoonDesk updated, but could not persist its one-time changelog notice: ${error.message}`);
+    }
+  }
+
   logger.log(`MoonDesk ${restartVersion} is installed. Restarting...`);
   try {
     return await restartUpdatedWrapperImpl(wrapperPath, originalArgs, {

package/npm/update-manager.js

@@ -14,16 +14,34 @@ const currentVersion = packageJson.version;
 const UPDATE_EXIT_CODE = 75;
 const UPDATE_STATE_SCHEMA_VERSION = 1;
 const UPDATE_REQUEST_SCHEMA_VERSION = 1;
+const CHANGELOG_NOTICE_SCHEMA_VERSION = 1;
 const REGISTRY_LATEST_URL = "https://registry.npmjs.org/moondesk/latest";
+const GITHUB_REPOSITORY = "Shattermoon/moondesk";
+const GITHUB_RELEASES_API_URL = `https://api.github.com/repos/${GITHUB_REPOSITORY}/releases?per_page=20`;
+const GITHUB_RELEASE_TAG_API_BASE = `https://api.github.com/repos/${GITHUB_REPOSITORY}/releases/tags`;
+const GITHUB_RELEASE_WEB_BASE = `https://github.com/${GITHUB_REPOSITORY}/releases/tag`;
+const GITHUB_PULL_WEB_BASE = `https://github.com/${GITHUB_REPOSITORY}/pull`;
 const UPDATE_CHECK_INTERVAL_MS = 15 * 60_000;
 const UPDATE_CHECK_TIMEOUT_MS = 15_000;
 const MAX_UPDATE_METADATA_BYTES = 64 * 1024;
+const MAX_CHANGELOG_METADATA_BYTES = 512 * 1024;
+const MAX_CHANGELOG_ITEMS = 12;
+const MAX_CHANGELOG_ITEM_CHARS = 180;
 const MAX_UPDATE_REQUEST_BYTES = 16 * 1024;
 const MAX_NPM_ROOT_BYTES = 16 * 1024;
 const NPM_ROOT_TIMEOUT_MS = 10_000;
 const UPDATE_LOCK_WAIT_MS = 60_000;
 const UPDATE_LOCK_POLL_MS = 200;
 
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const GITHUB_PULL_ATTRIBUTION_RE = new RegExp(
+  `\\s+by\\s+@[A-Za-z0-9_-]+\\s+in\\s+${escapeRegExp(GITHUB_PULL_WEB_BASE)}\\/\\d+\\s*$`,
+  "i",
+);
+
 function parseStableVersion(input) {
   if (typeof input !== "string") {
     return null;
@@ -101,6 +119,49 @@ function cleanupOldUpdateVersions(options = {}) {
   return { removed, skipped };
 }
 
+function changelogNoticePath(version = currentVersion) {
+  if (!parseStableVersion(version)) {
+    throw new Error(`MoonDesk changelog version must be a stable semantic version: ${version}`);
+  }
+  return path.join(updateRootDir(), `v${version}`, "post-update.json");
+}
+
+function normalizePersistedReleaseNotes(value) {
+  if (!Array.isArray(value)) return [];
+  const notes = [];
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const trimmed = item.trim();
+    if (!trimmed || trimmed.length > MAX_CHANGELOG_ITEM_CHARS) continue;
+    notes.push(trimmed);
+    if (notes.length >= MAX_CHANGELOG_ITEMS) break;
+  }
+  return notes;
+}
+
+function normalizeReleaseUrl(value, version) {
+  const expected = `${GITHUB_RELEASE_WEB_BASE}/v${version}`;
+  return typeof value === "string" && value === expected ? value : null;
+}
+
+function writePostUpdateNotice(request, installedVersion, options = {}) {
+  if (!request || request.targetVersion !== installedVersion || !parseStableVersion(installedVersion)) {
+    return null;
+  }
+  const filePath = options.noticePath ?? changelogNoticePath(installedVersion);
+  const notice = {
+    schemaVersion: CHANGELOG_NOTICE_SCHEMA_VERSION,
+    packageName: "moondesk",
+    fromVersion: request.currentVersion,
+    toVersion: installedVersion,
+    releaseNotes: normalizePersistedReleaseNotes(request.releaseNotes),
+    releaseUrl: normalizeReleaseUrl(request.releaseUrl, installedVersion),
+    createdAt: new Date().toISOString(),
+  };
+  atomicWriteJson(filePath, notice, options);
+  return filePath;
+}
+
 function updateRequestDir() {
   return path.join(currentUpdateDir(), "requests");
 }
@@ -234,7 +295,7 @@ function atomicWriteJson(filePath, value, options = {}) {
   }
 }
 
-async function fetchJsonLimited(fetchImpl, url, externalSignal) {
+async function fetchJsonLimited(fetchImpl, url, externalSignal, maxBytes = MAX_UPDATE_METADATA_BYTES) {
   const controller = new AbortController();
   const abortFromParent = () => controller.abort();
   if (externalSignal) {
@@ -259,7 +320,7 @@ async function fetchJsonLimited(fetchImpl, url, externalSignal) {
       throw new Error(`${url} returned HTTP ${response.status}`);
     }
     const contentLength = Number(response.headers.get("content-length"));
-    if (Number.isFinite(contentLength) && contentLength > MAX_UPDATE_METADATA_BYTES) {
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
       controller.abort();
       throw new Error(`MoonDesk update metadata is unexpectedly large (${contentLength} bytes)`);
     }
@@ -272,7 +333,7 @@ async function fetchJsonLimited(fetchImpl, url, externalSignal) {
     for await (const chunk of response.body) {
       const buffer = Buffer.from(chunk);
       totalBytes += buffer.length;
-      if (totalBytes > MAX_UPDATE_METADATA_BYTES) {
+      if (totalBytes > maxBytes) {
         controller.abort();
         throw new Error("MoonDesk update metadata exceeded the download limit");
       }
@@ -285,13 +346,138 @@ async function fetchJsonLimited(fetchImpl, url, externalSignal) {
   }
 }
 
-async function checkForUpdate(options = {}) {
+function normalizeChangelogLine(line) {
+  if (typeof line !== "string") return null;
+  let value = line.trim();
+  if (!value || value.startsWith("#") || /^\*\*Full Changelog\*\*/i.test(value)) return null;
+  value = value.replace(/^[-*+]\s+/, "");
+  value = value.replace(GITHUB_PULL_ATTRIBUTION_RE, "");
+  value = value.replace(/^\[(.+?)\]\([^)]*\)$/, "$1");
+  value = value.replace(/`([^`]+)`/g, "$1");
+  value = value.replace(/^(?:feat|fix|chore|refactor|perf|docs|test|build|ci|style)(?:\([^)]*\))?!?:\s*/i, "");
+  value = value.trim();
+  if (!value || /^https?:\/\//i.test(value)) return null;
+  value = `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+  if (value.length > MAX_CHANGELOG_ITEM_CHARS) {
+    value = `${value.slice(0, MAX_CHANGELOG_ITEM_CHARS - 3).trimEnd()}...`;
+  }
+  return value;
+}
+
+function normalizeReleaseNotes(body) {
+  if (typeof body !== "string") return [];
+  const notes = [];
+  const seen = new Set();
+  for (const line of body.split(/\r?\n/)) {
+    const note = normalizeChangelogLine(line);
+    if (!note || seen.has(note)) continue;
+    seen.add(note);
+    notes.push(note);
+    if (notes.length >= MAX_CHANGELOG_ITEMS) break;
+  }
+  return notes;
+}
+
+function boundedChangelogItem(value) {
+  const trimmed = String(value ?? "").trim();
+  if (!trimmed) return null;
+  if (trimmed.length <= MAX_CHANGELOG_ITEM_CHARS) return trimmed;
+  return `${trimmed.slice(0, MAX_CHANGELOG_ITEM_CHARS - 3).trimEnd()}...`;
+}
+
+function stableReleaseVersion(release) {
+  if (!release || release.draft === true || release.prerelease === true) return null;
+  if (typeof release.tag_name !== "string" || !release.tag_name.startsWith("v")) return null;
+  const version = release.tag_name.slice(1);
+  return parseStableVersion(version) ? version : null;
+}
+
+async function fetchReleaseChangelog(fromVersion, toVersion, options = {}) {
+  if (
+    !parseStableVersion(fromVersion) ||
+    !parseStableVersion(toVersion) ||
+    compareStableVersions(toVersion, fromVersion) <= 0
+  ) {
+    return { releaseNotes: [], releaseUrl: null };
+  }
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") return { releaseNotes: [], releaseUrl: null };
+
+  const releasesUrl = options.releasesApiUrl ?? GITHUB_RELEASES_API_URL;
+  const releases = await fetchJsonLimited(
+    fetchImpl,
+    releasesUrl,
+    options.signal,
+    MAX_CHANGELOG_METADATA_BYTES,
+  );
+  if (!Array.isArray(releases)) {
+    throw new Error("GitHub returned invalid MoonDesk releases metadata");
+  }
+
+  const selected = [];
+  for (const release of releases) {
+    const version = stableReleaseVersion(release);
+    if (!version) continue;
+    if (
+      compareStableVersions(version, fromVersion) > 0 &&
+      compareStableVersions(version, toVersion) <= 0
+    ) {
+      selected.push({ release, version });
+    }
+  }
+
+  if (!selected.some((item) => item.version === toVersion)) {
+    const tagApiBase = options.releaseTagApiBase ?? GITHUB_RELEASE_TAG_API_BASE;
+    try {
+      const release = await fetchJsonLimited(
+        fetchImpl,
+        `${tagApiBase}/v${toVersion}`,
+        options.signal,
+        MAX_CHANGELOG_METADATA_BYTES,
+      );
+      if (stableReleaseVersion(release) === toVersion) {
+        selected.push({ release, version: toVersion });
+      }
+    } catch {
+      // The recent releases list may briefly lag the just-published npm tag.
+      // Missing notes must never block a valid npm update.
+    }
+  }
+
+  selected.sort((left, right) => compareStableVersions(right.version, left.version));
+  const uniqueReleases = [];
+  const seenVersions = new Set();
+  for (const item of selected) {
+    if (seenVersions.has(item.version)) continue;
+    seenVersions.add(item.version);
+    uniqueReleases.push(item);
+  }
+
+  const includeVersion = uniqueReleases.length > 1;
+  const releaseNotes = [];
+  const seenNotes = new Set();
+  for (const { release, version } of uniqueReleases) {
+    for (const note of normalizeReleaseNotes(release.body)) {
+      const rendered = boundedChangelogItem(includeVersion ? `v${version}: ${note}` : note);
+      if (!rendered || seenNotes.has(rendered)) continue;
+      seenNotes.add(rendered);
+      releaseNotes.push(rendered);
+      if (releaseNotes.length >= MAX_CHANGELOG_ITEMS) break;
+    }
+    if (releaseNotes.length >= MAX_CHANGELOG_ITEMS) break;
+  }
+
+  const expectedUrl = `${GITHUB_RELEASE_WEB_BASE}/v${toVersion}`;
+  const target = uniqueReleases.find((item) => item.version === toVersion)?.release;
+  const releaseUrl = target ? expectedUrl : null;
+  return { releaseNotes, releaseUrl };
+}
+
+async function fetchLatestPackageMetadata(options = {}) {
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
-  const statePath = options.statePath ?? createUpdateStatePath();
   const registryUrl = options.registryUrl ?? REGISTRY_LATEST_URL;
-  const managedInstall = options.managedInstall === true;
   if (typeof fetchImpl !== "function") {
-    return null;
+    throw new Error("MoonDesk update checks require a fetch implementation");
   }
 
   const metadata = await fetchJsonLimited(fetchImpl, registryUrl, options.signal);
@@ -305,8 +491,69 @@ async function checkForUpdate(options = {}) {
   if (typeof metadata?.dist?.integrity !== "string" || !metadata.dist.integrity.startsWith("sha512-")) {
     throw new Error("npm returned MoonDesk metadata without a sha512 package integrity value");
   }
+  return metadata;
+}
+
+async function refreshUpdateRequestToLatest(request, options = {}) {
+  if (
+    !request ||
+    request.currentVersion !== currentVersion ||
+    !parseStableVersion(request.targetVersion) ||
+    compareStableVersions(request.targetVersion, currentVersion) <= 0
+  ) {
+    throw new Error("Refusing to refresh an invalid MoonDesk update request");
+  }
 
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const metadata = await fetchLatestPackageMetadata({ ...options, fetchImpl });
+  const latestVersion = metadata.version;
+  if (compareStableVersions(latestVersion, request.targetVersion) <= 0) {
+    return request;
+  }
+
+  let releaseNotes = [];
+  let releaseUrl = null;
+  try {
+    ({ releaseNotes, releaseUrl } = await fetchReleaseChangelog(
+      request.currentVersion,
+      latestVersion,
+      { ...options, fetchImpl },
+    ));
+  } catch {
+    // The exact newest npm target is authoritative. GitHub notes remain optional.
+  }
+
+  return {
+    ...request,
+    targetVersion: latestVersion,
+    releaseNotes,
+    releaseUrl,
+  };
+}
+
+async function checkForUpdate(options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const statePath = options.statePath ?? createUpdateStatePath();
+  const managedInstall = options.managedInstall === true;
+  if (typeof fetchImpl !== "function") {
+    return null;
+  }
+
+  const metadata = await fetchLatestPackageMetadata({ ...options, fetchImpl });
+  const latestVersion = metadata.version;
   const available = managedInstall && compareStableVersions(latestVersion, currentVersion) > 0;
+  let releaseNotes = [];
+  let releaseUrl = null;
+  if (available) {
+    try {
+      ({ releaseNotes, releaseUrl } = await fetchReleaseChangelog(currentVersion, latestVersion, {
+        ...options,
+        fetchImpl,
+      }));
+    } catch {
+      // Release notes are optional metadata. A GitHub outage must never hide a valid npm update.
+    }
+  }
   const state = {
     schemaVersion: UPDATE_STATE_SCHEMA_VERSION,
     packageName: "moondesk",
@@ -314,6 +561,8 @@ async function checkForUpdate(options = {}) {
     latestVersion,
     managedInstall,
     available,
+    releaseNotes,
+    releaseUrl,
     checkedAt: new Date().toISOString(),
   };
   atomicWriteJson(statePath, state, options);
@@ -396,7 +645,11 @@ function readUpdateRequest(requestPath) {
   ) {
     return null;
   }
-  return parsed;
+  return {
+    ...parsed,
+    releaseNotes: normalizePersistedReleaseNotes(parsed.releaseNotes),
+    releaseUrl: normalizeReleaseUrl(parsed.releaseUrl, parsed.targetVersion),
+  };
 }
 
 function updateLockPath() {
@@ -570,17 +823,22 @@ module.exports = {
   atomicWriteJson,
   checkForUpdate,
   cleanupOldUpdateVersions,
+  changelogNoticePath,
   compareStableVersions,
   createUpdateRequestPath,
   createUpdateStatePath,
   currentVersion,
+  fetchReleaseChangelog,
   installExactVersion,
   installedWrapperVersion,
   isGlobalPackageInstall,
+  normalizeReleaseNotes,
   parseStableVersion,
   readUpdateRequest,
+  refreshUpdateRequestToLatest,
   resolveGlobalNpmRoot,
   restartUpdatedWrapper,
   startUpdateMonitor,
   verifyInstalledWrapperVersion,
+  writePostUpdateNotice,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moondesk",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "MoonDesk — use ChatGPT Chat as a local coding agent, by Shattermoon.",
   "author": "Shattermoon",
   "license": "MIT",