@plasmickit/cli 0.0.81 → 0.0.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasmickit/cli",
-  "version": "0.0.81",
+  "version": "0.0.83",
   "description": "Plasmic skill bootstrap and NAS workflow resource manager",
   "license": "MIT",
   "repository": {

package/skill/plasmic/SKILL.md

@@ -19,6 +19,8 @@ Inspect uses accessible Desktop MCP reads and does not require edit permission o
 
 The command checks the NAS release manifest every time, downloads changed resources and verifies their hashes before returning absolute paths. Read all returned `mustRead` files, starting with `referencePath`; resolve subsequent links relative to the reference file. Use the returned `resourceRoot` for verification scripts. For a task spanning multiple modes, resolve and read each mode before its work begins.
 
+The CLI streams readable progress to stderr and reserves stdout for the final JSON result. Tell the user when resource preparation starts, then relay meaningful stage changes in their language: current and latest versions, already up to date, or download and integrity verification. Do not narrate cache saving, update locking, compatibility checks or workflow entrypoints. When the command runs longer than the tool's initial response window, use its background/session mode and retrieve incremental output so the user sees progress while it runs. Waiting messages report elapsed time, not an estimated completion percentage. If the tool buffers all output until exit, explain that limitation and report that preparation is still running; do not invent progress. A ready workflow means its files are available for you to read, not that you have already read or executed them. Read `mustRead` before starting dependent work.
+
 The runner uses the latest published `@plasmickit/cli`, distinct from official `@plasmicapp/cli`. Later commands can use `npx -y @plasmickit/cli@<cliVersion>` from the result to keep the task on that CLI version, or the global `plasmickit` after checking `plasmickit version check`.
 
 If the command fails, stop dependent work and report the error. Do not silently use cached references. If it requires a newer CLI before npm has that version, install the returned `cliUrl` with `npm install -g <cliUrl>` and rerun. Do not copy the resource bundle into this skill or treat an old transcript as the current component contract.

package/src/index.mjs

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
-import { parseArgs } from "node:util";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
 import { realpathSync } from "node:fs";
-import { checkCliVersion, checkReferences, referencePath, resolveContext, updateReferences } from "./references.mjs";
-import { installSkill } from "./skill.mjs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { formatProgress } from "./progress.mjs";
 import { CLI_VERSION } from "./protocol.mjs";
+import {
+  checkCliVersion,
+  checkReferences,
+  referencePath,
+  resolveContext,
+  updateReferences,
+} from "./references.mjs";
+import { installSkill } from "./skill.mjs";
 
 const usage = `plasmickit commands:
   skill install [--dry-run]
@@ -15,31 +22,79 @@ const usage = `plasmickit commands:
   --version
 `;
 export async function main(argv) {
-  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
-    "dry-run": { type: "boolean" }, mode: { type: "string" }, feed: { type: "string" }, home: { type: "string" },
-    help: { type: "boolean" }, version: { type: "boolean" },
-  } });
-  if (values.version) { process.stdout.write(CLI_VERSION + "\n"); return; }
-  if (!positionals.length || values.help) { process.stdout.write(usage); return; }
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      "dry-run": { type: "boolean" },
+      mode: { type: "string" },
+      feed: { type: "string" },
+      home: { type: "string" },
+      help: { type: "boolean" },
+      version: { type: "boolean" },
+    },
+  });
+  if (values.version) {
+    process.stdout.write(CLI_VERSION + "\n");
+    return;
+  }
+  if (!positionals.length || values.help) {
+    process.stdout.write(usage);
+    return;
+  }
   const [command, action] = positionals;
-  if (positionals.length !== 2) throw new Error("Expected a command and action; use --help");
+  if (positionals.length !== 2) {
+    throw new Error("Expected a command and action; use --help");
+  }
+  values.onProgress = (event) =>
+    process.stderr.write(
+      formatProgress({
+        ...event,
+        versionKind: command === "version" ? "cli" : "resources",
+      }),
+    );
   let output;
-  if (command === "skill" && action === "install") output = await installSkill({ dryRun: values["dry-run"] });
-  else if (command === "version" && action === "check") output = await checkCliVersion(values);
-  else if (command === "references" && action === "check") output = await checkReferences(values);
-  else if (command === "references" && action === "update") {
+  if (command === "skill" && action === "install") {
+    output = await installSkill({ dryRun: values["dry-run"] });
+  } else if (command === "version" && action === "check") {
+    output = await checkCliVersion(values);
+  } else if (command === "references" && action === "check") {
+    output = await checkReferences(values);
+  } else if (command === "references" && action === "update") {
     const { manifest: _manifest, ...result } = await updateReferences(values);
     output = result;
+  } else if (command === "references" && action === "path") {
+    output = await referencePath(values);
+  } else if (command === "context" && action === "resolve") {
+    output = await resolveContext(values.mode, values);
+  } else {
+    throw new Error(`Unknown command: ${command} ${action}`);
   }
-  else if (command === "references" && action === "path") output = await referencePath(values);
-  else if (command === "context" && action === "resolve") output = await resolveContext(values.mode, values);
-  else throw new Error(`Unknown command: ${command} ${action}`);
   process.stdout.write(JSON.stringify({ ok: true, ...output }, null, 2) + "\n");
-  if (output.ok === false) process.exitCode = 1;
+  if (output.ok === false) {
+    process.exitCode = 1;
+  }
 }
-if (process.argv[1] && realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
+if (
+  process.argv[1] &&
+  realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)
+) {
   main(process.argv.slice(2)).catch((error) => {
-    process.stderr.write(JSON.stringify({ ok: false, error: error.message, ...(error.cliUrl ? { cliUrl: error.cliUrl, cliVersion: error.cliVersion, latestCliVersion: error.latestCliVersion, minCliVersion: error.minCliVersion } : {}) }) + "\n");
+    process.stderr.write(
+      JSON.stringify({
+        ok: false,
+        error: error.message,
+        ...(error.stage ? { stage: error.stage } : {}),
+        ...(error.cliUrl
+          ? {
+              cliUrl: error.cliUrl,
+              cliVersion: error.cliVersion,
+              latestCliVersion: error.latestCliVersion,
+              minCliVersion: error.minCliVersion,
+            }
+          : {}),
+      }) + "\n",
+    );
     process.exitCode = 1;
   });
 }

package/src/progress.mjs

@@ -0,0 +1,122 @@
+const labels = {
+  manifest: ["版本检查", "正在检查版本", "版本检查完成"],
+  download: ["资源下载", "正在下载资源", "下载完成"],
+  verify: ["资源校验", "正在校验资源", "校验通过"],
+};
+
+export async function withProgress(options, stage, action, details = {}) {
+  const started = Date.now();
+  let state = details;
+  let lastUpdate = 0;
+  const emit = (status) =>
+    options.onProgress?.({
+      type: "resource-progress",
+      stage,
+      ...state,
+      status,
+      elapsedMs: Date.now() - started,
+    });
+  emit("running");
+  const timer = options.onProgress
+    ? setInterval(() => emit("running"), 2000)
+    : undefined;
+  timer?.unref();
+  try {
+    const result = await action((update) => {
+      state = { ...state, ...update };
+      if (
+        ("bytes" in update || "completedFiles" in update) &&
+        Date.now() - lastUpdate >= 500
+      ) {
+        lastUpdate = Date.now();
+        emit("running");
+      }
+    });
+    emit("completed");
+    return result;
+  } catch (error) {
+    error.stage ??= stage;
+    state = {
+      ...state,
+      error: error.message,
+      timedOut:
+        error.name === "TimeoutError" || error.cause?.name === "TimeoutError",
+    };
+    emit("failed");
+    throw error;
+  } finally {
+    clearInterval(timer);
+  }
+}
+
+function size(bytes) {
+  return bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MiB`
+    : bytes >= 1024
+      ? `${(bytes / 1024).toFixed(1)} KiB`
+      : `${bytes} B`;
+}
+
+export function formatProgress(event) {
+  if (event.status !== "failed") {
+    if (
+      event.stage === "cache" &&
+      event.status === "completed" &&
+      event.upToDate !== undefined
+    ) {
+      return event.upToDate
+        ? "✓ 当前资源已是最新版本\n"
+        : "… 正在准备加载资源\n";
+    }
+    if (
+      event.stage === "activate" &&
+      event.status === "completed" &&
+      event.updated
+    ) {
+      return "✓ 资源加载完成\n";
+    }
+    if (!labels[event.stage]) {
+      return event.status === "running" && event.elapsedMs >= 2000
+        ? `… 正在加载资源，已等待 ${Math.floor(event.elapsedMs / 1000)} 秒\n`
+        : "";
+    }
+  }
+  const [label, running, completed] = labels[event.stage] ?? ["资源加载"];
+  const icon =
+    event.status === "completed" ? "✓" : event.status === "failed" ? "✗" : "…";
+  let message = event.status === "completed" ? completed : running;
+  if (event.status === "failed") {
+    message = event.timedOut
+      ? "请求超过 30 秒，请检查网络和资源服务后重试"
+      : `未完成：${event.error}`;
+    if (event.error === "fetch failed") {
+      message = "无法连接资源服务，请检查网络或资源地址后重试";
+    }
+    if (event.error?.startsWith("Resource update already in progress:")) {
+      message = "已有资源更新任务正在进行，请等待该任务完成后重试";
+    }
+    const http = /HTTP (\d+)/.exec(event.error ?? "");
+    if (http) {
+      message = `资源服务返回 HTTP ${http[1]}，请检查服务状态或资源地址后重试`;
+    }
+  }
+  const details = [];
+  if (event.stage === "manifest" && event.version) {
+    message =
+      event.versionKind === "cli"
+        ? `当前版本 ${event.currentCliVersion}，最新版本 ${event.cliVersion}`
+        : `当前版本 ${event.currentVersion ?? "尚未加载"}，最新版本 ${event.version}`;
+  }
+  if (event.stage === "download" && event.bytes !== undefined) {
+    details.push(
+      `${size(event.bytes)}${event.totalBytes ? ` / ${size(event.totalBytes)}` : ""}`,
+    );
+    if (event.totalBytes && event.bytes <= event.totalBytes) {
+      details.push(`${Math.floor((event.bytes / event.totalBytes) * 100)}%`);
+    }
+  }
+  if (event.status === "running" && event.elapsedMs >= 2000) {
+    details.push(`仍在处理，已等待 ${Math.floor(event.elapsedMs / 1000)} 秒`);
+  }
+  return `${icon} [${label}] ${message}${details.length ? ` · ${details.join(" · ")}` : ""}\n`;
+}

package/src/protocol.mjs

@@ -39,10 +39,12 @@ export function resourcePath(name) {
 }
 export function validateManifest(manifest) {
   if (!manifest || manifest.schemaVersion !== 1 || !/^\d+\.\d+\.\d+$/.test(manifest.version) ||
+      !/^\d+\.\d+\.\d+$/.test(manifest.cliVersion) ||
       !/^\d+\.\d+\.\d+$/.test(manifest.minCliVersion) || manifest.releaseId !== releaseId(manifest)) {
     throw new Error("Invalid resource manifest or release checksum");
   }
-  if (compareVersions(manifest.minCliVersion, manifest.version) > 0) throw new Error("Required CLI version exceeds release version");
+  if (compareVersions(manifest.minCliVersion, manifest.cliVersion) > 0) throw new Error("Required CLI version exceeds published CLI version");
+  compareVersions(manifest.version, manifest.version);
   const files = new Map();
   if (!Array.isArray(manifest.files) || !manifest.files.length) throw new Error("Empty resource manifest");
   for (const file of manifest.files) {

package/src/references.mjs

@@ -1,74 +1,176 @@
-import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-import { artifactUrl, CLI_VERSION, MODE_REFERENCES, feedUrl, MAX_BYTES, requiresNewCli, sha256, unpackResources, validateManifest } from "./protocol.mjs";
+import { withProgress } from "./progress.mjs";
+import {
+  CLI_VERSION,
+  MAX_BYTES,
+  MODE_REFERENCES,
+  artifactUrl,
+  feedUrl,
+  requiresNewCli,
+  sha256,
+  unpackResources,
+  validateManifest,
+} from "./protocol.mjs";
 
-const cacheRoot = (options) => path.resolve(options.home || process.env.PLASMIC_RESOURCE_HOME || path.join(homedir(), ".cache", "plasmic"));
-async function download(url) {
-  const response = await fetch(url, { cache: "no-store", signal: AbortSignal.timeout(30000) });
-  if (!response.ok) throw new Error(`Cannot download ${url}: HTTP ${response.status}`);
+const cacheRoot = (options) =>
+  path.resolve(
+    options.home ||
+      process.env.PLASMIC_RESOURCE_HOME ||
+      path.join(homedir(), ".cache", "plasmic"),
+  );
+async function download(url, progress) {
+  const response = await fetch(url, {
+    cache: "no-store",
+    signal: AbortSignal.timeout(30000),
+  });
+  if (!response.ok) {
+    throw new Error(`Cannot download ${url}: HTTP ${response.status}`);
+  }
   const chunks = [];
   let size = 0;
   for await (const chunk of response.body) {
     size += chunk.length;
-    if (size > MAX_BYTES) throw new Error("Resource download exceeds limit");
+    if (size > MAX_BYTES) {
+      throw new Error("Resource download exceeds limit");
+    }
     chunks.push(chunk);
+    progress?.({ bytes: size });
   }
   return Buffer.concat(chunks);
 }
 async function latest(options) {
   const feed = feedUrl(options.feed);
-  const manifest = validateManifest(JSON.parse((await download(new URL("latest.json", feed))).toString("utf8")));
+  const manifest = await withProgress(options, "manifest", async (progress) => {
+    const state = await current(cacheRoot(options));
+    const checkedManifest = validateManifest(
+      JSON.parse(
+        (await download(new URL("latest.json", feed))).toString("utf8"),
+      ),
+    );
+    progress({
+      version: checkedManifest.version,
+      currentVersion: state?.version ?? null,
+      currentCliVersion: CLI_VERSION,
+      cliVersion: checkedManifest.cliVersion,
+    });
+    return checkedManifest;
+  });
   const cliUrl = artifactUrl(feed, manifest, "cli");
   return { feed, manifest, cliUrl };
 }
 function versionInfo(release) {
   return {
     cliVersion: CLI_VERSION,
-    latestCliVersion: release.manifest.version,
+    latestCliVersion: release.manifest.cliVersion,
     minCliVersion: release.manifest.minCliVersion,
-    cliUpdateAvailable: requiresNewCli(release.manifest.version),
+    cliUpdateAvailable: requiresNewCli(release.manifest.cliVersion),
     cliCompatible: !requiresNewCli(release.manifest.minCliVersion),
     cliUrl: release.cliUrl,
   };
 }
 function requireCompatibleCli(release) {
   if (requiresNewCli(release.manifest.minCliVersion)) {
-    const error = new Error(`Resources require CLI ${release.manifest.minCliVersion}; install ${release.cliUrl} and rerun`);
+    const error = new Error(
+      `Resources require CLI ${release.manifest.minCliVersion}; install ${release.cliUrl} and rerun`,
+    );
     Object.assign(error, versionInfo(release));
     throw error;
   }
 }
-export async function checkCliVersion(options = {}) { return versionInfo(await latest(options)); }
+export async function checkCliVersion(options = {}) {
+  return versionInfo(await latest(options));
+}
 async function current(root) {
-  try { return JSON.parse(await readFile(path.join(root, "current.json"), "utf8")); }
-  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  try {
+    return JSON.parse(await readFile(path.join(root, "current.json"), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
 }
-async function verifyLocal(directory, manifest) {
+async function verifyLocal(directory, manifest, progress) {
   try {
-    if (!(await lstat(directory)).isDirectory()) return false;
-    const cachedText = await readFile(path.join(directory, "manifest.json"), "utf8");
+    if (!(await lstat(directory)).isDirectory()) {
+      return false;
+    }
+    const cachedText = await readFile(
+      path.join(directory, "manifest.json"),
+      "utf8",
+    );
     try {
       const cached = validateManifest(JSON.parse(cachedText));
-      if (cached.releaseId !== manifest.releaseId) return false;
-    } catch { return false; }
+      if (cached.releaseId !== manifest.releaseId) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+    let completedFiles = 0;
     for (const file of manifest.files) {
       const target = path.join(directory, file.path);
       // Resource directories/files must be real cache entries, never symlinks.
       let parent = path.dirname(target);
       while (parent !== directory) {
-        if (!(await lstat(parent)).isDirectory()) return false;
+        if (!(await lstat(parent)).isDirectory()) {
+          return false;
+        }
         parent = path.dirname(parent);
       }
       const stat = await lstat(target);
-      if (!stat.isFile() || stat.size !== file.size || sha256(await readFile(target)) !== file.sha256) return false;
+      if (
+        !stat.isFile() ||
+        stat.size !== file.size ||
+        sha256(await readFile(target)) !== file.sha256
+      ) {
+        return false;
+      }
+      progress?.({
+        completedFiles: ++completedFiles,
+        totalFiles: manifest.files.length,
+      });
     }
     return true;
   } catch (error) {
-    if (["ENOENT", "ENOTDIR"].includes(error.code)) return false;
+    if (["ENOENT", "ENOTDIR"].includes(error.code)) {
+      return false;
+    }
     throw error;
   }
 }
+async function checkCache(directory, manifest, options, state) {
+  return withProgress(
+    options,
+    "cache",
+    async (progress) => {
+      const valid = await verifyLocal(directory, manifest, progress);
+      progress({
+        valid,
+        ...(state !== undefined
+          ? {
+              upToDate:
+                valid &&
+                state?.releaseId === manifest.releaseId &&
+                state?.feed === feedUrl(options.feed),
+            }
+          : {}),
+      });
+      return valid;
+    },
+    { completedFiles: 0, totalFiles: manifest.files.length },
+  );
+}
 function result(root, release, extra = {}) {
   const resourceRoot = path.join(root, "releases", release.manifest.releaseId);
   return {
@@ -81,66 +183,176 @@ function result(root, release, extra = {}) {
   };
 }
 export async function checkReferences(options = {}) {
-  const root = cacheRoot(options), release = await latest(options), state = await current(root);
+  const root = cacheRoot(options),
+    release = await latest(options),
+    state = await current(root);
   const directory = path.join(root, "releases", release.manifest.releaseId);
-  const valid = await verifyLocal(directory, release.manifest);
-  return result(root, release, { updateAvailable: state?.releaseId !== release.manifest.releaseId || state?.feed !== release.feed || !valid, localVersion: state?.version || null });
+  const valid = await checkCache(directory, release.manifest, options, state);
+  return result(root, release, {
+    updateAvailable:
+      state?.releaseId !== release.manifest.releaseId ||
+      state?.feed !== release.feed ||
+      !valid,
+    localVersion: state?.version || null,
+  });
 }
 export async function updateReferences(options = {}) {
-  const root = cacheRoot(options), release = await latest(options);
-  requireCompatibleCli(release);
-  await mkdir(root, { recursive: true });
+  const root = cacheRoot(options),
+    release = await latest(options);
+  await withProgress(options, "compatibility", () =>
+    requireCompatibleCli(release),
+  );
   const lock = path.join(root, ".update-lock");
-  try { await mkdir(lock); }
-  catch (error) {
-    if (error.code === "EEXIST") throw new Error(`Resource update already in progress: ${lock}`);
-    throw error;
+  await withProgress(options, "lock", async () => {
+    await mkdir(root, { recursive: true });
+    try {
+      await mkdir(lock);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new Error(`Resource update already in progress: ${lock}`);
+      }
+      throw error;
+    }
+  });
+  try {
+    return await installResources(root, release, options);
+  } finally {
+    await rm(lock, { recursive: true, force: true });
   }
-  try { return await installResources(root, release); }
-  finally { await rm(lock, { recursive: true, force: true }); }
 }
-async function installResources(root, release) {
+async function installResources(root, release, options) {
   const directory = path.join(root, "releases", release.manifest.releaseId);
   const state = await current(root);
-  let updated = state?.releaseId !== release.manifest.releaseId || state?.feed !== release.feed;
-  if (!await verifyLocal(directory, release.manifest)) {
-    const files = unpackResources(await download(artifactUrl(release.feed, release.manifest, "resources")), release.manifest);
-    await mkdir(path.dirname(directory), { recursive: true });
-    const staging = await mkdtemp(path.join(root, "releases", ".download-"));
-    try {
-      for (const file of files) {
-        const target = path.join(staging, file.path);
-        await mkdir(path.dirname(target), { recursive: true });
-        await writeFile(target, file.content, { flag: "wx" });
-      }
-      await writeFile(path.join(staging, "manifest.json"), JSON.stringify(release.manifest));
-      // Replace corrupt entries only after the complete replacement has been verified.
-      if (!await verifyLocal(directory, release.manifest)) await rm(directory, { recursive: true, force: true });
-      try { await rename(staging, directory); }
-      catch (error) {
-        if (!["EEXIST", "ENOTEMPTY"].includes(error.code) || !await verifyLocal(directory, release.manifest)) throw error;
-      }
-      updated = true;
-    } finally { await rm(staging, { recursive: true, force: true }); }
+  let updated =
+    state?.releaseId !== release.manifest.releaseId ||
+    state?.feed !== release.feed;
+  if (!(await checkCache(directory, release.manifest, options, state))) {
+    const bytes = await withProgress(
+      options,
+      "download",
+      (progress) =>
+        download(
+          artifactUrl(release.feed, release.manifest, "resources"),
+          progress,
+        ),
+      { bytes: 0, totalBytes: release.manifest.artifacts.resources.size },
+    );
+    const files = await withProgress(options, "verify", () =>
+      unpackResources(bytes, release.manifest),
+    );
+    await withProgress(
+      options,
+      "install",
+      async (progress) => {
+        await mkdir(path.dirname(directory), { recursive: true });
+        const staging = await mkdtemp(
+          path.join(root, "releases", ".download-"),
+        );
+        try {
+          let completedFiles = 0;
+          for (const file of files) {
+            const target = path.join(staging, file.path);
+            await mkdir(path.dirname(target), { recursive: true });
+            await writeFile(target, file.content, { flag: "wx" });
+            progress({
+              completedFiles: ++completedFiles,
+              totalFiles: files.length,
+            });
+          }
+          await writeFile(
+            path.join(staging, "manifest.json"),
+            JSON.stringify(release.manifest),
+          );
+          // Replace corrupt entries only after the complete replacement has been verified.
+          if (!(await verifyLocal(directory, release.manifest))) {
+            await rm(directory, { recursive: true, force: true });
+          }
+          try {
+            await rename(staging, directory);
+          } catch (error) {
+            if (
+              !["EEXIST", "ENOTEMPTY"].includes(error.code) ||
+              !(await verifyLocal(directory, release.manifest))
+            ) {
+              throw error;
+            }
+          }
+          updated = true;
+        } finally {
+          await rm(staging, { recursive: true, force: true });
+        }
+      },
+      { completedFiles: 0, totalFiles: files.length },
+    );
   }
-  const temporary = await mkdtemp(path.join(root, ".current-"));
-  try {
-    await writeFile(path.join(temporary, "current.json"), JSON.stringify({ feed: release.feed, releaseId: release.manifest.releaseId, version: release.manifest.version }));
-    await rename(path.join(temporary, "current.json"), path.join(root, "current.json"));
-  } finally { await rm(temporary, { recursive: true, force: true }); }
+  await withProgress(
+    options,
+    "activate",
+    async () => {
+      const temporary = await mkdtemp(path.join(root, ".current-"));
+      try {
+        await writeFile(
+          path.join(temporary, "current.json"),
+          JSON.stringify({
+            feed: release.feed,
+            releaseId: release.manifest.releaseId,
+            version: release.manifest.version,
+          }),
+        );
+        await rename(
+          path.join(temporary, "current.json"),
+          path.join(root, "current.json"),
+        );
+      } finally {
+        await rm(temporary, { recursive: true, force: true });
+      }
+    },
+    { updated },
+  );
   return result(root, release, { updated, manifest: release.manifest });
 }
 export async function referencePath(options = {}) {
-  const root = cacheRoot(options), state = await current(root);
-  if (!state || !/^[a-f0-9]{64}$/.test(state.releaseId)) throw new Error("No verified local resources; run plasmickit references update");
+  const root = cacheRoot(options),
+    state = await current(root);
+  if (!state || !/^[a-f0-9]{64}$/.test(state.releaseId)) {
+    throw new Error(
+      "No verified local resources; run plasmickit references update",
+    );
+  }
   const directory = path.join(root, "releases", state.releaseId);
-  const manifest = validateManifest(JSON.parse(await readFile(path.join(directory, "manifest.json"), "utf8")));
-  if (manifest.releaseId !== state.releaseId || !await verifyLocal(directory, manifest)) throw new Error("Local resources are corrupt; run plasmickit references update");
-  return result(root, { manifest, cliUrl: artifactUrl(feedUrl(state.feed), manifest, "cli") }, { freshness: "unchecked" });
+  const manifest = validateManifest(
+    JSON.parse(await readFile(path.join(directory, "manifest.json"), "utf8")),
+  );
+  if (
+    manifest.releaseId !== state.releaseId ||
+    !(await checkCache(directory, manifest, options))
+  ) {
+    throw new Error(
+      "Local resources are corrupt; run plasmickit references update",
+    );
+  }
+  return result(
+    root,
+    { manifest, cliUrl: artifactUrl(feedUrl(state.feed), manifest, "cli") },
+    { freshness: "unchecked" },
+  );
 }
 export async function resolveContext(mode, options = {}) {
-  if (!Object.hasOwn(MODE_REFERENCES, mode)) throw new Error("--mode must be inspect, prototype or codegen");
+  if (!Object.hasOwn(MODE_REFERENCES, mode)) {
+    throw new Error("--mode must be inspect, prototype or codegen");
+  }
   const { manifest, ...resources } = await updateReferences(options);
-  const references = [manifest.entrypoints.guide, "references/desktop-mcp.md", manifest.entrypoints[mode], ...MODE_REFERENCES[mode]];
-  return { ...resources, mode, mustRead: references.map((reference) => path.join(resources.resourceRoot, reference)) };
+  return withProgress(options, "workflow", (progress) => {
+    const references = [
+      manifest.entrypoints.guide,
+      "references/desktop-mcp.md",
+      manifest.entrypoints[mode],
+      ...MODE_REFERENCES[mode],
+    ];
+    const mustRead = references.map((reference) =>
+      path.join(resources.resourceRoot, reference),
+    );
+    progress({ mode, mustRead });
+    return { ...resources, mode, mustRead };
+  });
 }