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,83 @@
+---
+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
+  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:** 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 | Line | Finding |
+|----------|------|---------|
+| Critical | 42   | SkyflowException swallowed in catch block |
+| Bug      | 87   | skyflow_id not normalised to skyflowId |
+| Quality  | 103  | Magic string "records" — use Constants |
+```
+
+**Severities:**
+
+| Level | Meaning |
+|---|---|
+| **Critical** | Data loss, silent failure, security risk — must fix before merge |
+| **Bug** | Wrong behaviour, incorrect output — must fix before merge |
+| **Edge Case** | Unhandled input that will cause runtime failure — fix before merge |
+| **Quality** | Maintainability issue, naming violation, missing pattern — fix before merge |
+
+---
+
+## 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).
+
+---
+
+## 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).
+
+---
+
+## Final Verdict
+
+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.

.claude/commands/code-security.md

@@ -0,0 +1,71 @@
+---
+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'
+```
+
+## 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.

.claude/commands/code-smell.md

@@ -0,0 +1,149 @@
+---
+name: code-smell
+description: Structural smell analysis + spell check — long methods, dead code, misplaced validation, deep nesting, magic numbers. Does not check patterns or security.
+paths:
+  - src/main/java/**/*.java
+  - src/test/java/**/*.java
+  - .claude/**/*.md
+  - docs/**/*.md
+exclude:
+  - src/main/java/com/skyflow/generated/**
+context: fork
+---
+
+You are a senior engineer performing a code smell analysis on the Skyflow Java SDK.
+
+## Scope
+
+Use `$ARGUMENTS` to determine scope:
+- A file or directory path — analyse only that path
+- Empty / default — analyse files changed on current branch vs `main`:
+  ```bash
+  git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+  ```
+
+---
+
+## Spell check
+
+Before analysing smells, run cspell on the files in scope:
+
+```bash
+npx cspell --no-progress "src/**/*.java" ".claude/**/*.md" "CLAUDE.md" "docs/**/*.md" 2>&1 | grep "Unknown word"
+```
+
+Report any spelling violations at **Smell** severity in the per-file table. The word list is in `.cspell.json` — add legitimate project-specific terms there rather than fixing them as typos.
+
+---
+
+## What Are Code Smells
+
+Code smells are structural signals — they do not necessarily mean the code is broken, but they indicate areas of technical debt, reduced readability, or future maintenance risk. All findings are reported at **Smell** severity and do not block merge unless they indicate a design violation.
+
+---
+
+## Smell Catalogue
+
+### Method & Class Size
+
+**Long method** — any method over 40 lines.
+Signal: the method is doing too much. Candidate for decomposition into named private helpers.
+
+**Long class** — any class over 300 lines.
+Signal: the class may be taking on too many responsibilities. Check if it can be split by concern.
+
+**Large parameter list** — more than 4 parameters on a method.
+Signal: consider a config/options object or a builder to group related parameters.
+
+---
+
+### Responsibility Violations
+
+**Business logic in Request/Response classes**
+Request and Response classes are data holders — they carry data, nothing more. Flag any conditional logic, field transformation, or computation beyond null-safe getters.
+Example of a violation: a Response class that renames map keys in `toString()` instead of letting the controller do it.
+
+**toString() with business logic**
+`toString()` should only serialise state for debugging. Logic like field renaming, manual JSON construction, conditional field injection, or iteration belongs in the controller or formatter methods.
+
+**Validation outside `Validations.java`**
+Any `if (x == null) throw new SkyflowException(...)` outside `src/main/java/com/skyflow/utils/validations/` is misplaced validation. All request validation must live in `Validations.validateXxxRequest()`.
+
+---
+
+### Control Flow
+
+**Deep nesting** — more than 3 levels of `if` / `for` / `try` nesting.
+Signal: extract inner blocks to named private methods. Deep nesting hides the happy path.
+
+**Long if-else chains** — more than 4 branches on the same condition.
+Signal: consider a `Map`, `switch`, or polymorphism.
+
+**Null checks scattered**
+Multiple consecutive null guards that could be replaced with `Optional` or an early return guard clause.
+
+---
+
+### Data
+
+**Magic numbers**
+Literal integers or sizes (e.g. `25`, `3600`, `100`) without a named constant. Use `Constants`.
+
+**Raw HashMap chains**
+`HashMap<String, Object>` passed through more than 2 method boundaries without a typed wrapper or explanatory comment. Flag for awareness — do not require an immediate fix.
+
+**Temporary field**
+A class field that is only set in certain code paths and is `null` the rest of the time. Should be a local variable or method parameter instead.
+
+---
+
+### Dead Code
+
+**Unused private methods** — private methods with no callers.
+
+**Unused imports** — any `import` not referenced in the file.
+
+**Unreachable code** — code after `return` / `throw` in the same branch.
+
+**Commented-out code** — blocks of commented code without explanation. Remove entirely or add a `// TODO: [ticket]` with context.
+
+---
+
+### Comments
+
+**Explains what, not why**
+A comment that restates what the code does (`// get the vault ID`) adds no value. Only flag comments that explain the *what* without explaining *why*.
+
+**Stale comment**
+A comment that contradicts the current code — e.g. references a removed parameter, an old method name, or a behaviour that has changed.
+
+---
+
+## Output Format
+
+Group findings by file:
+
+```
+### path/to/File.java
+
+| Smell                     | Line | Detail                                                    |
+|---------------------------|------|-----------------------------------------------------------|
+| Long method               | 42   | processInsertResponse() is 67 lines — decompose          |
+| Business logic in Response| 88   | toString() renames skyflow_id — move to formatter         |
+| Magic number              | 103  | Literal 25 — extract to Constants.MAX_QUERY_RECORDS       |
+| Stale comment             | 210  | References removed tokenizedData field                    |
+| Dead code                 | 315  | Private method buildHeaders() has no callers              |
+```
+
+End with a **Smell Summary** table:
+
+```
+| Category              | Count | Files affected         |
+|-----------------------|-------|------------------------|
+| Long methods          | 2     | VaultController.java   |
+| Business logic in DTO | 1     | QueryResponse.java     |
+| Magic numbers         | 3     | Validations.java       |
+| Dead code             | 2     | Utils.java             |
+```
+
+Close with a recommendation: **CLEAN** / **MINOR DEBT** / **SIGNIFICANT DEBT** and a one-sentence summary.