mygo-framework

command module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 15 Imported by: 0

README

MyGo application framework

This repository is a framework module and reference application for building local-first MyGo desktop apps in Go. It adds a predictable application layout, SQLite and GORM persistence, Goose migrations, validation, explicit dependency injection, structured logging, typed settings, OS secrets, outbound HTTP helpers, form state, generators, and optional MCP tools without replacing MyGo's runtime or IPC.

The included Notes app is the working reference. It persists notes in one SQLite database, uses the same service from the desktop UI and MCP, and shuts down its listener and storage in dependency order.

Requirements

  • Go 1.27.3 or newer
  • Bun 1.4.2 (web projects only)
  • Git
  • The native libraries required by MyGo on your operating system

The manifests pin MyGo 0.8.3 and the frontend toolchain. Run framework doctor inside a generated project to check the local MyGo build requirements.

Create and run an app

Install the current CLI from a checkout. Ensure Go's binary directory is on your PATH.

cd /path/to/mygo-framework
go install ./cmd/framework
framework --version

Create the app from the directory that should contain it:

cd /path/to/projects
framework new my-notes
cd my-notes
bun install --frozen-lockfile
framework doctor
framework dev

The last command opens the Notes desktop app with MyGo's normal live-reload workflow. Add a note, quit the app, and start it again to see the persisted note.

Native Go UI

Create a native starter with Onevra components and persisted preferences:

framework new my-native-app --native
cd my-native-app
go mod download
framework dev

Native projects use the pinned Go MyGo tool for development, diagnostics, and packaging. They also include MyGo MCP for headless UI inspection, interaction, and screenshots. Start the harness with go run . -mcp 127.0.0.1:8080 and connect an MCP client to http://127.0.0.1:8080/mcp using Streamable HTTP.

See the native guide for reactive state, persistence, translations, signed updates, profiles, folder import, PDF reports, large lists, platform support, testing, and using framework packages in another application. In a native project framework make feature NAME writes a native view, store, migration and test instead.

Report errors

Set SENTRY_DSN to send unexpected Go errors, panics and (in the web starter) uncaught frontend errors to Sentry. With no DSN nothing is initialised or sent. See Reporting errors.

Add the first feature

From the generated project root, create a complete vertical slice:

framework make feature Bookmark
bun run generate

The first command creates the model, request, service, provider, and Goose migration. It also refreshes framework-owned adapters. The second command refreshes MyGo's TypeScript client in src/mygo.ts.

Edit the generated service method and frontend for the feature, then verify the owned files and builds:

framework generate --check
go test ./...
bun run test:web
framework build

Never edit files with a generated-code header. After changing an exposed method signature or a framework: annotation, run framework generate and then bun run generate. Ordinary method-body changes use MyGo's normal rebuild flow.

Common commands

Command Purpose
framework dev Start MyGo development; generate adapters first for web projects
framework build Build with MyGo; generate adapters first for web projects
framework doctor Run the pinned MyGo doctor; check adapters first for web projects
framework generate Refresh framework-owned Go adapters and registrations
framework generate --check Fail if committed generated files are stale
framework make feature NAME Create a complete feature and regenerate adapters
framework make migration NAME Create the next numbered Goose migration
go run ./cmd/appctl db status Inspect migrations while the desktop app is closed
go run ./cmd/appctl db up Apply pending migrations while the desktop app is closed
go run ./cmd/appctl db backup FILE Write a consistent copy of the database; safe while the app runs
go run ./cmd/appctl db restore FILE Replace the database with a backup while the desktop app is closed
go run ./cmd/appctl support-bundle FILE Write versions, migration status and logs to a zip for a bug report

MyGo flags pass through framework dev and framework build. Use each command's --help output for the pinned MyGo options.

Learn the framework

The framework intentionally has no Goravel dependency, mandatory UI server, global service facade, automatic database repair, plaintext secret fallback, or second file watcher.

Development

See development and releases for mise setup, repository hooks, checks, builds, and the release-please workflow.

License

MIT.

Documentation

Overview

Code generated by framework generate. DO NOT EDIT.

Package main runs the MyGo framework reference application.

Directories

Path Synopsis
app
bootstrap
Package bootstrap owns application provider registration and composition.
Package bootstrap owns application provider registration and composition.
desktop
Code generated by framework generate.
Code generated by framework generate.
mcp
Code generated by framework generate.
Code generated by framework generate.
models
Package models contains the reference application's persistence models.
Package models contains the reference application's persistence models.
profile
Package profile resolves the application's shared on-disk paths.
Package profile resolves the application's shared on-disk paths.
requests
Package requests defines validated application-service inputs.
Package requests defines validated application-service inputs.
services
Package services contains the application's transport-independent features.
Package services contains the application's transport-independent features.
ui
Package ui adapts committed application changes to MyGo pages.
Package ui adapts committed application changes to MyGo pages.
cmd
appctl command
Command appctl maintains the application while its desktop process is closed.
Command appctl maintains the application while its desktop process is closed.
framework command
Command framework manages MyGo framework projects.
Command framework manages MyGo framework projects.
Package database owns the application's shared SQLite connection pool.
Package database owns the application's shared SQLite connection pool.
migrations
Package migrations embeds the reference application's SQL migration history.
Package migrations embeds the reference application's SQL migration history.
Package diagnostics writes the support bundle a user can send with a bug report: versions, migration status and recent logs in one zip file.
Package diagnostics writes the support bundle a user can send with a bug report: versions, migration status and recent logs in one zip file.
Package errorreport sends unexpected errors and panics to Sentry.
Package errorreport sends unexpected errors and panics to Sentry.
examples
native command
Native demonstrates a Onevra window with retained state and framework settings.
Native demonstrates a Onevra window with retained state and framework settings.
report command
Report writes a one-page PDF with a table and a line chart using pdfreport.
Report writes a one-page PDF with a table and a line chart using pdfreport.
timechart command
Timechart demonstrates linked time-series charts over a night of 25 Hz recordings.
Timechart demonstrates linked time-series charts over a night of 25 Hz recordings.
Package httpclient configures Resty for outbound application requests.
Package httpclient configures Resty for outbound application requests.
internal
appctl
Package appctl defines offline commands for the reference application.
Package appctl defines offline commands for the reference application.
cli
Package cli defines the framework command-line interface.
Package cli defines the framework command-line interface.
generator
Package generator discovers and generates framework-owned adapters.
Package generator discovers and generates framework-owned adapters.
generator/_native command
Native demonstrates a Onevra window with retained state and framework settings.
Native demonstrates a Onevra window with retained state and framework settings.
generator/_template command
Code generated by framework generate.
Code generated by framework generate.
generator/_template/app/bootstrap
Package bootstrap owns application provider registration and composition.
Package bootstrap owns application provider registration and composition.
generator/_template/app/desktop
Code generated by framework generate.
Code generated by framework generate.
generator/_template/app/mcp
Code generated by framework generate.
Code generated by framework generate.
generator/_template/app/models
Package models contains the reference application's persistence models.
Package models contains the reference application's persistence models.
generator/_template/app/profile
Package profile resolves the application's shared on-disk paths.
Package profile resolves the application's shared on-disk paths.
generator/_template/app/requests
Package requests defines validated application-service inputs.
Package requests defines validated application-service inputs.
generator/_template/app/services
Package services contains the application's transport-independent features.
Package services contains the application's transport-independent features.
generator/_template/app/ui
Package ui adapts committed application changes to MyGo pages.
Package ui adapts committed application changes to MyGo pages.
generator/_template/cmd/appctl command
Command appctl maintains the application while its desktop process is closed.
Command appctl maintains the application while its desktop process is closed.
generator/_template/database/migrations
Package migrations embeds the reference application's SQL migration history.
Package migrations embeds the reference application's SQL migration history.
generator/_template/internal/appctl
Package appctl defines offline commands for the reference application.
Package appctl defines offline commands for the reference application.
secretstest
Package secretstest defines the common SecretStore behavior checks.
Package secretstest defines the common SecretStore behavior checks.
settingstest
Package settingstest defines the common persistence contract for settings adapters.
Package settingstest defines the common persistence contract for settings adapters.
Package jobs runs named background jobs with progress, cancellation, and completion events.
Package jobs runs named background jobs with progress, cancellation, and completion events.
Package logging configures the application's structured logs.
Package logging configures the application's structured logs.
Package pdfreport writes small business-style PDF reports: headings, text, tables and line charts under a page header and footer.
Package pdfreport writes small business-style PDF reports: headings, text, tables and line charts under a page header and footer.
Package problem defines transport-independent application failures.
Package problem defines transport-independent application failures.
Package profiles keeps each named profile's data in its own SQLite file under the data directory.
Package profiles keeps each named profile's data in its own SQLite file under the data directory.
Package runtime coordinates application startup and shutdown state.
Package runtime coordinates application startup and shutdown state.
Package secrets defines framework-neutral access to OS-protected secrets.
Package secrets defines framework-neutral access to OS-protected secrets.
memory
Package memory provides an in-memory SecretStore for tests.
Package memory provides an in-memory SecretStore for tests.
mygo
Package mygo adapts MyGo Secrets to the framework-neutral SecretStore.
Package mygo adapts MyGo Secrets to the framework-neutral SecretStore.
Package settings provides typed access to JSON-backed application settings.
Package settings provides typed access to JSON-backed application settings.
bbolt
Package bbolt provides an optional owning settings store backed by bbolt.
Package bbolt provides an optional owning settings store backed by bbolt.
sqlite
Package sqlite persists settings in the application's shared SQLite pool.
Package sqlite persists settings in the application's shared SQLite pool.
Package state provides observable values for UI and application state: cells that notify subscribers, derived selections, and debounced autosave.
Package state provides observable values for UI and application state: cells that notify subscribers, derived selections, and debounced autosave.
Package timechart draws continuous time-series charts in native UI: a time or numeric x-axis with clock-aligned ticks, zoom at the cursor, drag pan, double-click reset, line, step and min/max band series, event markers and a hover crosshair with a readout.
Package timechart draws continuous time-series charts in native UI: a time or numeric x-axis with clock-aligned ticks, zoom at the cursor, drag pan, double-click reset, line, step and min/max band series, event markers and a hover crosshair with a readout.
Package validation maps validator failures to application problems.
Package validation maps validator failures to application problems.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL