@polderlabs/openkan 0.4.0

package/dist/kanban/tags.js

@@ -0,0 +1,124 @@
+// OpenKan — tagging, categorization, priority, and effort inference.
+// ─── Tag keyword map (in priority order — first match wins) ──────────────────
+const TAG_KEYWORDS = [
+    { keywords: ["fix", "bug", "broken", "regression", "crash", "outage"], tag: "bug" },
+    { keywords: ["feature", "add support", "implement"], tag: "feature" },
+    { keywords: ["refactor", "cleanup", "clean up"], tag: "refactor" },
+    { keywords: ["doc", "docs", "documentation", "readme"], tag: "docs" },
+    { keywords: ["test", "spec", "e2e", "coverage"], tag: "test" },
+    { keywords: ["perf", "performance", "slow", "optimi"], tag: "perf" },
+    { keywords: ["security", "vuln", "cve", "xss"], tag: "security" },
+    { keywords: ["a11y", "accessibility"], tag: "a11y" },
+    { keywords: ["ux", "design"], tag: "ux" },
+    { keywords: ["i18n", "l10n", "locale"], tag: "i18n" },
+    { keywords: ["migration", "migrate"], tag: "migration" },
+    { keywords: ["deprecat"], tag: "deprecation" },
+];
+// ─── Category rules (first match wins) ───────────────────────────────────────
+const CATEGORY_PATTERNS = [
+    { pattern: /\.tsx|\.jsx|\.css|\.scss|component|page\/|ui\/|button|modal|style(?!s)|css[\/-]/i, category: "frontend" },
+    { pattern: /\.py|\.go|\.ts\b(?!x)|\/api|endpoint|route|handler|server|db|query|sql\b/i, category: "backend" },
+    { pattern: /k8s|kubernetes|docker|terraform|tf\b|helm|deploy|ci|cd|pipeline/i, category: "infra" },
+    { pattern: /readme|changelog|\bdocs\/|documentation|comment|jsdoc/i, category: "docs" },
+    { pattern: /playwright|vitest|jest|mocha|cypress|e2e|unit test/i, category: "test" },
+    { pattern: /figma|sketch|wireframe|mockup|style guide/i, category: "design" },
+    { pattern: /sql\b|postgres|mysql|migration|schema|index|query\b/i, category: "data" },
+    { pattern: /xss|csp|cve|auth|oauth|jwt|vuln|rbac/i, category: "security" },
+];
+// ─── Priority rules (first match wins) ───────────────────────────────────────
+const PRIORITY_PATTERNS = [
+    { pattern: /P0|urgent|asap|critical|blocker|outage/i, priority: "urgent" },
+    { pattern: /P1|high priority|high\b(?! priority)|important/i, priority: "high" },
+    { pattern: /P2|low priority/i, priority: "low" },
+    { pattern: /P3|backlog/i, priority: "normal" },
+];
+// ─── Effort rules (first match wins; null if no signal) ─────────────────────
+const EFFORT_PATTERNS = [
+    { pattern: /\b(?:xs|trivial|1[\s_-]?line|one[\s_-]?liner|typo)\b/i, effort: "xs" },
+    { pattern: /\b(?:small|quick|minutes?)\b/i, effort: "s" },
+    { pattern: /\b(?:medium|afternoon|half[\s_-]?day)\b/i, effort: "m" },
+    // xl pattern first (tries multi-week before week in the l rule below)
+    { pattern: /\b(?:xl|epic|multi[\s_-]?week|quarter)\b/i, effort: "xl" },
+    // "week" must NOT be preceded by a letter/digit/hyphen (prevents matching inside "multi-week")
+    { pattern: /\b(?:large|big|(?<![a-zA-Z0-9-])week)\b/i, effort: "l" },
+];
+// ─── Explicit tag extraction ─────────────────────────────────────────────────
+const HASHTAG_PATTERN = /#([a-zA-Z][a-zA-Z0-9_-]*)/g;
+/** Extract #word tokens from a string. Returns lowercased tag names without the #. */
+function extractExplicitTags(text) {
+    const tags = [];
+    let match;
+    const re = new RegExp(HASHTAG_PATTERN.source, "g");
+    while ((match = re.exec(text)) !== null) {
+        tags.push(match[1].toLowerCase());
+    }
+    return tags;
+}
+// ─── Core inference ───────────────────────────────────────────────────────────
+function matchFirst(text, rules) {
+    for (const rule of rules) {
+        if (rule.pattern.test(text))
+            return rule.value;
+    }
+    return null;
+}
+function deriveTags(title, description) {
+    const combined = `${title} ${description}`.toLowerCase();
+    const found = [];
+    for (const { keywords, tag } of TAG_KEYWORDS) {
+        if (keywords.some(kw => combined.includes(kw))) {
+            found.push(tag);
+        }
+    }
+    return found;
+}
+function deriveCategory(title, description) {
+    const combined = `${title} ${description}`;
+    const matched = matchFirst(combined, CATEGORY_PATTERNS.map(r => ({ pattern: r.pattern, value: r.category })));
+    return matched ?? "task";
+}
+function derivePriority(title, description) {
+    const combined = `${title} ${description}`;
+    const matched = matchFirst(combined, PRIORITY_PATTERNS.map(r => ({ pattern: r.pattern, value: r.priority })));
+    return matched ?? "normal";
+}
+function deriveEffort(title, description) {
+    const combined = `${title} ${description}`;
+    const matched = matchFirst(combined, EFFORT_PATTERNS.map(r => ({ pattern: r.pattern, value: r.effort })));
+    return matched ?? null;
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Infer tags, category, priority, and effort from a task's title and description.
+ * Tags are deduplicated and sorted: keyword-derived tags first (in table order),
+ * then explicit #tag tokens (alphabetical). The category is always included as a tag.
+ */
+export function extractMetadata(input) {
+    const title = input.title ?? "";
+    const description = input.description ?? "";
+    const explicitTags = extractExplicitTags(`${title} ${description}`);
+    const keywordTags = deriveTags(title, description);
+    // Merge: keyword tags first (preserving table order), then explicit tags alphabetical
+    const seen = new Set();
+    const tags = [];
+    for (const tag of keywordTags) {
+        if (!seen.has(tag)) {
+            seen.add(tag);
+            tags.push(tag);
+        }
+    }
+    for (const tag of [...explicitTags].sort()) {
+        if (!seen.has(tag)) {
+            seen.add(tag);
+            tags.push(tag);
+        }
+    }
+    const category = deriveCategory(title, description);
+    // Always include category as a tag
+    if (!seen.has(category)) {
+        tags.push(category);
+    }
+    const priority = derivePriority(title, description);
+    const effort = deriveEffort(title, description);
+    return { tags, category, priority, effort, explicitTags };
+}

package/dist/kanban/template.js

@@ -0,0 +1,145 @@
+// OpenKan — canonical task MDX template + helpers.
+// ─── Template ────────────────────────────────────────────────────────────────
+/**
+ * The canonical task MDX template.
+ * Agents fill this in when creating a new task via kanban_add without a description.
+ *
+ * The template uses placeholder comments so agents can detect
+ * unfilled sections via extractTemplate().
+ */
+export const TASK_MDX_TEMPLATE = `---
+title: {/* Task title — replace with a short, descriptive name */}
+column: todo
+order: 0
+state: idle
+status: idle
+agent: {/* Bizar agent ID, e.g. "mike" */}
+model: {/* optional provider/model override */}
+createdAt: {/* ISO timestamp */}
+updatedAt: {/* ISO timestamp */}
+tags: []
+category: task
+priority: normal
+effort: null
+archived: false
+---
+
+# {/\* Task title \*/}
+
+{/* Add the task title above, then fill in the sections below. */}
+
+## Goal
+
+{/* What does "done" look like? Describe the end state in 1-3 sentences.
+    Example: "Users can reset their password via a secure email link." */}
+
+## Context
+
+{/* Add background context, links to relevant issues/files, and why this task exists.
+    Example: "Related to #42 — the current reset flow has no rate limiting." */}
+
+## Acceptance criteria
+
+{/* Replace this checklist with concrete, testable conditions. */}
+- [ ] {/* Criterion 1 */}
+- [ ] {/* Criterion 2 */}
+- [ ] {/* Criterion 3 */}
+
+## Files to touch
+
+{/* List specific files/functions/UI components to change. */}
+{/* Example: src/auth/reset-password.ts, web/components/PasswordReset.tsx */}
+
+## Safety
+
+{/* Any non-functional requirements: performance, security, backwards compat, rollback plan. */}
+{/* Example: "Database migration must be reversible. Rate-limit to 5 attempts per IP." */}
+
+## Agent progress
+
+{/* Agents append timestamped one-liners here as they work.
+    Format: "- [YYYY-MM-DD HH:MM:SS] <tool or action description>" */}
+
+## MDX components
+
+{/* Available interactive components — embed in the task MDX when needed: */}
+
+{/* <Ask question="Your question here" /> */}
+{/* <Choice question="Pick one:" options={[{id:"a",label:"Option A"},{id:"b",label:"Option B"}]} /> */}
+{/* <Input label="Enter value" placeholder="e.g. foo" /> */}
+{/* <Confirm question="Proceed?" /> */}
+{/* <Preview tsx="<button>Click me</button>" /> */}
+`;
+/**
+ * Render the task template with field values filled in.
+ * Fields not provided retain their placeholder comments.
+ */
+export function renderTaskTemplate(fields) {
+    const { title, goal = "{/* Describe the goal of this task */}", context = "{/* Add context: why this task exists, links, background */}", acceptance = ["{/* Acceptance criterion */}"], safety = [], tags = [], } = fields;
+    const acceptanceLines = acceptance
+        .map(c => (c.startsWith("- [ ]") ? c : `- [ ] ${c}`))
+        .join("\n");
+    const safetyLines = safety.length > 0
+        ? safety.map(s => (s.startsWith("-") ? s : `- ${s}`)).join("\n")
+        : "{/* Safety considerations (optional) */}";
+    return `---
+title: ${title}
+column: todo
+order: 0
+state: idle
+status: idle
+agent:
+model:
+createdAt: ${new Date().toISOString()}
+updatedAt: ${new Date().toISOString()}
+tags: [${tags.map(t => `"${t}"`).join(", ")}]
+category: task
+priority: normal
+effort: null
+archived: false
+---
+
+# ${title}
+
+## Goal
+
+${goal}
+
+## Context
+
+${context}
+
+## Acceptance criteria
+
+${acceptanceLines}
+
+## Files to touch
+
+{/* List files to change */}
+
+## Safety
+
+${safetyLines}
+
+## Agent progress
+
+{/* Agents append progress notes here */}
+`;
+}
+// ─── Placeholder detection ──────────────────────────────────────────────────
+/**
+ * Returns true if the MDX still contains unfilled placeholder comments.
+ * Used by kanban_add to detect "empty template" state.
+ */
+export function extractTemplate(mdx) {
+    return /\{\/\*.*?\*\/\}/s.test(mdx);
+}
+// ─── Parse hints (for frontend help panel) ─────────────────────────────────
+/** Hints shown in the frontend template help panel. */
+export const TEMPLATE_PARSE_HINTS = [
+    "<Ask> — Ask the user a single structured question; blocks until answered",
+    "<Choice> — Present radio options; user picks one",
+    "<Input> — Free-form text input from the user",
+    "<Confirm> — Yes/no confirmation from the user",
+    "<Preview> — Inline interactive TSX preview (live in the browser)",
+];

package/dist/kanban/tsx-sandbox.js

@@ -0,0 +1,187 @@
+// OpenKan — TSX compile + sandbox iframe HTML builder.
+// ─── Hook detection (compile-time safety) ────────────────────────────────────
+const HOOK_PATTERN = /\buse[A-Z][a-zA-Z0-9_]*/;
+const BUILTIN_FUNCTIONS = new Set([
+    "Button", "Card", "Row", "Column", "Text", "Heading", "Image", "ColorSwatch", "Code",
+    "h", "render", "respond",
+]);
+function checkHooks(source) {
+    // Find all useXXX identifiers that aren't in BUILTIN_FUNCTIONS
+    const matches = source.matchAll(/\buse[A-Z][a-zA-Z0-9_]*/g);
+    for (const m of matches) {
+        const name = m[0];
+        if (!BUILTIN_FUNCTIONS.has(name)) {
+            return `Hooks (${name}) are not supported in sandbox TSX. Use plain functions instead.`;
+        }
+    }
+    return null;
+}
+// ─── Compile TSX ─────────────────────────────────────────────────────────────
+const MAX_BYTES_DEFAULT = 32768;
+export async function compileTsx(source, opts) {
+    const maxBytes = opts?.maxBytes ?? MAX_BYTES_DEFAULT;
+    if (Buffer.byteLength(source, "utf-8") > maxBytes) {
+        return { error: `TSX source exceeds ${maxBytes} bytes limit.` };
+    }
+    const hookError = checkHooks(source);
+    if (hookError)
+        return { error: hookError };
+    try {
+        // Lazy import sucrase
+        const { default: sucrase } = await import("sucrase");
+        const result = sucrase.transform(source, {
+            transforms: ["typescript", "jsx"],
+            production: false,
+            // Map JSX to the runtime's h() function so we don't need React.
+            jsxPragma: "h",
+            jsxFragmentPragma: "Fragment",
+        });
+        let js = result.code;
+        // Defensive: if any React.createElement leaked through, replace it.
+        js = js.replace(/React\.createElement\b/g, "h")
+            .replace(/React\.Fragment\b/g, "Fragment");
+        if (Buffer.byteLength(js, "utf-8") > maxBytes * 2) {
+            return { error: `Compiled JS exceeds ${maxBytes * 2} bytes after transpilation.` };
+        }
+        return { js };
+    }
+    catch (e) {
+        return { error: `Compile error: ${e?.message ?? String(e)}` };
+    }
+}
+// ─── BUILTIN_LIBRARY ─────────────────────────────────────────────────────────
+const BUILTIN_LIBRARY = `
+const Button = (props) => h('button', { onClick: props.onClick, class: 'ok-btn', type: 'button' }, props.label ?? props.children);
+const Card = (props) => h('div', { class: 'ok-card' }, props.children);
+const Row = (props) => h('div', { class: 'ok-row', style: 'display:flex;gap:8px;align-items:center' }, props.children);
+const Column = (props) => h('div', { class: 'ok-col', style: 'display:flex;flex-direction:column;gap:8px' }, props.children);
+const Text = (props) => h('span', { class: 'ok-text' }, props.children ?? props.text);
+const Heading = (props) => h('h3', { class: 'ok-heading' }, props.children ?? props.text);
+const Image = (props) => h('img', { class: 'ok-img', src: props.src, alt: props.alt ?? '' });
+const ColorSwatch = (props) => h('div', { class: 'ok-swatch', style: 'width:32px;height:32px;border-radius:4px;background:' + (props.color || '#ccc') });
+const Code = (props) => h('pre', { class: 'ok-code' }, h('code', {}, props.children ?? props.text));
+`;
+// ─── Runtime (tiny React-like, no hooks) ─────────────────────────────────────
+const RUNTIME = `
+// Minimal h() and render() runtime — no hooks, no reconciliation.
+// h(type, props, ...children) => vnode
+// render(vnode, root) => void
+function Fragment(props) { return props.children; }
+function h(type, props, ...children) {
+  return { type, props: props || {}, children: children.flat().filter(c => c != null && c !== false && c !== '') };
+}
+function render(vnode, root) {
+  if (typeof vnode === 'string' || typeof vnode === 'number') {
+    root.textContent = String(vnode);
+    return;
+  }
+  if (!vnode || !vnode.type) { root.textContent = ''; return; }
+  const el = document.createElement(vnode.type);
+  const { props, children } = vnode;
+  for (const [k, v] of Object.entries(props || {})) {
+    if (k === 'style' && typeof v === 'string') {
+      v.split(';').forEach(s => { const [pk, pv] = s.split(':'); if (pk && pv) el.style[pk.trim()] = pv.trim(); });
+    } else if (k.startsWith('on') && typeof v === 'function') {
+      el.addEventListener(k.slice(2).toLowerCase(), v);
+    } else if (k !== 'class') {
+      el.setAttribute(k, String(v));
+    }
+  }
+  if (props && props.class) el.className = props.class;
+  const childRoot = document.createDocumentFragment();
+  for (const child of children || []) {
+    render(child, childRoot);
+    el.appendChild(childRoot);
+  }
+  root.appendChild(el);
+}
+function respond(value) {
+  parent.postMessage({ type: 'openkan:respond', version: 1, value }, '*');
+}
+`;
+// ─── Sandbox HTML builder ─────────────────────────────────────────────────────
+function esc(s) {
+    return s
+        .replace(/<\/script>/gi, "<\\/script>")
+        .replace(/<\/iframe>/gi, "<\\/iframe>")
+        .replace(/`/g, "\\`")
+        .replace(/\\/g, "\\\\");
+}
+export function buildSandboxHtml(js, propsJson) {
+    const escapedJs = esc(js);
+    const escapedProps = esc(propsJson);
+    // Wrap user code: the user's component is assigned to window
+    const wrappedJs = `\
+const App = (function() {
+${escapedJs}
+})();
+window.render = function(props) {
+  const root = document.getElementById('root');
+  root.innerHTML = '';
+  const v = App(typeof props === 'string' ? JSON.parse(props) : props);
+  render(v, root);
+};
+window.addEventListener('message', function(e) {
+  if (e.data && e.data.type === 'openkan:props' && e.data.version === 1) {
+    try {
+      window.render(e.data.props);
+    } catch(err) {
+      document.body.textContent = 'Render error: ' + err.message;
+    }
+  }
+});
+`;
+    return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>preview</title>
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:system-ui,sans-serif;padding:16px;background:#fafafa}
+.ok-btn{background:#2563eb;color:#fff;border:none;padding:8px 16px;border-radius:4px;cursor:pointer;font-size:14px}
+.ok-btn:hover{background:#1d4ed8}
+.ok-card{border:1px solid #e5e7eb;border-radius:8px;padding:16px;background:#fff}
+.ok-row{display:flex;gap:8px;align-items:center}
+.ok-col{display:flex;flex-direction:column;gap:8px}
+.ok-text{font-size:14px;color:#374151}
+.ok-heading{font-size:18px;font-weight:600;color:#111}
+.ok-img{max-width:100%;border-radius:4px}
+.ok-swatch{border-radius:4px}
+.ok-code{background:#1f2937;color:#f9fafb;padding:12px;border-radius:6px;overflow-x:auto;font-size:13px}
+</style>
+<script>${BUILTIN_LIBRARY}</script>
+<script>${RUNTIME}</script>
+<script>
+window.ok = { Button, Card, Row, Column, Text, Heading, Image, ColorSwatch, Code, respond, h, render };
+try {
+  ${wrappedJs}
+} catch(e) {
+  document.body.textContent = 'Preview error: ' + e.message;
+}
+</script>
+</head>
+<body>
+<div id="root"></div>
+<script>
+// Initial props from server
+try { window.render && window.render(${escapedProps || '{}'}); } catch(e) {}
+</script>
+</body>
+</html>`;
+}
+// ─── Full preview pipeline ─────────────────────────────────────────────────────
+export async function buildPreview(source, props) {
+    const compileResult = await compileTsx(source);
+    if (compileResult.error)
+        return { error: compileResult.error };
+    const js = compileResult.js;
+    const propsJson = JSON.stringify(props ?? {});
+    try {
+        const sandboxHtml = buildSandboxHtml(js, propsJson);
+        return { js, sandboxHtml };
+    }
+    catch (e) {
+        return { error: `Sandbox error: ${e?.message ?? String(e)}` };
+    }
+}