Test, debug and distribute a plugin

Petti 1.4 · Plugin API v1 · Experimental

A JavaScript syntax check is not proof that a plugin works in Petti. Test the package through the signed app and the same consent flow your users will use.

Use a disposable database

Create a new SQLite test file or use a snapshot/copy. For Text Tools, create a table with ordinary TEXT values such as Hello, an empty string and emoji, plus NULL. Select the text cell before opening the palette. Expect a clear error for missing selection; never treat NULL as an empty string without deciding that behavior explicitly.

For Schema Explorer, create a table named notes, search for notes and confirm a result. Search for a nonexistent name and confirm an empty result. Search for a quote or SQL-looking string and confirm it is treated as text. The example needs no unlock or editing license to inspect an existing database.

Test the boundaries

• Install without enabling: no action should execute.
• Disable and reopen: its actions should no longer be available.
• Change your installed source and rediscover: approval should be required again.
• Use a database without your expected tables: display a useful result or error.
• Exercise empty, oversized and truncated results. Do not silently present the first 200 rows as all rows.
• For write tools, verify locked/unlicensed refusal, expectedChanges mismatch and transaction rollback on a disposable fixture.
• Cancel a run and close or replace the database. Do not assume cancellation reversed an accepted commit.

Debug where the failure occurs

Installation: check valid JSON, a contained entry path, unique nonreserved ID, supported apiVersion and permission names. The current package model is one manifest and one entry script, not a Node dependency tree.

Enablement: inspect the error under Installed plugins. A syntax error or invalid registration can prevent the whole package from loading. References to missing inspectors/jobs invalidate a workspace. A changed digest needs fresh approval.

Execution: throw Error with a concise explanation for a recoverable input problem. Use the documented context.log and job progress/log methods in their permitted callbacks. Errors and timeouts surface in native UI. Do not rely on a browser console, fetch, require or persistent global variables.

Updating locally: disable first, edit your installed development copy and reopen the palette. Reinstalling the same ID does not overwrite it. An installer rejection is not an invitation to change IDs repeatedly and leave conflicting copies behind.

Automated checks for repository maintainers

With a Petti source checkout and Xcode, run:

swift Tools/check-plugin-api.swift
PETTI_PLUGIN_TEST_BUNDLE="/Applications/Petti.app" swift test --filter PluginDocumentationTests

The API checker parses examples and checks registry/permission coverage. PluginDocumentationTests executes the downloadable examples with the packaged signed helper, checks missing selection, typed/parameterized schema reads, truncation, workspace matching and disabled-plugin refusal. These are maintainer tools, not prerequisites for users writing a plugin.

Share the package

Share a ZIP containing the .petti-plugin folder and installation instructions. The recipient extracts it, installs through the palette and approves permissions themselves. Include the tested Petti/API version, purpose, permissions and limitations. There is no marketplace publishing step, remote dependency installation or automatic update channel. Package consent is not publisher identity verification: users should still review where a package came from.