Claude code Setup

.claude/commands/code-review.md

@@ -0,0 +1,107 @@
+---
+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
+---
+
+You are a senior engineer performing a thorough code review on the Skyflow Java SDK.
+
+## 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 branch vs `main`:
+  ```bash
+  git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+  ```
+
+**Skip entirely:** `src/main/java/com/skyflow/generated/` — Fern-generated REST client, read-only.
+
+---
+
+## Step 1 — SDK Pattern Review
+
+Check the files in scope against the rules below.
+
+### 1. Request / Response / Options patterns
+
+- Request builders are plain data holders — validation happens in `Validations.validateXxxRequest()` inside the controller, not in `build()`. Flag if validation logic is duplicated outside `Validations`.
+- Response getters returning `ArrayList<HashMap<String, Object>>` is the established SDK pattern — do not flag these as violations.
+- All response classes must have `getErrors()` returning `null` (not absent) when no errors.
+- No separate `*Options` classes exist — options are fields on the request builder itself.
+- SDK must not add field-level null/empty validation on top of what the backend enforces. Only structural checks (`table == null`, `values == null`) are permitted.
+
+### 2. Error handling
+
+- All public methods must declare `throws SkyflowException`
+- `SkyflowException` must be thrown (not swallowed) on invalid input
+- No `System.out.println` or bare `e.printStackTrace()` — use `LogUtil`
+- Catch blocks must not silently drop exceptions
+- `catch (Exception e)` without re-throw or explicit handling is a critical issue
+
+### 3. Naming conventions and response field normalisation
+
+Follow the conventions in CLAUDE.md under "Naming Conventions". Key enforcement points:
+- Acronyms as words: `skyflowId`, `tokenUri`, `clientId` — never uppercase abbreviations
+- Builder setters: `setFooId()` not `setFooID()`; constants: `UPPER_SNAKE_CASE`; classes: `PascalCase`
+- Response maps: `skyflowId` (camelCase) only — never `skyflow_id`; `getErrors()` must be present on every response class
+- Deprecated methods: `@Deprecated(since = "x.x", forRemoval = true)` + `@deprecated` Javadoc with `{@link}` to replacement
+
+### 5. Test coverage
+
+- Every public method must have at least one positive and one negative test
+- Tests must use `Assert.assertEquals` / `Assert.assertNull` — not just `Assert.fail` guards
+- No mocking of the production class under test
+- Reflection-based tests on private methods are acceptable only when no public API exercises the method
+
+### 6. Code quality
+
+- No magic strings for API field names — use `Constants` or `ErrorMessage` enums
+- No duplicate validation logic across request classes — belongs in `Validations`
+- No `@SuppressWarnings` without a comment explaining why
+- `LogUtil.printWarningLog` must be used for deprecation warnings, not `System.err`
+
+### Output for Step 1
+
+Group findings by file:
+
+```
+### 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`

.claude/commands/code-security.md

@@ -0,0 +1,69 @@
+---
+name: code-security
+description: Security audit — credential exposure, input validation, path traversal, HTTP security, token lifecycle, dependency CVEs.
+paths:
+  - src/main/java/com/skyflow/serviceaccount/**/*.java
+  - src/main/java/com/skyflow/config/**/*.java
+  - src/main/java/com/skyflow/utils/**/*.java
+  - src/main/java/com/skyflow/vault/controller/**/*.java
+  - pom.xml
+---
+
+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
+git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+```
+
+**Skip:** `src/main/java/com/skyflow/generated/` — observations only, no edits.
+
+## 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,145 @@
+---
+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
+---
+
+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'
+  ```
+
+**Skip entirely:** `src/main/java/com/skyflow/generated/` — Fern-generated REST client, read-only.
+
+---
+
+## 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.

.claude/commands/commit.md

@@ -0,0 +1,55 @@
+---
+name: commit
+description: Stage check + Jira-aware commit — extracts ticket ID from branch name and validates against pr.yml commit-message check.
+---
+
+Create a git commit for staged changes on the current branch.
+
+Use `$ARGUMENTS` as the commit message description. If empty, ask the user for a description before proceeding.
+
+## Step 1 — Extract ticket ID from branch name
+
+```bash
+git rev-parse --abbrev-ref HEAD
+```
+
+Extract the Jira ticket ID using the pattern `[A-Z]{1,10}-[0-9]+`:
+- `devesh/SK-1234-fix-foo` → `SK-1234`
+- `karthik/GV-770-ext-auth-json-error` → `GV-770`
+- `username/SDK-2814-some-fix` → `SDK-2814`
+
+If no ticket ID is found, **stop** and ask the user to provide one before continuing.
+
+## Step 2 — Check what is staged
+
+```bash
+git status --short
+git diff --cached --stat
+```
+
+If nothing is staged, list the unstaged files and ask the user which files to stage. Do not run `git add .` — ask for explicit paths (`.env`, `credentials.json`, and `generated/` must never be staged).
+
+## Step 3 — Assemble and validate the commit message
+
+Build the message as:
+```
+<ticket-id> <description>
+```
+
+If the user provided a Conventional Commits prefix (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`), prepend it:
+```
+feat: SK-1234 add bulk insert support
+fix: GV-770 handle null bearer token on refresh
+```
+
+Validate against the `pr.yml` enforced pattern: `(\[?[A-Z]{1,10}-[1-9][0-9]*)|(\[AUTOMATED\])|(Merge)|(Release)`
+- Must contain a Jira ID — a bare description without a ticket ID will fail CI.
+- If validation fails, report the exact requirement and stop.
+
+## Step 4 — Commit
+
+```bash
+git commit -m "<assembled message>"
+```
+
+Report the resulting commit SHA and the commit message first line.