Workspaces, apps and background jobs

Petti 1.4 · Plugin API v1 · Experimental

Start with an inspector. Add a workspace when several pages belong together. Define an App only when your plugin should own a SQLite schema.

Inspectors and declarative UI

registerInspector declares a title, description, fields and an action. Petti renders the form and invokes run(context, fields) when the user runs it. Text, number, date, select, multi-select and checkbox fields are supported. Results can be typed tables or the documented tabs, metrics, charts and composed native page shapes.

These are validated data structures, not HTML, SwiftUI objects or arbitrary JavaScript UI callbacks. Opening a page or changing a field does not automatically execute a query. Composed stacks, forms, text, alerts, progress, trees and bounded chart/calendar nodes use the exact schemas in the reference.

Workspaces organize existing pages

registerWorkspace lists required table names and pages that refer to inspectors in the same package. The Schema Explorer example is a complete working workspace. Matching checks table names, not arbitrary SQL, required columns or every row’s contents. Make each inspector validate any additional assumptions through safe reads.

A workspace does not adopt a database or create tables. Petti always provides View Raw Database. Optional records forms support a bounded set of typed fields and a single INTEGER PRIMARY KEY, with reviewed writes; composite keys and arbitrary editable result grids are not supported by that form API.

Apps own schemas explicitly

registerApp declares ordered migrations. File → New Database… can create a new app database after user review. Existing databases require explicit compatible adoption; opening a random SQLite file never injects Petti metadata.

Migrations use a restricted declarative schema model: table creation and supported add/rename/drop column/table/index operations. They are ordered, transaction-wrapped and recorded in the opted-in App database. Previously applied migration definitions must remain compatible; do not rewrite history to hide a schema change. Raw SQL migration callbacks, general CHECK/foreign-key definitions and arbitrary data-transform migrations are not available.

Templates configure new files

registerTemplate references an App and can provide validated configuration, sample seeds and a workspace. Required plugins must already be installed and enabled at a sufficient version. Petti does not download dependencies or grant consent automatically.

Jobs perform bounded work

registerJob declares a read or reviewed-write job. A job can report progress and structured logs, accept typed fields and return results. Write jobs return a plan; previewing it does not commit it. Save is a separate snapshot-backed transaction. The owned-App materialization API supports specific bounded SELECT-to-result-table workflows; it is not unrestricted background SQL.

Jobs are cancellable and short-lived. They are not durable server workers, arbitrary WASM modules or unlimited scheduling solvers. Native opt-in automation is attended and bounded; unattended recurring execution and resumable jobs are not promised.

Learn from the bundled apps

Notes App exercises schema creation, migrations, workspace records and reviewed jobs. Analytics Workbook demonstrates owned result tables, supported transforms and native transfers. Their source is readable inside /Applications/Petti.app/Contents/Resources/Plugins/. Study a copy; do not modify the signed app or install a copied bundled ID as your own package. Both use the public API documented here.