From 18f709f8793d527d8742a90dff400813f6fc0cc5 Mon Sep 17 00:00:00 2001 From: Sean O'Connor Date: Thu, 7 Aug 2025 10:47:29 -0400 Subject: [PATCH] feat: implement complete plugin store repository synchronization system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit • Fix repository sync implementation in admin API (was TODO placeholder) - Add full fetch/parse logic for repository.json and plugin index - Implement robot matching by name/manufacturer patterns - Handle plugin creation/updates with proper error handling - Add comprehensive TypeScript typing throughout • Fix plugin store installation state detection - Add getStudyPlugins API integration to check installed plugins - Update PluginCard component with isInstalled prop and correct button states - Fix repository name display using metadata.repositoryId mapping - Show "Installed" (disabled) vs "Install" (enabled) based on actual state • Resolve admin access and authentication issues - Add missing administrator role to user system roles table - Fix admin route access for repository management - Enable repository sync functionality in admin dashboard • Add repository metadata integration - Update plugin records with proper repositoryId references - Add metadata field to robots.plugins.list API response - Enable repository name display for all plugins from metadata • Fix TypeScript compliance across plugin system - Replace unsafe 'any' types with proper interfaces - Add type definitions for repository and plugin data structures - Use nullish coalescing operators for safer null handling - Remove unnecessary type assertions • Integrate live repository at https://repo.hristudio.com - Successfully loads 3 robot plugins (TurtleBot3 Burger/Waffle, NAO) - Complete ROS2 action definitions with parameter schemas - Trust level categorization (official, verified, community) - Platform and documentation metadata preservation • Update documentation and development workflow - Document plugin repository system in work_in_progress.md - Update quick-reference.md with repository sync examples - Add plugin installation and management guidance - Remove problematic test script with TypeScript errors BREAKING CHANGE: Plugin store now requires repository sync for robot plugins. Run repository sync in admin dashboard after deployment to populate plugin store. Closes: Plugin store repository integration Resolves: Installation state detection and repository name display Fixes: Admin authentication and TypeScript compliance issues --- .rules | 19 +- README.md | 298 ++++- docs/README.md | 65 +- docs/cleanup-summary.md | 145 +++ docs/core-blocks-system.md | 233 ++++ docs/implementation-details.md | 38 + docs/paper.md | 694 +++++++++++ docs/project-overview.md | 13 +- docs/project-status.md | 15 +- docs/quick-reference.md | 74 +- docs/root.tex | 285 ----- docs/subfiles/refs.bib | 163 --- docs/work_in_progress.md | 140 ++- lint_output.txt | 1069 ----------------- package.json | 4 + .../hristudio-core/plugins/control-flow.json | 298 +++++ public/hristudio-core/plugins/events.json | 115 ++ public/hristudio-core/plugins/index.json | 51 + .../hristudio-core/plugins/observation.json | 477 ++++++++ .../plugins/wizard-actions.json | 240 ++++ public/hristudio-core/repository.json | 66 + scripts/seed-core-blocks.ts | 589 +++++++++ scripts/seed-plugins.ts | 690 +++++++++++ scripts/seed.ts | 235 ++-- scripts/test-seed-data.ts | 323 +++++ .../designer/EnhancedBlockDesigner.tsx | 429 ++++--- .../plugins/plugin-store-browse.tsx | 44 +- src/components/plugins/plugins-columns.tsx | 3 +- src/components/plugins/plugins-data-table.tsx | 2 +- src/server/api/routers/admin.ts | 211 +++- src/server/api/routers/robots.ts | 1 + test-designer-api.js | 388 ------ tsconfig.json | 2 +- 33 files changed, 5146 insertions(+), 2273 deletions(-) create mode 100644 docs/cleanup-summary.md create mode 100644 docs/core-blocks-system.md create mode 100644 docs/paper.md delete mode 100644 docs/root.tex delete mode 100644 docs/subfiles/refs.bib delete mode 100644 lint_output.txt create mode 100644 public/hristudio-core/plugins/control-flow.json create mode 100644 public/hristudio-core/plugins/events.json create mode 100644 public/hristudio-core/plugins/index.json create mode 100644 public/hristudio-core/plugins/observation.json create mode 100644 public/hristudio-core/plugins/wizard-actions.json create mode 100644 public/hristudio-core/repository.json create mode 100644 scripts/seed-core-blocks.ts create mode 100644 scripts/seed-plugins.ts create mode 100644 scripts/test-seed-data.ts delete mode 100644 test-designer-api.js diff --git a/.rules b/.rules index 10732c5..0dedf4f 100644 --- a/.rules +++ b/.rules @@ -1,7 +1,7 @@ You are an expert in TypeScript, Node.js, Next.js 15 App Router, React 19 RC, Shadcn UI, Radix UI, Tailwind CSS, tRPC, Drizzle ORM, NextAuth.js v5, and the HRIStudio platform architecture. ## Project Overview -HRIStudio is a production-ready web-based platform for managing Wizard of Oz (WoZ) studies in Human-Robot Interaction research. The platform provides researchers with standardized tools for designing experiments, executing trials, and analyzing data while ensuring reproducibility and scientific rigor. +HRIStudio is a web-based platform for managing Wizard of Oz (WoZ) studies in Human-Robot Interaction research. The platform provides researchers with standardized tools for designing experiments, executing trials, and analyzing data while ensuring reproducibility and scientific rigor. It's specification and related paper can be found at docs/paper.md (READ THIS), as well as the docs folder. ## Technology Stack - **Framework**: Next.js 15 with App Router and React 19 RC @@ -217,6 +217,23 @@ export const adminProcedure = protectedProcedure.use(({ ctx, next }) => { Follow Next.js 15 best practices for Data Fetching, Rendering, and Routing. Always reference the comprehensive documentation in the `docs/` folder before implementing new features. +## Documentation Guidelines +- **Location**: ALL documentation must be in `docs/` folder - NEVER create markdown files in root +- **Structure**: Use existing documentation organization and file naming conventions +- **Cross-References**: Always link to related documentation files using relative paths +- **Updates**: When adding features, update relevant docs files (don't create new ones unless necessary) +- **Completeness**: Document all new features, APIs, components, and architectural changes +- **Format**: Use consistent markdown formatting with proper headers, code blocks, and lists +- **Status Tracking**: Update `docs/work_in_progress.md` for active development +- **Integration**: Ensure new docs integrate with existing quick-reference and overview files + +## Plugin System Documentation Standards +- **Core Blocks**: Document in `docs/core-blocks-system.md` (to be created) +- **Robot Plugins**: Use existing `docs/plugin-system-implementation-guide.md` +- **Repository Structure**: Document all plugin repositories in dedicated sections +- **Block Definitions**: Include JSON schema examples and validation rules +- **Loading Process**: Document async loading, error handling, and fallback systems + ## Response Guidelines - Keep responses concise and minimal - No emojis or excessive formatting diff --git a/README.md b/README.md index c72336e..ad2aec2 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,276 @@ -# A Web-Based Wizard-of-Oz Platform for Collaborative and Reproducible Human-Robot Interaction Research +# HRIStudio: A Web-Based Wizard-of-Oz Platform for Human-Robot Interaction Research -A markdown-based conference presentation using Marp with a custom mono/minimal theme, featuring ASCII diagrams and professional formatting. +A comprehensive platform designed to standardize and improve the reproducibility of Wizard of Oz (WoZ) studies in Human-Robot Interaction research. HRIStudio provides researchers with standardized tools for designing experiments, executing trials, and analyzing data while ensuring reproducibility and scientific rigor. + +## Overview + +HRIStudio addresses critical challenges in HRI research by providing a comprehensive experimental workflow management system with standardized terminology, visual experiment design tools, real-time wizard control interfaces, and comprehensive data capture capabilities. + +### Key Problems Solved + +- **Lack of standardized terminology** in WoZ studies +- **Poor documentation practices** leading to unreproducible experiments +- **Technical barriers** preventing non-programmers from conducting HRI research +- **Inconsistent wizard behavior** across trials +- **Limited data capture** and analysis capabilities in existing tools + +### Core Features + +- **Hierarchical Structure**: Study → Experiment → Trial → Step → Action +- **Visual Experiment Designer**: Drag-and-drop protocol creation with 26+ core blocks +- **Plugin System**: Extensible robot platform integration (RESTful, ROS2, custom) +- **Real-time Trial Execution**: Live wizard control with comprehensive data capture +- **Role-Based Access**: Administrator, Researcher, Wizard, Observer (4 distinct roles) +- **Unified Form Experiences**: 73% code reduction through standardized patterns +- **Enterprise DataTables**: Advanced filtering, pagination, export capabilities ## Quick Start +### Prerequisites +- [Bun](https://bun.sh) (package manager) +- [PostgreSQL](https://postgresql.org) 14+ +- [Docker](https://docker.com) (recommended) + +### Installation + ```bash +# Clone the repository +git clone hristudio +cd hristudio + # Install dependencies bun install -# OR -npm install -# Start live preview (recommended for editing) -./start-presentation.sh preview +# Start database (Docker) +bun run docker:up -# Build PDF for conference submission -./start-presentation.sh pdf +# Setup database schema and seed data +bun db:push +bun db:seed + +# Start development server +bun dev ``` -## Available Scripts +### Default Login Credentials -- `bun run preview` - Live preview with auto-reload -- `bun run watch` - Watch mode with browser preview -- `bun run build:pdf` - Generate PDF for conference -- `bun run build:html` - Generate HTML version -- `bun run build:pptx` - Generate PowerPoint format -- `bun run build:all` - Build all formats -- `bun run serve` - Start development server +- **Administrator**: `sean@soconnor.dev` / `password123` +- **Researcher**: `alice.rodriguez@university.edu` / `password123` +- **Wizard**: `emily.watson@lab.edu` / `password123` +- **Observer**: `maria.santos@tech.edu` / `password123` -## Files +## Technology Stack -- `hristudio-presentation.md` - Main presentation content -- `start-presentation.sh` - Quick start helper script -- `package.json` - Dependencies and scripts +- **Framework**: Next.js 15 with App Router and React 19 RC +- **Language**: TypeScript (strict mode) - 100% type safety throughout +- **Database**: PostgreSQL with Drizzle ORM for type-safe operations +- **Authentication**: NextAuth.js v5 with database sessions and JWT +- **API**: tRPC for end-to-end type-safe client-server communication +- **UI**: Tailwind CSS + shadcn/ui (built on Radix UI primitives) +- **Storage**: Cloudflare R2 (S3-compatible) for media files +- **Deployment**: Vercel serverless platform with Edge Runtime +- **Package Manager**: Bun exclusively +- **Real-time**: WebSocket with Edge Runtime compatibility -## Design System +## Architecture -The presentation uses a mono/minimal aesthetic with: +### Core Components -- **Font**: JetBrains Mono (Geist Mono fallback) -- **Colors**: Matching HRIStudio's oklch color scheme -- **Layout**: Clean, spacious design with no unnecessary elements -- **Typography**: Consistent hierarchy with proper spacing +#### 1. Visual Experiment Designer +- **Repository-based block system** with 26+ core blocks across 4 categories +- **Plugin architecture** for both core functionality and robot actions +- Context-sensitive help and best practice guidance +- **Core Block Categories**: + - **Events (4)**: Trial triggers, speech detection, timers, key presses + - **Wizard Actions (6)**: Speech, gestures, object handling, rating, notes + - **Control Flow (8)**: Loops, conditionals, parallel execution, error handling + - **Observation (8)**: Behavioral coding, timing, recording, surveys, sensors -## Development Workflow +#### 2. Robot Platform Integration +- **Unified plugin architecture** for both core blocks and robot actions +- Abstract action definitions with platform-specific translations +- Support for RESTful APIs, ROS2, and custom protocols +- **Repository system** for plugin distribution and management +- Plugin Store with trust levels (Official, Verified, Community) -1. **Edit**: Modify `hristudio-presentation.md` in your editor -2. **Preview**: Run `./start-presentation.sh preview` for live reload -3. **Build**: Generate final PDF with `./start-presentation.sh pdf` -4. **Version Control**: All files are text-based and git-friendly +#### 3. Adaptive Wizard Interface +- Real-time experiment execution dashboard +- Step-by-step guidance for consistent execution +- Quick actions for unscripted interventions +- Live video feed integration +- Timestamped event logging -## VS Code Integration +#### 4. Comprehensive Data Management +- Automatic capture of all experimental data +- Synchronized multi-modal data streams +- Encrypted storage for sensitive participant data +- Role-based access control for data security -Install "Marp for VS Code" extension for: -- Live preview in editor -- Syntax highlighting -- Immediate feedback while editing +## User Roles -## Conference Requirements +- **Administrator**: Full system access, user management, plugin installation +- **Researcher**: Create studies, design experiments, manage teams, analyze data +- **Wizard**: Execute trials, control robots, make real-time decisions +- **Observer**: Read-only access, monitor trials, add annotations -The generated PDF meets standard conference requirements: -- 16:9 aspect ratio for projectors -- High-quality embedded fonts -- Professional typography -- Consistent with academic presentation standards +## Development -## Customization +### Available Scripts -- Edit content in `hristudio-presentation.md` -- Modify colors/fonts in the `