@jseeio/jsee 0.8.2 → 0.8.8

package/src/cli.js

@@ -2,10 +2,11 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const crypto = require('crypto')
+const Module = require('module')
 
 const minimist = require('minimist')
 
-const { getModelFuncJS, sanitizeName, generateOpenAPISpec, serializeResult, parseMultipart, fileExtToOutputType } = require('./utils.js')
+const { getModelFuncJS, sanitizeName, isRecordObject, normalizeFileOutputValue, generateOpenAPISpec, serializeResult, parseMultipart, fileExtToOutputType } = require('./utils.js')
 
 let jsdoc2md
 function getJsdocToMarkdown () {
@@ -69,6 +70,137 @@ function readDirListing (resolved, relative) {
     }))
 }
 
+function isPackageSpecifier (value) {
+  if (typeof value !== 'string') return false
+  if (!value || value.startsWith('.') || value.startsWith('/') || value.startsWith('file:')) return false
+  if (isHttpUrl(value)) return false
+  if (value.includes('\\')) return false
+  if (value.startsWith('@')) {
+    return /^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(value)
+  }
+  return /^[A-Za-z0-9._-]+$/.test(value)
+}
+
+function looksLikeMissingPackageInput (value, cwd) {
+  if (!isPackageSpecifier(value)) return false
+  if (value.includes('.json') || value.includes('.js')) return false
+  return !fs.existsSync(path.resolve(cwd, value))
+}
+
+function getPackageInputInstallHint (specifier) {
+  return `npx -p @jseeio/jsee -p ${specifier} jsee ${specifier} --serve`
+}
+
+function resolvePackageJsonPath (specifier, cwd) {
+  const resolver = Module.createRequire(path.join(cwd, '__jsee_resolve__.js'))
+  const searchPaths = resolver.resolve.paths(specifier) || []
+
+  for (const base of searchPaths) {
+    const candidate = path.join(base, specifier, 'package.json')
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate
+  }
+
+  try {
+    return require.resolve(`${specifier}/package.json`, { paths: [cwd] })
+  } catch (error) {
+    return null
+  }
+}
+
+function readJseePackageInput (specifier, packageJsonPath) {
+  const packageRoot = path.dirname(packageJsonPath)
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+  const appConfig = packageJson.jsee
+  let schemaRel
+  let descriptionRel
+
+  if (typeof appConfig === 'string') {
+    schemaRel = appConfig
+  } else if (appConfig && typeof appConfig === 'object') {
+    schemaRel = appConfig.schema || appConfig.input || appConfig.inputs
+    descriptionRel = appConfig.description
+  }
+
+  if (!schemaRel) {
+    throw new Error(`${specifier} does not declare a JSEE app. Add "jsee": "schema.json" to its package.json.`)
+  }
+
+  const schemaPath = path.resolve(packageRoot, schemaRel)
+  if (!fs.existsSync(schemaPath) || !fs.statSync(schemaPath).isFile()) {
+    throw new Error(`${specifier} declares JSEE schema ${schemaRel}, but the file was not found.`)
+  }
+
+  let descriptionPath = null
+  if (descriptionRel) {
+    descriptionPath = path.resolve(packageRoot, descriptionRel)
+  } else {
+    const readmePath = path.join(packageRoot, 'README.md')
+    if (fs.existsSync(readmePath) && fs.statSync(readmePath).isFile()) descriptionPath = readmePath
+  }
+
+  return {
+    packageName: packageJson.name || specifier,
+    packageRoot,
+    schemaPath,
+    descriptionPath
+  }
+}
+
+function resolveJseePackageInput (specifier, cwd) {
+  if (!isPackageSpecifier(specifier)) return null
+
+  const packageJsonPath = resolvePackageJsonPath(specifier, cwd)
+  if (!packageJsonPath) return null
+
+  return readJseePackageInput(specifier, packageJsonPath)
+}
+
+function findPackageRoot (startDir) {
+  let dir = path.resolve(startDir)
+  if (fs.existsSync(dir) && fs.statSync(dir).isFile()) dir = path.dirname(dir)
+
+  while (true) {
+    const packageJsonPath = path.join(dir, 'package.json')
+    if (fs.existsSync(packageJsonPath) && fs.statSync(packageJsonPath).isFile()) return dir
+
+    const parent = path.dirname(dir)
+    if (parent === dir) throw new Error(`No package.json found from ${startDir}`)
+    dir = parent
+  }
+}
+
+function hasArgOption (args, names) {
+  return args.some(arg => names.some(name => arg === name || arg.startsWith(name + '=')))
+}
+
+async function runPackage (dirname, args=[]) {
+  if (!Array.isArray(args)) throw new Error('runPackage args must be an array')
+
+  const packageRoot = findPackageRoot(dirname)
+  const packageInput = readJseePackageInput(packageRoot, path.join(packageRoot, 'package.json'))
+  const pargv = []
+
+  if (!hasArgOption(args, ['--inputs', '-i'])) {
+    pargv.push('--inputs', packageInput.schemaPath)
+  }
+  if (!hasArgOption(args, ['--description', '-d']) && packageInput.descriptionPath) {
+    pargv.push('--description', packageInput.descriptionPath)
+  }
+  pargv.push(...args)
+
+  if (hasArgOption(args, ['--run'])) {
+    return await gen(pargv)
+  }
+
+  const previousCwd = process.cwd()
+  process.chdir(packageInput.packageRoot)
+  try {
+    return await gen(pargv)
+  } finally {
+    process.chdir(previousCwd)
+  }
+}
+
 function generateIdentitySchema (target, cwd) {
   const resolved = path.isAbsolute(target) ? target : path.join(cwd, target)
   const stat = fs.existsSync(resolved) ? fs.statSync(resolved) : null
@@ -259,6 +391,402 @@ function resolveOutputPath (cwd, outputPath) {
   return path.join(cwd, outputPath)
 }
 
+function writeOutputFile (cwd, outputPath, content) {
+  const resolved = resolveOutputPath(cwd, outputPath)
+  fs.mkdirSync(path.dirname(resolved), { recursive: true })
+  fs.writeFileSync(resolved, content)
+}
+
+// Run mode helpers
+function getInputDefaultValue (input) {
+  if (!input || typeof input !== 'object') return undefined
+  if (input.type === 'group' && Array.isArray(input.elements)) {
+    const value = {}
+    input.elements.forEach(element => {
+      const elementValue = getInputDefaultValue(element)
+      if (typeof elementValue !== 'undefined' && element.name) value[element.name] = elementValue
+    })
+    return value
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'default')) return input.default
+
+  switch (input.type) {
+    case 'int':
+    case 'float':
+    case 'number':
+      return 0
+    case 'string':
+    case 'text':
+      return ''
+    case 'color':
+      return '#000000'
+    case 'categorical':
+    case 'select':
+    case 'radio':
+      return input.options && input.options.length ? input.options[0] : ''
+    case 'bool':
+    case 'checkbox':
+    case 'toggle':
+      return false
+    case 'multi-select':
+      return []
+    case 'range':
+      return [input.min || 0, input.max || 100]
+    case 'slider':
+      return input.min || 0
+    case 'folder':
+      return input.default || []
+    case 'file':
+      return ''
+    default:
+      return undefined
+  }
+}
+
+function getSchemaInputDefaults (schema) {
+  const data = {}
+  if (!schema.inputs) return data
+  schema.inputs.forEach(input => {
+    if (!input.name) return
+    const value = getInputDefaultValue(input)
+    if (typeof value !== 'undefined') data[input.name] = value
+  })
+  return data
+}
+
+function loadBrowserStyleModelFunction (src, model, modelPath) {
+  const modelName = getModelExportName(model)
+  const localRequire = modelPath
+    ? Module.createRequire(modelPath)
+    : require
+  const moduleShim = { exports: {} }
+  const dirname = modelPath ? path.dirname(modelPath) : process.cwd()
+  const filename = modelPath || path.join(dirname, '__jsee_model__.js')
+
+  const fn = new Function(
+    'require',
+    'module',
+    'exports',
+    '__filename',
+    '__dirname',
+    `${src}
+return typeof ${toJsIdentifier(modelName)} === 'function' ? ${toJsIdentifier(modelName)} : (module.exports && (module.exports.default || module.exports[${JSON.stringify(modelName)}] || module.exports))`
+  )
+  const target = fn(localRequire, moduleShim, moduleShim.exports, filename, dirname)
+  if (typeof target === 'function') return target
+  if (target && typeof target === 'object') {
+    if (typeof target[modelName] === 'function') return target[modelName]
+    if (typeof target.default === 'function') return target.default
+  }
+  return target
+}
+
+function resolveExportedTarget (target, model) {
+  const modelName = getModelExportName(model)
+  if (typeof target === 'function') return target
+  if (target && typeof target === 'object') {
+    if (typeof target[modelName] === 'function') return target[modelName]
+    if (typeof target.default === 'function') return target.default
+  }
+  return target
+}
+
+async function loadCliModelFunction (model, schemaPath, cwd, log) {
+  if (model.type === 'get' || model.type === 'post') {
+    throw new Error(`--run cannot execute remote ${model.type.toUpperCase()} model ${model.name || model.url}. Use a local JavaScript model.`)
+  }
+  if (model.type === 'py') {
+    throw new Error('--run currently supports local JavaScript models. Python model execution is available through the dev server/API path.')
+  }
+
+  let target
+  let modelPath = null
+
+  if (typeof model.code === 'function') {
+    target = model.code
+  } else if (typeof model.code === 'string' && model.code.trim()) {
+    try {
+      target = loadBrowserStyleModelFunction(model.code, model, null)
+    } catch (error) {
+      target = undefined
+    }
+    if (typeof target !== 'function') {
+      try {
+        target = new Function(`return (${model.code})`)()
+      } catch (error) {
+        // Keep the clearer error below.
+      }
+    }
+  } else if (model.url && !isHttpUrl(model.url)) {
+    modelPath = path.resolve(schemaPath ? path.dirname(schemaPath) : cwd, model.url)
+    target = resolveExportedTarget(require(modelPath), model)
+    if (typeof target !== 'function' && (!target || Object.keys(target).length === 0)) {
+      const src = fs.readFileSync(modelPath, 'utf-8')
+      target = loadBrowserStyleModelFunction(src, model, modelPath)
+    }
+  } else {
+    throw new Error(`--run requires local model code or a local model url for ${model.name || 'model'}`)
+  }
+
+  target = resolveExportedTarget(target, model)
+  if (typeof target !== 'function') {
+    throw new Error(`Could not load a callable function for model ${model.name || model.url || 'model'}`)
+  }
+
+  return getModelFuncJS(model, target, {
+    log,
+    progress: () => {},
+    isCancelled: () => false
+  })
+}
+
+async function runSchemaOnce (schema, data, schemaPath, cwd, log) {
+  let result = data
+  for (const model of schema.model) {
+    const modelFunc = await loadCliModelFunction(model, schemaPath, cwd, log)
+    const next = await modelFunc(result)
+    if (isRecordObject(result) && isRecordObject(next)) {
+      result = Object.assign({}, result, next)
+    } else if (typeof next !== 'undefined') {
+      result = next
+    }
+    if (isRecordObject(result) && result.stop) break
+  }
+  return result
+}
+
+function flattenOutputs (outputs, flat=[]) {
+  if (!Array.isArray(outputs)) return flat
+  outputs.forEach(output => {
+    if (output && output.type === 'group' && Array.isArray(output.elements)) {
+      flattenOutputs(output.elements, flat)
+    } else if (output) {
+      flat.push(output)
+    }
+  })
+  return flat
+}
+
+function cleanRunResultObject (result) {
+  if (!isRecordObject(result)) return result
+  const clean = Object.assign({}, result)
+  delete clean.caller
+  delete clean.stop
+  delete clean._status
+  delete clean._log
+  delete clean._progress
+  return clean
+}
+
+function getRunOutputValue (result, output) {
+  if (!isRecordObject(result)) return result
+  const names = [output.name, sanitizeName(output.name)]
+  if (output.alias) names.push(output.alias)
+  for (const name of names) {
+    if (name && Object.prototype.hasOwnProperty.call(result, name)) return result[name]
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'value')) return output.value
+  return undefined
+}
+
+function getRunOutputEntries (schema, result) {
+  const cleanResult = cleanRunResultObject(result)
+  const outputs = flattenOutputs(schema.outputs || [])
+  if (outputs.length) {
+    return outputs.map((output, index) => {
+      let value = getRunOutputValue(cleanResult, output)
+      if (typeof value === 'undefined' && outputs.length === 1 && !isRecordObject(cleanResult)) value = cleanResult
+      return {
+        output,
+        name: output.name || `output_${index + 1}`,
+        value
+      }
+    }).filter(entry => typeof entry.value !== 'undefined')
+  }
+
+  if (isRecordObject(cleanResult)) {
+    return Object.keys(cleanResult).map(key => ({
+      output: { name: key, type: typeof cleanResult[key] },
+      name: key,
+      value: cleanResult[key]
+    }))
+  }
+
+  return [{
+    output: { name: 'result', type: typeof cleanResult },
+    name: 'result',
+    value: cleanResult
+  }]
+}
+
+function getRunFileDescriptor (output, value) {
+  if (output.type !== 'file') {
+    return { value, filename: output.filename || output.name, mime: output.mime || output.contentType }
+  }
+  return normalizeFileOutputValue(output, value)
+}
+
+function extensionFromMime (mime) {
+  if (!mime || typeof mime !== 'string') return null
+  const clean = mime.split(';')[0].trim().toLowerCase()
+  const map = {
+    'text/csv': '.csv',
+    'text/plain': '.txt',
+    'text/markdown': '.md',
+    'text/html': '.html',
+    'application/json': '.json',
+    'application/pdf': '.pdf',
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/svg+xml': '.svg'
+  }
+  return map[clean] || null
+}
+
+function extensionForRunOutput (output, value, descriptor) {
+  if (descriptor && descriptor.filename && path.extname(descriptor.filename)) return path.extname(descriptor.filename)
+  if (descriptor && descriptor.mime) {
+    const mimeExt = extensionFromMime(descriptor.mime)
+    if (mimeExt) return mimeExt
+  }
+
+  switch ((output.type || '').toLowerCase()) {
+    case 'file':
+      return '.txt'
+    case 'markdown':
+      return '.md'
+    case 'html':
+      return '.html'
+    case 'code':
+    case 'text':
+    case 'string':
+    case 'chat':
+      return '.txt'
+    case 'image':
+      return '.png'
+    case 'pdf':
+      return '.pdf'
+    default:
+      return '.json'
+  }
+}
+
+function getRunOutputFilename (entry) {
+  const descriptor = getRunFileDescriptor(entry.output, entry.value)
+  const base = descriptor.filename
+    ? path.basename(String(descriptor.filename))
+    : sanitizeName(entry.name || 'output')
+  if (path.extname(base)) return base
+  return base + extensionForRunOutput(entry.output, descriptor.value, descriptor)
+}
+
+function formatRunOutputContent (entry, forStdout=false) {
+  const descriptor = getRunFileDescriptor(entry.output, entry.value)
+  const value = descriptor.value
+  const type = (entry.output.type || '').toLowerCase()
+
+  if (Buffer.isBuffer(value)) return { content: value, addNewline: false }
+  if (value instanceof Uint8Array) return { content: Buffer.from(value), addNewline: false }
+
+  if (type === 'file') {
+    if (isRecordObject(value) || Array.isArray(value)) {
+      return { content: JSON.stringify(value, null, 2), addNewline: true }
+    }
+    return { content: typeof value === 'undefined' || value === null ? '' : String(value), addNewline: false }
+  }
+
+  if (['text', 'string', 'code', 'markdown', 'html', 'chat'].includes(type)) {
+    if (isRecordObject(value) || Array.isArray(value)) {
+      return { content: JSON.stringify(value, null, 2), addNewline: true }
+    }
+    return { content: typeof value === 'undefined' || value === null ? '' : String(value), addNewline: true }
+  }
+
+  if (typeof value === 'string' && forStdout && !['table', 'object', 'array', 'json'].includes(type)) {
+    return { content: value, addNewline: true }
+  }
+
+  return { content: JSON.stringify(value, null, 2), addNewline: true }
+}
+
+function writeRunContent (target, formatted) {
+  let content = formatted.content
+  if (typeof content === 'string' && formatted.addNewline && !content.endsWith('\n')) content += '\n'
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.writeFileSync(target, content)
+}
+
+function writeRunStdout (formatted) {
+  let content = formatted.content
+  if (typeof content === 'string' && formatted.addNewline && !content.endsWith('\n')) content += '\n'
+  process.stdout.write(content)
+}
+
+function getRunOutputsDirectory (outputs, cwd) {
+  if (!outputs) return null
+  const value = Array.isArray(outputs) ? outputs[0] : outputs
+  if (value === true || typeof value !== 'string') {
+    throw new Error('--outputs in --run mode expects a directory path')
+  }
+  return resolveOutputPath(cwd, value)
+}
+
+function getRunOutputTarget (entry, argv, inputNames, cwd) {
+  const outputName = sanitizeName(entry.name)
+  const explicitKey = `output-${outputName}`
+  let value
+  if (Object.prototype.hasOwnProperty.call(argv, explicitKey)) {
+    value = argv[explicitKey]
+  } else if (!inputNames.has(outputName) && Object.prototype.hasOwnProperty.call(argv, outputName)) {
+    value = argv[outputName]
+  }
+  if (typeof value === 'undefined') return null
+  if (value === true || typeof value !== 'string') {
+    throw new Error(`Output target --${outputName} requires a file path`)
+  }
+  return resolveOutputPath(cwd, value)
+}
+
+function emitRunOutputs (schema, result, argv, outputs, cwd) {
+  const entries = getRunOutputEntries(schema, result)
+  const inputNames = new Set((schema.inputs || []).map(input => sanitizeName(input.name)))
+  const outputDir = getRunOutputsDirectory(outputs, cwd)
+  const targets = new Map()
+
+  entries.forEach(entry => {
+    const target = getRunOutputTarget(entry, argv, inputNames, cwd)
+    if (target) targets.set(entry.name, target)
+  })
+
+  if (outputDir) {
+    fs.mkdirSync(outputDir, { recursive: true })
+    entries.forEach(entry => {
+      const target = targets.get(entry.name) || path.join(outputDir, getRunOutputFilename(entry))
+      writeRunContent(target, formatRunOutputContent(entry))
+    })
+    return
+  }
+
+  if (targets.size) {
+    entries.forEach(entry => {
+      const target = targets.get(entry.name)
+      if (target) writeRunContent(target, formatRunOutputContent(entry))
+    })
+    return
+  }
+
+  if (entries.length === 1) {
+    writeRunStdout(formatRunOutputContent(entries[0], true))
+    return
+  }
+
+  const resultObject = {}
+  entries.forEach(entry => {
+    resultObject[entry.name] = entry.value
+  })
+  writeRunStdout({ content: JSON.stringify(resultObject, null, 2), addNewline: true })
+}
+
 let optionalEsbuild
 function getOptionalEsbuild () {
   if (optionalEsbuild) return optionalEsbuild
@@ -324,6 +852,64 @@ function buildBundledModelExposeCode (bundleGlobalName, modelName) {
 `
 }
 
+
+function escapeRegExp (value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function readPackageJsonForFile (filePath) {
+  try {
+    const packageRoot = findPackageRoot(filePath)
+    const packageJsonPath = path.join(packageRoot, 'package.json')
+    return {
+      packageRoot,
+      packageJson: JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+    }
+  } catch (error) {
+    return null
+  }
+}
+
+function createEmptyModulePlugin (specifiers) {
+  const list = Array.from(new Set(specifiers.filter(Boolean)))
+  if (!list.length) return null
+  const filter = new RegExp(`^(?:${list.map(escapeRegExp).join('|')})$`)
+  return {
+    name: 'jsee-empty-browser-modules',
+    setup (build) {
+      build.onResolve({ filter }, args => ({ path: args.path, namespace: 'jsee-empty' }))
+      build.onLoad({ filter: /.*/, namespace: 'jsee-empty' }, () => ({ contents: 'module.exports = {}', loader: 'js' }))
+    }
+  }
+}
+
+function getBrowserFieldEsbuildOptions (modelPath) {
+  const packageInfo = readPackageJsonForFile(modelPath)
+  if (!packageInfo) return {}
+
+  const browser = packageInfo.packageJson.browser
+  if (!browser || typeof browser !== 'object' || Array.isArray(browser)) {
+    return { absWorkingDir: packageInfo.packageRoot }
+  }
+
+  const alias = {}
+  const empty = []
+  Object.entries(browser).forEach(([key, value]) => {
+    if (!key || key.startsWith('.') || key.startsWith('/')) return
+    if (value === false) empty.push(key)
+    else if (typeof value === 'string' && value.length) alias[key] = value
+  })
+
+  const plugins = []
+  const emptyPlugin = createEmptyModulePlugin(empty)
+  if (emptyPlugin) plugins.push(emptyPlugin)
+
+  const options = { absWorkingDir: packageInfo.packageRoot }
+  if (Object.keys(alias).length) options.alias = alias
+  if (plugins.length) options.plugins = plugins
+  return options
+}
+
 async function bundleModelCode (model, modelPath, code) {
   if (!shouldBundleModelCode(code)) return code
 
@@ -339,14 +925,14 @@ async function bundleModelCode (model, modelPath, code) {
     throw new Error(`Bundling ${model.url || modelPath} requires a valid JavaScript model name or an explicit module export.`)
   }
 
-  const options = {
+  const options = Object.assign({
     bundle: true,
     write: false,
     platform: 'browser',
     format: 'iife',
     globalName: bundleGlobalName,
     logLevel: 'silent'
-  }
+  }, getBrowserFieldEsbuildOptions(modelPath))
 
   if (needsExportShim) {
     options.stdin = {
@@ -704,10 +1290,18 @@ function template(schema, blocks) {
     table th { background-color: #f0f0f0; border: 1px solid #e0e0e0; }
     table td { border: 1px solid #e8e8e8; }
     @media screen and (max-width: 800px) { table { display: block; overflow-x: auto; -webkit-overflow-scrolling: touch; -ms-overflow-style: -ms-autohiding-scrollbar; } }
-    .site-header { border-bottom: 1px solid #e8e8e8; min-height: 55.95px; line-height: 54px; position: relative; }
-    .site-title { font-size: 1.625rem; font-weight: 800; letter-spacing: -1px; margin-bottom: 0; float: left; }
-    @media screen and (max-width: 600px) { .site-title { padding-right: 45px; } }
+    .site-header { border-bottom: 1px solid #e8e8e8; min-height: 55.95px; position: relative; }
+    .site-header .wrapper { min-height: 54px; display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+    .site-header .wrapper:after { content: none; }
+    .site-title { font-size: 1.625rem; font-weight: 800; letter-spacing: -1px; line-height: 1.2; margin-bottom: 0; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
     .site-title, .site-title:visited { color: #424242; }
+    .jsee-header-actions { display: flex; align-items: center; justify-content: flex-end; gap: 8px; flex: 0 0 auto; font-size: 12px; line-height: 1; }
+    .jsee-header-badge, .jsee-header-button { border: 1px solid #e0e0e0; border-radius: 4px; background: #f8f8f8; color: #555; padding: 6px 10px; font: inherit; line-height: 1; white-space: nowrap; }
+    .jsee-header-badge { font-family: Menlo, Inconsolata, Consolas, Roboto Mono, Ubuntu Mono, Liberation Mono, Courier New, monospace; }
+    .jsee-header-button { cursor: pointer; }
+    .jsee-header-button:hover { background: #f0f0f0; color: #111; }
+    .jsee-header-toggle { display: flex; align-items: center; gap: 4px; color: #666; cursor: pointer; white-space: nowrap; }
+    @media screen and (max-width: 600px) { .site-header .wrapper { flex-wrap: wrap; gap: 8px; padding-top: 10px; padding-bottom: 10px; } .site-title { flex: 1 1 100%; white-space: normal; } .jsee-header-actions { width: 100%; justify-content: flex-start; } }
     .site-nav { position: absolute; top: 9px; right: 15px; background-color: #fdfdfd; border: 1px solid #e8e8e8; border-radius: 5px; text-align: right; }
     .site-nav .nav-trigger { display: none; }
     .site-nav .menu-icon { float: right; width: 36px; height: 26px; line-height: 0; padding-top: 10px; text-align: center; }
@@ -767,7 +1361,6 @@ function template(schema, blocks) {
     @media screen and (min-width: 800px) { .one-half { width: calc(50% - (30px / 2)); } }
     /** Jsee elements */
     .app-container { background-color: #F0F1F4; border-bottom: 1px solid #e8e8e8; padding-bottom: 55px }
-    #save-html-btn:hover { background-color: #f0f0f0 !important; }
     .schema-description { background-color: #f8f8fa; padding: 20px; margin-top: 20px; border-radius: 10px; border: 1px solid #e8e8e8; }
     .schema-description h2, .schema-description h3, .schema-description h4 { margin-top: 10px; }
     /** Logos */
@@ -782,10 +1375,10 @@ function template(schema, blocks) {
 </head>
 <body>
   ${blocks.hiddenElementHtml}
-  ${blocks.serveBarHtml}
   <header class="site-header">
     <div class="wrapper">
       <span class="site-title">${title}</span>
+      ${blocks.headerRightHtml}
     </div>
   </header>
   <div class="page-content app-container">
@@ -836,9 +1429,39 @@ function template(schema, blocks) {
         env = new JSEE({ container: container, schema: currentSchema })
       })
     }
-    var saveBtn = document.getElementById('save-html-btn')
-    if (saveBtn) {
-      saveBtn.addEventListener('click', function () { env.download("${title}") })
+    var downloadBtn = document.getElementById('download-html-btn')
+    if (downloadBtn) {
+      var downloadTitle = ${JSON.stringify(title)}
+      function formatHtmlSize(bytes) {
+        if (bytes >= 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB'
+        if (bytes >= 1024) return Math.round(bytes / 1024) + ' KB'
+        return bytes + ' B'
+      }
+      function getDownloadHtml() {
+        return '<!DOCTYPE html>\\n' + document.documentElement.outerHTML
+      }
+      function getDownloadFilename() {
+        var base = (downloadTitle || 'jsee').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+        return (base || 'jsee') + '.html'
+      }
+      function updateDownloadLabel() {
+        var html = getDownloadHtml()
+        var size = new Blob([html], { type: 'text/html' }).size
+        downloadBtn.textContent = 'Download HTML - ' + formatHtmlSize(size)
+      }
+      downloadBtn.addEventListener('click', function () {
+        var html = getDownloadHtml()
+        var blob = new Blob([html], { type: 'text/html' })
+        var url = URL.createObjectURL(blob)
+        var a = document.createElement('a')
+        a.href = url
+        a.download = getDownloadFilename()
+        document.body.appendChild(a)
+        a.click()
+        a.remove()
+        setTimeout(function () { URL.revokeObjectURL(url) }, 0)
+      })
+      setTimeout(updateDownloadLabel, 0)
     }
   </script>
 </body>
@@ -863,6 +1486,7 @@ async function gen (pargv, returnHtml=false) {
     execute: 'e',
     cdn: 'c',
     runtime: 'r',
+    serve: 's'
   }
   const argvDefault = {
     execute: 'auto', // execute the model code on the server (auto = server-side when serving local .js models)
@@ -872,12 +1496,15 @@ async function gen (pargv, returnHtml=false) {
     version: 'latest', // default version of JSEE runtime to use
     verbose: false, // verbose mode
     cdn: false,
-    runtime: 'auto'
+    runtime: 'auto',
+    serve: false,
+    run: false
   }
+  const booleanArgs = ['help', 'h', 'html', 'client', 'serve', 'run']
   let argv = minimist(pargv, {
     alias: argvAlias,
     default: argvDefault,
-    boolean: ['help', 'h', 'html', 'client'],
+    boolean: booleanArgs,
   })
 
   // ── jsee init <template> ──────────────────────────────────────────
@@ -1015,7 +1642,7 @@ npx @jseeio/jsee schema.json
 
   if (argv.help || argv.h) {
     console.log(`
-Usage: jsee [schema.json] [data...] [options]
+Usage: jsee [schema.json|package] [data...] [options]
        jsee init [template] [--html]
 
 Commands:
@@ -1030,6 +1657,8 @@ Options:
   -v, --version <version>   JSEE runtime version (default: latest)
   -b, --bundle             Bundle runtime + dependencies into output
   -f, --fetch               Alias for --bundle
+  -s, --serve               Serve explicitly (default when no output is provided)
+      --run                 Execute the model once and write pipeable outputs
   -e, --execute             Execute model server-side (auto-enabled when serving local .js models)
       --client              Force client-side execution (disable auto server-side)
   -c, --cdn <url|bool>      Rewrite model URLs for CDN deployment
@@ -1047,11 +1676,14 @@ Examples:
   jsee init chat                    Scaffold chat project
   jsee init --html                  Generate single index.html
   jsee schema.json                  Start dev server with schema
+  jsee @scope/app --serve           Start dev server from a JSEE app package
   jsee schema.json 42 hello         Pass positional data to first two inputs
   jsee schema.json --a=100 --b=200  Pass named data inputs
   jsee schema.json data.csv         Pass a file path as input
   jsee schema.json -o app.html      Generate static HTML file
   jsee schema.json -o app.html --bundle  Generate self-contained HTML with bundled runtime
+  jsee @statsim/gen --run --dataset Moons --format CSV --nSamples 500
+  jsee @statsim/gen --run --dataset Moons --file moons.csv
   jsee -p 8080                      Start dev server on port 8080
   jsee report.pdf                   Serve a PDF file (auto-detected viewer)
   jsee data/                        Serve a folder (file browser with preview)
@@ -1061,14 +1693,18 @@ Documentation: https://jsee.org
     return
   }
 
-  // Check if first positional arg is a file or directory for identity serving
+  // Check if first positional arg is a file/directory or JSEE app package.
   let identityResult = null
+  let packageInput = null
   if (!imported && argv._.length > 0) {
     identityResult = generateIdentitySchema(argv._[0], process.cwd())
+    if (!identityResult) {
+      packageInput = resolveJseePackageInput(argv._[0], process.cwd())
+    }
   }
 
-  // Set argv.inputs to the first positional argument if it looks like a schema/script
-  if (!identityResult && !imported && argv._.length > 0 && argv.inputs === argvDefault.inputs) {
+  // Set argv.inputs to the first positional argument if it looks like a schema/script/package.
+  if (!identityResult && !packageInput && !imported && argv._.length > 0 && argv.inputs === argvDefault.inputs) {
     argv.inputs = argv._[0]
   }
 
@@ -1087,8 +1723,22 @@ Documentation: https://jsee.org
 
   let cwd = process.cwd()
   let inputs = argv.inputs
-  let outputs = argv.outputs
-  let description = argv.description
+  let outputs = argv.serve ? false : argv.outputs
+  let description = argv.description || ''
+
+  if (packageInput || (!identityResult && typeof inputs === 'string')) {
+    const resolvedPackageInput = packageInput || resolveJseePackageInput(inputs, cwd)
+    if (resolvedPackageInput) {
+      packageInput = resolvedPackageInput
+      cwd = packageInput.packageRoot
+      inputs = [packageInput.schemaPath]
+      if (!description && packageInput.descriptionPath) {
+        description = path.relative(cwd, packageInput.descriptionPath)
+      }
+    } else if (looksLikeMissingPackageInput(inputs, cwd)) {
+      throw new Error(`Cannot resolve JSEE app package ${inputs}. Install it in this project or let npm provide both packages:\n  ${getPackageInputInstallHint(inputs)}`)
+    }
+  }
   let schema
   let schemaPath
   let descriptionTxt = ''
@@ -1099,13 +1749,13 @@ Documentation: https://jsee.org
   // Determine the inputs and outputs
   // if inputs is a string with js file names, split it into an array
   if (typeof inputs === 'string') {
-    if (inputs.includes('.js')) {
+    if (inputs.includes('.js') || inputs.includes('.json') || inputs.includes(',')) {
       inputs = inputs.split(',')
     }
   }
 
   // if outputs is a string with js file names, split it into an array
-  if (typeof outputs === 'string') {
+  if (typeof outputs === 'string' && !argv.run) {
     outputs = outputs.split(',')
   }
 
@@ -1150,8 +1800,11 @@ Documentation: https://jsee.org
     schema.inputs.forEach((inp, inp_index) => {
       if (inp.name) {
         const inputName = sanitizeName(inp.name)
-        if (inp.alias) {
-          argvAlias[inputName] = inp.alias
+        const inputAliases = []
+        if (inp.alias) inputAliases.push(...toArray(inp.alias))
+        if (inp.name !== inputName) inputAliases.push(inp.name)
+        if (inputAliases.length) {
+          argvAlias[inputName] = inputAliases
         }
         // Use positional arguments as schema input defaults
         if (imported && argv._.length > inp_index) {
@@ -1174,6 +1827,7 @@ Documentation: https://jsee.org
   argv = minimist(pargv, {
     alias: argvAlias,
     default: argvDefault,
+    boolean: booleanArgs
   })
 
   // Now deactivate the inputs present in argv
@@ -1204,6 +1858,17 @@ Documentation: https://jsee.org
     schema.model = [schema.model]
   }
 
+  if (argv.run) {
+    const data = Object.assign(
+      {},
+      getSchemaInputDefaults(schema),
+      getDataFromArgv(schema, argv, true)
+    )
+    const result = await runSchemaOnce(schema, data, schemaPath, cwd, log)
+    emitRunOutputs(schema, result, argv, outputs, process.cwd())
+    return result
+  }
+
   // Resolve server-side execution mode
   const hasOutputs = Array.isArray(outputs) ? outputs.length > 0 : Boolean(outputs)
   let shouldExecute = argv.execute
@@ -1230,18 +1895,7 @@ Documentation: https://jsee.org
   if (shouldExecute) {
     await Promise.all(schema.model.map(async m => {
       log('Preparing a model to run on the server side:', m.name, m.url)
-      const modelPath = path.join(schemaPath ? path.dirname(schemaPath) : cwd, m.url)
-      let target = require(modelPath)
-      // Handle browser-style model files (no module.exports) — eval the source
-      // to extract the named function, similar to how the worker does it
-      if (typeof target !== 'function' && (!target || Object.keys(target).length === 0)) {
-        const src = fs.readFileSync(modelPath, 'utf-8')
-        const fn = new Function(src + `\nreturn typeof ${m.name} === 'function' ? ${m.name} : undefined`)()
-        if (typeof fn === 'function') {
-          target = fn
-        }
-      }
-      modelFuncs[m.name] = await getModelFuncJS(m, target, {log})
+      modelFuncs[m.name] = await loadCliModelFunction(m, schemaPath, cwd, log)
       m.type = 'post'
       m.url = `/${m.name}`
       m.worker = false
@@ -1285,7 +1939,8 @@ Documentation: https://jsee.org
 
   // Generate description block
   if (description) {
-    const descriptionMd = fs.readFileSync(path.join(cwd, description), 'utf8')
+    const descriptionPath = path.isAbsolute(description) ? description : path.join(cwd, description)
+    const descriptionMd = fs.readFileSync(descriptionPath, 'utf8')
     descriptionHtml = getMarkdownConverter().render(descriptionMd)
 
     if (descriptionMd.includes('---')) {
@@ -1455,20 +2110,17 @@ Documentation: https://jsee.org
 
   }
 
-  // Build serve bar (only when serving, not for -o output)
-  let serveBarHtml = ''
+  // Build right-side header status/action. Serve mode shows only runtime status; bundled files can download themselves.
+  let headerRightHtml = ''
   let schemaScript = ''
   const isServing = !hasOutputs
   if (isServing) {
     const toggleHtml = shouldExecute
-      ? '<label style="cursor:pointer"><input type="checkbox" id="exec-toggle" style="margin-right:4px">Browser</label>'
+      ? '<label class="jsee-header-toggle"><input type="checkbox" id="exec-toggle">Browser</label>'
       : ''
-    serveBarHtml = `<div id="jsee-serve-bar" style="background:#f8f8f8;border-bottom:1px solid #e0e0e0;padding:6px 15px;font-size:13px;color:#828282;display:flex;align-items:center;gap:16px">
-      <span style="font-family:monospace">localhost:${argv.port}</span>
-      <span style="flex:1"></span>
-      ${toggleHtml}
-      <button id="save-html-btn" style="background:none;border:1px solid #ddd;border-radius:3px;padding:3px 10px;font-size:12px;color:#555;cursor:pointer" title="Save as self-contained HTML file">Save HTML</button>
-    </div>`
+    headerRightHtml = `<div class="jsee-header-actions">${toggleHtml}<span class="jsee-header-badge">localhost:${argv.port}</span></div>`
+  } else if (shouldBundle) {
+    headerRightHtml = '<div class="jsee-header-actions"><button id="download-html-btn" class="jsee-header-button" type="button" title="Download this standalone HTML file">Download HTML</button></div>'
   }
   if (shouldExecute) {
     const clientSchema = JSON.parse(JSON.stringify(schema))
@@ -1486,7 +2138,7 @@ Documentation: https://jsee.org
     hiddenElementHtml: hiddenElementHtml,
     socialHtml: pad(socialHtml, 2, 1),
     orgHtml: pad(orgHtml, 2, 1),
-    serveBarHtml: serveBarHtml,
+    headerRightHtml: headerRightHtml,
     schemaScript: schemaScript,
   })
 
@@ -1499,11 +2151,11 @@ Documentation: https://jsee.org
       if (o === 'stdout') {
         log(html)
       } else if (o.includes('.html')) {
-        fs.writeFileSync(resolveOutputPath(cwd, o), html)
+        writeOutputFile(cwd, o, html)
       } else if (o.includes('.json')) {
-        fs.writeFileSync(resolveOutputPath(cwd, o), JSON.stringify(schema, null, 2))
+        writeOutputFile(cwd, o, JSON.stringify(schema, null, 2))
       } else if (o.includes('.md')) {
-        fs.writeFileSync(resolveOutputPath(cwd, o), genMarkdownFromSchema(schema))
+        writeOutputFile(cwd, o, genMarkdownFromSchema(schema))
       } else {
         console.error('Invalid output file:', o)
       }
@@ -1613,6 +2265,16 @@ module.exports.resolveLocalImportFile = resolveLocalImportFile
 module.exports.resolveFetchImport = resolveFetchImport
 module.exports.resolveRuntimeMode = resolveRuntimeMode
 module.exports.resolveOutputPath = resolveOutputPath
+module.exports.resolveJseePackageInput = resolveJseePackageInput
+module.exports.readJseePackageInput = readJseePackageInput
+module.exports.findPackageRoot = findPackageRoot
+module.exports.runPackage = runPackage
+module.exports.looksLikeMissingPackageInput = looksLikeMissingPackageInput
+module.exports.getPackageInputInstallHint = getPackageInputInstallHint
+module.exports.isPackageSpecifier = isPackageSpecifier
+module.exports.writeOutputFile = writeOutputFile
 module.exports.needsFullBundle = needsFullBundle
 module.exports.shouldBundleModelCode = shouldBundleModelCode
 module.exports.bundleModelCode = bundleModelCode
+module.exports.runSchemaOnce = runSchemaOnce
+module.exports.emitRunOutputs = emitRunOutputs