proto-plugin 0.1.0

package/scripts/share-prototype.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TOOL_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/source-path.sh
+source "$TOOL_ROOT/scripts/lib/source-path.sh"
+HOST_ROOT="$(resolve_host_root "$TOOL_ROOT")"
+cd "$HOST_ROOT"
+
+if [[ -z "${VERCEL_PROJECT:-}" && -f "$HOST_ROOT/package.json" ]]; then
+  VERCEL_PROJECT="$(node -pe "require('$HOST_ROOT/package.json').name" 2>/dev/null || true)"
+fi
+VERCEL_PROJECT="${VERCEL_PROJECT:-}"
+PUSH=1
+OPEN=0
+SLUG=""
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options] <prototype-slug>
+
+Push the current branch, wait for the Vercel preview deployment, and copy a
+shareable link to the prototype (e.g. /prototypes/example-feature).
+
+Before pushing, stages all changes (git add -A) and commits them when needed.
+
+Options:
+  --no-push          Skip git push (use the current branch HEAD on GitHub)
+  --open             Open the shareable link in your browser
+  --project <name>   Vercel project to use (default: from VERCEL_PROJECT or package.json name)
+  -h, --help         Show this help message
+
+Examples:
+  pnpm share-prototype example-feature
+  pnpm share-prototype --no-push example-feature
+
+Requires: git, gh (authenticated), and network access.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --no-push)
+      PUSH=0
+      shift
+      ;;
+    --open)
+      OPEN=1
+      shift
+      ;;
+    --project)
+      [[ $# -ge 2 ]] || {
+        echo "Missing value for --project" >&2
+        exit 1
+      }
+      VERCEL_PROJECT="$2"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      if [[ -n "$SLUG" ]]; then
+        echo "Unexpected argument: $1" >&2
+        usage >&2
+        exit 1
+      fi
+      SLUG="$1"
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$SLUG" ]]; then
+  usage >&2
+  exit 1
+fi
+
+if [[ -z "$VERCEL_PROJECT" ]]; then
+  echo "Set VERCEL_PROJECT or pass --project <name>." >&2
+  exit 1
+fi
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "Missing required command: $1" >&2
+    exit 1
+  fi
+}
+
+require_command git
+require_command gh
+
+if ! gh auth status >/dev/null 2>&1; then
+  echo "gh is not authenticated. Run: gh auth login" >&2
+  exit 1
+fi
+
+remote_url="$(git remote get-url origin 2>/dev/null || true)"
+if [[ -z "$remote_url" ]]; then
+  echo "No git remote named origin found." >&2
+  exit 1
+fi
+
+if [[ "$remote_url" =~ github\.com[:/]([^/]+)/([^/.]+)(\.git)?$ ]]; then
+  REPO_OWNER="${BASH_REMATCH[1]}"
+  REPO_NAME="${BASH_REMATCH[2]%.git}"
+else
+  echo "Could not parse GitHub owner/repo from origin: $remote_url" >&2
+  exit 1
+fi
+
+branch="$(git branch --show-current)"
+if [[ -z "$branch" ]]; then
+  echo "Detached HEAD — checkout a branch before sharing." >&2
+  exit 1
+fi
+
+copy_to_clipboard() {
+  local text="$1"
+  if command -v pbcopy >/dev/null 2>&1; then
+    printf '%s' "$text" | pbcopy
+  elif command -v wl-copy >/dev/null 2>&1; then
+    printf '%s' "$text" | wl-copy
+  elif command -v xclip >/dev/null 2>&1; then
+    printf '%s' "$text" | xclip -selection clipboard
+  else
+    echo "Could not copy to clipboard (install pbcopy, wl-copy, or xclip)." >&2
+    return 1
+  fi
+}
+
+extract_branch_preview_host() {
+  local sha="$1"
+  local summary
+
+  summary="$(
+    gh api \
+      "repos/$REPO_OWNER/$REPO_NAME/commits/$sha/check-runs?per_page=30" \
+      --jq '.check_runs[] | select(.name == "Vercel Preview Comments") | .output.summary' \
+      2>/dev/null | head -1
+  )"
+
+  if [[ -z "$summary" ]]; then
+    return 1
+  fi
+
+  if [[ "$summary" =~ vercel\.live/open-feedback/([a-z0-9.-]+\.vercel\.app) ]]; then
+    printf '%s\n' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  if [[ "$summary" =~ (https?://)?([a-z0-9.-]+\.vercel\.app) ]]; then
+    printf '%s\n' "${BASH_REMATCH[2]}"
+    return 0
+  fi
+
+  return 1
+}
+
+extract_deployment_preview_url() {
+  local sha="$1"
+  local deployment_id environment_url
+
+  deployment_id="$(
+    gh api \
+      "repos/$REPO_OWNER/$REPO_NAME/deployments?sha=$sha&per_page=20" \
+      --jq ".[] | select(.environment == \"Preview – $VERCEL_PROJECT\") | .id" \
+      2>/dev/null | head -1
+  )"
+
+  if [[ -z "$deployment_id" ]]; then
+    return 1
+  fi
+
+  environment_url="$(
+    gh api \
+      "repos/$REPO_OWNER/$REPO_NAME/deployments/$deployment_id/statuses" \
+      --jq '.[] | select(.state == "success" and .environment_url != null) | .environment_url' \
+      2>/dev/null | head -1
+  )"
+
+  if [[ -z "$environment_url" ]]; then
+    return 1
+  fi
+
+  printf '%s\n' "$environment_url"
+}
+
+resolve_preview_origin() {
+  local sha="$1"
+  local host origin
+
+  if host="$(extract_branch_preview_host "$sha")"; then
+    printf 'https://%s\n' "$host"
+    return 0
+  fi
+
+  if origin="$(extract_deployment_preview_url "$sha")"; then
+    origin="${origin%/}"
+    printf '%s\n' "$origin"
+    return 0
+  fi
+
+  return 1
+}
+
+wait_for_preview_origin() {
+  local sha="$1"
+  local attempt=0
+  local max_attempts=60
+  local origin=""
+
+  while (( attempt < max_attempts )); do
+    if origin="$(resolve_preview_origin "$sha")"; then
+      printf '%s\n' "$origin"
+      return 0
+    fi
+
+    sleep 10
+    ((attempt += 1))
+  done
+
+  echo "Timed out waiting for Vercel preview deployment." >&2
+  echo "Check deployments: https://github.com/$REPO_OWNER/$REPO_NAME/deployments" >&2
+  return 1
+}
+
+share_url=""
+sha=""
+
+if [[ "$PUSH" -eq 1 ]]; then
+  echo "Staging changes..."
+  git add -A
+
+  if ! git diff --cached --quiet; then
+    echo "Committing staged changes..."
+    git commit -m "Update prototype: $SLUG"
+  fi
+
+  echo "Pushing branch: $branch"
+  git push -u origin HEAD
+else
+  echo "Skipping push (using current branch HEAD on origin)."
+fi
+
+sha="$(git rev-parse HEAD)"
+echo "Commit: ${sha:0:7} on $branch"
+echo "Building..." >&2
+
+origin="$(wait_for_preview_origin "$sha")"
+share_url="${origin%/}/prototypes/${SLUG}"
+
+echo
+echo "Shareable link:"
+echo "$share_url"
+echo
+
+if copy_to_clipboard "$share_url"; then
+  echo "Copied to clipboard."
+else
+  echo "Copy the link above manually."
+fi
+
+if [[ "$OPEN" -eq 1 ]]; then
+  if command -v open >/dev/null 2>&1; then
+    open "$share_url"
+  elif command -v xdg-open >/dev/null 2>&1; then
+    xdg-open "$share_url"
+  else
+    echo "Could not open browser automatically." >&2
+  fi
+fi

package/scripts/sync-from-source.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TOOL_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/source-path.sh
+source "$TOOL_ROOT/scripts/lib/source-path.sh"
+# shellcheck source=lib/host-config.sh
+source "$TOOL_ROOT/scripts/lib/host-config.sh"
+HOST_ROOT="$(resolve_host_root "$TOOL_ROOT")"
+
+if ! load_host_config "$HOST_ROOT"; then
+  exit 1
+fi
+
+if ! SOURCE="$(resolve_source_path "$HOST_ROOT")"; then
+  echo "Source app path not found." >&2
+  echo "Set SOURCE_PATH in .env.local (see .env.example), run pnpm link-source, or pass SOURCE=/path/to/source-app" >&2
+  exit 1
+fi
+
+echo "Syncing from $SOURCE"
+
+copy_file() {
+  local rel="$1"
+  mkdir -p "$HOST_ROOT/$(dirname "$rel")"
+  cp "$SOURCE/$rel" "$HOST_ROOT/$rel"
+}
+
+copy_dir() {
+  local rel="$1"
+  mkdir -p "$HOST_ROOT/$rel"
+  cp -R "$SOURCE/$rel/." "$HOST_ROOT/$rel/"
+}
+
+copy_glob() {
+  local glob="$1" dest matches
+  dest="$(dirname "$glob")"
+  mkdir -p "$HOST_ROOT/$dest"
+  # shellcheck disable=SC2206
+  matches=( "$SOURCE"/$glob )
+  if [[ -e "${matches[0]}" ]]; then
+    cp "${matches[@]}" "$HOST_ROOT/$dest/"
+  fi
+}
+
+for rel in ${SYNC_FILES[@]+"${SYNC_FILES[@]}"}; do
+  copy_file "$rel"
+done
+for rel in ${SYNC_DIRS[@]+"${SYNC_DIRS[@]}"}; do
+  copy_dir "$rel"
+done
+for glob in ${SYNC_GLOBS[@]+"${SYNC_GLOBS[@]}"}; do
+  copy_glob "$glob"
+done
+
+# Re-apply platform Tailwind source scan (package self-reference; not in source app).
+if ! grep -q '@source "../../packages/prototype' "$HOST_ROOT/src/app/globals.css"; then
+  if [[ "$OSTYPE" == darwin* ]]; then
+    sed -i '' '/^@import "tailwindcss";/a\
+@source "../../packages/prototype/src/**/*.{js,ts,jsx,tsx}";
+' "$HOST_ROOT/src/app/globals.css"
+  else
+    sed -i '/^@import "tailwindcss";/a @source "../../packages/prototype/src/**/*.{js,ts,jsx,tsx}";' "$HOST_ROOT/src/app/globals.css"
+  fi
+fi
+
+if [[ "${SYNC_LOCAL_EXTENSIONS+set}" == set && "${#SYNC_LOCAL_EXTENSIONS[@]}" -gt 0 ]]; then
+  echo "Done. Re-apply local extensions:"
+  for ext in "${SYNC_LOCAL_EXTENSIONS[@]}"; do
+    echo "  - $ext"
+  done
+else
+  echo "Done."
+fi

package/scripts/verify-prototype-component-ids.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Ensures every UI component under src/prototypes/{slug}/ is registered in
+ * component-ids.ts and wraps its root JSX with PrototypeTarget/PrototypeComponent/PrototypeControl.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  resolveHostRoot,
+  resolveToolRoot,
+} from "./lib/resolve-host-root.mjs";
+
+const toolRoot = resolveToolRoot(import.meta.url);
+const repoRoot = resolveHostRoot(toolRoot);
+const prototypesDir = path.join(repoRoot, "src/prototypes");
+
+function kebabCase(name) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/_/g, "-")
+    .toLowerCase();
+}
+
+function listPrototypeSlugs() {
+  return fs
+    .readdirSync(prototypesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name);
+}
+
+function readRegistryIds(slug) {
+  const registryPath = path.join(prototypesDir, slug, "component-ids.ts");
+  if (!fs.existsSync(registryPath)) {
+    return null;
+  }
+  const source = fs.readFileSync(registryPath, "utf8");
+  const match = source.match(
+    /(?:COMPONENT_IDS|\w+_COMPONENT_IDS)\s*=\s*\[([\s\S]*?)\]\s*as\s*const/,
+  );
+  if (!match) return null;
+  const ids = [...match[1].matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  const prefixMatch = source.match(
+    /DYNAMIC_TARGET_PREFIXES\s*=\s*\[([\s\S]*?)\]\s*as\s*const/,
+  );
+  const prefixes = prefixMatch
+    ? [...prefixMatch[1].matchAll(/"([^"]+)"/g)].map((m) => m[1])
+    : [];
+  return { ids: new Set(ids), prefixes };
+}
+
+function collectTsxFiles(slug) {
+  const root = path.join(prototypesDir, slug);
+  const files = [];
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith(".tsx")) files.push(full);
+    }
+  }
+  walk(root);
+  return files;
+}
+
+function fileBaseId(filePath, slug) {
+  const rel = path.relative(path.join(prototypesDir, slug), filePath);
+  const base = path.basename(rel, ".tsx");
+  if (base === "index") return "page";
+  return kebabCase(base);
+}
+
+function findRenderableComponents(source, fileBase) {
+  const components = [];
+  const fnRegex =
+    /export\s+function\s+([A-Z][A-Za-z0-9]*)\s*\([^)]*\)\s*\{/g;
+  let m;
+  while ((m = fnRegex.exec(source)) !== null) {
+    const name = m[1];
+    const segment =
+      name === fileBase.replace(/-/g, "") ||
+      kebabCase(name) === fileBase
+        ? fileBase
+        : `${fileBase}.${kebabCase(name)}`;
+    components.push({ name, expectedId: segment });
+  }
+
+  const defaultExport = /export\s+default\s+function\s+([A-Z][A-Za-z0-9]*)/.exec(
+    source,
+  );
+  if (defaultExport) {
+    components.push({ name: defaultExport[1], expectedId: "page" });
+  }
+
+  return components;
+}
+
+function hasTargetWrapper(source) {
+  return (
+    source.includes("PrototypeTarget") ||
+    source.includes("PrototypeComponent") ||
+    source.includes("PrototypeControl")
+  );
+}
+
+let failed = false;
+
+for (const slug of listPrototypeSlugs()) {
+  const registry = readRegistryIds(slug);
+  if (!registry) {
+    console.error(`[${slug}] Missing component-ids.ts`);
+    failed = true;
+    continue;
+  }
+
+  for (const file of collectTsxFiles(slug)) {
+    if (file.endsWith("component-ids.ts")) continue;
+    if (file.includes(`${path.sep}ui${path.sep}`)) continue;
+    if (file.includes(`${path.sep}_server${path.sep}`)) continue;
+
+    const source = fs.readFileSync(file, "utf8");
+    const fileBase = fileBaseId(file, slug);
+    const components = findRenderableComponents(source, fileBase);
+
+    if (components.length === 0) continue;
+
+    if (!hasTargetWrapper(source)) {
+      console.error(
+        `[${slug}] ${path.relative(repoRoot, file)}: no PrototypeTarget/PrototypeComponent/PrototypeControl wrapper`,
+      );
+      failed = true;
+    }
+
+    for (const { name, expectedId } of components) {
+      const allowed =
+        registry.ids.has(expectedId) ||
+        registry.prefixes.some((p) => expectedId.startsWith(p));
+      if (!allowed) {
+        console.error(
+          `[${slug}] ${name} in ${path.basename(file)}: expected registry id "${expectedId}"`,
+        );
+        failed = true;
+      }
+    }
+  }
+}
+
+if (failed) {
+  process.exit(1);
+}
+
+console.log("Prototype component id verification passed.");

package/scripts/verify-prototype-preview-states.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Ensures each prototype with a state map uses a single *-preview-states.ts
+ * registry that both the picker and canvas config import from.
+ *
+ * Runtime 1:1 parity (labels, variants, counts) is enforced when the registry
+ * module loads via definePreviewStateRegistry().
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  resolveHostRoot,
+  resolveToolRoot,
+} from "./lib/resolve-host-root.mjs";
+
+const toolRoot = resolveToolRoot(import.meta.url);
+const repoRoot = resolveHostRoot(toolRoot);
+const prototypesDir = path.join(repoRoot, "src/prototypes");
+
+function listPrototypeSlugs() {
+  return fs
+    .readdirSync(prototypesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name);
+}
+
+function walkFiles(dir, predicate) {
+  const files = [];
+
+  function walk(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (predicate(full, entry.name)) files.push(full);
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+function findPreviewStateFiles(slug) {
+  return walkFiles(
+    path.join(prototypesDir, slug),
+    (_full, name) => name.endsWith("-preview-states.ts"),
+  );
+}
+
+function findStateCanvasConfigFiles(slug) {
+  return walkFiles(
+    path.join(prototypesDir, slug),
+    (_full, name) => name.endsWith("-state-canvas-config.tsx"),
+  );
+}
+
+function findStateSelectFiles(slug) {
+  return walkFiles(
+    path.join(prototypesDir, slug),
+    (_full, name) =>
+      name.endsWith(".tsx") &&
+      (name.includes("state-select") || name.includes("tab-select")),
+  );
+}
+
+function fileUsesPreviewStateRegistry(filePath, registryBasename) {
+  const source = fs.readFileSync(filePath, "utf8");
+  const registryModule = registryBasename.replace(/\.ts$/, "");
+  return (
+    source.includes(registryModule) ||
+    source.includes("PREVIEW_STATE_REGISTRY") ||
+    source.includes("_PREVIEW_OPTIONS")
+  );
+}
+
+let failed = false;
+
+for (const slug of listPrototypeSlugs()) {
+  const previewStateFiles = findPreviewStateFiles(slug);
+  const canvasConfigFiles = findStateCanvasConfigFiles(slug);
+  const stateSelectFiles = findStateSelectFiles(slug);
+
+  if (canvasConfigFiles.length > 0 && previewStateFiles.length === 0) {
+    console.error(
+      `[${slug}] Has state canvas config but no *-preview-states.ts registry.`,
+    );
+    failed = true;
+    continue;
+  }
+
+  if (previewStateFiles.length === 0) {
+    continue;
+  }
+
+  if (previewStateFiles.length > 1) {
+    console.error(
+      `[${slug}] Expected one *-preview-states.ts file, found ${previewStateFiles.length}.`,
+    );
+    failed = true;
+  }
+
+  const registryFile = previewStateFiles[0];
+  const registryBasename = path.basename(registryFile);
+  const registrySource = fs.readFileSync(registryFile, "utf8");
+
+  if (!registrySource.includes("definePreviewStateRegistry")) {
+    console.error(
+      `[${slug}] ${path.relative(repoRoot, registryFile)} must call definePreviewStateRegistry().`,
+    );
+    failed = true;
+  }
+
+  for (const file of canvasConfigFiles) {
+    if (!fileUsesPreviewStateRegistry(file, registryBasename)) {
+      console.error(
+        `[${slug}] ${path.relative(repoRoot, file)} must import preview states from ${registryBasename}.`,
+      );
+      failed = true;
+    }
+  }
+
+  for (const file of stateSelectFiles) {
+    if (!fileUsesPreviewStateRegistry(file, registryBasename)) {
+      console.error(
+        `[${slug}] ${path.relative(repoRoot, file)} must import preview states from ${registryBasename}.`,
+      );
+      failed = true;
+    }
+  }
+}
+
+if (failed) {
+  process.exit(1);
+}
+
+console.log("Prototype preview state verification passed.");

package/src/app.ts

@@ -0,0 +1,4 @@
+import "server-only";
+
+export { createPrototypeGalleryPage } from "./config/create-prototype-gallery-page";
+export { createPrototypeCatchAllPage } from "./config/create-prototype-host-app";

package/src/components/platform-ui/code-block.tsx

@@ -0,0 +1,21 @@
+import { cn } from "@prototype/lib/utils";
+
+type CodeBlockProps = {
+  children: string;
+  compact?: boolean;
+  className?: string;
+};
+
+export function CodeBlock({ children, compact = false, className }: CodeBlockProps) {
+  return (
+    <pre
+      className={cn(
+        "overflow-auto whitespace-pre-wrap rounded-md bg-muted font-mono text-muted-foreground",
+        compact ? "max-h-48 p-2 text-[13px] leading-relaxed" : "max-h-64 p-3 text-sm leading-relaxed",
+        className,
+      )}
+    >
+      {children}
+    </pre>
+  );
+}