@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/create-site/template/theme/snippets/logo.liquid

@@ -0,0 +1,7 @@
+<span class="logo">
+  <svg class="logo__mark" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+    <path d="M16 2 L29 9 V23 L16 30 L3 23 V9 Z" fill="currentColor" fill-opacity="0.08" stroke="currentColor" stroke-width="1.6" stroke-linejoin="round"/>
+    <path d="M16 2 L16 30 M3 9 L16 15 L29 9 M3 23 L16 15" stroke="var(--accent)" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round"/>
+  </svg>
+  <span>Minamo</span>
+</span>

package/dist/create-site/template/theme/snippets/responsive-media.liquid

@@ -0,0 +1,107 @@
+{%- comment -%}
+  responsive-media - the only way a content image or video should reach a page.
+
+  Renders a `format: "image"` or `format: "video"` setting, and marks the
+  result as a drag-and-drop target so an editor can drag a file from the
+  admin's media library straight onto it in the live preview.
+
+    {% render 'responsive-media',
+         media: section.settings.image,   the whole setting object, not .url
+         kind: 'image',                   'image' or 'video'
+         field: 'image',                  REQUIRED - the settings key this
+                                          renders, which is what a drop writes
+                                          back to
+         alt: 'What is actually in the picture',
+         ratio: '16 / 9',                 any CSS aspect-ratio value
+         loading: 'eager',                'eager' above the fold, else lazy
+         priority: true,                  adds fetchpriority=high
+         need: 'Wide shot of the still house',   shown in the empty slot
+         class: 'extra-class' %}
+
+  Why `field` matters
+  -------------------
+  The admin finds a drop target by looking for data-cms-media, and uses its
+  value to know which setting to write the new URL into. Get it wrong and the
+  drop silently writes to the wrong field; omit it and the image simply is not
+  droppable. It must match the schema property name exactly.
+
+  An empty slot is NOT a drop target (decided directly). A theme has no way to
+  tell whether it is rendering for the admin preview or for the public site -
+  the renderer does not expose that - so an editor-only affordance would leak
+  onto the live site as a dashed box in front of real visitors. Guard the call
+  instead, exactly as hero.liquid and cta-banner.liquid do:
+
+    {% if section.settings.image.url %}{% render 'responsive-media', ... %}{% endif %}
+
+  so a section with nothing set renders nothing at all. Set the first image
+  through the Fields panel's own picker; drag-and-drop then replaces it.
+
+  No srcset, on purpose
+  ---------------------
+  The CMS names uploaded files by a hash of their own bytes, so a resized
+  variant gets a completely different name - "photo-480w.webp" is not
+  derivable from "photo-3f9a2b7c1e04.jpg". Hand-built variant URLs therefore
+  point at files that do not exist, which renders a page that looks perfectly
+  fine except at one breakpoint. Do not add a srcset here. One image is one
+  file and one URL; let CSS do the responsive work.
+{%- endcomment -%}
+{%- assign media_kind = kind | default: 'image' -%}
+{%- assign media_field = field | default: 'image' -%}
+{%- assign media_url = media.url -%}
+{%- capture ratio_style -%}--media-ratio: {{ ratio | default: '3 / 2' }};{%- endcapture -%}
+
+{%- if media_url == nil or media_url == '' -%}
+  {%- comment -%}
+    Reached only if a caller renders this without guarding on a url - the
+    scaffold's own call sites guard, so this never appears on a real page.
+    Kept as a graceful fallback for a theme that genuinely wants a visible
+    placeholder, and deliberately carrying NO drag attributes: see above.
+  {%- endcomment -%}
+  <div class="media media--empty {{ class }}"
+       style="{{ ratio_style }}"
+       role="img"
+       aria-label="Placeholder. {{ need | default: alt }}">
+    <span class="media__hint">{{ need | default: alt | default: 'Drag a file here' }}</span>
+  </div>
+{%- elsif media_kind == 'video' -%}
+  {%- comment -%}
+    No data-cms-image on a video: an older admin understands only that
+    attribute and would write an image-shaped value ({url, focalX, focalY})
+    over this field's own {url, poster}. Better it ignores the slot entirely
+    than corrupts it.
+
+    A background loop is muted and looping by definition, so it may autoplay.
+    The poster is what shows before the clip loads and wherever it will not
+    play at all, which is why it is worth setting rather than optional.
+  {%- endcomment -%}
+  <div class="media {{ class }}{% if media.poster and media.poster != '' %} media--has-poster{% endif %}"
+       style="{{ ratio_style }}{% if media.poster and media.poster != '' %} --media-poster: url('{{ media.poster }}');{% endif %}"
+       data-cms-media="{{ media_field }}"
+       data-cms-media-kind="video">
+    <video
+      src="{{ media_url }}"
+      {% if media.poster and media.poster != '' %}poster="{{ media.poster }}"{% endif %}
+      autoplay
+      muted
+      loop
+      playsinline
+      preload="metadata"
+      {% if alt and alt != '' %}aria-label="{{ alt }}"{% else %}aria-hidden="true"{% endif %}></video>
+  </div>
+{%- else -%}
+  {%- assign fx = media.focalX | default: 0.5 | times: 100 | round: 1 -%}
+  {%- assign fy = media.focalY | default: 0.5 | times: 100 | round: 1 -%}
+  <div class="media {{ class }}"
+       style="{{ ratio_style }}"
+       data-cms-media="{{ media_field }}"
+       data-cms-media-kind="image"
+       data-cms-image="{{ media_field }}">
+    <img
+      src="{{ media_url }}"
+      alt="{{ alt }}"
+      loading="{{ loading | default: 'lazy' }}"
+      decoding="async"
+      {% if priority %}fetchpriority="high"{% endif %}
+      style="object-position: {{ fx }}% {{ fy }}%;">
+  </div>
+{%- endif -%}

package/dist/create-site/template/theme/snippets/site-name.liquid

@@ -0,0 +1 @@
+<span class="site-name">{{ name }}</span>

package/dist/create-site/template/vhost/Dockerfile

@@ -0,0 +1,33 @@
+# Generic and site-content-agnostic - this file never needs to change
+# per site. Runs identically via plain `docker build`/`docker run` on a
+# bare VPS, Fly, ECS, or any PaaS - nothing platform-specific is baked
+# in here (see docs/guide-hosting.md for platform-specific deploy config,
+# which always layers on top of this, never inside it).
+#
+# Lives in vhost/, not the site root, alongside the rest of the site's
+# own serving config (package.json, server.js, site.config.json) - the
+# build context is still the site root, so build with:
+#   docker build -f vhost/Dockerfile -t my-site .
+FROM node:22-alpine
+
+# git is a hard runtime requirement (services/startup-checks.ts fails
+# fast without it) - content, drafts and publishes are all real git
+# operations, not a database.
+RUN apk add --no-cache git
+
+# Build-time install happens against the image-baked copy of the site
+# ("/seed"), never directly against "/site" - "/site" is where a
+# persistent volume gets mounted at runtime, and anything written there
+# during the build would simply be shadowed by that mount.
+WORKDIR /seed
+COPY . .
+RUN cd vhost && npm install --omit=dev
+
+WORKDIR /site
+COPY vhost/docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+# Must match vhost/site.config.json's own "port" field.
+EXPOSE 3000
+
+ENTRYPOINT ["/docker-entrypoint.sh"]

package/dist/create-site/template/vhost/docker-entrypoint.sh

@@ -0,0 +1,58 @@
+#!/bin/sh
+set -e
+
+# /seed is the image-baked copy of the site; /site is where the
+# persistent volume is mounted. Overridable only so the test suite can
+# run this exact script against temporary directories.
+SEED="${CMS_SEED_DIR:-/seed}"
+SITE="${CMS_SITE_DIR:-/site}"
+
+# First boot against an empty mounted volume: seed it from the
+# image-baked copy at /seed (content, theme, the already-`npm
+# install`ed vhost/node_modules). A later boot finds /site/vhost
+# already populated and skips this, so the same image works
+# identically with a real persistent volume mounted at /site
+# (production) or with nothing mounted at all (a quick local trial,
+# where content just lives in the ephemeral container layer).
+if [ ! -d "$SITE/vhost" ]; then
+  cp -r "$SEED/." "$SITE/"
+else
+  # Every later boot: refresh the CMS itself from the image, and
+  # nothing else. Content, drafts, media and theme on the volume are
+  # the live site's own and are never touched - but the installed CMS
+  # is code, not content, so without this a redeploy built from a newer
+  # version would keep running the old one from the volume forever.
+  # Only the dependency manifest, its installed packages and server.js
+  # (the CMS's own, which imports it by name: the package was renamed
+  # from @o-a/cms-agent to @minamocms/framework) are copied; site.config.json
+  # (tokens) stays as it is on the volume.
+  #
+  # This leaves vhost/package.json (and package-lock.json) showing as
+  # modified in the volume's git working tree after an upgrade. That is
+  # deliberate: nothing here commits, since publishing is the only
+  # routine operation that creates a commit.
+  cp "$SEED/vhost/package.json" "$SITE/vhost/package.json"
+  if [ -f "$SEED/vhost/package-lock.json" ]; then
+    cp "$SEED/vhost/package-lock.json" "$SITE/vhost/package-lock.json"
+  fi
+  rm -rf "$SITE/vhost/node_modules"
+  cp -r "$SEED/vhost/node_modules" "$SITE/vhost/node_modules"
+  cp "$SEED/vhost/server.js" "$SITE/vhost/server.js"
+fi
+
+# The site root must be a real git repository (services/startup-checks.ts) -
+# a plain `docker build` from a full local checkout preserves .git, but
+# some platforms (Railway's `railway up` included) build from a
+# git-archive-style upload of tracked file contents only, which never
+# includes .git at all. Recovered here rather than assumed away: if
+# it's missing, start a fresh repo over the already-seeded content.
+if [ ! -d "$SITE/.git" ]; then
+  git -C "$SITE" init --quiet
+  git -C "$SITE" add -A
+  GIT_AUTHOR_NAME="Minamo" GIT_AUTHOR_EMAIL="minamo@localhost" \
+    GIT_COMMITTER_NAME="Minamo" GIT_COMMITTER_EMAIL="minamo@localhost" \
+    git -C "$SITE" commit --quiet -m "chore: initial scaffold (recovered - .git was not part of the deploy upload)"
+fi
+
+cd "$SITE/vhost"
+exec node server.js

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { startServer, buildServer } from './server.ts';
+export type { BuildServerOptions } from './server.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+// The package's public entry point (package.json's "main"): a site's
+// real server.js ("import the agent, point it at this directory,
+// start", per the build plan) imports startServer from here.
+export { startServer, buildServer } from "./server.js";

package/dist/media/drivers/driver.d.ts

@@ -0,0 +1,11 @@
+export interface MediaListEntry {
+    name: string;
+    size: number;
+    mtimeMs: number;
+}
+export interface MediaStorageDriver {
+    list(): Promise<MediaListEntry[]>;
+    put(filename: string, bytes: Buffer): Promise<void>;
+    get(filename: string): Promise<Buffer | null>;
+    delete(filename: string): Promise<boolean>;
+}

package/dist/media/drivers/driver.js

@@ -0,0 +1 @@
+export {};

package/dist/media/drivers/local-fs-driver.d.ts

@@ -0,0 +1,3 @@
+import type { MediaStorageDriver } from './driver.ts';
+export declare const DRIVER_NAME = "local-fs";
+export declare function openLocalFsMediaDriver(root: string): MediaStorageDriver;

package/dist/media/drivers/local-fs-driver.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { PathSafetyError, sanitisePath } from "../../services/path-safety.js";
+// A plain string constant, matching node-sqlite-driver.ts's own
+// DRIVER_NAME convention - safe for the capabilities endpoint to
+// report without needing to import anything fs-touching.
+export const DRIVER_NAME = 'local-fs';
+// The default (and, for this build increment, only) MediaStorageDriver
+// implementation. No driver-containment static-analysis test exists
+// for this yet, unlike search/drivers' own G5 check for node:sqlite -
+// node:fs is a single already-pervasive Node builtin, not a swappable
+// third-party library the way node:sqlite/better-sqlite3 are, so
+// there's no "which alternative" question to fence off yet. The
+// natural trigger for that kind of test is a future object-storage
+// driver's own third-party SDK import.
+//
+// Every method resolves filename through sanitisePath itself before
+// touching disk - this file importing both node:fs and sanitisePath
+// is what satisfies the B7 static-analysis rule with no allowlist
+// entry needed, matching assets.ts/content.ts's own pattern of the
+// fs-touching file being the one that calls it.
+export function openLocalFsMediaDriver(root) {
+    return {
+        async list() {
+            mkdirSync(root, { recursive: true });
+            return readdirSync(root, { withFileTypes: true })
+                .filter((entry) => entry.isFile())
+                .map((entry) => {
+                const stats = statSync(sanitisePath(root, entry.name));
+                return { name: entry.name, size: stats.size, mtimeMs: stats.mtimeMs };
+            });
+        },
+        async put(filename, bytes) {
+            // The root first: sanitisePath resolves the root's real path, which
+            // fails outright on a fresh deploy whose media folder was never
+            // created (media/ is git-ignored, so a host building from the
+            // repository has none).
+            mkdirSync(root, { recursive: true });
+            const resolved = sanitisePath(root, filename);
+            // Harmless no-op for a flat, content-addressed namespace (media
+            // filenames never contain subdirectories) - matches
+            // manage-menus.ts's own defensive precedent of creating the
+            // parent directory before a write rather than assuming it
+            // already exists.
+            mkdirSync(dirname(resolved), { recursive: true });
+            // No existence check first: content-addressed naming means an
+            // identical re-upload writes identical bytes over identical
+            // bytes - a harmless idempotent overwrite, not something that
+            // needs special-casing.
+            writeFileSync(resolved, bytes);
+        },
+        async get(filename) {
+            // No media folder yet is no media yet: nothing to find, and a read
+            // has no business creating the folder.
+            if (!existsSync(root)) {
+                return null;
+            }
+            let resolved;
+            try {
+                resolved = sanitisePath(root, filename);
+            }
+            catch (error) {
+                // An invalid/traversal-shaped filename reads as "not found"
+                // from this method's own contract - the route layer is what
+                // decides whether that's a 404 or something else, the driver
+                // itself stays mechanical.
+                if (error instanceof PathSafetyError) {
+                    return null;
+                }
+                throw error;
+            }
+            if (!existsSync(resolved) || !statSync(resolved).isFile()) {
+                return null;
+            }
+            return readFileSync(resolved);
+        },
+        async delete(filename) {
+            // Unlike get(), a malformed delete path is let through
+            // uncaught - worth surfacing distinctly rather than silently
+            // reading as "already didn't exist", matching
+            // manage-redirects.ts's own not-found-is-a-distinct-reason
+            // precedent.
+            if (!existsSync(root)) {
+                return false;
+            }
+            const resolved = sanitisePath(root, filename);
+            if (!existsSync(resolved)) {
+                return false;
+            }
+            unlinkSync(resolved);
+            return true;
+        },
+    };
+}

package/dist/media/filename.d.ts

@@ -0,0 +1,2 @@
+export declare const ALLOWED_UPLOAD_EXTENSIONS: Set<string>;
+export declare function buildMediaFilename(originalFilename: string, bytes: Buffer): string;

package/dist/media/filename.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { basename, extname } from 'node:path';
+// Content-addressed: the filename is derived from a hash of the
+// file's own bytes, so two uploads can never collide, and an
+// identical re-upload naturally produces the identical filename (a
+// harmless overwrite in local-fs-driver.ts's put(), not a duplicate).
+// No separate manifest/index recording original filenames - this
+// codebase avoids a second source of truth on principle (the same
+// reasoning that keeps the SQLite search index disposable rather than
+// authoritative), so the original name is folded into the filename
+// itself instead of tracked anywhere else.
+//
+// Truncated to 12 hex chars (48 bits), not the full 64-char digest -
+// git itself only shows short hashes for the same reason. At this
+// length a collision between two different files stays astronomically
+// unlikely (well past a 1-in-a-trillion chance even at tens of
+// thousands of uploads to one site), while keeping filenames/URLs/git
+// history actually readable.
+//
+// Slug regex matches generate-site.ts's own sanitisePackageName -
+// lowercase, non [a-z0-9-] runs collapsed to a single "-", trimmed -
+// not a second, independently-invented convention.
+const HASH_LENGTH = 12;
+// Images and short videos - not a general document library. Video was
+// added deliberately (confirmed with the user) for silent looping
+// clips used where a hero image would otherwise go; long-form video
+// belongs on YouTube/Vimeo and needs nothing from here. The upload cap
+// (site.config.json's media.maxUploadBytes, 10MB by default) is what
+// keeps that distinction honest - it comfortably fits a well-compressed
+// 10-15s loop and comfortably rejects a real film.
+//
+// .svg is rejected regardless of this list even though it's
+// technically an image format - docs/cms-build-plan.md's own "SVG
+// rejected outright, not sanitised" decision (a real stored-XSS path
+// otherwise: mime-types.ts maps .svg to a real image/svg+xml content
+// type, and an SVG loaded as a top-level navigation, not just <img>-
+// embedded, can execute a script it carries).
+//
+// Exported from here, not left as routes/media.ts's own private
+// constant, specifically so seed-media.ts (an offline tool with no
+// HTTP request to validate) enforces the exact same rule rather than
+// a second, independently-maintained copy of it.
+export const ALLOWED_UPLOAD_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.mp4', '.webm']);
+export function buildMediaFilename(originalFilename, bytes) {
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, HASH_LENGTH);
+    const base = basename(originalFilename, extname(originalFilename));
+    const cleaned = base.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+    const slug = cleaned.length > 0 ? cleaned : 'file';
+    const extension = extname(originalFilename).toLowerCase();
+    // Slug first, hash last (requested directly) - the readable part of
+    // the filename sorts and scans first in a directory listing/URL,
+    // with the hash as a suffix rather than something to read past.
+    return `${slug}-${hash}${extension}`;
+}

package/dist/media/manage-media.d.ts

@@ -0,0 +1,19 @@
+import type { SiteConfig } from '../config.ts';
+export type ManageMediaReason = 'not-found' | 'invalid-file-type';
+export declare class ManageMediaError extends Error {
+    readonly reason: ManageMediaReason;
+    constructor(reason: ManageMediaReason, message: string);
+}
+export interface MediaEntry {
+    name: string;
+    size: number;
+    mtimeMs: number;
+    url: string;
+}
+export declare function listMedia(config: SiteConfig): Promise<MediaEntry[]>;
+export declare function putMedia(config: SiteConfig, originalFilename: string, bytes: Buffer): Promise<{
+    name: string;
+    size: number;
+    url: string;
+}>;
+export declare function deleteMedia(config: SiteConfig, filename: string): Promise<void>;

package/dist/media/manage-media.js

@@ -0,0 +1,45 @@
+import { enqueue } from "../services/write-queue.js";
+import { openLocalFsMediaDriver } from "./drivers/local-fs-driver.js";
+import { buildMediaFilename } from "./filename.js";
+export class ManageMediaError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'ManageMediaError';
+        this.reason = reason;
+    }
+}
+function mediaUrl(name) {
+    return `/media/${name}`;
+}
+// Opens a fresh driver per call rather than threading one long-lived
+// instance through BootedSite - unlike DatabaseSync, plain fs calls
+// have no connection/handle to reuse, so there's no driver-lifecycle
+// wiring needed. The only call site that decides which driver to open
+// is here, hardcoded, matching how rebuild-index.ts hardcodes
+// openNodeSqliteDriver today with no config-driven selection either -
+// this is where a future config-driven driver choice would go.
+function driverFor(config) {
+    return openLocalFsMediaDriver(config.mediaRoot);
+}
+// Not enqueued - reads bypass the write queue, matching
+// handleListRedirects' own precedent of only serialising mutations.
+export async function listMedia(config) {
+    const entries = await driverFor(config).list();
+    return entries.map((entry) => ({ ...entry, url: mediaUrl(entry.name) }));
+}
+export function putMedia(config, originalFilename, bytes) {
+    return enqueue(async () => {
+        const name = buildMediaFilename(originalFilename, bytes);
+        await driverFor(config).put(name, bytes);
+        return { name, size: bytes.length, url: mediaUrl(name) };
+    });
+}
+export function deleteMedia(config, filename) {
+    return enqueue(async () => {
+        const existed = await driverFor(config).delete(filename);
+        if (!existed) {
+            throw new ManageMediaError('not-found', `No media file at "${filename}"`);
+        }
+    });
+}

package/dist/media/seed-media-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/media/seed-media-cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { seedMedia } from "./seed-media.js";
+const [targetArg, ...sourceArgs] = process.argv.slice(2);
+if (!targetArg || sourceArgs.length === 0) {
+    console.error('Usage: seed-media <site-directory> <path> [<path> ...]');
+    process.exit(1);
+}
+const siteDir = resolve(process.cwd(), targetArg);
+const sourcePaths = sourceArgs.map((sourceArg) => resolve(process.cwd(), sourceArg));
+const result = seedMedia(siteDir, sourcePaths);
+for (const entry of result.entries) {
+    if (entry.status === 'seeded') {
+        console.log(`${entry.sourcePath} -> ${entry.url}`);
+    }
+    else {
+        console.log(`${entry.sourcePath}: skipped (${entry.reason})`);
+    }
+}
+if (!result.ok) {
+    process.exit(1);
+}

package/dist/media/seed-media.d.ts

@@ -0,0 +1,11 @@
+export interface SeedMediaEntry {
+    sourcePath: string;
+    status: 'seeded' | 'skipped-invalid-type';
+    url?: string;
+    reason?: string;
+}
+export interface SeedMediaResult {
+    ok: boolean;
+    entries: SeedMediaEntry[];
+}
+export declare function seedMedia(siteRoot: string, sourcePaths: string[]): SeedMediaResult;

package/dist/media/seed-media.js

@@ -0,0 +1,76 @@
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { ALLOWED_UPLOAD_EXTENSIONS, buildMediaFilename } from "./filename.js";
+// A directory argument expands to its own direct child files only -
+// one level, not recursive, matching theme-schemas.ts's own flat-
+// directory convention for exactly the same reason (a predictable,
+// easy-to-reason-about walk, not a surprise deep scan).
+function expandSourcePaths(sourcePaths) {
+    const files = [];
+    for (const sourcePath of sourcePaths) {
+        if (statSync(sourcePath).isDirectory()) {
+            for (const entry of readdirSync(sourcePath, { withFileTypes: true })) {
+                if (entry.isFile()) {
+                    files.push(join(sourcePath, entry.name));
+                }
+            }
+        }
+        else {
+            files.push(sourcePath);
+        }
+    }
+    return files;
+}
+// Seeds one or more local image files directly into a site's media/,
+// computing the exact same content-addressed filename a real
+// POST /v1/media upload would - see this module's own filename.ts for
+// why that's safe to do offline (a pure function of a filename and the
+// file's own bytes, no server/database involved). For an AI agent (or
+// any offline tool) generating a site's starter content before a
+// server is even running - GET /media/* just serves whatever file
+// exists at the requested path, so the result is indistinguishable
+// from a real upload.
+//
+// siteRoot is an operator/agent-supplied directory, the same category
+// as scaffoldSite/mintToken - not a web request's own :path, so
+// sanitisePath's traversal concern doesn't apply here (see
+// mint-token.ts's own comment on this exact point).
+//
+// Never a git commit - media is never git-tracked (constraint 2,
+// matching manage-media.ts's own "no commit, no author... Media is
+// never git-tracked" comment).
+//
+// A disallowed file type is skipped, not a reason to abort the whole
+// batch - an agent seeding a dozen images should still get the eleven
+// good ones, with the one bad one clearly reported. The allowlist
+// itself is the one thing that must not be relaxed here: it's the
+// same rule the real upload route enforces (ALLOWED_UPLOAD_EXTENSIONS,
+// shared, not a second copy), because skipping it would reopen the
+// real stored-XSS path SVG rejection exists to close, for whoever
+// later visits the live site - not a concern about this tool's own
+// caller, who already has full local trust.
+export function seedMedia(siteRoot, sourcePaths) {
+    const mediaRoot = join(siteRoot, 'media');
+    mkdirSync(mediaRoot, { recursive: true });
+    const entries = [];
+    for (const sourcePath of expandSourcePaths(sourcePaths)) {
+        const extension = extname(sourcePath).toLowerCase();
+        if (!ALLOWED_UPLOAD_EXTENSIONS.has(extension)) {
+            entries.push({
+                sourcePath,
+                status: 'skipped-invalid-type',
+                reason: `"${extension}" is not an accepted image type`,
+            });
+            continue;
+        }
+        const bytes = readFileSync(sourcePath);
+        const name = buildMediaFilename(basename(sourcePath), bytes);
+        // No existence check first: content-addressed naming means
+        // re-seeding the same bytes writes identical bytes over identical
+        // bytes - a harmless idempotent overwrite, matching
+        // local-fs-driver.ts's own put() precedent exactly.
+        writeFileSync(join(mediaRoot, name), bytes);
+        entries.push({ sourcePath, status: 'seeded', url: `/media/${name}` });
+    }
+    return { ok: entries.every((entry) => entry.status === 'seeded'), entries };
+}

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationMap } from '../services/migration-runner.ts';
+export declare const CURRENT_SCHEMA_VERSION = 7;
+export declare const migrations: MigrationMap;