Connection Import WASM

Overview

Build one connection importer as one WASM component. Keep parser logic in the extension repo, keep host capabilities generic in ../onetcli, and verify the whole path from WIT contract to local composite extension visibility.

Use DBeaver as the reference implementation, but avoid baking DBeaver-specific assumptions into the host.

Reference Library

When developing an importer for a new application, read the playbook first, then load the topic references needed by the app's storage format and output kind:

Repo Map

Implementation Workflow

1. Implement one tool per WASM component. Prefer extensions/wasm/<tool>-importer, with src/component.rs for WIT bindings and src/<tool>.rs for parser logic.
2. Keep connection-import.wit vendored in this repo under wit/. Do not make extension crates import the host repo WIT directly. Add or keep drift checks against ../onetcli when the host repo is present.
3. Generate bindings from ../../../wit in each importer crate:

wit_bindgen::generate!({
    path: "../../../wit",
    world: "connection-importer",
});

4. Export descriptor, scan, and preview. Return JSON matching connection-import-protocol. Use structured parsers such as serde_json, plist, or product-specific parsers; avoid ad hoc string slicing for config formats.
5. Gate secrets strictly. If ImportOptions.include_passwords is false, never return plaintext passwords even when they exist in config files.
6. Declare candidates and permissions in extension.json. Include all product paths per platform, for example macOS ~/... and Windows %APPDATA%/....
7. Register the importer in root manifest.json as a composite extension. Composite importers install under ~/.config/one-hub/extensions/composite/<extension-id>.
8. Package and install locally before host debugging. The installed folder must contain extension.json and wasm/<module>.wasm.

Host Capability Checklist

When an importer fails in the host, fix the host generically:

• WASI Preview2: crates/extension-wasm/src/connection_import.rs must add wasmtime_wasi::p2::add_to_linker_async, store WasiCtx, and implement WasiView with a ResourceTable. A wasm32-wasip2 component commonly imports wasi:io/poll@0.2.6.
• Manifest permissions: %APPDATA%/... and ~/... file permissions must validate in extension/manifest/security_rules.rs.
• Candidate path expansion: connection_import_provider.rs must expand ~/ and %VAR%/... before reading files.
• Local visibility: CompositeExtensionProvider uses load_and_check; host version checks must use the app version, not the extension-runtime crate version.
• UI responsiveness: never call futures::executor::block_on from GPUI import actions/dialogs. Open the preview dialog in a loading state and run preview work through one_core::gpui_tokio::Tokio.
• Feature wiring: main must enable extension-runtime with features = ["wasm-components"], including --no-default-features builds when the app should still expose WASM importers.

Manifest Pattern

Use a composite manifest shape like this:

{
  "schema_version": 1,
  "id": "com.onetcli.importer.<tool>",
  "name": "<Tool> Importer",
  "version": "0.1.0",
  "engines": { "onetcli": ">=0.7.0" },
  "runtime": {
    "wasm": [{
      "id": "<tool>-importer",
      "module": "wasm/<tool>_importer_wasm.wasm",
      "kind": "component"
    }]
  },
  "permissions": [
    "fs:read:~/Library/...",
    "fs:read:%APPDATA%/..."
  ],
  "contributes": {
    "connectionImporters": [{
      "id": "<tool>",
      "runtimeId": "<tool>-importer",
      "displayName": "<Tool>",
      "outputKinds": ["database"],
      "platforms": ["macos", "windows"],
      "candidateFiles": [{
        "id": "<tool>-macos-config",
        "platform": "macos",
        "path": "~/Library/..."
      }]
    }]
  }
}

Database Importer Notes

For database tools, fixtures from one product edition are not enough. Check every edition and platform path the importer claims in extension.json.

Navicat-specific rules:

• Premium Lite stores shared connection data at macOS ~/Library/Application Support/PremiumSoft CyberTech/Navicat CC/Common/conn.plist.
• The Windows analogue is expected under %APPDATA%/PremiumSoft CyberTech/Navicat CC/Common/conn.plist; declare it separately from the classic Navicat paths.
• Navicat plist files may be XML or binary. Use plist::Value::from_reader(Cursor::new(bytes)) when binary support matters, not XML-only parsing.
• Lite records may use lowercase fields such as host, port, username, and defaultdatabase.
• serviceprovider = Default is not a database type. Infer the database type from stable path/key segments such as MySQL, PostgreSQL, Oracle, or SQL Server-specific containers.
• Skip nested parameter dictionaries that are not database connections, including ssh_param, http_param, ssl_param, and compatibility_param.

Add focused fixtures for each schema variant. At minimum, cover classic Navicat entries and Lite conn.plist entries with lowercase fields and path-derived database types.

For SSH-focused importers, use ssh-connection-import. Keep this skill for shared WASM packaging, manifests, host capability, and database importer behavior.

Testing

Extension repo:

rtk cargo test -p <tool>_importer_wasm
rtk cargo fmt --all --check
rtk cargo build --release -p <tool>_importer_wasm --target wasm32-wasip2
rtk node --test tests/scripts.test.mjs
rtk node scripts/release-driver.mjs <tool>-importer 0.1.0 --target universal --artifact-dir artifacts

Host repo:

rtk cargo test -p extension-wasm
rtk cargo test -p extension-runtime connection_import
rtk cargo test -p extension-runtime composite_provider_lists_connection_importer_with_windows_env_permission
rtk cargo check -p main
rtk cargo check -p main --no-default-features
rtk cargo build -p main

Add focused tests for every host ability that was missing. Useful examples include:

• A real or fixture wasm32-wasip2 component that reproduces wasi:io/poll@0.2.6 linker failures.
• A manifest with %APPDATA%/... permissions and candidate files.
• A provider/listing test proving the local composite importer appears in Installed extensions.
• A preview-provider test that runs DBeaver/Termius fixture components.
• A parser fixture for every product edition/path variant declared in the manifest.
• A serialized JSON assertion for any field backed by a host serde enum or externally tagged protocol shape.

Troubleshooting

Guardrails

• Do not combine DBeaver, Navicat, and Termius into one component unless the product explicitly shares storage and parsing semantics. Independent tools should remain separate WASM importers.
• Do not special-case product ids in the host. Add generic manifest, permission, WIT, or runtime capability support.
• Do not let the extension repo depend on ../onetcli at build time. Use vendored WIT and drift verification.
• Do not claim local installation works until the installed composite folder is present and the host provider can list it.
• Do not leave long-running dev app processes active after build/test work unless the user asked to run the app.
• Do not trust display labels such as Default as database types when the product stores type information in surrounding keys or path segments.