@brimble/sandbox 0.1.0 → 0.1.2

package/README.md

@@ -24,9 +24,9 @@ BRIMBLE_SANDBOX_KEY=your_key_here npm run test:all
 ## Quickstart
 
 ```ts
-import { CodeLanguage, SandboxClient } from '@brimble/sandbox';
+import { CodeLanguage, Sandbox } from '@brimble/sandbox';
 
-const client = new SandboxClient();
+const client = new Sandbox();
 
 const sandbox = await client.sandboxes.createReady({
   template: 'node-22',
@@ -37,6 +37,10 @@ const sandbox = await client.sandboxes.createReady({
 await sandbox.exec({ cmd: 'node -v' });
 
 await sandbox.putFile('tmp/notes.txt', Buffer.from('hello sandbox'));
+await sandbox.putFiles([
+  { path: '/tmp/hello.txt', body: 'hello from batch' },
+  { path: '/tmp/config.json', body: JSON.stringify({ mode: 'dev' }) },
+]);
 const stream = await sandbox.getFile('tmp/notes.txt');
 
 await sandbox.runCode({
@@ -98,7 +102,7 @@ Use `client.sandboxes.create({ ..., volumeId })` or `client.sandboxes.withVolume
 ## Retry, timeouts, and idempotency
 
 ```ts
-const client = new SandboxClient({
+const client = new Sandbox({
   timeoutMs: 30_000,
   retry: {
     maxAttempts: 3,
@@ -120,9 +124,9 @@ If `region` is omitted, the SDK resolves the first available sandbox region auto
 - `client.sandboxes`
   - `create`, `createReady`, `withVolume`, `list`, `iterate`, `get`, `getReady`, `listRegions`, `listTemplates`, `getTemplate`, `destroy`, `pause`, `resume`, `quickstartNode`, `quickstartPython`, `use`
 - `sandbox` handle (returned from `create/get/list`)
-  - `waitUntilReady`, `refresh`, `destroy`, `pause`, `resume`, `exec`, `runCode`, `putFile`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`, `snapshots.create`, `snapshots.list`
+  - `waitUntilReady`, `refresh`, `destroy`, `pause`, `resume`, `exec`, `runCode`, `putFile`, `putFiles`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`, `snapshots.create`, `snapshots.list`
 - `client.sandboxes.use(id)`
-  - `exec`, `runCode`, `putFile`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`
+  - `exec`, `runCode`, `putFile`, `putFiles`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`
 - `client.snapshots`
   - `listAll`, `iterateAll`, `delete`
 - `client.volumes`

package/dist/package.json

@@ -1,9 +1,16 @@
 {
     "name": "@brimble/sandbox",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "TypeScript SDK for the Brimble Sandbox API",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "main": "dist/src/index.js",
+    "types": "dist/src/index.d.ts",
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
     "scripts": {
         "build": "rm -rf dist && tsc -p .",
         "test": "vitest run --config vitest.config.ts",

package/dist/src/client.d.ts

@@ -1,13 +1,13 @@
 import { SandboxesResource, SnapshotsResource, VolumesResource } from './resources';
 import type { RetryOptions } from './transport/http';
-export type SandboxClientOptions = {
+export type SandboxOptions = {
     apiKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
     retry?: RetryOptions;
     fetchImpl?: typeof fetch;
 };
-export declare class SandboxClient {
+export declare class Sandbox {
     /** Access sandbox lifecycle and per-sandbox scoped operations. */
     readonly sandboxes: SandboxesResource;
     /** Access account-level snapshot operations. */
@@ -19,5 +19,5 @@ export declare class SandboxClient {
      * Creates a client instance for the Brimble Sandbox API.
      * Pass `apiKey` directly or set `BRIMBLE_SANDBOX_KEY` in your environment.
      */
-    constructor(options?: SandboxClientOptions);
+    constructor(options?: SandboxOptions);
 }

package/dist/src/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxClient = void 0;
+exports.Sandbox = void 0;
 const constants_1 = require("./constants");
 const resources_1 = require("./resources");
 const http_1 = require("./transport/http");
@@ -18,7 +18,7 @@ function resolveApiKey(options) {
     }
     throw new Error(`Sandbox API key is required. Pass "apiKey" explicitly or set ${constants_1.SANDBOX_API_KEY_ENV_NAME} in your environment.`);
 }
-class SandboxClient {
+class Sandbox {
     /** Access sandbox lifecycle and per-sandbox scoped operations. */
     sandboxes;
     /** Access account-level snapshot operations. */
@@ -43,4 +43,4 @@ class SandboxClient {
         this.volumes = new resources_1.VolumesResource(this.transport);
     }
 }
-exports.SandboxClient = SandboxClient;
+exports.Sandbox = Sandbox;

package/dist/src/index.d.ts

@@ -1,10 +1,10 @@
 export { DEFAULT_BASE_URL, DEFAULT_PAGE, DEFAULT_PAGE_LIMIT, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_ATTEMPTS, DEFAULT_RETRY_MAX_DELAY_MS, DEFAULT_RETRY_STATUSES, DEFAULT_TIMEOUT_MS, MAX_PAGE_LIMIT, SANDBOX_API_KEY_ENV_NAME, } from './constants';
-export { SandboxClient } from './client';
-export type { SandboxClientOptions } from './client';
+export { Sandbox } from './client';
+export type { SandboxOptions } from './client';
 export { AuthError, NotFoundError, RateLimitError, SandboxApiError, ValidationError } from './errors';
 export type { SandboxApiErrorArgs } from './errors';
 export { CodeLanguage, DestroyReason, DestroyTimeout, SandboxStatus, SnapshotMode, SnapshotStatus, VolumeType, } from './enums';
 export { ExecResource, FilesResource, SandboxHandle, SandboxesResource, ScopedSandboxResource, SnapshotScopeResource, SnapshotsResource, StatsResource, VolumesResource, } from './resources';
-export type { AckMessage, CodeInput, CreateSandboxInput, CreateSandboxResult, CreateSnapshotInput, CreateVolumeInput, ExecInput, ExecResult, ExecStreamFrame, FileUploadBody, Paginated, Pagination, RegionSummary, SandboxRegion, SandboxRegionsResult, Sandbox, SandboxSpecs, Snapshot, Stats, StatsAverageNetwork, StatsAverageNumeric, StatsQuery, StatsTimelinePoint, TeamScopedPagination, WaitUntilReadyOptions, Volume, } from './types';
+export type { AckMessage, CodeInput, CreateSandboxInput, CreateSandboxResult, CreateSnapshotInput, CreateVolumeInput, ExecInput, ExecResult, ExecStreamFrame, FileUploadBody, Paginated, Pagination, RegionSummary, SandboxRegion, SandboxRegionsResult, Sandbox as SandboxData, SandboxSpecs, Snapshot, Stats, StatsAverageNetwork, StatsAverageNumeric, StatsQuery, StatsTimelinePoint, TeamScopedPagination, WaitUntilReadyOptions, Volume, } from './types';
 export type { RequestOptions } from './transport/http';
 export type { RetryOptions } from './transport/http';

package/dist/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VolumesResource = exports.StatsResource = exports.SnapshotsResource = exports.SnapshotScopeResource = exports.ScopedSandboxResource = exports.SandboxesResource = exports.SandboxHandle = exports.FilesResource = exports.ExecResource = exports.VolumeType = exports.SnapshotStatus = exports.SnapshotMode = exports.SandboxStatus = exports.DestroyTimeout = exports.DestroyReason = exports.CodeLanguage = exports.ValidationError = exports.SandboxApiError = exports.RateLimitError = exports.NotFoundError = exports.AuthError = exports.SandboxClient = exports.SANDBOX_API_KEY_ENV_NAME = exports.MAX_PAGE_LIMIT = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_RETRY_STATUSES = exports.DEFAULT_RETRY_MAX_DELAY_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.DEFAULT_PAGE_LIMIT = exports.DEFAULT_PAGE = exports.DEFAULT_BASE_URL = void 0;
+exports.VolumesResource = exports.StatsResource = exports.SnapshotsResource = exports.SnapshotScopeResource = exports.ScopedSandboxResource = exports.SandboxesResource = exports.SandboxHandle = exports.FilesResource = exports.ExecResource = exports.VolumeType = exports.SnapshotStatus = exports.SnapshotMode = exports.SandboxStatus = exports.DestroyTimeout = exports.DestroyReason = exports.CodeLanguage = exports.ValidationError = exports.SandboxApiError = exports.RateLimitError = exports.NotFoundError = exports.AuthError = exports.Sandbox = exports.SANDBOX_API_KEY_ENV_NAME = exports.MAX_PAGE_LIMIT = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_RETRY_STATUSES = exports.DEFAULT_RETRY_MAX_DELAY_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.DEFAULT_PAGE_LIMIT = exports.DEFAULT_PAGE = exports.DEFAULT_BASE_URL = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return constants_1.DEFAULT_BASE_URL; } });
 Object.defineProperty(exports, "DEFAULT_PAGE", { enumerable: true, get: function () { return constants_1.DEFAULT_PAGE; } });
@@ -13,7 +13,7 @@ Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: fu
 Object.defineProperty(exports, "MAX_PAGE_LIMIT", { enumerable: true, get: function () { return constants_1.MAX_PAGE_LIMIT; } });
 Object.defineProperty(exports, "SANDBOX_API_KEY_ENV_NAME", { enumerable: true, get: function () { return constants_1.SANDBOX_API_KEY_ENV_NAME; } });
 var client_1 = require("./client");
-Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_1.SandboxClient; } });
+Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return client_1.Sandbox; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_1.AuthError; } });
 Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });

package/dist/src/resources/files.d.ts

@@ -1,4 +1,4 @@
-import type { FileUploadBody } from '../types';
+import type { BatchFileUploadInput, BatchFileUploadResponse, FileUploadBody } from '../types';
 import type { RequestOptions } from '../transport/http';
 import { HttpTransport } from '../transport/http';
 export declare class FilesResource {
@@ -13,4 +13,9 @@ export declare class FilesResource {
     put(path: string, body: FileUploadBody, options?: RequestOptions): Promise<void>;
     /** Download a file from the sandbox as a stream. */
     get(path: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Upload multiple files in one request using base64 payloads.
+     * Best for small/medium known files (max 100 per call).
+     */
+    putFiles(files: BatchFileUploadInput[], options?: RequestOptions): Promise<BatchFileUploadResponse>;
 }

package/dist/src/resources/files.js

@@ -37,5 +37,41 @@ class FilesResource {
             ...options,
         });
     }
+    /**
+     * Upload multiple files in one request using base64 payloads.
+     * Best for small/medium known files (max 100 per call).
+     */
+    async putFiles(files, options) {
+        if (files.length === 0) {
+            throw new Error('putFiles requires at least one file.');
+        }
+        if (files.length > 100) {
+            throw new Error('putFiles supports at most 100 files per request.');
+        }
+        const response = await this.transport.requestJson({
+            endpoint: `/sandboxes/${this.sandboxId}/files/batch`,
+            method: 'POST',
+            body: {
+                files: files.map((file) => ({
+                    path: normalizeBatchPath(file.path),
+                    content_base64: encodeBatchBody(file.body),
+                })),
+            },
+            ...options,
+        });
+        if (!response) {
+            throw new Error('Batch upload returned an empty response.');
+        }
+        return response;
+    }
 }
 exports.FilesResource = FilesResource;
+function normalizeBatchPath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
+function encodeBatchBody(body) {
+    if (typeof body === 'string') {
+        return Buffer.from(body, 'utf-8').toString('base64');
+    }
+    return Buffer.from(body).toString('base64');
+}

package/dist/src/resources/sandbox-handle.d.ts

@@ -1,6 +1,6 @@
 import { SandboxStatus } from '../enums';
 import type { RequestOptions } from '../transport/http';
-import type { AckMessage, CodeInput, CreateSandboxResult, CreateSnapshotInput, ExecInput, ExecResult, FileUploadBody, Paginated, Pagination, Sandbox, SandboxRuntimeOptions, Snapshot, Stats, StatsQuery, WaitUntilReadyOptions } from '../types';
+import type { AckMessage, BatchFileUploadInput, BatchFileUploadResponse, CodeInput, CreateSandboxResult, CreateSnapshotInput, ExecInput, ExecResult, FileUploadBody, Paginated, Pagination, Sandbox, SandboxRuntimeOptions, Snapshot, Stats, StatsQuery, WaitUntilReadyOptions } from '../types';
 import type { SandboxesResource } from './sandboxes';
 export declare class SandboxHandle {
     private readonly sandboxes;
@@ -58,6 +58,11 @@ export declare class SandboxHandle {
      * By default this throws when not ready; set `waitUntilReady` to auto-wait.
      */
     getFile(path: string, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Upload multiple files in one call.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    putFiles(files: BatchFileUploadInput[], options?: SandboxRuntimeOptions): Promise<BatchFileUploadResponse>;
     /**
      * Fetch usage stats for this sandbox.
      * By default this throws when not ready; set `waitUntilReady` to auto-wait.

package/dist/src/resources/sandbox-handle.js

@@ -104,6 +104,14 @@ class SandboxHandle {
         await this.ensureReady(options.waitUntilReady);
         return this.scope.getFile(path, options);
     }
+    /**
+     * Upload multiple files in one call.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    async putFiles(files, options = {}) {
+        await this.ensureReady(options.waitUntilReady);
+        return this.scope.putFiles(files, options);
+    }
     /**
      * Fetch usage stats for this sandbox.
      * By default this throws when not ready; set `waitUntilReady` to auto-wait.

package/dist/src/resources/scoped-sandbox.d.ts

@@ -3,7 +3,7 @@ import { FilesResource } from './files';
 import { SnapshotScopeResource } from './snapshots';
 import { StatsResource } from './stats';
 import { HttpTransport } from '../transport/http';
-import type { CodeInput, CreateSnapshotInput, ExecInput, ExecResult, FileUploadBody, Paginated, Pagination, Snapshot, Stats, StatsQuery } from '../types';
+import type { BatchFileUploadInput, BatchFileUploadResponse, CodeInput, CreateSnapshotInput, ExecInput, ExecResult, FileUploadBody, Paginated, Pagination, Snapshot, Stats, StatsQuery } from '../types';
 import type { RequestOptions } from '../transport/http';
 export declare class ScopedSandboxResource {
     /** Lower-level exec/code runner resource. */
@@ -30,6 +30,8 @@ export declare class ScopedSandboxResource {
     putFile(path: string, body: FileUploadBody, options?: RequestOptions): Promise<void>;
     /** Download file bytes from this sandbox as a stream. */
     getFile(path: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+    /** Upload multiple files to this sandbox in one request. */
+    putFiles(files: BatchFileUploadInput[], options?: RequestOptions): Promise<BatchFileUploadResponse>;
     /** Fetch CPU, memory, and network stats for this sandbox. */
     stats(query?: StatsQuery, options?: RequestOptions): Promise<Stats>;
     /** Create a snapshot for this sandbox. */

package/dist/src/resources/scoped-sandbox.js

@@ -35,6 +35,10 @@ class ScopedSandboxResource {
     getFile(path, options) {
         return this.files.get(path, options);
     }
+    /** Upload multiple files to this sandbox in one request. */
+    putFiles(files, options) {
+        return this.files.putFiles(files, options);
+    }
     /** Fetch CPU, memory, and network stats for this sandbox. */
     stats(query = {}, options) {
         return this.statsResource.stats(query, options);

package/dist/src/types/files.d.ts

@@ -1 +1,17 @@
 export type FileUploadBody = ReadableStream<Uint8Array> | Buffer | Uint8Array;
+export type BatchFileUploadBody = Buffer | Uint8Array | string;
+export type BatchFileUploadInput = {
+    path: string;
+    body: BatchFileUploadBody;
+};
+export type BatchFileUploadResult = {
+    path: string;
+    bytes: number;
+    success: boolean;
+    error?: string;
+};
+export type BatchFileUploadResponse = {
+    uploaded: number;
+    failed: number;
+    results: BatchFileUploadResult[];
+};

package/dist/src/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { CodeInput, ExecInput, ExecResult, ExecStreamFrame } from './exec';
-export type { FileUploadBody } from './files';
+export type { BatchFileUploadBody, BatchFileUploadInput, BatchFileUploadResponse, BatchFileUploadResult, FileUploadBody } from './files';
 export type { Paginated, Pagination, TeamScopedPagination } from './pagination';
 export type { RegionSummary, SandboxRegion, SandboxRegionsResult } from './region';
 export type { AckMessage, CreateSandboxInput, CreateSandboxRequest, CreateSandboxResult, CreateSandboxWithVolumeInput, CreateSandboxWithVolumeResult, Sandbox, SandboxReadyRequestOptions, SandboxRegionInput, SandboxRuntimeOptions, SandboxSpecs, WaitPreference, WaitUntilReadyOptions, } from './sandbox';

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@brimble/sandbox",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript SDK for the Brimble Sandbox API",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "rm -rf dist && tsc -p .",
     "test": "vitest run --config vitest.config.ts",

package/CODEX.md

@@ -1,188 +0,0 @@
-# Coding Guidelines
-
-These are the rules you follow when writing or modifying code in this codebase. Read them once, apply them always.
-
-## 1. Separation of concerns
-
-Keep functions, types, enums, and classes in their own files (or at minimum, their own clearly-scoped sections). Do not mix concerns.
-
-- One responsibility per unit. A function does one thing; a class models one concept; a type describes one shape.
-- Types and enums live in dedicated files (`types.ts`, `enums.ts`, or a `types/` / `enums/` folder) unless they are trivially local to a single consumer.
-- Do not co-locate unrelated helpers inside a class or module just because they happen to touch the same data.
-- If a file starts doing two jobs, split it.
-
-## 2. Ternaries: short and flat, or not at all
-
-Use a ternary only when it is short, single-line, and obvious at a glance.
-
-```ts
-// Good
-const label = isActive ? 'on' : 'off';
-
-// Bad — nested
-const label = isActive ? (isAdmin ? 'admin-on' : 'user-on') : isAdmin ? 'admin-off' : 'user-off';
-```
-
-No nested ternaries. Ever. If branching gets past one level, use `if`/`else` or extract a function. Readability wins over cleverness.
-
-## 3. Stop using `typeof` everywhere
-
-`typeof` is a narrowing tool, not a default check. Do not reach for it when a simple truthy/falsy check is enough.
-
-```ts
-// Good
-if (!user) return;
-if (value) process(value);
-
-// Bad
-if (typeof user !== "undefined" && user !== null) { ... }
-if (typeof value === "string" && value.length > 0) { ... }  // when you just need truthiness
-```
-
-Use `typeof` only when you genuinely need to discriminate primitive types (e.g. inside a union where `string | number` matters). Otherwise, trust truthiness, optional chaining, and nullish coalescing.
-
-## 4. No over-engineered guard rails
-
-Write defenses for realistic failure modes, not hypothetical ones.
-
-- Validate at system boundaries (HTTP input, DB reads, external APIs). Do not re-validate the same data at every internal function call.
-- No `assert` chains at the top of ever4y function.
-- No wrapping every call in try/catch "just in case" — let errors bubble to a single handler that knows what to do with them.
-- If a guard clause is protecting against a case that cannot happen given the types, delete it.
-- Prefer types and schemas over runtime paranoia.
-
-The goal is correctness, not defensiveness theatre.
-
-## 5. Follow popular conventions
-
-Use the community standard for the language and ecosystem. Do not invent personal styles.
-
-- **TypeScript/JavaScript**: ESLint + Prettier defaults, camelCase for variables/functions, PascalCase for types/classes, `kebab-case` or `camelCase` file names consistent with the project.
-- **Go**: `gofmt`, idiomatic error handling (`if err != nil`), package names short and lowercase, no stutter.
-- **Python**: PEP 8, `ruff`/`black` formatting, `snake_case`.
-- Match the project's existing style before imposing anything new. When in doubt, grep the codebase and do what it already does.
-
-## 6. Comments: only when they add something
-
-Code should read itself. Comments are for things the code cannot say.
-
-Write a comment when:
-
-- The _why_ is non-obvious (business rule, workaround for an upstream bug, performance-sensitive choice).
-- A public API needs a docstring for consumers.
-- A `TODO` / `FIXME` with context and ownership.
-
-Do not write a comment when:
-
-- It restates the code (`// increment counter` above `counter++`).
-- It narrates obvious control flow (`// loop through users`).
-- It was auto-generated boilerplate that nobody reads.
-
-Delete stale comments on sight. A wrong comment is worse than no comment.
-
-## 7. Don't re-invent what already exists
-
-Before writing a helper, check:
-
-1. The language's stdlib.
-2. The framework the project uses.
-3. Utilities already in this codebase.
-
-Do not write a custom `debounce`, `deepClone`, `groupBy`, UUID generator, date parser, retry loop, or config loader when a well-tested one is already available. Do not introduce a second HTTP client, a second logger, or a second error class when the repo already has one — use what's there.
-
-The only reasons to roll your own: the existing option is genuinely insufficient, or pulling it in costs more than writing it.
-
-## 8. No `any`, no `as unknown as T`
-
-When types get annoying, fix the type — don't escape it.
-
-- `any` is banned except at genuine interop edges (and even then, narrow immediately).
-- `as` casts are a last resort. If you're writing `as unknown as T`, the real answer is usually a type guard, a discriminated union, or a schema parse (Zod, etc.).
-- `// @ts-ignore` and `// @ts-expect-error` require a comment explaining why.
-
-The type system earns its keep when you respect it.
-
-## 9. Delete dead code
-
-- No commented-out blocks "for reference." Git remembers.
-- No unused imports, unused variables, unused parameters (prefix with `_` if the signature forces it).
-- No stale feature flags still wired up months after launch.
-- No "v2" helper sitting next to the original with no caller.
-
-If it isn't used, it leaves.
-
-## 10. Consistent error handling
-
-Pick one error strategy per layer and stick to it.
-
-- Don't mix `throw`, `Result<T, E>`, `null` returns, and `{ error, data }` tuples in the same module.
-- Don't catch errors only to re-throw them unchanged — that's noise.
-- Don't swallow errors with empty `catch {}`. If you genuinely want to ignore one, log it or leave a comment saying why.
-- Handle errors at the layer that knows what to do with them (usually the HTTP handler or job runner), not at every function on the way down.
-
-## 11. No magic numbers or magic strings
-
-Named constants and enums beat literals scattered through the code.
-
-```ts
-// Bad
-setTimeout(retry, 86400000);
-if (user.status === "active") { ... }
-
-// Good
-const ONE_DAY_MS = 24 * 60 * 60 * 1000;
-setTimeout(retry, ONE_DAY_MS);
-if (user.status === UserStatus.Active) { ... }
-```
-
-If a value appears more than once, or its meaning isn't obvious from the number/string alone, name it.
-
-## 12. Async correctness
-
-- Always `await` or explicitly handle the promise. No dangling promises.
-- Parallelize independent work with `Promise.all`; don't serialize it in a `for` loop by accident.
-- Don't mix `.then()` chains and `await` in the same function — pick one.
-- Handle rejections. An unhandled rejection in production is a bug waiting to page you.
-
-## 13. Don't mutate function arguments
-
-Treat inputs as read-only. If you need a modified version, return a new one.
-
-```ts
-// Bad
-function addTag(user, tag) {
-  user.tags.push(tag);
-  return user;
-}
-
-// Good
-function addTag(user, tag) {
-  return { ...user, tags: [...user.tags, tag] };
-}
-```
-
-Hidden mutation through a function call is one of the worst bugs to trace in a large system.
-
-## 14. Respect the codebase's existing patterns
-
-Before introducing something new, look around:
-
-- If the project uses a specific HTTP client, logger, error class, config loader, or validation library — use it.
-- If there's an established folder structure, follow it.
-- If there's a naming convention in neighboring files, match it.
-
-Don't bring in a new dependency or pattern just because it's what you reached for first. Consistency across the codebase is worth more than any individual preference.
-
-## 15. No hardcoded environment values
-
-URLs, ports, credentials, feature flags, and tunable limits belong in config or environment variables — not in source.
-
-- Secrets never land in the repo. Not even temporarily.
-- Defaults for local dev are fine in a `.env.example` or config file, but the real values are injected.
-- If a value differs between staging and prod, it's config.
-
----
-
-## Summary
-
-Clean separation, flat logic, minimal runtime paranoia, community idioms, and comments only where they earn their place. Reuse what exists, respect the type system, delete what's dead, handle errors consistently, and keep configuration out of source. If a change adds complexity without earning it, reject the change.