justskill-design 0.0.1 → 3.2.0

package/dsh/index.js

@@ -0,0 +1,354 @@
+/**
+ * dsh/index.js — host half of the justSkill Design plugin.
+ *
+ * Three responsibilities, each deliberately small:
+ *
+ *   1. Register the skill that already lives in this package, so a plugin
+ *      install is equivalent to dropping the directory into a skills root.
+ *   2. Scan registered workspaces for design files. The browser cannot read
+ *      the filesystem, so the picker asks the Host.
+ *   3. Start one canvas service per design file on a loopback port and hand
+ *      the browser its tokenized URL. The canvas itself is unchanged — the
+ *      plugin only decides which file it serves.
+ */
+
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+import { startServer } from "../lib/node/server.mjs";
+import { readDesignFile, scanWorkspace } from "./scan.js";
+import { readSkill } from "./skill.js";
+
+export const name = "justskill-design";
+export const inject = ["skills"];
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CACHE_TTL_MS = 15_000;
+const SCAN_BUDGET_MS = 6_000;
+const WORKSPACE_BUDGET_MS = 2_500;
+const MAX_WORKSPACES = 64;
+const PENDING_TTL_MS = 60_000;
+
+/** Successful JSON response; no store, the panel re-reads deliberately. */
+function ok(value) {
+  return Response.json({ ok: true, value }, {
+    headers: { "cache-control": "no-store" },
+  });
+}
+
+/** Refusal response with a stable code the client can branch on. */
+function fail(status, code, message) {
+  return Response.json({ ok: false, error: { code, message } }, {
+    status,
+    headers: { "cache-control": "no-store" },
+  });
+}
+
+async function readJson(request) {
+  try {
+    const body = await request.json();
+    return body !== null && typeof body === "object" && !Array.isArray(body) ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Canonicalize one workspace directory; returns null when it is not one. */
+async function canonicalWorkspace(entry) {
+  if (entry === null || typeof entry !== "object") return null;
+  if (typeof entry.path !== "string" || entry.path.trim() === "") return null;
+  if (!isAbsolute(entry.path)) return null;
+  try {
+    const path = await realpath(entry.path);
+    const info = await stat(path);
+    if (!info.isDirectory()) return null;
+    return {
+      id: typeof entry.id === "string" ? entry.id : path,
+      path,
+      title: typeof entry.title === "string" ? entry.title : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One canvas server per design file, owned by the plugin fiber. A second open
+ * for the same file joins the first start instead of racing it.
+ */
+class CanvasPool {
+  #entries = new Map();
+
+  async open(file) {
+    const current = this.#entries.get(file);
+    if (current?.server !== undefined) return current.server;
+    if (current?.starting !== undefined) return current.starting;
+
+    const starting = (async () => {
+      const server = await startServer({
+        file,
+        port: 0,
+        ttlMinutes: 30,
+        open: false,
+      });
+      const entry = { server };
+      this.#entries.set(file, entry);
+      server.closed.then(() => {
+        if (this.#entries.get(file) === entry) this.#entries.delete(file);
+      }, () => {
+        if (this.#entries.get(file) === entry) this.#entries.delete(file);
+      });
+      return server;
+    })();
+
+    this.#entries.set(file, { starting });
+    try {
+      return await starting;
+    } catch (error) {
+      this.#entries.delete(file);
+      throw error;
+    }
+  }
+
+  close(file) {
+    const entry = this.#entries.get(file);
+    this.#entries.delete(file);
+    try {
+      entry?.server?.close("plugin closed the canvas");
+    } catch {
+      /* already closing */
+    }
+  }
+
+  closeAll() {
+    const entries = [...this.#entries.values()];
+    this.#entries.clear();
+    for (const entry of entries) {
+      try {
+        entry.server?.close("plugin disposed");
+      } catch {
+        /* already closing */
+      }
+    }
+  }
+}
+
+export function apply(ctx) {
+  const skill = readSkill(ROOT);
+  ctx.effect(() => ctx.skills.register({
+    ...skill,
+    source: "bundled",
+  }), "justskill-design: skill");
+
+  const pool = new CanvasPool();
+  ctx.effect(() => () => pool.closeAll(), "justskill-design: canvas servers");
+
+  // Session-scoped handoff from the Host tool to the browser watcher. The tool
+  // cannot touch the right-sidebar UI, so it leaves a request the client claims
+  // and clears after the tab is open.
+  const pending = new Map();
+  const purgePending = () => {
+    const now = Date.now();
+    for (const [sessionId, entry] of pending) {
+      if (now - entry.at > PENDING_TTL_MS) pending.delete(sessionId);
+    }
+  };
+
+  const cache = new Map();
+
+  ctx.inject(["connection"], (scope) => {
+    const connection = scope.get("connection");
+    if (connection === undefined || typeof connection.fetch?.register !== "function") {
+      ctx.logger?.warn?.("justskill-design: connection.fetch is unavailable; the workbench Host API stays off");
+      return;
+    }
+
+    const route = (path, handler, label) => {
+      scope.effect(() => connection.fetch.register({
+        path,
+        methods: ["POST"],
+        requestBody: "buffered",
+        fetch: handler,
+      }), label);
+    };
+
+    route("/api/justskill-design/scan", async (request) => {
+      const body = await readJson(request);
+      if (body === null) return fail(400, "bad-request", "body must be a JSON object");
+      if (!Array.isArray(body.workspaces)) return fail(400, "bad-request", "workspaces must be an array");
+      if (body.workspaces.length > MAX_WORKSPACES) {
+        return fail(400, "too-many-workspaces", `at most ${MAX_WORKSPACES} workspaces per scan`);
+      }
+
+      const valid = [];
+      for (const entry of body.workspaces) {
+        const workspace = await canonicalWorkspace(entry);
+        if (workspace !== null) valid.push(workspace);
+      }
+
+      const refresh = body.refresh === true;
+      const deadline = Date.now() + SCAN_BUDGET_MS;
+      const results = [];
+      for (const workspace of valid) {
+        const cached = cache.get(workspace.path);
+        if (!refresh && cached !== undefined && Date.now() - cached.at < CACHE_TTL_MS) {
+          results.push({ ...workspace, ...cached.value, cached: true });
+          continue;
+        }
+        const local = Math.min(Date.now() + WORKSPACE_BUDGET_MS, deadline);
+        const value = await scanWorkspace(workspace, { deadline: local });
+        cache.set(workspace.path, { at: Date.now(), value });
+        results.push({ ...workspace, ...value });
+      }
+
+      return ok({
+        workspaces: results,
+        scannedAt: Date.now(),
+        incomplete: results.some((entry) => entry.incomplete === true),
+      });
+    }, "justskill-design: workspace scan route");
+
+    route("/api/justskill-design/canvas", async (request) => {
+      const body = await readJson(request);
+      if (body === null) return fail(400, "bad-request", "body must be a JSON object");
+      if (typeof body.file !== "string" || body.file.trim() === "") {
+        return fail(400, "bad-request", "file must be a non-empty string");
+      }
+      if (!isAbsolute(body.file)) return fail(400, "bad-request", "file must be absolute");
+
+      let file;
+      try {
+        file = await realpath(body.file);
+      } catch {
+        return fail(404, "file-not-found", `no such file: ${body.file}`);
+      }
+
+      const meta = await readDesignFile(file);
+      if (meta === null) {
+        return fail(422, "not-a-design-file", `${file} has no design-schema marker`);
+      }
+
+      try {
+        const server = await pool.open(file);
+        return ok({ url: server.url, file, port: server.port });
+      } catch (error) {
+        return fail(500, "canvas-start-failed", error instanceof Error ? error.message : String(error));
+      }
+    }, "justskill-design: canvas open route");
+
+    route("/api/justskill-design/canvas/close", async (request) => {
+      const body = await readJson(request);
+      if (body === null) return fail(400, "bad-request", "body must be a JSON object");
+      if (typeof body.file !== "string" || body.file.trim() === "") {
+        return fail(400, "bad-request", "file must be a non-empty string");
+      }
+      let file;
+      try {
+        file = await realpath(body.file);
+      } catch {
+        return ok({ closed: false });
+      }
+      pool.close(file);
+      return ok({ closed: true });
+    }, "justskill-design: canvas close route");
+
+    route("/api/justskill-design/pending", async (request) => {
+      const body = await readJson(request);
+      if (body === null) return fail(400, "bad-request", "body must be a JSON object");
+      if (typeof body.sessionId !== "string" || body.sessionId === "") {
+        return fail(400, "bad-request", "sessionId must be a non-empty string");
+      }
+      purgePending();
+      const entry = pending.get(body.sessionId);
+      return ok({ pending: entry === undefined ? null : { file: entry.file } });
+    }, "justskill-design: pending canvas route");
+
+    route("/api/justskill-design/pending/clear", async (request) => {
+      const body = await readJson(request);
+      if (body === null) return fail(400, "bad-request", "body must be a JSON object");
+      if (typeof body.sessionId !== "string" || body.sessionId === "") {
+        return fail(400, "bad-request", "sessionId must be a non-empty string");
+      }
+      purgePending();
+      const entry = pending.get(body.sessionId);
+      if (entry !== undefined && (typeof body.file !== "string" || body.file === "" || body.file === entry.file)) {
+        pending.delete(body.sessionId);
+      }
+      return ok({ cleared: true });
+    }, "justskill-design: pending canvas clear route");
+  });
+
+  ctx.inject(["tools"], (scope) => {
+    const tools = scope.get("tools");
+    if (tools === undefined || typeof tools.register !== "function") return;
+
+    scope.effect(() => tools.register({
+      name: "justskill_canvas",
+      description:
+        "Open the justSkill design canvas in the DSH right-sidebar Canvas tab. Use this " +
+        "whenever the user asks to open, show or focus the design canvas, and before " +
+        "designing page by page. Never run `node design.mjs serve` in DeepSeek Harness; " +
+        "the canvas is the right-sidebar tab.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          file: {
+            type: "string",
+            description: "Absolute path to the design file. Defaults to design.html in the session workspace.",
+          },
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            requested: { type: "boolean" },
+            file: { type: "string" },
+          },
+          required: ["requested", "file"],
+        },
+        render(_args, value) {
+          return [{ type: "text", text: `justskill_canvas → ${value.file}` }];
+        },
+      },
+      timeoutMs: 15_000,
+      isConcurrencySafe() {
+        return false;
+      },
+      async execute(args, exec) {
+        const agent = exec === undefined ? undefined : exec.agent;
+        const sessionId = agent === undefined ? undefined : agent.id;
+        const cwd = agent === undefined ? undefined : agent.session?.header?.cwd;
+        if (typeof sessionId !== "string" || sessionId === "") {
+          throw new Error("justskill_canvas: no calling session");
+        }
+        if (typeof cwd !== "string" || cwd === "") {
+          throw new Error("justskill_canvas: no session workspace");
+        }
+        const requested = args !== null && typeof args === "object" && typeof args.file === "string"
+          ? args.file
+          : "";
+        const candidate = requested === ""
+          ? resolve(cwd, "design.html")
+          : isAbsolute(requested) ? requested : resolve(cwd, requested);
+        let file;
+        try {
+          file = await realpath(candidate);
+        } catch {
+          throw new Error(`justskill_canvas: no such file: ${candidate}`);
+        }
+        const meta = await readDesignFile(file);
+        if (meta === null) {
+          throw new Error(`justskill_canvas: ${file} has no design-schema marker`);
+        }
+        purgePending();
+        pending.set(sessionId, { file, at: Date.now() });
+        return { requested: true, file };
+      },
+    }), "justskill-design: canvas tool");
+  });
+}

package/dsh/scan.js

@@ -0,0 +1,139 @@
+/**
+ * dsh/scan.js — find justSkill design files inside a workspace.
+ *
+ * A design file is identified by the marker the format already carries:
+ * `<meta name="design-schema" content="...">`. No new marker is introduced and
+ * no filename convention is required, so a file named by the user keeps
+ * working. The scan is deliberately bounded: a workspace can be arbitrary
+ * large, and the workbench is a picker, not an indexer.
+ */
+
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** A design file always carries this meta tag; the format owns the spelling. */
+export const DESIGN_MARKER = /<meta\b[^>]*\bname\s*=\s*["']design-schema["'][^>]*>/i;
+
+/** Directories that never contain user-facing design files. */
+export const SKIP_DIRS = new Set([
+  ".git", ".hg", ".svn", ".idea", ".vscode", ".next", ".nuxt", ".svelte-kit",
+  ".cache", ".turbo", ".parcel-cache", ".venv", ".tox", ".pytest_cache",
+  "node_modules", "bower_components", "dist", "build", "out", "coverage",
+  "vendor", "target", "bin", "obj", "Pods", "DerivedData",
+]);
+
+/** Limits that keep one workspace from stalling the panel. */
+export const LIMITS = {
+  maxDepth: 6,
+  maxFiles: 2000,
+  maxReadBytes: 512 * 1024,
+  headBytes: 8 * 1024,
+  budgetMs: 2500,
+};
+
+const HTML = /\.html?$/i;
+const TITLE = /<title\b[^>]*>([\s\S]*?)<\/title>/i;
+const PAGE = /\bdata-type\s*=\s*["']page["']/g;
+
+/**
+ * Read one candidate file and return its design metadata, or null when it is
+ * not a design file.
+ *
+ * @param {string} file absolute path
+ * @returns {Promise<null | {path: string, uri: string, name: string, title: string | null, pages: number | null, size: number, mtime: number}>}
+ */
+export async function readDesignFile(file) {
+  let info;
+  try {
+    info = await stat(file);
+  } catch {
+    return null;
+  }
+  if (!info.isFile()) return null;
+
+  let text;
+  if (info.size <= LIMITS.maxReadBytes) {
+    try {
+      text = await readFile(file, "utf8");
+    } catch {
+      return null;
+    }
+  } else {
+    let handle;
+    try {
+      handle = await open(file, "r");
+      const buffer = Buffer.alloc(Math.min(LIMITS.headBytes, info.size));
+      await handle.read(buffer, 0, buffer.length, 0);
+      text = buffer.toString("utf8");
+    } catch {
+      return null;
+    } finally {
+      await handle?.close().catch(() => {});
+    }
+  }
+
+  if (!DESIGN_MARKER.test(text)) return null;
+  const title = TITLE.exec(text)?.[1]?.replace(/\s+/g, " ").trim() || null;
+  const pages = info.size <= LIMITS.maxReadBytes ? (text.match(PAGE)?.length ?? 0) : null;
+  return {
+    path: file,
+    uri: pathToFileURL(file).href,
+    name: basename(file),
+    title,
+    pages,
+    size: info.size,
+    mtime: info.mtimeMs,
+  };
+}
+
+/**
+ * Scan one workspace, depth-first, bounded by depth, file count and time.
+ *
+ * @param {{path: string}} workspace canonical workspace directory
+ * @param {{deadline?: number, maxDepth?: number, maxFiles?: number}} [options]
+ * @returns {Promise<{path: string, files: Array<object>, incomplete: boolean}>}
+ */
+export async function scanWorkspace(workspace, options = {}) {
+  const root = workspace.path;
+  const deadline = options.deadline ?? Date.now() + LIMITS.budgetMs;
+  const maxDepth = options.maxDepth ?? LIMITS.maxDepth;
+  const maxFiles = options.maxFiles ?? LIMITS.maxFiles;
+  const files = [];
+  let incomplete = false;
+
+  const expired = () => Date.now() > deadline;
+
+  async function walk(directory, depth) {
+    if (expired() || files.length >= maxFiles) {
+      incomplete = true;
+      return;
+    }
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return; // unreadable directory: skip, never fail the whole panel
+    }
+    for (const entry of entries) {
+      if (expired() || files.length >= maxFiles) {
+        incomplete = true;
+        return;
+      }
+      if (entry.isSymbolicLink()) continue;
+      const file = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (depth >= maxDepth || SKIP_DIRS.has(entry.name)) continue;
+        await walk(file, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !HTML.test(entry.name)) continue;
+      const meta = await readDesignFile(file);
+      if (meta !== null) files.push(meta);
+    }
+  }
+
+  await walk(root, 0);
+  files.sort((left, right) => right.mtime - left.mtime);
+  return { path: root, files, incomplete };
+}

package/dsh/skill.js

@@ -0,0 +1,41 @@
+/**
+ * dsh/skill.js — turn this package's SKILL.md into a DSH skill contribution.
+ *
+ * The skill stays the source of truth: README, CLI, references and the canvas
+ * are all resolved relative to the package root, so a plugin install and a
+ * `~/.agents/skills` symlink see exactly the same files. Only the YAML
+ * frontmatter is removed: DSH expects the Markdown body, not the metadata.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const SKILL_NAME = "justskill-design";
+
+/**
+ * The catalog description DSH shows next to the skill name. DSH truncates the
+ * catalog at 500 characters (dsh-tool-skill), and this stays comfortably under
+ * it while keeping the "what triggers it" part first.
+ */
+export const SKILL_DESCRIPTION =
+  "把产品想法推进到受用户审批的页面设计，再按设计写代码。用于产品想法、功能增删、页面/应用界面设计、改版、调整间距色彩排版、导出设计、导入 .pen 等场景。设计就是一份受校验的 HTML 文件，用户可以在画布上实时审阅和调整。";
+
+/**
+ * Read SKILL.md and return the registration DSH expects.
+ *
+ * @param {string} root package root containing SKILL.md
+ * @returns {{name: string, description: string, content: string, path: string, resourceBase: {kind: "directory", path: string}}}
+ */
+export function readSkill(root) {
+  const file = join(root, "SKILL.md");
+  const raw = readFileSync(file, "utf8");
+  const content = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trimStart();
+  if (content.trim() === "") throw new Error("SKILL.md has no body after its frontmatter");
+  return {
+    name: SKILL_NAME,
+    description: SKILL_DESCRIPTION,
+    content,
+    path: file,
+    resourceBase: { kind: "directory", path: root },
+  };
+}

package/lib/base-css.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/base-css.mjs — the rules a design file states about itself.
+ *
+ * A design file is a standalone HTML document. Inline styles decide the layout,
+ * and three browser defaults decide what those inline styles MEAN:
+ *
+ *   `box-sizing`   is `content-box`, so `width:375px;padding:0 24px` is 423px
+ *                  wide, not 375px.
+ *   `margin`       on `p`, `h1` and the other text tags is not zero, so a
+ *                  one-line label is 16px taller than its author expects.
+ *   SVG geometry   defaults to `fill:black`, so a stroke-based glyph paints as
+ *                  a solid silhouette.
+ *
+ * The rules are deliberately keyed on the element, not on a `data-*` attribute.
+ * A `data-*` selector would be shorter — one rule instead of 28 declarations —
+ * and it would be wrong: `export` drops every design attribute, so a rule keyed
+ * on `data-kind` stops matching in the deliverable and a circle ships as a
+ * square. What a node looks like has to live in the node's own `style`.
+ *
+ * The file cannot leave those to chance and then be read the same way by three
+ * renderers. So the file states them once, and every reader of the file gets the
+ * same answer: the browser, the canvas, and `export`.
+ *
+ * The one exception is `:root{…}` inside a shadow root. `:root` matches no
+ * element there, so the canvas puts the token values on `:host` instead. See
+ * `pageCss` in `lib/render.mjs`.
+ *
+ * Byte fidelity: these rules are text inside a `<style>` block, which is the
+ * page-frame layer. The serializer keeps them as bytes, and the parser does not
+ * read them.
+ */
+
+/** The rules, one per line, in the order they must appear. */
+export const BASE_RULES = [
+  "*,*::before,*::after{box-sizing:border-box}",
+  "*{margin:0}",
+  "img{display:block}",
+  // A built-in glyph carries no `fill` and no `stroke`, so these two live on the
+  // glyph's own `<svg>`: a stroke needs a colour from somewhere, and `color` on
+  // the element is what tints it. `:not([fill])` lets a solid icon opt out.
+  "svg:not([data-fill]) > :not([fill]):not([stroke]){fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}",
+];
+
+/** The base rules as CSS text, ready to sit in front of the token block. */
+export function baseCss(rules = BASE_RULES) {
+  return rules.join("\n");
+}
+
+/**
+ * True when this CSS text already states a box model.
+ *
+ * The check is on `box-sizing`, because that is the rule that changes what a
+ * `width` means. A file that omits it is not broken — it is a file whose widths
+ * are content widths, which is a legitimate thing to write and a bad thing to
+ * write by accident.
+ */
+export function hasBaseRules(cssText) {
+  return /box-sizing\s*:/.test(String(cssText ?? ""));
+}
+
+/** The base rules found in a `<style>` block, or "" when there are none. */
+export function baseRulesOf(cssText) {
+  const text = String(cssText ?? "");
+  if (!hasBaseRules(text)) return "";
+  const lines = [];
+  for (const rule of text.split("\n")) {
+    const trimmed = rule.trim();
+    if (!trimmed || trimmed.startsWith(":root")) continue;
+    if (/^[^{]*\{[^}]*\}$/.test(trimmed)) lines.push(trimmed);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The base rules this CSS text does not state.
+ *
+ * A file written before a rule existed is a file that renders differently from
+ * the format it claims, and the difference is silent: the box model holds, so
+ * nothing looks broken, and one shape or one glyph is simply wrong. So the file
+ * is told which rule it is missing.
+ *
+ * Whitespace and quotes are free: `svg:not([data-fill]) > :not([fill])` with a
+ * space before the brace states the same rule as the canonical line.
+ */
+export function missingBaseRules(cssText) {
+  const text = squash(String(cssText ?? ""));
+  return BASE_RULES.filter((rule) => !text.includes(squash(rule)));
+}
+
+function squash(text) {
+  return text.replace(/\s+/g, "").replace(/["']/g, "");
+}