feat(plugins): in-repo country plugin system

[carvalab]

Summary

Stage 1 of the plugin proposal: a country plugin system that lives in the repo, with a Settings → Integraciones UI to install, activate, and configure each capability.

What's in this PR:

• Manifests + runtimes for AR (IVA, ARCA, Mercado Pago, PedidosYa, Rappi), IN (GST, GST invoice, UPI, Swiggy, Zomato), TH (fixed 7% VAT), and a global.default package for countries without one. Each country package owns its own Zod config schema and the in-process tax math; payment/delivery/fiscal stay declared-only (hosted) for the Stage 3 broker. Some of that are examples, I will delete before the final PR.
• Shared contract in shared/plugin-api.ts that both sides import. Browser-safe Zod schemas cover the manifest, runtime bundle, request/result envelopes, the catalog response, installation, feature, connector, and payment-method wire shapes, plus a typed PluginRegistry and definePluginRuntimeBundle(). The shared installationFeatureSchema now allows installationId: null so unactivated features don't carry an empty string.
• Activation-aware tax dispatch. Country packages are auto-installed and activated at first-run setup and at every startup if the store has an owner + country. The dispatcher activates in-process tax only when the package is installed and the tax feature is active. AR/IN win over global.default; the global default wins for everything else.
• Per-capability activation gate. Payment/delivery/fiscal features require an authorized + broker-verified connector. Tax doesn't. Hosted capabilities get connector_verification_hosted instead of a local "verified" stamp.
• Connector handler dispatch. main/plugins/connector-handlers.ts is the only file that knows provider names. The route dispatches to validate/summarize by capability.provider. Unknown providers get 400, never a silent generic store.
• Manifest-driven UI. Capability display labels/descriptions, permission grid, runtime, scope, and the per-capability configuration form (text / select / number / boolean fields) all come from the manifest. Adding a new package is a manifest + registry edit, not a frontend change.
• SQLite migration v34 adds the plugin state tables. Migrations are non-destructive (CREATE IF NOT EXISTS) and the prior plugin_packages / plugin_outbox speculative tables were dropped because nothing reads them.
• Tests. npm test is green; test:plugin-contracts, test:plugin-routes, and test:plugin-default are wired into the test chain. Semver range parser now covers || and prerelease forms.
• Docs. docs/plugin-architecture.md, docs/plugin-authoring.md, docs/plugin-proposal.md, docs/plugin-references.md.

Visual

Settings → Integraciones on a fresh AR store (/settings/?tab=plugins):

• Catalog grid: 2 packages (country.ar, global.default), 5 AR capabilities, manifest permissions
• Detail dialog: capability list with localized labels + descriptions, per-capability status, per-capability configuration form
• After install: Desactivar/Desinstalar actions, persisted to plugin_installations + plugin_features

Self-review notes

• Hardcoded capability IDs, labels, and provider config state are gone from the frontend. Everything surfaces from the manifest.
• Frontend Zod-validates the catalog/install/connector/payment-method responses. No unchecked as casts.
• Reinstall after uninstalled works (deletes child features/connector rows + resets status).
• The connector config is hard-capped at 32 KiB; secret-like keys (camelCase normalized) are rejected at the route boundary.
• Fiscal hosted capabilities share the same activation gate as payment/delivery now.

Test plan (asking for help)

This PR is draft for proposal. I want to merge after two things:

1. Manual smoke test on each in-repo country package (AR, IN, TH, global.default):
   • First-run setup activates the right tax pack
   • Order with the country's tax math returns the expected line items
   • Settings → Integraciones shows the package; install/activate round-trips
   • Hosted payment/delivery/fiscal per-feature gate rejects unauthorized activation
2. The new test:plugin-default is now wired into test:cors so it runs in CI; please check the test pipeline on your end

@itsbkm @khaira777 — could you run through the country packages on a fresh DB please?

then open Settings → Integraciones on the AR/IN/TH seeded stores. And also no broke taxes.

Out of scope (Stage 2 / Stage 3)

• Signed external catalog API (docs/plugin-proposal.md)
• Hosted broker / provider API calls from the POS
• utility_process ABI execution
• Per-capability permission grants (currently install-wide)

Refs: docs/plugin-proposal.md, docs/plugin-authoring.md, docs/plugin-architecture.md

[itsbkm]

Thanks for putting real effort into this, @carvalab — the manifest-driven capability/connector/installation framework (Settings → Integraciones, per-capability activation gate, connector-handlers.ts dispatch, the Zod-validated shared contract) is genuinely the piece #142 has been missing, and I'd like to find a way to bring it in.

Two things stand in the way of merging as-is, both around tax specifically:

1. This branch predates the current tax engine. Since you opened it, main/services/tax.ts was rewritten from the IN/TH/default switch into a category-based engine backed by signed, versioned country tax packs (main/tax-packs/*.json + main/services/tax-engine.ts), with decimal-based (not floating-point) authoritative math and a signed catalog for install/activate/rollback. Your diff reintroduces the old switch shape, so it'll conflict heavily on rebase.
2. The country tax math itself shouldn't live in plugin runtimes. main/plugins/{ar,in,th}/tax-engine.ts hardcodes rates in-process (e.g. FIXED_RATES: { restaurant: 5, salon: 5 }, a Math.round-based CGST/SGST split) — that's exactly the per-country hardcoding this project moved away from twice already this cycle. The finalized boundary (docs/tax-engine-v2-spec.md, also written up for contributors in docs/tax-packs.md) is: tax stays data-only in signed packs, with one calculation mechanism; the plugin seam is for things a pack genuinely can't express — fiscal authorization, payment/delivery providers, external jurisdiction lookups (ARCA, IRN, Mercado Pago, PedidosYa, Rappi, UPI, Swiggy, Zomato all belong here, not tax math).

Could you pull the current main, take a look at docs/tax-packs.md and main/tax-packs/, and see whether the AR/IN/TH tax-calculation files can come out of this PR entirely — with those countries' tax handled by ordinary tax packs instead — while the connector/fiscal/payment/delivery scaffolding stays and gets rebased? If it's easier to split into two PRs (one scoped purely to the non-tax capability framework, tax math dropped) that'd probably be the fastest path to something mergeable.

Also very open to your take on sequencing here — if you see a better way to fold this in than what I've outlined, or think the split doesn't make sense for some reason I'm missing, let me know. Would rather build on what you've already done than have you redo it from scratch.