design-playbook 0.12.0 → 0.14.0

package/codex/AGENTS.md

@@ -36,10 +36,14 @@ python packages/design-playbook/codex/install_skills.py --force
 #   @packages/design-playbook/skills/design-playbook/SKILL.md
 ```
 
-Manual MCP (only if not using `codex plugin add`):
+Register MCP directly (fallback when `codex plugin add` is unavailable):
+
+`codex plugin add` depends on a healthy codex marketplace subsystem. If `codex doctor`
+or `codex plugin marketplace list` fails (e.g. a stale marketplace source path), register
+the servers directly in `~/.codex/config.toml` (or your `CODEX_HOME`):
 
 ```toml
-# ~/.codex/config.toml
+# ~/.codex/config.toml  (or $CODEX_HOME/config.toml)
 [mcp_servers.design-playbook-preview]
 command = "python"
 args = ["<abs>/packages/design-playbook/mcp/preview/server.py"]
@@ -50,6 +54,16 @@ args = ["<abs>/packages/design-playbook/mcp/evidence/server.py"]
 # evidence also needs: pip install playwright && playwright install chromium
 ```
 
+Verify: `codex mcp list` should list both. `preview*` needs a system Edge/Chrome (the
+adapter spawns it via `--app=`); `observe*` needs Playwright + Chromium.
+
+> **`preview*` silently skips when `preview_prototype` is absent.** If preview does not
+> appear, the orchestrator probed `tools/list`, found no `preview_prototype`, and skipped
+> G5 - this is designed skip behaviour, not a crash. Confirm the tool is registered
+> (`codex mcp list`) before treating it as a preview failure. Codex end-to-end preview
+> smoke is not yet validated (v0.4.4 deferred the codex E2E smoke; only evidence/G6 was
+> server-level smoked).
+
 ## Load order
 
 1. `skills/design-playbook/SKILL.md`

package/design_playbook.py

@@ -0,0 +1,20 @@
+"""Namespace alias: absolute ``design_playbook.*`` imports inside this plugin.
+
+The plugin directory is ``design-playbook`` (hyphen), so Python's import
+system cannot load it under the identifier ``design_playbook`` — FileFinder
+matches directory names literally. This module aliases the package root onto
+``design_playbook.__path__`` so that, once the one bootstrap (ADR-0022) puts
+the package root on ``sys.path``, absolute imports such as
+``design_playbook.mcp.preview.integrity`` and
+``design_playbook.scripts.stages`` resolve to the real ``mcp/`` and
+``scripts/`` trees below.
+
+The alias also keeps the import seam namespaced: a bare ``mcp.*`` import
+would collide with the PyPI ``mcp`` SDK when the host has it installed.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+__path__ = [str(Path(__file__).resolve().parent)]
+__all__: list[str] = []

package/lib/index.js

@@ -0,0 +1,172 @@
+'use strict'
+/**
+ * design-playbook dsh plugin
+ *
+ * Registers two contributions on the DSH context:
+ *
+ * 1. A skill provider (ctx.skills) whose candidates are this package's
+ *    `skills/` directory. The plugin locates the directory via `__dirname`,
+ *    so no `!!js` expression and no cwd-dependent resolution is involved.
+ *
+ * 2. Six slash commands (ctx.commands) — `design-io`, `doctor`,
+ *    `run-review`, `run-status`, `ui-review`, `ux-spec` — that load the
+ *    matching `commands/<name>.md` prompt, substitute `$ARGUMENTS` with the
+ *    raw trailing input, and inject it as a user-role follow-up turn via
+ *    `agent.followup()`.
+ *
+ * The Cordis `!!js` evaluation scope provides no `require` (only Node globals
+ * plus ctx-provided values like dshHomePath/loader), so pointing a
+ * skill-filesystem customSkillDirs row at package resources via
+ * `require.resolve` does not work. The plugin route is the supported way for
+ * a package to contribute its own skills and commands.
+ *
+ * Requires `ctx.skills` (the skill registry from @deepseek-ai/dsh-skill),
+ * `ctx.commands` (from @deepseek-ai/dsh-commands), and `@deepseek-ai/dsh-llm`
+ * (a core DSH dependency, always present in a booted profile).
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const SKILLS_DIR = path.join(__dirname, '..', 'skills')
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands')
+
+/** Parse a minimal frontmatter block: `---\nkey: value\n...\n---\nbody`. */
+function parseSkillFile(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8')
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
+  if (!m) return null
+  const front = {}
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([a-zA-Z0-9-]+):\s*(.*)$/.exec(line)
+    if (kv) front[kv[1]] = kv[2]
+  }
+  return { meta: front, content: m[2].trim() }
+}
+
+/**
+ * Build a user-role message carrying one text block.
+ *
+ * @deepseek-ai/dsh-llm is a core DSH dependency, but it lives in the DSH
+ * installation's node_modules, not in this package's node_modules.
+ * require.resolve from this package may fail depending on hoisting; the
+ * fallback plain object has the same shape DSH's inbox reads
+ * ({ id, role, content, source }) and is safe in all runtimes.
+ * @param {string} text - the prepared prompt body.
+ * @returns {object} a user-role message.
+ */
+function createUserMessageFromPrompt(text) {
+  try {
+    const { createUserMessage } = require('@deepseek-ai/dsh-llm')
+    return createUserMessage({
+      content: [{ type: 'text', text }],
+      source: { kind: 'user' },
+    })
+  } catch {
+    const crypto = require('node:crypto')
+    return Object.freeze({
+      id: crypto.randomUUID(),
+      role: 'user',
+      content: [{ type: 'text', text }],
+      source: { kind: 'user' },
+    })
+  }
+}
+
+exports.name = 'design-playbook'
+exports.inject = ['skills', 'commands']
+
+// Exported for test_commands.js to avoid duplicating the helpers.
+exports.parseSkillFile = parseSkillFile
+exports.createUserMessageFromPrompt = createUserMessageFromPrompt
+
+/**
+ * The six slash commands this plugin registers. Each maps to a
+ * `commands/<name>.md` prompt file; the file's frontmatter `description`
+ * becomes the command's discovery metadata, and the body (with `$ARGUMENTS`
+ * substituted) is injected as a user follow-up turn.
+ */
+const COMMAND_NAMES = [
+  'design-io',
+  'doctor',
+  'run-review',
+  'run-status',
+  'ui-review',
+  'ux-spec',
+]
+
+exports.apply = function (ctx) {
+  // ---- skills provider (P1) ----
+  if (fs.existsSync(SKILLS_DIR)) {
+    ctx.skills.registerProvider(() => {
+      const candidates = fs
+        .readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => {
+          const skillPath = path.join(SKILLS_DIR, e.name, 'SKILL.md')
+          if (!fs.existsSync(skillPath)) return null
+          const parsed = parseSkillFile(skillPath)
+          if (!parsed) return null
+          const meta = parsed.meta
+          const name = meta.name
+          const description = meta.description
+          if (!name || !description) return null
+          return {
+            name,
+            description,
+            ...(meta.whenToUse ? { whenToUse: meta.whenToUse } : {}),
+            rank: 600, // bundled rank (matches skill-filesystem's bundled rank)
+            invocation: { modelInvocable: true, userInvocable: true },
+            source: 'bundled',
+            provider: 'design-playbook',
+            resourceBase: { kind: 'directory', path: path.join(SKILLS_DIR, e.name) },
+            locator: skillPath,
+            path: skillPath,
+          }
+        })
+        .filter(Boolean)
+
+      return {
+        name: 'design-playbook',
+        list: async () => candidates,
+        get: async (candidate) => {
+          const parsed = parseSkillFile(candidate.locator)
+          if (!parsed) return undefined
+          return { ...candidate, content: parsed.content }
+        },
+      }
+    })
+  }
+
+  // ---- commands (P2) ----
+  // Each command loads its prompt from commands/<name>.md, substitutes
+  // $ARGUMENTS, and injects the result as a user-role follow-up turn. The
+  // handler returns a CommandResult immediately — the actual model work
+  // happens in the turn opened by agent.followup().
+  if (ctx.commands && fs.existsSync(COMMANDS_DIR)) {
+    for (const name of COMMAND_NAMES) {
+      const filePath = path.join(COMMANDS_DIR, `${name}.md`)
+      if (!fs.existsSync(filePath)) continue
+      const parsed = parseSkillFile(filePath)
+      if (!parsed || !parsed.meta.description) continue
+
+      // Capture the parsed body once — the handler substitutes $ARGUMENTS
+      // on the already-parsed content instead of re-reading the file.
+      const promptBody = parsed.content
+      ctx.commands.register({
+        name,
+        description: parsed.meta.description,
+        handler: (invocation) => {
+          const prompt = promptBody.replace(/\$ARGUMENTS/g, invocation.rawInput)
+          const message = createUserMessageFromPrompt(prompt)
+          // followup() queues an ordinary turn and wakes the driver — a
+          // slash command is an explicit user action, so followup is the
+          // right boundary (not inject(), which seeds context without
+          // waking).
+          invocation.agent.followup(message)
+          return { kind: 'success' }
+        },
+      })
+    }
+  }
+}

package/mcp/evidence/capture_contract.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""Capture contract v1 rules, owned by the bundled Evidence runtime.
+
+ADR-0018 enforcement site 1: this module is the single owner of the v1
+contract surface — the write-side parse/normalize authority, the read-side
+full-shape snapshot validator, and the contract-fields JSON Schema fragment
+the provider tool schema composes. The provider (server.py) keeps only
+Runtime Object fields, path/overwrite boundaries, and Playwright I/O; G6
+(scripts/validate_run.py) validates bound manifest request snapshots through
+``validate_capture_snapshot`` instead of hand-written partial checks.
+
+Named ``capture_contract.py`` to avoid collision with
+``scripts/contract_v1.py`` (the persistent contract, ADR-0017).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+CAPTURE_SCHEMA_VERSION = 1
+COLOR_SCHEMES = frozenset({"light", "dark", "no-preference"})
+MIN_VIEWPORT_DPR = 0.1
+RECAPTURE_HINT = "recapture with capture contract schemaVersion=1"
+FREEZE_DEFAULTS = {
+    "enabled": True,
+    "waitFonts": True,
+    "networkIdle": False,
+}
+
+
+@dataclass(frozen=True)
+class CaptureFact:
+    """One host-neutral capture-contract violation (empty facts = valid)."""
+
+    code: str
+    detail: str
+    expected: str = ""
+    actual: str = ""
+
+
+def _is_schema_version(value: object) -> bool:
+    return type(value) is int and value == CAPTURE_SCHEMA_VERSION
+
+
+def _bad_viewport(viewport: dict[str, Any]) -> str | None:
+    """First malformed viewport field, or None when the shape is valid.
+
+    Mirrors the parser's field rules exactly so the read side and write side
+    cannot disagree on what a valid viewport is.
+    """
+    width = viewport.get("width")
+    height = viewport.get("height")
+    dpr = viewport.get("devicePixelRatio")
+    scheme = viewport.get("colorScheme")
+    if type(width) is not int or width < 1:
+        return "viewport.width must be a positive integer"
+    if type(height) is not int or height < 1:
+        return "viewport.height must be a positive integer"
+    if (
+        type(dpr) not in (int, float)
+        or not math.isfinite(dpr)
+        or dpr < MIN_VIEWPORT_DPR
+    ):
+        return (
+            "viewport.devicePixelRatio must be a number greater than or equal "
+            f"to {MIN_VIEWPORT_DPR}"
+        )
+    if not isinstance(scheme, str) or scheme not in COLOR_SCHEMES:
+        return (
+            f"viewport.colorScheme must be one of {sorted(COLOR_SCHEMES)}; "
+            f"got {scheme!r}"
+        )
+    return None
+
+
+def _bad_freeze(freeze: dict[str, Any]) -> str | None:
+    """First malformed freeze field, or None when the shape is valid."""
+    for key in FREEZE_DEFAULTS:
+        if not isinstance(freeze.get(key), bool):
+            return f"freeze.{key} must be a boolean"
+    return None
+
+
+def parse_capture_contract(args: dict[str, Any]) -> dict[str, Any]:
+    """Validate capture contract v1 fields and return a normalized request.
+
+    Write authority (ADR-0018): raises ValueError with a recapture instruction
+    for missing/unknown versions or an incomplete viewport. Pure — no browser
+    side effects. The normalized output is what the provider echoes into the
+    manifest request snapshot, so real snapshots always carry freeze defaults.
+    """
+    if "schemaVersion" not in args:
+        raise ValueError(
+            f"capture contract schemaVersion is required; {RECAPTURE_HINT}"
+        )
+    version = args.get("schemaVersion")
+    if not _is_schema_version(version):
+        raise ValueError(
+            f"unsupported capture schemaVersion {version!r}; {RECAPTURE_HINT}"
+        )
+    viewport = args.get("viewport")
+    if not isinstance(viewport, dict):
+        raise ValueError(
+            f"viewport object is required for schemaVersion=1; {RECAPTURE_HINT}"
+        )
+    bad_viewport = _bad_viewport(viewport)
+    if bad_viewport is not None:
+        raise ValueError(bad_viewport)
+    width = viewport["width"]
+    height = viewport["height"]
+    dpr = viewport["devicePixelRatio"]
+    scheme = viewport["colorScheme"]
+
+    freeze_raw = args.get("freeze")
+    if freeze_raw is None:
+        freeze_raw = {}
+    if not isinstance(freeze_raw, dict):
+        raise ValueError("freeze must be an object when provided")
+    freeze = {
+        key: freeze_raw.get(key, FREEZE_DEFAULTS[key])
+        for key in FREEZE_DEFAULTS
+    }
+    bad_freeze = _bad_freeze(freeze)
+    if bad_freeze is not None:
+        raise ValueError(bad_freeze)
+
+    return {
+        "schemaVersion": CAPTURE_SCHEMA_VERSION,
+        "viewport": {
+            "width": width,
+            "height": height,
+            "devicePixelRatio": float(dpr),
+            "colorScheme": scheme,
+        },
+        "freeze": freeze,
+    }
+
+
+def validate_capture_snapshot(snapshot: object) -> list[CaptureFact]:
+    """Read authority: full-shape validation of a bound manifest snapshot.
+
+    Host-neutral — never raises, returns facts (empty list = valid). Strict on
+    the v1 full shape: schemaVersion=1, a complete typed viewport, and a
+    complete boolean freeze. The parser normalizes defaults at capture time;
+    the read side requires the recorded snapshot to be self-contained so the
+    manifest alone can reproduce the capture (ADR-0018). Malformed viewport
+    shape or missing freeze therefore fail closed (sanctioned correction; was
+    lax in the old hand-written G6 checks). Unknown extra keys are tolerated
+    (host-neutral forward compatibility).
+    """
+    if not isinstance(snapshot, dict):
+        return [CaptureFact(
+            "missing_schema_version",
+            "no request snapshot on the bound entry",
+            expected="schemaVersion=1 with viewport and freeze",
+            actual=("None" if snapshot is None else type(snapshot).__name__),
+        )]
+    version = snapshot.get("schemaVersion")
+    if not _is_schema_version(version):
+        return [CaptureFact(
+            ("missing_schema_version" if version is None
+             else "unsupported_schema_version"),
+            ("missing schemaVersion" if version is None
+             else f"unsupported schemaVersion {version!r}"),
+            expected="schemaVersion=1",
+            actual=repr(version),
+        )]
+    viewport = snapshot.get("viewport")
+    if not isinstance(viewport, dict):
+        return [CaptureFact(
+            "missing_viewport",
+            "viewport object is required for schemaVersion=1",
+            expected="viewport width/height/devicePixelRatio/colorScheme",
+            actual=type(viewport).__name__ if viewport is not None else "missing",
+        )]
+    bad_viewport = _bad_viewport(viewport)
+    if bad_viewport is not None:
+        return [CaptureFact(
+            "bad_viewport_shape",
+            bad_viewport,
+            expected="viewport width/height/devicePixelRatio/colorScheme",
+            actual=bad_viewport,
+        )]
+    freeze = snapshot.get("freeze")
+    if not isinstance(freeze, dict):
+        return [CaptureFact(
+            "missing_freeze",
+            "freeze snapshot is required on the bound entry",
+            expected="freeze enabled/waitFonts/networkIdle booleans",
+            actual=type(freeze).__name__ if freeze is not None else "missing",
+        )]
+    bad_freeze = _bad_freeze(freeze)
+    if bad_freeze is not None:
+        return [CaptureFact(
+            "bad_freeze_shape",
+            bad_freeze,
+            expected="freeze enabled/waitFonts/networkIdle booleans",
+            actual=bad_freeze,
+        )]
+    return []
+
+
+def capture_contract_schema_fragment() -> dict[str, Any]:
+    """JSON Schema fragment for the contract fields (schemaVersion/viewport/freeze).
+
+    The provider composes this into its tool schema alongside its Runtime
+    Object fields. const/enum/required/default all come from the same module
+    constants the parser uses, so the schema and the parser cannot drift.
+    """
+    return {
+        "properties": {
+            "schemaVersion": {
+                "type": "integer",
+                "description": "Capture contract version. Only 1 is supported.",
+                "const": CAPTURE_SCHEMA_VERSION,
+            },
+            "viewport": {
+                "type": "object",
+                "description": (
+                    "Required capture viewport. Provider does not invent "
+                    "desktop defaults."
+                ),
+                "properties": {
+                    "width": {"type": "integer", "minimum": 1},
+                    "height": {"type": "integer", "minimum": 1},
+                    "devicePixelRatio": {
+                        "type": "number",
+                        "minimum": MIN_VIEWPORT_DPR,
+                    },
+                    "colorScheme": {
+                        "type": "string",
+                        "enum": sorted(COLOR_SCHEMES),
+                    },
+                },
+                "required": [
+                    "width",
+                    "height",
+                    "devicePixelRatio",
+                    "colorScheme",
+                ],
+                "additionalProperties": False,
+            },
+            "freeze": {
+                "type": "object",
+                "description": (
+                    "Deterministic freeze controls. Defaults: "
+                    "enabled=true, waitFonts=true, networkIdle=false."
+                ),
+                "properties": {
+                    "enabled": {
+                        "type": "boolean",
+                        "default": FREEZE_DEFAULTS["enabled"],
+                    },
+                    "waitFonts": {
+                        "type": "boolean",
+                        "default": FREEZE_DEFAULTS["waitFonts"],
+                    },
+                    "networkIdle": {
+                        "type": "boolean",
+                        "default": FREEZE_DEFAULTS["networkIdle"],
+                    },
+                },
+                "additionalProperties": False,
+            },
+        },
+        "required": ["schemaVersion", "viewport"],
+    }