sandcms 0.6.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +1 -1
  2. package/dist/cli/doctor.js +2 -2
  3. package/dist/cli/files.js +11 -6
  4. package/dist/cli/index.js +1 -1
  5. package/dist/cli/upgrade.js +2 -1
  6. package/dist/env.d.ts +80 -0
  7. package/dist/env.js +103 -0
  8. package/dist/server/admin-load.d.ts +46 -76
  9. package/dist/server/admin-load.js +98 -24
  10. package/dist/server/api-pagination.d.ts +2 -0
  11. package/dist/server/api-pagination.js +51 -7
  12. package/dist/server/cms.d.ts +17 -2
  13. package/dist/server/cms.js +3 -1
  14. package/dist/server/content.d.ts +15 -2
  15. package/dist/server/content.js +72 -30
  16. package/dist/server/db/migration-data.js +8 -0
  17. package/dist/server/db/migrations/0007_content_and_job_indexes.sql +2 -0
  18. package/dist/server/db/migrations/0008_search_text_cache.sql +45 -0
  19. package/dist/server/db/migrations/meta/0007_snapshot.json +1643 -0
  20. package/dist/server/db/migrations/meta/0008_snapshot.json +1711 -0
  21. package/dist/server/db/migrations/meta/_journal.json +14 -0
  22. package/dist/server/db/schema.d.ts +83 -0
  23. package/dist/server/db/schema.js +23 -5
  24. package/dist/server/email/index.d.ts +5 -1
  25. package/dist/server/email/index.js +12 -11
  26. package/dist/server/media/runner.js +217 -191
  27. package/dist/server/media/service.d.ts +6 -0
  28. package/dist/server/media/service.js +36 -3
  29. package/dist/server/search.d.ts +2 -0
  30. package/dist/server/search.js +7 -0
  31. package/dist/worker/index.js +129 -76
  32. package/docs/cloudflare.md +1 -1
  33. package/docs/deployment.md +15 -1
  34. package/docs/email.md +5 -5
  35. package/docs/media.md +2 -2
  36. package/docs/package.md +4 -4
  37. package/docs/releases.md +10 -0
  38. package/docs/upgrades.md +31 -1
  39. package/package.json +5 -1
  40. package/templates/env.ts +8 -0
  41. package/templates/integration.ts +5 -5
@@ -2,7 +2,7 @@ import { isFocusPoint } from '../blueprints/files.js';
2
2
  import { sanitizeSvg, svgDimensions } from './svg.js';
3
3
  import { sourceURL, validSource } from './source.js';
4
4
  import { presignUpload, uploadInput } from './uploads.js';
5
- const PROTOCOL = 5;
5
+ const PROTOCOL = 6;
6
6
  const json = (v, status = 200) => Response.json(v, { status, headers: { 'Cache-Control': 'private, no-store' } });
7
7
  const idPattern = /^[a-f0-9-]{36}$/;
8
8
  const variantPattern = /^([a-f0-9-]{36})\/([a-f0-9]{16})\/([a-z][a-z0-9_-]*)-(\d+)\.(webp|avif|jpeg|svg)$/;
@@ -107,6 +107,106 @@ async function inspect(source) {
107
107
  dimensions(info?.original?.width, info?.original?.height);
108
108
  return dimensions(info?.width, info?.height);
109
109
  }
110
+ // Workers allow six concurrent connections; each variant needs R2 reads/writes plus a transform.
111
+ const maxBatch = 32, batchConcurrency = 4;
112
+ const validSpec = (spec) => !!spec &&
113
+ typeof spec === 'object' &&
114
+ (spec.aspectRatio === undefined ||
115
+ (typeof spec.aspectRatio === 'number' &&
116
+ Number.isFinite(spec.aspectRatio) &&
117
+ spec.aspectRatio >= 0.01 &&
118
+ spec.aspectRatio <= 100)) &&
119
+ (spec.focus === undefined || isFocusPoint(spec.focus)) &&
120
+ /^([a-z][a-z0-9_-]*)$/.test(spec.preset) &&
121
+ Number.isInteger(spec.size) &&
122
+ spec.size >= 1 &&
123
+ spec.size <= 8192 &&
124
+ ['webp', 'avif', 'jpeg', 'svg'].includes(spec.format) &&
125
+ Number.isInteger(spec.quality) &&
126
+ spec.quality >= 1 &&
127
+ spec.quality <= 100;
128
+ async function mapLimit(items, limit, run) {
129
+ const results = new Array(items.length);
130
+ let next = 0;
131
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
132
+ while (next < items.length) {
133
+ const index = next++;
134
+ results[index] = await run(items[index]);
135
+ }
136
+ }));
137
+ return results;
138
+ }
139
+ async function variantSource(env, origin, id) {
140
+ const original = await env.MEDIA.head('originals/' + id);
141
+ if (!original)
142
+ return null;
143
+ if (original.httpMetadata?.contentType === 'image/svg+xml') {
144
+ const object = await env.MEDIA.get('originals/' + id);
145
+ if (!object)
146
+ return null;
147
+ return { svg: sanitizeSvg(await object.text()) };
148
+ }
149
+ // Older originals have no saved dimensions; inspect them remotely on rebuild.
150
+ const metadata = original.customMetadata;
151
+ return metadata?.width && metadata?.height
152
+ ? dimensions(Number(metadata.width), Number(metadata.height))
153
+ : inspect(await sourceURL(origin, id, env.SANDCMS_WORKER_TOKEN));
154
+ }
155
+ // Returns null when the original is missing so callers can report a non-retryable upload error.
156
+ async function renderVariant(env, origin, id, version, spec, load) {
157
+ const key = `${id}/${version}/${spec.preset}-${spec.size}.${spec.format}`;
158
+ const existing = await env.MEDIA.head('variants/' + key);
159
+ if (existing?.customMetadata?.ready === 'true')
160
+ return JSON.parse(existing.customMetadata.result);
161
+ const info = await load();
162
+ if (!info)
163
+ return null;
164
+ let output, width, height;
165
+ if ('svg' in info) {
166
+ if (spec.format !== 'svg')
167
+ throw new Error('SVG requires a sanitized derivative');
168
+ output = new Response(info.svg, { headers: { 'Content-Type': 'image/svg+xml' } });
169
+ ({ width, height } = svgDimensions(info.svg));
170
+ }
171
+ else {
172
+ if (spec.format === 'svg')
173
+ throw new Error('Raster input cannot become SVG');
174
+ const scale = Math.min(1, spec.size / Math.max(info.width, info.height));
175
+ width = Math.max(1, Math.round(info.width * scale));
176
+ height = Math.max(1, Math.round(info.height * scale));
177
+ if (spec.aspectRatio) {
178
+ const targetWidth = Math.max(1, Math.round(spec.size * Math.min(1, spec.aspectRatio)));
179
+ const targetHeight = Math.max(1, Math.round(spec.size / Math.max(1, spec.aspectRatio)));
180
+ const cropScale = Math.min(1, info.width / targetWidth, info.height / targetHeight);
181
+ width = Math.max(1, Math.round(targetWidth * cropScale));
182
+ height = Math.max(1, Math.round(targetHeight * cropScale));
183
+ }
184
+ // Sign per variant: a five-minute capability must not expire partway through a batch.
185
+ output = await transform(await sourceURL(origin, id, env.SANDCMS_WORKER_TOKEN), {
186
+ width,
187
+ height,
188
+ fit: spec.aspectRatio ? 'cover' : 'scale-down',
189
+ ...(spec.aspectRatio && spec.focus ? { gravity: spec.focus } : {}),
190
+ format: spec.format,
191
+ quality: spec.quality
192
+ }, `image/${spec.format}`);
193
+ }
194
+ const result = {
195
+ key,
196
+ preset: spec.preset,
197
+ size: spec.size,
198
+ width,
199
+ height,
200
+ format: spec.format
201
+ };
202
+ // R2 requires a known stream length; the Images result may be streamed without one.
203
+ const bytes = await boundedBody(output, 20_000_000);
204
+ await putAsset(env, id, 'variants/' + key, bytes, {
205
+ httpMetadata: { contentType: output.headers.get('content-type') },
206
+ customMetadata: { ready: 'true', result: JSON.stringify(result) }
207
+ });
208
+ return result;
209
+ }
110
210
  export default {
111
211
  async fetch(request, env) {
112
212
  const url = new URL(request.url), path = url.pathname;
@@ -147,11 +247,11 @@ export default {
147
247
  return new Response('Not found', { status: 404, headers: { 'Cache-Control': 'no-store' } });
148
248
  if (path === '/internal/health')
149
249
  return json({ protocol: PROTOCOL });
150
- if (!['3', '4', String(PROTOCOL)].includes(request.headers.get('x-sandcms-protocol') ?? ''))
250
+ if (!['3', '4', '5', String(PROTOCOL)].includes(request.headers.get('x-sandcms-protocol') ?? ''))
151
251
  return json({ error: 'Incompatible CMS media protocol' }, 409);
152
252
  const uploadMatch = /^\/internal\/uploads\/([a-f0-9-]{36})\/(sign|complete)$/.exec(path);
153
253
  if (uploadMatch && request.method === 'POST') {
154
- if (!['4', String(PROTOCOL)].includes(request.headers.get('x-sandcms-protocol') ?? ''))
254
+ if (!['4', '5', String(PROTOCOL)].includes(request.headers.get('x-sandcms-protocol') ?? ''))
155
255
  return json({ error: 'Direct uploads require media protocol 4' }, 409);
156
256
  const id = uploadMatch[1];
157
257
  if (await isDeleted(env, id))
@@ -252,7 +352,7 @@ export default {
252
352
  await object.body.cancel();
253
353
  return new Response(request.method === 'HEAD' ? null : object.body, { headers });
254
354
  }
255
- const match = /^\/internal\/assets\/([^/]+)(?:\/(variant))?$/.exec(path);
355
+ const match = /^\/internal\/assets\/([^/]+)(?:\/(variants?))?$/.exec(path);
256
356
  if (!match || !idPattern.test(match[1]))
257
357
  return json({ error: 'Invalid asset' }, 400);
258
358
  const id = match[1];
@@ -306,82 +406,35 @@ export default {
306
406
  if (request.method === 'POST' && match[2]) {
307
407
  if (await isDeleted(env, id))
308
408
  throw new Error('Asset has been deleted');
309
- const body = JSON.parse(new TextDecoder().decode(await boundedBody(request, 4096)));
310
- if ((body.aspectRatio !== undefined &&
311
- (typeof body.aspectRatio !== 'number' ||
312
- !Number.isFinite(body.aspectRatio) ||
313
- body.aspectRatio < 0.01 ||
314
- body.aspectRatio > 100)) ||
315
- (body.focus !== undefined && !isFocusPoint(body.focus)) ||
316
- !/^[a-f0-9]{16}$/.test(body.version) ||
317
- !/^([a-z][a-z0-9_-]*)$/.test(body.preset) ||
318
- !Number.isInteger(body.size) ||
319
- body.size < 1 ||
320
- body.size > 8192 ||
321
- !['webp', 'avif', 'jpeg', 'svg'].includes(body.format) ||
322
- !Number.isInteger(body.quality) ||
323
- body.quality < 1 ||
324
- body.quality > 100)
409
+ const batch = match[2] === 'variants';
410
+ const body = JSON.parse(new TextDecoder().decode(await boundedBody(request, batch ? 65_536 : 4096)));
411
+ const specs = batch ? body.variants : [body];
412
+ if (!/^[a-f0-9]{16}$/.test(body.version) ||
413
+ !Array.isArray(specs) ||
414
+ specs.length < 1 ||
415
+ specs.length > maxBatch ||
416
+ !specs.every(validSpec))
325
417
  throw new Error('Invalid variant request');
326
- const key = `${id}/${body.version}/${body.preset}-${body.size}.${body.format}`;
327
- const existing = await env.MEDIA.head('variants/' + key);
328
- if (existing?.customMetadata?.ready === 'true')
329
- return json(JSON.parse(existing.customMetadata.result));
330
- const original = await env.MEDIA.get('originals/' + id);
331
- if (!original)
332
- return json({ error: 'Original missing; upload again' }, 404);
333
- let output, width, height;
334
- if (original.httpMetadata?.contentType === 'image/svg+xml') {
335
- if (body.format !== 'svg')
336
- throw new Error('SVG requires a sanitized derivative');
337
- const svg = sanitizeSvg(await original.text());
338
- output = new Response(svg, { headers: { 'Content-Type': 'image/svg+xml' } });
339
- ({ width, height } = svgDimensions(svg));
418
+ let source;
419
+ // Read the original once per request; every variant shares its type and dimensions.
420
+ const load = () => (source ??= variantSource(env, url.origin, id));
421
+ if (!batch) {
422
+ const result = await renderVariant(env, url.origin, id, body.version, specs[0], load);
423
+ return result ? json(result) : json({ error: 'Original missing; upload again' }, 404);
340
424
  }
341
- else {
342
- if (body.format === 'svg')
343
- throw new Error('Raster input cannot become SVG');
344
- await original.body.cancel();
345
- const source = await sourceURL(url.origin, id, env.SANDCMS_WORKER_TOKEN);
346
- // Older originals have no saved dimensions; inspect them remotely on rebuild.
347
- const metadata = original.customMetadata;
348
- const info = metadata?.width && metadata?.height
349
- ? dimensions(Number(metadata.width), Number(metadata.height))
350
- : await inspect(source);
351
- const scale = Math.min(1, body.size / Math.max(info.width, info.height));
352
- width = Math.max(1, Math.round(info.width * scale));
353
- height = Math.max(1, Math.round(info.height * scale));
354
- if (body.aspectRatio) {
355
- const targetWidth = Math.max(1, Math.round(body.size * Math.min(1, body.aspectRatio)));
356
- const targetHeight = Math.max(1, Math.round(body.size / Math.max(1, body.aspectRatio)));
357
- const cropScale = Math.min(1, info.width / targetWidth, info.height / targetHeight);
358
- width = Math.max(1, Math.round(targetWidth * cropScale));
359
- height = Math.max(1, Math.round(targetHeight * cropScale));
425
+ // Each variant fails independently so one bad encode does not retry the whole set.
426
+ const results = await mapLimit(specs, batchConcurrency, async (spec) => {
427
+ try {
428
+ const variant = await renderVariant(env, url.origin, id, body.version, spec, load);
429
+ return variant ? { variant } : null;
430
+ }
431
+ catch (e) {
432
+ return { error: e instanceof Error ? e.message : 'Media processing failed' };
360
433
  }
361
- output = await transform(source, {
362
- width,
363
- height,
364
- fit: body.aspectRatio ? 'cover' : 'scale-down',
365
- ...(body.aspectRatio && body.focus ? { gravity: body.focus } : {}),
366
- format: body.format,
367
- quality: body.quality
368
- }, `image/${body.format}`);
369
- }
370
- const result = {
371
- key,
372
- preset: body.preset,
373
- size: body.size,
374
- width,
375
- height,
376
- format: body.format
377
- };
378
- // R2 requires a known stream length; the Images result may be streamed without one.
379
- const bytes = await boundedBody(output, 20_000_000);
380
- await putAsset(env, id, 'variants/' + key, bytes, {
381
- httpMetadata: { contentType: output.headers.get('content-type') },
382
- customMetadata: { ready: 'true', result: JSON.stringify(result) }
383
434
  });
384
- return json(result);
435
+ if (results.includes(null))
436
+ return json({ error: 'Original missing; upload again' }, 404);
437
+ return json({ results });
385
438
  }
386
439
  if (request.method === 'DELETE' && !match[2]) {
387
440
  // Keep the small marker so late requests can never recreate this asset ID.
@@ -68,7 +68,7 @@ bun x --no-install sandcms worker update
68
68
  bun x --no-install sandcms doctor
69
69
  ```
70
70
 
71
- Worker updates verify recorded resource ownership. The current CMS/Worker protocol is **5**. The Worker also accepts protocols 3 and 4 for existing website processes and legacy BLOB transfers, allowing the Worker to be deployed first. Direct uploads require protocol 4 or 5. Focal-point crops require the protocol-5 Worker. Configure signing credentials, CORS and lifecycle cleanup, deploy the Worker, then migrate the database and deploy the website. The retained incremental migration adds `upload_sessions` without changing old media or pending BLOBs; follow the [upgrade workflow](upgrades.md).
71
+ Worker updates verify recorded resource ownership. The current CMS/Worker protocol is **6**. The Worker also accepts protocols 3, 4 and 5 for existing website processes and legacy BLOB transfers, allowing the Worker to be deployed first. Direct uploads require protocol 4 or later. Focal-point crops require protocol 5 or later, and batched variant processing requires the protocol-6 Worker. Configure signing credentials, CORS and lifecycle cleanup, deploy the Worker, then migrate the database and deploy the website. The retained incremental migration adds `upload_sessions` without changing old media or pending BLOBs; follow the [upgrade workflow](upgrades.md).
72
72
 
73
73
  For deployments still using legacy public Worker `/media/*` URLs, deploy a protocol-3 Worker to close that route, update manually constructed URLs to the CMS routes, and purge old Worker URL caches. Legacy browser copies may have a one-year immutable lifetime and cannot be recalled. Confirm bucket public access is disabled before relying on draft privacy.
74
74
 
@@ -30,6 +30,20 @@ Rebuild and restart the website after this configuration change. It requires no
30
30
  - Set `PORT` to the host's assigned port. Route both the public website and `/admin` to this container.
31
31
  - Keep one application instance per database volume; the SQLite volume must support local filesystem locking. Do not use an object-store mount or an unproven network filesystem.
32
32
 
33
+ ### Environment validation
34
+
35
+ The generated `src/env.ts` declares every SandCMS variable with `sandcmsEnvVars({ building })` from `sandcms/env`, and the integration reads the validated values from `$app/env/private`. The website exits on start, before serving requests, when `SANDCMS_ORIGIN` or `SANDCMS_SECRET` is missing or any SandCMS variable is malformed:
36
+
37
+ ```text
38
+ SvelteKit error: env_invalid
39
+ Invalid environment variables:
40
+
41
+ SANDCMS_SECRET
42
+ - Must be at least 32 characters
43
+ ```
44
+
45
+ Configure a container health check (for example `GET /admin/login`) so that a deployment with a broken environment never replaces the running release. Builds skip the required checks, so secrets need not be present in the build environment. Values are all runtime (`static: false`); none are inlined into the bundle. `SANDCMS_WORKER_TOKEN` stays optional so local development works without Cloudflare media. Declare your own variables in the same `defineEnvVars` call; see [SvelteKit environment variables](https://svelte.dev/docs/kit/environment-variables).
46
+
33
47
  `.dockerignore` excludes local credentials, databases, local R2 state, and build/test artifacts from the build context. Do not create accounts during image builds. The adapter may report `bun:sqlite` as an external module during bundling; it is intentionally provided by Bun at runtime.
34
48
 
35
49
  ## Migrate and bootstrap the actual production volume
@@ -46,7 +60,7 @@ In this source repository's demo image, use `bun dist/cli/index.js` in place of
46
60
 
47
61
  ### Automatic migration on start
48
62
 
49
- Set `SANDCMS_AUTO_MIGRATE=true` to apply pending migrations when the website starts instead of running `sandcms migrate` separately. The generated integration passes it to `createCMS({ autoMigrate })`; customized integrations must add `autoMigrate: env.SANDCMS_AUTO_MIGRATE === 'true'` themselves. Before migrating an existing database, the website writes a verified snapshot to `<database>.before-migrate-<timestamp>-<id>.sqlite` beside it and logs its path; empty databases are initialized without a snapshot, and a non-empty database with no migration history is refused. Incompatible or modified histories are still rejected without changes, a failed migration rolls back and stops startup, and concurrent starts apply each migration once. Snapshots are not pruned automatically; remove them after verifying the upgrade. Auto-migration does not create accounts; still run `user bootstrap` on a fresh volume. Leave it unset to keep the explicit operator workflow.
63
+ Set `SANDCMS_AUTO_MIGRATE=true` to apply pending migrations when the website starts instead of running `sandcms migrate` separately. The generated integration passes it to `createCMS({ autoMigrate })`; customized integrations must add `autoMigrate: env.SANDCMS_AUTO_MIGRATE` themselves when reading `$app/env/private` (the value is already a boolean), or `autoMigrate: process.env.SANDCMS_AUTO_MIGRATE === 'true'` when still reading `process.env`. Before migrating an existing database, the website writes a verified snapshot to `<database>.before-migrate-<timestamp>-<id>.sqlite` beside it and logs its path; empty databases are initialized without a snapshot, and a non-empty database with no migration history is refused. Incompatible or modified histories are still rejected without changes, a failed migration rolls back and stops startup, and concurrent starts apply each migration once. Snapshots are not pruned automatically; remove them after verifying the upgrade. Auto-migration does not create accounts; still run `user bootstrap` on a fresh volume. Leave it unset to keep the explicit operator workflow.
50
64
 
51
65
  For a one-off Docker command, override Railpack's shell entrypoint with `--entrypoint bun`, then pass `dist/cli/index.js migrate` after the image name. Mount the same `/data` volume and supply runtime variables. See the [local container drill](acceptance.md) for the tested setup.
52
66
 
package/docs/email.md CHANGED
@@ -22,18 +22,18 @@ Port 587 requires STARTTLS. Port 465 requires immediate TLS (`SANDCMS_SMTP_SECUR
22
22
 
23
23
  For Hetzner Cloud, use the port 587 STARTTLS configuration above. Hetzner blocks outbound ports 25 and 465 by default; port 587 is available for external mail delivery services without an unblock request. See the [Hetzner FAQ](https://docs.hetzner.com/cloud/servers/faq/#why-can-i-not-send-any-mails-from-my-server). A timeout can also indicate an incorrect host, firewall, or provider outage; it does not identify a specific hosting restriction. Port 465 remains supported where outbound access is available.
24
24
 
25
- Email is disabled when all email variables are absent or empty. `cms.email.enabled` reports configuration availability, not server connectivity. Partial or invalid configuration fails when the CMS is created; an unreachable provider fails only when sending. Startup does not contact the SMTP server.
25
+ Email is disabled when all email variables are absent or empty. `cms.email.enabled` reports configuration availability, not server connectivity. Malformed ports and booleans stop the website at startup through [environment validation](deployment.md#environment-validation); other partial or invalid configuration fails when the CMS is created; an unreachable provider fails only when sending. Startup does not contact the SMTP server.
26
26
 
27
27
  The generated integration and repository demo read these variables. For an existing customized integration, add the option yourself:
28
28
 
29
29
  ```ts
30
30
  import { createCMS, emailOptionsFromEnv } from 'sandcms/server';
31
- const env = process.env;
31
+ import * as env from '$app/env/private';
32
32
 
33
33
  const cms = createCMS({
34
- database: env.SANDCMS_DATABASE!,
35
- origin: env.SANDCMS_ORIGIN!,
36
- secret: env.SANDCMS_SECRET!,
34
+ database: env.SANDCMS_DATABASE,
35
+ origin: env.SANDCMS_ORIGIN,
36
+ secret: env.SANDCMS_SECRET,
37
37
  email: emailOptionsFromEnv(env)
38
38
  });
39
39
  ```
package/docs/media.md CHANGED
@@ -47,7 +47,7 @@ card:
47
47
 
48
48
  Crops use [Cloudflare gravity coordinates](https://developers.cloudflare.com/images/optimization/features/#gravity--g). Presets without `aspectRatio` preserve the full image. Focus changes automatically queue new immutable variant keys when cropping is configured; current variants stay available until the complete new set is ready. Unrelated metadata edits do not rebuild images. The reserved `sandcms-preview` preset supplies an uncropped WebP for the picker on raster files with a focus field.
49
49
 
50
- Existing project-owned blueprints/configuration are preserved during upgrades: add the field and ratio explicitly, deploy the protocol-5 Worker first with `sandcms worker update`, then deploy the website and run `sandcms media rebuild` to prepare existing files and previews. Protocol 5 accepts older protocol-3/4 website requests; new website processes reject older Workers. No database migration is required.
50
+ Existing project-owned blueprints/configuration are preserved during upgrades: add the field and ratio explicitly, deploy the current Worker first with `sandcms worker update`, then deploy the website and run `sandcms media rebuild` to prepare existing files and previews. The protocol-6 Worker accepts older protocol-3/4/5 website requests; new website processes reject older Workers. No database migration is required.
51
51
 
52
52
  ## Privacy and publication
53
53
 
@@ -113,7 +113,7 @@ and adds no styling or admin dependencies. Consumers control layout with their o
113
113
 
114
114
  ## Processing and rebuild
115
115
 
116
- The authenticated CMS initializes a metadata-only upload session and returns a 15-minute S3 presigned PUT URL for a private `incoming/<asset>/<attempt>` object. The browser sends the file directly to R2, then calls the idempotent completion endpoint. A durable job verifies the actual object size and MIME type, validates a separate private snapshot (or sanitizes SVG), and conditionally creates the original before queuing variants. Reusing the PUT URL cannot overwrite an accepted original. New uploads never enter SQLite as BLOBs. Existing BLOB uploads from older releases continue through the legacy runner and are removed after successful transfer. Interrupted browser transfers require the file to be sent again. Unfinished sessions expire after 15 minutes; the runner deletes their staging objects and marks the asset failed. Finalization failures retain staging for retries. Configure a one-day `incoming/` lifecycle rule to remove abandoned objects, including objects recreated using an unexpired PUT URL. Completion retries do not transfer the file again. Jobs have durable attempts, bounded leases, retry delays, and failure state. Restarting the website resumes pending/expired jobs. The media library shows processing/ready/failed and permits retries. An asset's old active set remains available throughout a rebuild.
116
+ The authenticated CMS initializes a metadata-only upload session and returns a 15-minute S3 presigned PUT URL for a private `incoming/<asset>/<attempt>` object. The browser sends the file directly to R2, then calls the idempotent completion endpoint. A durable job verifies the actual object size and MIME type, validates a separate private snapshot (or sanitizes SVG), and conditionally creates the original before queuing variants. Reusing the PUT URL cannot overwrite an accepted original. New uploads never enter SQLite as BLOBs. Existing BLOB uploads from older releases continue through the legacy runner and are removed after successful transfer. Interrupted browser transfers require the file to be sent again. Unfinished sessions expire after 15 minutes; the runner deletes their staging objects and marks the asset failed. Finalization failures retain staging for retries. Configure a one-day `incoming/` lifecycle rule to remove abandoned objects, including objects recreated using an unexpired PUT URL. Completion retries do not transfer the file again. Variant jobs for the same image are claimed together and encoded in one Worker request, up to 16 per request and four concurrently inside the Worker. Each variant reports success or failure separately, so only failed variants retry. The website runs up to four images in parallel and continues immediately while work remains. Jobs have durable attempts, bounded leases, retry delays, and failure state. Restarting the website resumes pending/expired jobs. The media library shows processing/ready/failed and permits retries. An asset's old active set remains available throughout a rebuild.
117
117
 
118
118
  ```sh
119
119
  bun x --no-install sandcms media rebuild
package/docs/package.md CHANGED
@@ -17,13 +17,13 @@ npm pack --dry-run
17
17
  npm pack --pack-destination /tmp
18
18
  ```
19
19
 
20
- This release produces `/tmp/sandcms-0.6.1.tgz`. `npm pack` builds the package through `prepack`; it packages only the allowlisted distribution, templates, documentation, and package metadata. The repository's example website, tests, databases, and environment files are excluded. `release:check` checks types, runs unit tests, inspects an npm archive, and installs/builds that archive in both a fresh starter and an existing SvelteKit site.
20
+ This release produces `/tmp/sandcms-0.6.2.tgz`. `npm pack` builds the package through `prepack`; it packages only the allowlisted distribution, templates, documentation, and package metadata. The repository's example website, tests, databases, and environment files are excluded. `release:check` checks types, runs unit tests, inspects an npm archive, and installs/builds that archive in both a fresh starter and an existing SvelteKit site.
21
21
 
22
22
  Upload the archive you just built:
23
23
 
24
24
  ```sh
25
- npm publish /tmp/sandcms-0.6.1.tgz --access restricted --registry=https://registry.npmjs.org/
26
- npm view sandcms@0.6.1 version --registry=https://registry.npmjs.org/
25
+ npm publish /tmp/sandcms-0.6.2.tgz --access restricted --registry=https://registry.npmjs.org/
26
+ npm view sandcms@0.6.2 version --registry=https://registry.npmjs.org/
27
27
  ```
28
28
 
29
29
  Complete npm's authentication/2FA prompts. The logged-in account must have publishing permission in `sandquist-group`. The package also defaults to restricted access and the npmjs registry in `publishConfig`. Do not set `private: true` on this package: that prevents publication entirely. Generated websites do set it.
@@ -36,7 +36,7 @@ After publishing, authenticate as a user with read access to the package, then r
36
36
 
37
37
  ```sh
38
38
  npm login --registry=https://registry.npmjs.org/
39
- bunx --bun --package sandcms@0.6.1 sandcms setup --cwd ./my-site
39
+ bunx --bun --package sandcms@0.6.2 sandcms setup --cwd ./my-site
40
40
  cd my-site
41
41
  bun run dev
42
42
  ```
package/docs/releases.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Release notes
2
2
 
3
+ ## 0.6.2
4
+
5
+ This patch release speeds up media processing and the admin, and validates the website environment on start. Before upgrading from 0.6.1, check every environment's SandCMS variables, deploy the protocol-6 Worker with `sandcms worker update`, then apply retained migrations `0007` and `0008` before restarting the website; see the [0.6.2 upgrade checklist](upgrades.md#062-upgrade-checklist). Stored data and project-owned YAML are preserved.
6
+
7
+ Speeds up admin search, the dashboard, relation labels, media usages and reference validation by computing them in SQL instead of loading every document. Search pre-filters in SQL and caches each entry's and file's searchable text, which triggers clear when the source changes; the cache is also cleared on start so blueprint label changes take effect. Apply the retained `0007_content_and_job_indexes.sql` and `0008_search_text_cache.sql` migrations before restarting the website. They add indexes, nullable search-text columns and a media-to-document link table backfilled from existing media metadata, without changing existing accounts, content or media. See [faster admin queries](upgrades.md#faster-admin-queries).
8
+
9
+ Speeds up media processing. Each image now encodes up to 16 variants per Worker request (up to four at a time inside the Worker). The website also processes up to four images in parallel and continues straight to the next item instead of waiting a second between jobs. A failed variant retries on its own without re-encoding the rest of the set. The Worker protocol is now **6**. Deploy the Worker with `sandcms worker update` before the website; it still accepts protocol 3–5 website processes. This change needs no SQL migration, and stored media and project-owned YAML are unchanged. See [batched media processing](upgrades.md#batched-media-processing).
10
+
11
+ Adds startup environment validation with SvelteKit 3 explicit environment variables. Setup generates `src/env.ts` using the new `sandcmsEnvVars()` helper from `sandcms/env`, and the generated integration reads validated values from `$app/env/private`. A missing `SANDCMS_ORIGIN` or `SANDCMS_SECRET`, or a malformed SandCMS variable, now stops the website on start, so health-checked deployments do not go live with a broken environment. Builds do not require runtime secrets. Existing `src/env.ts` files are preserved; merge the helper as described in [validated environment variables](upgrades.md#validated-environment-variables). No SQL migration is required.
12
+
3
13
  ## 0.6.1
4
14
 
5
15
  This patch release renames the media Worker secrets and adds opt-in automatic migration on start. Before upgrading from 0.6.0, set the new `SANDCMS_`-prefixed Worker secrets, then deploy the Worker with `sandcms worker update`; see the [0.6.1 upgrade checklist](upgrades.md#061-upgrade-checklist). There is no new SQL migration, and website environment variables, stored data and project-owned YAML are unchanged.
package/docs/upgrades.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Updates and generated files
2
2
 
3
+ ## 0.6.2 upgrade checklist
4
+
5
+ Version 0.6.2 includes retained database migrations `0007` and `0008`. Follow this order when upgrading from 0.6.1:
6
+
7
+ 1. Check `SANDCMS_ORIGIN`, `SANDCMS_SECRET` and the boolean SandCMS variables in every environment, as described in [validated environment variables](#validated-environment-variables).
8
+ 2. Stop website and job processes and take a verified backup with the installed package.
9
+ 3. Install `sandcms@0.6.2`, review `sandcms upgrade --check`, then apply integration updates with `sandcms upgrade`. Merge `sandcmsEnvVars` into an existing `src/env.ts`.
10
+ 4. Deploy the protocol-6 Worker with `sandcms worker update`; see [batched media processing](#batched-media-processing).
11
+ 5. Review `sandcms migrate --check`, then run `sandcms migrate`, or let a website with `SANDCMS_AUTO_MIGRATE=true` apply them on start.
12
+ 6. Rebuild and restart the website. Verify sign-in, admin search, uploads and media processing on staging.
13
+
14
+ Upgrading from 0.6.0 still requires the [0.6.1 upgrade checklist](#061-upgrade-checklist) first.
15
+
16
+ ## Faster admin queries
17
+
18
+ Apply the retained `0007_content_and_job_indexes.sql` and `0008_search_text_cache.sql` migrations before restarting the updated website. `0007` adds indexes for media jobs and document references. `0008` adds nullable `searchText` columns to documents and media, a `media_document_links` table backfilled from existing media metadata, and triggers that keep both current. Existing accounts, content, media and project-owned YAML are unchanged, and no configuration change is required. The search cache fills lazily and is cleared on every start.
19
+
20
+ ## Batched media processing
21
+
22
+ The media Worker protocol is now **6**. It adds a batch variant endpoint and still accepts protocol 3, 4 and 5 website processes, so deploy the Worker with `sandcms worker update` before the website. Updated website processes reject older Workers, and `sandcms doctor` reports the mismatch. No SQL migration is required. Existing jobs, active variant sets and project-owned YAML are preserved. Pending jobs resume in batches after the restart.
23
+
24
+ ## Validated environment variables
25
+
26
+ The website now validates its environment on start and refuses to run with a missing or malformed SandCMS variable; see [environment validation](deployment.md#environment-validation). No SQL migration is required.
27
+
28
+ - `sandcms upgrade` creates `src/env.ts` and updates an unmodified `src/lib/server/sandcms/index.ts` to read from `$app/env/private`.
29
+ - If the project already has `src/env.ts` or `src/env.js`, it is preserved and the report shows the merge: import `sandcmsEnvVars` from `sandcms/env` and spread `...sandcmsEnvVars({ building })` into the existing `defineEnvVars` call. The updated integration does not build until this is merged.
30
+ - Customized integrations may keep reading `process.env`, or switch to `import * as env from '$app/env/private'` and pass the validated values (`autoMigrate: env.SANDCMS_AUTO_MIGRATE` is already a boolean).
31
+ - Check every environment before deploying: `SANDCMS_ORIGIN` and a 32-character `SANDCMS_SECRET` are now required at start, and `SANDCMS_AUTO_MIGRATE`, `SANDCMS_SMTP_SECURE` and `SANDCMS_SMTP_ALLOW_INSECURE_LOCAL` accept only `true` or `false`. Previously, other values silently meant `false`.
32
+
3
33
  ## 0.6.1 upgrade checklist
4
34
 
5
35
  Version 0.6.1 adds no SQL migration. Follow this order when upgrading from 0.6.0:
@@ -13,7 +43,7 @@ Upgrading from 0.5.x still requires the [0.6.0 upgrade checklist](#060-upgrade-c
13
43
 
14
44
  ## Automatic migration on start
15
45
 
16
- The website can apply pending migrations itself when `SANDCMS_AUTO_MIGRATE=true` is set. It first takes a verified snapshot of an existing database beside it, then runs the same per-migration transactional runner as `sandcms migrate`. Unmodified generated integrations receive the setting through `sandcms upgrade`; merge `autoMigrate: env.SANDCMS_AUTO_MIGRATE === 'true'` into customized `src/lib/server/sandcms/index.ts` files. No SQL migration or configuration change is required, and leaving the variable unset keeps the explicit workflow below. See [automatic migration](deployment.md#automatic-migration-on-start).
46
+ The website can apply pending migrations itself when `SANDCMS_AUTO_MIGRATE=true` is set. It first takes a verified snapshot of an existing database beside it, then runs the same per-migration transactional runner as `sandcms migrate`. Unmodified generated integrations receive the setting through `sandcms upgrade`; merge `autoMigrate: env.SANDCMS_AUTO_MIGRATE` into customized `src/lib/server/sandcms/index.ts` files that read `$app/env/private` (the value is already a boolean), or `autoMigrate: process.env.SANDCMS_AUTO_MIGRATE === 'true'` into files that still read `process.env`. No SQL migration or configuration change is required, and leaving the variable unset keeps the explicit workflow below. See [automatic migration](deployment.md#automatic-migration-on-start).
17
47
 
18
48
  ## 0.6.0 upgrade checklist
19
49
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sandcms",
3
- "version": "0.6.1",
3
+ "version": "0.6.2",
4
4
  "scripts": {
5
5
  "dev": "bun run styles && bun --bun vite dev",
6
6
  "build": "bun run validate && bun run styles && bun --bun vite build && bun run package",
@@ -52,6 +52,10 @@
52
52
  "svelte": "./dist/admin/index.js"
53
53
  },
54
54
  "./admin/styles.css": "./dist/admin/generated/admin.css",
55
+ "./env": {
56
+ "types": "./dist/env.d.ts",
57
+ "default": "./dist/env.js"
58
+ },
55
59
  "./worker": "./dist/worker/index.js",
56
60
  "./worker/local": {
57
61
  "default": "./dist/worker/local.js"
@@ -0,0 +1,8 @@
1
+ import { building } from '$app/env';
2
+ import { defineEnvVars } from '@sveltejs/kit/env';
3
+ import { sandcmsEnvVars } from 'sandcms/env';
4
+ // The app refuses to start when a required SandCMS variable is missing or invalid.
5
+ // Declare your own variables alongside: https://svelte.dev/docs/kit/environment-variables
6
+ export const variables = defineEnvVars({
7
+ ...sandcmsEnvVars({ building })
8
+ });
@@ -1,19 +1,19 @@
1
1
  import { createCMS, emailOptionsFromEnv, type CMS } from 'sandcms/server';
2
- const env = process.env;
2
+ import * as env from '$app/env/private';
3
3
  let instance: CMS;
4
4
  export function getCMS() {
5
5
  if (!instance) {
6
6
  instance = createCMS({
7
7
  // Enable CMS-owned SEO routes after mapping your public pages:
8
8
  // seo: { routes: { home: '/', projects: '/projects/{slug}' } },
9
- database: env.SANDCMS_DATABASE ?? './data/sandcms.sqlite',
10
- origin: env.SANDCMS_ORIGIN ?? 'http://localhost:5410',
11
- secret: env.SANDCMS_SECRET ?? '',
9
+ database: env.SANDCMS_DATABASE,
10
+ origin: env.SANDCMS_ORIGIN,
11
+ secret: env.SANDCMS_SECRET,
12
12
  email: emailOptionsFromEnv(env),
13
13
  workerToken: env.SANDCMS_WORKER_TOKEN,
14
14
  workerUrl: env.SANDCMS_WORKER_URL,
15
15
  trustedProxyHeader: env.SANDCMS_TRUSTED_PROXY_HEADER,
16
- autoMigrate: env.SANDCMS_AUTO_MIGRATE === 'true'
16
+ autoMigrate: env.SANDCMS_AUTO_MIGRATE
17
17
  });
18
18
  instance.media.start();
19
19
  }