@wild-framework/storage-s3 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @wild-framework/storage-s3
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+S3 (AWS) storage driver for [Wild Framework](https://github.com/KhandaSoftware/wild-framework)'s storage package. Works with AWS S3 and any S3-compatible store (MinIO, Cloudflare R2, DigitalOcean Spaces, …).
+
+## Install
+
+```bash
+pnpm add @wild-framework/storage-s3
+```
+
+## Usage
+
+```ts
+import { S3StorageProvider } from "@wild-framework/storage-s3";
+
+S3StorageProvider.bucket = process.env.AWS_BUCKET;
+S3StorageProvider.region = process.env.AWS_REGION;
+S3StorageProvider.accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+S3StorageProvider.secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+
+app.register(S3StorageProvider);
+// … storage is now S3-backed, resolved via app.resolve(Storage)
+```
+
+- Omit `accessKeyId`/`secretAccessKey` to use the default AWS credential chain (env vars, IAM role, EC2 metadata).
+- Set `publicUrl` to serve public objects directly; otherwise `storage.url(key, { expiresIn })` returns a **presigned** URL.
+- Point `endpoint` + `forcePathStyle` at MinIO/R2 for self-hosted or S3-compatible storage.
+
+## Integration test
+
+```bash
+AWS_BUCKET=test AWS_REGION=us-east-1 \
+AWS_ENDPOINT=http://localhost:9000 \
+AWS_ACCESS_KEY_ID=wild AWS_SECRET_ACCESS_KEY=wildsecret \
+  pnpm --filter @wild-framework/storage-s3 test
+```
+
+Skips automatically when the env vars are not set.
+
+## License
+
+MIT

package/dist/driver.d.ts

@@ -0,0 +1,50 @@
+import type { StorageDriver, PutOptions, UrlOptions } from "@wild-framework/storage";
+import { S3Client } from "@aws-sdk/client-s3";
+/**
+ * Configuration for the S3 storage driver.
+ */
+export interface S3StorageConfig {
+    /** S3 bucket name. */
+    bucket: string;
+    /** AWS region, e.g. `us-east-1`. */
+    region: string;
+    /** Static credentials. Omit to use the default AWS credential chain (env, IAM role, etc.). */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    /** Custom endpoint — for S3-compatible stores like MinIO. */
+    endpoint?: string;
+    /** Use path-style addressing (required for MinIO and many custom endpoints). */
+    forcePathStyle?: boolean;
+    /** Base URL for public objects. When set, `url()` returns `${publicUrl}/${key}`. */
+    publicUrl?: string;
+    /** Default expiry (seconds) for signed URLs when `url()` is called with no `expiresIn`. */
+    signedUrlExpiresIn?: number;
+    /** A pre-built client — for advanced use or tests. */
+    client?: S3Client;
+}
+/**
+ * S3-backed storage driver implementing `StorageDriver`.
+ *
+ * Backed by `@aws-sdk/client-s3` (v3). Works with AWS S3 and any
+ * S3-compatible store (MinIO, R2, DigitalOcean Spaces, …). Call `connect()`
+ * to materialise the client (so bad config fails early) — `S3StorageProvider`
+ * does this on boot.
+ */
+export declare class S3StorageDriver implements StorageDriver {
+    private config;
+    private client;
+    constructor(config: S3StorageConfig);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    put(path: string, contents: Buffer | string, options?: PutOptions): Promise<string>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    url(path: string, options?: UrlOptions): Promise<string>;
+    private defaultPublicUrl;
+    private normalizeKey;
+    private requireClient;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,EACH,QAAQ,EAKX,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,WAAW,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,MAAM,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,aAAa;IAGrC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,MAAM,CAAyB;gBAEnB,MAAM,EAAE,eAAe;IASrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAanF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWlC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAetC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB9D,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,aAAa;CAaxB"}

package/dist/driver.js

@@ -0,0 +1,109 @@
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadObjectCommand, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+/**
+ * S3-backed storage driver implementing `StorageDriver`.
+ *
+ * Backed by `@aws-sdk/client-s3` (v3). Works with AWS S3 and any
+ * S3-compatible store (MinIO, R2, DigitalOcean Spaces, …). Call `connect()`
+ * to materialise the client (so bad config fails early) — `S3StorageProvider`
+ * does this on boot.
+ */
+export class S3StorageDriver {
+    config;
+    client = null;
+    constructor(config) {
+        this.config = config;
+        if (!config.bucket) {
+            throw new Error("S3StorageDriver requires a bucket.");
+        }
+        if (!config.client && !config.region) {
+            throw new Error("S3StorageDriver requires a region (or an injected client).");
+        }
+    }
+    async connect() {
+        this.requireClient(); // materialise so config errors surface at boot
+    }
+    async close() {
+        // Only destroy clients we created — an injected client is the caller's.
+        if (this.client && !this.config.client) {
+            this.client.destroy();
+        }
+        this.client = null;
+    }
+    async put(path, contents, options) {
+        await this.requireClient().send(new PutObjectCommand({
+            Bucket: this.config.bucket,
+            Key: this.normalizeKey(path),
+            Body: contents,
+            ContentType: options?.contentType,
+            Metadata: options?.metadata,
+        }));
+        return path;
+    }
+    async get(path) {
+        const response = await this.requireClient().send(new GetObjectCommand({ Bucket: this.config.bucket, Key: this.normalizeKey(path) }));
+        if (!response.Body) {
+            throw new Error(`Object "${path}" has no body.`);
+        }
+        const bytes = await response.Body.transformToByteArray();
+        return Buffer.from(bytes);
+    }
+    async delete(path) {
+        await this.requireClient().send(new DeleteObjectCommand({ Bucket: this.config.bucket, Key: this.normalizeKey(path) }));
+    }
+    async exists(path) {
+        try {
+            await this.requireClient().send(new HeadObjectCommand({ Bucket: this.config.bucket, Key: this.normalizeKey(path) }));
+            return true;
+        }
+        catch (error) {
+            const status = error
+                ?.$metadata?.httpStatusCode;
+            // 404 = missing; 403 = missing in a private bucket.
+            if (status === 404 || status === 403)
+                return false;
+            throw error;
+        }
+    }
+    async url(path, options) {
+        const key = this.normalizeKey(path);
+        if (this.config.publicUrl) {
+            return joinUrl(this.config.publicUrl, key);
+        }
+        if (options?.expiresIn !== undefined || this.config.signedUrlExpiresIn !== undefined) {
+            const expiresIn = options?.expiresIn ?? this.config.signedUrlExpiresIn ?? 3600;
+            return getSignedUrl(this.requireClient(), new GetObjectCommand({ Bucket: this.config.bucket, Key: key }), { expiresIn });
+        }
+        return this.defaultPublicUrl(key);
+    }
+    defaultPublicUrl(key) {
+        if (this.config.endpoint) {
+            return joinUrl(this.config.endpoint, `${this.config.bucket}/${key}`);
+        }
+        const host = this.config.region === "us-east-1"
+            ? `${this.config.bucket}.s3.amazonaws.com`
+            : `${this.config.bucket}.s3.${this.config.region}.amazonaws.com`;
+        return `https://${host}/${key}`;
+    }
+    normalizeKey(path) {
+        return path.replace(/^\/+/, "");
+    }
+    requireClient() {
+        if (!this.client) {
+            this.client =
+                this.config.client ??
+                    new S3Client({
+                        region: this.config.region,
+                        credentials: this.config.credentials,
+                        endpoint: this.config.endpoint,
+                        forcePathStyle: this.config.forcePathStyle,
+                    });
+        }
+        return this.client;
+    }
+}
+/** Join a base URL and a key without producing double slashes. */
+function joinUrl(base, key) {
+    return `${base.replace(/\/+$/, "")}/${key.replace(/^\/+/, "")}`;
+}
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { S3StorageDriver } from "./driver.js";
+export type { S3StorageConfig } from "./driver.js";
+export { S3StorageProvider } from "./provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { S3StorageDriver } from "./driver.js";
+export { S3StorageProvider } from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,39 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers an S3-backed storage with the application.
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * S3StorageProvider.bucket = "my-bucket";
+ * S3StorageProvider.region = "us-east-1";
+ * S3StorageProvider.accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+ * S3StorageProvider.secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+ * ```
+ *
+ * Materialises the client on boot (fail-fast on bad config) and destroys it
+ * on shutdown.
+ */
+export declare class S3StorageProvider implements Provider {
+    /** S3 bucket name. */
+    static bucket: string | undefined;
+    /** AWS region. */
+    static region: string | undefined;
+    /** Access key id. Omit to use the default AWS credential chain. */
+    static accessKeyId: string | undefined;
+    /** Secret access key. */
+    static secretAccessKey: string | undefined;
+    /** Custom endpoint (MinIO, R2, …). */
+    static endpoint: string | undefined;
+    /** Path-style addressing for custom endpoints. */
+    static forcePathStyle: boolean;
+    /** Base URL for public objects. */
+    static publicUrl: string | undefined;
+    /** Default expiry (seconds) for signed URLs. */
+    static signedUrlExpiresIn: number | undefined;
+    private driver;
+    register(app: Application): void;
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKlE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAC9C,sBAAsB;IACtB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,kBAAkB;IAClB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,mEAAmE;IACnE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,yBAAyB;IACzB,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,sCAAsC;IACtC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,kDAAkD;IAClD,MAAM,CAAC,cAAc,UAAS;IAC9B,mCAAmC;IACnC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,gDAAgD;IAChD,MAAM,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,OAAO,CAAC,MAAM,CAA8B;IAE5C,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAsB1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/provider.js

@@ -0,0 +1,63 @@
+import { Container } from "@wild-framework/container";
+import { Storage } from "@wild-framework/storage";
+import { S3StorageDriver } from "./driver.js";
+/**
+ * Registers an S3-backed storage with the application.
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * S3StorageProvider.bucket = "my-bucket";
+ * S3StorageProvider.region = "us-east-1";
+ * S3StorageProvider.accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+ * S3StorageProvider.secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+ * ```
+ *
+ * Materialises the client on boot (fail-fast on bad config) and destroys it
+ * on shutdown.
+ */
+export class S3StorageProvider {
+    /** S3 bucket name. */
+    static bucket;
+    /** AWS region. */
+    static region;
+    /** Access key id. Omit to use the default AWS credential chain. */
+    static accessKeyId;
+    /** Secret access key. */
+    static secretAccessKey;
+    /** Custom endpoint (MinIO, R2, …). */
+    static endpoint;
+    /** Path-style addressing for custom endpoints. */
+    static forcePathStyle = false;
+    /** Base URL for public objects. */
+    static publicUrl;
+    /** Default expiry (seconds) for signed URLs. */
+    static signedUrlExpiresIn;
+    driver;
+    register(app) {
+        const container = app.resolve(Container);
+        const driver = new S3StorageDriver({
+            bucket: S3StorageProvider.bucket ?? "",
+            region: S3StorageProvider.region ?? "",
+            credentials: S3StorageProvider.accessKeyId
+                ? {
+                    accessKeyId: S3StorageProvider.accessKeyId,
+                    secretAccessKey: S3StorageProvider.secretAccessKey ?? "",
+                }
+                : undefined,
+            endpoint: S3StorageProvider.endpoint,
+            forcePathStyle: S3StorageProvider.forcePathStyle,
+            publicUrl: S3StorageProvider.publicUrl,
+            signedUrlExpiresIn: S3StorageProvider.signedUrlExpiresIn,
+        });
+        this.driver = driver;
+        container.singleton(Storage, () => new Storage(driver));
+    }
+    async boot() {
+        await this.driver?.connect();
+    }
+    async shutdown() {
+        await this.driver?.close();
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,iBAAiB;IAC1B,sBAAsB;IACtB,MAAM,CAAC,MAAM,CAAqB;IAClC,kBAAkB;IAClB,MAAM,CAAC,MAAM,CAAqB;IAClC,mEAAmE;IACnE,MAAM,CAAC,WAAW,CAAqB;IACvC,yBAAyB;IACzB,MAAM,CAAC,eAAe,CAAqB;IAC3C,sCAAsC;IACtC,MAAM,CAAC,QAAQ,CAAqB;IACpC,kDAAkD;IAClD,MAAM,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,mCAAmC;IACnC,MAAM,CAAC,SAAS,CAAqB;IACrC,gDAAgD;IAChD,MAAM,CAAC,kBAAkB,CAAqB;IAEtC,MAAM,CAA8B;IAE5C,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEzC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YAC/B,MAAM,EAAE,iBAAiB,CAAC,MAAM,IAAI,EAAE;YACtC,MAAM,EAAE,iBAAiB,CAAC,MAAM,IAAI,EAAE;YACtC,WAAW,EAAE,iBAAiB,CAAC,WAAW;gBACtC,CAAC,CAAC;oBACI,WAAW,EAAE,iBAAiB,CAAC,WAAW;oBAC1C,eAAe,EAAE,iBAAiB,CAAC,eAAe,IAAI,EAAE;iBAC3D;gBACH,CAAC,CAAC,SAAS;YACf,QAAQ,EAAE,iBAAiB,CAAC,QAAQ;YACpC,cAAc,EAAE,iBAAiB,CAAC,cAAc;YAChD,SAAS,EAAE,iBAAiB,CAAC,SAAS;YACtC,kBAAkB,EAAE,iBAAiB,CAAC,kBAAkB;SAC3D,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,IAAI;QACN,MAAM,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,QAAQ;QACV,MAAM,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC"}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@wild-framework/storage-s3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "S3 (AWS) storage driver for Wild Framework's storage package.",
+  "keywords": [
+    "wild",
+    "framework",
+    "storage",
+    "files",
+    "s3",
+    "aws",
+    "minio"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@wild-framework/container": "0.2.0",
+    "@wild-framework/storage": "0.2.0",
+    "@wild-framework/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
 }