@gpc-cli/plugin-sdk 0.1.2 → 0.9.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -20
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -34,9 +34,7 @@ export const myPlugin: GpcPlugin = definePlugin({
|
|
|
34
34
|
registry.addCommand({
|
|
35
35
|
name: "slack:notify",
|
|
36
36
|
description: "Send a Slack notification",
|
|
37
|
-
options: [
|
|
38
|
-
{ flags: "--channel <channel>", description: "Slack channel" },
|
|
39
|
-
],
|
|
37
|
+
options: [{ flags: "--channel <channel>", description: "Slack channel" }],
|
|
40
38
|
action: async (opts) => {
|
|
41
39
|
await postToSlack(opts.channel, "Manual notification from GPC");
|
|
42
40
|
},
|
|
@@ -48,14 +46,14 @@ export const myPlugin: GpcPlugin = definePlugin({
|
|
|
48
46
|
|
|
49
47
|
## Lifecycle Hooks
|
|
50
48
|
|
|
51
|
-
| Hook
|
|
52
|
-
|
|
53
|
-
| `beforeCommand`
|
|
54
|
-
| `afterCommand`
|
|
55
|
-
| `onError`
|
|
56
|
-
| `beforeRequest`
|
|
57
|
-
| `afterResponse`
|
|
58
|
-
| `registerCommands` | Plugin initialization
|
|
49
|
+
| Hook | When | Use Case |
|
|
50
|
+
| ------------------ | ----------------------- | ---------------------------------- |
|
|
51
|
+
| `beforeCommand` | Before any CLI command | Logging, validation, feature flags |
|
|
52
|
+
| `afterCommand` | After command completes | Notifications, metrics, summaries |
|
|
53
|
+
| `onError` | When a command fails | Error reporting, alerting |
|
|
54
|
+
| `beforeRequest` | Before each API call | Request logging, headers |
|
|
55
|
+
| `afterResponse` | After each API response | Response logging, metrics |
|
|
56
|
+
| `registerCommands` | Plugin initialization | Add custom commands to the CLI |
|
|
59
57
|
|
|
60
58
|
## Permissions
|
|
61
59
|
|
|
@@ -72,15 +70,15 @@ const plugin: GpcPlugin = {
|
|
|
72
70
|
};
|
|
73
71
|
```
|
|
74
72
|
|
|
75
|
-
| Permission
|
|
76
|
-
|
|
77
|
-
| `read:config`
|
|
78
|
-
| `write:config`
|
|
79
|
-
| `read:auth`
|
|
80
|
-
| `api:read`
|
|
81
|
-
| `api:write`
|
|
82
|
-
| `commands:register` | Register custom commands
|
|
83
|
-
| `hooks:*`
|
|
73
|
+
| Permission | Grants |
|
|
74
|
+
| ------------------- | --------------------------- |
|
|
75
|
+
| `read:config` | Read GPC configuration |
|
|
76
|
+
| `write:config` | Modify GPC configuration |
|
|
77
|
+
| `read:auth` | Access auth credentials |
|
|
78
|
+
| `api:read` | Read-only API access |
|
|
79
|
+
| `api:write` | Write API access |
|
|
80
|
+
| `commands:register` | Register custom commands |
|
|
81
|
+
| `hooks:*` | Subscribe to specific hooks |
|
|
84
82
|
|
|
85
83
|
Third-party plugins require user approval before loading:
|
|
86
84
|
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PLUGIN_SDK_VERSION = \"0.
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PLUGIN_SDK_VERSION = \"0.9.4\";\n\n// ---------------------------------------------------------------------------\n// Plugin interface\n// ---------------------------------------------------------------------------\n\nexport interface GpcPlugin {\n /** Unique plugin name (e.g., \"@gpc-cli/plugin-ci\" or \"gpc-plugin-slack\") */\n name: string;\n\n /** Plugin version (semver) */\n version: string;\n\n /** Called once when the plugin is loaded. Register hooks here. */\n register(hooks: PluginHooks): void | Promise<void>;\n}\n\n// ---------------------------------------------------------------------------\n// Lifecycle hooks\n// ---------------------------------------------------------------------------\n\nexport interface PluginHooks {\n /** Run before a command executes. Can modify context or abort. */\n beforeCommand(handler: BeforeCommandHandler): void;\n\n /** Run after a command completes successfully. */\n afterCommand(handler: AfterCommandHandler): void;\n\n /** Run when a command fails with an error. */\n onError(handler: ErrorHandler): void;\n\n /** Run before each API request. Can inspect/modify request metadata. */\n beforeRequest(handler: BeforeRequestHandler): void;\n\n /** Run after each API response. Can inspect response metadata. */\n afterResponse(handler: AfterResponseHandler): void;\n\n /** Register additional CLI commands from the plugin. */\n registerCommands(handler: CommandRegistrar): void;\n}\n\nexport type BeforeCommandHandler = (ctx: CommandEvent) => void | Promise<void>;\nexport type AfterCommandHandler = (\n ctx: CommandEvent,\n result: CommandResult,\n) => void | Promise<void>;\nexport type ErrorHandler = (ctx: CommandEvent, error: PluginError) => void | Promise<void>;\nexport type BeforeRequestHandler = (req: RequestEvent) => void | Promise<void>;\nexport type AfterResponseHandler = (req: RequestEvent, res: ResponseEvent) => void | Promise<void>;\nexport type CommandRegistrar = (registry: CommandRegistry) => void;\n\n// ---------------------------------------------------------------------------\n// Event types\n// ---------------------------------------------------------------------------\n\nexport interface CommandEvent {\n /** The command name (e.g., \"releases upload\", \"vitals crashes\") */\n command: string;\n\n /** Resolved arguments passed to the command */\n args: Record<string, unknown>;\n\n /** App package name (if available) */\n app?: string;\n\n /** Timestamp when the command started */\n startedAt: Date;\n}\n\nexport interface CommandResult {\n /** Whether the command succeeded */\n success: boolean;\n\n /** The output data (before formatting) */\n data?: unknown;\n\n /** Duration in milliseconds */\n durationMs: number;\n\n /** Exit code */\n exitCode: number;\n}\n\n// ---------------------------------------------------------------------------\n// Request/response events (for beforeRequest/afterResponse hooks)\n// ---------------------------------------------------------------------------\n\nexport interface RequestEvent {\n /** HTTP method (GET, POST, PUT, PATCH, DELETE) */\n method: string;\n\n /** Request path (relative to API base URL) */\n path: string;\n\n /** Timestamp when the request started */\n startedAt: Date;\n}\n\nexport interface ResponseEvent {\n /** HTTP status code */\n status: number;\n\n /** Duration in milliseconds */\n durationMs: number;\n\n /** Whether the response was successful (2xx) */\n ok: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Error types\n// ---------------------------------------------------------------------------\n\nexport interface PluginError {\n /** Error code */\n code: string;\n\n /** Error message */\n message: string;\n\n /** Exit code */\n exitCode: number;\n\n /** Original error (if available) */\n cause?: Error;\n}\n\n// ---------------------------------------------------------------------------\n// Command registry (for plugins that add commands)\n// ---------------------------------------------------------------------------\n\nexport interface CommandRegistry {\n /** Add a new top-level command */\n add(definition: PluginCommand): void;\n}\n\nexport interface PluginCommand {\n /** Command name (e.g., \"deploy\") */\n name: string;\n\n /** Command description */\n description: string;\n\n /** Command options */\n options?: PluginCommandOption[];\n\n /** Command arguments */\n arguments?: PluginCommandArgument[];\n\n /** The action to run */\n action: (args: Record<string, unknown>, options: Record<string, unknown>) => void | Promise<void>;\n}\n\nexport interface PluginCommandOption {\n flags: string;\n description: string;\n defaultValue?: unknown;\n}\n\nexport interface PluginCommandArgument {\n name: string;\n description: string;\n required?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Plugin metadata (for discovery and permission checks)\n// ---------------------------------------------------------------------------\n\nexport interface PluginManifest {\n /** Plugin name */\n name: string;\n\n /** Plugin version */\n version: string;\n\n /** Required permissions */\n permissions?: PluginPermission[];\n\n /** Whether this is a first-party (@gpc-cli/*) plugin */\n trusted?: boolean;\n}\n\nexport type PluginPermission =\n | \"read:config\"\n | \"write:config\"\n | \"read:auth\"\n | \"api:read\"\n | \"api:write\"\n | \"commands:register\"\n | \"hooks:beforeCommand\"\n | \"hooks:afterCommand\"\n | \"hooks:onError\"\n | \"hooks:beforeRequest\"\n | \"hooks:afterResponse\";\n\n// ---------------------------------------------------------------------------\n// Helper to define a plugin (for plugin authors)\n// ---------------------------------------------------------------------------\n\nexport function definePlugin(plugin: GpcPlugin): GpcPlugin {\n return plugin;\n}\n"],"mappings":";AAAO,IAAM,qBAAqB;AAwM3B,SAAS,aAAa,QAA8B;AACzD,SAAO;AACT;","names":[]}
|