@revfleet/hscli 0.8.7 → 0.8.10

package/docs/PLUGIN_GUIDE.md

@@ -0,0 +1,158 @@
+# Plugin Guide
+
+hscli supports plugins that add new command groups without modifying the core codebase.
+
+## Plugin Contract
+
+A plugin is an ESM module that exports a `register` function:
+
+```typescript
+import type { Command } from "commander";
+import type { PluginContext } from "hscli/plugins";
+
+export function register(program: Command, ctx: PluginContext): void {
+  const analytics = program.command("analytics").description("Analytics commands");
+
+  analytics
+    .command("report")
+    .option("--days <n>", "Days to look back", "30")
+    .action(async (opts) => {
+      const cliCtx = ctx.getCtx();
+      const client = ctx.createClient(cliCtx.profile);
+      const res = await client.request(`/crm/v3/objects/contacts?limit=${opts.days}`);
+      ctx.printResult(cliCtx, res);
+    });
+}
+```
+
+## PluginContext API
+
+| Method | Description |
+|--------|-------------|
+| `getCtx()` | Returns current CLI context (profile, flags). **Call inside `.action()`, not at registration time.** |
+| `createClient(profile)` | Creates an authenticated HubSpot API client for the given profile. |
+| `printResult(ctx, data)` | Prints structured output to stdout (respects `--json`, `--format`). |
+| `printError(ctx, error)` | Prints structured error to stderr. |
+| `CliError` | Constructor for structured errors: `new ctx.CliError("CODE", "message")`. |
+| `maybeWrite(ctx, client, method, path, body?)` | Write-safe helper. Enforces `--dry-run`, `--force`, and `--policy-file` gates automatically. |
+
+## Write Safety
+
+Always use `ctx.maybeWrite()` for mutations. This enforces all safety gates:
+
+```typescript
+analytics
+  .command("delete-report")
+  .argument("<id>")
+  .action(async (id) => {
+    const cliCtx = ctx.getCtx();
+    const client = ctx.createClient(cliCtx.profile);
+    const result = await ctx.maybeWrite(cliCtx, client, "DELETE", `/analytics/v1/reports/${id}`);
+    ctx.printResult(cliCtx, result);
+  });
+```
+
+- Without `--force`: throws `WRITE_CONFIRMATION_REQUIRED`
+- With `--dry-run`: returns preview object without making the API call
+- With `--policy-file`: enforces profile-level write/delete rules
+
+## Plugin Discovery
+
+### 1. npm packages (automatic)
+
+Create an npm package with `"hscli-plugin"` in its `keywords`:
+
+```json
+{
+  "name": "hscli-plugin-analytics",
+  "keywords": ["hscli-plugin"],
+  "type": "module",
+  "main": "index.js",
+  "exports": { ".": "./index.js" }
+}
+```
+
+Install it alongside hscli:
+
+```bash
+npm install hscli-plugin-analytics
+```
+
+Auto-discovery is **opt-in** — since hscli handles bearer tokens,
+silently importing every `node_modules` package with a matching keyword
+is a supply-chain risk. To enable auto-discovery:
+
+```bash
+HSCLI_PLUGIN_AUTO_DISCOVER=1 hscli ...
+```
+
+When enabled, hscli prints the resolved package list to stderr before
+loading them, so a misconfigured `node_modules` can't inject token-path
+code silently. For production use, prefer the explicit allowlist below.
+
+### 2. HSCLI_PLUGINS env var (manual, always honored)
+
+For local development or private plugins:
+
+```bash
+HSCLI_PLUGINS=./my-plugin,/opt/plugins/custom hscli analytics report
+```
+
+Comma-separated list of paths (relative to cwd) or npm package names.
+
+## Local Development
+
+```bash
+mkdir hscli-plugin-analytics
+cd hscli-plugin-analytics
+
+cat > index.js << 'EOF'
+export function register(program, ctx) {
+  program
+    .command("analytics")
+    .description("Analytics commands (plugin)")
+    .command("hello")
+    .action(() => {
+      const cliCtx = ctx.getCtx();
+      ctx.printResult(cliCtx, { message: "Hello from analytics plugin!" });
+    });
+}
+EOF
+
+cd /path/to/hscli
+HSCLI_PLUGINS=../hscli-plugin-analytics hscli analytics hello
+```
+
+## Error Handling
+
+- Throw `ctx.CliError` for structured errors that follow hscli's error format.
+- Plugin load failures are logged to stderr but never crash the CLI.
+- If a plugin's `register()` throws, it is skipped and the rest of the CLI works normally.
+
+## TypeScript Setup
+
+For TypeScript plugins, target `ES2022` / `NodeNext` to match the host:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist"
+  }
+}
+```
+
+Import types from hscli:
+
+```typescript
+import type { PluginContext, HubcliPlugin } from "hscli/plugins";
+import type { CliContext } from "hscli/output";
+```
+
+## Limitations
+
+- Plugins cannot override built-in commands (Commander silently ignores duplicates).
+- Plugins share the same process and Node.js context as the CLI.
+- Plugin authors are responsible for their own error handling within `.action()` callbacks.

package/docs/POLICY_EXAMPLE.json

@@ -0,0 +1,57 @@
+{
+  "$schema-note": "hscli policy v2 — method+path glob rules, time windows, change-ticket + approval gates. First-match-wins per profile. Legacy v1 flat fields (allowWrite, allowDelete, requireChangeTicket) are still honored under `defaults` / per-profile for backward compat.",
+  "version": 2,
+  "profiles": {
+    "prod": {
+      "defaultAction": "deny",
+      "rules": [
+        {
+          "name": "allow-all-reads",
+          "match": { "method": "GET", "path": "**" },
+          "action": "allow"
+        },
+        {
+          "name": "block-gdpr-delete-anywhere",
+          "match": { "method": "*", "path": "**/gdpr-delete**" },
+          "action": "deny"
+        },
+        {
+          "name": "block-schema-deletes",
+          "match": { "method": "DELETE", "path": "/crm/v3/schemas/**" },
+          "action": "deny"
+        },
+        {
+          "name": "crm-writes-need-ticket-and-hours",
+          "match": { "method": "POST", "path": "/crm/v3/objects/**" },
+          "action": "allow",
+          "requireChangeTicket": true,
+          "window": { "tz": "US/Eastern", "hours": "09-17", "days": "mon-fri" }
+        },
+        {
+          "name": "crm-updates-need-ticket-and-hours",
+          "match": { "method": "PATCH", "path": "/crm/v3/objects/**" },
+          "action": "allow",
+          "requireChangeTicket": true,
+          "window": { "tz": "US/Eastern", "hours": "09-17", "days": "mon-fri" }
+        },
+        {
+          "name": "deletes-need-approval",
+          "match": { "method": "DELETE", "path": "/crm/v3/objects/**" },
+          "action": "allow",
+          "requireChangeTicket": true,
+          "requireApproval": "manual"
+        }
+      ]
+    },
+    "sandbox": {
+      "defaultAction": "allow",
+      "rules": [
+        {
+          "name": "still-block-gdpr-delete",
+          "match": { "method": "*", "path": "**/gdpr-delete**" },
+          "action": "deny"
+        }
+      ]
+    }
+  }
+}