NETCATTY · PLUGIN STARTER
Your first plugin
Read your Greeting preference and show it here. No hosts, terminals or secrets are accessed.
diff --git a/components/QuickSwitcher.pluginContributions.test.tsx b/components/QuickSwitcher.pluginContributions.test.tsx
index c31c59c21..d1940381c 100644
--- a/components/QuickSwitcher.pluginContributions.test.tsx
+++ b/components/QuickSwitcher.pluginContributions.test.tsx
@@ -151,3 +151,24 @@ test('plugin palette items keep repeated placements independently addressable',
commandId: 'com.example.palette.run',
}]);
});
+
+test('packaged Starter contributions are discoverable through the real palette builder', async (context) => {
+ const { createRequire } = await import('node:module');
+ const { mkdtempSync, rmSync } = await import('node:fs');
+ const { tmpdir } = await import('node:os');
+ const { join } = await import('node:path');
+ const require = createRequire(import.meta.url);
+ const { PluginDatabase } = require('../electron/plugins/database.cjs');
+ const { PluginContributionService } = require('../electron/plugins/contributionService.cjs');
+ const manifest = JSON.parse(readFileSync(new URL('../examples/plugins/starter-netcatty/netcatty.plugin.json', import.meta.url), 'utf8'));
+ const root = mkdtempSync(join(tmpdir(), 'starter-palette-'));
+ const database = new PluginDatabase(join(root, 'plugins.sqlite'));
+ context.after(() => { database.close(); rmSync(root, { recursive: true, force: true }); });
+ database.installVersion({ pluginId: manifest.id, version: manifest.version, manifest, archiveSha256: 'a'.repeat(64), packageRelativePath: 'starter' }, { enable: true });
+ const service = new PluginContributionService({ database, runtimeSupervisor: {}, secretStore: {}, getLocale: () => 'en' });
+ const items = buildPluginPaletteItems(service.snapshot().plugins, 'Starter');
+ assert.ok(items.some((item) => item.type === 'plugin-command' && item.commandId === 'com.netcatty.starter.greet'));
+ assert.ok(items.some((item) => item.type === 'plugin-view' && item.id === 'com.netcatty.starter.panel'));
+ database.setEnabled(manifest.id, false);
+ assert.equal(buildPluginPaletteItems(service.snapshot().plugins, 'Starter').length, 0);
+});
diff --git a/components/settings/tabs/PluginPackageManager.tsx b/components/settings/tabs/PluginPackageManager.tsx
index 65213a428..571abae6c 100644
--- a/components/settings/tabs/PluginPackageManager.tsx
+++ b/components/settings/tabs/PluginPackageManager.tsx
@@ -1,5 +1,5 @@
-import { describePluginPermission } from '../../../domain/pluginPermissionDescriptions.cjs';
-import { describePluginRuntime } from '../../../domain/pluginRuntimePolicy.cjs';
+import { describePluginPermission } from '@/domain/pluginPermissionDescriptions.cjs';
+import { describePluginRuntime } from '@/domain/pluginRuntimePolicy.cjs';
import React, { useState } from 'react';
import { ArrowLeft, Package } from 'lucide-react';
import { usePluginManager } from '../../../application/state/usePluginManager';
diff --git a/electron/plugins/starterExample.test.cjs b/electron/plugins/starterExample.test.cjs
new file mode 100644
index 000000000..8ddac4d6f
--- /dev/null
+++ b/electron/plugins/starterExample.test.cjs
@@ -0,0 +1,42 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const vm = require("node:vm");
+const { pathToFileURL } = require("node:url");
+const test = require("node:test");
+
+test("Starter panel renders the actual command result as text and reports denial", async () => {
+ const root = path.resolve(__dirname, "../../examples/plugins/starter-netcatty");
+ const plugin = (await import(pathToFileURL(path.join(root, "dist/index.js")).href)).default;
+ let command;
+ let receive;
+ let click;
+ const elements = new Map(["greet", "result", "title", "description"].map((id) => [id, {
+ textContent: "", disabled: false, addEventListener(_event, callback) { click = callback; },
+ }]));
+ const greeting = ' synthetic hello';
+ await plugin.activate({
+ subscriptions: { add() {} },
+ commands: { registerCommand(id, handler) { assert.equal(id, "com.netcatty.starter.greet"); command = handler; } },
+ settings: { get: async () => greeting },
+ views: { postMessage: (_id, message) => receive?.(message) },
+ });
+ let deny = false;
+ vm.runInNewContext(fs.readFileSync(path.join(root, "panel.js"), "utf8"), {
+ document: { getElementById: (id) => elements.get(id), documentElement: { style: {} } },
+ window: { netcattyView: {
+ onDidChangeEnvironment: (listener) => listener({ locale: "en", theme: "light" }),
+ onDidReceiveMessage: (listener) => { receive = listener; },
+ executeCommand: async (id) => { assert.equal(id, "com.netcatty.starter.greet"); if (deny) throw new Error("Denied"); return command(); },
+ } },
+ });
+ await click();
+ assert.equal(elements.get("result").textContent, greeting);
+ assert.equal(elements.get("greet").disabled, false);
+ deny = true;
+ await click();
+ assert.match(elements.get("result").textContent, /Check permission approval/);
+ assert.equal(elements.get("greet").disabled, false);
+});
diff --git a/examples/plugins/starter-netcatty/README.md b/examples/plugins/starter-netcatty/README.md
index 3f523c8e6..bd0a9e8ad 100644
--- a/examples/plugins/starter-netcatty/README.md
+++ b/examples/plugins/starter-netcatty/README.md
@@ -1,7 +1,7 @@
# Plugin Starter
A minimal first-party browser plugin for learning import, settings and lifecycle.
-It requests only `commands` and `settings.read`: no terminal text, host credentials,
+It requests `commands`, `settings.read`, `menus` and `views`: no terminal text, host credentials,
network, files, secrets or advanced Node access. It works without OS key storage.
Permission declarations are not grants; follow the app's normal mediation.
@@ -15,9 +15,12 @@ node packages/plugin-cli/dist/cli.js pack examples/plugins/starter-netcatty --ou
Start the actual app normally with a fresh test profile; no development flag is
needed. Open **Settings > Plugins > Installed**, import the package, inspect its
-permissions and enable it. Change **Greeting**, then find **Starter: Read Greeting**
-in the command palette. The command reads the preference and records it in the
-plugin's local log; it does not write to a terminal or connect to a host.
+permissions and enable it. Change **Greeting**, then find **Starter: Greeting Panel** (入门:问候面板)
+in the command palette. Review the normal permission prompts, then click
+**Show greeting** to see the exact preference in the sandboxed panel.
+**Starter: Read Greeting** is also listed and refreshes an already-open panel.
+The panel inserts text using `textContent`, never HTML. It does not write to
+a terminal or connect to a host. Denied permissions remain denied.
Disable, restart and re-enable to verify the preference persists. Re-importing
the same package leaves it disabled for review. Uninstall removes code and local
diff --git a/examples/plugins/starter-netcatty/netcatty.plugin.json b/examples/plugins/starter-netcatty/netcatty.plugin.json
index 6f52a0b11..f1267212a 100644
--- a/examples/plugins/starter-netcatty/netcatty.plugin.json
+++ b/examples/plugins/starter-netcatty/netcatty.plugin.json
@@ -2,17 +2,74 @@
"manifestVersion": 1,
"id": "com.netcatty.starter",
"name": "starter-netcatty",
- "displayName": { "en": "Plugin Starter", "zh-CN": "插件入门" },
+ "displayName": {
+ "en": "Plugin Starter",
+ "zh-CN": "插件入门"
+ },
"description": "First-party settings and command example. No terminal, network, filesystem or secret access.",
- "version": "0.1.0",
+ "version": "0.1.1",
"publisher": "netcatty",
"license": "GPL-3.0-or-later",
- "engines": { "netcatty": ">=0.0.0", "api": ">=0.1.0-internal <0.2.0" },
- "main": { "browser": "dist/index.js" },
- "activationEvents": ["onCommand:com.netcatty.starter.greet"],
- "permissions": { "required": ["commands", "settings.read"], "optional": [] },
+ "engines": {
+ "netcatty": ">=0.0.0",
+ "api": ">=0.1.0-internal <0.2.0"
+ },
+ "main": {
+ "browser": "dist/index.js"
+ },
+ "activationEvents": [
+ "onCommand:com.netcatty.starter.greet",
+ "onView:com.netcatty.starter.panel"
+ ],
+ "permissions": {
+ "required": [
+ "commands",
+ "settings.read",
+ "menus",
+ "views"
+ ],
+ "optional": []
+ },
"contributes": {
- "settings": [{ "id": "com.netcatty.starter.greeting", "label": { "en": "Greeting", "zh-CN": "问候语" }, "description": "A local preference for the example command.", "control": "text", "scope": "application", "default": "Hello, synthetic world!" }],
- "commands": [{ "id": "com.netcatty.starter.greet", "title": { "en": "Starter: Read Greeting", "zh-CN": "入门:读取问候语" } }]
+ "settings": [
+ {
+ "id": "com.netcatty.starter.greeting",
+ "label": {
+ "en": "Greeting",
+ "zh-CN": "问候语"
+ },
+ "description": "A local preference for the example command.",
+ "control": "text",
+ "scope": "application",
+ "default": "Hello, synthetic world!"
+ }
+ ],
+ "commands": [
+ {
+ "id": "com.netcatty.starter.greet",
+ "title": {
+ "en": "Starter: Read Greeting",
+ "zh-CN": "入门:读取问候语"
+ }
+ }
+ ],
+ "menus": [
+ {
+ "command": "com.netcatty.starter.greet",
+ "location": "commandPalette",
+ "group": "examples"
+ }
+ ],
+ "views": [
+ {
+ "id": "com.netcatty.starter.panel",
+ "title": {
+ "en": "Starter: Greeting Panel",
+ "zh-CN": "入门:问候面板"
+ },
+ "location": "modal",
+ "entry": "panel.html"
+ }
+ ]
}
}
diff --git a/examples/plugins/starter-netcatty/package.json b/examples/plugins/starter-netcatty/package.json
index c50356525..8dd661aca 100644
--- a/examples/plugins/starter-netcatty/package.json
+++ b/examples/plugins/starter-netcatty/package.json
@@ -1,8 +1,12 @@
{
"name": "@netcatty/example-starter-plugin",
- "version": "0.1.0",
+ "version": "0.1.1",
"private": true,
"type": "module",
- "scripts": { "build": "tsc -p tsconfig.json" },
- "dependencies": { "@netcatty/plugin-sdk": "0.1.0-internal" }
+ "scripts": {
+ "build": "tsc -p tsconfig.json"
+ },
+ "dependencies": {
+ "@netcatty/plugin-sdk": "0.1.0-internal"
+ }
}
diff --git a/examples/plugins/starter-netcatty/panel.css b/examples/plugins/starter-netcatty/panel.css
new file mode 100644
index 000000000..77becc47b
--- /dev/null
+++ b/examples/plugins/starter-netcatty/panel.css
@@ -0,0 +1 @@
+:root { color-scheme: light dark; font: 15px/1.6 system-ui, sans-serif; } body { margin: 0; } main { padding: 32px; max-width: 640px; margin: auto; } .eyebrow { font-size: 11px; letter-spacing: .12em; opacity: .65; } h1 { font-size: 24px; } #description { opacity: .75; } button { font: inherit; color: inherit; background: transparent; border: 1px solid currentColor; border-radius: 8px; padding: 8px 16px; cursor: pointer; } button:disabled { opacity: .5; } #result { white-space: pre-wrap; overflow-wrap: anywhere; padding: 16px; border-radius: 8px; background: light-dark(#f3f4f6, #252525); min-height: 24px; }
diff --git a/examples/plugins/starter-netcatty/panel.html b/examples/plugins/starter-netcatty/panel.html
new file mode 100644
index 000000000..55c27123e
--- /dev/null
+++ b/examples/plugins/starter-netcatty/panel.html
@@ -0,0 +1,3 @@
+
+
NETCATTY · PLUGIN STARTER
Read your Greeting preference and show it here. No hosts, terminals or secrets are accessed.