sandcms 0.6.0 → 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 (51) hide show
  1. package/README.md +1 -1
  2. package/dist/cli/cloudflare.js +6 -6
  3. package/dist/cli/doctor.js +2 -2
  4. package/dist/cli/files.js +11 -6
  5. package/dist/cli/index.js +1 -1
  6. package/dist/cli/upgrade.js +2 -1
  7. package/dist/env.d.ts +80 -0
  8. package/dist/env.js +103 -0
  9. package/dist/server/admin-load.d.ts +46 -76
  10. package/dist/server/admin-load.js +98 -24
  11. package/dist/server/api-pagination.d.ts +2 -0
  12. package/dist/server/api-pagination.js +51 -7
  13. package/dist/server/cms.d.ts +19 -2
  14. package/dist/server/cms.js +13 -1
  15. package/dist/server/content.d.ts +15 -2
  16. package/dist/server/content.js +72 -30
  17. package/dist/server/db/auto-migrate.d.ts +12 -0
  18. package/dist/server/db/auto-migrate.js +23 -0
  19. package/dist/server/db/migration-data.js +8 -0
  20. package/dist/server/db/migrations/0007_content_and_job_indexes.sql +2 -0
  21. package/dist/server/db/migrations/0008_search_text_cache.sql +45 -0
  22. package/dist/server/db/migrations/meta/0007_snapshot.json +1643 -0
  23. package/dist/server/db/migrations/meta/0008_snapshot.json +1711 -0
  24. package/dist/server/db/migrations/meta/_journal.json +14 -0
  25. package/dist/server/db/schema.d.ts +83 -0
  26. package/dist/server/db/schema.js +23 -5
  27. package/dist/server/db/store.js +24 -9
  28. package/dist/server/email/index.d.ts +5 -1
  29. package/dist/server/email/index.js +12 -11
  30. package/dist/server/index.d.ts +1 -0
  31. package/dist/server/index.js +1 -0
  32. package/dist/server/media/runner.js +217 -191
  33. package/dist/server/media/service.d.ts +6 -0
  34. package/dist/server/media/service.js +36 -3
  35. package/dist/server/search.d.ts +2 -0
  36. package/dist/server/search.js +7 -0
  37. package/dist/worker/index.d.ts +1 -1
  38. package/dist/worker/index.js +134 -81
  39. package/dist/worker/local.js +5 -5
  40. package/dist/worker/uploads.d.ts +5 -5
  41. package/dist/worker/uploads.js +11 -9
  42. package/docs/cloudflare.md +7 -7
  43. package/docs/deployment.md +18 -0
  44. package/docs/email.md +5 -5
  45. package/docs/media.md +2 -2
  46. package/docs/package.md +4 -4
  47. package/docs/releases.md +18 -0
  48. package/docs/upgrades.md +66 -0
  49. package/package.json +5 -1
  50. package/templates/env.ts +8 -0
  51. package/templates/integration.ts +6 -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)$/;
@@ -19,10 +19,10 @@ async function putAsset(env, id, key, value, options) {
19
19
  return stored;
20
20
  }
21
21
  async function authenticated(request, env) {
22
- if (!env.CMS_TOKEN || env.CMS_TOKEN.length < 32)
22
+ if (!env.SANDCMS_WORKER_TOKEN || env.SANDCMS_WORKER_TOKEN.length < 32)
23
23
  return false;
24
24
  const got = request.headers.get('authorization') ?? '';
25
- const a = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(got))), b = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`Bearer ${env.CMS_TOKEN}`)));
25
+ const a = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(got))), b = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`Bearer ${env.SANDCMS_WORKER_TOKEN}`)));
26
26
  let diff = 0;
27
27
  for (let i = 0; i < a.length; i++)
28
28
  diff |= a[i] ^ b[i];
@@ -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;
@@ -117,7 +217,7 @@ export default {
117
217
  !idPattern.test(id) ||
118
218
  (staging !== undefined && !idPattern.test(staging)) ||
119
219
  extra.length > 0 ||
120
- !(await validSource(url, env.CMS_TOKEN)))
220
+ !(await validSource(url, env.SANDCMS_WORKER_TOKEN)))
121
221
  return new Response('Not found', {
122
222
  status: 404,
123
223
  headers: { 'Cache-Control': 'private, no-store' }
@@ -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))
@@ -196,7 +296,7 @@ export default {
196
296
  await env.MEDIA.put(validation, object.body, {
197
297
  httpMetadata: { contentType: input.mime }
198
298
  });
199
- const info = await inspect(await sourceURL(url.origin, id, env.CMS_TOKEN, validationAttempt));
299
+ const info = await inspect(await sourceURL(url.origin, id, env.SANDCMS_WORKER_TOKEN, validationAttempt));
200
300
  const validated = await env.MEDIA.get(validation);
201
301
  if (!validated)
202
302
  throw new Error('Upload snapshot missing');
@@ -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];
@@ -288,7 +388,7 @@ export default {
288
388
  });
289
389
  if (!stored || stored.size !== length)
290
390
  throw new Error('Upload length mismatch');
291
- const info = await inspect(await sourceURL(url.origin, id, env.CMS_TOKEN, attempt));
391
+ const info = await inspect(await sourceURL(url.origin, id, env.SANDCMS_WORKER_TOKEN, attempt));
292
392
  const validated = await env.MEDIA.get(staging);
293
393
  if (!validated)
294
394
  throw new Error('Upload missing');
@@ -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.CMS_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.
@@ -8,10 +8,10 @@ export default {
8
8
  return new Response('Local media Worker requires a loopback hostname', { status: 403 });
9
9
  const local = {
10
10
  ...env,
11
- R2_ENDPOINT: url.origin,
12
- R2_BUCKET_NAME: 'local-media',
13
- R2_ACCESS_KEY_ID: 'local-only',
14
- R2_SECRET_ACCESS_KEY: env.CMS_TOKEN
11
+ SANDCMS_R2_ENDPOINT: url.origin,
12
+ SANDCMS_R2_BUCKET_NAME: 'local-media',
13
+ SANDCMS_R2_ACCESS_KEY_ID: 'local-only',
14
+ SANDCMS_R2_SECRET_ACCESS_KEY: env.SANDCMS_WORKER_TOKEN
15
15
  };
16
16
  if (!url.pathname.startsWith('/local-media/'))
17
17
  return worker.fetch(request, local);
@@ -30,7 +30,7 @@ export default {
30
30
  const signature = url.searchParams.get('X-Amz-Signature');
31
31
  const expires = Number(url.searchParams.get('X-Amz-Expires'));
32
32
  const timestamp = Date.parse(date.replace(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/, '$1-$2-$3T$4:$5:$6Z'));
33
- if (!env.CMS_TOKEN ||
33
+ if (!env.SANDCMS_WORKER_TOKEN ||
34
34
  request.method !== 'PUT' ||
35
35
  !/^incoming\/[a-f0-9-]{36}\/[a-f0-9-]{36}$/.test(key) ||
36
36
  !Number.isFinite(timestamp) ||
@@ -1,10 +1,10 @@
1
1
  import { AwsClient } from 'aws4fetch';
2
2
  export interface UploadSigningEnv {
3
- R2_ACCOUNT_ID?: string;
4
- R2_BUCKET_NAME?: string;
5
- R2_ACCESS_KEY_ID?: string;
6
- R2_SECRET_ACCESS_KEY?: string;
7
- R2_ENDPOINT?: string;
3
+ SANDCMS_CF_ACCOUNT_ID?: string;
4
+ SANDCMS_R2_BUCKET_NAME?: string;
5
+ SANDCMS_R2_ACCESS_KEY_ID?: string;
6
+ SANDCMS_R2_SECRET_ACCESS_KEY?: string;
7
+ SANDCMS_R2_ENDPOINT?: string;
8
8
  }
9
9
  export declare const uploadLifetime = 900;
10
10
  export declare function uploadSigner(env: UploadSigningEnv): AwsClient;
@@ -1,23 +1,25 @@
1
1
  import { AwsClient } from 'aws4fetch';
2
2
  export const uploadLifetime = 900;
3
3
  export function uploadSigner(env) {
4
- if (!env.R2_ACCESS_KEY_ID || !env.R2_SECRET_ACCESS_KEY || !env.R2_BUCKET_NAME)
5
- throw new Error('Configure R2_BUCKET_NAME, R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY on the media Worker');
4
+ if (!env.SANDCMS_R2_ACCESS_KEY_ID ||
5
+ !env.SANDCMS_R2_SECRET_ACCESS_KEY ||
6
+ !env.SANDCMS_R2_BUCKET_NAME)
7
+ throw new Error('Configure SANDCMS_R2_BUCKET_NAME, SANDCMS_R2_ACCESS_KEY_ID and SANDCMS_R2_SECRET_ACCESS_KEY on the media Worker');
6
8
  return new AwsClient({
7
9
  service: 's3',
8
10
  region: 'auto',
9
- accessKeyId: env.R2_ACCESS_KEY_ID,
10
- secretAccessKey: env.R2_SECRET_ACCESS_KEY
11
+ accessKeyId: env.SANDCMS_R2_ACCESS_KEY_ID,
12
+ secretAccessKey: env.SANDCMS_R2_SECRET_ACCESS_KEY
11
13
  });
12
14
  }
13
15
  export async function presignUpload(env, key, mime) {
14
16
  const signer = uploadSigner(env);
15
- if (!env.R2_ENDPOINT && !env.R2_ACCOUNT_ID)
16
- throw new Error('Configure R2_ACCOUNT_ID on the media Worker');
17
- const endpoint = env.R2_ENDPOINT ?? `https://${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`;
18
- const url = new URL(`${endpoint.replace(/\/$/, '')}/${encodeURIComponent(env.R2_BUCKET_NAME)}/${key}`);
17
+ if (!env.SANDCMS_R2_ENDPOINT && !env.SANDCMS_CF_ACCOUNT_ID)
18
+ throw new Error('Configure SANDCMS_CF_ACCOUNT_ID on the media Worker');
19
+ const endpoint = env.SANDCMS_R2_ENDPOINT ?? `https://${env.SANDCMS_CF_ACCOUNT_ID}.r2.cloudflarestorage.com`;
20
+ const url = new URL(`${endpoint.replace(/\/$/, '')}/${encodeURIComponent(env.SANDCMS_R2_BUCKET_NAME)}/${key}`);
19
21
  if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
20
- throw new Error('R2_ENDPOINT must use HTTPS');
22
+ throw new Error('SANDCMS_R2_ENDPOINT must use HTTPS');
21
23
  url.searchParams.set('X-Amz-Expires', String(uploadLifetime));
22
24
  const signed = await signer.sign(url, {
23
25
  method: 'PUT',
@@ -7,7 +7,7 @@ Website proxy caching is optional and separate from Worker deployment. Public im
7
7
  ## Local development
8
8
 
9
9
  1. Generate a random secret of at least 32 characters.
10
- 2. Put the same value in ignored `.env.local` as `SANDCMS_WORKER_TOKEN` and ignored `sandcms/worker/.dev.vars` as `CMS_TOKEN`.
10
+ 2. Put the same value as `SANDCMS_WORKER_TOKEN` in both ignored `.env.local` and ignored `sandcms/worker/.dev.vars`.
11
11
  3. Use `http://localhost:8787` as `media.workerUrl` (the starter default).
12
12
  4. Run the local Worker, then restart the website:
13
13
 
@@ -25,7 +25,7 @@ Setup optionally uses the existing Wrangler login, asks for an account, displays
25
25
 
26
26
  - Keep R2 public access disabled, including `r2.dev`. Do not attach a public custom domain to the bucket.
27
27
  - Set `media.workerUrl` to the deployed Worker URL, or use the server-only `SANDCMS_WORKER_URL` environment override.
28
- - Supply the same secret as website `SANDCMS_WORKER_TOKEN` and Worker `CMS_TOKEN`.
28
+ - Supply the same secret as `SANDCMS_WORKER_TOKEN` to both the website and the Worker.
29
29
  - Use project-owned resources. The repository's `sandcms-local-media` name is a local example, not a production bucket to reuse.
30
30
 
31
31
  The `IMAGES` binding is no longer required: both dimension inspection (`format=json`) and encoding use remote transformations. Existing project-owned configurations may retain the unused binding. Ensure image transformations are enabled for the Worker’s account and that its own hostname is an allowed source. Cloudflare supports `cf.image` on Worker zones, including `workers.dev`. The Worker constructs source URLs from its request origin; use the deployed hostname for `media.workerUrl` and avoid redirects or rewrites on `/internal/source/*`.
@@ -38,11 +38,11 @@ The browser uploads to the R2 S3 API endpoint using a 15-minute presigned PUT UR
38
38
 
39
39
  Set these **Worker** secrets with `bun x wrangler secret put NAME --config sandcms/worker/wrangler.jsonc`:
40
40
 
41
- - `R2_ACCOUNT_ID`: the account containing the bucket.
42
- - `R2_BUCKET_NAME`: exactly the bucket bound as `MEDIA`.
43
- - `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`: an R2 S3 API token with Object Read & Write access restricted to that bucket. These are separate from Wrangler credentials and `CMS_TOKEN`; never put them in browser or website configuration.
41
+ - `SANDCMS_CF_ACCOUNT_ID`: the Cloudflare account containing the bucket.
42
+ - `SANDCMS_R2_BUCKET_NAME`: exactly the bucket bound as `MEDIA`.
43
+ - `SANDCMS_R2_ACCESS_KEY_ID` and `SANDCMS_R2_SECRET_ACCESS_KEY`: an R2 S3 API token with Object Read & Write access restricted to that bucket. These are separate from Wrangler credentials and `SANDCMS_WORKER_TOKEN`; never put them in browser or website configuration.
44
44
 
45
- For a jurisdiction-specific endpoint, set optional Worker `R2_ENDPOINT` to its HTTPS S3 endpoint. The endpoint and bucket must address the same bucket as `MEDIA`.
45
+ For a jurisdiction-specific endpoint, set optional Worker `SANDCMS_R2_ENDPOINT` to its HTTPS S3 endpoint. The endpoint and bucket must address the same bucket as `MEDIA`.
46
46
 
47
47
  Configure bucket CORS in R2 Settings for every authorized admin origin (merge with existing project-owned rules):
48
48
 
@@ -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
@@ -44,6 +58,10 @@ bun x --no-install sandcms user bootstrap --database /data/sandcms.sqlite --emai
44
58
 
45
59
  In this source repository's demo image, use `bun dist/cli/index.js` in place of `bun x --no-install sandcms`. From 0.5.0, apply retained incremental migrations to upgrade supported databases. Changed pre-0.5.0 baselines still require a fresh database. If retaining the old state, take a verified backup with the matching old package before updating. See [upgrade workflow](upgrades.md). The app refuses to start with pending or incompatible migrations. Each numbered migration runs transactionally. Bootstrap only works when the selected database has no users, generates a password, and prints it once. A local account does not create a production account.
46
60
 
61
+ ### Automatic migration on start
62
+
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.
64
+
47
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.
48
66
 
49
67
  A new user added later must have an operator/admin-supplied password. The CLI prompts without echo; automation may use `--password-stdin`. Both paths require a change at first login. Password and 2FA recovery invalidate sessions and write audit metadata:
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.0.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.0.tgz --access restricted --registry=https://registry.npmjs.org/
26
- npm view sandcms@0.6.0 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.0 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,23 @@
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
+
13
+ ## 0.6.1
14
+
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.
16
+
17
+ **Breaking:** Worker secrets now use the `SANDCMS_` prefix. `CMS_TOKEN` is renamed to `SANDCMS_WORKER_TOKEN`, matching the website variable that holds the same value, and the direct-upload secrets `R2_ACCOUNT_ID`, `R2_BUCKET_NAME`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` and optional `R2_ENDPOINT` become `SANDCMS_CF_ACCOUNT_ID` and `SANDCMS_R2_*`. Old names are not read. Set the new Worker secrets before running `sandcms worker update` and rename `CMS_TOKEN` in `sandcms/worker/.dev.vars`. Website environment variables, the database and project-owned YAML are unchanged. See [renamed Worker secrets](upgrades.md#renamed-worker-secrets).
18
+
19
+ Adds opt-in automatic migration on website start with `SANDCMS_AUTO_MIGRATE=true` (`createCMS({ autoMigrate: true })`). Existing databases receive a verified snapshot before pending migrations are applied; incompatible histories are still rejected and concurrent starts apply each migration once. No SQL migration is required; customized integrations must opt in explicitly. See [automatic migration](deployment.md#automatic-migration-on-start).
20
+
3
21
  ## 0.6.0
4
22
 
5
23
  This minor release adds new content editing and media capabilities and changes framework requirements and API contracts. Before upgrading from 0.5.x, review the [0.6.0 upgrade checklist](upgrades.md#060-upgrade-checklist): migrate developer-owned SvelteKit configuration, deploy the protocol-5 Worker and configure direct R2 uploads, then apply retained migrations `0001` through `0006` before restarting the website. Supported accounts, content, and media are preserved; project-owned YAML and customized application files remain protected.