@plasmickit/cli 0.4.0 → 0.5.10

package/package.json

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

package/skill/plasmic/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plasmic
 compatibility: Requires Node.js >=22.12, Python >=3.9 available as python3, and signed-in Plasmic Desktop MCP for design inspection or editing.
-description: Inspect self-hosted Plasmic pages and templates, create or revise editable Plasmic prototypes, and implement native React code from Plasmic designs. Use for Plasmic Studio/Desktop MCP work such as 原型设计, 后台页面原型 (list/form/detail pages), 按需求或线框/设计稿生成页面, 解读模板或页面, and 根据 Plasmic 设计生成代码. Not for generic React pages without a Plasmic design, or for developing the Plasmic platform itself.
+description: Create, revise and review editable UI prototypes in Plasmic (原型设计/修改/验收), and generate, repair or verify their application code (代码生成/修复/还原验收). Use for prototype design when no other tool is specified, explicit Plasmic work, and follow-ups in established Plasmic design/code context. Excludes unrelated application coding and Plasmic platform development.
 ---
 
 # Plasmic
@@ -10,19 +10,27 @@ This is the entrypoint for resolving current resources and selecting a workflow.
 
 ## Resolve the workflow
 
-Choose `inspect` for read-only explanation/review, `prototype` for editable design creation or revision, or `codegen` for native application implementation.
+Choose by the task's artifact and intent, not whether it is new work or uses MCP:
+
+- `inspect`: explain or review the design/model itself without changing it.
+- `prototype`: create, revise or repair an editable design and verify the resulting prototype.
+- `codegen`: generate, update, repair or review application code against a Plasmic design, including read-only implementation acceptance.
+
+For an editable prototype request with no chosen tool or existing design source, use Plasmic; honor another explicitly selected tool or established source. Follow-up work keeps its design/code context without repeating the skill name. Switch workflows when the target changes; read-only code review still uses codegen. Review does not authorize repairs. If the intended artifact is unclear, clarify it rather than choosing an editor or codebase by keyword alone.
 
 If this skill contains `local-source.json`, read its absolute `resolver` path and run `node RESOLVER_PATH --mode MODE`. This selects current local development resources. A missing resolver/resource is an error; do not fall back to published or cached resources.
 
 Otherwise run the matching published command:
 
 ```sh
-npx -y @plasmickit/cli@latest context resolve --mode inspect
-npx -y @plasmickit/cli@latest context resolve --mode prototype
-npx -y @plasmickit/cli@latest context resolve --mode codegen
+npx -y --prefer-online @plasmickit/cli@latest context resolve --mode inspect
+npx -y --prefer-online @plasmickit/cli@latest context resolve --mode prototype
+npx -y --prefer-online @plasmickit/cli@latest context resolve --mode codegen
 ```
 
-Read every returned `mustRead` file, starting with `referencePath`. Resolve linked documents from the returned `resourceRoot`; follow the workflow's scenario-specific reading and evidence requirements. Resource readiness does not mean the documents have been read. For a task spanning modes, resolve and read each workflow before its work begins.
+Published `context resolve` first synchronizes existing installed skill entries from its CLI bundle, independently of resource updates. Local-source and symlinked entries are preserved. Report `skillUpdate` failures separately; they do not invalidate usable resources. Updated discovery instructions apply when the client reloads skills, not necessarily in this conversation.
+
+Before work in a mode, resolve its resources and read every returned `mustRead` file, starting with `referencePath`; follow relevant links from `resourceRoot`. Within the same task, reuse known, already-read resources and retain pending checks; do not resolve again just because a new message arrived. Resolve/read a newly required mode or recover missing resource context before dependent work; reread affected design inputs when they change. Resource readiness or document reading alone does not establish workflow completion.
 
 Both resolvers verify that Python 3.9+ is available as `python3` for reference readers and gates. The published resolver also checks the NAS release manifest and verifies resource hashes. Stop dependent work on failure; do not silently use stale references. If it requires a newer CLI before npm has that version, install its returned `cliUrl` and rerun. Relay meaningful preparation progress from stderr; stdout contains the result. Report local versus published resources accurately.
 
@@ -40,7 +48,7 @@ Select components before composing markup. Discover existing business components
 
 For admin prototypes, read `references/admin-templates.md` and its catalog, inspect applicable live templates, then adapt the selected composition to the requirement. Read the relevant component and composition references before using them. A template or component must fit the current requirement and the project's actual library.
 
-Use the selected workflow for source interpretation, project selection, editing and verification. Keep plans and acceptance evidence outside the business UI. Inspect is read-only; prototype mutations require edit permission. Codegen uses the target application's architecture and codegen workflow; an explicit official Plasmic CLI request follows the guide's official-CLI reference.
+Keep plans and acceptance evidence outside the business UI. Prototype mutations require edit permission. Codegen follows the target application's architecture; an explicit official Plasmic CLI request follows the guide's official-CLI reference.
 
 For prototype work, follow the workflow's execution-stage table. Derive observable acceptance cases from the current requirements before generation, prepare the current Page's detailed inputs, and retain actual gate/runtime results at each stage. Use existing preparation and verification commands; declarations, tool success and screenshots alone do not establish business acceptance.
 

package/src/index.mjs

@@ -4,7 +4,7 @@ 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 { CLI_VERSION, MODE_REFERENCES } from "./protocol.mjs";
 import {
   checkCliVersion,
   checkReferences,
@@ -66,7 +66,17 @@ export async function main(argv) {
   } else if (command === "references" && action === "path") {
     output = await referencePath(values);
   } else if (command === "context" && action === "resolve") {
-    output = await resolveContext(values.mode, values);
+    if (!Object.hasOwn(MODE_REFERENCES, values.mode)) throw new Error("--mode must be inspect, prototype or codegen");
+    let skillUpdate;
+    try { skillUpdate = await installSkill({ existingOnly: true }); }
+    catch (error) { skillUpdate = { ok: false, error: error.message, installations: [] }; }
+    for (const entry of skillUpdate.installations) {
+      if (entry.status === "updated") process.stderr.write(`✓ Skill 入口已更新：${entry.skillPath}；客户端重新加载技能后采用新入口\n`);
+      if (entry.status === "failed") process.stderr.write(`! Skill 入口更新失败：${entry.skillPath}：${entry.error}\n`);
+    }
+    if (skillUpdate.error) process.stderr.write(`! Skill 入口更新失败：${skillUpdate.error}\n`);
+    try { output = { ...await resolveContext(values.mode, values), skillUpdate }; }
+    catch (error) { error.skillUpdate = skillUpdate; throw error; }
   } else {
     throw new Error(`Unknown command: ${command} ${action}`);
   }
@@ -85,6 +95,7 @@ if (
         ok: false,
         error: error.message,
         ...(error.stage ? { stage: error.stage } : {}),
+        ...(error.skillUpdate ? { skillUpdate: error.skillUpdate } : {}),
         ...(error.cliUrl
           ? {
               cliUrl: error.cliUrl,

package/src/skill.mjs

@@ -1,7 +1,59 @@
-import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { detectInstalledAgents } from "./agents.mjs";
+import { CLI_VERSION, compareVersions } from "./protocol.mjs";
+
+const versionMarker = /^<!-- plasmickit-cli-version: (.+) -->$/m;
+
+async function optionalStat(filename) {
+  try { return await lstat(filename); }
+  catch (error) { if (error.code === "ENOENT") return undefined; throw error; }
+}
+
+async function skipReason(target, existingOnly) {
+  if (await optionalStat(path.join(target, "local-source.json"))) return "local-source";
+  const file = await optionalStat(path.join(target, "SKILL.md"));
+  if ((await optionalStat(target))?.isSymbolicLink() || file?.isSymbolicLink()) return "symlink";
+  if (existingOnly && !file) return "not-installed";
+}
+
+async function writeSkill(destination, content, existingOnly) {
+  const { target, skillPath } = destination;
+  const skipped = await skipReason(target, existingOnly);
+  if (skipped) return { status: "skipped", reason: skipped };
+  if (!existingOnly) await mkdir(target, { recursive: true });
+  const lock = path.join(target, ".plasmickit-skill-lock");
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    try { await mkdir(lock); break; }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) throw new Error(`Skill update still locked: ${lock}. Retry after the other updater finishes; remove this lock only if no updater is running.`);
+      await delay(50);
+    }
+  }
+  try {
+    // Recheck under the shared directory lock: another CLI may have just updated it.
+    const skipped = await skipReason(target, existingOnly);
+    if (skipped) return { status: "skipped", reason: skipped };
+    let previous;
+    try { previous = await readFile(skillPath, "utf8"); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    const installedVersion = previous?.match(versionMarker)?.[1];
+    if (installedVersion && compareVersions(installedVersion, CLI_VERSION) > 0) {
+      return { status: "skipped", reason: "newer-installed", installedVersion };
+    }
+    if (previous === content) return { status: "unchanged" };
+    const temporary = path.join(target, `.SKILL-${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, content, { flag: "wx" });
+      await rename(temporary, skillPath);
+    } finally { await rm(temporary, { force: true }); }
+    return { status: previous === undefined ? "installed" : "updated" };
+  } finally { await rm(lock, { recursive: true, force: true }); }
+}
 
 async function physicalPath(filename) {
   try { return await realpath(filename); }
@@ -12,10 +64,12 @@ async function physicalPath(filename) {
   }
 }
 
-export async function installSkill({ dryRun = false, ...options } = {}) {
+export async function installSkill({ dryRun = false, existingOnly = false, ...options } = {}) {
   const detected = await detectInstalledAgents(options);
-  if (!detected.length) return { ok: false, mode: "bootstrap", detected, installations: [], error: "No supported local Agent CLI or app detected. Install or initialize a supported client, then rerun skill install." };
-  const content = await readFile(new URL("../skill/plasmic/SKILL.md", import.meta.url), "utf8");
+  if (!detected.length && !existingOnly) return { ok: false, mode: "bootstrap", detected, installations: [], error: "No supported local Agent CLI or app detected. Install or initialize a supported client, then rerun skill install." };
+  const bundled = await readFile(new URL("../skill/plasmic/SKILL.md", import.meta.url), "utf8");
+  // Keep version and instructions in one atomic replacement, without a sidecar file.
+  const content = `${bundled.trimEnd()}\n\n<!-- plasmickit-cli-version: ${CLI_VERSION} -->\n`;
   const destinations = new Map();
   const installations = [];
   for (const agent of detected) {
@@ -32,18 +86,8 @@ export async function installSkill({ dryRun = false, ...options } = {}) {
   for (const destination of destinations.values()) {
     if (dryRun) { installations.push({ ...destination, status: "planned" }); continue; }
     try {
-      let previous;
-      try { previous = await readFile(destination.skillPath, "utf8"); }
-      catch (error) { if (error.code !== "ENOENT") throw error; }
-      if (previous === content) { installations.push({ ...destination, status: "unchanged" }); continue; }
-      await mkdir(destination.target, { recursive: true });
-      const temporary = path.join(destination.target, `.SKILL-${randomUUID()}.tmp`);
-      try {
-        await writeFile(temporary, content, { flag: "wx" });
-        await rename(temporary, destination.skillPath);
-      } finally { await rm(temporary, { force: true }); }
-      installations.push({ ...destination, status: "installed" });
+      installations.push({ ...destination, ...await writeSkill(destination, content, existingOnly) });
     } catch (error) { installations.push({ ...destination, status: "failed", error: error.message }); }
   }
-  return { ok: installations.every((result) => result.status !== "failed"), mode: "bootstrap", dryRun, detected, installations };
+  return { ok: installations.every((result) => result.status !== "failed"), mode: existingOnly ? "sync" : "bootstrap", cliVersion: CLI_VERSION, dryRun, detected, installations };
 }