@jfrog/opencode-jfrog-plugin 0.0.2 → 0.0.4

package/skills/jfrog/references/platform-access-entities.md

@@ -0,0 +1,200 @@
+# Platform / Access entities
+
+When to read this file:
+
+- Explaining how **Projects**, **repositories**, **members**, **roles**, and
+  **environments** fit together.
+- Working with **users**, **groups**, or **access tokens** at the platform level.
+- Building **inventories or reports** that join Artifactory data with
+  Access / Projects.
+- Avoiding two common mistakes: inferring project membership from
+  **repository name**, or assuming **roles** are identical across projects.
+
+For endpoint-level curl examples, see `projects-api.md`. For list-vs-detail
+API patterns and batching, see `general-bulk-operations-and-agent-patterns.md`.
+
+## Entity relationship overview
+
+```mermaid
+erDiagram
+    Project ||--o{ Repository : "projectKey"
+    Project ||--o{ ProjectRole : defines
+    Project ||--o{ ProjectMember : has
+    ProjectMember }o--|| Principal : "user or group"
+    ProjectRole }o--o{ Environment : "environments array"
+    Repository }o--o{ Environment : "repo env assignment"
+    User ||--o{ AccessToken : "creates"
+    User }o--o{ Group : "belongs to"
+    Permission }o--o{ Repository : "targets"
+    Permission }o--o{ Principal : "grants actions to"
+```
+
+## Project
+
+Organizational container for grouping members, roles, and resources.
+
+| Field | Description |
+|-------|-------------|
+| `project_key` | Unique identifier (short string, used in APIs and repo assignment) |
+| `display_name` | Human-readable name |
+| `description` | Project description |
+| `admin_privileges` | Flags controlling project-level admin behavior |
+| `storage_quota` | Storage limits for the project |
+
+A project hosts **members** (users and groups with roles) and **resources**
+(repositories, builds, Release Bundles) assigned to it.
+
+API: `GET /access/api/v1/projects`, `GET /access/api/v1/projects/<project-key>`.
+
+Documentation: [Get Started with Projects](https://docs.jfrog.com/projects/docs),
+[Basic Projects Terminology](https://docs.jfrog.com/projects/docs/basic-projects-terminology).
+
+## Project role
+
+Per-project role definition that scopes what members may do.
+
+| Field | Description |
+|-------|-------------|
+| `name` | Role name (e.g. `Developer`, `Release Manager`) |
+| `type` | `PREDEFINED` or `CUSTOM` |
+| `environments` | List of environments where the role applies (e.g. `["DEV", "PROD"]`) |
+| `actions` | Permitted actions within those environments |
+
+Predefined role templates exist, but projects can define **custom roles**.
+Two projects may have different custom roles or different definitions for
+roles with the same name — always fetch per project when reporting.
+
+API: `GET /access/api/v1/projects/<project-key>/roles`.
+
+## Project member
+
+A user or group assigned a role within a project.
+
+| Field | Description |
+|-------|-------------|
+| `name` | Username or group name |
+| `roles` | List of role names assigned in this project |
+
+Membership is **not** the same as global platform administration. Roles are
+evaluated in a project context — a user can be a Developer in one project
+and a Release Manager in another.
+
+API: `GET /access/api/v1/projects/<project-key>/users`,
+`GET /access/api/v1/projects/<project-key>/groups`.
+
+## Environment
+
+Environments group resources and scope RBAC so that roles can have different
+permissions per environment (e.g. separate DEV vs PROD behavior).
+
+| Field | Description |
+|-------|-------------|
+| `name` | Environment name (e.g. `DEV`, `STAGING`, `PROD`) |
+
+Environments can be defined at **global** scope (available across projects) or
+**project** scope. Repositories can be assigned to one or more environments.
+Environments are also used in release bundle promotion and application version
+promotion (see `release-lifecycle-entities.md` and `apptrust-entities.md`).
+
+API: `GET /access/api/v1/environments`.
+
+Documentation: [Environments](https://docs.jfrog.com/administration/docs/environments).
+
+## User
+
+A platform identity that authenticates and is granted permissions.
+
+| Field | Description |
+|-------|-------------|
+| `username` | Unique login name |
+| `email` | Email address |
+| `status` | `enabled` or `disabled` |
+| `admin` | Whether the user has platform admin privileges |
+| `groups` | Groups the user belongs to |
+| `realm` | Authentication realm (e.g. `internal`, `ldap`, `saml`) |
+
+Users can be managed via REST API or synced from external identity providers
+(LDAP, SAML, SCIM).
+
+API: `GET /access/api/v2/users/`, `GET /access/api/v2/users/<username>`.
+
+## Group
+
+A named collection of users that simplifies permission management.
+
+| Field | Description |
+|-------|-------------|
+| `name` | Group name |
+| `description` | Group description |
+| `auto_join` | Whether new users automatically join this group |
+| `admin_privileges` | Whether group members have admin privileges |
+| `realm` | Source realm (e.g. `internal`, `ldap`) |
+| `external_id` | External identity provider ID (for synced groups) |
+
+Groups can be assigned permissions and project roles, applying them to all
+members at once.
+
+API: `GET /access/api/v2/groups/`, `GET /access/api/v2/groups/<group-name>`.
+
+## Access token
+
+A bearer credential with scoped permissions and optional expiry.
+
+| Field | Description |
+|-------|-------------|
+| `token_id` | Unique token identifier |
+| `subject` | The user or service the token represents |
+| `scope` | Permission scope (e.g. `applied-permissions/admin`, `applied-permissions/groups:readers`) |
+| `expires_in` | TTL in seconds (0 = non-expiring) |
+| `refreshable` | Whether the token can be refreshed |
+| `description` | Human-readable description |
+
+Tokens are the primary authentication mechanism for API and CLI access.
+They can be scoped to specific groups, projects, or admin-level permissions.
+
+CLI: `jf access-token-create [username] [options]`.
+
+API: `POST /access/api/v1/tokens`.
+
+## Repository–Project assignment
+
+A repository is linked to **at most one** project via the `projectKey` field
+in its configuration.
+
+| Rule | Detail |
+|------|--------|
+| **Authoritative field** | `projectKey` on the repository configuration |
+| **Not authoritative** | Repository name — a naming pattern like `<project-key>-<suffix>` is a convention, not a guarantee |
+| **Unassigned** | Missing or empty `projectKey` means the repo is not tied to any project |
+
+## Agent rules
+
+### 1. Repository to project (authoritative)
+
+1. Obtain repository keys from `GET /api/repositories` (lite list).
+2. For each key, call `GET /api/repositories/<repo-key>` and read `projectKey`.
+3. Treat missing or empty `projectKey` as **unassigned**, regardless of
+   whether the repo name looks like `<project-key>-...`.
+
+Do **not** infer project membership from naming alone. A name-prefix filter is
+only a heuristic when detail calls are impossible, and is not authoritative.
+
+Cost: one list plus N detail calls. Batch in one Shell invocation; reuse
+captured JSON per SKILL.md "Preserving command output" when iterating with `jq`.
+
+### 2. Project roles (per project)
+
+For each `project_key` in a multi-project report or comparison, call:
+
+`GET /access/api/v1/projects/<project-key>/roles`
+
+Do **not** reuse one project's role payload as representative of all projects.
+
+## Further reading
+
+- [JFrog documentation URLs in this skill](jfrog-url-references.md)
+- [Get Started with Projects](https://docs.jfrog.com/projects/docs)
+- [Basic Projects Terminology](https://docs.jfrog.com/projects/docs/basic-projects-terminology)
+- [Environments (Administration)](https://docs.jfrog.com/administration/docs/environments)
+- [Projects API (interactive reference)](https://docs.jfrog.com/projects/reference)
+- [Projects API (this skill)](projects-api.md)

package/skills/jfrog/references/platform-admin-api-gaps.md

@@ -0,0 +1,164 @@
+# Platform Administration API Gaps
+
+Operations available through REST API but not (or only partially) through the
+CLI. Invoke all of them via `jf api` (see the base skill's *Invoking platform
+APIs with `jf api`* section). Authentication is handled automatically from
+the configured `jf` server — no token extraction needed. Every path includes
+the product prefix (`/access/...`, `/artifactory/...`, `/xray/...`,
+`/worker/...`).
+
+## Users (full CRUD)
+
+The CLI has `users-create` and `users-delete` but lacks GET and UPDATE.
+
+### Get user details
+```bash
+jf api /access/api/v2/users/<username>
+```
+
+### List users
+```bash
+jf api /access/api/v2/users/
+```
+
+### Update user (partial)
+```bash
+jf api /access/api/v2/users/<username> \
+  -X PATCH -H "Content-Type: application/json" \
+  -d '{"email": "newemail@example.com"}'
+```
+
+### Create user
+```bash
+jf api /access/api/v2/users/ \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"username": "newuser", "email": "user@example.com", "password": "...", "admin": false}'
+```
+
+## Groups (full CRUD)
+
+### Get group details
+```bash
+jf api /access/api/v2/groups/<groupname>
+```
+
+### List groups
+```bash
+jf api /access/api/v2/groups/
+```
+
+## Permissions (full CRUD)
+
+### List permissions
+```bash
+jf api /access/api/v2/permissions/
+```
+
+### Get permission details
+```bash
+jf api /access/api/v2/permissions/<permission-name>
+```
+
+## Access tokens (beyond CLI)
+
+The CLI has `access-token-create` but not list or revoke.
+
+### List tokens
+```bash
+jf api /access/api/v1/tokens
+```
+
+### Revoke token by ID
+```bash
+jf api /access/api/v1/tokens/<token-id> -X DELETE
+```
+
+## Environments
+
+### List global environments
+```bash
+jf api /access/api/v1/environments
+```
+
+### Create global environment
+```bash
+jf api /access/api/v1/environments \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"name": "STAGING"}'
+```
+
+## Projects
+
+See `references/projects-api.md` for full project CRUD, members, roles, and
+environments.
+
+## Webhooks
+
+### List webhooks
+```bash
+jf api /access/api/v1/webhooks
+```
+
+### Create webhook
+```bash
+jf api /access/api/v1/webhooks \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"key": "my-webhook", "url": "https://example.com/hook", "event_types": ["uploaded"]}'
+```
+
+## System health
+
+### Platform ping
+```bash
+jf api /artifactory/api/system/ping
+```
+
+### Artifactory version
+```bash
+jf api /artifactory/api/system/version
+```
+
+### Xray ping
+```bash
+jf api /xray/api/v1/system/ping
+```
+
+### Xray version
+```bash
+jf api /xray/api/v1/system/version
+```
+
+## OIDC configuration
+
+### List OIDC providers
+```bash
+jf api /access/api/v1/oidc
+```
+
+### Create OIDC configuration
+```bash
+jf api /access/api/v1/oidc \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"name": "my-oidc", "issuer_url": "https://...", "provider_type": "generic"}'
+```
+
+## SCIM (user provisioning)
+
+### Get SCIM users
+```bash
+jf api /access/api/v1/scim/v2/Users
+```
+
+## Workers (beyond CLI)
+
+The CLI covers most worker operations. These are API-only:
+
+### Get available actions
+```bash
+jf api /worker/api/v1/actions
+```
+
+### Get actions metadata
+```bash
+jf api /worker/api/v1/actions/metadata
+```

package/skills/jfrog/references/platform-admin-operations.md

@@ -0,0 +1,58 @@
+# Platform Administration Operations
+
+CLI and REST commands for platform-wide administration: access tokens, login,
+stats, projects, and system health.
+
+## Access tokens
+
+```bash
+jf access-token-create [username] [options]
+```
+
+Key options: `--groups`, `--scope`, `--expiry`, `--refreshable`, `--description`.
+
+## Login
+
+For login, see `references/jfrog-login-flow.md`.
+
+## Stats
+
+```bash
+jf stats rt [--server-id <id>] [--format json|table]
+```
+
+## Projects
+
+Projects are managed via the Access API (no CLI subcommand). Invoke the
+endpoints through `jf api` (see the base skill's *Invoking platform APIs
+with `jf api`* section). Authentication is handled automatically:
+
+```bash
+jf api /access/api/v1/projects
+```
+
+- **List projects**: `GET /access/api/v1/projects`
+- **Get project**: `GET /access/api/v1/projects/<project-key>`
+- **List members**: `GET /access/api/v1/projects/<project-key>/users`
+- **List groups**: `GET /access/api/v1/projects/<project-key>/groups`
+- **List roles**: `GET /access/api/v1/projects/<project-key>/roles`
+- **List environments**: `GET /access/api/v1/environments`
+
+When querying multiple projects, batch the calls in a single Shell invocation
+to avoid per-project round-trips:
+
+```bash
+for proj in proj1 proj2 proj3; do
+  jf api "/access/api/v1/projects/$proj/users"
+done
+```
+
+Read `references/projects-api.md` for detailed endpoint patterns including
+creating/updating projects, managing members, and assigning repositories.
+
+## System health
+
+Not available as a dedicated CLI subcommand. Use:
+```bash
+jf api /artifactory/api/system/ping
+```

package/skills/jfrog/references/projects-api.md

@@ -0,0 +1,241 @@
+# JFrog Projects API
+
+**See also:** `references/platform-access-entities.md` for how Projects relate to
+repositories, members, roles, and environments.
+
+Projects are managed through the Access API. There is no CLI subcommand —
+invoke the endpoints via `jf api` (see the base skill's *Invoking platform
+APIs with `jf api`* section). Authentication against the resolved JFrog
+server is automatic.
+
+All endpoints below use full product-prefixed paths (`/access/api/...`,
+`/artifactory/api/...`).
+
+## Authentication
+
+Credentials are resolved automatically by `jf api` from the active `jf config`
+server — no token extraction or `curl` wiring is needed.
+
+## Projects
+
+### List all projects
+
+```bash
+jf api /access/api/v1/projects
+```
+
+Returns an array of project objects with `project_key`, `display_name`,
+`description`, `admin_privileges`, `storage_quota_bytes`, etc.
+
+### Get a single project
+
+```bash
+jf api /access/api/v1/projects/<project-key>
+```
+
+### Create a project
+
+```bash
+jf api /access/api/v1/projects \
+  -X POST -H "Content-Type: application/json" \
+  -d '{
+    "display_name": "My Project",
+    "description": "Project description",
+    "admin_privileges": {
+      "manage_members": true,
+      "manage_resources": true,
+      "index_resources": true
+    },
+    "project_key": "myproj"
+  }'
+```
+
+The `project_key` must be 2-32 lowercase alphanumeric characters (hyphens
+allowed, no leading/trailing hyphen).
+
+### Update a project
+
+```bash
+jf api /access/api/v1/projects/<project-key> \
+  -X PUT -H "Content-Type: application/json" \
+  -d '{"display_name": "Updated Name", "description": "Updated description"}'
+```
+
+### Delete a project
+
+```bash
+jf api /access/api/v1/projects/<project-key> -X DELETE
+```
+
+## Members
+
+### List project members (users)
+
+```bash
+jf api /access/api/v1/projects/<project-key>/users
+```
+
+Returns `{"members": [{"name": "<username>", "roles": ["<role-name>"]}]}`.
+
+### Add a member
+
+```bash
+jf api /access/api/v1/projects/<project-key>/users/<username> \
+  -X PUT -H "Content-Type: application/json" \
+  -d '{"name": "<username>", "roles": ["Developer"]}'
+```
+
+### Remove a member
+
+```bash
+jf api /access/api/v1/projects/<project-key>/users/<username> -X DELETE
+```
+
+### List project groups
+
+```bash
+jf api /access/api/v1/projects/<project-key>/groups
+```
+
+The response may list group entries under **`members`**, **`groups`**, or both,
+depending on platform version (same general shape as users: `name` and
+`roles`). Parsers should accept whichever key is present.
+
+### Add a group
+
+```bash
+jf api /access/api/v1/projects/<project-key>/groups/<group-name> \
+  -X PUT -H "Content-Type: application/json" \
+  -d '{"name": "<group-name>", "roles": ["Contributor"]}'
+```
+
+## Roles
+
+### List project roles
+
+```bash
+jf api /access/api/v1/projects/<project-key>/roles
+```
+
+Returns an array of role objects. Each has `name`, `description`, `type`
+(`PREDEFINED`, `ADMIN`, or `CUSTOM`), `environments` (e.g. `["DEV","PROD"]`),
+and `actions` (permission strings).
+
+Predefined roles: Project Admin, Developer, Contributor, Viewer, Release
+Manager, Security Manager, AppTrust Manager, Model Governor, Model Developer.
+
+**Multi-project reports:** Call this endpoint **once per `project_key`**. Custom
+roles and definitions can differ by project; do not assume one project's role
+list matches another. See `references/platform-access-entities.md`.
+
+### Create a custom role
+
+```bash
+jf api /access/api/v1/projects/<project-key>/roles \
+  -X POST -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Engineer",
+    "description": "Read and annotate repos in DEV",
+    "type": "CUSTOM",
+    "environments": ["DEV"],
+    "actions": ["READ_REPOSITORY", "ANNOTATE_REPOSITORY", "READ_BUILD"]
+  }'
+```
+
+## Environments
+
+The product supports **global** and **project-scoped** environment concepts for
+RBAC and resource grouping; see
+[Environments (Administration)](https://docs.jfrog.com/administration/docs/environments)
+and `references/platform-access-entities.md`.
+
+### List environments (platform API)
+
+```bash
+jf api /access/api/v1/environments
+```
+
+Returns `[{"name": "DEV"}, {"name": "PROD"}, ...]` -- the platform environment
+list available through this Access API path.
+
+### Create an environment
+
+```bash
+jf api /access/api/v1/environments \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"name": "STAGING"}'
+```
+
+Environment names are uppercase by convention.
+
+## Repository assignment
+
+### Assign a repository to a project
+
+Assign a repository to a project by updating its configuration:
+
+```bash
+jf api /artifactory/api/repositories/<repo-key> \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"projectKey": "<project-key>"}'
+```
+
+### List repositories for a project
+
+`GET /artifactory/api/repositories` supports optional query parameters that can
+be combined:
+
+| Parameter | Values | Example |
+|-----------|--------|---------|
+| `project` | project key | `?project=myproj` |
+| `type` | `local`, `remote`, `virtual` | `?type=local` |
+| `packageType` | `docker`, `maven`, `npm`, etc. | `?packageType=docker` |
+
+```bash
+# All repos in a project
+jf api "/artifactory/api/repositories?project=<project-key>"
+
+# Only local Docker repos in a project
+jf api "/artifactory/api/repositories?project=<project-key>&type=local&packageType=docker"
+
+# All remote repos (no project filter)
+jf api "/artifactory/api/repositories?type=remote"
+```
+
+Returns a lite list with `key`, `type`, `packageType`, and `url` per repo.
+See `references/artifactory-api-gaps.md` for additional filter examples.
+
+### Get repository detail
+
+To retrieve the full configuration of a specific repository (including fields
+like `projectKey`, `description`, storage settings, etc. that are absent from
+the lite list), use the detail endpoint:
+
+```bash
+jf api "/artifactory/api/repositories/<repo-key>"
+```
+
+Use this when you have a specific repo or a short list of repos to inspect --
+not for filtering large sets. For filtering, use the query parameters above.
+
+### Name-prefix heuristic (unreliable -- last resort)
+
+Project-scoped repos often follow a `<project-key>-*` naming convention, but
+the API does **not** enforce this. Repos can belong to a project without the
+prefix, or carry the prefix without belonging. Always prefer
+`?project=<project-key>` for authoritative results. Use name-prefix matching
+only when the `project` query parameter is unavailable (e.g. older Artifactory
+versions).
+
+## Common error responses
+
+- **Empty members/groups**: projects with no members return
+  `{"members": []}`, not 404. The groups list endpoint may use the same
+  `members` key for group entries; empty lists look like `{"members": []}`.
+  Always check the array rather than the status code alone.
+- **Invalid project key on create**: returns 400 if `project_key` is outside
+  2-32 chars, contains uppercase letters, or has leading/trailing hyphens.
+- **Project not found**: returns 404 with `{"errors": [{"message": "..."}]}`.
+- **Insufficient permissions**: `jf api` exits with code 1 on non-2xx and
+  prints `[Warn] jf api: ... returned 403` on stderr when the token lacks
+  project admin or platform admin privileges.