Plugin examples and use cases

Petti 1.4 · Plugin API v1 · Experimental

Use the smallest extension point that fits the task. Neither example below requests database.write or mutates the opened database.

Text tools: commands and cell previews

Text Tools contains the complete package from the quickstart. It demonstrates selected-cell input, a useful error when selection is missing, plain-text output and a value-only preview. Adapt it to explain an application-specific string or validate a small JSON payload.

Do not convert database identifiers to JavaScript Number merely to format them. Full 64-bit identifiers can lose precision. If parsing JSON for display, describe that result as an interpretation and preserve Raw as the authoritative bytes.

Schema Explorer: a native form and workspace

Download Schema Explorer. Install the extracted folder, enable it, and open a SQLite database. In the Command Palette, choose Inspectors → Find Schema Objects, enter part of a table name and click Search. Alternatively choose Workspaces… → Schema Browser → Open Workspace. The same inspector appears as a workspace page.

{"id":"dev.example.schema-explorer","name":"Example Schema Explorer","version":"1.0.0","apiVersion":1,"type":"workspace","entry":"main.js","permissions":["database.read","schema.read"]}

petti.registerInspector({
  id: "find-schema",
  title: "Find Schema Objects",
  description: "Inspect metadata without scanning table rows.",
  actionTitle: "Search",
  fields: [{id: "name", type: "text", label: "Name contains", initialValue: ""}],
  async run(context, fields) {
    if (!context.database) throw Error("Open a database first.");
    return await context.database.query(
      "SELECT name, type FROM sqlite_schema WHERE instr(name, ?) > 0 ORDER BY name",
      [{type: "text", value: fields.name}]
    );
  }
});
petti.registerWorkspace({
  id: "schema-browser",
  title: "Schema Browser",
  description: "A read-only metadata workspace for any SQLite database.",
  match: {tables: []},
  pages: [{id: "search", title: "Search schema", inspector: "find-schema"}]
});

The name is a bound parameter, so a quote or SQL-looking input is treated as text. The query reads schema metadata, not every row of every table. Results carry a truncated flag; returning the result unchanged preserves that flag for the native table. An empty match.tables matches any valid SQLite database, but creates no metadata and changes no schema.

More useful directions

• API payload inspection: use a cell previewer for a bounded JSON/text value. Bundled JSON Tools demonstrates an outline without a database write permission.
• Application diagnostics: use a parameterized query and inspector to show a small set of suspicious records. Keep scans bounded and do not describe a sample as an exhaustive check.
• Import/export: register a small custom parser/renderer, or a native CSV/typed-JSONL transfer for full-table streaming. These are different APIs with different scope limits.
• Reviewed cleanup: a write action or write job can propose a bounded batch, which Petti reviews and snapshots before committing. See the safety guide before using direct command transactions.
• A local app interface: combine inspectors, workspace records, owned schema migrations and templates. The bundled Notes App shows this path.

What is not a ready-made plugin use case?

There is no arbitrary network access, Node module loader, native library loading or unlimited JavaScript computation. A school timetable solver or petroleum allocation system would need its own implementation within the current limits; those complete vertical applications are not bundled. Plugins do not provide an open marketplace or automatic remote updates.