jfrog/opencode-jfrog-plugin/jfrog-init

/jfrog-init — verify and guide JFrog plugin readiness

First output must be a tool call, not text. No "I'll start..." preamble.

Walks a fixed, ordered checklist and stops at the first non-passing result, guiding the user through the matching fix before re-checking. Every detector in scripts/ is idempotent, read-only, JSON-emitting, and implemented in Node (.mjs), so the same detector runs unmodified on macOS, Linux, and Windows. Step 3's web-login uses this skill's own local .mjs scripts, same as every other step. The one interactive fix step that isn't a Node script at all is Step 1's Node install itself — a missing Node can't run a .mjs installer, so that one step branches on OS or shell directly.

Approval model — every user-approval point is detailed in its own Step below (exact wording, AskUserQuestion payloads, forbidden phrases); this is just the map:

• `node` — AskUserQuestion Yes/No before auto-installing (Step 1).
• `jf` (JFrog CLI) — AskUserQuestion Yes/No before auto-installing

(Step 2).

• `jf config` — AskUserQuestion picker (web login, in-session, vs.

access token, which never enters this conversation) (Step 3/4).

• Project selection — the user answers with a project name or key;

an AskUserQuestion picker offers the first two enumerated projects plus "Other" (Step 6).

• Everything else is read-only, except: Step 5's placeholder

substitution and OpenCode-only mcp.jfrog write (both unattended, no AskUserQuestion — see references/script-invocation.md); Step 8's headers-helper install and Claude Code config writes (same, see references/marketplace-setup.md); and the Final summary's state write below.

Step 1's nvm install and jfrog-install-jf-cli.mjs, Step 3's web-login scripts, Step 8's jfrog-add-claude-marketplace.mjs call, and the Final summary's jfrog-state-file.mjs set call are deliberately not in allowed-tools and will raise the harness's own approval prompt — intended, not a misconfiguration; see references/script-invocation.md.

Step 0: resolve the ${CLAUDE_SKILL_DIR} placeholder (do this FIRST)

`${CLAUDE_SKILL_DIR}` is this skill's own absolute directory — the folder holding this SKILL.md, scripts/, and references/. Every node "${CLAUDE_SKILL_DIR}/scripts/…" command below needs it resolved first.

• Claude Code — substitutes it automatically. Run commands as

written.

• Every other harness — you MUST look it up and export it before

Step 1:

1. Look up this skill's absolute directory from wherever your

harness loaded this file (per-harness plugin roots are listed in references/mcp-plugin-config.md). On OpenCode specifically, it announces its own real path in its own preamble — use that value directly instead of hunting for it.

1. Export it:

``bash export CLAUDE_SKILL_DIR="<absolute path to this skill's directory>" ``

1. Verify with the sentinel — STOP and re-resolve if it fails:

``bash ls "${CLAUDE_SKILL_DIR}/scripts/jfrog-detect-jf-cli.mjs" ``

1. If your harness does not persist environment variables across

commands, use the resolved absolute path directly in every node invocation instead of ${CLAUDE_SKILL_DIR}.

Skipping this fails silently rather than loudly — see references/script-invocation.md for why. Step 0 resolves script paths; Step 5's JFROG_INIT_HARNESS resolves harness detection. Non-Claude harnesses need both.

At a glance (always-read core)

• Order matters. Walk Steps 1–8

in exact order, stop at the first non-passing result — except Step 5's failure/error outcomes, Step 5b entirely, Step 6's one-retry cap, Step 7's "not entitled" and "catalog unreachable" outcomes, and Step 8 entirely (all five non-blocking). See The checklist, in order.

• Capturing the exit code before forcing success is mandatory (`;

rc=$?; true bash / ; $rc=$LASTEXITCODE; exit 0 PowerShell — see references/invoking-and-output-rules.md`'s "Invoking scripts" section). A bare success-forcer with no capture hides every failure/ask result as success.

• Approval gates: AskUserQuestion Yes/No before auto-installing

Node (Step 1) or jf (Step 2); AskUserQuestion picker for web-login vs. token (Step 3/4); AskUserQuestion picker for project selection (Step 6). Everything else is read-only except Step 5's placeholder substitution (plus OpenCode mcp.jfrog write, and the kiro-cli ~/.kiro/settings/mcp.json / Junie ~/.junie/mcp/mcp.json merge), Step 8's headers-helper install and Claude Code config writes, and the Final summary's state write.

• Never surface the checklist. Run silently — no step narration, no

raw JSON/exit codes, no branch-reasoning said out loud. See references/invoking-and-output-rules.md's "Customer-facing output" section.

• `<server-id>` for Steps 4-7 always comes from the shared resolver

(explicit arg → JF_SERVER_ID → isDefault → sole configured server → ask) — never invented, never jf's own fallback. Step 8 reuses the same value. See Resolving `<server-id>`.

• Persist state before the final summary — run

jfrog-state-file.mjs set whenever Steps 1-4 all pass, regardless of Step 5/6/7. See Final summary.

• Close with the Final summary. When Steps 1-4 pass, render the

Final summary checklist — never end on ad-hoc "Summary / Changes" status text.

• Never store, log, or print an access token — credentials stay

inside jf's own process or in-memory for one fetch call. Step 8 stores none: Claude Code's marketplace config names a helper that asks jf at request time — see Step 8 and Non-goals.

• **This skill is the exception to, not a consumer of, the base

`../jfrog/SKILL.md`'s prerequisites** — do not run its environment check as a gate before starting this walk.

Steps: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8

Prerequisites

• **Read the base `../jfrog/SKILL.md` for foundational

context** — JFrog Platform concepts and terminology, and the Server selection rules this skill's own "Resolving <server-id>" section (below) follows the same never-guess/never-infer philosophy of, via its own mechanism.

• **This skill is the exception that makes the base skill's prerequisites

true, not a consumer of them.** The base skill's environment check assumes jf is already installed at a working version — /jfrog-init is what gets a user from nothing installed to that point. Do not run the base skill's environment check as a gate before starting this walk; Steps 1-4 below are this skill's own, more granular equivalent (Node, jf CLI install, connection, credentials) purpose-built for the "nothing works yet" case.

• Deliberately does not export `JFROG_CLI_USER_AGENT`, unlike the

base skill's invariant — see runJf() in scripts/lib/jf.mjs for why (telemetry-only impact).

Operating rules

Stop and read `references/invoking-and-output-rules.md` in full before running any command in this walk — required behavior, not optional background. It covers three things:

• Customer-facing output — the user never sees step numbers, raw

JSON/exit codes, or branch-selection reasoning; only asks, failures in plain English, and the final summary.

• Invoking scripts: exit codes are signal, not failure — every

detector needs ; rc=$?; true appended, and every Step's branch table below keys off that captured exit code.

• Flow — follow the flow literally, no reordering or skipping; see

references/flow-diagram.md for the full map.

The checklist, in order

1. Node.js ≥ 18 installed? — no script; run node --version / npx --version directly
2. JFrog CLI (`jf`) installed? — scripts/jfrog-detect-jf-cli.mjs
3. `jf` connected to a server? — scripts/jfrog-detect-jf-config.mjs
4. Server reachable + credentials valid? — scripts/jfrog-detect-server-ping.mjs [server-id]
5. JFrog MCP plugin file has a jfrog entry? — scripts/jfrog-detect-jfrog-mcp.mjs [server-id], then is the JFrog MCP server enabled on this JPD? — scripts/jfrog-detect-jfrog-mcp-responding.mjs [server-id] (non-blocking)

• 5b (OpenCode only): MCP auth token present? —

scripts/jfrog-detect-opencode-mcp-auth.mjs, runs only when Step 5 exits 0 and the harness is OpenCode

1. Project resolved? — scripts/jfrog-detect-project.mjs [server-id] [project-input]
2. AI Catalog reachable & user entitled? — scripts/jfrog-detect-catalog-runtime.mjs [server-id]
3. Claude agent-plugin marketplace registered? — scripts/jfrog-add-claude-marketplace.mjs [server-id] [project-key], Claude Code only

Run detectors in this exact order and stop at the first non-passing result — except Step 5 going into failure/error (see Step 5), Step 5b entirely (see Step 5b), Step 6 hitting its one-retry cap (see Step 6), Step 7's "not entitled" and "catalog unreachable" outcomes (see Step 7), and Step 8 entirely (see Step 8), all five non-blocking. Step 1 has no script — a Node script can't verify Node exists — so every step after it is written in Node and can assume Node is present. The JPD URL is read directly from jf config; there is no separate JFROG_PLATFORM_URL env var. The project key is asked every walk in Step 6 (the state file at ~/.jfrog/setup.json may supply a "reuse the current project?" hint); Step 7's catalog probe takes no project argument — it only checks catalog reachability and entitlement for the resolved server.

Resolving <server-id> for Steps 4-7

Order (used by every detector that takes [server-id] — resolved through the single shared scripts/jfrog-resolve-jf-server.mjs):

1. Explicit argument passed to the detector.
2. JF_SERVER_ID env var.
3. The server flagged `"isDefault": true` in ~/.jfrog/jfrog-cli.conf.v6

— resolved automatically via scripts/jfrog-resolve-jf-server.mjs.

1. If only one server is configured, it is used silently.
2. Otherwise the detector exits 2 ("ask") with a JSON candidates

list of the configured server IDs. Stop and read `references/server-picker.md` in full — it has the exact AskUserQuestion payload for showing the user the actual servers to pick from; do not paraphrase or invent your own prompt. Never invent a server, never rely on jf's own fallback.

Step 1: Node.js ≥ 18 installed?

node --version; true
npx --version; true

No script — Node's own binary is the only thing that can answer "is Node installed", so there's nothing a script would check that these two commands don't already answer directly. Checked first because every other script in this walk — including every other detector — is a Node program. npx matters because the JFrog MCP server (mcpServers.jfrog, Step 5) is launched via npx @jfrog/agent-guard — no npx means the MCP entry can't start, regardless of everything else.

Read the output yourself, no JSON to parse: