lazycodex-ai 5.0.0-beta.89 → 5.0.0-beta.90

package/packages/shared-skills/skills/ulw-research/scripts/design-spec.mjs

@@ -0,0 +1,161 @@
+// design-spec.mjs - read the palette and lineage mode out of design-spec.md, and render a
+// design-spec.md draft from a format extract. Nothing is guessed: every value the extract
+// does not carry is written `TODO: ask` and listed under Open questions.
+// Plain Node ESM, node: builtins and siblings only.
+
+import { DESIGN_SPEC_SECTIONS, LINEAGE_MODES } from "./contracts.mjs"
+import { hexColors } from "./css-lite.mjs"
+
+const TODO = "TODO: ask"
+// English and Korean section names (the requester writes specs in either language).
+const PALETTE_HEADING = /^(palette|tokens|colou?rs?|\uD1A0\uD070|\uD314\uB808\uD2B8|\uC0C9\uC0C1|\uCEEC\uB7EC)/i
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/
+const HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/
+const TOKEN_DECLARATION = /--[\w-]+\s*:\s*([^;]*)/g
+const FIGURE_STANDARD =
+	"Each figure sits in a fixed-size container with a caption; the image scales to fit with its aspect ratio preserved (object-fit: contain), never stretched, cropped, or spilling out. Every chart carries a title, axis labels, units, and value labels."
+
+/**
+ * Walk markdown lines with fence awareness.
+ * visit(line, { fenced, heading: { level, text } | null })
+ */
+function walkLines(markdown, visit) {
+	let fence = null
+	for (const line of String(markdown ?? "").split(/\r?\n/)) {
+		const fenceMatch = FENCE.exec(line)
+		if (fence) {
+			const closes = fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length && line.trim() === fenceMatch[1]
+			if (closes) fence = null
+			else visit(line, { fenced: true, heading: null })
+			continue
+		}
+		if (fenceMatch) {
+			fence = fenceMatch[1]
+			continue
+		}
+		const heading = HEADING.exec(line)
+		visit(line, { fenced: false, heading: heading ? { level: heading[1].length, text: heading[2].replace(/^[\d.\s]+/, "") } : null })
+	}
+}
+
+/**
+ * Palette = hex values of every `--x: #hex` inside any fenced code block, plus every hex
+ * anywhere under a heading named Palette / Tokens / Colors / Colours or their Korean equivalents (subheadings included).
+ * @returns {Set<string>} normalized #rrggbb values
+ */
+export function parsePalette(specMarkdown) {
+	const palette = new Set()
+	let paletteLevel = 0
+	walkLines(specMarkdown, (line, { fenced, heading }) => {
+		if (heading) {
+			if (paletteLevel && heading.level > paletteLevel) return
+			paletteLevel = PALETTE_HEADING.test(heading.text) ? heading.level : 0
+			return
+		}
+		if (fenced) for (const match of line.matchAll(TOKEN_DECLARATION)) for (const hex of hexColors(match[1])) palette.add(hex)
+		if (paletteLevel) for (const hex of hexColors(line)) palette.add(hex)
+	})
+	return palette
+}
+
+/** `Lineage: inline|section` under the Citations heading; absent or unrecognized -> "inline". */
+export function parseLineageMode(specMarkdown) {
+	let citationsLevel = 0
+	let mode = null
+	walkLines(specMarkdown, (line, { fenced, heading }) => {
+		if (mode || fenced) return
+		if (heading) {
+			if (citationsLevel && heading.level > citationsLevel) return
+			citationsLevel = /^citations\b/i.test(heading.text) ? heading.level : 0
+			return
+		}
+		const match = citationsLevel ? /^\s*(?:[-*]\s+)?lineage\s*:\s*(\S+)/i.exec(line) : null
+		if (match && LINEAGE_MODES.includes(match[1].toLowerCase())) mode = match[1].toLowerCase()
+	})
+	return mode ?? "inline"
+}
+
+function entriesOf(value) {
+	if (value instanceof Map) return [...value]
+	return value !== null && typeof value === "object" ? Object.entries(value) : []
+}
+
+function isKnown(value) {
+	if (value === undefined || value === null || value === "" || value === "unknown") return false
+	if (Array.isArray(value)) return value.length > 0
+	return true
+}
+
+function tokenFence(entries, dark) {
+	const lines = entries.map(([name, value]) => `${dark ? "    " : "  "}${name}: ${value};`)
+	const body = dark ? ["@media (prefers-color-scheme: dark) {", "  :root {", ...lines, "  }", "}"] : [":root {", ...lines, "}"]
+	return ["```css", ...body, "```"]
+}
+
+/**
+ * Render a design-spec.md draft. `extract` follows the format-extract shape
+ * ({ origin, bytes, date?, tokens: { light, dark }, fonts, colors, breakpoints, headingNumbering,
+ * citationStyle, lineageMode, figureContainers, skeleton, measure, notes }); every field is optional.
+ * @returns {string}
+ */
+export function renderDesignSpec(extract = {}) {
+	const source = extract ?? {}
+	const open = []
+	const field = (label, value, format = String) => {
+		if (isKnown(value)) return format(value)
+		open.push(label)
+		return TODO
+	}
+	const fonts = source.fonts ?? {}
+	const measure = source.measure ?? {}
+	const light = entriesOf(source.tokens?.light)
+	const dark = entriesOf(source.tokens?.dark)
+	const colors = Array.isArray(source.colors) ? source.colors : []
+	const skeleton = Array.isArray(source.skeleton) ? source.skeleton : []
+	const notes = Array.isArray(source.notes) ? source.notes : []
+
+	const sections = {
+		"Extracted from": [
+			`- Source: ${field("Source path or URL", source.origin)}`,
+			`- Bytes: ${field("Source byte count", source.bytes)}`,
+			`- Date: ${source.date ?? new Date().toISOString().slice(0, 10)}`,
+			...notes.map((note) => `- Note: ${note}`),
+		],
+		Tokens: [
+			...(light.length ? tokenFence(light, false) : [`- Light tokens: ${field("Light tokens", null)}`]),
+			...(dark.length ? tokenFence(dark, true) : [`- Dark tokens: ${field("Dark tokens", null)}`]),
+			...(colors.length
+				? ["- Top colors:", ...colors.map((c) => `  - ${c.hex}${c.count ? ` (${c.count} uses${c.roles?.length ? `; ${c.roles.join(", ")}` : ""})` : ""}`)]
+				: [`- Top colors: ${field("Top colors", null)}`]),
+		],
+		Typography: [
+			`- Body font: ${field("Body font", fonts.body)}`,
+			`- Heading font: ${field("Heading font", fonts.heading)}`,
+			`- Mono font: ${field("Mono font", fonts.mono)}`,
+			`- Body size: ${field("Body size", measure.fontSize)}`,
+			`- Line height: ${field("Line height", measure.lineHeight)}`,
+		],
+		Layout: [
+			`- Breakpoints: ${field("Breakpoints", source.breakpoints, (list) => list.map((px) => `${px}px`).join(", "))}`,
+			`- Measure (max width): ${field("Measure", measure.maxWidth)}`,
+		],
+		Structure: [
+			`- Heading numbering: ${field("Heading numbering", source.headingNumbering)}`,
+			skeleton.length ? "- Skeleton:" : `- Skeleton: ${field("Section skeleton", null)}`,
+			...skeleton.map((entry) => `${"  ".repeat(Math.max(1, entry.level))}- ${entry.text}`),
+		],
+		Figures: [
+			`- Containers: ${field("Figure containers", source.figureContainers, (list) => list.join(", "))}`,
+			`- Standard: ${FIGURE_STANDARD}`,
+		],
+		Citations: [
+			`- Style: ${field("Citation style", source.citationStyle)}`,
+			`- Lineage: ${field("Lineage mode", LINEAGE_MODES.includes(source.lineageMode) ? source.lineageMode : null)}`,
+		],
+	}
+	sections["Open questions"] = open.length ? open.map((label) => `- ${label}: ${TODO}`) : ["- None"]
+
+	const out = ["# Design spec", ""]
+	for (const heading of DESIGN_SPEC_SECTIONS) out.push(`## ${heading}`, ...(sections[heading] ?? [`- ${TODO}`]), "")
+	return out.join("\n")
+}

package/packages/shared-skills/skills/ulw-research/scripts/design-spec.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test"
+
+import { DESIGN_SPEC_SECTIONS } from "./contracts.mjs"
+import { parseLineageMode, parsePalette, renderDesignSpec } from "./design-spec.mjs"
+
+function sectionBody(markdown: string, heading: string): string {
+	const start = markdown.indexOf(`## ${heading}\n`)
+	const rest = markdown.slice(start + heading.length + 4)
+	const next = rest.search(/^## /m)
+	return next === -1 ? rest : rest.slice(0, next)
+}
+
+describe("parsePalette", () => {
+	test("#given a css fence and a Palette bullet list #when parsed #then the union is returned", () => {
+		// given
+		const spec = [
+			"# Spec",
+			"```css",
+			":root { --bg: #FAF6EF; --accent: #c2410c; }",
+			"```",
+			"## Palette",
+			"- accent #C2410C",
+			"- good #15803d",
+			"## Layout",
+			"- divider #999999 is prose, not a token",
+		].join("\n")
+		// when
+		const palette = parsePalette(spec)
+		// then
+		expect([...palette].sort()).toEqual(["#15803d", "#c2410c", "#faf6ef"])
+	})
+
+	test("#given Tokens and Colours headings with nested subheadings #when parsed #then hex under them counts", () => {
+		// given
+		const spec = [
+			"## Tokens (copied from the reference)",
+			"- Light: --bg #faf6ef, --fg #24211b",
+			"### Dark",
+			"- --bg #0c0b0a",
+			"## Colours",
+			"good #abc",
+			"## Structure",
+			"#def is not a color heading",
+		].join("\n")
+		// then
+		expect([...parsePalette(spec)].sort()).toEqual(["#0c0b0a", "#24211b", "#aabbcc", "#faf6ef"])
+	})
+
+	test("#given a fence line starting with a hash #when parsed #then it is not read as a heading", () => {
+		// given
+		const spec = ["## Palette", "```", "# not a heading", "--x: #111111", "```", "- #222222"].join("\n")
+		// then
+		expect([...parsePalette(spec)].sort()).toEqual(["#111111", "#222222"])
+	})
+
+	test("#given a spec with no tokens #when parsed #then the palette is empty", () => {
+		expect(parsePalette("# Spec\n\nPlain prose with #fff outside a palette.").size).toBe(0)
+	})
+})
+
+describe("parseLineageMode", () => {
+	test("#given a Lineage line under Citations #when parsed #then that mode is returned", () => {
+		expect(parseLineageMode("## Citations\n- Style: bracket-S\n- Lineage: section\n")).toBe("section")
+		expect(parseLineageMode("## Citations\nLineage: inline")).toBe("inline")
+	})
+
+	test("#given no Citations section or a Lineage line elsewhere #when parsed #then inline is the default", () => {
+		expect(parseLineageMode("# Spec")).toBe("inline")
+		expect(parseLineageMode("## Layout\nLineage: section\n## Citations\n- Style: footnote")).toBe("inline")
+		expect(parseLineageMode("## Citations\nLineage: TODO: ask")).toBe("inline")
+	})
+})
+
+describe("renderDesignSpec", () => {
+	test("#given an empty extract #when rendered #then every section heading appears in order with TODO: ask under each", () => {
+		// when
+		const markdown = renderDesignSpec({})
+		// then
+		let cursor = -1
+		for (const heading of DESIGN_SPEC_SECTIONS) {
+			const index = markdown.indexOf(`## ${heading}\n`)
+			expect(index, heading).toBeGreaterThan(cursor)
+			cursor = index
+			expect(sectionBody(markdown, heading), heading).toContain("TODO: ask")
+		}
+	})
+
+	test("#given a full extract #when rendered #then values, provenance and a round-trippable palette and lineage appear", () => {
+		// given
+		const extract = {
+			origin: "tests/fixtures/reference-report.html",
+			bytes: 16500,
+			date: "2026-09-24",
+			tokens: {
+				light: new Map([
+					["--bg", "#faf6ef"],
+					["--accent", "#c2410c"],
+				]),
+				dark: new Map([["--bg", "#0c0b0a"]]),
+			},
+			fonts: { body: "Pretendard, sans-serif", heading: "Pretendard, sans-serif", mono: "ui-monospace, monospace" },
+			colors: [{ hex: "#24211b", count: 12, roles: ["body"] }],
+			breakpoints: [560, 640],
+			headingNumbering: "double-digit",
+			citationStyle: "bracket-S",
+			lineageMode: "section",
+			figureContainers: ["fig"],
+			skeleton: [
+				{ level: 1, text: "Title" },
+				{ level: 2, text: "01 Findings" },
+			],
+			measure: { fontSize: "17px", lineHeight: "1.75", maxWidth: "720px" },
+			notes: ["skipped external stylesheet: theme.css"],
+		}
+		// when
+		const markdown = renderDesignSpec(extract)
+		// then
+		const provenance = sectionBody(markdown, "Extracted from")
+		expect(provenance).toContain("tests/fixtures/reference-report.html")
+		expect(provenance).toContain("16500")
+		expect(provenance).toContain("2026-09-24")
+		expect(provenance).toContain("skipped external stylesheet: theme.css")
+		expect([...parsePalette(markdown)].sort()).toEqual(["#0c0b0a", "#24211b", "#c2410c", "#faf6ef"])
+		expect(parseLineageMode(markdown)).toBe("section")
+		expect(sectionBody(markdown, "Layout")).toContain("560px, 640px")
+		expect(sectionBody(markdown, "Structure")).toContain("  - 01 Findings")
+		expect(sectionBody(markdown, "Figures")).toContain("fig")
+		expect(sectionBody(markdown, "Open questions")).not.toContain("TODO: ask")
+		for (const heading of ["Tokens", "Typography", "Layout", "Structure", "Figures", "Citations"]) {
+			expect(sectionBody(markdown, heading), heading).not.toContain("TODO: ask")
+		}
+	})
+
+	test("#given unknown enum values and plain-object tokens #when rendered #then unknowns are TODO: ask and listed as open questions", () => {
+		// given
+		const extract = { tokens: { light: { "--bg": "#ffffff" }, dark: {} }, lineageMode: "unknown", citationStyle: "unknown" }
+		// when
+		const markdown = renderDesignSpec(extract)
+		// then
+		expect(sectionBody(markdown, "Tokens")).toContain("--bg: #ffffff;")
+		expect(sectionBody(markdown, "Tokens")).toContain("Dark tokens: TODO: ask")
+		expect(sectionBody(markdown, "Citations")).toContain("Lineage: TODO: ask")
+		expect(parseLineageMode(markdown)).toBe("inline")
+		expect(sectionBody(markdown, "Open questions")).toContain("Lineage mode")
+	})
+})
+
+describe("parsePalette with Korean headings", () => {
+	test("#given a spec whose token section is headed in Korean #when parsed #then the bullet hexes under it are the palette", () => {
+		// given
+		const md = ["# design-spec", "## 토큰 (변경 금지)", "- 라이트: bg #faf6ef · fg #24211b · accent #c2410c", "## 그림 표준", "- 테두리 #ffffff"].join("\n")
+		// when
+		const palette = parsePalette(md)
+		// then
+		expect([...palette].sort()).toEqual(["#24211b", "#c2410c", "#faf6ef"])
+	})
+
+	test("#given Korean color and palette headings #when parsed #then each is recognized", () => {
+		expect([...parsePalette("## 팔레트\n- #112233")]).toEqual(["#112233"])
+		expect([...parsePalette("## 색상\n- #445566")]).toEqual(["#445566"])
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/entities.mjs

@@ -0,0 +1,39 @@
+// entities.mjs - HTML character reference decoding for html-lite.mjs.
+//
+// Supports a fixed set of named entities plus decimal and hex numeric references. Unknown or
+// malformed references stay verbatim. Single indexOf scan; plain Node ESM, no dependencies.
+
+const NAMED_ENTITIES = {
+	amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0", mdash: "\u2014", ndash: "\u2013",
+	hellip: "\u2026", copy: "\u00a9", reg: "\u00ae", times: "\u00d7", middot: "\u00b7",
+}
+
+function decodeOne(body) {
+	if (Object.hasOwn(NAMED_ENTITIES, body)) return NAMED_ENTITIES[body]
+	if (body[0] !== "#") return null
+	const hex = body[1] === "x" || body[1] === "X"
+	const digits = body.slice(hex ? 2 : 1)
+	if (!(hex ? /^[0-9a-fA-F]{1,6}$/ : /^[0-9]{1,7}$/).test(digits)) return null
+	const cp = Number.parseInt(digits, hex ? 16 : 10)
+	return cp > 0 && cp <= 0x10ffff && (cp < 0xd800 || cp > 0xdfff) ? String.fromCodePoint(cp) : "\ufffd"
+}
+
+/** Decode the supported named entities plus decimal/hex numeric references; unknown ones stay verbatim. */
+export function decodeEntities(text) {
+	const source = String(text)
+	let out = ""
+	let last = 0
+	let at = source.indexOf("&")
+	while (at !== -1) {
+		const semi = source.indexOf(";", at + 1)
+		const decoded = semi !== -1 && semi - at <= 12 ? decodeOne(source.slice(at + 1, semi)) : null
+		if (decoded !== null) {
+			out += source.slice(last, at) + decoded
+			last = semi + 1
+			at = source.indexOf("&", last)
+		} else {
+			at = source.indexOf("&", at + 1)
+		}
+	}
+	return out + source.slice(last)
+}

package/packages/shared-skills/skills/ulw-research/scripts/entry-guard.mjs

@@ -0,0 +1,21 @@
+import { realpathSync } from "node:fs"
+import { pathToFileURL } from "node:url"
+
+/**
+ * True when the module at `importMetaUrl` is the process entrypoint (`node <script>`).
+ * Compares against the realpath too: Node resolves import.meta.url through symlinks while
+ * process.argv[1] keeps the symlinked spelling, so a plain equality check silently skips the CLI
+ * body when the skill is reached through a symlinked plugin directory.
+ *
+ * @param {string} importMetaUrl the caller's import.meta.url
+ */
+export function isCliEntry(importMetaUrl) {
+	const argv1 = process.argv[1]
+	if (argv1 === undefined) return false
+	if (importMetaUrl === pathToFileURL(argv1).href) return true
+	try {
+		return importMetaUrl === pathToFileURL(realpathSync(argv1)).href
+	} catch {
+		return false
+	}
+}

package/packages/shared-skills/skills/ulw-research/scripts/format-extract-css.mjs

@@ -0,0 +1,122 @@
+// format-extract-css.mjs - the CSS half of format-extract: tokens, font stacks, ranked colors,
+// breakpoints, and the reading measure. Only values the stylesheet states are returned; a
+// missing value stays undefined so the renderer writes `TODO: ask`.
+// Plain Node ESM, node: builtins and siblings only.
+
+import { customProperties, fontFamilies, hexColors, mediaBreakpoints, resolveVar, scanRules } from "./css-lite.mjs"
+
+const ROLE_ORDER = ["body", "heading", "link", "background", "border", "accent"]
+const TOP_COLORS = 8
+const ABSOLUTE_LENGTH = /^\d+(?:\.\d+)?(?:px|rem|em|ch)$/i
+
+/** Last compound of each comma-separated selector part, pseudo-classes and attributes dropped. */
+function subjects(selector) {
+	return selector.split(",").map((part) => {
+		const compounds = part.trim().split(/\s*[\s>+~]\s*/)
+		return (compounds.at(-1) ?? "").replace(/(?:::?[\w-]+(?:\([^)]*\))?|\[[^\]]*\])+$/g, "").toLowerCase()
+	})
+}
+
+const isBodySubject = (subject) => subject === "body" || subject === "html" || subject === ":root"
+const isHeadingSubject = (subject) => /^h[1-6](?![\w-])/.test(subject)
+const isMonoSubject = (subject) => /^(?:code|pre|kbd|samp)(?![\w-])/.test(subject)
+const isLinkSubject = (subject) => /^a(?![\w-])/.test(subject)
+
+function formatStack(families) {
+	return families.map((family) => (/^-?[A-Za-z_][\w-]*$/.test(family) ? family : JSON.stringify(family))).join(", ")
+}
+
+/** { body?, heading?, mono? } from font-family / font declarations, var() resolved. */
+export function fontStacks(css) {
+	const fonts = {}
+	const entries = fontFamilies(css)
+	const pick = (test) => entries.find((entry) => subjects(entry.selector).some(test))
+	const body = pick(isBodySubject)
+	const heading = pick(isHeadingSubject)
+	const mono = pick(isMonoSubject) ?? entries.find((entry) => entry.families.at(-1)?.toLowerCase() === "monospace")
+	if (body) fonts.body = formatStack(body.families)
+	if (heading) fonts.heading = formatStack(heading.families)
+	if (mono) fonts.mono = formatStack(mono.families)
+	return fonts
+}
+
+function tokenRoles(name) {
+	const roles = []
+	if (/accent|primary|brand/i.test(name)) roles.push("accent")
+	if (/(?:^--|-)bg(?:-|$)|background|surface/i.test(name)) roles.push("background")
+	if (/border|(?:^--|-)rule(?:-|$)/i.test(name)) roles.push("border")
+	return roles
+}
+
+function declarationRoles(selector, prop) {
+	if (prop.startsWith("--")) return tokenRoles(prop)
+	if (prop.startsWith("background")) return ["background"]
+	if (prop.startsWith("border") || prop.startsWith("outline")) return ["border"]
+	if (prop !== "color") return []
+	const parts = subjects(selector)
+	const roles = []
+	if (parts.some(isLinkSubject)) roles.push("link")
+	if (parts.some(isHeadingSubject)) roles.push("heading")
+	if (parts.some(isBodySubject)) roles.push("body")
+	return roles
+}
+
+/**
+ * Top hex colors by use count (ties keep first appearance): each token definition counts once,
+ * and each other declaration counts once per hex it resolves to (var() against light tokens).
+ * Roles are guessed from the selector and property where the color is used.
+ */
+export function rankColors(css, lightTokens) {
+	const table = new Map()
+	for (const rule of scanRules(css)) {
+		for (const { prop, value } of rule.declarations) {
+			const roles = declarationRoles(rule.selector, prop)
+			for (const hex of hexColors(prop.startsWith("--") ? value : resolveVar(value, lightTokens))) {
+				const entry = table.get(hex) ?? { hex, count: 0, roles: new Set() }
+				entry.count++
+				for (const role of roles) entry.roles.add(role)
+				table.set(hex, entry)
+			}
+		}
+	}
+	return [...table.values()]
+		.sort((a, b) => b.count - a.count)
+		.slice(0, TOP_COLORS)
+		.map((entry) => ({ hex: entry.hex, count: entry.count, roles: ROLE_ORDER.filter((role) => entry.roles.has(role)) }))
+}
+
+/** { fontSize?, lineHeight?, maxWidth? }: body size and leading, plus the most used absolute max width. */
+export function readingMeasure(css, lightTokens) {
+	const measure = {}
+	const rules = scanRules(css).filter((rule) => !rule.atRule)
+	for (const rule of rules) {
+		if (!subjects(rule.selector).some(isBodySubject)) continue
+		for (const { prop, value } of rule.declarations) {
+			if (prop === "font-size" && !measure.fontSize) measure.fontSize = resolveVar(value, lightTokens)
+			if (prop === "line-height" && !measure.lineHeight) measure.lineHeight = resolveVar(value, lightTokens)
+		}
+	}
+	const widths = new Map()
+	for (const rule of rules) {
+		for (const { prop, value } of rule.declarations) {
+			if (prop !== "max-width" && prop !== "max-inline-size") continue
+			const resolved = resolveVar(value, lightTokens).trim()
+			if (ABSOLUTE_LENGTH.test(resolved)) widths.set(resolved, (widths.get(resolved) ?? 0) + 1)
+		}
+	}
+	const widest = [...widths].sort((a, b) => b[1] - a[1])[0]
+	if (widest) measure.maxWidth = widest[0]
+	return measure
+}
+
+/** Every CSS-derived Extract field from one concatenated stylesheet. */
+export function cssFacts(css) {
+	const tokens = customProperties(css)
+	return {
+		tokens,
+		fonts: fontStacks(css),
+		colors: rankColors(css, tokens.light),
+		breakpoints: mediaBreakpoints(css),
+		measure: readingMeasure(css, tokens.light),
+	}
+}