saeeol 1.2.9 → 1.3.1

package/test/fixture/skills/cloudflare/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: cloudflare
+description: Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task.
+references:
+  - workers
+  - pages
+  - d1
+  - durable-objects
+  - workers-ai
+---
+
+# Cloudflare Platform Skill
+
+Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
+
+## Quick Decision Trees
+
+### "I need to run code"
+
+```
+Need to run code?
+├─ Serverless functions at the edge → workers/
+├─ Full-stack web app with Git deploys → pages/
+├─ Stateful coordination/real-time → durable-objects/
+├─ Long-running multi-step jobs → workflows/
+├─ Run containers → containers/
+├─ Multi-tenant (customers deploy code) → workers-for-platforms/
+├─ Scheduled tasks (cron) → cron-triggers/
+├─ Lightweight edge logic (modify HTTP) → snippets/
+├─ Process Worker execution events (logs/observability) → tail-workers/
+└─ Optimize latency to backend infrastructure → smart-placement/
+```
+
+### "I need to store data"
+
+```
+Need storage?
+├─ Key-value (config, sessions, cache) → kv/
+├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
+├─ Object/file storage (S3-compatible) → r2/
+├─ Message queue (async processing) → queues/
+├─ Vector embeddings (AI/semantic search) → vectorize/
+├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
+├─ Secrets management → secrets-store/
+├─ Streaming ETL to R2 → pipelines/
+└─ Persistent cache (long-term retention) → cache-reserve/
+```
+
+### "I need AI/ML"
+
+```
+Need AI?
+├─ Run inference (LLMs, embeddings, images) → workers-ai/
+├─ Vector database for RAG/search → vectorize/
+├─ Build stateful AI agents → agents-sdk/
+├─ Gateway for any AI provider (caching, routing) → ai-gateway/
+└─ AI-powered search widget → ai-search/
+```
+
+### "I need networking/connectivity"
+
+```
+Need networking?
+├─ Expose local service to internet → tunnel/
+├─ TCP/UDP proxy (non-HTTP) → spectrum/
+├─ WebRTC TURN server → turn/
+├─ Private network connectivity → network-interconnect/
+├─ Optimize routing → argo-smart-routing/
+├─ Optimize latency to backend (not user) → smart-placement/
+└─ Real-time video/audio → realtimekit/ or realtime-sfu/
+```
+
+### "I need security"
+
+```
+Need security?
+├─ Web Application Firewall → waf/
+├─ DDoS protection → ddos/
+├─ Bot detection/management → bot-management/
+├─ API protection → api-shield/
+├─ CAPTCHA alternative → turnstile/
+└─ Credential leak detection → waf/ (managed ruleset)
+```
+
+### "I need media/content"
+
+```
+Need media?
+├─ Image optimization/transformation → images/
+├─ Video streaming/encoding → stream/
+├─ Browser automation/screenshots → browser-rendering/
+└─ Third-party script management → zaraz/
+```
+
+### "I need infrastructure-as-code"
+
+```
+Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)
+```
+
+## Product Index
+
+### Compute & Runtime
+
+| Product | Reference |
+|---|---|
+| Workers | `references/workers/` |
+| Pages | `references/pages/` |
+| Pages Functions | `references/pages-functions/` |
+| Durable Objects | `references/durable-objects/` |
+| Workflows | `references/workflows/` |
+| Containers | `references/containers/` |
+| Workers for Platforms | `references/workers-for-platforms/` |
+| Cron Triggers | `references/cron-triggers/` |
+| Tail Workers | `references/tail-workers/` |
+| Snippets | `references/snippets/` |
+| Smart Placement | `references/smart-placement/` |
+
+### Storage & Data
+
+| Product | Reference |
+|---|---|
+| KV | `references/kv/` |
+| D1 | `references/d1/` |
+| R2 | `references/r2/` |
+| Queues | `references/queues/` |
+| Hyperdrive | `references/hyperdrive/` |
+| DO Storage | `references/do-storage/` |
+| Secrets Store | `references/secrets-store/` |
+| Pipelines | `references/pipelines/` |
+| R2 Data Catalog | `references/r2-data-catalog/` |
+| R2 SQL | `references/r2-sql/` |
+
+### AI & Machine Learning
+
+| Product | Reference |
+|---|---|
+| Workers AI | `references/workers-ai/` |
+| Vectorize | `references/vectorize/` |
+| Agents SDK | `references/agents-sdk/` |
+| AI Gateway | `references/ai-gateway/` |
+| AI Search | `references/ai-search/` |
+
+### Networking & Connectivity
+
+| Product | Reference |
+|---|---|
+| Tunnel | `references/tunnel/` |
+| Spectrum | `references/spectrum/` |
+| TURN | `references/turn/` |
+| Network Interconnect | `references/network-interconnect/` |
+| Argo Smart Routing | `references/argo-smart-routing/` |
+| Workers VPC | `references/workers-vpc/` |
+
+### Security
+
+| Product | Reference |
+|---|---|
+| WAF | `references/waf/` |
+| DDoS Protection | `references/ddos/` |
+| Bot Management | `references/bot-management/` |
+| API Shield | `references/api-shield/` |
+| Turnstile | `references/turnstile/` |
+
+### Media & Content
+
+| Product | Reference |
+|---|---|
+| Images | `references/images/` |
+| Stream | `references/stream/` |
+| Browser Rendering | `references/browser-rendering/` |
+| Zaraz | `references/zaraz/` |
+
+### Real-Time Communication
+
+| Product | Reference |
+|---|---|
+| RealtimeKit | `references/realtimekit/` |
+| Realtime SFU | `references/realtime-sfu/` |
+
+### Developer Tools
+
+| Product | Reference |
+|---|---|
+| Wrangler | `references/wrangler/` |
+| Miniflare | `references/miniflare/` |
+| C3 | `references/c3/` |
+| Observability | `references/observability/` |
+| Analytics Engine | `references/analytics-engine/` |
+| Web Analytics | `references/web-analytics/` |
+| Sandbox | `references/sandbox/` |
+| Workerd | `references/workerd/` |
+| Workers Playground | `references/workers-playground/` |
+
+### Infrastructure as Code
+
+| Product | Reference |
+|---|---|
+| Pulumi | `references/pulumi/` |
+| Terraform | `references/terraform/` |
+| API | `references/api/` |
+
+### Other Services
+
+| Product | Reference |
+|---|---|
+| Email Routing | `references/email-routing/` |
+| Email Workers | `references/email-workers/` |
+| Static Assets | `references/static-assets/` |
+| Bindings | `references/bindings/` |
+| Cache Reserve | `references/cache-reserve/` |

package/test/fixture/skills/index.json

@@ -0,0 +1,6 @@
+{
+  "skills": [
+    { "name": "agents-sdk", "description": "Cloudflare Agents SDK", "files": ["SKILL.md", "references/callable.md"] },
+    { "name": "cloudflare", "description": "Cloudflare Platform Skill", "files": ["SKILL.md"] }
+  ]
+}

package/test/fixture/tui-plugin.ts

@@ -0,0 +1,323 @@
+import { createSaeeolClient } from "@saeeol/sdk/v2"
+import { RGBA, type CliRenderer } from "@opentui/core"
+import { createPluginKeybind } from "../../src/cli/cmd/tui/context/plugin-keybinds"
+import type { HostPluginApi } from "../../src/cli/cmd/tui/plugin/slots"
+
+type Count = {
+  event_add: number
+  event_drop: number
+  route_add: number
+  route_drop: number
+  command_add: number
+  command_drop: number
+}
+
+function themeCurrent(): HostPluginApi["theme"]["current"] {
+  const a = RGBA.fromInts(0, 120, 240)
+  const b = RGBA.fromInts(120, 120, 120)
+  const c = RGBA.fromInts(230, 230, 230)
+  const d = RGBA.fromInts(120, 30, 30)
+  const e = RGBA.fromInts(140, 100, 40)
+  const f = RGBA.fromInts(20, 140, 80)
+  const g = RGBA.fromInts(20, 80, 160)
+  const h = RGBA.fromInts(40, 40, 40)
+  const i = RGBA.fromInts(60, 60, 60)
+  const j = RGBA.fromInts(80, 80, 80)
+  return {
+    primary: a,
+    secondary: b,
+    accent: a,
+    error: d,
+    warning: e,
+    success: f,
+    info: g,
+    text: c,
+    textMuted: b,
+    selectedListItemText: h,
+    background: h,
+    backgroundPanel: h,
+    backgroundElement: i,
+    backgroundMenu: i,
+    border: j,
+    borderActive: c,
+    borderSubtle: i,
+    diffAdded: f,
+    diffRemoved: d,
+    diffContext: b,
+    diffHunkHeader: b,
+    diffHighlightAdded: f,
+    diffHighlightRemoved: d,
+    diffAddedBg: h,
+    diffRemovedBg: h,
+    diffContextBg: h,
+    diffLineNumber: b,
+    diffAddedLineNumberBg: h,
+    diffRemovedLineNumberBg: h,
+    markdownText: c,
+    markdownHeading: c,
+    markdownLink: a,
+    markdownLinkText: g,
+    markdownCode: f,
+    markdownBlockQuote: e,
+    markdownEmph: e,
+    markdownStrong: c,
+    markdownHorizontalRule: b,
+    markdownListItem: a,
+    markdownListEnumeration: g,
+    markdownImage: a,
+    markdownImageText: g,
+    markdownCodeBlock: c,
+    syntaxComment: b,
+    syntaxKeyword: a,
+    syntaxFunction: g,
+    syntaxVariable: c,
+    syntaxString: f,
+    syntaxNumber: e,
+    syntaxType: a,
+    syntaxOperator: a,
+    syntaxPunctuation: c,
+    thinkingOpacity: 0.6,
+  }
+}
+
+type Opts = {
+  client?: HostPluginApi["client"] | (() => HostPluginApi["client"])
+  renderer?: HostPluginApi["renderer"]
+  count?: Count
+  keybind?: Partial<HostPluginApi["keybind"]>
+  tuiConfig?: HostPluginApi["tuiConfig"]
+  app?: Partial<HostPluginApi["app"]>
+  state?: {
+    ready?: HostPluginApi["state"]["ready"]
+    config?: HostPluginApi["state"]["config"]
+    provider?: HostPluginApi["state"]["provider"]
+    path?: HostPluginApi["state"]["path"]
+    vcs?: HostPluginApi["state"]["vcs"]
+    session?: Partial<HostPluginApi["state"]["session"]>
+    part?: HostPluginApi["state"]["part"]
+    lsp?: HostPluginApi["state"]["lsp"]
+    mcp?: HostPluginApi["state"]["mcp"]
+  }
+  theme?: {
+    selected?: string
+    has?: HostPluginApi["theme"]["has"]
+    set?: HostPluginApi["theme"]["set"]
+    install?: HostPluginApi["theme"]["install"]
+    mode?: HostPluginApi["theme"]["mode"]
+    ready?: boolean
+    current?: HostPluginApi["theme"]["current"]
+  }
+}
+
+export function createTuiPluginApi(opts: Opts = {}): HostPluginApi {
+  const kv: Record<string, unknown> = {}
+  const count = opts.count
+  const ctrl = new AbortController()
+  const own = createSaeeolClient({
+    baseUrl: "http://localhost:4096",
+  })
+  const fallback = () => own
+  const read =
+    typeof opts.client === "function"
+      ? opts.client
+      : opts.client
+        ? () => opts.client as HostPluginApi["client"]
+        : fallback
+  const client = () => read()
+  let depth = 0
+  let size: "medium" | "large" | "xlarge" = "medium"
+  const has = opts.theme?.has ?? (() => false)
+  let selected = opts.theme?.selected ?? "saeeol"
+  const key = {
+    match: opts.keybind?.match ?? (() => false),
+    print: opts.keybind?.print ?? ((name: string) => name),
+  }
+  const set =
+    opts.theme?.set ??
+    ((name: string) => {
+      if (!has(name)) return false
+      selected = name
+      return true
+    })
+  const renderer: CliRenderer = opts.renderer ?? {
+    ...Object.create(null),
+    once(this: CliRenderer) {
+      return this
+    },
+  }
+
+  function kvGet(name: string): unknown
+  function kvGet<Value>(name: string, fallback: Value): Value
+  function kvGet(name: string, fallback?: unknown) {
+    const value = kv[name]
+    if (value === undefined) return fallback
+    return value
+  }
+
+  return {
+    app: {
+      get version() {
+        return opts.app?.version ?? "0.0.0-test"
+      },
+    },
+    get client() {
+      return client()
+    },
+    event: {
+      on: () => {
+        if (count) count.event_add += 1
+        return () => {
+          if (!count) return
+          count.event_drop += 1
+        }
+      },
+    },
+    renderer,
+    slots: {
+      register: () => "fixture-slot",
+    },
+    plugins: {
+      list: () => [],
+      activate: async () => false,
+      deactivate: async () => false,
+      add: async () => false,
+      install: async () => ({
+        ok: false,
+        message: "not implemented in fixture",
+      }),
+    },
+    lifecycle: {
+      signal: ctrl.signal,
+      onDispose() {
+        return () => {}
+      },
+    },
+    command: {
+      register: () => {
+        if (count) count.command_add += 1
+        return () => {
+          if (!count) return
+          count.command_drop += 1
+        }
+      },
+      trigger: () => {},
+      show: () => {},
+    },
+    route: {
+      register: () => {
+        if (count) count.route_add += 1
+        return () => {
+          if (!count) return
+          count.route_drop += 1
+        }
+      },
+      navigate: () => {},
+      get current() {
+        return { name: "home" }
+      },
+    },
+    ui: {
+      Dialog: () => null,
+      DialogAlert: () => null,
+      DialogConfirm: () => null,
+      DialogPrompt: () => null,
+      DialogSelect: () => null,
+      Slot: () => null,
+      Prompt: () => null,
+      toast: () => {},
+      dialog: {
+        replace: () => {
+          depth = 1
+        },
+        clear: () => {
+          depth = 0
+          size = "medium"
+        },
+        setSize: (next) => {
+          size = next
+        },
+        get size() {
+          return size
+        },
+        get depth() {
+          return depth
+        },
+        get open() {
+          return depth > 0
+        },
+      },
+    },
+    keybind: {
+      ...key,
+      create:
+        opts.keybind?.create ??
+        ((defaults, over) => {
+          return createPluginKeybind(key, defaults, over)
+        }),
+    },
+    tuiConfig: opts.tuiConfig ?? {},
+    kv: {
+      get: kvGet,
+      set(name, value) {
+        kv[name] = value
+      },
+      get ready() {
+        return true
+      },
+    },
+    state: {
+      get ready() {
+        return opts.state?.ready ?? true
+      },
+      get config() {
+        return opts.state?.config ?? {}
+      },
+      get provider() {
+        return opts.state?.provider ?? []
+      },
+      get path() {
+        return opts.state?.path ?? { home: "", state: "", config: "", worktree: "", directory: "" }
+      },
+      get vcs() {
+        return opts.state?.vcs
+      },
+      session: {
+        count: opts.state?.session?.count ?? (() => 0),
+        diff: opts.state?.session?.diff ?? (() => []),
+        todo: opts.state?.session?.todo ?? (() => []),
+        messages: opts.state?.session?.messages ?? (() => []),
+        status: opts.state?.session?.status ?? (() => undefined),
+        permission: opts.state?.session?.permission ?? (() => []),
+        question: opts.state?.session?.question ?? (() => []),
+      },
+      part: opts.state?.part ?? (() => []),
+      lsp: opts.state?.lsp ?? (() => []),
+      mcp: opts.state?.mcp ?? (() => []),
+    },
+    theme: {
+      get current() {
+        return opts.theme?.current ?? themeCurrent()
+      },
+      get selected() {
+        return selected
+      },
+      has(name) {
+        return has(name)
+      },
+      set(name) {
+        return set(name)
+      },
+      async install(file) {
+        if (opts.theme?.install) return opts.theme.install(file)
+        throw new Error("base theme.install should not run")
+      },
+      mode() {
+        if (opts.theme?.mode) return opts.theme.mode()
+        return "dark"
+      },
+      get ready() {
+        return opts.theme?.ready ?? true
+      },
+    },
+  }
+}

package/test/fixture/tui-runtime.ts

@@ -0,0 +1,31 @@
+import { spyOn } from "bun:test"
+import path from "path"
+import { TuiConfig } from "../../src/cli/cmd/tui/config/tui"
+
+type PluginSpec = string | [string, Record<string, unknown>]
+
+export function mockTuiRuntime(dir: string, plugin: PluginSpec[], opts?: { plugin_enabled?: Record<string, boolean> }) {
+  process.env.SAEEOL_PLUGIN_META_FILE = path.join(dir, "plugin-meta.json")
+  const plugin_origins = plugin.map((spec) => ({
+    spec,
+    scope: "local" as const,
+    source: path.join(dir, "tui.json"),
+  }))
+  const wait = spyOn(TuiConfig, "waitForDependencies").mockResolvedValue()
+  const cwd = spyOn(process, "cwd").mockImplementation(() => dir)
+
+  const config: TuiConfig.Info = {
+    plugin,
+    plugin_origins,
+    ...(opts?.plugin_enabled && { plugin_enabled: opts.plugin_enabled }),
+  }
+
+  return {
+    config,
+    restore: () => {
+      cwd.mockRestore()
+      wait.mockRestore()
+      delete process.env.SAEEOL_PLUGIN_META_FILE
+    },
+  }
+}