@ecmaos/kernel 0.2.5 → 0.2.7

package/README.md

@@ -59,107 +59,151 @@ The goal is to create a kernel and supporting apps that tie together modern web
 - `Metal`: An API server for allowing connections to physical systems from ecmaOS using [Hono](https://hono.dev)
 - `SWAPI`: An API server running completely inside a service worker using [Hono](https://hono.dev)
 
-## Basic Overview
-
-- `Apps`
-  - These are full applications that are developed specifically to work with ecmaOS
-  - Refer to the full list of [official published apps on npm](https://www.npmjs.com/org/ecmaos-apps)
-  - See the [./APPS.md](./APPS.md) file for a list of community apps; submit a PR to add your app!
-  - An app is an npm package, in which the bin file has a shebang line of `#!ecmaos:bin:app:myappname`
-  - Its default export (or exported `main` function) will be called with the `ProcessEntryParams` object
-  - They can be installed from the terminal using the `install` command, e.g. `# install @ecmaos-apps/code`
-  - Run the installed app (bins are linked to `/usr/bin`): `# code /root/hello.js`
-  - During development, it can be useful to run a [Verdaccio](https://github.com/verdaccio/verdaccio) server to test local packages
-  - To publish to Verdaccio, run `# npm publish --registry http://localhost:4873` in your app's development environment
-  - Then to install from your local registry, run `# install @myscope/mypackage --registry http://localhost:4873`
-
-- `BIOS`
-  - The BIOS is a C++ module compiled to WebAssembly with [Emscripten](https://emscripten.org) providing performance-critical functionality
-  - The BIOS has its own filesystem, located at `/bios` — this allows data to be copied in and out of the BIOS for custom code and utilities
-  - The main idea is that data and custom code can be loaded into it from the OS for WASM-native performance, as well as providing various utilities
-  - Confusingly, the Kernel loads the BIOS — not the other way around
-
-- `Core`
-  - Core modules provide the system's essential functionality; this includes the kernel itself
-  - Other core modules include BIOS, Jaffa, Metal, SWAPI, as well as the main `@ecmaos/types` package
-
-- `Commands`
-  - Commands are small utilities that aren't quite full Apps, provided by the shell
-  - Some builtin commands that exist now will be moved into separate apps over time
-
-- `Devices`
-  - Refer to the full list of [official devices on npm](https://www.npmjs.com/org/ecmaos-devices)
-  - See the [./DEVICES.md](./DEVICES.md) file for a list of community devices; submit a PR to add your device!
-  - Devices get loaded on boot, e.g. `/dev/bluetooth`, `/dev/random`, `/dev/battery`, etc.
-  - A device can support being "run" by a user, e.g. `# /dev/battery status`
-  - Devices may also be directly read/written using `fs` methods, and will behave accordingly (or have no effect if not supported)
-  - An individual device module can provide multiple device drivers, e.g. `/dev/usb` provides `/dev/usb-mydevice-0001-0002`
-
-- `Generators`
-  - Generators are used to scaffold new apps, devices, modules, etc.
-  - They are located in the `turbo/generators` directory of the repository
-  - They are used by the `turbo gen` command, e.g. `turbo gen app`, `turbo gen device`, `turbo gen module`, etc.
-
-- `Jaffa`
-  - Jaffa is a [Tauri](https://tauri.app) wrapper for the ecmaOS kernel
-  - It's used to tie the kernel into a desktop or mobile environment, allowing for native functionality
-
-- `Kernel`
-  - The kernel ties together the various components of the system into a cohesive whole
-    - Authentication (WebAuthn)
-    - Components (Web Components/Custom Elements)
-    - Devices
-    - DOM
-    - Events (CustomEvents)
-    - Filesystem (ZenFS)
-    - Internationalization (i18next)
-    - Interval Manager (setInterval)
-    - Log Manager (tslog)
-    - Memory Manager (Abstractions)
-    - Process Manager
-    - Protocol Handlers (web+ecmaos://...)
-    - Service Worker Manager
-    - Shell
-    - Storage (IndexedDB, localStorage, sessionStorage, etc.)
-    - Terminal (xterm.js)
-    - User Manager
-    - WASM Loader
-    - Window Manager (WinBox)
-    - Workers (Web Workers)
-
-- `Metal`
-  - Metal is an API server for allowing connections to physical systems from ecmaOS using [Hono](https://hono.dev)
-  - Authenticated and encrypted connections with JWK/JWE/JOSE
-
-- `Modules`
-  - Refer to the full list of [official modules on npm](https://www.npmjs.com/org/ecmaos-modules)
-  - See the [./MODULES.md](./MODULES.md) file for a list of community modules; submit a PR to add your module!
-  - Modules are dynamically loaded into the kernel at boot and can be enabled or disabled
-  - They are specified during build via the `VITE_KERNEL_MODULES` environment variable
-    - e.g. `VITE_KERNEL_MODULES=@ecmaos-modules/boilerplate@0.1.2,@your/package@1.2.3`
-  - Versions must be exact and are mandatory - you cannot use NPM version specifiers
-  - They can provide additional functionality, devices, commands, etc.
-  - They offer a [common interface](./core/types/modules.ts) for interacting with the kernel
-  - Generally they should be written in [AssemblyScript](https://www.assemblyscript.org), but this isn't required
-
-- `Packages`
-  - Packages are [NPM packages](https://www.npmjs.com) that are installed into the ecmaOS environment
-  - They can be installed from the terminal using the `install` command, e.g. `# install jquery`
-  - NPM version specifiers are supported, e.g.:
-    - `# install jquery@3.7.1`
-    - `# install jquery@^3.7.1`
-    - `# install jquery@latest`
-  - [JSR](https://jsr.io) may be used with the [NPM compatibility layer](https://jsr.io/docs/npm-compatibility):
-    - `# install @jsr/defaude__hello-jsr --registry https://npm.jsr.io`
-
-- `SWAPI`
-  - The SWAPI is an API server running completely inside a service worker using [Hono](https://hono.dev)
-  - It allows for various operations including the `fs` route to fetch files via URL
-  - e.g., `# fetch /swapi/fs/home/user/hello.txt`
-  - e.g., `# fetch /swapi/fake/person/fullName`
-
-- `Utils`
-  - Utilities and configuration used during development
+## Basic Concepts
+
+### Apps
+
+> [/apps](/apps)
+
+- These are full applications that are developed specifically to work with ecmaOS
+- Refer to the full list of [official published apps on npm](https://www.npmjs.com/org/ecmaos-apps)
+- See the [APPS.md](/APPS.md) file for a list of community apps; submit a PR to add your app!
+- An app is an npm package, in which the bin file has a shebang line of `#!ecmaos:bin:app:myappname`
+- Its default export (or exported `main` function) will be called with the `ProcessEntryParams` object
+- They can be installed from the terminal using the `install` command, e.g. `# install @ecmaos-apps/code`
+- Run the installed app (bins are linked to `/usr/bin`): `# code /root/hello.js`
+- During development, it can be useful to run a [Verdaccio](https://github.com/verdaccio/verdaccio) server to test local packages
+- To publish to Verdaccio, run `# npm publish --registry http://localhost:4873` in your app's development environment
+- Then to install from your local registry, run `# install @myscope/mypackage --registry http://localhost:4873`
+
+### BIOS
+
+> [/core/bios](/core/bios)
+
+- The BIOS is a C++ module compiled to WebAssembly with [Emscripten](https://emscripten.org) providing performance-critical functionality
+- The BIOS has its own filesystem, located at `/bios` — this allows data to be copied in and out of the BIOS for custom code and utilities
+- The main idea is that data and custom code can be loaded into it from the OS for WASM-native performance, as well as providing various utilities
+- Confusingly, the Kernel loads the BIOS — not the other way around
+
+### Commands
+
+> [/core/kernel/src/tree/lib/commands](/core/kernel/src/tree/lib/commands)
+
+- Commands are small utilities that aren't quite full Apps, provided by the shell
+- Some builtin commands that exist now will be moved into separate apps over time
+
+### Devices
+
+> [/devices](/devices)
+
+- Refer to the full list of [official devices on npm](https://www.npmjs.com/org/ecmaos-devices)
+- See the [DEVICES.md](/DEVICES.md) file for a list of community devices; submit a PR to add your device!
+- Devices get loaded on boot, e.g. `/dev/bluetooth`, `/dev/random`, `/dev/battery`, etc.
+- A device can support being "run" by a user, e.g. `# /dev/battery status`
+- Devices may also be directly read/written using `fs` methods, and will behave accordingly (or have no effect if not supported)
+- An individual device module can provide multiple device drivers, e.g. `/dev/usb` provides `/dev/usb-mydevice-0001-0002`
+
+### Generators
+
+> [/turbo/generators](/turbo/generators)
+
+- Generators are used to scaffold new apps, devices, modules, etc.
+- They are located in the `turbo/generators` directory of the repository
+- They are used by the `turbo gen` command, e.g. `turbo gen app`, `turbo gen device`, `turbo gen module`, etc.
+
+### Jaffa
+
+> [/core/jaffa](/core/jaffa)
+
+- Jaffa is a [Tauri](https://tauri.app) wrapper for the ecmaOS kernel
+- It's used to tie the kernel into a desktop or mobile environment, allowing for native functionality
+
+### Kernel
+
+> [/core/kernel](/core/kernel)
+
+- The kernel ties together the various components of the system into a cohesive whole
+  - Authentication (WebAuthn)
+  - Components (Web Components/Custom Elements)
+  - Devices
+  - DOM
+  - Events (CustomEvents)
+  - Filesystem (ZenFS)
+  - Internationalization (i18next)
+  - Interval Manager (setInterval)
+  - Log Manager (tslog)
+  - Memory Manager (Abstractions)
+  - Process Manager
+  - Protocol Handlers (web+ecmaos://...)
+  - Service Worker Manager
+  - Shell
+  - Storage (IndexedDB, localStorage, sessionStorage, etc.)
+  - Terminal (xterm.js)
+  - User Manager
+  - WASM Loader
+  - Window Manager (WinBox)
+  - Workers (Web Workers)
+
+### Metal
+
+> [/core/metal](/core/metal)
+
+- Metal is an API server for allowing connections to physical systems from ecmaOS using [Hono](https://hono.dev)
+- Authenticated and encrypted connections with JWK/JWE/JOSE
+
+### Modules
+
+> [/modules](/modules)
+
+- Refer to the full list of [official modules on npm](https://www.npmjs.com/org/ecmaos-modules)
+- See the [MODULES.md](/MODULES.md) file for a list of community modules; submit a PR to add your module!
+- Modules are dynamically loaded into the kernel at boot and can be enabled or disabled
+- They are specified during build via the `VITE_KERNEL_MODULES` environment variable
+  - e.g. `VITE_KERNEL_MODULES=@ecmaos-modules/boilerplate@0.1.0,@your/package@1.2.3`
+- Versions must be pinned and are mandatory - you cannot use NPM version specifiers
+- They can provide additional functionality, devices, commands, etc.
+- They offer a [common interface](./core/types/modules.ts) for interacting with the kernel
+- Generally they should be written in [AssemblyScript](https://www.assemblyscript.org), but this isn't required
+
+### Packages
+
+- Packages are [NPM packages](https://www.npmjs.com) that are installed into the ecmaOS environment
+- They can be installed from the terminal using the `install` command, e.g. `# install jquery`
+- NPM version specifiers are supported, e.g.:
+  - `# install jquery@3.7.1`
+  - `# install jquery@^3.7.1`
+  - `# install jquery@latest`
+- [JSR](https://jsr.io) may be used with the [NPM compatibility layer](https://jsr.io/docs/npm-compatibility):
+  - `# install @jsr/defaude__hello-jsr --registry https://npm.jsr.io`
+
+### SWAPI
+
+> [/core/swapi](/core/swapi)
+
+- The SWAPI is an API server running completely inside a service worker using [Hono](https://hono.dev)
+- It allows for various operations including the `fs` route to fetch files via URL
+- e.g., `# fetch /swapi/fs/home/user/hello.txt`
+- e.g., `# fetch /swapi/fake/person/fullName`
+
+### Utils
+
+> [/utils](/utils)
+
+- Utilities and configuration used during development
+
+## Important Files and Directories
+
+- `/bin/`: Built-in commands
+- `/bios/`: The BIOS filesystem
+- `/boot/init`: A script that runs on boot
+- `/dev/`: All devices are here
+- `/etc/packages`: A list of installed packages to load on boot
+- `/home/`: Contains user home directories
+- `/proc/`: A directory containing various dynamic system information
+- `/root/`: The home directory for the root user
+- `/usr/bin/`: Executable packages get linked here
+- `/usr/lib/`: All installed packages are here
+- `/var/log/kernel.log`: The kernel log
 
 ## Command Examples
 
@@ -243,6 +287,15 @@ The `apps` directory in the repository contains a number of examples of how to d
 
 Basically, your app's [bin](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin) file has a `main` (or default) function export that is passed the kernel reference and can use it to interact with the system as needed. A shebang line of `#!ecmaos:bin:app:myappname` is required at the top of the bin file to identify it as an app.
 
+## Kernel Interface Example
+
+```ts
+export default async function main({ kernel }: ProcessEntryParams) {
+  kernel.log.info("Hello, world!");
+  kernel.terminal.writeln("Hello, world!");
+}
+```
+
 ## Early Days
 
 The kernel is currently in active development. It is not considered stable and the structure and API are very likely to change in unexpected and possibly unannounced ways until version 1.0.0. Use cautiously and at your own risk.
@@ -252,8 +305,9 @@ Things to keep in mind:
 - Things have changed a lot since the tests were written, so they need to be updated and fixed
 - The kernel is designed to be run in an environment with a DOM (i.e. a browser)
 - Many features are only available on Chromium-based browsers, and many more behind feature flags
+- There will be a lot of technical challenges to overcome, and many things will first be implemented in a non-optimal way
 - Command interfaces won't match what you might be used to from a traditional Linux environment; not all commands and options are supported. Over time, Linuxish commands will be fleshed out and made to behave in a more familiar way.
-- Globbing doesn't work in the terminal yet
+- Globbing doesn't work in the terminal yet, [but is supported at the filesystem level](https://zenfs.dev/core/functions/fs.promises.glob.html)
 
 ## Development
 
@@ -269,9 +323,9 @@ git clone https://github.com/ecmaos/ecmaos.git
 cd ecmaos && pnpm install
 
 # Run the dev server
-pnpm run dev
+pnpm run dev:kernel
 
-# Run the docs server
+# Run the docs server (optional)
 pnpm run dev:docs
 
 # Build
@@ -285,10 +339,12 @@ pnpm run test:bench
 pnpm run test:ui
 
 # Generate modules
+turbo gen app # generate a new app template
 turbo gen device # generate a new device template
+turbo gen module # generate a new module template
 ```
 
-Also see [turbo.json](./turbo.json) and [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
+Also see [turbo.json](./turbo.json) and [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
 
 ## Security Vulnerabilities
 

package/dist/.vite/manifest.json

@@ -1,18 +1,18 @@
 {
-  "_browser-C0q0NWWv.js": {
-    "file": "browser-C0q0NWWv.js",
+  "_browser-D_CtuxSB.js": {
+    "file": "browser-D_CtuxSB.js",
     "name": "browser",
     "isDynamicEntry": true,
     "imports": [
-      "_empty-BMkCc_7L.js"
+      "_empty--zdtkf0T.js"
     ]
   },
-  "_empty-BMkCc_7L.js": {
-    "file": "empty-BMkCc_7L.js",
+  "_empty--zdtkf0T.js": {
+    "file": "empty--zdtkf0T.js",
     "name": "empty",
     "dynamicImports": [
-      "_topbar.min-xBbuiIjv.js",
-      "_browser-C0q0NWWv.js",
+      "_topbar.min-CDkSVOxV.js",
+      "_browser-D_CtuxSB.js",
       "src/tree/lib/commands/install.ts",
       "node_modules/.pnpm/figlet@1.8.0/node_modules/figlet/importable-fonts/Poison.js"
     ]
@@ -21,12 +21,12 @@
     "file": "kernel.css",
     "src": "_kernel.css"
   },
-  "_topbar.min-xBbuiIjv.js": {
-    "file": "topbar.min-xBbuiIjv.js",
+  "_topbar.min-CDkSVOxV.js": {
+    "file": "topbar.min-CDkSVOxV.js",
     "name": "topbar.min",
     "isDynamicEntry": true,
     "imports": [
-      "_empty-BMkCc_7L.js"
+      "_empty--zdtkf0T.js"
     ]
   },
   "node_modules/.pnpm/figlet@1.8.0/node_modules/figlet/importable-fonts/Poison.js": {
@@ -41,16 +41,16 @@
     "src": "src/tree/kernel.ts",
     "isEntry": true,
     "imports": [
-      "_empty-BMkCc_7L.js"
+      "_empty--zdtkf0T.js"
     ]
   },
   "src/tree/lib/commands/install.ts": {
-    "file": "install-C64fBUI2.js",
+    "file": "install-Ds1oWgTf.js",
     "name": "install",
     "src": "src/tree/lib/commands/install.ts",
     "isDynamicEntry": true,
     "imports": [
-      "_empty-BMkCc_7L.js"
+      "_empty--zdtkf0T.js"
     ]
   },
   "src/ui.ts": {
@@ -59,7 +59,7 @@
     "src": "src/ui.ts",
     "isEntry": true,
     "imports": [
-      "_empty-BMkCc_7L.js"
+      "_empty--zdtkf0T.js"
     ]
   }
 }

package/dist/{browser-C0q0NWWv.js → browser-D_CtuxSB.js}

@@ -1,4 +1,4 @@
-import { g as getDefaultExportFromCjs } from "./empty-BMkCc_7L.js";
+import { g as getDefaultExportFromCjs } from "./empty--zdtkf0T.js";
 var browser$2;
 var hasRequiredBrowser;
 function requireBrowser() {
@@ -20,4 +20,4 @@ const browser$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.definePro
 export {
   browser$1 as b
 };
-//# sourceMappingURL=browser-C0q0NWWv.js.map
+//# sourceMappingURL=browser-D_CtuxSB.js.map

package/dist/{browser-C0q0NWWv.js.map → browser-D_CtuxSB.js.map}

@@ -1 +1 @@
-{"version":3,"file":"browser-C0q0NWWv.js","sources":["../node_modules/.pnpm/ws@8.18.0/node_modules/ws/browser.js"],"sourcesContent":["'use strict';\n\nmodule.exports = function () {\n  throw new Error(\n    'ws does not work in the browser. Browser clients must use the native ' +\n      'WebSocket object'\n  );\n};\n"],"names":["browser"],"mappings":";;;;;;AAEAA,cAAiB,WAAY;AAC3B,UAAM,IAAI;AAAA,MACR;AAAA,IAED;AAAA,EACF;;;;;;;;;","x_google_ignoreList":[0]}
+{"version":3,"file":"browser-D_CtuxSB.js","sources":["../node_modules/.pnpm/ws@8.18.0/node_modules/ws/browser.js"],"sourcesContent":["'use strict';\n\nmodule.exports = function () {\n  throw new Error(\n    'ws does not work in the browser. Browser clients must use the native ' +\n      'WebSocket object'\n  );\n};\n"],"names":["browser"],"mappings":";;;;;;AAEAA,cAAiB,WAAY;AAC3B,UAAM,IAAI;AAAA,MACR;AAAA,IAED;AAAA,EACF;;;;;;;;;","x_google_ignoreList":[0]}