@owear/cli 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@owear/cli",
+  "version": "0.1.0",
+  "description": "CLI de Owear: create, dev, build",
+  "type": "module",
+  "bin": {
+    "ow": "./src/ow.js",
+    "owear-build-native": "./src/owear-build-native.js"
+  },
+  "optionalDependencies": {
+    "@owear/linux-x64-gnu": "0.1.0"
+  },
+  "files": [
+    "src",
+    "template"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://owear.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/owear/owear.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck": "node --check src/ow.js && node --check src/owear-build-native.js"
+  }
+}

package/src/ow.js

@@ -0,0 +1,443 @@
+#!/usr/bin/env node
+// Copyright 2026 Owear Contributors
+// SPDX-License-Identifier: Apache-2.0
+//
+// ow — CLI del framework Owear.
+//   ow create <dir>   scaffoldea una app
+//   ow dev            kernel nativo + vite dev server + sidecar Node
+//   ow build          build de producción (vite build + módulos .owm)
+//
+import { spawn, spawnSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const C = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+}
+const log = (msg) => console.log(`${C.dim}[ow]${C.reset} ${msg}`)
+const die = (msg) => {
+  console.error(`${C.red}[ow] ✗${C.reset} ${msg}`)
+  process.exit(1)
+}
+
+function platformPreset() {
+  switch (process.platform) {
+    case 'linux': return 'linux-release'
+    case 'win32': return 'windows-release'
+    case 'darwin': return 'macos-release'
+    default: die(`plataforma no soportada: ${process.platform}`)
+  }
+}
+
+/** Nombre del paquete de runtime para la plataforma actual (null si no hay). */
+function runtimePackageName() {
+  if (process.platform === 'linux' && process.arch === 'x64') return '@owear/linux-x64-gnu'
+  if (process.platform === 'win32' && process.arch === 'x64') return '@owear/win32-x64'
+  if (process.platform === 'darwin' && process.arch === 'arm64') return '@owear/darwin-arm64'
+  if (process.platform === 'darwin' && process.arch === 'x64') return '@owear/darwin-x64'
+  return null
+}
+
+/** Directorio del paquete de runtime instalado (o null). */
+function runtimePackageDir() {
+  const name = runtimePackageName()
+  if (!name) return null
+  try {
+    return path.dirname(require.resolve(name + '/package.json'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Ruta(s) de los módulos stock, separadas por `path.delimiter`.
+ * - runtime npm:  <pkg>/bin/modules (plano)
+ * - monorepo:     cada build/<preset>/api/<nombre>/ (el loader NO recursiona)
+ */
+function stockModulesPath() {
+  const rt = runtimePackageDir()
+  if (rt) {
+    const m = path.join(rt, 'bin', 'modules')
+    if (fs.existsSync(m)) return m
+  }
+  const api = path.resolve(__dirname, '../../../build', platformPreset(), 'api')
+  if (fs.existsSync(api)) {
+    const dirs = fs
+      .readdirSync(api, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name !== 'CMakeFiles')
+      .map((d) => path.join(api, d.name))
+    if (dirs.length) return dirs.join(path.delimiter)
+  }
+  return ''
+}
+
+/** Localiza el binario del kernel. Orden: OW_KERNEL_BIN → local → runtime npm → monorepo. */
+function findKernelBin(cwd = process.cwd()) {
+  if (process.env.OW_KERNEL_BIN && fs.existsSync(process.env.OW_KERNEL_BIN)) {
+    return process.env.OW_KERNEL_BIN
+  }
+  const exe = process.platform === 'win32' ? 'owear.exe' : 'owear'
+  const rt = runtimePackageDir()
+  const candidates = [
+    path.join(cwd, '.owear', 'bin', exe),
+    ...(rt ? [path.join(rt, 'bin', exe)] : []),
+    // monorepo en desarrollo
+    path.resolve(__dirname, '../../../build', platformPreset(), 'src', exe),
+  ]
+  for (const c of candidates) if (fs.existsSync(c)) return c
+  return null
+}
+
+/** Compila el kernel si hay fuentes disponibles (repo hermano o checkout). */
+function ensureKernelBuilt(cwd) {
+  const existing = findKernelBin(cwd)
+  if (existing) return existing
+
+  const repoRoot = path.resolve(__dirname, '../../..')
+  const hasSources = fs.existsSync(path.join(repoRoot, 'CMakeLists.txt'))
+  if (!hasSources) {
+    // El binario del kernel todavía no se distribuye como paquete npm, así que
+    // no prometemos `@owear/runtime-<platform>`: damos las salidas reales.
+    const exe = process.platform === 'win32' ? 'owear.exe' : 'owear'
+    die(
+      `no encuentro el kernel owear. Opciones:
+  · compílalo desde un checkout: cmake --preset ${platformPreset()} && cmake --build --preset ${platformPreset()}
+  · copia el binario en ${path.join(process.cwd(), '.owear', 'bin', exe)}
+  · o define OW_KERNEL_BIN=/ruta/al/owear
+  (el binario precompilado por plataforma aún no se publica en npm)`)
+  }
+  log('compilando kernel nativo (primera vez)…')
+  const preset = platformPreset()
+  for (const args of [['--preset', preset], ['--build', '--preset', preset]]) {
+    const r = spawnSync('cmake', args, { cwd: repoRoot, stdio: 'inherit' })
+    if (r.status !== 0) die('fallo al compilar el kernel')
+  }
+  return findKernelBin(cwd)
+}
+
+// ── comandos ────────────────────────────────────────────────────────────────
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv
+
+  if (!cmd || cmd === '-h' || cmd === '--help') {
+    printHelp(); return
+  }
+
+  switch (cmd) {
+    case 'create': return cmdCreate(rest)
+    case 'dev':    return cmdDev(rest)
+    case 'build':  return cmdBuild(rest)
+    case 'api':    return cmdApi(rest)
+    default:
+      die(`comando desconocido: ${cmd} (usa --help)`)
+  }
+}
+
+function printHelp() {
+  console.log(`
+${C.cyan}owear${C.reset} — framework desktop nativo
+
+  ${C.green}ow create <dir>${C.reset}   crea una app nueva
+  ${C.green}ow dev${C.reset}            desarrollo: vite + kernel + sidecar node
+  ${C.green}ow build${C.reset}          build de producción
+  ${C.green}ow api list${C.reset}       lista las APIs del repo y sus manifiestos
+  ${C.green}ow api new <nombre>${C.reset}  scaffoldea una API (api/<nombre>/ + manifiesto)
+
+Variables útiles:
+  OW_KERNEL_BIN     ruta al binario owear
+`)
+}
+
+function cmdCreate(args) {
+  const dir = args[0]
+  if (!dir) die('uso: ow create <dir>')
+  const target = path.resolve(dir)
+  if (fs.existsSync(target) && fs.readdirSync(target).length) {
+    die(`el directorio ya existe y no está vacío: ${target}`)
+  }
+  const templateDir = path.resolve(__dirname, '../template')
+  if (!fs.existsSync(templateDir)) {
+    die(`template no encontrado en ${templateDir} (instala @owear/cli completo)`)
+  }
+  fs.cpSync(templateDir, target, { recursive: true })
+  log(`app creada en ${target}`)
+  log('siguientes pasos:')
+  console.log(`  cd ${path.basename(target)}`)
+  console.log('  pnpm install')
+  console.log('  pnpm dev')
+}
+
+// ── ow api — gestión de las APIs del framework ──────────────────────────────
+// Fuente única de verdad: api/<nombre>/owear.module.json. `ow api new` crea la
+// carpeta + manifiesto + esqueleto C++ y regenera el descubrimiento.
+
+/** Raíz del repo de Owear (para `ow api`, que no vive en la app). */
+function owearRepoRoot() {
+  const root = path.resolve(__dirname, '../../..')
+  return fs.existsSync(path.join(root, 'CMakeLists.txt')) ? root : null
+}
+
+function cmdApi(args) {
+  const root = owearRepoRoot()
+  if (!root) die('`ow api` solo funciona dentro del repo de Owear (no encuentro api/ desde el CLI)')
+  const sub = args[0]
+  if (sub === 'list') return cmdApiList(root)
+  if (sub === 'new') return cmdApiNew(root, args[1])
+  die('uso: ow api <list | new <nombre>>')
+}
+
+function readApiManifests(root) {
+  const apiDir = path.join(root, 'api')
+  const out = []
+  for (const d of fs.readdirSync(apiDir, { withFileTypes: true })) {
+    if (!d.isDirectory()) continue
+    const file = path.join(apiDir, d.name, 'owear.module.json')
+    if (!fs.existsSync(file)) continue
+    out.push(JSON.parse(fs.readFileSync(file, 'utf8')))
+  }
+  return out
+}
+
+function cmdApiList(root) {
+  const manifests = readApiManifests(root).sort((a, b) => a.name.localeCompare(b.name))
+  const fnCount = (m) =>
+    m.kind === 'module'
+      ? (m.functions?.length ?? 0)
+      : (m.descriptors ?? []).reduce((a, d) => a + (d.functions?.length ?? 0), 0)
+  const w = Math.max(4, ...manifests.map((m) => m.name.length))
+  console.log(`\n${'API'.padEnd(w)}  KIND     VER    FNS  PLATAFORMAS`)
+  console.log(`${'─'.repeat(w)}  ───────  ─────  ───  ────────────`)
+  for (const m of manifests) {
+    const fns = String(fnCount(m)).padStart(3)
+    const plats = (m.platforms ?? [...new Set((m.descriptors ?? []).flatMap((d) => d.platforms ?? []))]).join('/') || '—'
+    console.log(`${m.name.padEnd(w)}  ${m.kind.padEnd(7)}  ${m.version.padEnd(5)}  ${fns}  ${plats}`)
+  }
+  const mods = manifests.filter((m) => m.kind === 'module').length
+  console.log(`\n${manifests.length} APIs — ${mods} módulos (.owm), ${manifests.length - mods} builtins\n`)
+}
+
+function cmdApiNew(root, name) {
+  if (!name) die('uso: ow api new <nombre>')
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) die('nombre inválido (minúsculas, dígitos y guiones; debe empezar por letra)')
+  const dir = path.join(root, 'api', name)
+  if (fs.existsSync(dir) && fs.readdirSync(dir).length) die(`api/${name}/ ya existe y no está vacío`)
+
+  fs.mkdirSync(path.join(dir, 'src'), { recursive: true })
+
+  const manifest = {
+    $schema: '../owear.module.schema.json',
+    name,
+    kind: 'module',
+    version: '0.1.0',
+    description: `${name} — API de Owear.`,
+    platforms: ['linux', 'win', 'mac'],
+    functions: ['ping'],
+  }
+  fs.writeFileSync(path.join(dir, 'owear.module.json'), JSON.stringify(manifest, null, 2) + '\n')
+
+  fs.writeFileSync(
+    path.join(dir, 'CMakeLists.txt'),
+    `# ── API ${name} ────────────────────────────────────────────────────────────────\n` +
+      `# Manifiesto: owear.module.json (fuente única de verdad).\n` +
+      `ow_add_module(${name} SOURCES src/${name}.cpp)\n`
+  )
+
+  fs.writeFileSync(
+    path.join(dir, 'src', `${name}.cpp`),
+    `// Copyright 2026 Owear Contributors\n` +
+      `// SPDX-License-Identifier: Apache-2.0\n` +
+      `//\n` +
+      `// api/${name}/src/${name}.cpp — implementación de la API ${name}.\n` +
+      `// Se compila a ${name}.owm y se invoca desde el renderer con:\n` +
+      `//   await ow.invoke('${name}', 'ping')\n` +
+      `\n` +
+      `#include <ow/Json.h>\n` +
+      `#include <ow/Module.h>\n` +
+      `#include "ow_api.h"\n` +
+      `\n` +
+      `static void ping(const ow_request_t*, ow_response_t* res) {\n` +
+      `    ow::Module::RespondOk(res, "\\"pong\\"");\n` +
+      `}\n` +
+      `\n` +
+      `OW_MODULE_BEGIN(${name}, "1.0.0")\n` +
+      `OW_FN(ping)\n` +
+      `OW_MODULE_END()\n`
+  )
+
+  fs.writeFileSync(
+    path.join(dir, 'README.md'),
+    `# ${name}\n\n` +
+      `API de Owear. Manifiesto: [\`owear.module.json\`](./owear.module.json).\n\n` +
+      `Desde el renderer:\n\n\`\`\`ts\nawait ow.invoke('${name}', 'ping') // → "pong"\n\`\`\`\n`
+  )
+
+  log(`API creada en api/${name}/`)
+  log('regenerando descubrimiento (api/generated.cmake + builtins)…')
+  const r = spawnSync(process.execPath, [path.join(root, 'tools', 'gen-apis.mjs')], { stdio: 'inherit' })
+  if (r.status !== 0) die('falló tools/gen-apis.mjs')
+  log(`listo. En el renderer: ow.invoke('${name}', 'ping')`)
+}
+
+function runProc(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, { stdio: 'inherit', ...opts })
+    p.on('exit', (code) => resolve(code ?? 1))
+  })
+}
+
+async function waitForServer(url, timeoutMs = 30000) {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const r = await fetch(url)
+      if (r.ok) return true
+    } catch { /* aún no */ }
+    await new Promise((r) => setTimeout(r, 250))
+  }
+  return false
+}
+
+/** Entry del proceso principal: app/main.{ts,mts,js,mjs}. */
+function findMainEntry(cwd) {
+  for (const name of ['main.ts', 'main.mts', 'main.js', 'main.mjs']) {
+    const p = path.join(cwd, 'app', name)
+    if (fs.existsSync(p)) return p
+  }
+  return null
+}
+
+/**
+ * Prepara el entry del sidecar para que lo ejecute CUALQUIER node instalado.
+ * Node no ejecuta TypeScript hasta la 22.6 (y hasta la 23.6 sólo con un flag),
+ * así que compilamos con esbuild (viene con vite). De este modo el runtime del
+ * sistema sirve y el arranque no depende de la versión que tenga el usuario.
+ */
+function prepareMain(cwd, outDir) {
+  const entry = findMainEntry(cwd)
+  if (!entry) return null
+  if (entry.endsWith('.js') || entry.endsWith('.mjs')) return entry
+
+  const out = path.join(outDir, 'main.js')
+  fs.mkdirSync(outDir, { recursive: true })
+  log(`compilando ${path.relative(cwd, entry)}…`)
+  const r = spawnSync(
+    'npx',
+    [
+      'esbuild', entry,
+      '--bundle', '--platform=node', '--format=esm',
+      '--packages=external', `--outfile=${out}`, '--log-level=warning',
+    ],
+    { cwd, stdio: 'inherit', shell: process.platform === 'win32' }
+  )
+  if (r.status !== 0) {
+    die(`no se pudo compilar ${path.relative(cwd, entry)} — esbuild viene con vite, revisa que esté instalado`)
+  }
+  return out
+}
+
+async function cmdDev() {
+  const cwd = process.cwd()
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) die('ejecuta dentro de tu app')
+
+  const kernelBin = ensureKernelBuilt(cwd)
+
+  log('arrancando vite…')
+  const vite = spawn('npx', ['vite', '--port', '5173', '--strictPort'], {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+
+  const up = await waitForServer('http://localhost:5173/')
+  if (!up) { vite.kill(); die('vite no arrancó') }
+  log('dev server listo en http://localhost:5173')
+
+  // compila módulos nativos de la app (native/*.cpp → .owm)
+  const nativeDir = path.join(cwd, 'native')
+  let modulesDir = ''
+  if (fs.existsSync(nativeDir)) {
+    modulesDir = path.join(cwd, '.owear', 'modules')
+    fs.mkdirSync(modulesDir, { recursive: true })
+    const r = spawnSync('npx', ['owear-build-native'], {
+      cwd,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      env: { ...process.env, OW_MODULES_OUT: modulesDir },
+    })
+    if (r.status !== 0) die('falló la compilación de native/*.cpp')
+  }
+
+  const mainJs = prepareMain(cwd, path.join(cwd, '.owear'))
+  if (mainJs) log(`proceso principal: ${path.relative(cwd, mainJs)}`)
+
+  log(`lanzando kernel: ${kernelBin}`)
+  const kernel = spawn(kernelBin, [], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      OW_APP_NAME: JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).name ?? 'Owear App',
+      OW_DEV_SERVER_URL: 'http://localhost:5173/',
+      ...(mainJs ? { OW_APP_MAIN: mainJs } : {}),
+      ...(() => {
+        // módulos stock (fs/path/…) + los nativos de la app, si los hay
+        const dirs = [stockModulesPath(), modulesDir].filter(Boolean)
+        return dirs.length ? { OW_MODULES_DIR: dirs.join(path.delimiter) } : {}
+      })(),
+    },
+  })
+  kernel.on('exit', (code) => {
+    log(`kernel terminó (${code})`)
+    vite.kill('SIGTERM')
+    process.exit(code ?? 0)
+  })
+  process.on('SIGINT', () => {
+    kernel.kill('SIGTERM')
+    vite.kill('SIGTERM')
+    process.exit(0)
+  })
+}
+
+async function cmdBuild() {
+  const cwd = process.cwd()
+  log('vite build…')
+  const code = await runProc('npx', ['vite', 'build'], { cwd, shell: process.platform === 'win32' })
+  if (code !== 0) die('vite build falló')
+
+  const mainJs = prepareMain(cwd, path.join(cwd, 'dist'))
+
+  const nativeDir = path.join(cwd, 'native')
+  if (fs.existsSync(nativeDir)) {
+    const out = path.join(cwd, 'dist', 'modules')
+    const r = spawnSync('npx', ['owear-build-native'], {
+      cwd,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      env: { ...process.env, OW_MODULES_OUT: out },
+    })
+    if (r.status !== 0) die('falló la compilación de native/*.cpp')
+  }
+  log('build lista en dist/')
+  const runMods = [
+    stockModulesPath(),
+    fs.existsSync(path.join(cwd, 'dist', 'modules')) ? path.join(cwd, 'dist', 'modules') : '',
+  ]
+    .filter(Boolean)
+    .join(path.delimiter)
+  console.log(
+    `  OW_ASSETS_DIR=dist${mainJs ? ' OW_APP_MAIN=dist/main.js' : ''}` +
+      `${runMods ? ` OW_MODULES_DIR="${runMods}"` : ''} ./owear`
+  )
+}
+
+main().catch((e) => die(e?.stack ?? String(e)))

package/src/owear-build-native.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Copyright 2026 Owear Contributors
+// SPDX-License-Identifier: Apache-2.0
+//
+// owear-build-native — compila native/*.cpp de una app a .owm.
+// Cero configuración: detecta el compilador del sistema y compila como librería
+// dinámica exportando ow_module_descriptor.
+//
+import { spawnSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+const out = process.env.OW_MODULES_OUT ?? path.join(process.cwd(), '.owear', 'modules')
+const nativeDir = path.join(process.cwd(), 'native')
+
+if (!fs.existsSync(nativeDir)) {
+  console.log('[ow-build-native] sin directorio native/ — nada que hacer')
+  process.exit(0)
+}
+fs.mkdirSync(out, { recursive: true })
+
+// incluye headers públicos del framework si están instalados junto al kernel
+function frameworkIncludes() {
+  const incs = []
+  let runtimeInclude = null
+  // paquete de runtime de npm (@owear/<plataforma>): trae include/
+  const rtName =
+    process.platform === 'linux' && process.arch === 'x64'
+      ? '@owear/linux-x64-gnu'
+      : process.platform === 'win32' && process.arch === 'x64'
+        ? '@owear/win32-x64'
+        : process.platform === 'darwin'
+          ? `@owear/darwin-${process.arch}`
+          : null
+  if (rtName) {
+    try {
+      runtimeInclude = path.join(path.dirname(require.resolve(rtName + '/package.json')), 'include')
+    } catch {
+      /* sin runtime npm: cae al include del monorepo */
+    }
+  }
+  // desde packages/cli/src/ → raíz del repo (monorepo en desarrollo)
+  const candidates = [
+    process.env.OW_INCLUDE_DIR,
+    runtimeInclude,
+    path.resolve(
+      import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url)),
+      '../../../include',
+    ),
+  ].filter(Boolean)
+  for (const c of candidates) if (fs.existsSync(c)) incs.push(c)
+  return incs
+}
+
+function pickCompiler() {
+  if (process.env.CXX) return process.env.CXX
+  for (const c of ['c++', 'g++', 'clang++']) {
+    if (spawnSync(c, ['--version'], { stdio: 'ignore' }).status === 0) return c
+  }
+  return null
+}
+
+function pickWindowsCompiler() {
+  // cl.exe del último VS instalado (via vswhere)
+  const vswhere = 'C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe'
+  if (!fs.existsSync(vswhere)) {
+    if (spawnSync('clang++', ['--version'], { stdio: 'ignore' }).status === 0) {
+      return { cmd: 'clang++', msvcLike: false }
+    }
+    return null
+  }
+  const r = spawnSync(vswhere, ['-latest', '-property', 'installationPath'], { encoding: 'utf8' })
+  const vsPath = r.stdout?.trim()
+  if (!vsPath) return null
+  const clCandidates = fs.readdirSync(path.join(vsPath, 'VC', 'Tools', 'MSVC'))
+    .sort().reverse()
+  for (const v of clCandidates) {
+    const cl = path.join(vsPath, 'VC', 'Tools', 'MSVC', v, 'bin', 'Hostx64', 'x64', 'cl.exe')
+    if (fs.existsSync(cl)) return { cmd: cl, msvcLike: true }
+  }
+  return null
+}
+
+const incs = frameworkIncludes()
+let failures = 0
+
+for (const file of fs.readdirSync(nativeDir)) {
+  if (!file.endsWith('.cpp')) continue
+  const src = path.join(nativeDir, file)
+  const name = path.basename(file, '.cpp')
+  const ext = process.platform === 'win32' ? '.dll' : process.platform === 'darwin' ? '.dylib' : '.so'
+  const dest = path.join(out, name + ext)
+
+  // rebuild solo si cambió la fuente
+  if (fs.existsSync(dest) && fs.statSync(src).mtimeMs < fs.statSync(dest).mtimeMs) {
+    console.log(`[ow-build-native] ${name} al día`)
+    continue
+  }
+
+  const compiler = process.platform === 'win32' ? pickWindowsCompiler() : (() => {
+    const cmd = pickCompiler()
+    return cmd ? { cmd, msvcLike: false } : null
+  })()
+  if (!compiler) {
+    console.error(`[ow-build-native] ✗ no hay compilador C++ para ${file}`)
+    failures++
+    continue
+  }
+
+  let args
+  if (compiler.msvcLike) {
+    args = ['/std:c++20', '/LD', '/O2', '/EHsc', `/Fe:${dest}`, src,
+            ...incs.flatMap((i) => [`/I${i}`])]
+  } else {
+    args = ['-std=c++20', '-O2', '-fPIC', '-shared', '-o', dest, src,
+            ...incs.flatMap((i) => ['-I', i]),
+            ...(process.platform === 'darwin' ? [] : [])]
+  }
+  console.log(`[ow-build-native] compilando ${file} → ${path.basename(dest)}`)
+  const r = spawnSync(compiler.cmd, args, { stdio: 'inherit' })
+  if (r.status !== 0) {
+    console.error(`[ow-build-native] ✗ falló ${file}`)
+    failures++
+  }
+}
+
+process.exit(failures ? 1 : 0)

package/template/app/main.ts

@@ -0,0 +1,29 @@
+// Copyright 2026 Owear Contributors
+// SPDX-License-Identifier: Apache-2.0
+//
+// main.ts — proceso principal (sidecar Node). Estilo Electron.
+//
+import { app, BrowserWindow } from '@owear/core'
+
+let windows = 0
+
+app.whenReady().then(() => {
+  const win = new BrowserWindow({
+    title: 'Mi App Owear',
+    width: 1100,
+    height: 720,
+    titleBarStyle: 'custom', // titlebar custom + drag regions CSS
+    url: process.env.OW_DEV_SERVER_URL ?? 'app://index.html',
+  })
+  windows++
+
+  win.on('closed', () => {
+    windows--
+    if (windows === 0) app.quit()
+  })
+
+  // ejemplo: evaluar JS en la página
+  win.on('ready-to-show', async () => {
+    console.log('[main] ventana lista, id =', win.id)
+  })
+})

package/template/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Mi App Owear</title>
+</head>
+<body>
+  <header data-ow-drag class="titlebar">
+    <span>Mi App Owear</span>
+    <nav>
+      <button data-ow-no-drag onclick="ow.invoke('ow-window','minimize', window.__owWindowId)">–</button>
+      <button data-ow-no-drag onclick="ow.invoke('ow-window','maximize', window.__owWindowId, true)">□</button>
+      <button data-ow-no-drag onclick="ow.invoke('ow-window','close', window.__owWindowId)">✕</button>
+    </nav>
+  </header>
+  <main>
+    <h1>Funciona 🚀</h1>
+    <p id="demo">invocando módulo nativo…</p>
+    <pre id="out"></pre>
+  </main>
+  <script type="module" src="/src/renderer.ts"></script>
+</body>
+</html>

package/template/native/files.cpp

@@ -0,0 +1,42 @@
+// Copyright 2026 Owear Contributors
+// SPDX-License-Identifier: Apache-2.0
+//
+// native/files.cpp — módulo nativo PROPIO de la app.
+// Se compila a .owm y se invoca desde el renderer con:
+//   import { files } from '@owear/native'
+//   await files.readText('/etc/hostname')
+//
+#include <ow/Json.h>
+#include <ow/Module.h>
+#include "ow_api.h"
+
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+
+namespace fs = std::filesystem;
+
+static void readText(const ow_request_t* req, ow_response_t* res) {
+    auto parsed = ow::json::Parse(std::string_view(req->json, req->json_len));
+    if (!parsed.value || !parsed.value->IsArray() || !parsed.value->AsArray()[0].IsString())
+        return ow::Module::RespondError(res, "readText(path): path requerido");
+    std::ifstream f(parsed.value->AsArray()[0].AsString(), std::ios::binary);
+    if (!f) return ow::Module::RespondError(res, "no se pudo abrir");
+    std::ostringstream ss;
+    ss << f.rdbuf();
+    ow::Module::RespondOk(res, ow::json::Value(ss.str()).Serialize().c_str());
+}
+
+static void exists(const ow_request_t* req, ow_response_t* res) {
+    auto parsed = ow::json::Parse(std::string_view(req->json, req->json_len));
+    if (!parsed.value || !parsed.value->IsArray() || !parsed.value->AsArray()[0].IsString())
+        return ow::Module::RespondError(res, "exists(path): path requerido");
+    std::error_code ec;
+    bool ok = fs::exists(parsed.value->AsArray()[0].AsString(), ec);
+    ow::Module::RespondOk(res, ok ? "true" : "false");
+}
+
+OW_MODULE_BEGIN(files, "1.0.0")
+OW_FN(readText)
+OW_FN(exists)
+OW_MODULE_END()

package/template/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "mi-app-owear",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "ow dev",
+    "build": "ow build"
+  },
+  "dependencies": {
+    "@owear/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@owear/cli": "^0.1.0",
+    "@owear/vite-plugin": "^0.1.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0"
+  }
+}

package/template/src/renderer.ts

@@ -0,0 +1,30 @@
+// Copyright 2026 Owear Contributors
+// SPDX-License-Identifier: Apache-2.0
+//
+// renderer.ts — corre dentro del WebView. `ow` lo inyecta el kernel.
+//
+import { files } from '@owear/native'
+
+const out = document.getElementById('out')!
+const demo = document.getElementById('demo')!
+
+async function main() {
+  try {
+    // módulo nativo PROPIO (native/files.cpp)
+    const text = await files.readText('/etc/hostname')
+    demo.textContent = `hostname leído desde C++ nativo: ${text.trim()}`
+
+    // módulo stock fs
+    const st = await ow.invoke('fs', 'stat', '/etc/hosts')
+    out.textContent = JSON.stringify(st, null, 2)
+
+    // eventos de ventana
+    ow.on('resize', (b) => {
+      document.title = `${b.width}×${b.height}`
+    })
+  } catch (e) {
+    demo.textContent = '✗ ' + (e as Error).message
+  }
+}
+
+main()

package/template/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "app"]
+}

package/template/vite.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite'
+import owear from '@owear/vite-plugin'
+
+export default defineConfig({
+  plugins: [owear()],
+  base: './',
+  build: {
+    outDir: 'dist',
+  },
+})