@gpc-cli/plugin-sdk 0.1.1 → 0.9.4
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 +103 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# @gpc-cli/plugin-sdk
|
|
2
|
+
|
|
3
|
+
Plugin interface and SDK for extending GPC with custom commands, lifecycle hooks, and integrations.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @gpc-cli/plugin-sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Create a Plugin
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { definePlugin } from "@gpc-cli/plugin-sdk";
|
|
15
|
+
import type { GpcPlugin } from "@gpc-cli/plugin-sdk";
|
|
16
|
+
|
|
17
|
+
export const myPlugin: GpcPlugin = definePlugin({
|
|
18
|
+
name: "gpc-plugin-slack",
|
|
19
|
+
version: "1.0.0",
|
|
20
|
+
|
|
21
|
+
hooks: {
|
|
22
|
+
afterCommand({ command, result }) {
|
|
23
|
+
// Notify Slack after every command
|
|
24
|
+
if (result.success) {
|
|
25
|
+
postToSlack(`${command} completed successfully`);
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
|
|
29
|
+
onError({ error }) {
|
|
30
|
+
postToSlack(`GPC error: ${error.message}`);
|
|
31
|
+
},
|
|
32
|
+
|
|
33
|
+
registerCommands(registry) {
|
|
34
|
+
registry.addCommand({
|
|
35
|
+
name: "slack:notify",
|
|
36
|
+
description: "Send a Slack notification",
|
|
37
|
+
options: [{ flags: "--channel <channel>", description: "Slack channel" }],
|
|
38
|
+
action: async (opts) => {
|
|
39
|
+
await postToSlack(opts.channel, "Manual notification from GPC");
|
|
40
|
+
},
|
|
41
|
+
});
|
|
42
|
+
},
|
|
43
|
+
},
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Lifecycle Hooks
|
|
48
|
+
|
|
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 |
|
|
57
|
+
|
|
58
|
+
## Permissions
|
|
59
|
+
|
|
60
|
+
Plugins declare required permissions in their manifest:
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
const plugin: GpcPlugin = {
|
|
64
|
+
name: "my-plugin",
|
|
65
|
+
version: "1.0.0",
|
|
66
|
+
manifest: {
|
|
67
|
+
permissions: ["api:read", "hooks:afterCommand"],
|
|
68
|
+
},
|
|
69
|
+
hooks: { ... },
|
|
70
|
+
};
|
|
71
|
+
```
|
|
72
|
+
|
|
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 |
|
|
82
|
+
|
|
83
|
+
Third-party plugins require user approval before loading:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
gpc plugins approve gpc-plugin-slack
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Scaffold a Plugin
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
gpc plugins init my-plugin
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Generates a complete plugin project with TypeScript config, tests, and example hooks.
|
|
96
|
+
|
|
97
|
+
## Part of the GPC Monorepo
|
|
98
|
+
|
|
99
|
+
See the [Plugin Development Guide](https://yasserstudio.github.io/gpc/advanced/plugins) for full documentation.
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PLUGIN_SDK_VERSION = \"0.8.0\";\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 = (ctx: CommandEvent
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PLUGIN_SDK_VERSION = \"0.8.0\";\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":[]}
|