sdtk-design-kit 0.3.1 → 0.4.0

package/src/index.js

@@ -4,6 +4,8 @@ const { cmdBrief } = require("./commands/brief");
 const { cmdHandoff } = require("./commands/handoff");
 const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
+const { cmdPreview } = require("./commands/preview");
+const { cmdStyles } = require("./commands/styles");
 const { cmdPrototype } = require("./commands/prototype");
 const { cmdReview } = require("./commands/review");
 const { cmdScreens } = require("./commands/screens");
@@ -71,6 +73,12 @@ async function run(argv) {
   if (command === "prototype") {
     return cmdPrototype(args);
   }
+  if (command === "preview") {
+    return cmdPreview(args);
+  }
+  if (command === "styles") {
+    return cmdStyles(args);
+  }
   if (command === "start") {
     return cmdStart(args);
   }

package/src/lib/design-server.js

@@ -0,0 +1,437 @@
+"use strict";
+
+// BK-275 — SDTK-DESIGN Preview Studio local server.
+// Fork-minimal, dependency-free static server (Node stdlib only). Modeled on the
+// sdtk-wiki viewer runner pattern but stripped to: static-serve the prototype
+// directory, serve the single-file studio at "/" and "/studio", and accept ONE
+// POST endpoint (/api/feedback) that writes a scoped feedback artifact to a
+// local file. It NEVER shells out to an agent (manual-apply boundary, BK-275 D3).
+
+const fs = require("fs");
+const http = require("http");
+const net = require("net");
+const path = require("path");
+const { describeDesignPaths, isPathInsideOrEqual } = require("./design-paths");
+
+const JSON_HEADERS = {
+  "Content-Type": "application/json; charset=utf-8",
+  "Cache-Control": "no-cache",
+};
+
+const MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".md": "text/plain; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+const MAX_BODY_BYTES = 2 * 1024 * 1024; // 2 MB cap for a feedback batch.
+const HEALTH_CHECK_RETRIES = 20;
+const HEALTH_CHECK_INTERVAL_MS = 150;
+
+const HARD_SCOPE_PREAMBLE =
+  "Hard scope: change ONLY the elements identified below by screen / selector / stable-id / position. " +
+  "Do NOT modify sibling screens, parent layout, global CSS, design tokens, or unrelated rules even if you " +
+  "notice issues there — surface those as a follow-up note instead of editing them. If a request cannot be " +
+  "satisfied without touching outside this scope, ask the user before proceeding.";
+
+function isPortOpen(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host, port, timeout: 500 });
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => resolve(false));
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+async function findFreePort(host, startPort) {
+  for (let p = startPort; p < startPort + 20; p += 1) {
+    const busy = await isPortOpen(host, p);
+    if (!busy) return p;
+  }
+  throw new Error(
+    `Could not find a free port in range ${startPort}-${startPort + 19}. ` +
+      "Stop unused preview servers or pass a different --port."
+  );
+}
+
+async function waitForServer(host, port) {
+  for (let i = 0; i < HEALTH_CHECK_RETRIES; i += 1) {
+    const ok = await isPortOpen(host, port);
+    if (ok) return;
+    await new Promise((r) => setTimeout(r, HEALTH_CHECK_INTERVAL_MS));
+  }
+  throw new Error(`SDTK-DESIGN preview server did not start on http://${host}:${port}`);
+}
+
+function feedbackStamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return (
+    `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+    `T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+  );
+}
+
+function trimText(value, max) {
+  const text = String(value == null ? "" : value).replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text;
+}
+
+function normalizePosition(input) {
+  const finite = (v) => (Number.isFinite(v) ? Math.round(v) : 0);
+  const pos = input || {};
+  return { x: finite(pos.x), y: finite(pos.y), width: finite(pos.width), height: finite(pos.height) };
+}
+
+function formatComputedStyle(style) {
+  if (!style || typeof style !== "object") return "";
+  return Object.keys(style)
+    .map((key) => {
+      const value = style[key];
+      return value ? `${key}: ${trimText(value, 80)}` : null;
+    })
+    .filter(Boolean)
+    .join("; ");
+}
+
+function renderTargetLines(target, indent = "") {
+  const t = target || {};
+  const pos = normalizePosition(t.position);
+  const lines = [
+    `${indent}selector: ${trimText(t.selector, 200) || "(none)"}`,
+    `${indent}label: ${trimText(t.label, 120) || "(unlabeled)"}`,
+    `${indent}position: x${pos.x} y${pos.y} ${pos.width}x${pos.height}`,
+    `${indent}currentText: ${trimText(t.currentText, 160) || "(empty)"}`,
+    `${indent}htmlHint: ${trimText(t.htmlHint, 200) || "(none)"}`,
+    `${indent}computedStyle: ${formatComputedStyle(t.computedStyle) || "(none)"}`,
+  ];
+  return lines;
+}
+
+// Pure, exported — the unit-test target. Ports the shape of Open Design's
+// comments.ts#renderCommentAttachmentContext into SDTK screen/file vocabulary.
+function compileFeedbackMarkdown(marks, options = {}) {
+  const list = Array.isArray(marks) ? marks : [];
+  const generatedAt = options.generatedAt || new Date().toISOString();
+  const manifestRelPath = options.manifestRelPath || "docs/design/prototype/.manifest.json";
+
+  const out = [];
+  out.push("---");
+  out.push("schema: sdtk.design.feedback.v1");
+  out.push(`generatedAt: ${generatedAt}`);
+  out.push(`prototypeManifest: ${manifestRelPath}`);
+  out.push(`markCount: ${list.length}`);
+  out.push("---");
+  out.push("");
+  out.push("<attached-preview-comments>");
+  out.push(HARD_SCOPE_PREAMBLE);
+
+  list.forEach((mark, index) => {
+    const rawKind = mark && mark.kind;
+    const kind = rawKind === "pod" ? "pod" : rawKind === "token" ? "token" : "element";
+
+    // Token marks are GLOBAL design-token changes (not anchored to one screen):
+    // render the token name/old/new + scope instead of an element descriptor.
+    if (kind === "token") {
+      const tokenName = trimText(mark && mark.token, 120) || `token-${index + 1}`;
+      out.push("");
+      out.push(`${index + 1}. ${tokenName}`);
+      out.push(`   targetKind: token`);
+      out.push(`   scope: ${trimText(mark && mark.scope, 40) || "global"}`);
+      out.push(`   token: ${tokenName}`);
+      out.push(`   oldValue: ${trimText(mark && mark.oldValue, 120) || "(unknown)"}`);
+      out.push(`   newValue: ${trimText(mark && mark.newValue, 120) || "(unset)"}`);
+      const tNote = trimText(mark && mark.note, 600);
+      out.push(`   comment: ${tNote || "(no note — apply the token change above)"}`);
+      return;
+    }
+
+    const screenId = trimText(mark && mark.screenId, 120) || "(unknown-screen)";
+    const stableId = trimText(mark && (mark.target && mark.target.stableId), 200) ||
+      trimText(mark && mark.stableId, 200) || `mark-${index + 1}`;
+    out.push("");
+    out.push(`${index + 1}. ${stableId}`);
+    out.push(`   targetKind: ${kind}`);
+    out.push(`   screen: ${screenId}  (file: docs/design/prototype/screens/${screenId}.html)`);
+    if (kind === "pod") {
+      const members = Array.isArray(mark.members) ? mark.members : [];
+      out.push(`   memberCount: ${members.length}`);
+      members.slice(0, 12).forEach((member, mi) => {
+        const mStable = trimText(member && member.stableId, 200) || `member-${mi + 1}`;
+        out.push(`   member.${mi + 1}: ${mStable}`);
+        renderTargetLines(member, "     ").forEach((line) => out.push(line));
+      });
+    } else {
+      renderTargetLines(mark && mark.target, "   ").forEach((line) => out.push(line));
+    }
+    const note = trimText(mark && mark.note, 600);
+    out.push(`   comment: ${note || "(no note — see target)"}`);
+  });
+
+  out.push("</attached-preview-comments>");
+  out.push("");
+  return out.join("\n");
+}
+
+// Parse the optional `sdtk:` block from a SKILL.md YAML front-matter. Tolerant
+// by contract: returns {} on anything unexpected (never throws). Supports the
+// documented shape only — preview.entry, parameters (inline-object list items),
+// capabilities_required (inline [list]). A full YAML parser is intentionally
+// NOT a dependency.
+function parseInlineObject(line) {
+  // "- { name: accent, type: color, min: 0, max: 24 }" -> { name, type, min, max }
+  // Strips from the last "}" so a trailing YAML comment ("} # note") is ignored.
+  // NOTE: values must be comma-free scalars (the schema only uses name/type/min/max).
+  const body = line.replace(/^\s*-\s*\{/, "").replace(/\}[^}]*$/, "");
+  const obj = {};
+  body.split(",").forEach((pair) => {
+    const idx = pair.indexOf(":");
+    if (idx === -1) return;
+    const key = pair.slice(0, idx).trim();
+    let value = pair.slice(idx + 1).trim().replace(/^['"]|['"]$/g, "");
+    if (!key) return;
+    if ((key === "min" || key === "max") && value !== "" && Number.isFinite(Number(value))) {
+      value = Number(value);
+    }
+    obj[key] = value;
+  });
+  return obj;
+}
+
+function parseSkillMeta(skillMdText) {
+  try {
+    // Strip a leading UTF-8 BOM (editors add it; fs 'utf-8' does not remove it).
+    const text = String(skillMdText || "").replace(/^\uFEFF/, "");
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!fm) return {};
+    const lines = fm[1].split(/\r?\n/);
+    const startIdx = lines.findIndex((l) => /^sdtk:\s*$/.test(l));
+    if (startIdx === -1) return {};
+    const block = [];
+    for (let i = startIdx + 1; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.trim() === "") continue;
+      if (/^\s/.test(line)) block.push(line);
+      else break; // dedented back to top level → end of sdtk block
+    }
+    const meta = {};
+    const parameters = [];
+    let inParameters = false;
+    for (const line of block) {
+      const trimmed = line.trim();
+      const indent = line.length - line.replace(/^\s+/, "").length;
+      if (/^preview:\s*$/.test(trimmed)) { inParameters = false; continue; }
+      const entryMatch = /^entry:\s*(.+)$/.exec(trimmed);
+      if (entryMatch) {
+        meta.preview = meta.preview || {};
+        meta.preview.entry = entryMatch[1].trim().replace(/^['"]|['"]$/g, "");
+        continue;
+      }
+      if (/^parameters:\s*$/.test(trimmed)) { inParameters = true; continue; }
+      const capsMatch = /^capabilities_required:\s*\[(.*)\]\s*$/.exec(trimmed);
+      if (capsMatch) {
+        meta.capabilitiesRequired = capsMatch[1]
+          .split(",").map((c) => c.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+        inParameters = false;
+        continue;
+      }
+      if (inParameters && /^-\s*\{.*\}\s*(#.*)?$/.test(trimmed) && indent >= 4) {
+        const obj = parseInlineObject(line);
+        if (obj.name) parameters.push(obj);
+        continue;
+      }
+      if (trimmed && !/^-/.test(trimmed) && indent <= 2) inParameters = false;
+    }
+    if (parameters.length) meta.parameters = parameters;
+    return meta;
+  } catch (_) {
+    return {};
+  }
+}
+
+function serveStatic(req, res, paths) {
+  let urlPath;
+  try {
+    urlPath = decodeURIComponent((req.url || "/").split("?")[0]);
+  } catch (_) {
+    // Malformed percent-encoding must not crash the server.
+    res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Bad request");
+    return;
+  }
+  const rel = urlPath.replace(/^\/+/, "");
+  const candidate = path.join(paths.prototypePath, rel);
+  if (!isPathInsideOrEqual(candidate, paths.prototypePath)) {
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+    return;
+  }
+  fs.stat(candidate, (err, stat) => {
+    if (err || !stat.isFile()) {
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("Not found");
+      return;
+    }
+    const ext = path.extname(candidate).toLowerCase();
+    res.writeHead(200, { "Content-Type": MIME_TYPES[ext] || "application/octet-stream", "Cache-Control": "no-cache" });
+    fs.createReadStream(candidate).pipe(res);
+  });
+}
+
+function handleFeedbackPost(req, res, paths) {
+  let body = "";
+  let aborted = false;
+  req.on("data", (chunk) => {
+    if (aborted) return;
+    body += chunk;
+    if (body.length > MAX_BODY_BYTES) {
+      aborted = true;
+      res.writeHead(413, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "Feedback body too large." }));
+      req.destroy();
+    }
+  });
+  req.on("end", () => {
+    if (aborted) return;
+    let payload;
+    try {
+      payload = body ? JSON.parse(body) : {};
+    } catch (_) {
+      res.writeHead(400, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "Invalid JSON body." }));
+      return;
+    }
+    const marks = Array.isArray(payload.marks) ? payload.marks : [];
+    if (marks.length === 0) {
+      res.writeHead(400, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "No marks to send." }));
+      return;
+    }
+    const generatedAt = new Date();
+    const markdown = compileFeedbackMarkdown(marks, {
+      generatedAt: generatedAt.toISOString(),
+      manifestRelPath: "docs/design/prototype/.manifest.json",
+    });
+    const feedbackDir = path.join(paths.designDocsPath, "feedback");
+    const relPath = `docs/design/feedback/DESIGN_FEEDBACK_${feedbackStamp(generatedAt)}.md`;
+    const outPath = path.join(paths.projectPath, relPath);
+    if (!isPathInsideOrEqual(outPath, paths.designDocsPath)) {
+      res.writeHead(400, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "Refusing to write outside docs/design." }));
+      return;
+    }
+    try {
+      fs.mkdirSync(feedbackDir, { recursive: true });
+      fs.writeFileSync(outPath, `${markdown}`, "utf-8");
+    } catch (err) {
+      res.writeHead(500, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: `Could not write feedback: ${err.message}` }));
+      return;
+    }
+    res.writeHead(200, JSON_HEADERS);
+    res.end(JSON.stringify({ ok: true, path: relPath }));
+  });
+}
+
+function loadSkillMeta(skillMetaPath) {
+  if (!skillMetaPath) return {};
+  try {
+    return parseSkillMeta(fs.readFileSync(skillMetaPath, "utf-8"));
+  } catch (_) {
+    // Missing/unreadable SKILL.md must not break the studio — fall back to {}.
+    return {};
+  }
+}
+
+function startDesignServer({ host = "127.0.0.1", port, projectPath, studioHtml, skillMetaPath, styles, defaultStyle }) {
+  const paths = describeDesignPaths(projectPath);
+  const styleCatalog = Array.isArray(styles) ? styles : [];
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const method = (req.method || "GET").toUpperCase();
+      const pathOnly = (req.url || "/").split("?")[0];
+
+      if (pathOnly === "/" || pathOnly === "/studio" || pathOnly === "/studio/") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+        res.end(studioHtml);
+        return;
+      }
+      if (pathOnly === "/api/health") {
+        res.writeHead(200, JSON_HEADERS);
+        res.end(JSON.stringify({ ok: true, projectPath: paths.projectPath }));
+        return;
+      }
+      if (pathOnly === "/api/styles") {
+        if (method !== "GET") {
+          res.writeHead(405, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: "Method not allowed." }));
+          return;
+        }
+        // Read-only style catalog for the visual gallery (display-safe fields only).
+        res.writeHead(200, JSON_HEADERS);
+        res.end(JSON.stringify({
+          ok: true,
+          defaultStyle: defaultStyle || (styleCatalog.length ? styleCatalog[0].name : null),
+          styles: styleCatalog,
+        }));
+        return;
+      }
+      if (pathOnly === "/api/skill-meta") {
+        if (method !== "GET") {
+          res.writeHead(405, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: "Method not allowed." }));
+          return;
+        }
+        // Read-only; tolerant — never 500 on a malformed/absent SKILL.md.
+        res.writeHead(200, JSON_HEADERS);
+        res.end(JSON.stringify({ ok: true, sdtk: loadSkillMeta(skillMetaPath) }));
+        return;
+      }
+      if (pathOnly === "/api/feedback") {
+        if (method !== "POST") {
+          res.writeHead(405, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: "Method not allowed." }));
+          return;
+        }
+        handleFeedbackPost(req, res, paths);
+        return;
+      }
+      serveStatic(req, res, paths);
+    });
+
+    server.on("error", reject);
+    server.listen(port, host, () => {
+      resolve({ server, port, url: `http://${host}:${port}/` });
+    });
+  });
+}
+
+module.exports = {
+  HARD_SCOPE_PREAMBLE,
+  MAX_BODY_BYTES,
+  compileFeedbackMarkdown,
+  feedbackStamp,
+  findFreePort,
+  isPortOpen,
+  parseSkillMeta,
+  startDesignServer,
+  waitForServer,
+};

package/src/lib/runtime-skills.js

@@ -0,0 +1,46 @@
+"use strict";
+
+// Runtime/scope → skills directory resolver for SDTK-DESIGN.
+//
+// Mirrors the convention used by the runtime-aware kits (sdtk-spec/ops/code,
+// see their src/lib/scope.js): claude installs skills under `.claude/skills`,
+// codex under `.codex/skills` (honoring CODEX_HOME for the user/global scope).
+// Each kit is an independent npm package, so this small resolver is duplicated
+// rather than imported across package boundaries.
+
+const path = require("path");
+const os = require("os");
+
+const VALID_RUNTIMES = ["claude", "codex"];
+const VALID_SCOPES = ["project", "user"];
+
+// Claude defaults to project-local; Codex defaults to user/global.
+function defaultScope(runtime) {
+  return runtime === "claude" ? "project" : "user";
+}
+
+function resolveCodexHome(scope, projectPath) {
+  if (scope === "project") {
+    return path.join(projectPath || process.cwd(), ".codex");
+  }
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
+
+// Absolute skills directory for the given runtime/scope/project root.
+function resolveSkillsDir(runtime, scope, projectPath) {
+  if (runtime === "claude") {
+    if (scope === "user") {
+      return path.join(os.homedir(), ".claude", "skills");
+    }
+    return path.join(projectPath || process.cwd(), ".claude", "skills");
+  }
+  return path.join(resolveCodexHome(scope, projectPath), "skills");
+}
+
+module.exports = {
+  VALID_RUNTIMES,
+  VALID_SCOPES,
+  defaultScope,
+  resolveCodexHome,
+  resolveSkillsDir,
+};