@ossy/app 0.15.1 → 0.15.4

package/README.md

@@ -41,17 +41,32 @@ Run `npx @ossy/cli dev` or `npx @ossy/cli build`.
 
 ## API routes
 
-Create `src/api.js` to define custom API endpoints. Each route must have `id`, `path`, and a `handle(req, res)` function:
+Define HTTP handlers as an array of `{ id, path, handle(req, res) }` objects (same shape the server passes to `@ossy/router`).
+
+**Split files (recommended):** add any number of `*.api.js` (or `.api.mjs` / `.api.cjs`) files under `src/` (nested dirs allowed). Each file’s **default export** is either one route object or an array of routes. They are merged: `src/api.js` first (if present), then each `*.api.js` in lexicographic file path order.
+
+**Legacy single file:** `src/api.js` default export is still supported. If it exists, its routes are merged **first**, then every `*.api.js`.
+
+At build/dev time this becomes `.ossy-api.generated.js` (gitignored) whenever you have `src/api.js` and/or any `*.api.js`, so the Rollup entry stays stable when you add or remove split files.
+
+**Override:** pass `--api-source ./path/to/file.js` to use a single file and skip discovery.
+
+Example `src/health.api.js`:
 
 ```js
-export default [
-  {
-    id: 'health',
-    path: '/api/health',
-    handle(req, res) {
-      res.json({ status: 'ok' })
-    },
+export default {
+  id: 'health',
+  path: '/api/health',
+  handle(req, res) {
+    res.json({ status: 'ok' })
   },
+}
+```
+
+Example `src/api.js` (optional aggregate or empty `[]`):
+
+```js
+export default [
   {
     id: 'users',
     path: '/api/users',
@@ -64,6 +79,18 @@ export default [
 
 API routes are matched before the app is rendered. The router supports dynamic segments (e.g. `path: '/api/users/:id'`); extract params from `req.originalUrl` if needed. Use paths that don't conflict with `/@ossy/*` (reserved for the internal proxy).
 
+## Background worker tasks (`*.task.js`)
+
+For long-running job processors (separate from the SSR server), use **`npx @ossy/cli build --worker`** in a package that only needs the worker. It uses the same Rollup + Babel pipeline as `ossy build`, discovers **`*.task.js`** (and `.task.mjs` / `.task.cjs`) under `src/` (or `--pages <dir>`), and writes **`.ossy-tasks.generated.js`** (gitignored) when needed—same idea as `*.api.js` + `.ossy-api.generated.js`.
+
+Optional legacy aggregate: **`src/tasks.js`** default export is merged **first**, then each `*.task.js` in path order.
+
+Each task file’s **default export** is `{ type, handler }` where `type` matches the platform job type string, and `handler` is `async ({ sdk, job }) => { ... }` (see `@ossy/worker` for examples).
+
+**Override:** `--task-source ./path/to/tasks.js` skips discovery and uses a single file.
+
+Output: **`build/worker.js`**. Run with `node build/worker.js` (after `import 'dotenv/config'` via the entry). Set `OSSY_WORKSPACE_ID`, `OSSY_API_URL`, and `OSSY_API_TOKEN` as before.
+
 ## Port configuration
 
 By default, the server listens on port **3000**.

package/cli/build.js

@@ -15,9 +15,206 @@ import replace from '@rollup/plugin-replace';
 import remove from 'rollup-plugin-delete';
 import arg from 'arg'
 import { ensureBuildStubs } from '../scripts/ensure-build-stubs.mjs'
+import { builtinModules, createRequire } from 'node:module'
 // import inject from '@rollup/plugin-inject'
 
 const PAGE_FILE_PATTERN = /\.page\.(jsx?|tsx?)$/
+const API_FILE_PATTERN = /\.api\.(mjs|cjs|js)$/
+const TASK_FILE_PATTERN = /\.task\.(mjs|cjs|js)$/
+
+export function discoverApiFiles(srcDir) {
+  const dir = path.resolve(srcDir)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return []
+  }
+  const files = []
+  const walk = (d) => {
+    const entries = fs.readdirSync(d, { withFileTypes: true })
+    for (const e of entries) {
+      const full = path.join(d, e.name)
+      if (e.isDirectory()) walk(full)
+      else if (API_FILE_PATTERN.test(e.name)) files.push(full)
+    }
+  }
+  walk(dir)
+  return files.sort()
+}
+
+export function discoverTaskFiles(srcDir) {
+  const dir = path.resolve(srcDir)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return []
+  }
+  const files = []
+  const walk = (d) => {
+    const entries = fs.readdirSync(d, { withFileTypes: true })
+    for (const e of entries) {
+      const full = path.join(d, e.name)
+      if (e.isDirectory()) walk(full)
+      else if (TASK_FILE_PATTERN.test(e.name)) files.push(full)
+    }
+  }
+  walk(dir)
+  return files.sort()
+}
+
+/**
+ * Merges `src/api.js` (optional) and every `*.api.js` under the pages tree into one default export array
+ * for the Ossy API router ({ id, path, handle }).
+ */
+export function generateApiModule({ cwd, apiFiles, legacyPath }) {
+  const lines = [
+    '// Generated by @ossy/app — do not edit',
+    '',
+  ]
+  const hasLegacy = legacyPath && fs.existsSync(legacyPath)
+  if (hasLegacy) {
+    const rel = path.relative(cwd, legacyPath).replace(/\\/g, '/')
+    lines.push(`import _legacyApi from './${rel}'`)
+  }
+  apiFiles.forEach((f, i) => {
+    const rel = path.relative(cwd, f).replace(/\\/g, '/')
+    lines.push(`import * as _api${i} from './${rel}'`)
+  })
+  lines.push(
+    '',
+    'function _normalizeApiExport(mod) {',
+    '  const d = mod?.default',
+    '  if (d == null) return []',
+    '  return Array.isArray(d) ? d : [d]',
+    '}',
+    '',
+    'export default [',
+  )
+  const parts = []
+  if (hasLegacy) {
+    parts.push('  ..._normalizeApiExport({ default: _legacyApi }),')
+  }
+  apiFiles.forEach((_, i) => {
+    parts.push(`  ..._normalizeApiExport(_api${i}),`)
+  })
+  lines.push(parts.join('\n'))
+  lines.push(']')
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * Resolves the Rollup entry for @ossy/api/source-file and which files to scan for the build overview.
+ */
+export function resolveApiSource({ cwd, pagesOpt, scriptDir, explicitApiSource }) {
+  const srcDir = path.resolve(cwd, pagesOpt)
+  const legacyPath = path.resolve(cwd, 'src/api.js')
+  const defaultStub = path.resolve(scriptDir, 'api.js')
+  const generatedPath = path.join(cwd, '.ossy-api.generated.js')
+
+  if (explicitApiSource) {
+    const p = path.isAbsolute(explicitApiSource)
+      ? explicitApiSource
+      : path.resolve(cwd, explicitApiSource)
+    if (fs.existsSync(p)) {
+      return { apiSourcePath: p, apiOverviewFiles: [p], usedGenerated: false }
+    }
+    return { apiSourcePath: defaultStub, apiOverviewFiles: [], usedGenerated: false }
+  }
+
+  const apiFiles = discoverApiFiles(srcDir)
+  const hasLegacy = fs.existsSync(legacyPath)
+  // Always feed Rollup the same entry (`.ossy-api.generated.js`) when there is any API surface,
+  // so adding/removing `*.api.js` does not require changing the replace target mid-dev.
+  if (apiFiles.length > 0 || hasLegacy) {
+    fs.writeFileSync(
+      generatedPath,
+      generateApiModule({
+        cwd,
+        apiFiles,
+        legacyPath: hasLegacy ? legacyPath : null,
+      })
+    )
+    const overview = [...(hasLegacy ? [legacyPath] : []), ...apiFiles]
+    return { apiSourcePath: generatedPath, apiOverviewFiles: overview, usedGenerated: true }
+  }
+
+  return { apiSourcePath: defaultStub, apiOverviewFiles: [], usedGenerated: false }
+}
+
+/**
+ * Merges `src/tasks.js` (optional) and every `*.task.js` under `src/` into one default export array
+ * of job handlers `{ type, handler }` for the Ossy worker.
+ */
+export function generateTaskModule({ cwd, taskFiles, legacyPath }) {
+  const lines = [
+    '// Generated by @ossy/app — do not edit',
+    '',
+  ]
+  const hasLegacy = legacyPath && fs.existsSync(legacyPath)
+  if (hasLegacy) {
+    const rel = path.relative(cwd, legacyPath).replace(/\\/g, '/')
+    lines.push(`import _legacyTasks from './${rel}'`)
+  }
+  taskFiles.forEach((f, i) => {
+    const rel = path.relative(cwd, f).replace(/\\/g, '/')
+    lines.push(`import * as _task${i} from './${rel}'`)
+  })
+  lines.push(
+    '',
+    'function _normalizeTaskExport(mod) {',
+    '  const d = mod?.default',
+    '  if (d == null) return []',
+    '  return Array.isArray(d) ? d : [d]',
+    '}',
+    '',
+    'export default [',
+  )
+  const parts = []
+  if (hasLegacy) {
+    parts.push('  ..._normalizeTaskExport({ default: _legacyTasks }),')
+  }
+  taskFiles.forEach((_, i) => {
+    parts.push(`  ..._normalizeTaskExport(_task${i}),`)
+  })
+  lines.push(parts.join('\n'))
+  lines.push(']')
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * Resolves the Rollup entry for @ossy/tasks/source-file and which files to list in the worker build overview.
+ */
+export function resolveTaskSource({ cwd, pagesOpt, scriptDir, explicitTaskSource }) {
+  const srcDir = path.resolve(cwd, pagesOpt)
+  const legacyPath = path.resolve(cwd, 'src/tasks.js')
+  const defaultStub = path.resolve(scriptDir, 'tasks.js')
+  const generatedPath = path.join(cwd, '.ossy-tasks.generated.js')
+
+  if (explicitTaskSource) {
+    const p = path.isAbsolute(explicitTaskSource)
+      ? explicitTaskSource
+      : path.resolve(cwd, explicitTaskSource)
+    if (fs.existsSync(p)) {
+      return { taskSourcePath: p, taskOverviewFiles: [p], usedGenerated: false }
+    }
+    return { taskSourcePath: defaultStub, taskOverviewFiles: [], usedGenerated: false }
+  }
+
+  const taskFiles = discoverTaskFiles(srcDir)
+  const hasLegacy = fs.existsSync(legacyPath)
+  if (taskFiles.length > 0 || hasLegacy) {
+    fs.writeFileSync(
+      generatedPath,
+      generateTaskModule({
+        cwd,
+        taskFiles,
+        legacyPath: hasLegacy ? legacyPath : null,
+      })
+    )
+    const overview = [...(hasLegacy ? [legacyPath] : []), ...taskFiles]
+    return { taskSourcePath: generatedPath, taskOverviewFiles: overview, usedGenerated: true }
+  }
+
+  return { taskSourcePath: defaultStub, taskOverviewFiles: [], usedGenerated: false }
+}
 
 export function discoverPageFiles(srcDir) {
   const dir = path.resolve(srcDir)
@@ -75,6 +272,65 @@ export function generatePagesModule(pageFiles, cwd, srcDir = 'src') {
   return lines.join('\n')
 }
 
+export async function discoverModulePageFiles({ cwd, configPath }) {
+  if (!configPath || !fs.existsSync(configPath)) return []
+  try {
+    // Try a cheap static parse first so we don't depend on the config file being
+    // importable (configs often import theme/template modules that may not be
+    // resolvable in the build-time node context).
+    const cfgSource = fs.readFileSync(configPath, 'utf8')
+    const modules = []
+
+    // pagesModules: ['a', "b"]
+    const arrMatch = cfgSource.match(/pagesModules\s*:\s*\[([^\]]*)\]/m)
+    if (arrMatch?.[1]) {
+      const body = arrMatch[1]
+      const re = /['"]([^'"]+)['"]/g
+      let m
+      while ((m = re.exec(body)) !== null) modules.push(m[1])
+    }
+
+    // pagesModule: 'a'
+    if (modules.length === 0) {
+      const singleMatch = cfgSource.match(/pagesModule\s*:\s*['"]([^'"]+)['"]/m)
+      if (singleMatch?.[1]) modules.push(singleMatch[1])
+    }
+
+    if (modules.length) {
+      const req = createRequire(path.resolve(cwd, 'package.json'))
+      const files = []
+      for (const name of modules) {
+        const pkgJsonPath = req.resolve(`${name}/package.json`)
+        const pkgDir = path.dirname(pkgJsonPath)
+        const modulePagesDir = path.join(pkgDir, 'src', 'pages')
+        files.push(...discoverPageFiles(modulePagesDir))
+      }
+      return files
+    }
+
+    const mod = await import(url.pathToFileURL(configPath))
+    const cfg = mod?.default ?? mod ?? {}
+    const modules2 = Array.isArray(cfg.pagesModules)
+      ? cfg.pagesModules
+      : (typeof cfg.pagesModule === 'string' ? [cfg.pagesModule] : [])
+
+    if (!modules2.length) return []
+
+    const req = createRequire(path.resolve(cwd, 'package.json'))
+    const files = []
+    for (const name of modules2) {
+      const pkgJsonPath = req.resolve(`${name}/package.json`)
+      const pkgDir = path.dirname(pkgJsonPath)
+      const modulePagesDir = path.join(pkgDir, 'src', 'pages')
+      files.push(...discoverPageFiles(modulePagesDir))
+    }
+    return files
+  } catch (e) {
+    console.warn('[@ossy/app][build] pagesModules config could not be loaded; continuing without modules')
+    return []
+  }
+}
+
 export function parsePagesFromSource(filePath) {
   try {
     const content = fs.readFileSync(filePath, 'utf8')
@@ -108,7 +364,14 @@ export function parsePagesFromSource(filePath) {
   }
 }
 
-export function printBuildOverview({ pagesSourcePath, apiSourcePath, configPath, isPageFiles, pageFiles }) {
+export function printBuildOverview({
+  pagesSourcePath,
+  apiSourcePath,
+  apiOverviewFiles = [],
+  configPath,
+  isPageFiles,
+  pageFiles,
+}) {
   const rel = (p) => path.relative(process.cwd(), p)
   const cwd = process.cwd()
   const srcDir = path.resolve(cwd, 'src')
@@ -118,6 +381,7 @@ export function printBuildOverview({ pagesSourcePath, apiSourcePath, configPath,
   if (fs.existsSync(configPath)) {
     console.log(`  \x1b[36mConfig:\x1b[0m ${rel(configPath)}`)
   }
+  console.log(`  \x1b[36mAPI:\x1b[0m ${rel(apiSourcePath)}`)
   console.log('  ' + '─'.repeat(50))
 
   const pages = isPageFiles && pageFiles?.length
@@ -136,21 +400,127 @@ export function printBuildOverview({ pagesSourcePath, apiSourcePath, configPath,
     console.log('  \x1b[33mRoutes:\x1b[0m (could not parse or empty)')
   }
 
-  if (fs.existsSync(apiSourcePath)) {
-    const apiRoutes = parsePagesFromSource(apiSourcePath)
-    if (apiRoutes.length > 0) {
-      console.log('  \x1b[36mAPI routes:\x1b[0m')
-      apiRoutes.forEach((r) => {
-        console.log(`    ${r.id}  ${r.path}`)
-      })
-    }
+  const apiFilesToScan =
+    apiOverviewFiles?.length > 0
+      ? apiOverviewFiles
+      : fs.existsSync(apiSourcePath)
+        ? [apiSourcePath]
+        : []
+  const apiRoutes = []
+  for (const f of apiFilesToScan) {
+    if (fs.existsSync(f)) apiRoutes.push(...parsePagesFromSource(f))
+  }
+  if (apiRoutes.length > 0) {
+    console.log('  \x1b[36mAPI routes:\x1b[0m')
+    apiRoutes.forEach((r) => {
+      console.log(`    ${r.id}  ${r.path}`)
+    })
   }
   console.log('  ' + '─'.repeat(50) + '\n')
 }
 
-export const build = async (cliArgs) => {
-    console.log('[@ossy/app][build] Starting...')
+const WORKER_EXTERNAL_IDS = new Set([
+  ...builtinModules,
+  ...builtinModules.map((m) => `node:${m}`),
+  'dotenv',
+  'dotenv/config',
+  '@ossy/sdk',
+  'openai',
+  'sharp',
+])
+
+function isWorkerExternal(id) {
+  if (id.startsWith('.') || path.isAbsolute(id)) return false
+  if (WORKER_EXTERNAL_IDS.has(id)) return true
+  if (id.startsWith('node:')) return true
+  if (id === '@ossy/sdk' || id.startsWith('@ossy/sdk/')) return true
+  if (id === 'openai' || id.startsWith('openai/')) return true
+  if (id === 'sharp' || id.startsWith('sharp/')) return true
+  if (id === 'dotenv' || id.startsWith('dotenv/')) return true
+  return false
+}
+
+/**
+ * Worker-only bundle: discovers `*.task.js` (and optional `src/tasks.js`), writes `.ossy-tasks.generated.js`
+ * when needed, and emits `build/worker.js`. Invoke via `npx @ossy/cli build --worker`.
+ */
+export async function buildWorker(cliArgs) {
+  console.log('[@ossy/app][build][worker] Starting...')
+
+  const workerArgv = cliArgs.filter((a) => a !== '--worker')
+  const options = arg(
+    {
+      '--pages': String,
+      '--p': '--pages',
+      '--destination': String,
+      '--d': '--destination',
+      '--task-source': String,
+    },
+    { argv: workerArgv }
+  )
+
+  const scriptDir = path.dirname(url.fileURLToPath(import.meta.url))
+  const cwd = process.cwd()
+  const pagesOpt = options['--pages'] || 'src'
+  const buildPath = path.resolve(options['--destination'] || 'build')
+  const { taskSourcePath, taskOverviewFiles, usedGenerated } = resolveTaskSource({
+    cwd,
+    pagesOpt,
+    scriptDir,
+    explicitTaskSource: options['--task-source'],
+  })
+
+  const workerEntryPath = path.resolve(scriptDir, 'worker-entry.js')
+  if (!fs.existsSync(workerEntryPath)) {
+    throw new Error(`[@ossy/app][build][worker] Missing worker entry: ${workerEntryPath}`)
+  }
+
+  console.log('\n  \x1b[1mWorker build\x1b[0m')
+  console.log('  ' + '─'.repeat(50))
+  console.log(`  \x1b[36mTasks module:\x1b[0m ${path.relative(cwd, taskSourcePath)}`)
+  if (taskOverviewFiles.length > 0) {
+    console.log('  \x1b[36mTask files:\x1b[0m')
+    taskOverviewFiles.forEach((f) => console.log(`    ${path.relative(cwd, f)}`))
+  } else if (!usedGenerated) {
+    console.log('  \x1b[33m(no *.task.js; using empty task list stub)\x1b[0m')
+  }
+  console.log('  ' + '─'.repeat(50) + '\n')
+
+  const bundle = await rollup({
+    input: workerEntryPath,
+    external: isWorkerExternal,
+    plugins: [
+      remove({ targets: buildPath }),
+      replace({
+        preventAssignment: true,
+        delimiters: ['%%', '%%'],
+        '@ossy/tasks/source-file': taskSourcePath,
+      }),
+      replace({
+        preventAssignment: true,
+        'process.env.NODE_ENV': JSON.stringify('production'),
+      }),
+      json(),
+      resolveCommonJsDependencies(),
+      resolveDependencies({ preferBuiltins: true }),
+      babel({
+        babelHelpers: 'bundled',
+        presets: ['@babel/preset-env', '@babel/preset-react'],
+      }),
+    ],
+  })
+
+  await bundle.write({
+    dir: buildPath,
+    entryFileNames: 'worker.js',
+    chunkFileNames: '[name]-[hash].js',
+    format: 'esm',
+  })
 
+  console.log('[@ossy/app][build][worker] Finished')
+}
+
+export const build = async (cliArgs) => {
     const options = arg({
         '--pages': String,
         '--p': '--pages',
@@ -160,22 +530,34 @@ export const build = async (cliArgs) => {
     
         '--config': String,
         '-c': '--config',
+
+        '--api-source': String,
+        '--worker': Boolean,
+        '--task-source': String,
       }, { argv: cliArgs })
 
+    if (options['--worker']) {
+      return buildWorker(cliArgs)
+    }
+
+    console.log('[@ossy/app][build] Starting...')
+
 
     const scriptDir = path.dirname(url.fileURLToPath(import.meta.url))
     const cwd = process.cwd()
     const pagesOpt = options['--pages'] || 'src'
     const srcDir = path.resolve(pagesOpt)
+    const configPath = path.resolve(options['--config'] || 'src/config.js');
     const pageFiles = discoverPageFiles(srcDir)
+    const modulePageFiles = await discoverModulePageFiles({ cwd, configPath })
     const pagesJsxPath = path.resolve('src/pages.jsx')
     const hasPagesJsx = fs.existsSync(pagesJsxPath)
 
     let effectivePagesSource
     let isPageFiles = false
-    if (pageFiles.length > 0) {
+    if (pageFiles.length > 0 || modulePageFiles.length > 0) {
       const generatedPath = path.join(cwd, '.ossy-pages.generated.jsx')
-      fs.writeFileSync(generatedPath, generatePagesModule(pageFiles, cwd, pagesOpt))
+      fs.writeFileSync(generatedPath, generatePagesModule([...pageFiles, ...modulePageFiles], cwd, pagesOpt))
       effectivePagesSource = generatedPath
       isPageFiles = true
     } else if (hasPagesJsx) {
@@ -184,9 +566,17 @@ export const build = async (cliArgs) => {
       throw new Error(`[@ossy/app][build] No pages found. Create *.page.jsx files in src/, or src/pages.jsx`);
     }
 
-    let apiSourcePath = path.resolve(options['--api-source'] || 'src/api.js');
+    const {
+      apiSourcePath: resolvedApi,
+      apiOverviewFiles,
+    } = resolveApiSource({
+      cwd,
+      pagesOpt,
+      scriptDir,
+      explicitApiSource: options['--api-source'],
+    })
+    let apiSourcePath = resolvedApi
     let middlewareSourcePath = path.resolve(options['--middleware-source'] || 'src/middleware.js');
-    const configPath = path.resolve(options['--config'] || 'src/config.js');
     const buildPath = path.resolve(options['--destination'] || 'build');
     const publicDir = path.resolve('public')
 
@@ -196,7 +586,14 @@ export const build = async (cliArgs) => {
     const inputFiles = [inputClient, inputServer]
 
     const appEntryPath = path.resolve(scriptDir, 'default-app.jsx')
-    printBuildOverview({ pagesSourcePath: effectivePagesSource, apiSourcePath, configPath, isPageFiles, pageFiles: isPageFiles ? pageFiles : [] });
+    printBuildOverview({
+      pagesSourcePath: effectivePagesSource,
+      apiSourcePath,
+      apiOverviewFiles,
+      configPath,
+      isPageFiles,
+      pageFiles: isPageFiles ? pageFiles : [],
+    });
 
     if (!fs.existsSync(apiSourcePath)) {
       apiSourcePath = path.resolve(scriptDir, 'api.js')

package/cli/dev.js

@@ -1,15 +1,17 @@
 import path from 'path';
 import url from 'url';
 import fs from 'fs';
-import { printBuildOverview, discoverPageFiles, generatePagesModule } from './build.js';
+import {
+  printBuildOverview,
+  discoverPageFiles,
+  generatePagesModule,
+  discoverModulePageFiles,
+  resolveApiSource,
+} from './build.js';
 import { watch } from 'rollup';
 import babel from '@rollup/plugin-babel';
 import { nodeResolve as resolveDependencies } from '@rollup/plugin-node-resolve'
 import resolveCommonJsDependencies from '@rollup/plugin-commonjs'
-import removeOwnPeerDependencies from 'rollup-plugin-peer-deps-external'
-import minifyJS from '@rollup/plugin-terser'
-// import typescript from '@rollup/plugin-typescript'
-import preserveDirectives from "rollup-plugin-preserve-directives"
 import json from "@rollup/plugin-json"
 import copy from 'rollup-plugin-copy';
 import replace from '@rollup/plugin-replace';
@@ -30,6 +32,8 @@ export const dev = async (cliArgs) => {
     
         '--config': String,
         '-c': '--config',
+
+        '--api-source': String,
       }, { argv: cliArgs, permissive: true })
 
 
@@ -37,15 +41,17 @@ export const dev = async (cliArgs) => {
     const cwd = process.cwd()
     const pagesOpt = options['--pages'] || 'src'
     const srcDir = path.resolve(pagesOpt)
+    const configPath = path.resolve(options['--config'] || 'src/config.js');
     const pageFiles = discoverPageFiles(srcDir)
+    const modulePageFiles = await discoverModulePageFiles({ cwd, configPath })
     const pagesJsxPath = path.resolve('src/pages.jsx')
     const hasPagesJsx = fs.existsSync(pagesJsxPath)
 
     let effectivePagesSource
     let isPageFiles = false
-    if (pageFiles.length > 0) {
+    if (pageFiles.length > 0 || modulePageFiles.length > 0) {
       const generatedPath = path.join(cwd, '.ossy-pages.generated.jsx')
-      fs.writeFileSync(generatedPath, generatePagesModule(pageFiles, cwd, pagesOpt))
+      fs.writeFileSync(generatedPath, generatePagesModule([...pageFiles, ...modulePageFiles], cwd, pagesOpt))
       effectivePagesSource = generatedPath
       isPageFiles = true
     } else if (hasPagesJsx) {
@@ -54,9 +60,17 @@ export const dev = async (cliArgs) => {
       throw new Error(`[@ossy/app][dev] No pages found. Create *.page.jsx files in src/, or src/pages.jsx`);
     }
 
-    let apiSourcePath = path.resolve(options['--api-source'] || 'src/api.js');
+    const {
+      apiSourcePath: resolvedApi,
+      apiOverviewFiles,
+    } = resolveApiSource({
+      cwd,
+      pagesOpt,
+      scriptDir,
+      explicitApiSource: options['--api-source'],
+    })
+    let apiSourcePath = resolvedApi
     let middlewareSourcePath = path.resolve(options['--middleware-source'] || 'src/middleware.js');
-    const configPath = path.resolve(options['--config'] || 'src/config.js');
     const buildPath = path.resolve(options['--destination'] || 'build');
     const publicDir = path.resolve('public')
 
@@ -65,7 +79,14 @@ export const dev = async (cliArgs) => {
 
     const inputFiles = [inputClient, inputServer]
 
-    printBuildOverview({ pagesSourcePath: effectivePagesSource, apiSourcePath, configPath, isPageFiles, pageFiles: isPageFiles ? pageFiles : [] });
+    printBuildOverview({
+      pagesSourcePath: effectivePagesSource,
+      apiSourcePath,
+      apiOverviewFiles,
+      configPath,
+      isPageFiles,
+      pageFiles: isPageFiles ? pageFiles : [],
+    });
 
     if (!fs.existsSync(apiSourcePath)) {
       apiSourcePath = path.resolve(scriptDir, 'api.js')
@@ -202,15 +223,32 @@ export const dev = async (cliArgs) => {
       }
     })
 
-    if (isPageFiles) {
-      fs.watch(srcDir, { recursive: true }, (eventType, filename) => {
-        if (filename && /\.page\.(jsx?|tsx?)$/.test(filename)) {
-          const files = discoverPageFiles(srcDir)
-          if (files.length > 0) {
-            const generatedPath = path.join(cwd, '.ossy-pages.generated.jsx')
-            fs.writeFileSync(generatedPath, generatePagesModule(files, cwd, pagesOpt))
-          }
-        }
+    const regenApiBundle = () => {
+      if (options['--api-source']) return
+      resolveApiSource({
+        cwd,
+        pagesOpt,
+        scriptDir,
+        explicitApiSource: undefined,
       })
+      const gen = path.resolve(cwd, '.ossy-api.generated.js')
+      if (fs.existsSync(gen) && typeof watcher?.invalidate === 'function') {
+        watcher.invalidate(gen)
+      }
     }
-};
+
+    fs.watch(srcDir, { recursive: true }, (eventType, filename) => {
+      if (!filename) return
+      if (/\.page\.(jsx?|tsx?)$/.test(filename)) {
+        if (!isPageFiles) return
+        const files = discoverPageFiles(srcDir)
+        if (files.length > 0) {
+          const generatedPath = path.join(cwd, '.ossy-pages.generated.jsx')
+          fs.writeFileSync(generatedPath, generatePagesModule(files, cwd, pagesOpt))
+        }
+      }
+      if (/\.api\.(mjs|cjs|js)$/.test(filename) || /(^|\/)api\.js$/.test(filename.replace(/\\/g, '/'))) {
+        regenApiBundle()
+      }
+    })
+};

package/cli/tasks.js

@@ -0,0 +1,2 @@
+/** Stub when no `*.task.js` / `src/tasks.js` — replaced at build time when tasks exist. */
+export default []

package/cli/worker-entry.js

@@ -0,0 +1,5 @@
+import 'dotenv/config'
+import taskHandlers from '%%@ossy/tasks/source-file%%'
+import { runWorkerScheduler } from './worker-runtime.js'
+
+runWorkerScheduler(taskHandlers)

package/cli/worker-runtime.js

@@ -0,0 +1,120 @@
+import { SDK } from '@ossy/sdk'
+
+/**
+ * @param {Array<{ type: string, handler: (ctx: { sdk: import('@ossy/sdk').SDK, job: Record<string, unknown> }) => Promise<void> }>} handlers
+ */
+export function runWorkerScheduler(handlers) {
+  const sdk = SDK.of({
+    workspaceId: process.env.OSSY_WORKSPACE_ID,
+    apiUrl: process.env.OSSY_API_URL,
+    authorization: process.env.OSSY_API_TOKEN,
+  })
+
+  const jobsClient = /** @type {{ getUnprocessed: () => Promise<unknown[]> }} */ (sdk.jobs)
+
+  let status = 'running'
+
+  console.log('Starting scheduler')
+
+  main()
+
+  setInterval(() => {
+    if (status === 'running') return
+    status = 'running'
+    try {
+      main()
+    } catch (error) {
+      console.log('Error running main')
+      console.error(error)
+      status = 'idle'
+    }
+  }, 3000)
+
+  function main() {
+    console.log('Looking for jobs')
+    jobsClient
+      .getUnprocessed()
+      .then(async (jobs) => {
+        if (!jobs || !jobs.length) {
+          console.log('No jobs found, going idle')
+          status = 'idle'
+          return
+        }
+
+        const jobsGroupedByResourceId = groupJobsByResourceId(jobs)
+
+        console.log(`Found ${jobs.length} jobs between ${jobsGroupedByResourceId.length} resources`)
+
+        const processedGroups = jobsGroupedByResourceId.map(([resourceId, groupJobs]) => {
+          console.log(`Processing group for resourceId ${resourceId}`)
+          return processJobsSequentially(groupJobs)
+            .then(() => console.log(`Completed group for resourceId ${resourceId}`))
+            .catch((err) => {
+              console.log(`Failed to process group for resourceId ${resourceId}`)
+              console.error(err)
+            })
+        })
+
+        try {
+          await Promise.allSettled(processedGroups)
+
+          console.log(`Finished processing of groups...`)
+          console.log('Going idle')
+          status = 'idle'
+          console.log('----------------------------------')
+          console.groupEnd()
+        } catch (error) {
+          console.log('Error processing groups')
+          console.error(error)
+          status = 'idle'
+        }
+      })
+      .catch((error) => {
+        console.log('Error getting jobs')
+        console.error(error)
+        status = 'idle'
+      })
+  }
+
+  function groupJobsByResourceId(jobList) {
+    return Object.entries(
+      jobList.reduce((acc, job) => {
+        const content = /** @type {{ resourceId?: string }} */ (job.content || {})
+        const rid = content.resourceId
+        return {
+          ...acc,
+          [rid]: [...(acc[rid] || []), job],
+        }
+      }, /** @type {Record<string, unknown[]>} */ ({}))
+    )
+  }
+
+  async function processJobsSequentially(jobList) {
+    console.log(`Processing ${jobList.length} jobs`)
+    for (const job of jobList) {
+      console.log(`Processing job ${job.id}`)
+      const handler = handlers.find((h) => h.type === job.type)
+
+      if (!handler) {
+        console.log('No handler found for job', job.id)
+        continue
+      }
+
+      console.log(`Handler found for ${handler.type}`)
+
+      try {
+        console.log('create sdk')
+        const jobSdk = SDK.of({
+          workspaceId: job.belongsTo,
+          authorization: process.env.OSSY_API_TOKEN,
+        })
+        console.log('created sdk')
+
+        await handler.handler({ sdk: jobSdk, job }).catch(() => {})
+      } catch (error) {
+        console.error(error)
+        console.log('Failed to processing job')
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "0.15.1",
+  "version": "0.15.4",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -66,5 +66,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "19917b325524994f304813ba9d81e52a79da544e"
+  "gitHead": "f9c6ce7e08475bc0c96cae92e1eff3404964e315"
 }

package/src/index.js

@@ -1,2 +1,2 @@
-export { build } from '../cli/build.js'
+export { build, buildWorker } from '../cli/build.js'
 export { dev } from '../cli/dev.js'

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Ossy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.