@w3kits-com/plugin-opendesign 0.1.8 → 0.1.10

package/dist/__w3kits/assets/design-templates/live-artifact/references/artifact-schema.md

@@ -0,0 +1,99 @@
+# Live Artifact Schema Reference
+
+Live artifacts are stored as daemon-owned project files under `.live-artifacts/<artifactId>/`. Agents author the source files, then register them through daemon tooling. The daemon assigns IDs, project scope, timestamps, run scope, and refresh status.
+
+## Source files
+
+| File | Owner | Purpose |
+| --- | --- | --- |
+| `artifact.json` | agent-authored input, daemon-validated | Artifact metadata, preview settings, document metadata, and source descriptors. Must not contain daemon-owned fields. |
+| `template.html` | agent-authored | `html_template_v1` template used to render the preview. |
+| `data.json` | agent-authored then refresh-runner-updated | Canonical preview data. API `document.dataJson` is only a derived cache. |
+| `provenance.json` | agent-authored then refresh-runner-updated | Source summary and generation notes. |
+| `index.html` | daemon-derived | Generated preview output. Do not treat as source of truth. |
+
+## Create/update input
+
+`artifact.json` should match `LiveArtifactCreateInput` or `LiveArtifactUpdateInput` from `packages/contracts/src/api/live-artifacts.ts`.
+
+Allowed agent-owned top-level fields:
+
+- `title`
+- `slug`
+- `sessionId`
+- `pinned`
+- `status`
+- `preview`
+- `document`
+
+Daemon-owned fields are rejected in agent input:
+
+- `id`
+- `projectId`
+- `createdAt`
+- `updatedAt`
+- `createdByRunId`
+- `schemaVersion`
+- `refreshStatus`
+- `lastRefreshedAt`
+
+## HTML document contract
+
+MVP documents use `html_template_v1`:
+
+```json
+{
+  "format": "html_template_v1",
+  "templatePath": "template.html",
+  "generatedPreviewPath": "index.html",
+  "dataPath": "data.json",
+  "dataJson": {}
+}
+```
+
+`template.html + data.json` is rendered by the daemon into `index.html` and the preview route.
+
+### Binding rules
+
+- Use escaped interpolation: `{{data.path.to.value}}`.
+- Paths must start with `data` and use dot-separated keys; numeric array indexes are allowed as path segments.
+- Supported structural directive: `data-od-repeat="item in data.items"` for one-level array repeats.
+- Nested repeats, conditionals, filters, helper functions, partials, and expression evaluation are not supported.
+- Raw HTML insertion is forbidden: no triple braces, ampersand interpolation, `data-od-html`, `data-od-raw`, or equivalent.
+- Interpolation in text and ordinary attributes is HTML-escaped by default.
+- Do not interpolate inside tag names, attribute names, comments, `<script>`, `<style>`, `<iframe srcdoc>`, event-handler attributes, or unsupported URL-bearing attributes.
+
+## Bounded JSON limits
+
+All persisted JSON values must fit the shared bounded JSON envelope:
+
+| Limit | Value |
+| --- | ---: |
+| Maximum object/array depth | 8 |
+| Maximum keys per object | 100 |
+| Maximum array length | 500 |
+| Maximum string length | 16 KiB |
+| Maximum serialized JSON size | 256 KiB |
+
+Forbidden keys anywhere in persisted JSON include `raw`, `rawResponse`, `payload`, `body`, `headers`, `cookie`, `authorization`, `token`, `secret`, `credential`, and `password`.
+
+## Minimal static artifact input
+
+```json
+{
+  "title": "Release Status",
+  "preview": { "type": "html", "entry": "index.html" },
+  "document": {
+    "format": "html_template_v1",
+    "templatePath": "template.html",
+    "generatedPreviewPath": "index.html",
+    "dataPath": "data.json",
+    "dataJson": {
+      "summary": {
+        "title": "Release Status",
+        "status": "On track"
+      }
+    }
+  }
+}
+```

package/dist/__w3kits/assets/design-templates/live-artifact/references/connector-policy.md

@@ -0,0 +1,119 @@
+# Connector Policy Reference
+
+Live artifacts may use connector or local data, but they must persist only compact, preview-oriented data and provenance. Never persist credentials or raw provider envelopes inside live artifact files.
+
+## Connector safety model
+
+Connector tools are classified by side effect and approval requirement:
+
+- `read` + `auto`: eligible for agent preview and potential refresh.
+- `write` + `confirm`: not refreshable; requires explicit user confirmation if exposed later.
+- `destructive` + `disabled`: never refreshable.
+- `unknown` + `confirm` or `disabled`: fail closed until classified.
+
+If a tool name, scope, or description suggests write/create/update/delete/admin/send/post/manage behavior, treat it as write-capable unless the daemon catalog explicitly proves otherwise. Destructive hints must be disabled for refresh.
+
+## Execution boundaries
+
+- Use daemon wrapper commands or `/api/tools/connectors/*`; do not call provider APIs directly from the artifact workflow when a daemon connector exists.
+- Tool endpoints require the injected `OD_TOOL_TOKEN`; do not invent or pass `projectId`.
+- Agent calls and refresh-runner calls must share the same daemon connector execution service.
+- Re-check connector status, allowlists, current scopes, tool safety, and refresh eligibility at execution time.
+- For connector-backed refresh, saved `connectorId`, `accountLabel`, tool name, input shape, and approval policy must still match current connector state.
+
+## Connector listing
+
+List connectors before using connector-backed data:
+
+```bash
+"$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
+```
+
+The compact result includes each connector's `id`, display metadata, `status`, optional `accountLabel`, and callable tool summaries with `name`, `description`, `safety`, and `inputSchema`. Use this output to select a connector and tool; do not guess tool names.
+
+Only execute tools from connectors whose status is `connected`. Local/public connectors may already be connected by the daemon; OAuth-backed connectors must be connected by the user through the UI before agent execution.
+
+If the user already named a connector or app, treat that as the intended data source. For example, “create a Notion live artifact” means: list connectors, find `notion`, and if it is `connected`, use its read-only tools instead of asking where the Notion data comes from. Ask a follow-up only when the matching connector is missing/unconnected, when several connected matches are equally plausible, or when there is no searchable topic/page/database clue in the user’s request.
+
+For Notion, prefer this selection order:
+
+1. Use `notion.notion_search` with a concise query derived from the user’s requested artifact/topic.
+2. Use `notion.notion_fetch_database` only when the user provided a database id or a prior search result identifies a specific database.
+3. If the user simply says “Notion live artifact” with no topic, ask what Notion page/database/topic to visualize or whether to search broadly.
+
+## Connector execution
+
+Create a bounded JSON object input file that matches the selected tool's `inputSchema`, then execute through the wrapper:
+
+```bash
+"$OD_NODE_BIN" "$OD_BIN" tools connectors execute --connector "$CONNECTOR_ID" --tool "$TOOL_NAME" --input input.json
+```
+
+The wrapper reads `OD_NODE_BIN`, `OD_BIN`, `OD_DAEMON_URL`, and `OD_TOOL_TOKEN`, sends the request to `/api/tools/connectors/execute`, and prints compact JSON. Successful output includes `connectorId`, optional `accountLabel`, `toolName`, `safety`, `outputSummary`, redacted `output`, and daemon metadata. On failure, fix the input/schema/connection issue and retry; do not bypass connector validation with direct provider calls.
+
+Execution is fail-closed:
+
+- connector and tool IDs must be in the daemon catalog allowlist;
+- the connector must still be connected and not disabled;
+- current runtime safety must be `read` + `auto` for agent execution;
+- input must match the current tool schema;
+- run rate limits and total call limits apply;
+- output is size-bounded and redacted before the agent receives it.
+
+Use execution output as an intermediate source only. Normalize it into `data.json` and provenance, keeping only fields the preview needs.
+
+## Read-only refresh rules
+
+Connector-backed live artifact refresh is allowed only for tools that remain read-only and refresh-eligible at refresh time. A saved refresh source must include non-sensitive connector metadata and permission state, for example:
+
+```json
+{
+  "type": "connector_tool",
+  "toolName": "github.public_repo_summary",
+  "input": { "owner": "open-design", "repo": "open-design" },
+  "connector": {
+    "connectorId": "github_public",
+    "accountLabel": "public",
+    "toolName": "github.public_repo_summary"
+  },
+  "outputMapping": {
+    "dataPaths": [{ "from": "summary", "to": "repository" }],
+    "transform": "metric_summary"
+  },
+  "refreshPermission": "manual_refresh_granted_for_read_only"
+}
+```
+
+During refresh, the daemon revalidates `connectorId`, `accountLabel`, tool name, saved input schema, and allowlist membership. If anything drifts, the refresh fails without changing the previous valid preview.
+
+Never mark write, destructive, unknown, confirmation-required, disabled, unconnected, or schema-drifted connector tools as refreshable.
+
+## Persistence rules
+
+Persist only:
+
+- compact normalized values needed by the preview in `data.json`;
+- high-level provenance in `provenance.json`;
+- connector references and refresh metadata in `sourceJson`.
+
+Never persist:
+
+- OAuth tokens, API keys, cookies, headers, authorization values, or session material;
+- raw provider HTTP bodies, envelopes, payloads, or full responses;
+- credential-like values under alternate names;
+- connector credentials under `.live-artifacts/`.
+
+Credential storage is daemon-controlled and outside project artifact directories. Artifacts may contain connector IDs and non-sensitive account labels only.
+
+## Credential handling constraints
+
+- Do not ask the user for connector secrets inside the artifact workflow.
+- Do not ask the user to re-specify a data source that is already named and connected; inspect the connector catalog first.
+- Do not write OAuth material, API keys, cookies, sessions, HTTP request metadata, or provider auth state into `artifact.json`, `data.json`, `provenance.json`, tile JSON, snapshots, refresh history, or `.live-artifacts/`.
+- Do not include secret-like values in connector tool inputs or source metadata. If a connector requires credentials, the daemon-owned connector UI/storage must handle them outside project artifacts.
+- Safe persisted connector references are limited to catalog IDs, tool names, non-sensitive account labels, selected normalized output fields, and concise provenance notes.
+- If connector output contains unredacted sensitive or envelope-like fields, stop and return a validation/safety error instead of storing it.
+
+## Output protection
+
+Connector outputs must be bounded and redacted before returning to agents or entering artifact files. Use compact summaries and selected fields. If redaction cannot prove the result is safe, fail with a validation error instead of storing it.

package/dist/__w3kits/assets/design-templates/live-artifact/references/refresh-contract.md

@@ -0,0 +1,78 @@
+# Refresh Contract Reference
+
+Refresh updates live artifact data without redesigning the presentation. The refresh runner updates `data.json`, provenance, and audit history; it does not allow arbitrary template rewrites.
+
+## Refreshable source metadata
+
+Refreshable documents use `sourceJson`:
+
+```json
+{
+  "type": "connector_tool",
+  "toolName": "list_releases",
+  "input": {},
+  "connector": {
+    "connectorId": "github",
+    "accountLabel": "example/org",
+    "toolName": "list_releases"
+  },
+  "outputMapping": {
+    "dataPaths": [{ "from": "items", "to": "releases" }],
+    "transform": "compact_table"
+  },
+  "refreshPermission": "manual_refresh_granted_for_read_only"
+}
+```
+
+Supported source types:
+
+- `local_file`
+- `daemon_tool`
+- `connector_tool`
+
+Supported output transforms:
+
+- `identity`
+- `compact_table`
+- `metric_summary`
+
+## Source execution model
+
+- `refreshPermission` is retained for backward compatibility with older artifacts, but the refresh runner does not require a separate connector approval step.
+- If a safe source descriptor exists, manual refresh executes it through daemon-owned local or connector wrappers.
+- Write, destructive, unknown, disabled, unconnected, or schema-drifted connector tools should not be authored as refresh sources.
+
+## Connector-backed refresh
+
+Connector-backed refresh sources use the same connector execution service as agent-initiated connector calls. Do not call provider APIs directly from refresh logic or from skill-authored scripts.
+
+Before creating a connector-backed refresh source:
+
+1. List connectors with `"$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact`.
+2. If the user named a connector/source and it is connected, select that connector directly instead of asking where the source is. Then select a tool whose safety is `read` + `auto` and whose catalog metadata marks it refresh-eligible.
+3. Execute once with `"$OD_NODE_BIN" "$OD_BIN" tools connectors execute --connector <id> --tool <name> --input input.json` to produce compact normalized preview data.
+4. Store only non-sensitive connector references, the bounded input object, output mapping, and compatibility `refreshPermission` in `sourceJson`.
+
+On each refresh, the daemon must re-check connector status, account label, allowlist membership, input schema, and output protection. If any check fails or output protection rejects the result, refresh fails all-or-nothing and preserves the previous valid preview.
+
+Persisted connector refresh metadata may include `connectorId`, `toolName`, non-sensitive `accountLabel`, bounded `input`, `outputMapping`, and compatibility `refreshPermission`. It must not include credentials, auth/session material, raw provider envelopes, or unbounded provider responses.
+
+## Commit behavior
+
+Refresh is all-or-nothing:
+
+1. Acquire one active refresh lock per artifact.
+2. Execute each refreshable source with timeouts and current safety checks.
+3. Build candidate `data.json`, provenance, and preview.
+4. Validate all candidates with the same schemas used for create/update.
+5. Commit only if every refreshable source succeeds.
+6. Preserve the previous valid preview if any step fails.
+
+Refresh IDs must be monotonic so stale runs cannot overwrite newer committed data.
+
+## Audit storage
+
+- Append compact records to `refreshes.jsonl`.
+- Successful refresh snapshots live under `snapshots/<refreshId>/` and may include `data.json` and provenance.
+- Failed refreshes are summarized in `refreshes.jsonl` without leaking raw provider output or credentials.
+- On daemon startup, stale running refreshes should be marked failed or timed out while preserving the last valid preview.

package/dist/__w3kits/assets/design-templates/live-dashboard/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: live-dashboard
+description: |
+  Notion-style team dashboard rendered as a Live Artifact. A single-page,
+  self-contained HTML dashboard with KPIs, a 7-day sparkline, a real-time
+  activity feed and a linked-database task table — wired to Notion via the
+  Composio connector catalog. Refreshes on demand and when the artifact
+  is opened. Falls back to seeded mock data when no connector is bound,
+  so it works offline / in screenshots / in the picker preview.
+triggers:
+  - "team dashboard"
+  - "notion dashboard"
+  - "live dashboard"
+  - "ops dashboard"
+  - "team workspace dashboard"
+  - "团队仪表盘"
+  - "Notion 仪表盘"
+  - "Live Artifact dashboard"
+od:
+  mode: prototype
+  platform: desktop
+  scenario: operation
+  featured: 1
+  fidelity: high
+  preview:
+    type: html
+    entry: index.html
+    reload: debounce-100
+  design_system:
+    requires: true
+    sections: [color, typography, layout, components, anti-patterns]
+  craft:
+    requires: [typography, color, anti-ai-slop, motion-discipline, state-coverage]
+  inputs:
+    - name: workspace_name
+      type: string
+      required: true
+    - name: page_title
+      type: string
+      default: "Team Dashboard"
+    - name: connector
+      type: enum
+      values: [notion, linear, stripe, posthog, mock]
+      default: notion
+    - name: refresh_seconds
+      type: integer
+      default: 30
+      min: 10
+      max: 300
+    - name: stale_after_seconds
+      type: integer
+      default: 90
+      min: 30
+      max: 600
+    - name: kpi_count
+      type: enum
+      values: [2, 4, 6]
+      default: 4
+    - name: include_activity_feed
+      type: boolean
+      default: true
+    - name: include_task_table
+      type: boolean
+      default: true
+  parameters:
+    - name: accent_hue
+      type: hue
+      default: 198          # Notion-blue baseline
+      range: [0, 360]
+    - name: surface_warmth
+      type: spacing
+      default: 0
+      range: [-12, 24]      # nudges sidebar / soft-bg L* in OKLch
+    - name: density
+      type: spacing
+      default: 18
+      range: [8, 36]
+    - name: display_scale
+      type: font-scale
+      default: 1.0
+      range: [0.85, 1.4]
+  outputs:
+    primary: index.html
+    secondary: [connectors.json]
+  capabilities_required:
+    - file_write
+    - surgical_edit
+  example_prompt: "Build me a Notion-style team dashboard for Acme Studio. KPIs: total tasks, done this week, active members, docs in review. Wire it to the Notion connector and let it refresh on demand."
+---
+
+# Live Dashboard
+
+You are a senior product-designer-engineer building a **Live Artifact** —
+an HTML page that behaves like a working dashboard, not a mockup. Your
+output ships, not only renders.
+
+## Pre-flight (must complete before emitting any HTML)
+
+1. `Read assets/template.html` — start from this skeleton verbatim. Do
+   not rebuild the shell from scratch. Override only what the user's
+   brief or the active DESIGN.md require.
+2. `Read references/layouts.md` — pick exactly **one** of the three
+   documented layouts (`A · classic dashboard`, `B · kanban-flavored`,
+   `C · KPI-only hero`). State your choice in your reply.
+3. `Read references/components.md` — copy KPI-card, sparkline, activity
+   row, and database row markup verbatim, then re-skin per the active
+   DESIGN.md. Do not invent new component shapes.
+4. `Read references/connectors.md` — only when `inputs.connector !== mock`.
+   Emit a sibling `connectors.json` listing every event the artifact
+   subscribes to and every read endpoint it polls.
+5. `Read references/checklist.md` — every P0 row must be true before
+   you emit `index.html`. Quote each P0 row inline in your reply with
+   `[x]` or `[ ]`. Do not emit while any P0 is unchecked.
+
+## Build order
+
+1. **Lock visual direction** from the active `DESIGN.md`. Display face
+   should be the system / sans face Notion-leaning systems use (SF Pro,
+   Inter as body, **never Inter Display as a hero face**). Body 14/22.
+2. **Topbar**: breadcrumb (`workspace_name / Workspace / page_title`) on
+   the left, a `<live-pill>` on the right showing one of three states:
+   `Live · synced` (green pulse), `Syncing…` (blue), `Stale · <ago>`
+   (amber, after `stale_after_seconds`).
+3. **Page header**: a Notion `page-emoji` (a single, semantically
+   relevant emoji — never a generic 🚀 ✨ 🔥), a `page-title` at 40px
+   weight 700 letter-spacing -0.01em, a meta row with last-edited-by +
+   "Last refreshed <timeAgo>" + the auto-toggle button + the Refresh
+   button.
+4. **Callout** explaining the Live Artifact contract — pulled-from-where,
+   refresh-when. One line. No marketing language.
+5. **KPI grid**: respect `inputs.kpi_count`. 1px hairline grid, no
+   shadows, no rounded internal cards. Numbers `font-variant-numeric:
+   tabular-nums`, weight 600, letter-spacing -0.01em. Each KPI gets a
+   small grey delta line (`↑ 6 vs last week`).
+6. **Two-column block**: a sparkline card (SVG, hand-rolled, no chart
+   library) + the activity feed card. Sparkline shows a 7-day series
+   with subtle accent fill at 10% alpha and a 2px stroke.
+7. **Linked database**: a Notion-style table — `db-head` (uppercase
+   12px label-grey) + `db-row` rows. Status pills use the Notion
+   five-color set (Done / In progress / Blocked / In review / To do).
+   Person chips use a colored 18px round avatar with two-letter
+   initials.
+8. **Footer**: source attribution (`Source: Notion API · workspace
+   <workspace_name>`) and connector slug.
+
+## Live behavior (the part that earns the "Live" in Live Artifact)
+
+Wire these in a single `<script>` block at the bottom of `index.html`:
+
+- `init()` runs `refresh({silent: true})` 600ms after mount — the
+  "refresh on open" semantic.
+- The Refresh button calls `refresh({silent: false})`. Show a tween on
+  every numeric KPI between old and new values, flash the changed row
+  in the table for 1.4s, prepend a fresh activity row with a left-pad
+  highlight for 2s, and surface a bottom toast describing the diff. The
+  tween/flash hooks are already wired in `assets/template.html`
+  (`tweenText()` + `.flash` + `.db-row.changed` + `.feed-row.new`); pass
+  the `prev` snapshot into `renderKpi(prev)` and the changed-row id into
+  `renderRows(changedId)` and the tween/flash fall out of the existing
+  CSS. Do not rebuild this from scratch.
+- `setInterval(refresh, refresh_seconds * 1000)` when Auto is on.
+- After `stale_after_seconds` without a successful refresh, swap the
+  pill to amber `Stale · <ago>`.
+- Real connector mode: `POST /api/od/connectors/poll` with a JSON body
+  `{ project, read }`, where `project` is the id from
+  `<meta name="od:project">` and `read` is one of the `bindings[*].reads[].id`
+  values declared in `connectors.json`. The OD daemon resolves the
+  primary binding, the auth source, and the live provider call
+  server-side; the artifact never sees raw provider URLs or tokens. See
+  `references/connectors.md` for the wire shape and the daemon
+  resolution order. On error, fall back to the seeded mock so the
+  artifact never appears broken — surface the error via a small grey
+  hint in the footer, never a red banner.
+
+## Self-critique (must run before emitting)
+
+Score the artifact on the five dimensions inherited from `skills/critique/`:
+**Philosophy · Hierarchy · Detail · Function · Innovation**.
+
+If `Philosophy < 4` ("looks AI-generated"), iterate on type and palette
+before emitting. Quote the offending element in your reply and explain
+the fix. Do not emit if any dimension scores below 3.
+
+## Hard nos (anti-AI-slop)
+
+- No purple→pink gradient header.
+- No emoji icon strip across the top of the page.
+- No rounded card with a 4px left-border accent.
+- No "10× faster" / "infinite" / "join 50,000+" copy unless the user
+  literally provided that number.
+- No glassmorphism / backdrop-blur on KPI cards.
+- No colored progress bars under KPI numbers; the delta line is enough.
+- Inter is body-only. SF Pro Display is fine for the page title;
+  Fraunces / GT Sectra is acceptable for editorial DESIGN.md variants.
+
+## Output contract
+
+- `index.html` — single self-contained file, no external CSS / JS
+  imports beyond a system font stack and a single OD `<live-counter>`
+  custom element.
+- `connectors.json` — when `inputs.connector !== mock`. See
+  `references/connectors.md` for the schema.
+- Both files in the project cwd. Do not write anywhere else.