@ossy/platform 1.39.2 → 3.0.1

package/src/server.js

@@ -7,12 +7,12 @@ import { Router as OssyRouter } from '@ossy/router'
 import cookieParser from 'cookie-parser'
 import { ProxyInternal } from './proxy-internal.js'
 import { SDK, resolveActionId } from '@ossy/sdk'
-import { AggregateRebuild, resolveMongoUrl } from '@ossy/event-store'
+import { AggregateRebuild, ensureEventStoreIndexes, Mongo, resolveMongoUrl } from '@ossy/event-store'
 import { TaskService } from './tasks/task-service.js'
 import { ChangeStream } from './tasks/change-stream.js'
-import { CONTENT_SLOT_NAME } from '@ossy/app/runtime/resolve-shell-slots'
 import { buildManifestSummary } from '@ossy/app/manifest/build-manifest-summary'
-import { registerResourceTemplate } from './resources/resource-template.registry.js'
+import { registerSchema } from './resources/schema.registry.js'
+import { initPlatformSchema } from './resources/schema.service.js'
 import { IntegrationService } from './integration.service.js'
 import { ActionService } from './actions/action.service.js'
 import { createLogger } from '@ossy/observability'
@@ -20,7 +20,29 @@ import { ConfigService } from './config.service.js'
 import { UsersMiddleware } from './users.middleware.js'
 import { WorkspacesMiddleware } from './workspaces.middleware.js'
 import { resolveRequestLocale } from './locale.js'
+import { mountPlatformMcp } from './mcp/mount-platform-mcp.js'
+import {
+  assertActionEntitled,
+  buildActionEntitlementIndex,
+  createWorkspaceLoader,
+} from './entitlements/action-entitlement.js'
+import { closePushSseConnections, mountPushSse } from './push/mount-push-sse.js'
+import {
+  createSlowRequestLogger,
+  createTimedOperation,
+  OperationTimeoutError,
+  resolveTimeoutMs,
+  withTimeout,
+} from './request-diagnostics.js'
+import { mergeWorkspaceSchemas } from '@ossy/workspaces/merge-workspace-schemas'
+import {
+  buildEnableablePackageSet,
+  setEnableablePackages,
+} from '@ossy/workspaces/entitlements'
 const log = createLogger('@ossy/platform')
+const MONGO_TIMEOUT_MS = resolveTimeoutMs('OSSY_MONGO_TIMEOUT_MS', 10_000)
+const SSR_RENDER_TIMEOUT_MS = resolveTimeoutMs('OSSY_SSR_RENDER_TIMEOUT_MS', 30_000)
+const ACTION_TIMEOUT_MS = resolveTimeoutMs('OSSY_ACTION_TIMEOUT_MS', 60_000)
 
 const DEFAULT_PORT = 3000
 const MANIFEST_FILE = 'manifest.json'
@@ -58,14 +80,15 @@ export function loadManifest (buildDir) {
   const apis = entries.filter((e) => e.type === 'api' && validRoutable(e))
   const tasks = entries.filter((e) => e.type === 'task')
   const components = Array.isArray(manifest.components) ? manifest.components : []
-  const resourceTemplates = Array.isArray(manifest.resourceTemplates) ? manifest.resourceTemplates : []
+  const schemas = Array.isArray(manifest.schemas) ? manifest.schemas : []
   const aggregates = Array.isArray(manifest.aggregates) ? manifest.aggregates : []
   const integrations = Array.isArray(manifest.integrations) ? manifest.integrations : []
   const startups = Array.isArray(manifest.startups) ? manifest.startups : []
   const actions = Array.isArray(manifest.actions) ? manifest.actions : []
   const emails = Array.isArray(manifest.emails) ? manifest.emails : []
   const layouts = Array.isArray(manifest.layouts) ? manifest.layouts : []
-  for (const e of entries) {    if ((e.type === 'page' || e.type === 'api') && !validRoutable(e)) {
+  for (const e of entries) {
+    if ((e.type === 'page' || e.type === 'api') && !validRoutable(e)) {
       log.warn(`Skipping ${e.type} "${e.id}" — manifest entry has no path.`)
     }
   }
@@ -75,7 +98,7 @@ export function loadManifest (buildDir) {
     apis,
     tasks,
     components,
-    resourceTemplates,
+    schemas,
     aggregates,
     integrations,
     startups,
@@ -85,6 +108,9 @@ export function loadManifest (buildDir) {
     config: manifest.config || {},
     definitions: manifest.definitions || {},
     translations: manifest.translations || {},
+    actionRoutes: manifest.actionRoutes || {},
+    taskCatalog: Array.isArray(manifest.taskCatalog) ? manifest.taskCatalog : [],
+    taskGraphEdges: Array.isArray(manifest.taskGraphEdges) ? manifest.taskGraphEdges : [],
   }
 }
 
@@ -102,6 +128,49 @@ function cloneSerializable (value) {
   return value == null ? value : JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * Load all registered layout bundles keyed by canonical layout id.
+ *
+ * @param {Array<{ id: string, entry: string }>} layoutManifest
+ * @param {string} buildDir
+ * @param {import('@ossy/observability').Logger} log
+ */
+async function loadLayoutsById (layoutManifest, buildDir, log) {
+  /** @type {Map<string, { component: import('react').ComponentType, entry: string }>} */
+  const layoutsById = new Map()
+  for (const layoutEntry of layoutManifest ?? []) {
+    if (!layoutEntry?.id || !layoutEntry?.entry) continue
+    try {
+      const mod = await import(/* @vite-ignore */ resolveEntryUrl(layoutEntry.entry, buildDir))
+      if (typeof mod.default === 'function') {
+        layoutsById.set(layoutEntry.id, { component: mod.default, entry: layoutEntry.entry })
+      }
+    } catch (err) {
+      log.warn(`Failed to load layout "${layoutEntry.id}"`, undefined, err)
+    }
+  }
+  return layoutsById
+}
+
+/**
+ * @param {Map<string, { component: import('react').ComponentType, entry: string }>} layoutsById
+ * @param {{ layout?: string, slots?: Record<string, string | null> }} pageEntry
+ */
+function resolvePageLayoutRender (layoutsById, pageEntry) {
+  const layoutId = pageEntry?.layout ?? '@ossy/app/layout/default'
+  const layoutRecord = layoutsById.get(layoutId) ?? layoutsById.get('@ossy/app/layout/default') ?? null
+  const layoutSlots =
+    pageEntry?.slots && typeof pageEntry.slots === 'object' && !Array.isArray(pageEntry.slots)
+      ? pageEntry.slots
+      : {}
+  return {
+    Layout: layoutRecord?.component ?? null,
+    layoutEntry: layoutRecord?.entry ?? null,
+    layoutSlots,
+    layoutId,
+  }
+}
+
 export async function startServer (options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd()
   const buildDir = path.resolve(cwd, options.buildDir || 'build')
@@ -114,12 +183,18 @@ export async function startServer (options = {}) {
 
   const manifest = loadManifest(buildDir)
   const manifestSummary = buildManifestSummary(manifest)
+  setEnableablePackages(buildEnableablePackageSet(manifest))
+  initPlatformSchema(manifest)
+  const capabilitiesPath = path.join(buildDir, 'capabilities.json')
+  const capabilities = fs.existsSync(capabilitiesPath)
+    ? JSON.parse(fs.readFileSync(capabilitiesPath, 'utf8'))
+    : null
   const config = manifest.config
   const supportedLanguages = Array.isArray(config.supportedLanguages) ? config.supportedLanguages : []
   const defaultLanguage = config.defaultLanguage
   for (const task of manifest.tasks ?? []) {
     try {
-      const mod = await import(resolveEntryUrl(task.entry, buildDir))
+      const mod = await import(/* @vite-ignore */ resolveEntryUrl(task.entry, buildDir))
       if (mod.metadata) {
         TaskService.registerTask(mod)
       }
@@ -128,8 +203,8 @@ export async function startServer (options = {}) {
     }
   }
 
-  for (const template of manifest.resourceTemplates ?? []) {
-    registerResourceTemplate(template)
+  for (const template of manifest.schemas ?? []) {
+    registerSchema(template)
   }
 
   // Integration loading — import each bundled integration module, check its
@@ -139,33 +214,39 @@ export async function startServer (options = {}) {
   const integrationModules = []
   for (const intEntry of manifest.integrations ?? []) {
     try {
-      integrationModules.push(await import(resolveEntryUrl(intEntry.entry, buildDir)))
+      integrationModules.push(await import(/* @vite-ignore */ resolveEntryUrl(intEntry.entry, buildDir)))
     } catch (err) {
       log.warn(`Failed to import integration "${intEntry.id}"`, undefined, err)
     }
   }
   await IntegrationService.load(integrationModules, process.env)
 
-  // Aggregate registration — mirrors task and resource-template registration above.
+  // Aggregate registration — mirrors task and schema registration above.
   // AggregateRebuild is provided by @ossy/event-store.
+  /** @type {(() => void) | null} */
+  let runStartupRebuild = null
   if (AggregateRebuild) {
     for (const agg of manifest.aggregates ?? []) {
       try {
-        const mod = await import(resolveEntryUrl(agg.entry, buildDir))
+        const mod = await import(/* @vite-ignore */ resolveEntryUrl(agg.entry, buildDir))
         AggregateRebuild.registerAggregate(mod)
       } catch (err) {
         log.error(`Failed to load aggregate "${agg.id}"`, undefined, err)
       }
     }
 
-    AggregateRebuild.BuildAndSaveAll().catch((error) => {
-      log.error('BuildAndSaveAll failed — is MongoDB reachable?', undefined, error)
-    })
+    // Defer full startup rebuild until the server is listening so request handling
+    // is not starved while snapshots catch up (332k+ streams on large local DBs).
+    runStartupRebuild = () => {
+      AggregateRebuild.BuildAndSaveAll().catch((error) => {
+        log.error('BuildAndSaveAll failed — is MongoDB reachable?', undefined, error)
+      })
+    }
   }
 
   for (const startup of manifest.startups ?? []) {
     try {
-      const mod = await import(resolveEntryUrl(startup.entry, buildDir))
+      const mod = await import(/* @vite-ignore */ resolveEntryUrl(startup.entry, buildDir))
       if (typeof mod.run === 'function') {
         await mod.run({ env: process.env })
       }
@@ -178,41 +259,16 @@ export async function startServer (options = {}) {
   // with ActionService so it can be looked up and invoked at runtime.
   for (const actionEntry of manifest.actions ?? []) {
     try {
-      const mod = await import(resolveEntryUrl(actionEntry.entry, buildDir))
+      const mod = await import(/* @vite-ignore */ resolveEntryUrl(actionEntry.entry, buildDir))
       ActionService.register(mod)
     } catch (err) {
       log.error(`Failed to load action "${actionEntry.id}"`, undefined, err)
     }
   }
 
-  // Layout loading — one `*.layout.jsx` per app wraps every page render. The
-  // layout component decides route-specific chrome (auth, public flows, etc.).
-  /** @type {{ component: import('react').ComponentType, entry: string } | null} */
-  let appLayout = null
+  // Layout loading — registered layouts keyed by id; each page picks layout + merged slots at build time.
   const layoutManifest = manifest.layouts ?? []
-  if (layoutManifest.length > 1) {
-    log.warn(
-      `Multiple layouts in manifest (${layoutManifest.length}); only the first is used. Use one *.layout.jsx per app.`,
-    )
-  }
-  const layoutEntry = layoutManifest[0]
-  if (layoutEntry) {
-    try {
-      const mod = await import(resolveEntryUrl(layoutEntry.entry, buildDir))
-      if (typeof mod.default === 'function') {
-        appLayout = { component: mod.default, entry: layoutEntry.entry }
-      }
-    } catch (err) {
-      log.warn(`Failed to load layout "${layoutEntry.id}"`, undefined, err)
-    }
-  }
-
-  // App-controlled shell slots: `export const slots` in `*.layout.jsx` is recorded
-  // on `manifest.layouts[0].slots` at build time and resolved at render in page-runtime.
-  const layoutSlots =
-    layoutEntry && typeof layoutEntry.slots === 'object' && !Array.isArray(layoutEntry.slots)
-      ? layoutEntry.slots
-      : {}
+  const layoutsById = await loadLayoutsById(layoutManifest, buildDir, log)
 
   // Register the SDK so all tasks receive it as `sdk`.
   // Priority: explicit options.sdk → SDK.of() from env vars → null (direct-DB fallback in tasks).
@@ -224,6 +280,9 @@ export async function startServer (options = {}) {
   TaskService.startScheduler()
 
   if (process.env.DB_URL) {
+    await ensureEventStoreIndexes().catch((err) => {
+      log.error('Failed to ensure MongoDB indexes — aggregate reads may be very slow', undefined, err)
+    })
     ChangeStream.start(resolveMongoUrl(process.env.DB_URL))
   }
 
@@ -237,11 +296,25 @@ export async function startServer (options = {}) {
   const moduleCache = new Map()
   async function loadEntry (entryUrl) {
     if (moduleCache.has(entryUrl)) return moduleCache.get(entryUrl)
-    const promise = import(resolveEntryUrl(entryUrl, buildDir))
+    const promise = import(/* @vite-ignore */ resolveEntryUrl(entryUrl, buildDir))
     moduleCache.set(entryUrl, promise)
     return promise
   }
 
+  const actionEntitlementIndex = buildActionEntitlementIndex(manifest)
+  let loadWorkspaceForEntitlements = null
+  try {
+    const { Workspace } = await import('@ossy/workspaces/server')
+    const loadWorkspace = createWorkspaceLoader(Workspace)
+    loadWorkspaceForEntitlements = (workspaceId) => withTimeout(
+      loadWorkspace(workspaceId),
+      MONGO_TIMEOUT_MS,
+      `loadWorkspace(${workspaceId})`,
+    )
+  } catch (err) {
+    log.warn('[@ossy/platform] Workspace aggregate unavailable — action entitlements disabled', err)
+  }
+
   const app = express()
   app.use(morgan('tiny'))
   app.use(express.json({ strict: false }))
@@ -258,14 +331,19 @@ export async function startServer (options = {}) {
   })
   app.use(UsersMiddleware.AuthenticateUser)
   app.use(WorkspacesMiddleware.ExtractWorkspaceId())
+  app.use(createSlowRequestLogger(log))
   if (fs.existsSync(publicDir)) app.use(express.static(publicDir))
   app.use(ProxyInternal())
 
+  mountPushSse(app)
+
   // Actions endpoint — POST /actions with body { action, payload }.
   app.post('/actions', async (req, res) => {
     const actionId = resolveActionId(req.body?.action)
     if (!actionId) return res.status(400).json({ error: 'Missing action' })
 
+    const payload = req.body?.payload ?? {}
+
     const action = ActionService.get(actionId)
     if (!action) return res.status(404).json({ error: 'Action not found' })
 
@@ -276,26 +354,82 @@ export async function startServer (options = {}) {
       return res.status(403).json({ error: 'Forbidden' })
     }
 
-    const payload = req.body?.payload ?? {}
+    if (!ActionService.hasHandler(actionId)) {
+      return res.status(405).json({ error: 'Action has no server handler' })
+    }
+
+    if (loadWorkspaceForEntitlements) {
+      try {
+        await assertActionEntitled({
+          actionId,
+          access: action.access,
+          workspaceId: req.workspaceId,
+          entitlementIndex: actionEntitlementIndex,
+          loadWorkspace: loadWorkspaceForEntitlements,
+        })
+      } catch (err) {
+        if (err?.code === 'SERVICE_NOT_ENTITLED') {
+          return res.status(403).json({
+            error: err.message,
+            code: err.code,
+            package: err.package,
+          })
+        }
+        if (err?.code === 'ACTION_NOT_PERMITTED') {
+          return res.status(403).json({
+            error: err.message,
+            code: err.code,
+          })
+        }
+        const status = err?.status ?? 500
+        return res.status(status).json({ error: err.message ?? 'Forbidden' })
+      }
+    }
+
     const actionLog = createLogger(actionId)
+    const actionTimer = createTimedOperation(`POST /actions ${actionId}`, { log: actionLog })
+    const actionAbort = new AbortController()
     try {
-      const result = await ActionService.invoke(actionId, {
-        payload,
-        sdk: req.sdk ?? null,
-        log: actionLog,
-        integrations: IntegrationService,
-        req,
-      })
+      const result = await withTimeout(
+        ActionService.invoke(actionId, {
+          payload,
+          sdk: req.sdk ?? null,
+          log: actionLog,
+          integrations: IntegrationService,
+          req,
+          signal: actionAbort.signal,
+        }),
+        ACTION_TIMEOUT_MS,
+        `POST /actions ${actionId}`,
+        { abortController: actionAbort },
+      )
+      actionTimer.finish({ statusCode: 200 })
       res.json(result ?? { ok: true })
     } catch (err) {
+      actionTimer.finish({
+        statusCode: err instanceof OperationTimeoutError ? 504 : (err?.status ?? 500),
+        timedOut: err instanceof OperationTimeoutError,
+      })
+      if (err instanceof OperationTimeoutError) {
+        actionLog.error('Action timed out', { id: actionId, timeoutMs: err.timeoutMs })
+        return res.status(504).json({ error: 'Action timed out', code: 'ACTION_TIMEOUT' })
+      }
       actionLog.error('Action failed', { id: actionId }, err)
       const status = err?.status ?? 500
       res.status(status).json({ error: err?.message ?? 'Internal error' })
     }
   })
 
+  const resolvedCapabilities = mountPlatformMcp(app, {
+    manifest,
+    capabilities,
+    actionEntitlementIndex,
+    loadWorkspaceForEntitlements,
+  })
+
   app.all('*all', async (req, res) => {
     const requestUrl = req.originalUrl || '/'
+    const pageTimer = createTimedOperation(`page ${req.method} ${requestUrl}`, { log })
     try {
       const apiRoute = apiRouter.getPageByUrl(requestUrl)
       if (apiRoute) {
@@ -321,22 +455,60 @@ export async function startServer (options = {}) {
           res.status(404).send('Not found')
           return
         }
+        const loadEntryTimer = createTimedOperation(`SSR loadEntry ${pageRoute.id}`, { log })
         const mod = await loadEntry(pageEntry.entry)
+        loadEntryTimer.finish()
         if (typeof mod.render !== 'function') {
           res.status(503).type('text').send('SSR runtime unavailable')
           return
         }
-        const Layout = appLayout?.component ?? null
-        const layoutEntry = appLayout?.entry ?? null
+        const {
+          Layout,
+          layoutEntry,
+          layoutSlots,
+        } = resolvePageLayoutRender(layoutsById, pageEntry)
         const { language, messages, fallbackMessages } = resolveRequestLocale(pageRouter, requestUrl, buildDir, config)
-        // Page component → `shell:content` is resolved in page-runtime (SSR + hydrate).
+        let schemasForPage = cloneSerializable(manifest.schemas || [])
+        if (req.workspaceId && loadWorkspaceForEntitlements) {
+          const workspaceTimer = createTimedOperation(`SSR loadWorkspace ${req.workspaceId}`, { log })
+          try {
+            const workspace = await loadWorkspaceForEntitlements(req.workspaceId)
+            workspaceTimer.finish({ pageId: pageRoute.id })
+            if (workspace?.schemas?.length) {
+              schemasForPage = mergeWorkspaceSchemas(
+                schemasForPage,
+                cloneSerializable(workspace.schemas),
+              )
+            }
+          } catch (err) {
+            workspaceTimer.finish({
+              pageId: pageRoute.id,
+              error: err?.message ?? String(err),
+              timedOut: err instanceof OperationTimeoutError,
+            })
+            if (err instanceof OperationTimeoutError) {
+              log.warn('[@ossy/platform] SSR workspace schema merge timed out — using manifest schemas only', {
+                workspaceId: req.workspaceId,
+                pageId: pageRoute.id,
+                timeoutMs: err.timeoutMs,
+              })
+            } else {
+              log.warn('[@ossy/platform] Failed to merge workspace schemas for SSR', err)
+            }
+          }
+        }
+        // Page component → `app:content` is resolved in page-runtime (SSR + hydrate).
         const props = {
           ...config,
           ...(req.userAppSettings || {}),
           theme: req.userAppSettings?.theme || cloneSerializable(config?.theme),
           themes: cloneSerializable(config?.themes),
-          resourceTemplates: cloneSerializable(manifest.resourceTemplates),
+          schemas: schemasForPage,
           manifestSummary: cloneSerializable(manifestSummary),
+          capabilities: cloneSerializable(resolvedCapabilities),
+          actionRoutes: cloneSerializable(manifest.actionRoutes || {}),
+          taskCatalog: cloneSerializable(manifest.taskCatalog || []),
+          taskGraphEdges: cloneSerializable(manifest.taskGraphEdges || []),
           url: requestUrl,
           isAuthenticated: !!req.isAuthenticated,
           language,
@@ -349,18 +521,44 @@ export async function startServer (options = {}) {
           })),
           pageId: pageRoute.id,
           componentEntries: manifest.components,
+          resolveComponentEntry: (entry) => resolveEntryUrl(entry, buildDir),
           layoutSlots,
-          contentSlotName: CONTENT_SLOT_NAME,
           Layout,
           layoutEntry,
         }
-        const html = await mod.render(props)
+        const renderTimer = createTimedOperation(`SSR render ${pageRoute.id}`, { log })
+        let html
+        try {
+          html = await withTimeout(
+            mod.render(props),
+            SSR_RENDER_TIMEOUT_MS,
+            `SSR render(${pageRoute.id})`,
+          )
+        } catch (err) {
+          renderTimer.finish({ timedOut: err instanceof OperationTimeoutError })
+          if (err instanceof OperationTimeoutError) {
+            log.error('[@ossy/platform] SSR render timed out', {
+              pageId: pageRoute.id,
+              url: requestUrl,
+              timeoutMs: err.timeoutMs,
+            })
+            if (!res.headersSent) {
+              res.status(504).type('text').send('Page render timed out')
+            }
+            return
+          }
+          throw err
+        }
+        renderTimer.finish()
+        pageTimer.finish({ pageId: pageRoute.id, statusCode: 200 })
         res.status(200).type('html').send(html)
         return
       }
 
+      pageTimer.finish({ statusCode: 404 })
       res.status(404).send('Not found')
     } catch (err) {
+      pageTimer.finish({ error: err?.message ?? String(err) })
       log.error('Request handling failed', undefined, err)
       if (!res.headersSent) {
         res.status(500).type('text').send('Internal Server Error')
@@ -377,7 +575,12 @@ export async function startServer (options = {}) {
   log.info(`Running on http://localhost:${port}`)
   log.info('Press Ctrl+C to stop.')
 
-  const closeServer = () => new Promise((resolve) => server.close(() => resolve()))
+  runStartupRebuild?.()
+
+  const closeServer = () => new Promise((resolve) => {
+    server.closeAllConnections?.()
+    server.close(() => resolve())
+  })
 
   let shuttingDown = false
   const handleShutdown = async (signal) => {
@@ -385,6 +588,10 @@ export async function startServer (options = {}) {
     shuttingDown = true
     log.info(`Received ${signal}, shutting down...`)
     try {
+      TaskService.stop()
+      closePushSseConnections()
+      await ChangeStream.stop()
+      await Mongo.closeConnection()
       await closeServer()
     } finally {
       process.exit(0)
@@ -399,11 +606,23 @@ export async function startServer (options = {}) {
 }
 
 export default startServer
+export { loadLayoutsById, resolvePageLayoutRender }
 export { ConfigService } from './config.service.js'
 export { ActionService } from './actions/action.service.js'
 export { IntegrationService } from './integration.service.js'
 export { StorageClient } from './storage/storage.client.js'
+export { originalObjectKey, derivativeObjectKey, assertStorageKey } from './storage/storage-keys.js'
 export { S3Client } from './storage/s3.client.js'
 export { LocalStorageClient } from './storage/local-storage.client.js'
-export { getSystemResourceTemplates } from './resources/resource-template.registry.js'
-export { normalizeAndValidateDocumentContent, validateResourceTemplatesForImport } from './resources/resource-template.validation.js'
+export { getSystemSchemas } from './resources/schema.registry.js'
+export { getPlatformSchema, initPlatformSchema, createSchemaEngine, schemaForWorkspace } from './resources/schema.service.js'
+export { validateSchemasForImport } from './resources/schema.validation.js'
+export {
+  USER_SETTINGS_COOKIE,
+  AUTH_COOKIE,
+  readUserAppSettings,
+  mergeUserAppSettingsCookie,
+  clearWorkspaceFromUserAppSettings,
+  setAuthCookie,
+  clearAuthCookie,
+} from './user-app-settings.js'

package/src/storage/filesystem-storage.client.js

@@ -0,0 +1,109 @@
+import path from 'path'
+import os from 'os'
+import { mkdir, writeFile, readFile, stat } from 'fs/promises'
+import { existsSync } from 'fs'
+import { assertStorageKey } from './storage-keys.js'
+import { createResourceReadUrl } from './resource-read-url.js'
+
+const DEV_FALLBACK_DIR = path.join(os.tmpdir(), 'ossy-local-media')
+
+export function resolveFilesystemStorageRoot (env = process.env) {
+  const dataDir = env.OSSY_DATA_DIR
+  if (dataDir) {
+    return path.join(path.resolve(dataDir), 'blobs')
+  }
+  return DEV_FALLBACK_DIR
+}
+
+function normalizeKey (keyOrShape) {
+  const Key = typeof keyOrShape === 'string' ? keyOrShape : keyOrShape?.Key
+  assertStorageKey(Key)
+  return Key
+}
+
+function keyToLocalPath (root, key) {
+  const filename = encodeURIComponent(key)
+  const resolved = path.resolve(root, filename)
+  const rootResolved = path.resolve(root)
+  if (!resolved.startsWith(`${rootResolved}${path.sep}`)) {
+    throw new Error('[FilesystemStorage] invalid key: path traversal detected')
+  }
+  return resolved
+}
+
+function buildUrl (key, env = process.env) {
+  return createResourceReadUrl(key, env)
+}
+
+export function createFilesystemStorageClient ({ root, env = process.env } = {}) {
+  const storageRoot = root ?? resolveFilesystemStorageRoot(env)
+
+  return {
+    backend: 'filesystem',
+    root: storageRoot,
+
+    createUploadUrl ({ Key }) {
+      return Promise.resolve(buildUrl(normalizeKey({ Key }), env))
+    },
+
+    createPresignedDownloadUrl (keyOrShape) {
+      const Key = normalizeKey(keyOrShape)
+      return Promise.resolve(buildUrl(Key, env))
+    },
+
+    createDownloadUrl (keyOrShape) {
+      const Key = normalizeKey(keyOrShape)
+      return buildUrl(Key, env)
+    },
+
+    async save (key, body) {
+      const Key = normalizeKey(key)
+      const localPath = keyToLocalPath(storageRoot, Key)
+      await mkdir(storageRoot, { recursive: true })
+      await writeFile(localPath, body)
+    },
+
+    async load (keyOrShape) {
+      const Key = normalizeKey(keyOrShape)
+      const localPath = keyToLocalPath(storageRoot, Key)
+      if (!existsSync(localPath)) return { buffer: null, exists: false }
+      const buffer = await readFile(localPath)
+      return { buffer, exists: true }
+    },
+
+    async headObject ({ Key }) {
+      const key = normalizeKey({ Key })
+      const localPath = keyToLocalPath(storageRoot, key)
+      const s = await stat(localPath).catch(() => null)
+      if (!s) throw Object.assign(new Error('Not Found'), { $metadata: { httpStatusCode: 404 } })
+      return { ContentLength: s.size }
+    },
+  }
+}
+
+/** @deprecated Use createFilesystemStorageClient — kept for direct imports. */
+export class LocalStorageClient {
+  static createUploadUrl (params) {
+    return createFilesystemStorageClient().createUploadUrl(params)
+  }
+
+  static createPresignedDownloadUrl (keyOrShape) {
+    return createFilesystemStorageClient().createPresignedDownloadUrl(keyOrShape)
+  }
+
+  static createDownloadUrl (keyOrShape) {
+    return createFilesystemStorageClient().createDownloadUrl(keyOrShape)
+  }
+
+  static save (key, body) {
+    return createFilesystemStorageClient().save(key, body)
+  }
+
+  static load (keyOrShape) {
+    return createFilesystemStorageClient().load(keyOrShape)
+  }
+
+  static headObject (params) {
+    return createFilesystemStorageClient().headObject(params)
+  }
+}