sdtk-design-kit 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 `sdtk-design-kit` is the public CLI package for SDTK-DESIGN.
 
-Package version in this source snapshot: `0.4.0`
+Package version in this source snapshot: `0.5.0`
 CLI command: `sdtk-design`
 
 SDTK-DESIGN is a local-first MVP design planner and reviewer. It turns either a rough MVP idea or explicit SDTK-SPEC design artifacts into reviewable design docs, a static prototype, visual review evidence, and an SDTK-CODE handoff.
@@ -61,6 +61,7 @@ sdtk-design wireframe --screen landing
 sdtk-design system --style minimal-saas
 sdtk-design prototype
 sdtk-design preview
+sdtk-design open
 sdtk-design styles
 sdtk-design review --artifact docs/design/prototype/index.html
 sdtk-design handoff
@@ -69,6 +70,8 @@ sdtk-design status
 
 `preview` starts a local Preview Studio (browser): it renders the prototype screens, lets you click/shift-click elements to annotate them with a note, and (via the **Tokens** panel) live-preview design-token tweaks on the `:root` CSS variables a screen declares. On "Send to agent" it shows a confirm summary, writes `docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md` (schema `sdtk.design.feedback.v1`), then a copy-ready instruction to apply it. Run the `design-prototype` skill afterward to apply that scoped feedback. The studio serves the prototype read-only, writes only under `docs/design/feedback/`, and never runs the agent itself.
 
+`open` is the always-open entry to the same Preview Studio: unlike a strict preview it never hard-fails on a missing prototype — if none exists yet it opens an empty-state with the Style Gallery and "run `sdtk-design prototype` first" guidance; once a prototype is present it renders the screens for annotation. (`preview` is now equally graceful about a missing manifest.)
+
 `styles` opens the same studio focused on the **Style Gallery** — a visual menu of the category-oriented style presets (swatches + type sample + summary). Click a card to copy its `start --style <preset>` command. It needs no prototype (pick a style before generating) and is choose-only: it copies a command, it writes nothing.
 
 Visual style presets:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-design-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local-first MVP design planner and reviewer for SDTK workspaces.",
   "bin": {
     "sdtk-design": "bin/sdtk-design.js"

package/src/commands/help.js

@@ -15,6 +15,7 @@ Usage:
   sdtk-design system --style minimal-saas
   sdtk-design prototype
   sdtk-design preview
+  sdtk-design open
   sdtk-design styles
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
@@ -60,6 +61,7 @@ Command status:
   system                Available.
   prototype             Available SPEC-driven prototype manifest launcher.
   preview               Available local Preview Studio (render screens + element-level annotate to feedback).
+  open                  Available always-open Preview Studio (empty-state when no prototype yet).
   styles                Available visual Style Gallery (browse + copy a "start --style" command).
   handoff               Available.
   review                Available for local markdown and static HTML artifacts.

package/src/commands/open.js

@@ -0,0 +1,94 @@
+"use strict";
+
+// BK-278 P-A — `sdtk-design open`: the discoverable entry point that opens the
+// Preview Studio whether or not a prototype exists yet. It is a thin wrapper
+// over `runDesignPreview` (which is now graceful about a missing manifest), so
+// `sdtk-design open` always starts the studio — empty-state when there is no
+// prototype, full annotate surface once `sdtk-design prototype` has run. This
+// mirrors how `sdtk-wiki atlas open` / `sdtk-wiki kanban` always open.
+
+const { parseFlags } = require("../lib/args");
+const { ValidationError } = require("../lib/errors");
+const { runDesignPreview, tryOpenBrowser } = require("./preview");
+
+const OPEN_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  port: { type: "string" },
+  "no-open": { type: "boolean" },
+};
+
+function cmdOpenHelp() {
+  console.log(`SDTK-DESIGN Open (Preview Studio)
+
+Usage:
+  sdtk-design open [--project-path <path>] [--port <n>] [--no-open]
+
+Example:
+  sdtk-design open
+  sdtk-design open --no-open
+
+What it does:
+  Opens the Preview Studio in your browser. Unlike a strict preview, it always
+  opens: if no prototype exists yet it shows an empty-state with the Style
+  Gallery and "run sdtk-design prototype first" guidance; once a prototype is
+  present it renders the screens for element-level annotation.
+
+Reads:
+  docs/design/prototype/.manifest.json (optional)
+  docs/design/prototype/screens/*.html (skill-owned screen HTML, when present)
+
+Creates:
+  Nothing directly. The studio writes only via its in-browser "Send to agent"
+  action: docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md.
+
+Safety:
+  Local server on 127.0.0.1 only; no external network. Never shells out.
+  In WSL2/Docker, use --no-open and tunnel the printed URL (e.g. cloudflared).`);
+  return 0;
+}
+
+async function cmdOpen(args) {
+  const { flags, positionals } = parseFlags(args || [], OPEN_FLAG_DEFS);
+  if (flags.help) return cmdOpenHelp();
+  if (positionals.length > 0) {
+    throw new ValidationError(
+      `Unsupported open argument: ${positionals.join(" ")}. Use sdtk-design open [--project-path <path>] [--port <n>] [--no-open]. No server started.`
+    );
+  }
+
+  const result = await runDesignPreview({
+    projectPath: flags["project-path"],
+    port: flags.port,
+    noOpen: Boolean(flags["no-open"]),
+  });
+
+  console.log(`[design] Preview Studio: ${result.url}`);
+  if (result.screenCount > 0) {
+    console.log(`[design] Serving ${result.screenCount} screen(s) from docs/design/prototype/`);
+    console.log("[design] Annotate elements, then \"Send to agent\" writes docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md");
+  } else {
+    console.log("[design] No prototype yet — opening with an empty-state. Browse the Style Gallery,");
+    console.log("[design] then run sdtk-design prototype to populate screens for annotation.");
+  }
+  if (result.noOpen) {
+    console.log("[design] --no-open: not launching a browser. Open the URL above (tunnel it on WSL2/Docker).");
+  } else {
+    tryOpenBrowser(result.url);
+  }
+  console.log("[design] Press Ctrl+C to stop the server.");
+
+  return new Promise((resolve) => {
+    const shutdown = () => {
+      try { result.server.close(); } catch (_) {}
+      resolve(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+}
+
+module.exports = {
+  cmdOpen,
+  cmdOpenHelp,
+};

package/src/commands/preview.js

@@ -40,7 +40,8 @@ Example:
   sdtk-design preview --port 3210 --no-open
 
 Reads:
-  docs/design/prototype/.manifest.json (run sdtk-design prototype first)
+  docs/design/prototype/.manifest.json (optional — without it the studio opens
+    with an empty-state; run sdtk-design prototype to populate screens)
   docs/design/prototype/screens/*.html (skill-owned screen HTML)
 
 In the studio:
@@ -100,16 +101,17 @@ async function runDesignPreview({ projectPath, port, noOpen = false }) {
     throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No server started.`);
   }
   const paths = describeDesignPaths(resolvedProjectPath);
-  if (!fs.existsSync(paths.prototypeManifestPath)) {
-    throw new ValidationError(
-      "Missing docs/design/prototype/.manifest.json. Run sdtk-design prototype first. No server started."
-    );
-  }
-  let manifest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(paths.prototypeManifestPath, "utf-8"));
-  } catch (err) {
-    throw new ValidationError(`Could not read prototype manifest: ${err.message}. No server started.`);
+  // Graceful no-manifest (BK-278 P-A): the studio opens with an empty-state
+  // instead of hard-failing, mirroring `sdtk-design styles`. A missing or
+  // malformed manifest must not block opening the studio — the user can still
+  // browse the Style Gallery and read the "run prototype first" instructions.
+  let manifest = { screens: [] };
+  if (fs.existsSync(paths.prototypeManifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(paths.prototypeManifestPath, "utf-8"));
+    } catch (_) {
+      manifest = { screens: [] };
+    }
   }
   const screenCount = Array.isArray(manifest.screens) ? manifest.screens.length : 0;
 
@@ -163,9 +165,14 @@ async function cmdPreview(args) {
   });
 
   console.log(`[design] Preview Studio: ${result.url}`);
-  console.log(`[design] Serving ${result.screenCount} screen(s) from docs/design/prototype/`);
-  console.log("[design] Annotate elements, then \"Send to agent\" writes docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md");
-  console.log("[design] Then run the design-prototype skill to apply the scoped feedback.");
+  if (result.screenCount > 0) {
+    console.log(`[design] Serving ${result.screenCount} screen(s) from docs/design/prototype/`);
+    console.log("[design] Annotate elements, then \"Send to agent\" writes docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md");
+    console.log("[design] Then run the design-prototype skill to apply the scoped feedback.");
+  } else {
+    console.log("[design] No prototype yet — opening with an empty-state. Browse the Style Gallery,");
+    console.log("[design] then run sdtk-design prototype to populate screens for annotation.");
+  }
   if (result.noOpen) {
     console.log("[design] --no-open: not launching a browser. Open the URL above (tunnel it on WSL2/Docker).");
   } else {

package/src/index.js

@@ -5,6 +5,7 @@ const { cmdHandoff } = require("./commands/handoff");
 const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
 const { cmdPreview } = require("./commands/preview");
+const { cmdOpen } = require("./commands/open");
 const { cmdStyles } = require("./commands/styles");
 const { cmdPrototype } = require("./commands/prototype");
 const { cmdReview } = require("./commands/review");
@@ -76,6 +77,9 @@ async function run(argv) {
   if (command === "preview") {
     return cmdPreview(args);
   }
+  if (command === "open") {
+    return cmdOpen(args);
+  }
   if (command === "styles") {
     return cmdStyles(args);
   }