@plasmickit/cli 0.0.0-stage → 0.0.36

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@plasmickit/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.36",
+  "description": "Plasmic skill bootstrap and NAS workflow resource manager",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shiguang-lab/plasmic.git",
+    "directory": "packages/plasmic-cli"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "plasmickit": "src/index.mjs"
+  },
+  "files": [
+    "src",
+    "skill"
+  ]
+}

package/skill/plasmic/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: plasmic
+description: Design, revise, and verify editable product prototypes in self-hosted Plasmic, or read Plasmic pages and generate native React project code under maintained engineering standards. Use for Plasmic product prototyping and design-to-code development.
+---
+
+# Plasmic
+
+This is a bootstrap skill. Workflows, component guidance and verification scripts live in a versioned resource bundle on the NAS, outside this installed skill.
+
+At the start of each task, choose `prototype` for product design or `codegen` for code generation and integration. Run:
+
+```sh
+npx -y @plasmickit/cli@latest context resolve --mode prototype
+# Or: npx -y @plasmickit/cli@latest context resolve --mode codegen
+```
+
+In `codegen` mode, read page models, component contracts and interactions through Desktop MCP, then implement code in the target project's architecture. Generation follows the returned standards; it does not use `export_code` or the official Plasmic CLI.
+
+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 both modes, resolve and read each mode before its work begins.
+
+The runner uses the latest published Plasmic 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

@@ -0,0 +1,44 @@
+#!/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 { CLI_VERSION } from "./protocol.mjs";
+
+const usage = `plasmickit commands:
+  skill install --target SKILLS_ROOT
+  version check [--feed HTTPS_URL]
+  references check|update|path [--feed HTTPS_URL] [--home CACHE_ROOT]
+  context resolve --mode prototype|codegen [--feed HTTPS_URL] [--home CACHE_ROOT]
+  --version
+`;
+export async function main(argv) {
+  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
+    target: { type: "string" }, 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");
+  let output;
+  if (command === "skill" && action === "install") output = await installSkill(values.target);
+  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}`);
+  process.stdout.write(JSON.stringify({ ok: true, ...output }, null, 2) + "\n");
+}
+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.exitCode = 1;
+  });
+}

package/src/protocol.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { createRequire } from "node:module";
+
+export const DEFAULT_FEED = "https://plasmic.studio.publib.cn/desktop-updates/plasmic";
+export const CLI_VERSION = createRequire(import.meta.url)("../package.json").version;
+export const MIN_CLI_VERSION = "0.0.34";
+export const CODEGEN_REFERENCES = [
+  "references/codegen/page-reading.md",
+  "references/codegen/project-code.md",
+  "references/codegen/interactions.md",
+  "references/codegen/acceptance.md",
+];
+export function compareVersions(a, b) {
+  const parse = (version) => {
+    if (typeof version !== "string" || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)) throw new Error(`Invalid stable version: ${version}`);
+    const parts = version.split(".").map(Number);
+    if (!parts.every(Number.isSafeInteger)) throw new Error(`Invalid stable version: ${version}`);
+    return parts;
+  };
+  const left = parse(a), right = parse(b);
+  const changed = left.findIndex((part, index) => part !== right[index]);
+  return changed === -1 ? 0 : left[changed] > right[changed] ? 1 : -1;
+}
+export const MAX_BYTES = 16 * 1024 * 1024;
+export const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const canonical = (value) => JSON.stringify(value, function (_key, item) {
+  return item && typeof item === "object" && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]])) : item;
+});
+export function releaseId(manifest) {
+  const { releaseId: _id, ...content } = manifest;
+  return sha256(canonical(content));
+}
+export function resourcePath(name) {
+  if (typeof name !== "string" || !/^(references|scripts)\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+\.(md|py|json)$/.test(name)) {
+    throw new Error(`Invalid resource path: ${name}`);
+  }
+  return name;
+}
+export function validateManifest(manifest) {
+  if (!manifest || manifest.schemaVersion !== 1 || !/^\d+\.\d+\.\d+$/.test(manifest.version) ||
+      !/^\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");
+  const files = new Map();
+  if (!Array.isArray(manifest.files) || !manifest.files.length) throw new Error("Empty resource manifest");
+  for (const file of manifest.files) {
+    resourcePath(file.path);
+    if (files.has(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256) || !Number.isSafeInteger(file.size) || file.size < 0 || file.size > MAX_BYTES) {
+      throw new Error("Invalid or duplicate resource entry");
+    }
+    files.set(file.path, file);
+  }
+  for (const mode of ["guide", "prototype", "codegen"]) {
+    const entry = manifest.entrypoints?.[mode];
+    if (!files.has(entry) || !entry.startsWith("references/") || !entry.endsWith(".md")) throw new Error(`Missing ${mode} entrypoint`);
+  }
+  if (!files.has("references/desktop-mcp.md")) throw new Error("Missing Desktop MCP reference");
+  for (const reference of CODEGEN_REFERENCES) {
+    if (!files.has(reference)) throw new Error(`Missing code-generation standard: ${reference}`);
+  }
+  for (const [kind, name] of [["resources", "resources.json.gz"], ["cli", "plasmic-cli.tgz"]]) {
+    const artifact = manifest.artifacts?.[kind];
+    if (!artifact || artifact.file !== name || !/^[a-f0-9]{64}$/.test(artifact.sha256) ||
+        !Number.isSafeInteger(artifact.size) || artifact.size <= 0 || artifact.size > MAX_BYTES) throw new Error(`Invalid ${kind} artifact`);
+  }
+  return manifest;
+}
+export function verifyArtifact(bytes, artifact) {
+  if (bytes.length !== artifact.size || sha256(bytes) !== artifact.sha256) throw new Error(`Artifact checksum mismatch: ${artifact.file}`);
+}
+export function unpackResources(bytes, manifest) {
+  verifyArtifact(bytes, manifest.artifacts.resources);
+  const bundle = JSON.parse(gunzipSync(bytes, { maxOutputLength: MAX_BYTES }).toString("utf8"));
+  if (bundle.schemaVersion !== 1 || !Array.isArray(bundle.files) || bundle.files.length !== manifest.files.length) throw new Error("Resource bundle does not match manifest");
+  const expected = new Map(manifest.files.map((file) => [file.path, file]));
+  for (const file of bundle.files) {
+    resourcePath(file.path);
+    const entry = expected.get(file.path);
+    if (!entry || typeof file.content !== "string" || Buffer.byteLength(file.content) !== entry.size || sha256(file.content) !== entry.sha256) {
+      throw new Error(`Resource checksum mismatch: ${file.path}`);
+    }
+    expected.delete(file.path);
+  }
+  return bundle.files;
+}
+export function feedUrl(value = process.env.PLASMIC_RESOURCE_URL || DEFAULT_FEED) {
+  const url = new URL(value.replace(/\/+$/, "") + "/");
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))) {
+    throw new Error("Resource feed must use HTTPS (HTTP is allowed only for loopback tests)");
+  }
+  if (url.search || url.hash || url.username || url.password) throw new Error("Invalid resource feed URL");
+  return url.href;
+}
+export function artifactUrl(feed, manifest, kind) {
+  return new URL(`releases/${manifest.releaseId}/${manifest.artifacts[kind].file}`, feed).href;
+}
+export function requiresNewCli(minimum, current = CLI_VERSION) {
+  return compareVersions(minimum, current) > 0;
+}

package/src/references.mjs

@@ -0,0 +1,146 @@
+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, CODEGEN_REFERENCES, feedUrl, MAX_BYTES, 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 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");
+    chunks.push(chunk);
+  }
+  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 cliUrl = artifactUrl(feed, manifest, "cli");
+  return { feed, manifest, cliUrl };
+}
+function versionInfo(release) {
+  return {
+    cliVersion: CLI_VERSION,
+    latestCliVersion: release.manifest.version,
+    minCliVersion: release.manifest.minCliVersion,
+    cliUpdateAvailable: requiresNewCli(release.manifest.version),
+    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`);
+    Object.assign(error, versionInfo(release));
+    throw error;
+  }
+}
+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; }
+}
+async function verifyLocal(directory, manifest) {
+  try {
+    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; }
+    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;
+        parent = path.dirname(parent);
+      }
+      const stat = await lstat(target);
+      if (!stat.isFile() || stat.size !== file.size || sha256(await readFile(target)) !== file.sha256) return false;
+    }
+    return true;
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR"].includes(error.code)) return false;
+    throw error;
+  }
+}
+function result(root, release, extra = {}) {
+  const resourceRoot = path.join(root, "releases", release.manifest.releaseId);
+  return {
+    version: release.manifest.version,
+    releaseId: release.manifest.releaseId,
+    resourceRoot,
+    referencePath: path.join(resourceRoot, release.manifest.entrypoints.guide),
+    ...versionInfo(release),
+    ...extra,
+  };
+}
+export async function checkReferences(options = {}) {
+  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 });
+}
+export async function updateReferences(options = {}) {
+  const root = cacheRoot(options), release = await latest(options);
+  requireCompatibleCli(release);
+  await mkdir(root, { recursive: true });
+  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;
+  }
+  try { return await installResources(root, release); }
+  finally { await rm(lock, { recursive: true, force: true }); }
+}
+async function installResources(root, release) {
+  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 }); }
+  }
+  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 }); }
+  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 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" });
+}
+export async function resolveContext(mode, options = {}) {
+  if (!["prototype", "codegen"].includes(mode)) throw new Error("--mode must be prototype or codegen");
+  const { manifest, ...resources } = await updateReferences(options);
+  const references = [manifest.entrypoints.guide, "references/desktop-mcp.md", manifest.entrypoints[mode], ...(mode === "codegen" ? CODEGEN_REFERENCES : [])];
+  return { ...resources, mode, mustRead: references.map((reference) => path.join(resources.resourceRoot, reference)) };
+}

package/src/skill.mjs

@@ -0,0 +1,11 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function installSkill(targetRoot) {
+  if (!targetRoot) throw new Error("skill install requires --target SKILLS_ROOT");
+  const target = path.resolve(targetRoot, "plasmic");
+  const content = await readFile(new URL("../skill/plasmic/SKILL.md", import.meta.url), "utf8");
+  await mkdir(target, { recursive: true });
+  await writeFile(path.join(target, "SKILL.md"), content);
+  return { target, skillPath: path.join(target, "SKILL.md"), mode: "bootstrap" };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.