narai-primitives 2.0.0-rc.1

package/plugins/gcp-agent/skills/gcp-agent/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gcp-agent
+description: |
+  Use when the user asks about read-only GCP inventory — Cloud Run services,
+  Cloud SQL instances, Pub/Sub topics, or Cloud Logging entries. Queries are
+  scoped to a single GCP project. Never modifies GCP resources.
+context: fork
+---
+
+# GCP Agent
+
+Answer the user's question by invoking the `gcp-agent` binary exposed by
+this plugin. It delegates to `@narai/gcp-agent-connector`, which speaks to
+GCP by shelling out to `gcloud` / `bq` with Application Default Credentials.
+
+## Invocation
+
+```
+gcp-agent --action <action> --params '<json>'
+```
+
+The CLI writes a single JSON envelope to stdout and exits 0 on success, 1
+on a handled error, 2 on CLI misuse. Return the envelope verbatim to the
+orchestrator.
+
+## Supported actions
+
+| Action | Required params |
+|---|---|
+| `list_services` | `project_id` |
+| `describe_db` | `project_id`, `instance_id`, optional `database` |
+| `list_topics` | `project_id` |
+| `query_logs` | `project_id`, `filter`, optional `hours` (default 24, max 168), optional `max_results` (default 100, max 1000) |
+
+Example:
+
+```bash
+gcp-agent --action list_services --params '{"project_id":"acme-prod-123"}'
+```
+
+## Credentials
+
+Uses Application Default Credentials. Before first use, run:
+
+```bash
+gcloud auth application-default login
+```
+
+## Safety
+
+Read-only by construction: the connector enforces a binary and sub-command
+whitelist at the `execFileSync` layer, forbids shell strings, and refuses
+write-style flags. Cannot invoke `create`, `delete`, `update`, or any
+mutating `gcloud` sub-command.

package/plugins/github-agent/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "github-agent-plugin",
+  "version": "1.0.0",
+  "description": "Read-only GitHub connector for Claude Code. Wraps @narai/github-agent-connector.",
+  "author": "narai"
+}

package/plugins/github-agent/README.md

@@ -0,0 +1,13 @@
+# github-agent-plugin
+
+Claude Code plugin wrapping `@narai/github-agent-connector`. Same layout as the other platform plugins.
+
+## Credentials
+
+```bash
+export GITHUB_TOKEN="ghp_…"
+```
+
+## License
+
+MIT

package/plugins/github-agent/bin/github-agent

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "github-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/github-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "github-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/github-agent/commands/github-agent.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only GitHub query via the github-agent connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `github-agent` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/github-agent/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "github" }
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+            "env": {
+              "USAGE_CONNECTOR_NAME": "github",
+              "USAGE_BIN_HINT": "@narai/github-agent-connector"
+            }
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "github" }
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/github-agent/hooks/reminder.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder for the GitHub connector.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["github"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/github-agent/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "github-agent-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@narai/github-agent-connector": "file:.."
+  }
+}

package/plugins/github-agent/skills/github-agent/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: github-agent
+description: |
+  Use when the user asks about read-only GitHub data — repository info,
+  code search, issue/PR listing, or single-file retrieval. Never
+  modifies GitHub.
+context: fork
+---
+
+# GitHub Agent
+
+Answer the user's question by invoking the `github-agent` binary
+exposed by this plugin. It delegates to
+`@narai/github-agent-connector` via GitHub's REST v3 + GraphQL APIs.
+
+## Invocation
+
+```
+github-agent --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action | Required params |
+|---|---|
+| `repo_info` | `owner`, `repo` |
+| `search_code` | `query`, optional `max_results` |
+| `get_issues` | `owner`, `repo`, optional `state`, `max_results` |
+| `get_pulls` | `owner`, `repo`, optional `state`, `max_results` |
+| `get_file` | `owner`, `repo`, `path`, optional `ref` |
+
+## Credentials
+
+Export `GITHUB_TOKEN` (PAT with `repo` / `read:org` as needed).
+
+## Safety
+
+Read-only — only GET (REST) and POST /graphql (read-only queries)
+are permitted.

package/plugins/jira-agent/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "jira-agent-plugin",
+  "version": "1.0.0",
+  "description": "Read-only Jira connector for Claude Code. Wraps @narai/jira-agent-connector.",
+  "author": "narai"
+}

package/plugins/jira-agent/README.md

@@ -0,0 +1,15 @@
+# jira-agent-plugin
+
+Claude Code plugin wrapping `@narai/jira-agent-connector`. Same layout as the other platform plugins.
+
+## Credentials
+
+```bash
+export JIRA_SITE_URL="https://your.atlassian.net"
+export JIRA_EMAIL="you@example.com"
+export JIRA_API_TOKEN="…"
+```
+
+## License
+
+MIT

package/plugins/jira-agent/bin/jira-agent

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "jira-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/jira-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "jira-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/jira-agent/commands/jira-agent.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only Jira query via the jira-agent connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `jira-agent` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/jira-agent/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "jira" }
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+            "env": {
+              "USAGE_CONNECTOR_NAME": "jira",
+              "USAGE_BIN_HINT": "@narai/jira-agent-connector"
+            }
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "jira" }
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/jira-agent/hooks/reminder.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder for the Jira connector.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["jira"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/jira-agent/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "jira-agent-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@narai/jira-agent-connector": "file:.."
+  }
+}

package/plugins/jira-agent/skills/jira-agent/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: jira-agent
+description: |
+  Use when the user asks about read-only Jira data — JQL search, single
+  issue details, or project metadata. Never modifies Jira.
+context: fork
+---
+
+# Jira Agent
+
+Answer the user's question by invoking the `jira-agent` binary exposed
+by this plugin. It delegates to `@narai/jira-agent-connector` via
+Atlassian's Jira REST v3.
+
+## Invocation
+
+```
+jira-agent --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action | Required params |
+|---|---|
+| `jql_search` | `jql`, optional `max_results` (default 50, max 500) |
+| `get_issue` | `issue_key` (e.g. `FOO-123`), optional `expand` |
+| `get_project` | `project_key` (e.g. `FOO`) |
+
+## Credentials
+
+Set `JIRA_SITE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` before use.
+
+## Safety
+
+Read-only — only GET requests permitted.

package/plugins/notion-agent/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "notion-agent-plugin",
+  "version": "1.0.0",
+  "description": "Read-only Notion connector for Claude Code. Wraps @narai/notion-agent-connector.",
+  "author": "narai"
+}

package/plugins/notion-agent/README.md

@@ -0,0 +1,23 @@
+# notion-agent-plugin
+
+Claude Code plugin that wraps `@narai/notion-agent-connector` as a read-only Notion skill and slash command.
+
+- Skill `notion-agent` — automatic invocation for Notion workspace questions.
+- Slash command `/notion-agent <action> <params-json>`.
+- Binary `notion-agent` — thin shim over the installed connector CLI.
+
+## How install works
+
+On first `SessionStart` the hook copies `package.json` into
+`${CLAUDE_PLUGIN_DATA}` and runs `npm install --no-audit --no-fund` there
+once. After that, `${CLAUDE_PLUGIN_DATA}/node_modules/@narai/notion-agent-connector/dist/cli.js`
+exists and `bin/notion-agent` exec's it.
+
+## Credentials
+
+Export `NOTION_TOKEN` before starting Claude Code, or configure a
+credential provider via `@narai/credential-providers`.
+
+## License
+
+MIT

package/plugins/notion-agent/bin/notion-agent

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "notion-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/@narai/notion-agent-connector/dist/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "notion-agent: connector CLI not found at $CLI" >&2
+  echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
+  exit 2
+fi
+
+exec node "$CLI" "$@"

package/plugins/notion-agent/commands/notion-agent.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only Notion query via the notion-agent connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `notion-agent` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/notion-agent/hooks/hooks.json

@@ -0,0 +1,49 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/plugin/hooks/reminder.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/stale-summarize.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "notion" }
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/usage-record.mjs\" 2>/dev/null || true",
+            "env": {
+              "USAGE_CONNECTOR_NAME": "notion",
+              "USAGE_BIN_HINT": "@narai/notion-agent-connector"
+            }
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/@narai/connector-toolkit/plugin-hooks/session-summary.mjs\" 2>/dev/null || true",
+            "env": { "USAGE_CONNECTOR_NAME": "notion" }
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/notion-agent/hooks/reminder.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * SessionStart curation reminder for the Notion connector.
+ * See Confluence connector for pattern docs.
+ */
+try {
+  const data = process.env.CLAUDE_PLUGIN_DATA;
+  if (!data) process.exit(0);
+  const toolkitEntry = `${data}/node_modules/@narai/connector-toolkit/dist/plugin/reminder.js`;
+  const mod = await import(toolkitEntry);
+  const decision = mod.evaluateNudge({ connectors: ["notion"] });
+  if (decision.nudge) {
+    process.stdout.write(decision.banner + "\n");
+  }
+} catch {
+  // best-effort — reminder never blocks startup
+}

package/plugins/notion-agent/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "notion-agent-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@narai/notion-agent-connector": "file:.."
+  }
+}

package/plugins/notion-agent/skills/notion-agent/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: notion-agent
+description: |
+  Use when the user asks about read-only Notion workspace content — search,
+  page contents, database schema, or database queries. Never modifies Notion.
+context: fork
+---
+
+# Notion Agent
+
+Answer the user's question by invoking the `notion-agent` binary exposed
+by this plugin. It delegates to `@narai/notion-agent-connector`, which
+speaks to the Notion Public API with a `NOTION_TOKEN` integration secret.
+
+## Invocation
+
+```
+notion-agent --action <action> --params '<json>'
+```
+
+Return the JSON envelope from the CLI verbatim.
+
+## Supported actions
+
+| Action | Required params |
+|---|---|
+| `search` | `query`, optional `filter_type` (`page`/`database`), optional `max_results` (default 25, max 100) |
+| `get_page` | `page_id` (UUID) |
+| `get_database` | `database_id` (UUID) |
+| `query_database` | `database_id`, optional `filter` object, optional `max_results` |
+
+Example:
+
+```bash
+notion-agent --action search --params '{"query":"architecture","filter_type":"page"}'
+```
+
+## Credentials
+
+Set `NOTION_TOKEN` to a Notion internal integration secret. The
+integration must be invited to the pages/databases you want to read.
+
+## Safety
+
+Read-only by construction: the connector's HTTP method whitelist allows
+`GET` plus only two narrow `POST` endpoints (`/v1/search` and
+`/v1/databases/{id}/query`, which Notion requires `POST` for despite
+being read). No other endpoints can be reached.