@chainpatrol/cli 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# ChainPatrol CLI
+
+Terminal interface for ChainPatrol threat detection.
+
+## Installation
+
+```bash
+npm install -g chainpatrol
+```
+
+## Usage
+
+```bash
+chainpatrol login
+chainpatrol configs list --org my-org
+chainpatrol --json configs list --org my-org
+chainpatrol detections healthcheck --org my-org --run
+chainpatrol detections drift --org my-org --lookback-hours 168
+chainpatrol detections configs update --org my-org --config-id 42 --enable --set query=brand-phishing
+chainpatrol metrics found --org my-org --this-week
+chainpatrol reports create --org my-org --title "Phishing report" --asset "https://phish.example:BLOCKED"
+chainpatrol reports list --org my-org --limit 10
+chainpatrol metrics breakdown --org my-org --by type --from 2026-01-01 --to 2026-01-08
+chainpatrol queues snapshot --all --output markdown
+chainpatrol presets run cs-weekly-health --org my-org --output json
+```
+
+### Global agent-first flags
+
+```bash
+# preview mutations without sending API write requests
+chainpatrol reports create --org my-org --title "Preview" --asset "https://phish.example:BLOCKED" --dry-run
+
+# include recommendation context and emit markdown
+chainpatrol detections drift --org my-org --explain --output markdown
+
+# CSV handoff for docs/slides
+chainpatrol queues snapshot --all --output csv
+```
+
+### Detection commands
+
+```bash
+# run a full healthcheck with source validation
+chainpatrol detections healthcheck --org my-org --run --min-results 1 --lookback-hours 168
+
+# validate only
+chainpatrol detections validate --org my-org --source urlscan
+
+# run configs on demand
+chainpatrol detections run --org my-org --source google_search
+
+# detect noisy/stale/zero-result drift
+chainpatrol detections drift --org my-org --lookback-hours 168
+
+# update one config
+chainpatrol detections configs update --org my-org --config-id 42 --disable
+chainpatrol detections configs update --org my-org --config-id 42 --set query=brand-phishing --set maxResults=100
+
+# dry-run config update
+chainpatrol detections configs update --org my-org --config-id 42 --set query=brand-phishing --dry-run --output json
+```
+
+### Metrics commands
+
+```bash
+# summary metrics
+chainpatrol metrics summary --org my-org --from 2026-01-01 --to 2026-01-08
+
+# default "found" metric = customer-facing new threats
+chainpatrol metrics found --org my-org --this-week
+
+# grouped metrics
+chainpatrol metrics breakdown --org my-org --by day --from 2026-01-01 --to 2026-01-08
+chainpatrol metrics breakdown --org my-org --by type --from 2026-01-01 --to 2026-01-08
+chainpatrol metrics breakdown --org my-org --by brand --from 2026-01-01 --to 2026-01-08
+```
+
+### Reports commands
+
+```bash
+# create report with inline assets
+chainpatrol reports create --org my-org --title "New phishing campaign" --description "Detected from CLI" --asset "https://phish.example:BLOCKED"
+
+# add multiple assets and attachments
+chainpatrol reports create --org my-org --title "Batch report" --asset "https://a.example:BLOCKED" --asset "https://b.example:ALLOWED" --attachment-url "https://cdn.example/screenshot1.png"
+
+# use full payload for advanced fields (externalReporter, enrichments, rawAssetsInput)
+chainpatrol reports create --payload-file ./report-payload.json --json
+
+# dry-run then apply
+chainpatrol reports create --org my-org --title "Batch report" --asset "https://a.example:BLOCKED" --dry-run --output markdown
+chainpatrol reports create --org my-org --title "Batch report" --asset "https://a.example:BLOCKED"
+
+# confirm recently created reports
+chainpatrol reports list --org my-org --limit 5
+chainpatrol reports list --org my-org --status TODO --search "Phishing report"
+```
+
+### Operations commands
+
+```bash
+# org-level queue snapshot
+chainpatrol queues snapshot --org my-org
+
+# all-org queue snapshot
+chainpatrol queues snapshot --all --window-hours 168 --output markdown
+```
+
+### Presets
+
+```bash
+# list available presets
+chainpatrol presets list
+
+# run CS weekly health workflow
+chainpatrol presets run cs-weekly-health --org my-org --output json
+```
+
+### AI-friendly workflows
+
+Use `--json` in automations and agent prompts:
+
+```bash
+chainpatrol --json detections healthcheck --org my-org --run --min-results 1
+chainpatrol --json metrics found --org my-org --this-week
+chainpatrol --json metrics breakdown --org my-org --by type --from 2026-01-01 --to 2026-01-08
+```
+
+Deterministic exit codes:
+
+- `0` success
+- `2` auth errors
+- `3` usage/argument errors
+- `4` not found
+- `5` forbidden
+- `6` check failure (health/drift/queue thresholds)
+- `7` mutation partial failure
+- `8` network/API unavailable
+- `1` unknown fallback
+
+## Development
+
+### Build and install locally
+
+From the repo root:
+
+```bash
+yarn cli:local:install
+```
+
+And set up the config:
+
+```bash
+mkdir -p ~/.chainpatrol
+echo '{"apiUrl": "https://api.chainpatrol.dev"}' > ~/.chainpatrol/config.json
+```
+
+### Install the Claude Code skill
+
+```bash
+chainpatrol setup
+```
+
+This copies the `/chainpatrol` skill to `~/.claude/skills/chainpatrol/SKILL.md` so Claude Code can help you use the CLI in any project.
+
+### Testing locally
+
+Install the CLI and point it at your local dev server:
+
+```bash
+yarn cli:local:install
+chainpatrol setup
+
+mkdir -p ~/.chainpatrol
+echo '{"apiUrl": "http://localhost:3000"}' > ~/.chainpatrol/config.json
+```
+
+XDG path is also supported:
+
+```bash
+mkdir -p ~/.config/chainpatrol
+echo '{"apiUrl": "http://localhost:3000"}' > ~/.config/chainpatrol/config.json
+```
+
+Start the dev server (`yarn dev`), then test:
+
+```bash
+# authenticate
+chainpatrol login
+
+# list configs (sets default org)
+chainpatrol configs list --org chainpatrol
+
+# uses saved default org
+chainpatrol configs list
+
+# JSON output
+chainpatrol configs list --json
+
+# detection healthcheck
+chainpatrol detections healthcheck --org chainpatrol --run
+
+# metrics checks
+chainpatrol metrics found --org chainpatrol --this-week
+chainpatrol metrics breakdown --org chainpatrol --by type --from 2026-01-01 --to 2026-01-08
+```
+
+### Uninstall
+
+```bash
+chainpatrol uninstall   # remove Claude Code skill
+npm unlink chainpatrol  # remove global CLI link
+```
+
+### Scripts
+
+| Script           | Description                   |
+| ---------------- | ----------------------------- |
+| `yarn dev`       | Run CLI from source via tsx   |
+| `yarn dev:setup` | Run setup command from source |
+| `yarn build`     | Build with tsup               |
+| `yarn typecheck` | Type check                    |
+| `yarn test`      | Run unit tests                |

package/dist/breakdown-JVN66HY3.js

@@ -0,0 +1,69 @@
+import {
+  printOutput,
+  toCsvRows
+} from "./chunk-VFT3TD3E.js";
+import {
+  createApiClient
+} from "./chunk-H7UKKLCV.js";
+import "./chunk-EEG7T6WT.js";
+import "./chunk-U73SABXK.js";
+
+// src/commands/metrics/breakdown.ts
+async function runMetricsBreakdown(options) {
+  const client = options.apiClient ?? createApiClient();
+  const result = await client.getMetricsBreakdown({
+    slug: options.org,
+    by: options.by,
+    startDate: options.from,
+    endDate: options.to,
+    brandIds: options.brandIds
+  });
+  const outputFormat = options.outputFormat ?? (options.json ? "json" : "human");
+  printOutput({
+    outputFormat,
+    json: result,
+    markdown: [
+      `# Metrics Breakdown (${options.org})`,
+      "",
+      `- Grouped by: ${result.by}`,
+      "",
+      ...result.points.map((point) => {
+        if (result.by === "day") {
+          return `- ${point.date ?? point.key}: ${point.count}`;
+        }
+        if (result.by === "type") {
+          return `- ${point.type ?? point.key}: ${point.count}`;
+        }
+        return `- ${point.brandName ?? point.brandSlug ?? point.key}: ${point.count}`;
+      })
+    ].join("\n"),
+    csv: toCsvRows(
+      result.points.map((point) => ({
+        key: point.key,
+        count: point.count,
+        date: point.date ?? null,
+        type: point.type ?? null,
+        brandId: point.brandId ?? null,
+        brandSlug: point.brandSlug ?? null,
+        brandName: point.brandName ?? null
+      }))
+    ),
+    human: () => {
+      console.log(`Metrics breakdown for ${options.org} by ${result.by}`);
+      for (const point of result.points) {
+        if (result.by === "day") {
+          console.log(`${point.date ?? point.key}: ${point.count}`);
+          continue;
+        }
+        if (result.by === "type") {
+          console.log(`${point.type ?? point.key}: ${point.count}`);
+          continue;
+        }
+        console.log(`${point.brandName ?? point.brandSlug ?? point.key}: ${point.count}`);
+      }
+    }
+  });
+}
+export {
+  runMetricsBreakdown
+};

package/dist/chunk-D2QGXYXZ.js

@@ -0,0 +1,126 @@
+import {
+  CliExitError,
+  ExitCode
+} from "./chunk-E2LAMILJ.js";
+import {
+  printOutput,
+  toCsvRows
+} from "./chunk-VFT3TD3E.js";
+import {
+  DateTime,
+  createApiClient
+} from "./chunk-H7UKKLCV.js";
+
+// src/presets/index.ts
+var PRESETS = [
+  {
+    id: "cs-weekly-health",
+    title: "CS Weekly Health",
+    description: "Weekly customer health package with found threats, summary metrics, and detection validation."
+  }
+];
+function getPresetDefinition(id) {
+  return PRESETS.find((preset) => preset.id === id);
+}
+async function runPreset({
+  presetId,
+  org,
+  outputFormat,
+  explain,
+  apiClient
+}) {
+  const client = apiClient ?? createApiClient();
+  if (presetId !== "cs-weekly-health") {
+    throw new CliExitError(`Unknown preset '${presetId}'.`, ExitCode.USAGE);
+  }
+  const now = DateTime.now().toUTC();
+  const startDate = now.startOf("week").toISO();
+  const endDate = now.toISO();
+  if (!startDate || !endDate) {
+    throw new CliExitError("Failed to resolve preset date range.", ExitCode.UNKNOWN);
+  }
+  const [summary, found, validation] = await Promise.all([
+    client.getMetricsSummary({
+      slug: org,
+      startDate,
+      endDate
+    }),
+    client.getMetricsFound({
+      slug: org,
+      startDate,
+      endDate
+    }),
+    client.validateDetectionConfigs({
+      slug: org,
+      lookbackHours: 168,
+      minResults: 1,
+      runBeforeValidate: false,
+      includeDisabled: false
+    })
+  ]);
+  const payload = {
+    presetId,
+    org,
+    range: { startDate, endDate },
+    summary: summary.metrics,
+    found,
+    detectionValidation: validation.summary,
+    failedDetectionConfigs: validation.validations.filter((item) => !item.valid)
+  };
+  printOutput({
+    outputFormat,
+    json: {
+      ...payload,
+      explanation: explain ? "Combines customer-facing weekly threat metrics with detector healthcheck coverage." : void 0
+    },
+    markdown: [
+      `# Preset: CS Weekly Health (${org})`,
+      "",
+      `- Range: ${startDate} -> ${endDate}`,
+      `- Reports: ${summary.metrics.reports}`,
+      `- New threats: ${summary.metrics.newThreats}`,
+      `- Found metric: ${found.found}`,
+      `- Detection configs checked: ${validation.summary.checkedConfigs}`,
+      `- Detection configs failing: ${validation.summary.failingConfigs}`
+    ].join("\n"),
+    csv: toCsvRows([
+      {
+        org,
+        startDate,
+        endDate,
+        reports: summary.metrics.reports,
+        newThreats: summary.metrics.newThreats,
+        found: found.found,
+        checkedConfigs: validation.summary.checkedConfigs,
+        failingConfigs: validation.summary.failingConfigs
+      }
+    ]),
+    human: () => {
+      console.log(`Preset "${presetId}" for ${org}`);
+      console.log(`Range: ${startDate} -> ${endDate}`);
+      console.log(
+        `Metrics: reports=${summary.metrics.reports} newThreats=${summary.metrics.newThreats} watchlisted=${summary.metrics.threatsWatchlisted}`
+      );
+      console.log(
+        `Found threats this week: ${found.found} | Detector health failures: ${validation.summary.failingConfigs}`
+      );
+      if (explain) {
+        console.log(
+          "This preset highlights weekly CS health outcomes plus detector reliability checks."
+        );
+      }
+    }
+  });
+  if (!validation.ok) {
+    throw new CliExitError(
+      "Preset completed with detector health failures.",
+      ExitCode.CHECK_FAILED
+    );
+  }
+}
+
+export {
+  PRESETS,
+  getPresetDefinition,
+  runPreset
+};

package/dist/chunk-E2LAMILJ.js

@@ -0,0 +1,48 @@
+// src/lib/exit-codes.ts
+var ExitCode = {
+  SUCCESS: 0,
+  UNKNOWN: 1,
+  AUTH: 2,
+  USAGE: 3,
+  NOT_FOUND: 4,
+  FORBIDDEN: 5,
+  CHECK_FAILED: 6,
+  MUTATION_PARTIAL_FAILURE: 7,
+  NETWORK_UNAVAILABLE: 8
+};
+var CliExitError = class extends Error {
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "CliExitError";
+    this.exitCode = exitCode;
+  }
+};
+function mapErrorToExitCode(error) {
+  if (error instanceof CliExitError) {
+    return error.exitCode;
+  }
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  if (message.includes("authentication failed") || message.includes("run `chainpatrol login`")) {
+    return ExitCode.AUTH;
+  }
+  if (message.includes("permission") || message.includes("forbidden")) {
+    return ExitCode.FORBIDDEN;
+  }
+  if (message.includes("not found")) {
+    return ExitCode.NOT_FOUND;
+  }
+  if (message.includes("cannot connect") || message.includes("network error") || message.includes("timed out") || message.includes("temporarily unavailable")) {
+    return ExitCode.NETWORK_UNAVAILABLE;
+  }
+  if (message.includes("usage") || message.includes("requires --") || message.includes("unknown command")) {
+    return ExitCode.USAGE;
+  }
+  return ExitCode.UNKNOWN;
+}
+
+export {
+  ExitCode,
+  CliExitError,
+  mapErrorToExitCode
+};