@wrongstack/tools 0.313.0 → 0.316.1

package/dist/chunk-6RNIFLG4.js

@@ -0,0 +1,305 @@
+// src/design.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  applyTokenOverrides,
+  getDesignKitLoader,
+  isDesignStack,
+  loadActiveKit,
+  materializeTokens,
+  recordKitChoice,
+  recordOverrides,
+  resolveSemanticTune,
+  runDesignVerify,
+  setActiveKit,
+  setDesignOverrides
+} from "@wrongstack/core/design";
+async function resolveReal(p) {
+  const resolved = path.resolve(p);
+  let probe = resolved;
+  const missing = [];
+  for (; ; ) {
+    try {
+      return path.resolve(await fs.realpath(probe), ...missing);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        const parent = path.dirname(probe);
+        if (parent === probe) return resolved;
+        missing.unshift(path.basename(probe));
+        probe = parent;
+        continue;
+      }
+      return resolved;
+    }
+  }
+}
+function normalizeOverrides(set) {
+  const out = {};
+  if (set && typeof set === "object") {
+    for (const [k, v] of Object.entries(set)) {
+      if (typeof v === "string") out[k] = v;
+    }
+  }
+  return out;
+}
+var designTool = {
+  name: "design",
+  category: "Design",
+  description: 'Browse, load, customize, and enforce curated frontend/mobile UI design kits. Use BEFORE writing UI code to commit to one coherent, modern, responsive, dark/light, accessible design. Actions: "list" (menu), "use" (load+pin a kit for a stack), "foundations" (baseline), "set" (override kit colors/tokens), "materialize" (write the tokens to a real theme file \u2014 CSS @theme/OKLCH or native), "verify" (scan UI files for off-palette colors).',
+  usageHint: 'Flow: `design {action:"use", kit:"minimal-clarity", stack:"web"}` \u2192 optionally `design {action:"set", set:{primary:"oklch(62% 0.2 25)"}}` \u2192 `design {action:"materialize"}` to write tokens to disk \u2192 implement against them \u2192 `design {action:"verify"}`.',
+  permission: "confirm",
+  // WS-046: gives permission decisions something to key on.
+  // The action performed; `out` is optional so it cannot be the subject.
+  subjectKey: "action",
+  mutating: true,
+  capabilities: ["fs.write"],
+  timeoutMs: 15e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["list", "use", "foundations", "set", "tune", "materialize", "verify"],
+        description: "list = menu; use = load+pin a kit; foundations = baseline; set = override colors/tokens; tune = high-level knobs (radius/density/font/motion); materialize = write tokens to a theme file; verify = scan UI for token drift. Default: list."
+      },
+      kit: {
+        type: "string",
+        description: 'Kit id (required for "use"), e.g. "minimal-clarity", "neo-brutalist".'
+      },
+      stack: {
+        type: "string",
+        enum: ["web", "react-native", "flutter", "swiftui", "compose"],
+        description: "Target stack \u2014 narrows guidance + materialize format. Default: web."
+      },
+      set: {
+        type: "object",
+        description: 'Token overrides for "set"/"use": { "primary": "oklch(\u2026)", "dark.bg": "#111" }. Bare key = both themes; "light."/"dark." prefix = that theme only. Empty value clears an override.',
+        additionalProperties: { type: "string" }
+      },
+      tune: {
+        type: "object",
+        description: 'High-level knobs for "tune": { "radius": "lg", "density": "compact", "font": "Space Grotesk", "motion": "snappy" }. radius = none|sm|md|lg|xl|full or a base length; density = compact|cozy|comfortable; motion = snappy|smooth|none. Resolved to concrete token overrides.',
+        properties: {
+          radius: { type: "string" },
+          density: { type: "string" },
+          font: { type: "string" },
+          motion: { type: "string" }
+        }
+      },
+      out: {
+        type: "string",
+        description: "Materialize output path (project-relative). Defaults to a per-stack convention."
+      },
+      force: {
+        type: "boolean",
+        description: "Materialize: overwrite an existing file (default false \u2014 refuses to clobber)."
+      },
+      files: {
+        type: "array",
+        items: { type: "string" },
+        description: "Verify: explicit project-relative files to scan. Default: a bounded UI-file walk."
+      }
+    },
+    required: []
+  },
+  async execute(input, ctx) {
+    const loader = getDesignKitLoader(ctx.projectRoot);
+    const action = input.action ?? "list";
+    const stack = input.stack && isDesignStack(input.stack) ? input.stack : void 0;
+    if (action === "foundations") {
+      const text = await loader.foundationsText(stack);
+      return { action, stack, output: text || "No foundations document is installed." };
+    }
+    if (action === "use") {
+      const kitId = input.kit?.trim();
+      if (!kitId) {
+        const menu2 = await loader.menuText();
+        return { action, output: `No kit id provided.
+
+${menu2}` };
+      }
+      const manifest = await loader.find(kitId);
+      if (!manifest) {
+        const menu2 = await loader.menuText();
+        return { action, kit: kitId, output: `Kit "${kitId}" not found.
+
+${menu2}` };
+      }
+      const resolvedStack = stack ?? manifest.stacks[0] ?? "web";
+      const body = await loader.readBody(manifest.id, resolvedStack);
+      const rawTokens = await loader.readTokens(manifest.id);
+      const persisted = await loadActiveKit(ctx.projectRoot);
+      const keepOverrides = persisted?.kit === manifest.id ? persisted.overrides ?? {} : {};
+      const overrides = { ...keepOverrides, ...normalizeOverrides(input.set) };
+      const tokens = rawTokens ? applyTokenOverrides(rawTokens, overrides) : rawTokens;
+      setActiveKit(ctx, manifest.id, resolvedStack, overrides);
+      await recordKitChoice(
+        ctx.projectRoot,
+        manifest.id,
+        resolvedStack,
+        "design-tool",
+        (/* @__PURE__ */ new Date()).toISOString(),
+        Object.keys(overrides).length ? overrides : void 0
+      );
+      const ovLine = Object.keys(overrides).length ? `
+Active color overrides: ${Object.entries(overrides).map(([k, v]) => `${k}=${v}`).join(", ")}
+` : "";
+      const header = `# Active design kit: ${manifest.name} (${manifest.id}) \u2014 stack: ${resolvedStack}
+${manifest.aesthetic}
+${ovLine}
+Implement the UI faithfully to this spec. Keep light/dark, responsive, and WCAG AA.
+`;
+      const tokenBlock = tokens ? `
+## Token snapshot (overrides applied)
+\`\`\`json
+${JSON.stringify(tokens, null, 2)}
+\`\`\`
+Tip: run \`design {action:"materialize"}\` to write these tokens to a real theme file.
+` : "";
+      return {
+        action,
+        kit: manifest.id,
+        stack: resolvedStack,
+        output: `${header}${tokenBlock}
+${body}`
+      };
+    }
+    if (action === "set") {
+      const patch = normalizeOverrides(input.set);
+      if (Object.keys(patch).length === 0) {
+        return { action, output: 'No overrides given. Pass set:{ "primary": "oklch(\u2026)" }.' };
+      }
+      const merged = await recordOverrides(ctx.projectRoot, patch, (/* @__PURE__ */ new Date()).toISOString());
+      if (!merged) {
+        return {
+          action,
+          output: 'No active kit. Pick one first: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      setDesignOverrides(ctx, merged);
+      return {
+        action,
+        output: `Overrides updated. Active overrides: ${Object.entries(merged).map(([k, v]) => `${k}=${v}`).join(", ")}
+These win over kit tokens. Run \`design {action:"materialize"}\` to write them to a theme file.`
+      };
+    }
+    if (action === "tune") {
+      const patch = resolveSemanticTune(input.tune ?? {});
+      if (Object.keys(patch).length === 0) {
+        return {
+          action,
+          output: 'No recognized knobs. Pass tune:{ radius:"lg", density:"compact", font:"\u2026", motion:"snappy" }.'
+        };
+      }
+      const merged = await recordOverrides(ctx.projectRoot, patch, (/* @__PURE__ */ new Date()).toISOString());
+      if (!merged) {
+        return {
+          action,
+          output: 'No active kit. Pick one first: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      setDesignOverrides(ctx, merged);
+      return {
+        action,
+        output: `Tuned. Resolved ${Object.keys(patch).length} token override(s): ${Object.entries(patch).map(([k, v]) => `${k}=${v}`).join(", ")}
+Run \`design {action:"materialize"}\` to write the tuned tokens to your theme file.`
+      };
+    }
+    if (action === "materialize") {
+      const active = await loadActiveKit(ctx.projectRoot);
+      if (!active) {
+        return {
+          action,
+          output: 'No active kit. Pick one first: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      const resolvedStack = stack ?? (active.stack && isDesignStack(active.stack) ? active.stack : "web");
+      const rawTokens = await loader.readTokens(active.kit);
+      if (!rawTokens) {
+        return { action, kit: active.kit, output: `Kit "${active.kit}" has no tokens.json.` };
+      }
+      const tokens = applyTokenOverrides(rawTokens, active.overrides);
+      const result = materializeTokens({
+        tokens,
+        stack: resolvedStack,
+        kitId: active.kit,
+        outPath: input.out
+      });
+      const root = await resolveReal(ctx.projectRoot);
+      const absResolved = path.isAbsolute(result.path) ? path.resolve(result.path) : path.resolve(path.join(ctx.projectRoot, result.path));
+      const absParent = await resolveReal(path.dirname(absResolved));
+      const abs = path.join(absParent, path.basename(absResolved));
+      const rel = path.relative(root, abs);
+      if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`design: materialize path "${result.path}" would escape the project root`);
+      }
+      let exists = false;
+      try {
+        await fs.access(abs);
+        exists = true;
+      } catch {
+      }
+      if (exists && !input.force) {
+        return {
+          action,
+          kit: active.kit,
+          stack: resolvedStack,
+          path: result.path,
+          output: `${result.path} already exists. Re-run with force:true to overwrite, or write this ${result.format} yourself:
+
+\`\`\`
+${result.content}
+\`\`\``
+        };
+      }
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, result.content);
+      return {
+        action,
+        kit: active.kit,
+        stack: resolvedStack,
+        path: result.path,
+        output: `Wrote ${result.format} to ${result.path}. Import these tokens in your UI so the kit palette is the source of truth. ${exists ? "(overwrote existing file)" : ""}`
+      };
+    }
+    if (action === "verify") {
+      const active = await loadActiveKit(ctx.projectRoot);
+      if (!active) {
+        return {
+          action,
+          output: 'No active kit to verify against. Pick one: `design {action:"use", kit:"<id>"}`.'
+        };
+      }
+      const rawTokens = await loader.readTokens(active.kit);
+      if (!rawTokens) {
+        return { action, kit: active.kit, output: `Kit "${active.kit}" has no tokens.json.` };
+      }
+      const tokens = applyTokenOverrides(rawTokens, active.overrides);
+      const report = await runDesignVerify(ctx.projectRoot, tokens, input.files);
+      const pct = Math.round(report.score * 100);
+      const top = report.violations.slice(0, 25).map((v) => `  ${v.file}:${v.line} \u2014 ${v.reason}: ${v.snippet}`).join("\n");
+      const summary = `Adherence: ${pct}% on-palette across ${report.filesScanned} file(s). ${report.violations.length} violation(s).` + (report.violations.length ? `
+${top}${report.violations.length > 25 ? `
+  \u2026and ${report.violations.length - 25} more` : ""}
+
+Replace off-palette colors with kit tokens (or the materialized CSS vars / token utilities).` : "\nNo off-palette colors found \u2014 UI adheres to the kit palette.");
+      return {
+        action,
+        kit: active.kit,
+        output: summary,
+        score: report.score,
+        violations: report.violations.length
+      };
+    }
+    const menu = await loader.menuText();
+    return {
+      action: "list",
+      output: (menu || "No design kits are installed.") + '\n\nLoad one with `design {action:"use", kit:"<id>", stack:"<stack>"}`.'
+    };
+  }
+};
+
+export {
+  designTool
+};
+//# sourceMappingURL=chunk-6RNIFLG4.js.map