@rebasepro/server 0.22.0 → 0.24.0

package/README.md

@@ -33,7 +33,7 @@ This is the central orchestrator for any Rebase backend. It provides the framewo
 
 Also exports `HonoEnv`, the auth, email, storage, history and cron modules, custom functions, logging utilities, and the driver registry. The abstract driver interfaces (`DatabaseAdapter`, `AuthAdapter`, `DataDriver`, …) are not re-exported: import them from `@rebasepro/types`.
 
-`@rebasepro/server/functions` is the portable surface a function file imports — `defineFunction`, the `requireAuth`/`requireAdmin` guards, `getUser`, `rebase` and the rest. The package also ships the `rebase-server` binary, which runs a built project bundle (`rebase-server ./dist-bundle`); it is what the `rebasepro/server` image executes.
+`@rebasepro/server/functions` is the portable surface a function file imports — `defineFunction`, the `requireAuth`/`requireAdmin`/`requireScope` guards, `getUser`, `getScopes`, `hasScope`, `rebase` and the rest. The package also ships the `rebase-server` binary, which runs a built project bundle (`rebase-server ./dist-bundle`); it is what the `rebasepro/server` image executes.
 
 ## Quick Start
 

package/bin/rebase-server.js

@@ -31,6 +31,9 @@ Key environment variables:
                         window, requires CORS_ORIGINS, refuses local file
                         storage and turns the OpenAPI docs off
   DATABASE_URL          Connection string for the default database (required)
+  ALLOW_LOCALHOST_IN_PRODUCTION  "true" when the database (or any other
+                        service a variable names) runs on this same machine.
+                        Production refuses localhost addresses without it
   JWT_SECRET            Signing secret, >=32 chars (required in production)
   REBASE_SERVICE_KEY    Server-to-server credential that bypasses row-level
                         security. Treat it like a database superuser password
@@ -46,8 +49,7 @@ Key environment variables:
                         tables and columns at boot, INCLUDING your collections',
                         additively, and applies their row-level security. It
                         never alters, drops or narrows: those go through
-                        'rebase db push' from a checkout, along with
-                        junction-table RLS for many-to-many relations
+                        'rebase db push' from a checkout
 
 Additional databases and buckets are configured by suffixing the variable with
 the source key, e.g. DATABASE_URL__ANALYTICS or S3_BUCKET__MEDIA.

package/dist/{GCSStorageController-CLIJXwGS.js → GCSStorageController-BSiP1c-f.js}

@@ -3,7 +3,8 @@ import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
 import { n as __exportAll } from "./rolldown-runtime-dW7B1o5h.js";
-import { o as folderKey, s as listingPrefix } from "./keys-Qfc4XieN.js";
+import { t as ApiError } from "./errors-D6_y86c5.js";
+import { c as listingPrefix, s as folderKey } from "./keys-GAVZqbqx.js";
 import "./types-BfKcm9do.js";
 //#region src/storage/GCSStorageController.ts
 /**
@@ -72,7 +73,16 @@ var GCSStorageController = class {
 			storageUrl: `gs://${usedBucket}/${key}`
 		};
 	}
-	async getSignedUrl(key, bucket) {
+	/**
+	* Read the object's metadata and nothing else — no signing.
+	*
+	* Signing needs a private key. With `keyFilename` or `credentials` the
+	* client has one; on Cloud Run, GKE or GCE it has only the metadata
+	* server's token, and falls back to the IAM Credentials `signBlob` API,
+	* which the runtime account may call on itself only when it holds
+	* `iam.serviceAccounts.signBlob` there. That is not a default grant.
+	*/
+	async getMetadata(key, bucket) {
 		let resolvedPath = key;
 		let resolvedBucket = this.getBucket(bucket);
 		const match = key.match(/^(gs|s3):\/\//);
@@ -86,32 +96,37 @@ var GCSStorageController = class {
 			}
 		}
 		try {
-			const gcsFile = (await this.getClient()).bucket(resolvedBucket).file(resolvedPath);
-			const [fileMetadata] = await gcsFile.getMetadata();
-			const expiresIn = this.config.signedUrlExpiration ?? 3600;
-			const [url] = await gcsFile.getSignedUrl({
-				action: "read",
-				expires: Date.now() + expiresIn * 1e3
-			});
+			const [fileMetadata] = await (await this.getClient()).bucket(resolvedBucket).file(resolvedPath).getMetadata();
 			return {
-				url,
-				metadata: {
-					bucket: resolvedBucket,
-					fullPath: resolvedPath,
-					name: resolvedPath.split("/").pop() || resolvedPath,
-					size: Number(fileMetadata.size) || 0,
-					contentType: fileMetadata.contentType || "application/octet-stream",
-					customMetadata: fileMetadata.metadata || {}
-				}
+				bucket: resolvedBucket,
+				fullPath: resolvedPath,
+				name: resolvedPath.split("/").pop() || resolvedPath,
+				size: Number(fileMetadata.size) || 0,
+				contentType: fileMetadata.contentType || "application/octet-stream",
+				customMetadata: fileMetadata.metadata || {}
 			};
 		} catch (error) {
-			if (isNotFoundError(error)) return {
-				url: null,
-				fileNotFound: true
-			};
+			if (isNotFoundError(error)) return null;
 			throw error;
 		}
 	}
+	async getSignedUrl(key, bucket) {
+		const metadata = await this.getMetadata(key, bucket);
+		if (!metadata) return {
+			url: null,
+			fileNotFound: true
+		};
+		const client = await this.getClient();
+		const expiresIn = this.config.signedUrlExpiration ?? 3600;
+		const [url] = await client.bucket(metadata.bucket).file(metadata.fullPath).getSignedUrl({
+			action: "read",
+			expires: Date.now() + expiresIn * 1e3
+		});
+		return {
+			url,
+			metadata
+		};
+	}
 	async getObject(key, bucket) {
 		let resolvedPath = key;
 		let resolvedBucket = this.getBucket(bucket);
@@ -132,7 +147,11 @@ var GCSStorageController = class {
 			const contentType = fileMetadata.contentType || "application/octet-stream";
 			const fileName = resolvedPath.split("/").pop() || resolvedPath;
 			const blob = new Blob([new Uint8Array(contents)], { type: contentType });
-			return new File([blob], fileName, { type: contentType });
+			const updated = typeof fileMetadata.updated === "string" ? Date.parse(fileMetadata.updated) : NaN;
+			return new File([blob], fileName, {
+				type: contentType,
+				lastModified: Number.isNaN(updated) ? void 0 : updated
+			});
 		} catch (error) {
 			if (isNotFoundError(error)) return null;
 			throw error;
@@ -155,15 +174,17 @@ var GCSStorageController = class {
 	}
 	async listObjects(prefix, options) {
 		const resolvedBucket = this.getBucket(options?.bucket);
-		const [files, , filesApiResponse] = await (await this.getClient()).bucket(resolvedBucket).getFiles({
-			prefix: listingPrefix(prefix),
+		const gcsBucket = (await this.getClient()).bucket(resolvedBucket);
+		const folderPrefix = listingPrefix(prefix);
+		const [listed, , filesApiResponse] = await gcsBucket.getFiles({
+			prefix: folderPrefix,
 			delimiter: "/",
 			maxResults: options?.maxResults ?? 1e3,
 			pageToken: options?.pageToken,
 			autoPaginate: false
 		});
 		return {
-			items: files.map((file) => ({
+			items: listed.filter((file) => file.name !== folderPrefix).map((file) => ({
 				bucket: resolvedBucket,
 				fullPath: file.name,
 				name: file.name.split("/").pop() || "",
@@ -185,12 +206,19 @@ var GCSStorageController = class {
 			nextPageToken: filesApiResponse?.nextPageToken
 		};
 	}
+	/** See {@link StorageController.maxFileSize}. */
+	maxFileSize() {
+		return this.config.maxFileSize ?? 52428800;
+	}
 	/**
 	* Validate file before upload
 	*/
 	validateFile(file) {
-		const maxSize = this.config.maxFileSize ?? 52428800;
-		if (file.size > maxSize) throw new Error(`File size ${file.size} exceeds maximum allowed size ${maxSize}`);
+		const maxSize = this.maxFileSize();
+		if (file.size > maxSize) throw new ApiError(413, "PAYLOAD_TOO_LARGE", `File size ${file.size} exceeds this storage source's maximum of ${maxSize} bytes.`, {
+			size: file.size,
+			maxFileSize: maxSize
+		});
 		if (this.config.allowedMimeTypes && this.config.allowedMimeTypes.length > 0) {
 			if (!this.config.allowedMimeTypes.includes(file.type)) throw new Error(`File type ${file.type} is not allowed. Allowed types: ${this.config.allowedMimeTypes.join(", ")}`);
 		}
@@ -225,4 +253,4 @@ function isNotFoundError(error) {
 //#endregion
 export { GCSStorageController_exports as n, GCSStorageController as t };
 
-//# sourceMappingURL=GCSStorageController-CLIJXwGS.js.map
+//# sourceMappingURL=GCSStorageController-BSiP1c-f.js.map

package/dist/GCSStorageController-BSiP1c-f.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GCSStorageController-BSiP1c-f.js","names":[],"sources":["../src/storage/GCSStorageController.ts"],"sourcesContent":["/**\n * Google Cloud Storage controller (works with GCS and Firebase Storage)\n *\n * The `@google-cloud/storage` package is loaded lazily so it remains an\n * optional peer dependency — users who don't need GCS never pay for the\n * import cost or need it installed.\n */\n\nimport {\n    StorageController,\n    GCSStorageConfig,\n    DEFAULT_MAX_FILE_SIZE\n} from \"./types\";\nimport { folderKey, listingPrefix } from \"./keys\";\nimport { ApiError } from \"../api/errors\";\nimport {\n    UploadFileProps,\n    UploadFileResult,\n    DownloadConfig,\n    DownloadMetadata,\n    StorageListResult,\n    StorageReference\n} from \"@rebasepro/types\";\n\n// ---------------------------------------------------------------------------\n// Lazy import of @google-cloud/storage\n// ---------------------------------------------------------------------------\n\nlet gcsModule: typeof import(\"@google-cloud/storage\") | null = null;\n\nasync function loadGCS(): Promise<typeof import(\"@google-cloud/storage\")> {\n    if (gcsModule) return gcsModule;\n    try {\n        gcsModule = await import(\"@google-cloud/storage\");\n        return gcsModule;\n    } catch {\n        throw new Error(\n            \"Google Cloud Storage is required for the GCS storage controller. \" +\n            \"Install it with: pnpm add @google-cloud/storage\"\n        );\n    }\n}\n\n// ---------------------------------------------------------------------------\n// GCSStorageController\n// ---------------------------------------------------------------------------\n\n/**\n * Google Cloud Storage implementation of `StorageController`.\n *\n * Works with standard GCS buckets **and** Firebase Storage buckets\n * (e.g. `\"my-project.appspot.com\"`).\n */\nexport class GCSStorageController implements StorageController {\n    private config: GCSStorageConfig;\n    private client: InstanceType<typeof import(\"@google-cloud/storage\").Storage> | null = null;\n\n    constructor(config: GCSStorageConfig) {\n        this.config = config;\n    }\n\n    // ------------------------------------------------------------------\n    // Lazy client initialisation\n    // ------------------------------------------------------------------\n\n    private async getClient(): Promise<InstanceType<typeof import(\"@google-cloud/storage\").Storage>> {\n        if (this.client) return this.client;\n        const { Storage } = await loadGCS();\n        this.client = new Storage({\n            projectId: this.config.projectId,\n            keyFilename: this.config.keyFilename,\n            credentials: this.config.credentials\n        });\n        return this.client;\n    }\n\n    // ------------------------------------------------------------------\n    // StorageController interface\n    // ------------------------------------------------------------------\n\n    getType(): \"gcs\" {\n        return \"gcs\";\n    }\n\n    /**\n     * The configured bucket, and the logical `default` that maps to it.\n     * @see S3StorageController.knownBuckets\n     */\n    knownBuckets(): string[] {\n        return [\"default\", this.config.bucket];\n    }\n\n    async putObject({\n        file,\n        key,\n        metadata,\n        bucket\n    }: UploadFileProps): Promise<UploadFileResult> {\n        this.validateFile(file);\n\n        const usedBucket = this.getBucket(bucket);\n        const client = await this.getClient();\n        const gcsFile = client.bucket(usedBucket).file(key);\n\n        // Convert File to Buffer\n        const arrayBuffer = await file.arrayBuffer();\n        const buffer = Buffer.from(arrayBuffer);\n\n        await gcsFile.save(buffer, {\n            contentType: file.type,\n            metadata: metadata ? { metadata: this.flattenMetadata(metadata) } : undefined\n        });\n\n        return {\n            key,\n            bucket: usedBucket,\n            storageUrl: `gs://${usedBucket}/${key}`\n        };\n    }\n\n    /**\n     * Read the object's metadata and nothing else — no signing.\n     *\n     * Signing needs a private key. With `keyFilename` or `credentials` the\n     * client has one; on Cloud Run, GKE or GCE it has only the metadata\n     * server's token, and falls back to the IAM Credentials `signBlob` API,\n     * which the runtime account may call on itself only when it holds\n     * `iam.serviceAccounts.signBlob` there. That is not a default grant.\n     */\n    async getMetadata(key: string, bucket?: string): Promise<DownloadMetadata | null> {\n        // Handle gs:// and s3:// URLs\n        let resolvedPath = key;\n        let resolvedBucket = this.getBucket(bucket);\n\n        const match = key.match(/^(gs|s3):\\/\\//);\n        if (match) {\n            const protocolLength = match[0].length;\n            const withoutProtocol = key.substring(protocolLength);\n            const firstSlash = withoutProtocol.indexOf(\"/\");\n            if (firstSlash > 0) {\n                resolvedBucket = withoutProtocol.substring(0, firstSlash);\n                resolvedPath = withoutProtocol.substring(firstSlash + 1);\n            }\n        }\n\n        try {\n            const client = await this.getClient();\n            const [fileMetadata] = await client.bucket(resolvedBucket).file(resolvedPath).getMetadata();\n\n            return {\n                bucket: resolvedBucket,\n                fullPath: resolvedPath,\n                name: resolvedPath.split(\"/\").pop() || resolvedPath,\n                size: Number(fileMetadata.size) || 0,\n                contentType: fileMetadata.contentType || \"application/octet-stream\",\n                customMetadata: (fileMetadata.metadata as Record<string, string> | undefined) || {}\n            };\n        } catch (error: unknown) {\n            if (isNotFoundError(error)) {\n                return null;\n            }\n            throw error;\n        }\n    }\n\n    async getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig> {\n        // Metadata first, to check existence and populate the response.\n        const metadata = await this.getMetadata(key, bucket);\n        if (!metadata) {\n            return {\n                url: null,\n                fileNotFound: true\n            };\n        }\n\n        const client = await this.getClient();\n        const expiresIn = this.config.signedUrlExpiration ?? 3600;\n        const [url] = await client.bucket(metadata.bucket).file(metadata.fullPath).getSignedUrl({\n            action: \"read\",\n            expires: Date.now() + expiresIn * 1000\n        });\n\n        return {\n            url,\n            metadata\n        };\n    }\n\n    async getObject(key: string, bucket?: string): Promise<File | null> {\n        // Handle gs:// and s3:// URLs\n        let resolvedPath = key;\n        let resolvedBucket = this.getBucket(bucket);\n\n        const match = key.match(/^(gs|s3):\\/\\//);\n        if (match) {\n            const protocolLength = match[0].length;\n            const withoutProtocol = key.substring(protocolLength);\n            const firstSlash = withoutProtocol.indexOf(\"/\");\n            if (firstSlash > 0) {\n                resolvedBucket = withoutProtocol.substring(0, firstSlash);\n                resolvedPath = withoutProtocol.substring(firstSlash + 1);\n            }\n        }\n\n        try {\n            const client = await this.getClient();\n            const gcsFile = client.bucket(resolvedBucket).file(resolvedPath);\n\n            const [contents] = await gcsFile.download();\n\n            // Get content type from metadata\n            const [fileMetadata] = await gcsFile.getMetadata();\n            const contentType = fileMetadata.contentType || \"application/octet-stream\";\n            const fileName = resolvedPath.split(\"/\").pop() || resolvedPath;\n\n            const blob = new Blob([new Uint8Array(contents)], { type: contentType });\n            // The object's own version — see `S3StorageController.getObject`.\n            const updated = typeof fileMetadata.updated === \"string\" ? Date.parse(fileMetadata.updated) : NaN;\n            return new File([blob], fileName, {\n                type: contentType,\n                lastModified: Number.isNaN(updated) ? undefined : updated\n            });\n        } catch (error: unknown) {\n            if (isNotFoundError(error)) {\n                return null;\n            }\n            throw error;\n        }\n    }\n\n    async deleteObject(key: string, bucket?: string): Promise<void> {\n        // Handle gs:// and s3:// URLs\n        let resolvedPath = key;\n        let resolvedBucket = this.getBucket(bucket);\n\n        const match = key.match(/^(gs|s3):\\/\\//);\n        if (match) {\n            const protocolLength = match[0].length;\n            const withoutProtocol = key.substring(protocolLength);\n            const firstSlash = withoutProtocol.indexOf(\"/\");\n            if (firstSlash > 0) {\n                resolvedBucket = withoutProtocol.substring(0, firstSlash);\n                resolvedPath = withoutProtocol.substring(firstSlash + 1);\n            }\n        }\n\n        const client = await this.getClient();\n        const gcsFile = client.bucket(resolvedBucket).file(resolvedPath);\n\n        await gcsFile.delete({ ignoreNotFound: true });\n    }\n\n    async listObjects(prefix: string, options?: {\n        bucket?: string;\n        maxResults?: number;\n        pageToken?: string;\n    }): Promise<StorageListResult> {\n        const resolvedBucket = this.getBucket(options?.bucket);\n        const client = await this.getClient();\n        const gcsBucket = client.bucket(resolvedBucket);\n\n        // Fetch files (objects) matching the prefix\n        const folderPrefix = listingPrefix(prefix);\n        const [listed, , filesApiResponse] = await gcsBucket.getFiles({\n            prefix: folderPrefix,\n            delimiter: \"/\",\n            maxResults: options?.maxResults ?? 1000,\n            pageToken: options?.pageToken,\n            autoPaginate: false\n        });\n\n        // The folder's own marker object is not something in the folder —\n        // see `S3StorageController.listObjects`.\n        const files = listed.filter(file => file.name !== folderPrefix);\n        const items: StorageReference[] = files.map(file => ({\n            bucket: resolvedBucket,\n            fullPath: file.name,\n            name: file.name.split(\"/\").pop() || \"\",\n            parent: null as never,\n            root: null as never,\n            toString: () => `gs://${resolvedBucket}/${file.name}`\n        }));\n\n        // Common prefixes (folder-like entries) come from the API response\n        const apiPrefixes: string[] =\n            (filesApiResponse as Record<string, unknown> | undefined)?.prefixes as string[] ?? [];\n\n        const prefixes: StorageReference[] = apiPrefixes.map(p => {\n            // Without the trailing slash GCS puts on a common prefix, so a\n            // `fullPath` from a listing is a key any controller accepts.\n            const folder = folderKey(p);\n            return {\n                bucket: resolvedBucket,\n                fullPath: folder,\n                name: folder.split(\"/\").pop() || \"\",\n                parent: null as never,\n                root: null as never,\n                toString: () => `gs://${resolvedBucket}/${folder}`\n            };\n        });\n\n        // The next page token is returned on the query object (second element)\n        const nextPageToken =\n            (filesApiResponse as Record<string, unknown> | undefined)?.nextPageToken as string | undefined;\n\n        return {\n            items,\n            prefixes,\n            nextPageToken\n        };\n    }\n\n    // ------------------------------------------------------------------\n    // Private helpers\n    // ------------------------------------------------------------------\n\n    /** See {@link StorageController.maxFileSize}. */\n    maxFileSize(): number {\n        return this.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;\n    }\n\n    /**\n     * Validate file before upload\n     */\n    private validateFile(file: File): void {\n        const maxSize = this.maxFileSize();\n        if (file.size > maxSize) {\n            // An ApiError, so the refusal reaches the caller as what it is. A\n            // plain Error was a 500 on `/upload` and a 502 on TUS — after the\n            // client had sent every byte.\n            throw new ApiError(\n                413,\n                \"PAYLOAD_TOO_LARGE\",\n                `File size ${file.size} exceeds this storage source's maximum of ${maxSize} bytes.`,\n                { size: file.size, maxFileSize: maxSize }\n            );\n        }\n\n        if (this.config.allowedMimeTypes && this.config.allowedMimeTypes.length > 0) {\n            if (!this.config.allowedMimeTypes.includes(file.type)) {\n                throw new Error(`File type ${file.type} is not allowed. Allowed types: ${this.config.allowedMimeTypes.join(\", \")}`);\n            }\n        }\n    }\n\n    /**\n     * Get the bucket name — either from parameter or config.\n     */\n    private getBucket(bucket?: string): string {\n        // \"default\" is a logical bucket name used by local storage;\n        // for GCS it should resolve to the configured bucket.\n        if (!bucket || bucket === \"default\") return this.config.bucket;\n        return bucket;\n    }\n\n    /**\n     * Flatten nested metadata to string values (GCS custom metadata requirement)\n     */\n    private flattenMetadata(metadata: Record<string, unknown>): Record<string, string> {\n        const flattened: Record<string, string> = {};\n        for (const [key, value] of Object.entries(metadata)) {\n            if (typeof value === \"string\") {\n                flattened[key] = value;\n            } else if (value !== undefined && value !== null) {\n                flattened[key] = JSON.stringify(value);\n            }\n        }\n        return flattened;\n    }\n}\n\n// ---------------------------------------------------------------------------\n// Error helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Check whether an error represents a 404 / Not Found from the GCS client.\n */\nfunction isNotFoundError(error: unknown): boolean {\n    if (typeof error !== \"object\" || error === null) return false;\n    const err = error as Record<string, unknown>;\n    if (err[\"code\"] === 404) return true;\n    if (typeof err[\"message\"] === \"string\" && /not found/i.test(err[\"message\"])) return true;\n    return false;\n}\n"],"mappings":"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"}

package/dist/{S3StorageController-Dcuf8lMA.js → S3StorageController-CAwFRgjV.js}

@@ -3,7 +3,8 @@ import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
 import { n as __exportAll } from "./rolldown-runtime-dW7B1o5h.js";
-import { o as folderKey, s as listingPrefix } from "./keys-Qfc4XieN.js";
+import { t as ApiError } from "./errors-D6_y86c5.js";
+import { c as listingPrefix, s as folderKey } from "./keys-GAVZqbqx.js";
 import "./types-BfKcm9do.js";
 //#region src/storage/S3StorageController.ts
 var S3StorageController_exports = /* @__PURE__ */ __exportAll({ S3StorageController: () => S3StorageController });
@@ -66,12 +67,19 @@ var S3StorageController = class {
 	knownBuckets() {
 		return ["default", this.config.bucket];
 	}
+	/** See {@link StorageController.maxFileSize}. */
+	maxFileSize() {
+		return this.config.maxFileSize ?? 52428800;
+	}
 	/**
 	* Validate file before upload
 	*/
 	validateFile(file) {
-		const maxSize = this.config.maxFileSize ?? 52428800;
-		if (file.size > maxSize) throw new Error(`File size ${file.size} exceeds maximum allowed size ${maxSize}`);
+		const maxSize = this.maxFileSize();
+		if (file.size > maxSize) throw new ApiError(413, "PAYLOAD_TOO_LARGE", `File size ${file.size} exceeds this storage source's maximum of ${maxSize} bytes.`, {
+			size: file.size,
+			maxFileSize: maxSize
+		});
 		if (this.config.allowedMimeTypes && this.config.allowedMimeTypes.length > 0) {
 			if (!this.config.allowedMimeTypes.includes(file.type)) throw new Error(`File type ${file.type} is not allowed. Allowed types: ${this.config.allowedMimeTypes.join(", ")}`);
 		}
@@ -188,7 +196,10 @@ var S3StorageController = class {
 			const contentType = response.ContentType || "application/octet-stream";
 			const fileName = resolvedPath.split("/").pop() || resolvedPath;
 			const blob = new Blob([buffer], { type: contentType });
-			return new File([blob], fileName, { type: contentType });
+			return new File([blob], fileName, {
+				type: contentType,
+				lastModified: response.LastModified?.getTime()
+			});
 		} catch (error) {
 			const s3Error = error;
 			if (s3Error.name === "NoSuchKey" || s3Error.$metadata?.httpStatusCode === 404) return null;
@@ -226,16 +237,17 @@ var S3StorageController = class {
 		const resolvedBucket = this.getBucket(options?.bucket);
 		const s3 = await loadS3();
 		const client = await this.getClient();
+		const folderPrefix = listingPrefix(prefix);
 		const command = new s3.ListObjectsV2Command({
 			Bucket: resolvedBucket,
-			Prefix: listingPrefix(prefix),
+			Prefix: folderPrefix,
 			MaxKeys: options?.maxResults ?? 1e3,
 			ContinuationToken: options?.pageToken,
 			Delimiter: "/"
 		});
 		const response = await client.send(command);
 		return {
-			items: (response.Contents || []).map((obj) => ({
+			items: (response.Contents || []).filter((obj) => obj.Key !== folderPrefix).map((obj) => ({
 				bucket: resolvedBucket,
 				fullPath: obj.Key || "",
 				name: (obj.Key || "").split("/").pop() || "",
@@ -261,4 +273,4 @@ var S3StorageController = class {
 //#endregion
 export { S3StorageController_exports as n, S3StorageController as t };
 
-//# sourceMappingURL=S3StorageController-Dcuf8lMA.js.map
+//# sourceMappingURL=S3StorageController-CAwFRgjV.js.map

package/dist/S3StorageController-CAwFRgjV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3StorageController-CAwFRgjV.js","names":[],"sources":["../src/storage/S3StorageController.ts"],"sourcesContent":["/**\n * S3-compatible storage controller (works with AWS S3 and MinIO)\n */\n\nimport type { S3Client as S3ClientType, } from \"@aws-sdk/client-s3\";\nimport { DEFAULT_MAX_FILE_SIZE, S3StorageConfig, StorageController } from \"./types\";\nimport { folderKey, listingPrefix } from \"./keys\";\nimport { ApiError } from \"../api/errors\";\nimport {\n    DownloadConfig,\n    DownloadMetadata,\n    StorageListResult,\n    StorageReference,\n    UploadFileProps,\n    UploadFileResult\n} from \"@rebasepro/types\";\n\nlet _s3Module: typeof import(\"@aws-sdk/client-s3\") | undefined;\nlet _presignerModule: typeof import(\"@aws-sdk/s3-request-presigner\") | undefined;\n\nasync function loadS3() {\n    if (!_s3Module) {\n        try {\n            _s3Module = await import(\"@aws-sdk/client-s3\");\n        } catch {\n            throw new Error(\n                \"@aws-sdk/client-s3 is required for S3 storage. \" +\n                \"Install it: pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner\"\n            );\n        }\n    }\n    return _s3Module;\n}\n\nasync function loadPresigner() {\n    if (!_presignerModule) {\n        try {\n            _presignerModule = await import(\"@aws-sdk/s3-request-presigner\");\n        } catch {\n            throw new Error(\n                \"@aws-sdk/s3-request-presigner is required for S3 storage. \" +\n                \"Install it: pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner\"\n            );\n        }\n    }\n    return _presignerModule;\n}\n\n/**\n * S3-compatible storage implementation\n * Works with AWS S3 and MinIO (with forcePathStyle option)\n */\nexport class S3StorageController implements StorageController {\n    private config: S3StorageConfig;\n    private _client: S3ClientType | undefined;\n\n    constructor(config: S3StorageConfig) {\n        this.config = config;\n    }\n\n    /**\n     * Lazily create and cache the S3 client on first use\n     */\n    private async getClient(): Promise<S3ClientType> {\n        if (!this._client) {\n            const s3 = await loadS3();\n            this._client = new s3.S3Client({\n                region: this.config.region || \"us-east-1\",\n                endpoint: this.config.endpoint,\n                forcePathStyle: this.config.forcePathStyle ?? !!this.config.endpoint, // Auto-enable for custom endpoints (MinIO)\n                credentials: {\n                    accessKeyId: this.config.accessKeyId,\n                    secretAccessKey: this.config.secretAccessKey\n                }\n            });\n        }\n        return this._client;\n    }\n\n    getType(): \"s3\" {\n        return \"s3\";\n    }\n\n    /**\n     * The configured bucket, and the logical `default` that maps to it.\n     *\n     * Any other name went straight to S3 as a bucket name, so the request\n     * parameter was a way to address *any* bucket the deployment's credentials\n     * can reach — and a mistyped one came back as \"file not found\".\n     */\n    knownBuckets(): string[] {\n        return [\"default\", this.config.bucket];\n    }\n\n    /** See {@link StorageController.maxFileSize}. */\n    maxFileSize(): number {\n        return this.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;\n    }\n\n    /**\n     * Validate file before upload\n     */\n    private validateFile(file: File): void {\n        const maxSize = this.maxFileSize();\n        if (file.size > maxSize) {\n            // An ApiError, so the refusal reaches the caller as what it is. A\n            // plain Error was a 500 on `/upload` and a 502 on TUS — after the\n            // client had sent every byte.\n            throw new ApiError(\n                413,\n                \"PAYLOAD_TOO_LARGE\",\n                `File size ${file.size} exceeds this storage source's maximum of ${maxSize} bytes.`,\n                { size: file.size, maxFileSize: maxSize }\n            );\n        }\n\n        if (this.config.allowedMimeTypes && this.config.allowedMimeTypes.length > 0) {\n            if (!this.config.allowedMimeTypes.includes(file.type)) {\n                throw new Error(`File type ${file.type} is not allowed. Allowed types: ${this.config.allowedMimeTypes.join(\", \")}`);\n            }\n        }\n    }\n\n    /**\n     * Get the bucket name - either from parameter or config\n     */\n    private getBucket(bucket?: string): string {\n        // \"default\" is a logical bucket name used by local storage;\n        // for S3 it should resolve to the configured bucket.\n        if (!bucket || bucket === \"default\") return this.config.bucket;\n        return bucket;\n    }\n\n    async putObject({\n        file,\n        key,\n        metadata,\n        bucket\n    }: UploadFileProps): Promise<UploadFileResult> {\n        this.validateFile(file);\n\n        const usedBucket = this.getBucket(bucket);\n\n        // Convert File to Buffer\n        const arrayBuffer = await file.arrayBuffer();\n        const buffer = Buffer.from(arrayBuffer);\n\n        const s3 = await loadS3();\n        const client = await this.getClient();\n\n        const command = new s3.PutObjectCommand({\n            Bucket: usedBucket,\n            Key: key,\n            Body: buffer,\n            ContentType: file.type,\n            Metadata: metadata ? this.flattenMetadata(metadata) : undefined\n        });\n\n        await client.send(command);\n\n        return {\n            key,\n            bucket: usedBucket,\n            storageUrl: `s3://${usedBucket}/${key}`\n        };\n    }\n\n    /**\n     * Flatten nested metadata to string values (S3 requirement)\n     */\n    private flattenMetadata(metadata: Record<string, unknown>): Record<string, string> {\n        const flattened: Record<string, string> = {};\n        for (const [key, value] of Object.entries(metadata)) {\n            if (typeof value === \"string\") {\n                flattened[key] = value;\n            } else if (value !== undefined && value !== null) {\n                flattened[key] = JSON.stringify(value);\n            }\n        }\n        return flattened;\n    }\n\n    async getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig> {\n        // Handle s3:// and gs:// URLs for backward compatibility\n        let resolvedPath = key;\n        let resolvedBucket = this.getBucket(bucket);\n\n        const match = key.match(/^(s3|gs):\\/\\//);\n        if (match) {\n            const protocolLength = match[0].length;\n            const withoutProtocol = key.substring(protocolLength);\n            const firstSlash = withoutProtocol.indexOf(\"/\");\n            if (firstSlash > 0) {\n                resolvedBucket = withoutProtocol.substring(0, firstSlash);\n                resolvedPath = withoutProtocol.substring(firstSlash + 1);\n            }\n        }\n\n        try {\n            const s3 = await loadS3();\n            const presigner = await loadPresigner();\n            const client = await this.getClient();\n\n            // First check if the object exists and get metadata\n            const headCommand = new s3.HeadObjectCommand({\n                Bucket: resolvedBucket,\n                Key: resolvedPath\n            });\n\n            const headResult = await client.send(headCommand);\n\n            // Generate a signed URL\n            const getCommand = new s3.GetObjectCommand({\n                Bucket: resolvedBucket,\n                Key: resolvedPath\n            });\n\n            const expiresIn = this.config.signedUrlExpiration ?? 3600;\n            const url = await presigner.getSignedUrl(client, getCommand, { expiresIn });\n\n            const metadata: DownloadMetadata = {\n                bucket: resolvedBucket,\n                fullPath: resolvedPath,\n                name: resolvedPath.split(\"/\").pop() || resolvedPath,\n                size: headResult.ContentLength || 0,\n                contentType: headResult.ContentType || \"application/octet-stream\",\n                customMetadata: headResult.Metadata || {}\n            };\n\n            return {\n                url,\n                metadata\n            };\n        } catch (error: unknown) {\n            const s3Error = error as { name?: string; $metadata?: { httpStatusCode?: number } };\n            if (s3Error.name === \"NotFound\" || s3Error.$metadata?.httpStatusCode === 404) {\n                return {\n                    url: null,\n                    fileNotFound: true\n                };\n            }\n            throw error;\n        }\n    }\n\n    async getObject(key: string, bucket?: string): Promise<File | null> {\n        // Handle s3:// and gs:// URLs\n        let resolvedPath = key;\n        let resolvedBucket = this.getBucket(bucket);\n\n        const match = key.match(/^(s3|gs):\\/\\//);\n        if (match) {\n            const protocolLength = match[0].length;\n            const withoutProtocol = key.substring(protocolLength);\n            const firstSlash = withoutProtocol.indexOf(\"/\");\n            if (firstSlash > 0) {\n                resolvedBucket = withoutProtocol.substring(0, firstSlash);\n                resolvedPath = withoutProtocol.substring(firstSlash + 1);\n            }\n        }\n\n        try {\n            const s3 = await loadS3();\n            const client = await this.getClient();\n\n            const command = new s3.GetObjectCommand({\n                Bucket: resolvedBucket,\n                Key: resolvedPath\n            });\n\n            const response = await client.send(command);\n\n            if (!response.Body) {\n                return null;\n            }\n\n            // Convert stream to buffer\n            const chunks: Uint8Array[] = [];\n            for await (const chunk of response.Body as AsyncIterable<Uint8Array>) {\n                chunks.push(chunk);\n            }\n            const buffer = Buffer.concat(chunks);\n\n            const contentType = response.ContentType || \"application/octet-stream\";\n            const fileName = resolvedPath.split(\"/\").pop() || resolvedPath;\n\n            const blob = new Blob([buffer], { type: contentType });\n            // The object's own version. Left out, `File` stamps `Date.now()`,\n            // and the routes build the `ETag`, `Last-Modified` and the\n            // transform cache key from this — so every read was a new version:\n            // no 304, no cache hit, and a fresh rendition written per request.\n            return new File([blob], fileName, {\n                type: contentType,\n                lastModified: response.LastModified?.getTime()\n            });\n        } catch (error: unknown) {\n            const s3Error = error as { name?: string; $metadata?: { httpStatusCode?: number } };\n            if (s3Error.name === \"NoSuchKey\" || s3Error.$metadata?.httpStatusCode === 404) {\n                return null;\n            }\n            throw error;\n        }\n    }\n\n    async deleteObject(key: string, bucket?: string): Promise<void> {\n        // Handle s3:// and gs:// URLs\n        let resolvedPath = key;\n        let resolvedBucket = this.getBucket(bucket);\n\n        const match = key.match(/^(s3|gs):\\/\\//);\n        if (match) {\n            const protocolLength = match[0].length;\n            const withoutProtocol = key.substring(protocolLength);\n            const firstSlash = withoutProtocol.indexOf(\"/\");\n            if (firstSlash > 0) {\n                resolvedBucket = withoutProtocol.substring(0, firstSlash);\n                resolvedPath = withoutProtocol.substring(firstSlash + 1);\n            }\n        }\n\n        const s3 = await loadS3();\n        const client = await this.getClient();\n\n        const command = new s3.DeleteObjectCommand({\n            Bucket: resolvedBucket,\n            Key: resolvedPath\n        });\n\n        // Deleting something that is already gone is the outcome the caller\n        // wanted, so it is not an error. AWS itself answers DeleteObject with\n        // 204 for a key that never existed, but S3-compatible backends (MinIO,\n        // Ceph, R2 in some configurations) do raise NoSuchKey — and the local\n        // controller has always returned quietly in this case. Without this,\n        // which of those a deployment happens to run decides whether\n        // `DELETE /api/storage/:path` on a stale reference is a 200 or a 500.\n        try {\n            await client.send(command);\n        } catch (error: unknown) {\n            const s3Error = error as { name?: string; $metadata?: { httpStatusCode?: number } };\n            if (s3Error.name === \"NoSuchKey\" || s3Error.$metadata?.httpStatusCode === 404) {\n                return;\n            }\n            throw error;\n        }\n    }\n\n    async listObjects(prefix: string, options?: {\n        bucket?: string;\n        maxResults?: number;\n        pageToken?: string;\n    }): Promise<StorageListResult> {\n        const resolvedBucket = this.getBucket(options?.bucket);\n\n        const s3 = await loadS3();\n        const client = await this.getClient();\n\n        const folderPrefix = listingPrefix(prefix);\n        const command = new s3.ListObjectsV2Command({\n            Bucket: resolvedBucket,\n            Prefix: folderPrefix,\n            MaxKeys: options?.maxResults ?? 1000,\n            ContinuationToken: options?.pageToken,\n            Delimiter: \"/\" // This gives us folder-like behavior\n        });\n\n        const response = await client.send(command);\n\n        // The folder's own marker — the zero-byte `folder/` object that\n        // `POST /folder` writes — is in `Contents` when the listed prefix is\n        // that folder. It is how the folder exists, not something in it, and\n        // listed it is an entry with an empty name. Local storage has no such\n        // object to list.\n        const objects = (response.Contents || []).filter(obj => obj.Key !== folderPrefix);\n        const items: StorageReference[] = objects.map(obj => ({\n            bucket: resolvedBucket,\n            fullPath: obj.Key || \"\",\n            name: (obj.Key || \"\").split(\"/\").pop() || \"\",\n            parent: null as never,\n            root: null as never,\n            toString: () => `s3://${resolvedBucket}/${obj.Key}`\n        }));\n\n        const prefixes: StorageReference[] = (response.CommonPrefixes || []).map(common => {\n            // Without the trailing slash S3 puts on a common prefix, so a\n            // `fullPath` from a listing is a key any controller accepts.\n            const folder = folderKey(common.Prefix || \"\");\n            return {\n                bucket: resolvedBucket,\n                fullPath: folder,\n                name: folder.split(\"/\").pop() || \"\",\n                parent: null as never,\n                root: null as never,\n                toString: () => `s3://${resolvedBucket}/${folder}`\n            };\n        });\n\n        return {\n            items,\n            prefixes,\n            nextPageToken: response.NextContinuationToken\n        };\n    }\n}\n"],"mappings":";;;;;;;;;;AAiBA,IAAI;AACJ,IAAI;AAEJ,eAAe,SAAS;CACpB,IAAI,CAAC,WACD,IAAI;EACA,YAAY,MAAM,OAAO;CAC7B,QAAQ;EACJ,MAAM,IAAI,MACN,sHAEJ;CACJ;CAEJ,OAAO;AACX;AAEA,eAAe,gBAAgB;CAC3B,IAAI,CAAC,kBACD,IAAI;EACA,mBAAmB,MAAM,OAAO;CACpC,QAAQ;EACJ,MAAM,IAAI,MACN,iIAEJ;CACJ;CAEJ,OAAO;AACX;;;;;AAMA,IAAa,sBAAb,MAA8D;CAC1D;CACA;CAEA,YAAY,QAAyB;EACjC,KAAK,SAAS;CAClB;;;;CAKA,MAAc,YAAmC;EAC7C,IAAI,CAAC,KAAK,SAAS;GACf,MAAM,KAAK,MAAM,OAAO;GACxB,KAAK,UAAU,IAAI,GAAG,SAAS;IAC3B,QAAQ,KAAK,OAAO,UAAU;IAC9B,UAAU,KAAK,OAAO;IACtB,gBAAgB,KAAK,OAAO,kBAAkB,CAAC,CAAC,KAAK,OAAO;IAC5D,aAAa;KACT,aAAa,KAAK,OAAO;KACzB,iBAAiB,KAAK,OAAO;IACjC;GACJ,CAAC;EACL;EACA,OAAO,KAAK;CAChB;CAEA,UAAgB;EACZ,OAAO;CACX;;;;;;;;CASA,eAAyB;EACrB,OAAO,CAAC,WAAW,KAAK,OAAO,MAAM;CACzC;;CAGA,cAAsB;EAClB,OAAO,KAAK,OAAO,eAAA;CACvB;;;;CAKA,aAAqB,MAAkB;EACnC,MAAM,UAAU,KAAK,YAAY;EACjC,IAAI,KAAK,OAAO,SAIZ,MAAM,IAAI,SACN,KACA,qBACA,aAAa,KAAK,KAAK,4CAA4C,QAAQ,UAC3E;GAAE,MAAM,KAAK;GAAM,aAAa;EAAQ,CAC5C;EAGJ,IAAI,KAAK,OAAO,oBAAoB,KAAK,OAAO,iBAAiB,SAAS;OAClE,CAAC,KAAK,OAAO,iBAAiB,SAAS,KAAK,IAAI,GAChD,MAAM,IAAI,MAAM,aAAa,KAAK,KAAK,kCAAkC,KAAK,OAAO,iBAAiB,KAAK,IAAI,GAAG;EAAA;CAG9H;;;;CAKA,UAAkB,QAAyB;EAGvC,IAAI,CAAC,UAAU,WAAW,WAAW,OAAO,KAAK,OAAO;EACxD,OAAO;CACX;CAEA,MAAM,UAAU,EACZ,MACA,KACA,UACA,UAC2C;EAC3C,KAAK,aAAa,IAAI;EAEtB,MAAM,aAAa,KAAK,UAAU,MAAM;EAGxC,MAAM,cAAc,MAAM,KAAK,YAAY;EAC3C,MAAM,SAAS,OAAO,KAAK,WAAW;EAEtC,MAAM,KAAK,MAAM,OAAO;EACxB,MAAM,SAAS,MAAM,KAAK,UAAU;EAEpC,MAAM,UAAU,IAAI,GAAG,iBAAiB;GACpC,QAAQ;GACR,KAAK;GACL,MAAM;GACN,aAAa,KAAK;GAClB,UAAU,WAAW,KAAK,gBAAgB,QAAQ,IAAI,KAAA;EAC1D,CAAC;EAED,MAAM,OAAO,KAAK,OAAO;EAEzB,OAAO;GACH;GACA,QAAQ;GACR,YAAY,QAAQ,WAAW,GAAG;EACtC;CACJ;;;;CAKA,gBAAwB,UAA2D;EAC/E,MAAM,YAAoC,CAAC;EAC3C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAC9C,IAAI,OAAO,UAAU,UACjB,UAAU,OAAO;OACd,IAAI,UAAU,KAAA,KAAa,UAAU,MACxC,UAAU,OAAO,KAAK,UAAU,KAAK;EAG7C,OAAO;CACX;CAEA,MAAM,aAAa,KAAa,QAA0C;EAEtE,IAAI,eAAe;EACnB,IAAI,iBAAiB,KAAK,UAAU,MAAM;EAE1C,MAAM,QAAQ,IAAI,MAAM,eAAe;EACvC,IAAI,OAAO;GACP,MAAM,iBAAiB,MAAM,EAAE,CAAC;GAChC,MAAM,kBAAkB,IAAI,UAAU,cAAc;GACpD,MAAM,aAAa,gBAAgB,QAAQ,GAAG;GAC9C,IAAI,aAAa,GAAG;IAChB,iBAAiB,gBAAgB,UAAU,GAAG,UAAU;IACxD,eAAe,gBAAgB,UAAU,aAAa,CAAC;GAC3D;EACJ;EAEA,IAAI;GACA,MAAM,KAAK,MAAM,OAAO;GACxB,MAAM,YAAY,MAAM,cAAc;GACtC,MAAM,SAAS,MAAM,KAAK,UAAU;GAGpC,MAAM,cAAc,IAAI,GAAG,kBAAkB;IACzC,QAAQ;IACR,KAAK;GACT,CAAC;GAED,MAAM,aAAa,MAAM,OAAO,KAAK,WAAW;GAGhD,MAAM,aAAa,IAAI,GAAG,iBAAiB;IACvC,QAAQ;IACR,KAAK;GACT,CAAC;GAED,MAAM,YAAY,KAAK,OAAO,uBAAuB;GAYrD,OAAO;IACH,KAAA,MAZc,UAAU,aAAa,QAAQ,YAAY,EAAE,UAAU,CAAC;IAatE,UAAA;KAVA,QAAQ;KACR,UAAU;KACV,MAAM,aAAa,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK;KACvC,MAAM,WAAW,iBAAiB;KAClC,aAAa,WAAW,eAAe;KACvC,gBAAgB,WAAW,YAAY,CAAC;IAKxC;GACJ;EACJ,SAAS,OAAgB;GACrB,MAAM,UAAU;GAChB,IAAI,QAAQ,SAAS,cAAc,QAAQ,WAAW,mBAAmB,KACrE,OAAO;IACH,KAAK;IACL,cAAc;GAClB;GAEJ,MAAM;EACV;CACJ;CAEA,MAAM,UAAU,KAAa,QAAuC;EAEhE,IAAI,eAAe;EACnB,IAAI,iBAAiB,KAAK,UAAU,MAAM;EAE1C,MAAM,QAAQ,IAAI,MAAM,eAAe;EACvC,IAAI,OAAO;GACP,MAAM,iBAAiB,MAAM,EAAE,CAAC;GAChC,MAAM,kBAAkB,IAAI,UAAU,cAAc;GACpD,MAAM,aAAa,gBAAgB,QAAQ,GAAG;GAC9C,IAAI,aAAa,GAAG;IAChB,iBAAiB,gBAAgB,UAAU,GAAG,UAAU;IACxD,eAAe,gBAAgB,UAAU,aAAa,CAAC;GAC3D;EACJ;EAEA,IAAI;GACA,MAAM,KAAK,MAAM,OAAO;GACxB,MAAM,SAAS,MAAM,KAAK,UAAU;GAEpC,MAAM,UAAU,IAAI,GAAG,iBAAiB;IACpC,QAAQ;IACR,KAAK;GACT,CAAC;GAED,MAAM,WAAW,MAAM,OAAO,KAAK,OAAO;GAE1C,IAAI,CAAC,SAAS,MACV,OAAO;GAIX,MAAM,SAAuB,CAAC;GAC9B,WAAW,MAAM,SAAS,SAAS,MAC/B,OAAO,KAAK,KAAK;GAErB,MAAM,SAAS,OAAO,OAAO,MAAM;GAEnC,MAAM,cAAc,SAAS,eAAe;GAC5C,MAAM,WAAW,aAAa,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK;GAElD,MAAM,OAAO,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,MAAM,YAAY,CAAC;GAKrD,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,UAAU;IAC9B,MAAM;IACN,cAAc,SAAS,cAAc,QAAQ;GACjD,CAAC;EACL,SAAS,OAAgB;GACrB,MAAM,UAAU;GAChB,IAAI,QAAQ,SAAS,eAAe,QAAQ,WAAW,mBAAmB,KACtE,OAAO;GAEX,MAAM;EACV;CACJ;CAEA,MAAM,aAAa,KAAa,QAAgC;EAE5D,IAAI,eAAe;EACnB,IAAI,iBAAiB,KAAK,UAAU,MAAM;EAE1C,MAAM,QAAQ,IAAI,MAAM,eAAe;EACvC,IAAI,OAAO;GACP,MAAM,iBAAiB,MAAM,EAAE,CAAC;GAChC,MAAM,kBAAkB,IAAI,UAAU,cAAc;GACpD,MAAM,aAAa,gBAAgB,QAAQ,GAAG;GAC9C,IAAI,aAAa,GAAG;IAChB,iBAAiB,gBAAgB,UAAU,GAAG,UAAU;IACxD,eAAe,gBAAgB,UAAU,aAAa,CAAC;GAC3D;EACJ;EAEA,MAAM,KAAK,MAAM,OAAO;EACxB,MAAM,SAAS,MAAM,KAAK,UAAU;EAEpC,MAAM,UAAU,IAAI,GAAG,oBAAoB;GACvC,QAAQ;GACR,KAAK;EACT,CAAC;EASD,IAAI;GACA,MAAM,OAAO,KAAK,OAAO;EAC7B,SAAS,OAAgB;GACrB,MAAM,UAAU;GAChB,IAAI,QAAQ,SAAS,eAAe,QAAQ,WAAW,mBAAmB,KACtE;GAEJ,MAAM;EACV;CACJ;CAEA,MAAM,YAAY,QAAgB,SAIH;EAC3B,MAAM,iBAAiB,KAAK,UAAU,SAAS,MAAM;EAErD,MAAM,KAAK,MAAM,OAAO;EACxB,MAAM,SAAS,MAAM,KAAK,UAAU;EAEpC,MAAM,eAAe,cAAc,MAAM;EACzC,MAAM,UAAU,IAAI,GAAG,qBAAqB;GACxC,QAAQ;GACR,QAAQ;GACR,SAAS,SAAS,cAAc;GAChC,mBAAmB,SAAS;GAC5B,WAAW;EACf,CAAC;EAED,MAAM,WAAW,MAAM,OAAO,KAAK,OAAO;EA+B1C,OAAO;GACH,QAzBa,SAAS,YAAY,CAAC,EAAA,CAAG,QAAO,QAAO,IAAI,QAAQ,YAClC,CAAA,CAAQ,KAAI,SAAQ;IAClD,QAAQ;IACR,UAAU,IAAI,OAAO;IACrB,OAAO,IAAI,OAAO,GAAA,CAAI,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK;IAC1C,QAAQ;IACR,MAAM;IACN,gBAAgB,QAAQ,eAAe,GAAG,IAAI;GAClD,EAiBI;GACA,WAhBkC,SAAS,kBAAkB,CAAC,EAAA,CAAG,KAAI,WAAU;IAG/E,MAAM,SAAS,UAAU,OAAO,UAAU,EAAE;IAC5C,OAAO;KACH,QAAQ;KACR,UAAU;KACV,MAAM,OAAO,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK;KACjC,QAAQ;KACR,MAAM;KACN,gBAAgB,QAAQ,eAAe,GAAG;IAC9C;GACJ,CAII;GACA,eAAe,SAAS;EAC5B;CACJ;AACJ"}

package/dist/api/ast-schema-editor.d.ts

@@ -1,3 +1,4 @@
+import { type CollectionPatch } from "@rebasepro/types";
 /**
  * Move presentation keys into the `admin` block.
  *
@@ -59,6 +60,22 @@ export declare class AstSchemaEditor {
      * Resolve a file path and ensure it falls within the collectionsDir.
      */
     private safePath;
+    /**
+     * Bring the in-memory project back in line with the disk.
+     *
+     * The source-only editor builds ONE of these at boot and serves every
+     * request with it, and ts-morph reads a file once and then trusts its
+     * copy. `project.save()` writes that copy back whole, so anything that
+     * reached the disk in between — the live editor's committed change (it
+     * builds a fresh editor per request), or the developer's own edit in the
+     * IDE — was overwritten by the boot-time copy plus this edit. In `rebase
+     * dev` the tsx-watch restart usually closed the window; outside watch mode
+     * the loss was permanent.
+     *
+     * Called at the top of every public method, so each edit applies to what
+     * is on disk now.
+     */
+    private syncWithDisk;
     private getCollectionFile;
     /**
      * Find the object literal a collection is declared with, through whatever
@@ -85,6 +102,18 @@ export declare class AstSchemaEditor {
     private findProperty;
     private static quoteKey;
     private static isPlainObject;
+    /**
+     * The field that identifies each element of an array of objects, so an
+     * old element can be found again in the new array.
+     *
+     * Arrays travel whole (see `collection_patch.ts`), and an element's
+     * position is not its identity — adding an entity action at the front
+     * shifts every other one. `key`, `id`, `relationName`, `name`: the first
+     * one every new element carries, distinct, wins.
+     */
+    private static identityField;
+    /** The old array's object elements, keyed by `field`'s literal value. */
+    private oldElementsBy;
     private convertJsonToAstString;
     /**
      * Write only the keys the patch names, leaving every sibling alone.
@@ -95,7 +124,18 @@ export declare class AstSchemaEditor {
      * and kanban config in the same write.
      */
     private mergeIntoObjectLiteral;
+    /**
+     * Drop whatever a refused edit left in memory.
+     *
+     * One editor serves every request, and `project.save()` writes every file
+     * with unsaved changes. So an edit refused halfway through — a relation with
+     * no target, found after the name was already rewritten and an import
+     * added — reached the disk with the next save of some other collection, and
+     * a file refused as it was being created appeared anyway.
+     */
+    private forgetUnsaved;
     saveProperty(collectionId: string, propertyKey: string, propertyConfig: Record<string, unknown>): Promise<void>;
+    private writeProperty;
     deleteProperty(collectionId: string, propertyKey: string): Promise<void>;
     /**
      * Write a collection back to its file.
@@ -111,6 +151,69 @@ export declare class AstSchemaEditor {
     saveCollection(collectionId: string, collectionData: Record<string, unknown>, options?: {
         partial?: boolean;
     }): Promise<void>;
+    /**
+     * Write what changed about a collection, and nothing else.
+     *
+     * The patch is the difference between the collection the panel loaded and
+     * the one it is saving (`diffCollections` in `@rebasepro/types`), so it
+     * names only keys the person changed. Each is written where it is; every
+     * other byte of the file — imports, comments, formatting, handlers,
+     * properties shared from another module — is left as it was.
+     *
+     * A key whose value in the file is code — `status: statusProperty`,
+     * `enum: LOCALE_ENUM`, a spread — is not overwritten with the JSON the
+     * panel saw of it, which is what the whole-collection save did. The edit
+     * is refused, naming the code, so it can be made where that code lives.
+     *
+     * All or nothing: a refused operation leaves the file as it was, including
+     * the operations before it.
+     */
+    applyPatch(collectionId: string, patch: CollectionPatch): Promise<void>;
+    private writePatch;
+    private applyPatchOp;
+    /**
+     * A patched value with every relation target it carries turned back into
+     * source — `() => xCollection` plus its import — according to where the
+     * path lands: a relation's `target`, a relation, a property, or a map of
+     * properties.
+     */
+    private patchValueAsSource;
+    /** A member of an object literal by name: an assignment, a shorthand, a method. */
+    private findMember;
+    private spreadIn;
+    /** `x as const`, `x satisfies T`, `(x)` — the value inside. */
+    private static unwrapExpression;
+    /**
+     * Whether a value in the file is data the panel's JSON fully describes —
+     * a literal — rather than code it saw only the result of.
+     */
+    private static isLiteralValue;
+    /** "`properties.status` is `statusProperty` in posts.ts…" */
+    private codeRefusal;
+    private writeCollection;
+    /**
+     * Every property relation's `target`, as source.
+     *
+     * The collection-level `relations` array has {@link writeRelations}. A
+     * relation declared on a property went through `convertJsonToAstString`
+     * like any other value, so a target the property form had picked — a slug,
+     * which is all JSON can carry — was written as the string literal
+     * `target: "authors"`, and the next boot threw in `resolveRelation` for every
+     * collection in the directory. The same rule applies here as there: a slug
+     * becomes `() => xCollection` plus its import, an arrow returning one
+     * identifier is written through, and a relation sent without a target keeps
+     * the one already in the file — or is refused, when there is none.
+     *
+     * Walks into `map` properties, an array's `of` and a block's `oneOf`, which
+     * the registry resolves relations in too. `oldProperties` is the same
+     * properties object in the file, when there is one.
+     */
+    private relationTargetsAsSource;
+    private propertyRelationTargetsAsSource;
+    /** The initializer of `obj[key]` in the file, when it is written as a property assignment. */
+    private initializerOf;
+    /** `obj[key]` in the file, when it is an object literal. */
+    private objectAt;
     /**
      * Write the collection-level `relations` array.
      *
@@ -133,5 +236,28 @@ export declare class AstSchemaEditor {
     private targetThunk;
     private hasDefaultImport;
     private getDefaultExportName;
-    deleteCollection(collectionId: string): Promise<void>;
+    /**
+     * Delete a collection's file, and take it out of `index.ts`.
+     *
+     * This used to unlink `<slug>.ts` and stop. Every scaffold's `index.ts`
+     * imports every collection, so the next boot failed for the whole project
+     * ("Cannot find module …/tags"), and a collection another one linked to
+     * took that one down with it. Now:
+     *
+     * - a file any other module imports is refused, naming the importers — a
+     *   relation to it has to go first, and that is a change the person makes;
+     * - `index.ts`'s import of it is removed, and so is each place it is listed
+     *   in an array; any other use there is refused, naming the line;
+     * - the file is deleted.
+     *
+     * Only the source. The table and its rows are not touched.
+     *
+     * Returns what changed, as absolute paths, so the caller can commit it.
+     */
+    deleteCollection(collectionId: string): Promise<{
+        deleted: string;
+        changed: string[];
+    }>;
+    /** The import and export declarations in `file` whose relative specifier resolves to `targetPath`. */
+    private declarationsOf;
 }

package/dist/api/errors.d.ts

@@ -23,6 +23,15 @@ export declare function schemaDriftRemedy(): {
     short: string;
     lines: string[];
 };
+/**
+ * Did the database refuse a value as unreadable for its column's type —
+ * SQLSTATE class 22, anywhere down the cause chain?
+ *
+ * For a lookup by an id the caller supplied, that is an answer rather than a
+ * failure: `abc` against a UUID key names no row, exactly as a well-formed id
+ * nobody has does.
+ */
+export declare function isDataException(error: unknown): boolean;
 /**
  * Standardized API error class.
  * Throw this from any route handler — the errorHandler middleware

package/dist/api/live-schema-routes.d.ts

@@ -29,7 +29,7 @@
  * — `applySchemaChange` re-checks rather than trusting the plan it is handed.
  */
 import { Hono } from "hono";
-import { type CollectionConfig, type DatabaseAdmin, type SchemaCommitPaths } from "@rebasepro/types";
+import { type CollectionPatch, type CollectionConfig, type DatabaseAdmin, type SchemaCommitPaths } from "@rebasepro/types";
 import { HonoEnv } from "./types.js";
 import { type SchemaEditRepository } from "../schema-edit/apply-schema-change.js";
 import { type SchemaEditPolicy } from "../schema-edit/schema-edit-permissions.js";
@@ -87,8 +87,8 @@ export interface LiveSchemaRoutesConfig {
      *
      * Absent for a project that *is* the repository, which is what the defaults
      * describe. Present for one in a subdirectory, where the defaults would
-     * write `backend/` and `drizzle/` beside `.git` and leave the project's real
-     * generated files untouched — committing a source change alongside a stale
+     * write `backend/` beside `.git` and leave the project's real generated
+     * file untouched — committing a source change alongside a stale
      * schema, which is the failure committing the whole change exists to avoid.
      */
     commitPaths?: Partial<SchemaCommitPaths>;
@@ -97,8 +97,8 @@ export interface LiveSchemaRoutesConfig {
      * environment.
      *
      * If it does, applying here is not the whole job: the DDL runs against
-     * *this* database and `drizzle/schema.sql` is committed, but no migration
-     * is written — a server cannot mint one, since that needs Atlas and a
+     * *this* database and the collection is committed, but no migration is
+     * written — a server cannot mint one, since that needs Atlas and a
      * throwaway database. The next environment built by replaying migrations
      * would not have this change, and nothing would have said so.
      */
@@ -111,11 +111,31 @@ export interface LiveSchemaRoutesConfig {
      */
     policy?: SchemaEditPolicy;
 }
-/** What the panel posts: one collection, in the shape it should end up. */
+/**
+ * What the panel posts about one collection.
+ *
+ * For a collection that exists, a `patch`: what the person changed, as the
+ * difference between the JSON the editor loaded and the JSON it is saving (see
+ * `collection_patch.ts` in `@rebasepro/types`). The whole collection travelled
+ * here once, and the write rewrote every key it carried and deleted whatever
+ * JSON had dropped — handlers, shared properties, imported enums, comments.
+ *
+ * For a collection that does not exist yet, the whole `collection`. A caller
+ * that sends a whole collection for one that exists has it turned into the
+ * patch of what differs (see {@link asPatch}).
+ */
 export interface ProposedChange {
     collectionId: string;
-    /** The whole collection as it should be after the edit. */
-    collection: Record<string, unknown>;
+    /** The whole collection — only for one that does not exist yet. */
+    collection?: Record<string, unknown>;
+    /** What changed about an existing collection. */
+    patch?: CollectionPatch;
+    /**
+     * Delete the collection's source: its file, and its entry in `index.ts`.
+     * Planned like any change — the table and its rows stay, and say so — and
+     * committed source-only.
+     */
+    remove?: true;
 }
 /**
  * The git identity for the caller.
@@ -128,9 +148,33 @@ export declare function commitAuthor(user: unknown): {
     name: string;
     email: string;
 } | undefined;
+/**
+ * The change as a patch against the collection as it is.
+ *
+ * A whole collection posted for one that exists is the difference from the
+ * current one: a caller that sends JSON cannot then delete what JSON could not
+ * carry. A key it left out is removed only when its value is pure data — a
+ * key holding code (`callbacks`, a handler, a component) is not something a
+ * JSON caller could have meant to drop.
+ */
+export declare function asPatch(existing: CollectionConfig, change: ProposedChange): CollectionPatch;
 /**
  * The proposed collection set: everything as it is, with one collection
  * replaced or added.
+ *
+ * The replacement arrives as JSON, and a relation's `target` is a thunk —
+ * `JSON.stringify` drops it, so every relation the panel did not touch comes
+ * back with no target, and one picked in the property form names its target by
+ * slug. The planner calls `target()` on every relation in the set, so as it
+ * arrived it threw on the first one, and no change of any kind could be planned
+ * for a collection that had a relation.
+ *
+ * So each target is made callable again, the way the AST editor makes it
+ * source again when it writes the file: a slug becomes a lookup in the
+ * proposed set — so a link to the collection being edited reaches its new
+ * version — and a missing target is the one the same relation has now. A
+ * target that is neither is refused here, as the caller's mistake, rather than
+ * thrown from inside the planner as a 500.
  */
 export declare function proposedCollections(current: CollectionConfig[], change: ProposedChange): CollectionConfig[];
 export declare function createLiveSchemaRoutes(config: LiveSchemaRoutesConfig): Hono<HonoEnv>;