Turbo Sample Plugin

5-Minute Plugin Quickstart

1. Clone and enter this plugin repo.
2. Run plugin bootstrap once.
3. Update plugin DB connection in .env.
4. Run integrated core+plugin development flow.

Clone:

git clone <your-plugin-repo-url> turbo-sample-plugin
cd turbo-sample-plugin

Bootstrap (PowerShell):

pwsh -File scripts/bootstrap.ps1

Bootstrap (bash/zsh):

sh scripts/bootstrap.sh

Set PLUGIN_DEV_CONNECTION in .env, then run integrated workflow:

PowerShell:

pwsh -File scripts/dev-integrated.ps1

bash/zsh:

sh scripts/dev-integrated.sh

What This Repo Is

This repository is a plugin project for the Turbo emulator ecosystem. It is loaded by the emulator in the sibling turbo-cloud repository and is not a standalone host app.

Required Folder Layout

your-dev-folder/
  turbo-cloud/
  turbo-sample-plugin/

This sibling layout is required for project references and integrated scripts.

Tooling Baseline

• .NET SDK 9.x (pinned via global.json)
• Git
• MySQL (or compatible database)

Check SDK:

dotnet --version

Build Scope Matrix

Command	Scope	Default?	Use when
dotnet build TurboSamplePlugin/TurboSamplePlugin.csproj	Plugin only	Yes	Normal plugin development
dotnet build ../turbo-cloud/Turbo.Main/Turbo.Main.csproj	Core only	No	Validating core build independently
dotnet build ../turbo-cloud/Turbo.Cloud.sln	Full integrated workspace	No	One-window emulator + plugin validation

Revision Protocol Source of Truth

For protocol parser/serializer placement and naming, use:

• TurboSamplePlugin/Revision/README.md

This file explicitly defines the cross-repo boundary:

• plugin repo owns revision parsers/serializers
• core repo owns runtime host/domain orchestration

For Boost-style AI task recipes and prompt contract, use:

• ../turbo-cloud/AGENTS.md (canonical source)
• Local tool adapters:
  • CLAUDE.md
  • CODEX.md

Quality Model (Two-Phase)

• Fast local commit check:
  • dotnet build TurboSamplePlugin/TurboSamplePlugin.csproj -t:TurboSamplePluginFastCheck
• Full quality gate (pre-push + CI):
  • dotnet build TurboSamplePlugin/TurboSamplePlugin.csproj -t:TurboSamplePluginQualityGate

Hooks are repository-managed in .githooks:

• pre-commit runs staged-file dotnet format style verification, then fast check.
• pre-push runs full quality gate.

Integrated Core + Plugin Workflow

This repo exposes integrated helpers for one-window plugin development:

PowerShell:

pwsh -File scripts/dev-integrated.ps1

bash/zsh:

sh scripts/dev-integrated.sh

Build-only mode:

• PowerShell: pwsh -File scripts/dev-integrated.ps1 -BuildOnly
• bash/zsh: sh scripts/dev-integrated.sh --build-only

Equivalent integrated helpers also exist in turbo-cloud/scripts/.

Local Plugin Configuration

Create .env from .env.example and set:

PLUGIN_DEV_CONNECTION=server=127.0.0.1;user=root;password=password;database=turbo

Optional: DB Migrations

From TurboSamplePlugin.DesignTime:

dotnet ef migrations add Init --project ../TurboSamplePlugin/TurboSamplePlugin.csproj --startup-project . --context SampleDbContext --output-dir ../TurboSamplePlugin/Migrations

Troubleshooting

turbo-cloud path not found

Symptoms:

• Build fails on missing references under ..\..\turbo-cloud\....
• Integrated scripts fail to locate Turbo.Main.csproj.

Fix:

• Ensure turbo-cloud is cloned as a sibling folder next to turbo-sample-plugin.

Plugin is built but not loaded by emulator

Symptoms:

• Turbo.Main runs but plugin features are missing.

Fix:

• Ensure turbo-cloud/appsettings.Development.json contains Turbo:Plugin:DevPluginPaths pointing to this plugin output folder.

Wrong or missing .NET SDK

Symptoms:

• Build errors about unsupported net9.0.

Fix:

• Install .NET SDK 9.x and re-run dotnet --version.

Quality checks fail on formatting/line endings

Run:

dotnet tool restore
dotnet format TurboSamplePlugin/TurboSamplePlugin.csproj style --verify-no-changes
dotnet format TurboSamplePlugin/TurboSamplePlugin.csproj analyzers --verify-no-changes
dotnet build TurboSamplePlugin/TurboSamplePlugin.csproj -t:TurboSamplePluginQualityGate

If your checkout predates .gitattributes normalization, line endings may need a fresh checkout before running repo-wide format checks.

Contributing

See CONTRIBUTING.md for build scope, quality policy, and integrated workflow commands.