@bastani/atomic 0.5.25 → 0.5.26-0

package/src/sdk/workflows/builtin/open-claude-design/helpers/design-system.ts

@@ -0,0 +1,88 @@
+/**
+ * Design.md persistence — loading, saving, and reading design system data.
+ *
+ * The Design.md file is a structured markdown document containing design
+ * tokens (colors, typography, spacing, components) extracted from the
+ * codebase and approved by the user via HIL. It serves as the single
+ * source of truth for all generation and refinement stages.
+ */
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { DESIGN_SYSTEM_FILENAME, IMPECCABLE_FILENAME } from "./constants.ts";
+
+/** Structured representation of the design system data. */
+export interface DesignSystemData {
+  /** Raw markdown content of Design.md. */
+  raw: string;
+  /** Absolute path to the Design.md file. */
+  path: string;
+}
+
+/**
+ * Load an existing Design.md from the given path.
+ * Used when the user provides `--design-system=<path>`.
+ */
+export async function loadDesignSystem(
+  designSystemPath: string,
+): Promise<DesignSystemData> {
+  const resolved = path.resolve(designSystemPath);
+  const raw = await readFile(resolved, "utf-8");
+  return { raw, path: resolved };
+}
+
+/**
+ * Persist the design system builder's output as Design.md in the project root.
+ *
+ * The builder stage produces a visible session where the agent constructs
+ * the Design.md content interactively with the user. We read the transcript
+ * and extract the final Design.md content that the agent wrote.
+ *
+ * For simplicity, the agent in the builder stage is instructed to write
+ * Design.md directly to disk. This function reads it back to populate
+ * the DesignSystemData for downstream stages.
+ */
+export async function persistDesignSystem(
+  root: string,
+): Promise<DesignSystemData> {
+  const designPath = path.join(root, DESIGN_SYSTEM_FILENAME);
+  const raw = await readFile(designPath, "utf-8");
+  return { raw, path: designPath };
+}
+
+/**
+ * Read the existing .impeccable.md brand context file, if present.
+ * Returns empty string if the file does not exist.
+ */
+export async function readImpeccableMd(root: string): Promise<string> {
+  try {
+    return await readFile(path.join(root, IMPECCABLE_FILENAME), "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Derive a URL-safe slug from the user's prompt for directory naming.
+ */
+export function slugifyPrompt(prompt: string): string {
+  const slug = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 6)
+    .join("-")
+    .substring(0, 60);
+  return slug || "design";
+}
+
+/**
+ * Ensure the scratch directory exists for intermediate workflow outputs.
+ */
+export async function ensureScratchDir(root: string): Promise<string> {
+  const { mkdir } = await import("node:fs/promises");
+  const scratchDir = path.join(root, "research", "designs", ".scratch");
+  await mkdir(scratchDir, { recursive: true });
+  return scratchDir;
+}

package/src/sdk/workflows/builtin/open-claude-design/helpers/export.ts

@@ -0,0 +1,193 @@
+/**
+ * Export engine — handoff bundle packaging.
+ *
+ * Writes the deterministic parts of the handoff bundle (no LLM call):
+ *   - handoff-prompt.md  — ready-to-use prompt for Claude Code
+ *   - README.md          — how to use the bundle
+ *
+ * The exporter stage (LLM) handles copying design files, writing
+ * design-intent.md and component-specs.md since those require
+ * understanding the generated design content.
+ */
+
+import { writeFile, mkdir, copyFile } from "node:fs/promises";
+import path from "node:path";
+import type { DesignSystemData } from "./design-system.ts";
+
+export interface HandoffBundleOptions {
+  designSystem: DesignSystemData;
+  prompt: string;
+  outputType: string;
+}
+
+/**
+ * Write the deterministic handoff bundle files.
+ *
+ * The exporter stage is responsible for:
+ *   - Copying design files (index.html, styles.css, script.js) to design/
+ *   - Writing design-intent.md from transcript analysis
+ *   - Writing component-specs.md from design analysis
+ *
+ * This function writes the remaining deterministic files:
+ *   - Design.md (copy of the design system)
+ *   - handoff-prompt.md (ready-to-use implementation prompt)
+ *   - README.md (bundle documentation)
+ */
+export async function writeHandoffBundle(
+  finalDesignDir: string,
+  opts: HandoffBundleOptions,
+): Promise<void> {
+  await mkdir(finalDesignDir, { recursive: true });
+  await mkdir(path.join(finalDesignDir, "design"), { recursive: true });
+
+  // Copy Design.md
+  await copyFile(
+    opts.designSystem.path,
+    path.join(finalDesignDir, "Design.md"),
+  );
+
+  // Write handoff-prompt.md
+  const handoffPrompt = buildHandoffPrompt(opts);
+  await writeFile(
+    path.join(finalDesignDir, "handoff-prompt.md"),
+    handoffPrompt,
+    "utf-8",
+  );
+
+  // Write README.md
+  const readme = buildReadme(opts);
+  await writeFile(
+    path.join(finalDesignDir, "README.md"),
+    readme,
+    "utf-8",
+  );
+}
+
+function buildHandoffPrompt(opts: HandoffBundleOptions): string {
+  return `# Design Handoff — Implementation Prompt
+
+Use this prompt with Claude Code to implement the design in this bundle.
+
+## Original Design Request
+
+${opts.prompt}
+
+## Output Type
+
+${opts.outputType}
+
+## Instructions
+
+1. Read \`Design.md\` for the complete design system (colors, typography, spacing, components).
+2. Open \`design/index.html\` in a browser to see the reference design.
+3. Read \`design-intent.md\` for the design rationale and key decisions.
+4. Read \`component-specs.md\` for individual component specifications.
+5. Implement the design using the design system tokens from Design.md.
+6. Match the reference design in \`design/\` as closely as possible.
+7. Use semantic HTML, CSS custom properties for tokens, and progressive enhancement.
+
+## Design System Tokens
+
+The design tokens are defined in \`Design.md\`. Use CSS custom properties:
+
+\`\`\`css
+:root {
+  /* Import all tokens from Design.md as custom properties */
+}
+\`\`\`
+
+## Quality Checklist
+
+- [ ] All colors match Design.md tokens
+- [ ] Typography follows the defined scale
+- [ ] Spacing uses the defined base unit
+- [ ] Components match the identified patterns
+- [ ] No AI slop anti-patterns (gradient text, side-stripe borders, reflex fonts)
+- [ ] Responsive at common breakpoints
+- [ ] Accessible (WCAG 2.1 AA)
+`;
+}
+
+function buildReadme(opts: HandoffBundleOptions): string {
+  const extraFileRows = buildExtraFileRows(opts.outputType);
+  const previewSection = buildPreviewSection(opts.outputType);
+
+  return `# Design Handoff Bundle
+
+Generated by the \`open-claude-design\` workflow.
+
+Output type: **${opts.outputType}**
+
+## Contents
+
+| File | Description |
+|------|-------------|
+| \`design/index.html\` | Generated HTML |
+| \`design/styles.css\` | Generated CSS styles |
+| \`design/script.js\` | Generated JavaScript |${extraFileRows}
+| \`Design.md\` | Design system tokens (colors, typography, spacing) |
+| \`design-intent.md\` | Design rationale and key decisions |
+| \`component-specs.md\` | Component / page / wireframe / component-anatomy specs |
+| \`handoff-prompt.md\` | Ready-to-use prompt for Claude Code |
+
+## Usage
+
+${previewSection}
+
+### Implement with Claude Code
+
+\`\`\`bash
+# From the project root, run:
+claude "$(cat ${opts.outputType === "component" ? "component-specs.md" : "handoff-prompt.md"})"
+\`\`\`
+
+### Design System Reference
+
+All design tokens are in \`Design.md\`. Use these tokens when implementing
+to ensure visual consistency with the generated design.
+
+## Original Request
+
+${opts.prompt}
+`;
+}
+
+function buildExtraFileRows(outputType: string): string {
+  if (outputType === "prototype") {
+    return `
+| \`design/server.ts\` | Zero-dependency Bun static-file server (port 4173) |
+| \`design/package.json\` | Defines the \`start\` script |`;
+  }
+  if (outputType === "component") {
+    return `
+| \`design/snippet.html\` | Isolated component markup for copy-paste into a host app |`;
+  }
+  return "";
+}
+
+function buildPreviewSection(outputType: string): string {
+  if (outputType === "prototype") {
+    return `### Preview the Prototype
+
+The prototype ships with a runnable Bun server.
+
+\`\`\`bash
+cd design
+bun run start
+# → Prototype running at http://localhost:4173
+\`\`\`
+
+Override the port with \`PORT=3000 bun run start\` if 4173 is taken.`;
+  }
+  if (outputType === "component") {
+    return `### Preview the Component
+
+Open \`design/index.html\` in a browser to view the component showcase
+(all variants and states). Use \`design/snippet.html\` as a minimal
+copy-paste target for dropping the component into a host application.`;
+  }
+  // page, wireframe, and any other future single-view output types
+  return `### Preview the Design
+
+Open \`design/index.html\` directly in a browser — no server required.`;
+}

package/src/sdk/workflows/builtin/open-claude-design/helpers/import.ts

@@ -0,0 +1,52 @@
+/**
+ * Import handler — input type detection and aggregation.
+ *
+ * Classifies the user's `--reference` input as a URL, file path, or
+ * neither, and aggregates all import sources into a structured context
+ * object that the generator consumes.
+ */
+
+/** Aggregated import context passed to the generator stage. */
+export interface ImportContext {
+  /** The user's free-form design prompt. */
+  prompt: string;
+  /** Raw reference string (URL, file path, or empty). */
+  reference: string;
+  /** Extracted content from a web URL capture, or null. */
+  webCapture: string | null;
+  /** Extracted content from a parsed file, or null. */
+  fileParse: string | null;
+}
+
+/** Check whether the reference string looks like a URL. */
+export function isUrl(reference: string): boolean {
+  if (!reference.trim()) return false;
+  return /^https?:\/\//i.test(reference.trim());
+}
+
+/** Check whether the reference string looks like a file path. */
+export function isFilePath(reference: string): boolean {
+  const trimmed = reference.trim();
+  if (!trimmed) return false;
+  if (isUrl(trimmed)) return false;
+  // Looks like a path: starts with /, ./, ~/, or contains file extension
+  return /^[./~]/.test(trimmed) || /\.\w{1,6}$/.test(trimmed);
+}
+
+/**
+ * Aggregate all import results into a single context object.
+ * Pure deterministic function — no LLM call.
+ */
+export function aggregateImportResults(opts: {
+  prompt: string;
+  reference: string;
+  webCapture: string | null;
+  fileParse: string | null;
+}): ImportContext {
+  return {
+    prompt: opts.prompt,
+    reference: opts.reference,
+    webCapture: opts.webCapture,
+    fileParse: opts.fileParse,
+  };
+}