SK: 2832 Added Claude Code setup for Java

.claude/commands/code-quality.md

@@ -0,0 +1,90 @@
+---
+name: code-quality
+description: Quality pipeline — compile, checkstyle, build, tests, coverage check. Pass a class name to target a single test class.
+paths:
+  - src/**/*.java
+  - pom.xml
+exclude:
+  - src/main/java/com/skyflow/generated/**
+context: fork
+---
+
+Run the Skyflow Java SDK quality pipeline.
+
+Use `$ARGUMENTS` to target a specific test class (e.g. `BearerTokenTests`). If empty, run the full suite.
+
+> Baseline failures are documented in the Known Pre-existing Test Failures table.
+> Do not investigate them unless specifically asked. Only report failures **beyond** that baseline.
+
+## Coverage Requirements
+
+Follow the Tests coding rules (100% instruction + branch coverage). Public interface packages:
+- `src/main/java/com/skyflow/vault/` (controllers, data, tokens, connection, audit, bin, detect)
+- `src/main/java/com/skyflow/config/`
+- `src/main/java/com/skyflow/serviceaccount/`
+
+Flag any gap as a blocker — **NEEDS FIXES** if coverage is below 100% on Claude-written or public interface code.
+
+---
+
+## Pipeline
+
+### Step 1 — Compile
+```bash
+mvn compile -q 2>&1 | tail -20
+```
+Expected: no output (clean compile). Report any errors.
+
+### Step 2 — Checkstyle
+```bash
+mvn checkstyle:check -q 2>&1 | tail -20
+```
+Note: `failsOnError=false` in pom.xml means the build will not fail even if violations exist — check the output for `[WARN]` checkstyle lines. Violations are excluded from `generated/` by pom config.
+
+### Step 3 — Build
+```bash
+mvn package -DskipTests -q 2>&1 | tail -20
+```
+Expected: BUILD SUCCESS.
+
+### Step 4 — Tests
+If `$ARGUMENTS` is set:
+```bash
+mvn test -Dtest=$ARGUMENTS -q 2>&1 | tail -40
+```
+Otherwise:
+```bash
+mvn test -q 2>&1 | tail -40
+```
+Report: tests run, failures, errors. Flag any pre-existing failures separately from new ones.
+
+### Step 5 — Coverage analysis
+For every public interface class and every class touched by Claude in this session:
+- Check for a corresponding test file under `src/test/`
+- Check that every public method has at least one positive and one negative test case
+- Check that every branch (if/else, switch, try/catch) is covered
+
+List all gaps. Any gap on Claude-written or public interface code is a **blocker**.
+
+### Step 6 — Edge case identification
+For any class below 100% coverage, identify missing scenarios:
+- Null / empty inputs
+- Invalid types / wrong enum values
+- Concurrent / reuse scenarios
+- Error paths (API rejection, network failure)
+
+Write concrete JUnit 4 test method stubs (not full implementations) for each gap.
+
+### Step 7 — Report
+
+```
+| Step             | Status    | Notes                        |
+|------------------|-----------|------------------------------|
+| Compile          | ✅ / ❌   | ...                          |
+| Checkstyle       | ✅ / ❌   | ...                          |
+| Build            | ✅ / ❌   | ...                          |
+| Tests            | ✅ / ❌   | N passed, M failed           |
+| Coverage (100%)  | ✅ / ❌   | list classes with gaps       |
+```
+
+Conclude with **READY TO MERGE** or **NEEDS FIXES** and a prioritised fix list.

.claude/commands/code-review.md

@@ -0,0 +1,146 @@
+---
+name: code-review
+description: Full code review — SDK patterns, naming, test coverage, then runs /code-smell and /code-security.
+paths:
+  - src/main/java/**/*.java
+  - src/test/java/**/*.java
+exclude:
+  - src/main/java/com/skyflow/generated/**
+context: fork
+---
+
+You are a senior engineer performing a thorough code review on the Skyflow Java SDK.
+
+## Pre-requisite
+
+If `GITHUB_ACTIONS` environment variable is set, skip this step (CI runs compile/test in a separate job).
+
+Otherwise, confirm `/code-quality` has been run and passed (compile, tests, 100% coverage). If it has not been run, run it now before proceeding with the review.
+
+## Scope
+
+Use `$ARGUMENTS` to determine scope:
+- `full review` — scan all files under `src/main/java/com/skyflow/` recursively (exclude `generated/`)
+- A file or directory path — review only that path
+- Empty / default — review files changed on current PR/branch vs base:
+  ```bash
+  # REVIEW_BASE_SHA, when set (CI incremental review), is the last commit already
+  # reviewed by the bot — diff only lines added since then. Otherwise fall back to
+  # the PR base branch.
+  BASE="${REVIEW_BASE_SHA:-${GITHUB_BASE_REF:+origin/$GITHUB_BASE_REF}}"
+  BASE="${BASE:-main}"
+  git diff "$BASE"...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+  ```
+  **If `GITHUB_ACTIONS` is set:** work from the diff output directly (changed lines only) instead of reading full files:
+  ```bash
+  git diff "$BASE"...HEAD -- '*.java' | grep -v 'src/main/java/com/skyflow/generated/'
+  ```
+  Review only added lines (`+` prefix) from the diff. Do not comment on unchanged context lines or pre-existing code.
+
+---
+
+## Step 1 — SDK Pattern Review
+
+Review all files in scope against the rules defined in `CLAUDE.md` (loaded automatically from the project root). Check every rule category: naming conventions, error handling, request/response patterns, string literals, tests, and code quality.
+
+Group findings by file and produce a table:
+
+```
+### path/to/File.java
+
+| Severity | Category | Line | Finding |
+|----------|----------|------|---------|
+| Critical | Security    | 42  | SkyflowException swallowed in catch block |
+| High     | Correctness | 87  | skyflow_id not normalised to skyflowId |
+| Low      | Pattern     | 103 | Magic string "records" — use Constants |
+```
+
+Every finding has **two independent axes** — don't conflate them:
+
+**Severity** — *how serious* (one scale shared by all three steps):
+
+| Severity | Meaning | Blocks merge? |
+|---|---|---|
+| **Critical** | Data loss, security breach, silent failure | Yes |
+| **High** | Wrong behaviour / bug / guaranteed runtime failure | Yes |
+| **Medium** | Likely problem, risky or unhandled input, missing safeguard | Yes |
+| **Low** | Minor maintainability, naming, style, code smell | No — advisory |
+| **Info** | Note / FYI | No — advisory |
+
+**Category** — *what kind*: `Correctness` (a bug), `Edge case`, `Security`, `Pattern`, `Naming`, `Tests`, `Smell`.
+
+A logic bug is **Severity `High`/`Critical` + Category `Correctness`** — never severity "Bug". A magic string is **Severity `Low` + Category `Pattern`** — never severity "Quality". Keep level in the Severity column and kind in the Category column.
+
+---
+
+## Step 2 — Code Smell Analysis
+
+Read the file `.claude/commands/code-smell.md` and follow all of its instructions for the same files in scope. Produce its full output (per-file smell table + smell summary + recommendation).
+
+**If `GITHUB_ACTIONS` is set:** apply that command's **PR / CI mode** — report only smells introduced by added (`+`) lines; do not report whole-file metrics (Long class/method, large parameter list) or any pre-existing debt. Do **not** print code-smell's standalone tables, summary, or recommendation — collect its findings into the single consolidated report defined in **Output (PR / CI mode)** below.
+
+---
+
+## Step 3 — Security Audit
+
+Read the file `.claude/commands/code-security.md` and follow all of its instructions for the same files in scope. Produce its full output (per-finding blocks + summary table + overall risk rating).
+
+**If `GITHUB_ACTIONS` is set:** apply that command's **PR / CI mode** — report only issues introduced by added (`+`) lines; do not raise pre-existing vulnerabilities or whole-project checks the diff does not touch. Do **not** print code-security's standalone per-finding blocks, summary, or risk rating — collect its findings into the single consolidated report defined in **Output (PR / CI mode)** below.
+
+---
+
+## Final Verdict (local mode only)
+
+> Skip this section when `GITHUB_ACTIONS` is set — use **Output (PR / CI mode)** instead.
+
+After all three steps, close with:
+1. A tech-debt summary table grouped by category (SDK Patterns / Error Handling / Naming / Tests / Smells / Security)
+2. A verdict: `APPROVE` / `APPROVE WITH FIXES` / `REQUEST CHANGES`
+3. Remind: run `/code-quality` again after any fixes before merging.
+
+---
+
+## Output (PR / CI mode)
+
+When `GITHUB_ACTIONS` is set, your **entire output is the body of a code-review comment** — not a chat reply. The **first character must be the verdict**. Never emit any preamble, planning, narration, acknowledgement, "Now I have…/Let me…" line, restatement of the diff, or per-step headers. Describe the **review outcome**, not the PR.
+
+Merge every finding from Steps 1–3 into one de-duplicated report (same issue flagged by multiple steps → keep once at the highest severity). Emit **exactly** the following, and nothing else.
+
+**Rendering rules (GitHub markdown):** emit each part below as a **top-level block at the left margin**, separated by a blank line. The numbers are labels for you — do **not** reproduce them as a markdown numbered list, and do **not** indent the tables or `<details>` (tables/`<details>` nested inside list items do not render on GitHub). Every table needs a blank line before and after it, and `<details>` needs a blank line after the `</summary>` tag.
+
+**Severity buckets (single source of truth; Category is a separate axis, never a severity):**
+- **Blocking** (must fix before merge): `Critical`, `High`, `Medium`.
+- **Advisory** (does not block merge): `Low`, `Info`.
+
+1. **Verdict** (first line, nothing above it) — `REQUEST CHANGES` if ≥1 blocking finding; `APPROVE WITH FIXES` if only advisory; `APPROVE` if none. Follow it with **one short clause stating the theme/count only** — e.g. "— 2 error-handling issues on the changed lines." **Never enumerate or restate the individual findings**; the table already lists them.
+
+2. **Blocking-findings table** — `Critical` / `High` / `Medium` only (never `Low` / `Info`). The `Finding` cell is a **terse identifier (≤ ~12 words, a noun phrase)** — no mechanism, no "because…", no fix; the full explanation lives in the inline comment, so never repeat it here. If the **same issue appears at multiple locations**, emit **one row** with the locations comma-separated in `File:Line` (the inline block still gets one entry per location) — do not create near-duplicate rows. Omit the table and write "No blocking findings on the changed lines." if there are none.
+   ```
+   | File:Line | Severity · Category | Finding |
+   |-----------|---------------------|---------|
+   | HttpUtility.java:88 | High · Correctness | getMessage() returns null on the no-body error path |
+   | VaultClient.java:942, ConnectionClient.java:92 | Medium · Pattern | misleading EmptyCredentials message in generic catch |
+   ```
+
+3. **Advisory section (collapsed)** — every advisory finding, one crisp line each; `N` must equal the row count.
+   ```
+   <details><summary>Advisory (Low / Info) — N items</summary>
+
+   | File:Line | Severity · Category | Finding |
+   |-----------|---------------------|---------|
+   </details>
+   ```
+
+4. **Inline-findings block** — the **very last thing** in your output, wrapped in an **HTML comment** so it never renders even if parsing fails. Its body is a JSON array of **only blocking findings whose line is an added (`+`) line** (never advisory items, never lines outside the diff). Put the **full explanation in `comment`** (this is what renders inline on the code); keep the summary table above terse.
+
+   **Critical:** `comment` must be **plain text** — you may use single backticks for short identifiers, but **never triple backticks / code fences / `\`\`\`` anywhere inside the JSON** (they corrupt extraction). Describe the fix in prose, not a code block.
+
+   Use exactly these sentinels (emit `[]` for the array if there are no inline findings):
+
+   ```
+   <!-- ai-review-inline
+   [{ "path": "src/main/java/com/skyflow/Foo.java", "line": 42, "severity": "High", "category": "Correctness", "comment": "skyflow_id is not normalised to skyflowId before returning; normalise it in the controller." }]
+   -->
+   ```
+
+   The workflow extracts this block, strips it from the visible summary, and renders items 1–3 as the review body.

.claude/commands/code-security.md

@@ -0,0 +1,77 @@
+---
+name: code-security
+description: Security audit — credential exposure, input validation, path traversal, HTTP security, token lifecycle, dependency CVEs.
+paths:
+  - src/main/java/com/skyflow/**/*.java
+  - pom.xml
+exclude:
+  - src/main/java/com/skyflow/generated/**
+context: fork
+---
+
+You are a security engineer auditing the Skyflow Java SDK for vulnerabilities.
+
+## Audit Scope
+
+Use `$ARGUMENTS` to determine target files. If none provided, run:
+```bash
+# CI: GITHUB_BASE_REF is set (e.g. "main") — use origin/ prefix
+# Local: unset — use main directly
+BASE="${GITHUB_BASE_REF:+origin/$GITHUB_BASE_REF}"
+BASE="${BASE:-main}"
+git diff "$BASE"...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+```
+
+**If `GITHUB_ACTIONS` is set (PR review mode):** audit only the code this PR changed. Work from the diff:
+```bash
+git diff "$BASE"...HEAD -- '*.java' | grep -v 'src/main/java/com/skyflow/generated/'
+```
+Report a finding **only if an added line (`+` prefix) introduces or directly exposes it.** Do not raise pre-existing vulnerabilities in unchanged code, and skip whole-project checks the diff does not touch (e.g. the dependency-CVE check in §6 unless `pom.xml` changed). If the added lines introduce no security issues, state that explicitly rather than listing pre-existing risks. (Local / non-CI runs and explicit file arguments keep full-file auditing.)
+
+## Security Checks
+
+### 1. Credential and token exposure (Critical)
+- Bearer tokens, API keys, and private keys must never appear in logs, error messages, exception messages, or `toString()` output
+- `Credentials` fields (`path`, `token`, `apiKey`, `credentialsString`) must not be serialised to logs
+- JWT claims must not be logged
+
+### 2. Input validation (High)
+- All string inputs from callers must be null/empty checked before use
+- File paths passed to `new File(path)` must not allow path traversal (`../`)
+- JSON strings parsed with `JsonParser` must be wrapped in try/catch for `JsonSyntaxException`
+
+### 3. Credentials file handling (High)
+- Credentials files must only be read from paths provided by the caller — no environment variable path injection without sanitisation
+- `FileReader` must be in a try-with-resources or explicitly closed
+
+### 4. HTTP security (Medium)
+- All API calls must go over HTTPS — verify `Utils.getBaseURL` enforces this
+- Authorization headers must not be logged at any log level
+- HTTP timeouts must be configured
+
+### 5. Error information leakage (Medium)
+- `SkyflowException` messages must not include raw server response bodies that could contain PII
+- Stack traces must not be surfaced to callers — wrap in `SkyflowException`
+
+### 6. Dependency vulnerabilities (Low)
+- Note any dependencies that are known to have CVEs (check pom.xml versions)
+
+### 7. Authentication lifecycle (Medium)
+- Bearer token caching must check expiry before reuse
+- Token refresh must be thread-safe (`synchronized` or equivalent)
+
+## Output Format
+
+For each finding:
+
+```
+### path/to/File.java : line N
+
+**Severity:** Critical / High / Medium / Low / Info
+**Risk:** What an attacker could do
+**Trigger:** Input or code path that triggers the vulnerability
+**Fix:** Concrete remediation with code example
+**CWE:** CWE-NNN
+```
+
+End with a summary table and overall risk rating.