sdtk-design-kit 0.2.1 → 0.3.1

package/src/lib/screen-briefs.js

@@ -43,36 +43,107 @@ function listOrNeeds(values, marker) {
   return `- ${needs(marker)}`;
 }
 
-function tokenUsageOrDefault(value) {
+// BK-227: bounded enum — sections with repeated-slot content render NEEDS_* as <a> skeleton.
+const INTERACTIVE_COMPONENT_PATTERNS = [
+  "product-card", "product-row", "order-row", "order-card",
+  "search-result", "search-row", "result-row",
+  "nav-item", "list-item", "category-card", "catalog-card",
+];
+
+const INTERACTIVE_TEMPLATE_CONTEXTS = {
+  category: ["grid", "products", "items", "list", "catalog"],
+  search: ["results", "items", "matches"],
+  "order-history": ["orders", "list", "rows", "history"],
+  home: ["categories", "featured", "grid", "cards"],
+  "product-detail": ["related", "recommendations"],
+};
+
+// BK-230: normalize identifier for naming-convention-agnostic comparison
+// (matches PascalCase, kebab-case, snake_case, spaced — all collapse to lower-alphanum).
+function normalizeIdentifier(value) {
+  return String(value || "").toLowerCase().replace(/[\s_-]+/g, "");
+}
+
+// BK-230: precompute normalized pattern + keyword sets at module load.
+const INTERACTIVE_COMPONENT_PATTERNS_NORM = INTERACTIVE_COMPONENT_PATTERNS.map(normalizeIdentifier);
+const INTERACTIVE_TEMPLATE_CONTEXTS_NORM = Object.fromEntries(
+  Object.entries(INTERACTIVE_TEMPLATE_CONTEXTS).map(([k, kws]) => [
+    normalizeIdentifier(k),
+    kws.map(normalizeIdentifier),
+  ])
+);
+
+function isInteractiveSection(section, screen) {
+  if (!section || !screen) return false;
+  const components = Array.isArray(section.components)
+    ? section.components.map(normalizeIdentifier)
+    : [];
+  // Rule 1: explicit component pattern match (normalized both sides).
+  for (const pattern of INTERACTIVE_COMPONENT_PATTERNS_NORM) {
+    if (components.some((c) => c.includes(pattern))) return true;
+  }
+  // Rule 2: template_role + section title/components keyword (normalized).
+  const templateRole = normalizeIdentifier(screen.templateRole || screen.template_role || "");
+  const contextKeywords = INTERACTIVE_TEMPLATE_CONTEXTS_NORM[templateRole] || [];
+  if (contextKeywords.length === 0) return false;
+  const title = normalizeIdentifier(section.title || "");
+  for (const kw of contextKeywords) {
+    if (title.includes(kw)) return true;
+    if (components.some((c) => c.includes(kw))) return true;
+  }
+  return false;
+}
+
+function interactiveDataSlotsForSection(section, screen) {
+  if (!isInteractiveSection(section, screen)) return [];
+  return Array.isArray(section.data_slots) ? cleanArray(section.data_slots) : [];
+}
+
+// BK-225: v3 visual_token_usage aligned to BK-223 v2 token schema key paths.
+const TOKEN_USAGE_V3_DEFAULTS = {
+  palette_keys: [
+    "palette.surface", "palette.surfaceAlt", "palette.textPrimary", "palette.textMuted",
+    "palette.primary", "palette.accent", "palette.border",
+    "palette.state.success.base", "palette.state.error.base",
+  ],
+  typography_keys: [
+    "typography.fontFamily.body",
+    "typography.ramp.h1", "typography.ramp.h2", "typography.ramp.h3",
+    "typography.ramp.body", "typography.ramp.caption",
+  ],
+  section_keys: [
+    "section.containerMaxWidth", "section.contentMaxWidth",
+    "section.sectionGap", "section.heroMinHeight", "section.gridColumns",
+  ],
+  component_keys: [
+    "component.radius.card", "component.radius.control",
+    "component.shadow.sm", "component.shadow.md",
+    "component.borderWidth.default",
+  ],
+};
+
+function tokenUsageV3OrDefault(value) {
   const payload = value && typeof value === "object" && !Array.isArray(value) ? value : {};
   const tokenUsage = {
     palette_keys: cleanArray(payload.palette_keys || payload.paletteKeys),
     typography_keys: cleanArray(payload.typography_keys || payload.typographyKeys),
-    spacing_keys: cleanArray(payload.spacing_keys || payload.spacingKeys),
-    radius_keys: cleanArray(payload.radius_keys || payload.radiusKeys),
+    section_keys: cleanArray(payload.section_keys || payload.sectionKeys),
+    component_keys: cleanArray(payload.component_keys || payload.componentKeys),
   };
-  if (
-    tokenUsage.palette_keys.length === 0 &&
-    tokenUsage.typography_keys.length === 0 &&
-    tokenUsage.spacing_keys.length === 0 &&
-    tokenUsage.radius_keys.length === 0
-  ) {
-    return {
-      palette_keys: ["color.surface", "color.textPrimary", "color.accentPrimary"],
-      typography_keys: ["typography.fontFamily", "typography.uiWeight"],
-      spacing_keys: ["spacing.md", "spacing.lg", "spacing.sectionGap"],
-      radius_keys: ["radius.card", "radius.control"],
-    };
-  }
-  return tokenUsage;
+  const hasAny =
+    tokenUsage.palette_keys.length > 0 ||
+    tokenUsage.typography_keys.length > 0 ||
+    tokenUsage.section_keys.length > 0 ||
+    tokenUsage.component_keys.length > 0;
+  return hasAny ? tokenUsage : { ...TOKEN_USAGE_V3_DEFAULTS };
 }
 
 function tokenUsageMarkdown(tokenUsage) {
   return [
     `- Palette keys: ${tokenUsage.palette_keys.length > 0 ? tokenUsage.palette_keys.join(", ") : needs("PALETTE_KEYS")}`,
     `- Typography keys: ${tokenUsage.typography_keys.length > 0 ? tokenUsage.typography_keys.join(", ") : needs("TYPOGRAPHY_KEYS")}`,
-    `- Spacing keys: ${tokenUsage.spacing_keys.length > 0 ? tokenUsage.spacing_keys.join(", ") : needs("SPACING_KEYS")}`,
-    `- Radius keys: ${tokenUsage.radius_keys.length > 0 ? tokenUsage.radius_keys.join(", ") : needs("RADIUS_KEYS")}`,
+    `- Section keys: ${tokenUsage.section_keys.length > 0 ? tokenUsage.section_keys.join(", ") : needs("SECTION_KEYS")}`,
+    `- Component keys: ${tokenUsage.component_keys.length > 0 ? tokenUsage.component_keys.join(", ") : needs("COMPONENT_KEYS")}`,
   ].join("\n");
 }
 
@@ -100,6 +171,90 @@ function densityForRole(templateRole) {
   return null;
 }
 
+// BK-225: derive height_band from section position and role.
+function heightBandForSection(index, total, templateRole) {
+  if (index === 0 && templateRole === "home") return "hero";
+  if (index === 0) return "standard";
+  if (index === total - 1) return "compact";
+  return "standard";
+}
+
+// BK-225: build visual_direction block for a section.
+// Only uses explicit handoff fields from the normalized section record.
+function visualDirectionForSection(section, screen, index) {
+  const totalSections = Array.isArray(screen.sections) ? screen.sections.length : 1;
+  const templateRole = screen.templateRole || "generic";
+
+  // Dimension
+  const heightBand = heightBandForSection(index, totalSections, templateRole);
+  const hasColumns = typeof section.column_count === "number" || typeof section.columnCount === "number";
+  const columnCount = hasColumns ? (section.column_count || section.columnCount) : null;
+  const splitRatio = section.split_ratio || section.splitRatio || null;
+  const dimension = {
+    height_band: heightBand,
+    column_count: columnCount !== null ? columnCount : needs("COLUMN_COUNT"),
+    split_ratio: splitRatio || needs("SPLIT_RATIO"),
+  };
+
+  // Layout intent: derive from explicit layout_model or section components.
+  const hasComponents = Array.isArray(section.components) && section.components.length > 0;
+  const sectionLayoutIntent = section.layout_intent || section.layoutIntent || null;
+  let layoutIntent;
+  if (sectionLayoutIntent) {
+    layoutIntent = sectionLayoutIntent;
+  } else if (hasComponents) {
+    layoutIntent = `Render ${section.components.slice(0, 2).join(" and ")} in section.`;
+  } else {
+    layoutIntent = needs("LAYOUT_INTENT");
+  }
+
+  // Content direction: sourced from explicit handoff fields only.
+  const heading = section.title ? section.title : needs("CONTENT_HEADING");
+  const body = section.purpose ? section.purpose : needs("CONTENT_BODY");
+  const hasDataSlots = Array.isArray(section.data_slots) && section.data_slots.length > 0;
+  const dataDirection = hasDataSlots
+    ? `Map data_slots into scannable rows: ${section.data_slots.slice(0, 3).join(", ")}.`
+    : needs("DATA_DIRECTION");
+  const contentDirection = {
+    heading,
+    body,
+    data_direction: dataDirection,
+  };
+
+  // Imagery: sourced from explicit handoff fields only.
+  const imageryPlacement = section.imagery_placement || section.imageryPlacement || needs("IMAGERY_PLACEMENT");
+  const imagerySubject = section.imagery_subject || section.imagerySubject || needs("IMAGERY_SUBJECT");
+  const imageryAspectRatio = section.imagery_aspect_ratio || section.imageryAspectRatio || "16:9";
+  const imageryTreatment = section.imagery_treatment || section.imageryTreatment || "token-bounded, non-decorative";
+  const imagery = {
+    placement: imageryPlacement,
+    subject: imagerySubject,
+    aspect_ratio: imageryAspectRatio,
+    treatment: imageryTreatment,
+  };
+
+  // Source evidence: screen-level is sufficient when section-specific is unavailable.
+  const screenEvidence = screen.sourceEvidence || {};
+  const sourceStatus = screenEvidence.source_status || "explicit";
+  const sourceQuote = screenEvidence.source_quote || needs("SOURCE_QUOTE");
+  const sourceLineRange = Array.isArray(screenEvidence.source_line_range)
+    ? screenEvidence.source_line_range
+    : [1, 1];
+  const sourceEvidence = {
+    source_status: sourceStatus,
+    source_quote: sourceQuote,
+    source_line_range: sourceLineRange,
+  };
+
+  return {
+    dimension,
+    layout_intent: layoutIntent,
+    content_direction: contentDirection,
+    imagery,
+    source_evidence: sourceEvidence,
+  };
+}
+
 function sectionMarkdown(sections) {
   if (!Array.isArray(sections) || sections.length === 0) {
     return `- ${needs("SECTIONS")}`;
@@ -115,6 +270,10 @@ function sectionMarkdown(sections) {
       if (Array.isArray(section.data_slots) && section.data_slots.length > 0) {
         details.push(`data=${section.data_slots.map(escapeMarkdown).join(", ")}`);
       }
+      // BK-227: surface interactive slot list for renderer skill consumption.
+      if (Array.isArray(section.interactive_data_slots) && section.interactive_data_slots.length > 0) {
+        details.push(`interactive=${section.interactive_data_slots.map(escapeMarkdown).join(", ")}`);
+      }
       if (Array.isArray(section.states) && section.states.length > 0) {
         details.push(`states=${section.states.map(escapeMarkdown).join(", ")}`);
       }
@@ -156,14 +315,23 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
   const dataSlots = uniqueStrings([...(screen.dataSlots || []), ...sectionDataSlots]);
   const sourceEvidence = screen.sourceEvidence || {};
   const supportingArtifacts = cleanArray(sourceArtifacts);
+
+  // BK-225: add visual_direction per section.
+  // BK-227: add interactive_data_slots per section (subset of data_slots for repeated-slot contexts).
+  const sectionsWithVisualDirection = sections.map((section, index) => ({
+    ...section,
+    visual_direction: visualDirectionForSection(section, screen, index),
+    interactive_data_slots: interactiveDataSlotsForSection(section, screen),
+  }));
+
   const model = {
-    schema: "sdtk.design.screen-brief.v2",
+    schema: "sdtk.design.screen-brief.v3",
     screen_id: screen.screenId,
     screen_title: screen.title,
     purpose: screen.purpose || needs("SCREEN_PURPOSE"),
     user_intent: screen.userIntent || needs("USER_INTENT"),
     route: screen.route || needs("ROUTE"),
-    sections,
+    sections: sectionsWithVisualDirection,
     section_titles: sections.map((section) => section.title).filter(Boolean),
     layout_model: screen.layoutModel || layoutModelForRole(templateRole) || needs("LAYOUT_MODEL"),
     density: screen.density || densityForRole(templateRole) || needs("DENSITY"),
@@ -179,7 +347,7 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
             "Expose keyboard focus order for navigation, filters, forms, and primary actions.",
             "Keep contrast and touch target sizing aligned with DESIGN_TOKENS guidance.",
           ],
-    visual_token_usage: tokenUsageOrDefault(screen.visualTokenUsage),
+    visual_token_usage: tokenUsageV3OrDefault(screen.visualTokenUsage),
     acceptance_criteria:
       cleanArray(screen.acceptanceCriteria).length > 0
         ? cleanArray(screen.acceptanceCriteria)
@@ -197,7 +365,8 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
     profile: profileSelection || "generic",
     confidence: screen.confidence || "low",
   };
-  model.gaps = [
+
+  const gapSources = [
     model.purpose,
     model.user_intent,
     model.route,
@@ -209,10 +378,49 @@ function buildBriefModel({ screen, profileSelection, profilePrimitives, sourceAr
     ...model.data_slots,
     ...model.acceptance_criteria,
     model.source_evidence.source_quote,
-  ].filter((value) => String(value).startsWith("NEEDS_"));
+  ];
+  // BK-225: include visual_direction NEEDS_* markers in gaps.
+  for (const section of sectionsWithVisualDirection) {
+    const vd = section.visual_direction;
+    if (vd) {
+      if (String(vd.layout_intent).startsWith("NEEDS_")) gapSources.push(vd.layout_intent);
+      if (String(vd.dimension && vd.dimension.column_count).startsWith("NEEDS_")) gapSources.push(String(vd.dimension.column_count));
+      if (String(vd.content_direction && vd.content_direction.heading).startsWith("NEEDS_")) gapSources.push(String(vd.content_direction.heading));
+      if (String(vd.imagery && vd.imagery.subject).startsWith("NEEDS_")) gapSources.push(String(vd.imagery.subject));
+    }
+  }
+  model.gaps = gapSources.filter((value) => String(value).startsWith("NEEDS_"));
   return model;
 }
 
+function renderVisualDirectionMarkdown(sections) {
+  if (!Array.isArray(sections) || sections.length === 0) {
+    return `- ${needs("VISUAL_DIRECTION")}`;
+  }
+  return sections
+    .map((section, index) => {
+      const vd = section.visual_direction;
+      if (!vd) return `- Section ${index + 1}: ${needs("VISUAL_DIRECTION")}`;
+      const title = escapeMarkdown(section.title || `Section ${index + 1}`);
+      const dim = vd.dimension || {};
+      return [
+        `### ${title}`,
+        `- Height band: ${escapeMarkdown(dim.height_band || needs("HEIGHT_BAND"))}`,
+        `- Column count: ${escapeMarkdown(String(dim.column_count || needs("COLUMN_COUNT")))}`,
+        `- Split ratio: ${escapeMarkdown(dim.split_ratio || needs("SPLIT_RATIO"))}`,
+        `- Layout intent: ${escapeMarkdown(vd.layout_intent || needs("LAYOUT_INTENT"))}`,
+        `- Content heading: ${escapeMarkdown((vd.content_direction && vd.content_direction.heading) || needs("CONTENT_HEADING"))}`,
+        `- Content body: ${escapeMarkdown((vd.content_direction && vd.content_direction.body) || needs("CONTENT_BODY"))}`,
+        `- Data direction: ${escapeMarkdown((vd.content_direction && vd.content_direction.data_direction) || needs("DATA_DIRECTION"))}`,
+        `- Imagery placement: ${escapeMarkdown((vd.imagery && vd.imagery.placement) || needs("IMAGERY_PLACEMENT"))}`,
+        `- Imagery subject: ${escapeMarkdown((vd.imagery && vd.imagery.subject) || needs("IMAGERY_SUBJECT"))}`,
+        `- Imagery aspect ratio: ${escapeMarkdown((vd.imagery && vd.imagery.aspect_ratio) || "16:9")}`,
+        `- Imagery treatment: ${escapeMarkdown((vd.imagery && vd.imagery.treatment) || "token-bounded, non-decorative")}`,
+      ].join("\n");
+    })
+    .join("\n\n");
+}
+
 function renderScreenBrief({ screen, profileSelection, profilePrimitives, sourceArtifacts }) {
   const model = buildBriefModel({ screen, profileSelection, profilePrimitives, sourceArtifacts });
 
@@ -254,6 +462,9 @@ ${listOrNeeds(model.data_slots, "DATA_SLOTS")}
 ## Visual Token Usage
 ${tokenUsageMarkdown(model.visual_token_usage)}
 
+## Section Visual Direction
+${renderVisualDirectionMarkdown(model.sections)}
+
 ## Accessibility Notes
 ${listOrNeeds(model.accessibility_notes, "ACCESSIBILITY_NOTES")}
 

package/src/lib/update.js

@@ -0,0 +1,219 @@
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const { parseFlags } = require("./args");
+const { CliError, ValidationError } = require("./errors");
+
+const PACKAGE_NAME = "sdtk-design-kit";
+const PRODUCT_NAME = "SDTK-DESIGN";
+const NPM_BIN = process.platform === "win32" ? "npm.cmd" : "npm";
+const NPM_DISPLAY = "npm";
+const NPM_VIEW_ARGS = ["view", PACKAGE_NAME, "version"];
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const FLAG_DEFS = {
+  version: { type: "string" },
+  "project-path": { type: "string" },
+  "check-only": { type: "boolean" },
+  "skip-project-files": { type: "boolean" },
+  verbose: { type: "boolean" },
+};
+const pkg = require("../../package.json");
+
+let commandExecutor = defaultCommandExecutor;
+
+function defaultCommandExecutor(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env: options.env || process.env,
+      shell: options.shell || false,
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (options.verbose) process.stdout.write(text);
+    });
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      if (options.verbose) process.stderr.write(text);
+    });
+    child.on("error", (error) => {
+      if (error && error.code === "ENOENT") {
+        reject(new CliError(`Required command not found in PATH: ${command}`));
+        return;
+      }
+      reject(error);
+    });
+    child.on("close", (exitCode) => {
+      resolve({ exitCode: typeof exitCode === "number" ? exitCode : 1, stdout, stderr });
+    });
+  });
+}
+
+function setCommandExecutorForTests(executor) {
+  commandExecutor = executor || defaultCommandExecutor;
+}
+
+function resetCommandExecutorForTests() {
+  commandExecutor = defaultCommandExecutor;
+}
+
+function quote(value) {
+  const text = String(value);
+  return /[\s"]/u.test(text) ? JSON.stringify(text) : text;
+}
+
+function formatCommand(command, args) {
+  return [command, ...args].map((value) => quote(value)).join(" ");
+}
+
+function validateVersion(targetVersion) {
+  if (targetVersion !== "latest" && !VERSION_PATTERN.test(targetVersion)) {
+    throw new ValidationError(`Invalid value for --version: "${targetVersion}". Must be "latest" or x.y.z.`);
+  }
+}
+
+function extractResolvedVersion(stdout) {
+  const lines = String(stdout || "")
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const candidate = (lines[lines.length - 1] || "").replace(/^['"]|['"]$/gu, "");
+  if (!VERSION_PATTERN.test(candidate)) {
+    throw new CliError(`npm registry lookup returned an invalid version for ${PACKAGE_NAME}: "${candidate || "<empty>"}"`);
+  }
+  return candidate;
+}
+
+async function resolveTargetVersion(options) {
+  if (options.requestedVersion !== "latest") {
+    return options.requestedVersion;
+  }
+
+  let result;
+  try {
+    result = await commandExecutor(NPM_BIN, NPM_VIEW_ARGS, {
+      verbose: options.verbose,
+      shell: process.platform === "win32",
+    });
+  } catch (error) {
+    throw new CliError(`npm registry lookup failed for ${PACKAGE_NAME} while resolving --version latest.\n${error.message}`, error.exitCode || 4);
+  }
+
+  if (result.exitCode !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new CliError(`npm registry lookup failed for ${PACKAGE_NAME} while resolving --version latest (exit code ${result.exitCode}).${detail ? `\n${detail}` : ""}`);
+  }
+
+  try {
+    return extractResolvedVersion(result.stdout);
+  } catch (error) {
+    throw new CliError(`npm registry lookup failed for ${PACKAGE_NAME} while resolving --version latest.\n${error.message}`, error.exitCode || 4);
+  }
+}
+
+function buildPlan(options) {
+  const npmArgs = ["install", "-g", `${PACKAGE_NAME}@${options.targetVersion}`];
+  return {
+    installedVersion: pkg.version,
+    requestedVersion: options.requestedVersion,
+    targetVersion: options.targetVersion,
+    updateNeeded: pkg.version !== options.targetVersion,
+    npmArgs,
+    npmCommand: formatCommand(NPM_DISPLAY, npmArgs),
+    projectPath: options.projectPath,
+    checkOnly: options.checkOnly,
+    skipProjectFiles: options.skipProjectFiles,
+    projectRefreshCommand: options.skipProjectFiles
+      ? "skipped (--skip-project-files)"
+      : "skipped (R1 package-only update; project files are never mutated)",
+    runtimeRefreshCommand: "skipped (no runtime asset update in R1)",
+  };
+}
+
+function parseUpdateOptions(args) {
+  const parsed = parseFlags(args || [], FLAG_DEFS);
+  const flags = parsed.flags || {};
+  const positional = parsed.positional || parsed.positionals || [];
+
+  if (positional.length > 0) {
+    throw new ValidationError(`Unexpected arguments: ${positional.join(" ")}`);
+  }
+
+  const requestedVersion = flags.version || "latest";
+  validateVersion(requestedVersion);
+
+  return {
+    requestedVersion,
+    projectPath: path.resolve(flags["project-path"] || process.cwd()),
+    checkOnly: Boolean(flags["check-only"]),
+    skipProjectFiles: Boolean(flags["skip-project-files"]),
+    verbose: Boolean(flags.verbose),
+  };
+}
+
+function printPlan(plan) {
+  console.log(`${PRODUCT_NAME} update plan`);
+  console.log(`  Installed package version: ${plan.installedVersion}`);
+  console.log(`  Requested package version: ${plan.requestedVersion}`);
+  console.log(`  Target package version:    ${plan.targetVersion}`);
+  console.log(`  Package update needed:     ${plan.updateNeeded ? "yes" : `no (already installed: ${plan.installedVersion})`}`);
+  console.log(`  Package refresh command:   ${plan.npmCommand}`);
+  console.log(`  Project path:              ${plan.projectPath}`);
+  console.log(`  Project file refresh:      ${plan.projectRefreshCommand}`);
+  console.log(`  Runtime asset refresh:     ${plan.runtimeRefreshCommand}`);
+  console.log(`  Mode:                      ${plan.checkOnly ? "check-only (no changes applied)" : "apply"}`);
+}
+
+async function runCommand(label, command, args, options) {
+  const result = await commandExecutor(command, args, options);
+  if (result.exitCode !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    throw new CliError(`${label} failed (exit code ${result.exitCode}).${detail ? `\n${detail}` : ""}`);
+  }
+  return result;
+}
+
+async function applyPlan(plan, options) {
+  console.log("");
+  console.log(`Applying ${PRODUCT_NAME} update...`);
+  console.log(`  npm refresh: ${plan.npmCommand}`);
+  await runCommand("npm package refresh", NPM_BIN, plan.npmArgs, {
+    verbose: options.verbose,
+    shell: process.platform === "win32",
+  });
+  console.log(`  project refresh: ${plan.projectRefreshCommand}`);
+  console.log(`  runtime refresh: ${plan.runtimeRefreshCommand}`);
+  console.log("");
+  console.log(`${PRODUCT_NAME} update completed successfully.`);
+}
+
+async function executeUpdate(args) {
+  const options = parseUpdateOptions(args);
+  const targetVersion = await resolveTargetVersion(options);
+  const plan = buildPlan({ ...options, targetVersion });
+  printPlan(plan);
+
+  if (options.checkOnly) {
+    return 0;
+  }
+
+  await applyPlan(plan, options);
+  return 0;
+}
+
+module.exports = {
+  buildPlan,
+  executeUpdate,
+  formatCommand,
+  parseUpdateOptions,
+  resetCommandExecutorForTests,
+  resolveTargetVersion,
+  setCommandExecutorForTests,
+};

package/src/lib/prototype-briefs.js

@@ -1,125 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-
-function slugify(value, fallback = "item") {
-  const slug = String(value == null ? "" : value)
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  return slug || fallback;
-}
-
-function normalizeSlot(slot, fallbackId) {
-  if (slot && typeof slot === "object") {
-    const id = slugify(slot.id || slot.key || slot.name || slot.label || fallbackId, fallbackId);
-    return {
-      id,
-      label: String(slot.label || slot.name || slot.title || slot.id || id),
-    };
-  }
-  const label = String(slot == null ? fallbackId : slot);
-  return { id: slugify(label, fallbackId), label };
-}
-
-function normalizeComponent(component, fallbackId) {
-  if (component && typeof component === "object") {
-    const id = slugify(component.id || component.type || component.name || component.label || fallbackId, fallbackId);
-    return {
-      id,
-      label: String(component.label || component.name || component.title || component.type || component.id || id),
-    };
-  }
-  const label = String(component == null ? fallbackId : component);
-  return { id: slugify(label, fallbackId), label };
-}
-
-function normalizeSection(section, index) {
-  const source = section && typeof section === "object" ? section : {};
-  const title = source.title || source.name || `Section ${index + 1}`;
-  const id = slugify(source.id || title, `section-${index + 1}`);
-  const slots = source.data_slots || source.dataSlots || [];
-  const components = source.components || [];
-  return {
-    id,
-    title: String(title),
-    purpose: String(source.purpose || source.description || "Brief-defined section."),
-    components: (Array.isArray(components) ? components : []).map((component, componentIndex) =>
-      normalizeComponent(component, `${id}-component-${componentIndex + 1}`)
-    ),
-    states: Array.isArray(source.states) ? source.states.map((state) => String(state)) : [],
-    interactions: Array.isArray(source.interactions) ? source.interactions.map((interaction) => String(interaction)) : [],
-    data_slots: (Array.isArray(slots) ? slots : []).map((slot, slotIndex) => normalizeSlot(slot, `${id}-slot-${slotIndex + 1}`)),
-  };
-}
-
-function normalizeBrief(raw, filePath) {
-  const source = raw && typeof raw === "object" ? raw : {};
-  const screenId = slugify(source.screen_id || source.screenId || source.id || path.basename(filePath || "screen", ".json"), "screen");
-  const sections = Array.isArray(source.sections) ? source.sections.map(normalizeSection) : [];
-  const topLevelSlots = source.data_slots || source.dataSlots || [];
-  const topLevelComponents = source.components || [];
-  return {
-    screen_id: screenId,
-    screen_title: String(source.screen_title || source.screenTitle || source.title || screenId),
-    purpose: String(source.purpose || ""),
-    user_intent: String(source.user_intent || source.userIntent || ""),
-    route: String(source.route || ""),
-    primary_action: String(source.primary_action || source.primaryAction || "Continue"),
-    template_role: source.template_role || source.templateRole || null,
-    sections,
-    components: (Array.isArray(topLevelComponents) ? topLevelComponents : []).map((component, index) =>
-      normalizeComponent(component, `${screenId}-component-${index + 1}`)
-    ),
-    states: Array.isArray(source.states || source.required_states || source.requiredStates)
-      ? (source.states || source.required_states || source.requiredStates).map((state) => String(state))
-      : [],
-    interactions: Array.isArray(source.interactions) ? source.interactions.map((interaction) => String(interaction)) : [],
-    data_slots: (Array.isArray(topLevelSlots) ? topLevelSlots : []).map((slot, index) => normalizeSlot(slot, `${screenId}-slot-${index + 1}`)),
-    acceptance_criteria: Array.isArray(source.acceptance_criteria || source.acceptanceCriteria)
-      ? (source.acceptance_criteria || source.acceptanceCriteria).map((item) => String(item))
-      : [],
-    source_evidence: source.source_evidence || source.sourceEvidence || null,
-    file_path: filePath,
-  };
-}
-
-function loadPrototypeBriefIndex({ paths }) {
-  const briefsByScreenId = new Map();
-  const findings = [];
-  const root = paths && paths.designScreenBriefsStatePath ? paths.designScreenBriefsStatePath : null;
-  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
-    return {
-      briefsByScreenId,
-      findings: [{ code: "BRIEF_DIR_MISSING", message: ".sdtk/design/screen-briefs directory is missing." }],
-    };
-  }
-  for (const filePath of fs.readdirSync(root).filter((name) => name.toLowerCase().endsWith(".json")).sort()) {
-    const absolutePath = path.join(root, filePath);
-    try {
-      const brief = normalizeBrief(JSON.parse(fs.readFileSync(absolutePath, "utf-8")), absolutePath);
-      if (briefsByScreenId.has(brief.screen_id)) {
-        findings.push({ screenId: brief.screen_id, code: "BRIEF_DUPLICATE", message: `Duplicate brief skipped: ${filePath}` });
-      } else {
-        briefsByScreenId.set(brief.screen_id, brief);
-      }
-    } catch (err) {
-      findings.push({ code: "BRIEF_INVALID_JSON", message: `${filePath}: ${err.message}` });
-    }
-  }
-  return { briefsByScreenId, findings };
-}
-
-function briefForScreen({ screen, briefIndex }) {
-  if (!screen || !briefIndex || !briefIndex.briefsByScreenId) return null;
-  return briefIndex.briefsByScreenId.get(slugify(screen.screenId || screen.id || screen.title, "screen")) || null;
-}
-
-module.exports = {
-  briefForScreen,
-  loadPrototypeBriefIndex,
-  normalizeBrief,
-  slugify,
-};