narai-primitives 2.1.3 → 2.3.0

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

@@ -0,0 +1,146 @@
+---
+name: jira-connector
+description: |
+  Use when the user asks about Jira data or wants to create, update, or
+  delete Jira content — JQL search, issue details, project metadata,
+  comments, attachments, status transitions, or any write operation on
+  issues and comments. Supports both read and write surfaces; every action
+  passes the policy gate before any network call is made: read actions
+  succeed by default, write and delete actions escalate by default,
+  privilege actions are hard-denied.
+context: fork
+---
+
+# Jira Connector
+
+Answer the user's question by invoking the `jira-connector` binary exposed by
+this plugin. It delegates to `narai-primitives/jira`, which enforces the
+policy gate before any Atlassian REST v3 call is made.
+
+## Invocation
+
+```
+jira-connector --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action              | Classification | Required params                                                              | Optional params                                                           |
+|---------------------|----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| `jql_search`        | read           | `jql`                                                                        | `max_results` (default 50, max 500)                                       |
+| `get_issue`         | read           | `issue_key` (e.g. `PROJ-123`)                                                | `expand` (array of field names)                                           |
+| `get_project`       | read           | `project_key` (e.g. `PROJ`)                                                  |                                                                           |
+| `list_attachments`  | read           | `issue_key`                                                                  |                                                                           |
+| `get_attachment`    | read           | `issue_key`, `attachment_id`                                                 |                                                                           |
+| `get_comments`      | read           | `issue_key`                                                                  | `max_results` (default 50)                                                |
+| `create_issue`      | write          | `project_key`, `issue_type`, `summary`                                       | `description` (content input), `labels`, `assignee_account_id`, `parent_key` |
+| `update_issue`      | write          | `issue_key`                                                                  | `summary`, `description` (content input), `labels`, `assignee_account_id` |
+| `delete_issue`      | write/delete   | `issue_key`                                                                  |                                                                           |
+| `add_comment`       | write          | `issue_key`, `body` (content input)                                          |                                                                           |
+| `update_comment`    | write          | `issue_key`, `comment_id`, `body` (content input)                            |                                                                           |
+| `delete_comment`    | write/delete   | `issue_key`, `comment_id`                                                    |                                                                           |
+| `transition_issue`  | write          | `issue_key`, `transition_id`                                                 | `comment` (content input)                                                 |
+| `post_attachment`   | write          | `issue_key`, `files` (array — see Multipart upload)                          |                                                                           |
+
+## Envelope shape
+
+**success**
+```json
+{"status": "success", "action": "create_issue", "data": {"key": "PROJ-123", "id": "10456", "self": "https://acme.atlassian.net/rest/api/3/issue/10456"}}
+```
+
+**escalate** (default for write/delete actions)
+```json
+{"status": "escalate", "action": "create_issue", "reason": "WRITE statements require approval"}
+```
+
+**denied** (default for privilege actions, or operator-set policy)
+```json
+{"status": "denied", "action": "delete_issue", "reason": "DELETE actions are not allowed by operator policy"}
+```
+
+**error**
+```json
+{"status": "error", "action": "create_issue", "error_code": "VALIDATION_ERROR", "message": "Invalid ADF: root.type must be 'doc'", "retriable": false}
+```
+
+## Content input (ADF / markdown / plain)
+
+Fields that accept body text (`description`, `body`, `comment`) use a
+discriminated union so you can pass whichever format is most convenient:
+
+**markdown** (converted via marklassian; output validated via assertValidAdf):
+```json
+{"description": {"format": "markdown", "value": "# Title\n\nSome **bold** text."}}
+```
+
+**ADF** (passed through; validated via assertValidAdf):
+```json
+{"description": {"format": "adf", "value": {"type": "doc", "version": 1, "content": []}}}
+```
+
+**plain** (wrapped in an ADF paragraph node):
+```json
+{"description": {"format": "plain", "value": "Just text."}}
+```
+
+## Multipart upload
+
+`post_attachment` uploads one or more files to an issue. Each entry in
+`files` is either inline base64 or a local path:
+
+```json
+{
+  "issue_key": "PROJ-1",
+  "files": [
+    {"filename": "report.pdf", "content_base64": "JVBERi..."},
+    {"path": "./uploads/screenshot.png"}
+  ]
+}
+```
+
+Path inputs must resolve under the current working directory (validated via
+the toolkit's `checkPathContainment`); any path that escapes CWD returns a
+`VALIDATION_ERROR` envelope without making any network call.
+
+## Credentials
+
+Set these environment variables before use:
+
+| Variable         | Description                                  |
+|------------------|----------------------------------------------|
+| `JIRA_SITE_URL`  | Your Atlassian site URL (e.g. `https://acme.atlassian.net`) |
+| `JIRA_EMAIL`     | Atlassian account email                      |
+| `JIRA_API_TOKEN` | Atlassian API token                          |
+
+Alternatively, register a credential provider via
+`narai-primitives/credentials`. Per-site credentials can be configured
+under `connectors.jira.options.sites.<alias>` in
+`~/.connectors/config.yaml`.
+
+## Safety
+
+Read AND write surface; the policy gate gates every action before any
+network call is made. WRITE escalates by default; DELETE also escalates by
+default; PRIVILEGE is hard-denied. Never bypass the `jira-connector` binary to
+call the Atlassian REST API directly — the binary is the only sanctioned
+channel. Never edit the operator's config to weaken a policy decision;
+report the decision instead.
+
+Default policy (operator may override under `connectors.jira.policy` in
+`~/.connectors/config.yaml`; per-site override under
+`connectors.jira.options.sites.<alias>.policy`):
+
+```yaml
+policy:
+  read: allow
+  write: escalate
+  delete: escalate
+  admin: deny
+  privilege: deny
+```
+
+The `admin` and `privilege` rules cannot be set to `allow` — the safety
+floor is enforced at config load.

package/plugins/linear-connector/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "linear-connector-plugin",
+  "version": "1.0.0",
+  "description": "Read + write CRUD on Linear issues, projects, comments, and attachment links. Policy-gated.",
+  "author": "narai"
+}

package/plugins/linear-connector/README.md

@@ -0,0 +1,29 @@
+# linear-connector plugin
+
+Claude Code plugin for the Linear connector. Exposes the `linear-connector` binary
+that delegates to `narai-primitives/linear` — a GraphQL-based connector with
+7 read actions and 7 write actions for Linear issues, comments, and attachments.
+
+## Environment variables
+
+| Variable          | Description                        |
+|-------------------|------------------------------------|
+| `LINEAR_API_KEY`  | Linear personal API key (no Bearer prefix — Linear is opinionated) |
+
+Obtain your API key from Linear → Settings → API → Personal API keys.
+
+## Credentials note
+
+The connector reads `LINEAR_API_KEY` from the environment. You can also
+register a credential provider via `narai-primitives/credentials`, or
+configure it under `connectors.linear.options.api_key` in
+`~/.connectors/config.yaml`.
+
+The authorization header sent to `https://api.linear.app/graphql` is:
+
+```
+Authorization: <api_key>
+```
+
+Note: Linear does **not** use a `Bearer` prefix — this is Linear-specific
+and differs from most REST APIs.

package/plugins/linear-connector/bin/linear-connector

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
+  echo "linear-connector: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  exit 2
+fi
+
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/linear/cli.js"
+
+if [ ! -f "$CLI" ]; then
+  echo "linear-connector: 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/linear-connector/commands/linear-connector.md

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

package/plugins/linear-connector/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "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_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/linear-connector/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "linear-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/linear-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "linear",
+  "binPath": "narai-primitives/dist/connectors/linear"
+}

package/plugins/linear-connector/skills/linear-connector/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: linear-connector
+description: |
+  Use when the user asks about Linear data or wants to create, update, or
+  archive Linear content — issue search, issue details, project metadata,
+  comments, attachment links, or any write operation on issues and comments.
+  Supports both read and write surfaces; every action passes the policy gate
+  before any network call is made: read actions succeed by default, write and
+  delete actions escalate by default, privilege actions are hard-denied.
+context: fork
+---
+
+# Linear Connector
+
+Answer the user's question by invoking the `linear-connector` binary exposed by
+this plugin. It delegates to `narai-primitives/linear`, which enforces the
+policy gate before any Linear GraphQL call is made.
+
+## Invocation
+
+```
+linear-connector --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action               | Classification | Required params                                          | Optional params                                                            |
+|----------------------|----------------|----------------------------------------------------------|----------------------------------------------------------------------------|
+| `get_issue`          | read           | `id` (identifier like `ENG-123` or UUID)                 |                                                                            |
+| `search_issues`      | read           |                                                          | `team_key`, `state`, `assignee_email`, `text`, `max_results` (default 50) |
+| `get_project`        | read           | `id` (UUID)                                              |                                                                            |
+| `get_team`           | read           | `key_or_id` (team key like `ENG` or UUID)                |                                                                            |
+| `get_comments`       | read           | `issue_id`                                               | `max_results` (default 50)                                                 |
+| `list_attachments`   | read           | `issue_id`                                               |                                                                            |
+| `get_attachment`     | read           | `attachment_id`                                          | Use `list_attachments` first to get the URL; then fetch externally.        |
+| `create_issue`       | write          | `team_id`, `title`                                       | `description` (markdown), `assignee_id`, `label_ids`, `priority`, `parent_id` |
+| `update_issue`       | write          | `id`                                                     | `title`, `description`, `assignee_id`, `state_id`, `priority`             |
+| `archive_issue`      | write/delete   | `id`                                                     |                                                                            |
+| `add_comment`        | write          | `issue_id`, `body` (markdown)                            |                                                                            |
+| `update_comment`     | write          | `comment_id`, `body` (markdown)                          |                                                                            |
+| `delete_comment`     | write/delete   | `comment_id`                                             |                                                                            |
+| `attachment_link`    | write          | `issue_id`, `title`, `url`                               | `subtitle`, `metadata`                                                     |
+
+## Envelope shape
+
+**success**
+```json
+{"status": "success", "action": "create_issue", "data": {"id": "abc-uuid", "identifier": "ENG-123", "url": "https://linear.app/team/issue/ENG-123", "title": "Fix login bug", "created_at": "2026-05-01T00:00:00.000Z"}}
+```
+
+**escalate** (default for write/delete actions)
+```json
+{"status": "escalate", "action": "create_issue", "reason": "WRITE statements require approval"}
+```
+
+**denied** (default for privilege actions, or operator-set policy)
+```json
+{"status": "denied", "action": "archive_issue", "reason": "DELETE actions are not allowed by operator policy"}
+```
+
+**error**
+```json
+{"status": "error", "action": "get_issue", "error_code": "NOT_FOUND", "message": "Issue 'ENG-999' not found", "retriable": false}
+```
+
+## Issue identifiers
+
+Linear issues can be addressed two ways:
+
+- **Identifier** (human-readable): `ENG-123` — team key + number
+- **UUID** (internal): `abc12345-...` — 32+ hex character UUID
+
+Both formats are accepted by `get_issue`, `search_issues`, `get_comments`,
+`list_attachments`, `update_issue`, `archive_issue`, `add_comment`.
+
+## Descriptions and comments
+
+Linear is **markdown-native**. Pass descriptions and comment bodies as plain
+markdown strings — no ADF conversion needed:
+
+```json
+{
+  "team_id": "team-uuid",
+  "title": "Fix login redirect",
+  "description": "## Problem\n\nUsers are redirected to a blank page after login.\n\n## Steps to reproduce\n\n1. Log out\n2. Log in again"
+}
+```
+
+## Priority values
+
+Linear priorities map to integers:
+
+| Value | Label     |
+|-------|-----------|
+| 0     | No priority |
+| 1     | Urgent    |
+| 2     | High      |
+| 3     | Medium    |
+| 4     | Low       |
+
+## Attachment linking
+
+Linear does not host files via the public API. Use `attachment_link` to
+associate an externally-hosted URL with an issue:
+
+```json
+{
+  "issue_id": "ENG-123",
+  "title": "Design mockup",
+  "url": "https://figma.com/file/abc",
+  "subtitle": "v3 iteration"
+}
+```
+
+## Credentials
+
+Set this environment variable before use:
+
+| Variable          | Description                                  |
+|-------------------|----------------------------------------------|
+| `LINEAR_API_KEY`  | Linear personal API key                      |
+
+Obtain from Linear → Settings → API → Personal API keys.
+
+The authorization header is `Authorization: <api_key>` (no `Bearer` prefix —
+this is Linear-specific).
+
+Alternatively, configure under `connectors.linear.options.api_key` in
+`~/.connectors/config.yaml`.
+
+## Safety
+
+Read AND write surface; the policy gate gates every action before any network
+call is made. WRITE escalates by default; DELETE also escalates by default;
+PRIVILEGE is hard-denied. Never bypass the `linear-connector` binary to call the
+Linear GraphQL API directly — the binary is the only sanctioned channel. Never
+edit the operator's config to weaken a policy decision; report the decision
+instead.
+
+`archive_issue` and `delete_comment` are classified as `{kind: "write", aspects: ["delete"]}`.
+Linear has no hard-delete via the public API; `archive_issue` invokes the
+`issueArchive` mutation which sets `archivedAt`.
+
+Default policy (operator may override under `connectors.linear.policy` in
+`~/.connectors/config.yaml`):
+
+```yaml
+policy:
+  read: allow
+  write: escalate
+  delete: escalate
+  admin: deny
+  privilege: deny
+```
+
+The `admin` and `privilege` rules cannot be set to `allow` — the safety floor
+is enforced at config load.

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

@@ -0,0 +1,6 @@
+{
+  "name": "notion-connector-plugin",
+  "version": "1.1.0",
+  "description": "Read + write CRUD on Notion pages, blocks, and database entries. Policy-gated.",
+  "author": "narai"
+}

package/plugins/{notion-agent → notion-connector}/README.md

@@ -1,17 +1,17 @@
-# notion-agent-plugin
+# notion-connector-plugin
 
 Claude Code plugin that wraps `narai-primitives/notion` 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.
+- Skill `notion-connector` — automatic invocation for Notion workspace questions.
+- Slash command `/notion-connector <action> <params-json>`.
+- Binary `notion-connector` — 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-primitives/dist/connectors/notion/cli.js`
-exists and `bin/notion-agent` exec's it.
+exists and `bin/notion-connector` exec's it.
 
 ## Credentials
 

package/plugins/{notion-agent/bin/notion-agent → notion-connector/bin/notion-connector}

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

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

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

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

@@ -0,0 +1,50 @@
+{
+  "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_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/notion-connector/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "notion-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/notion-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "notion",
+  "binPath": "narai-primitives/dist/connectors/notion"
+}