feat(add): improved bucket provider support

Author: CodeMeAPixel

.claude/commands/add-api-route.md

@@ -0,0 +1,44 @@
+# add-api-route
+
+Scaffold a new API route following Emberly's conventions.
+
+## Pattern
+
+```ts
+// app/api/<path>/route.ts
+import { HTTP_STATUS, apiError, apiResponse } from '@/packages/lib/api/response'
+import { requireAdmin } from '@/packages/lib/auth/api-auth' // or requireAuth for user-level
+import { prisma } from '@/packages/lib/database/prisma'
+import { loggers } from '@/packages/lib/logger'
+
+const logger = loggers.api // pick the right logger namespace
+
+export async function GET(req: Request) {
+  try {
+    const { response, session } = await requireAdmin(req) // or requireAuth
+    if (response) return response
+
+    // ... handler logic ...
+
+    return apiResponse(data)
+  } catch (error) {
+    logger.error('Failed to ...', error as Error)
+    return apiError('Internal server error', HTTP_STATUS.INTERNAL_SERVER_ERROR)
+  }
+}
+```
+
+## Auth helpers
+
+| Helper              | Use when                                       |
+| ------------------- | ---------------------------------------------- |
+| `requireAdmin(req)` | Admin panel routes — user must have ADMIN role |
+| `requireAuth(req)`  | Authenticated user routes                      |
+| `verifyApiKey(req)` | API key auth (programmatic access)             |
+
+## Rules
+
+- Always wrap in try/catch and return `apiError('Internal server error')` on unexpected failures.
+- Never return raw S3 secrets or sensitive credentials.
+- Validate and sanitise body input before using it in DB queries.
+- Use `prisma` from `@/packages/lib/database/prisma`, never instantiate a new client.

.claude/commands/add-integration.md

@@ -0,0 +1,31 @@
+# add-integration
+
+Add a new third-party integration (API key / credentials) to Emberly's configuration system.
+
+## What to do
+
+1. **Add the Zod schema** in `packages/lib/config/index.ts` under `settings.integrations`:
+
+   ```ts
+   myservice: z.object({
+     apiKey: z.string().optional().default(''),
+   }).passthrough().optional().default({}),
+   ```
+
+2. **Add the default value** in the `DEFAULT_CONFIG` object in the same file:
+
+   ```ts
+   myservice: { apiKey: '' },
+   ```
+
+3. **Create the API client** at `packages/lib/storage/providers/myservice.ts` (for storage providers)
+   or `packages/lib/myservice/index.ts` for other services, following the same auth pattern as
+   `packages/lib/storage/providers/vultr.ts`:
+   - Read credentials via `getIntegrations()` with env var fallback
+   - Validate and build URLs safely before fetching
+
+4. **Wire up the admin UI** — the settings manager (`packages/components/admin/settings/settings-manager.tsx`)
+   has sections per integration. Add an API key input field and a test button following the
+   existing Vultr pattern.
+
+5. **Document the env var fallback** in `.env.template` as a comment.

.claude/commands/db-migrate.md

@@ -0,0 +1,15 @@
+# db-migrate
+
+Run a Prisma migration for the current schema changes.
+
+## Steps
+
+1. Ask the user for a short migration name that describes what changed (e.g. `add-object-storage-pool`, `add-user-avatar-field`).
+2. Run the migration:
+   ```bash
+   yarn db:migrate --name <migration-name>
+   ```
+3. Run `yarn db:generate` to update the Prisma client.
+4. Report the new migration file created under `prisma/migrations/`.
+
+If `yarn db:migrate` fails due to a destructive change (dropping a column, renaming), explain the impact and ask whether to proceed with `--create-only` so the SQL can be reviewed first.

.claude/commands/lint.md

@@ -0,0 +1,20 @@
+# lint
+
+Run ESLint across the project and auto-fix what can be fixed.
+
+```bash
+yarn lint:fix
+```
+
+Then verify no remaining errors:
+
+```bash
+yarn lint
+```
+
+Key rules to be aware of:
+
+- `@typescript-eslint/no-explicit-any` is a **warning** (not error) — minimise `any` but don't panic.
+- `react/no-unescaped-entities` is **off** — apostrophes in JSX are fine.
+- `@next/next/no-img-element` is **off** — `<img>` is allowed.
+- Unused variables are warned if not prefixed with `_`.

.claude/commands/typecheck.md

@@ -0,0 +1,13 @@
+# typecheck
+
+Run TypeScript type checking across the entire project without emitting files.
+
+```bash
+yarn typecheck
+```
+
+If there are errors, fix them before considering any task complete. Pay attention to:
+
+- Prisma model field names (regenerate the client with `yarn db:generate` if model types are stale)
+- Import path aliases (`@/packages/lib/...` not relative paths)
+- `unknown` vs `any` — prefer narrowing over casting

.claude/settings.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(yarn:*)",
+      "Bash(npx prisma:*)",
+      "Bash(npx tsx:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git status:*)",
+      "Bash(git show:*)"
+    ]
+  }
+}

.github/workflows/socket.yml

@@ -0,0 +1,33 @@
+name: Socket Security
+
+on:
+  push:
+    branches: [ master, dev ]
+  pull_request:
+    branches: [ master, dev ]
+
+jobs:
+  socket-scan:
+    name: Supply Chain Security
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Required to post PR comments and check run results
+      pull-requests: write
+      checks: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Socket Security Scan
+        uses: SocketDev/socket-action@v1
+        with:
+          api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+          # Fail the workflow if any issue reaches the "error" action level in socket.yml
+          # (malware, install scripts, obfuscated files, typosquatting, new authors, env exfil)
+          fail_on_error: true