Merge branch 'main' into warning_dialog

Author: jelveh

Diff for: CONTRIBUTING.md

@@ -45,15 +45,18 @@ If you'd like to contribute code to Puter, you need to fork the project and subm
 
 We'll review your pull request and work with you to get your changes merged into the project.
 
+## Repository Structure
+
+![file structure](./doc/File%20Structure.drawio.png)
+
 ## Your first code contribution
 
 We maintain a list of issues that are good for first-time contributors. You can find these issues by searching for the [`good first issue`](https://github.com/HeyPuter/puter/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label in our [GitHub repository](https://github.com/HeyPuter/puter). These issues are designed to be relatively easy to fix, and we're happy to help you get started. Pick an issue that interests you, and leave a comment on the issue to let us know you're working on it.
 
-<br>
-
 ## Documentation for Contributors
 
-See [doc/contributors/index.md](./doc/contributors/index.md) for more information.
+### Backend
+See [src/backend/CONTRIBUTING.md](src/backend/CONTRIBUTING.md)
 
 <br>
 

Diff for: awesome/#DoesItRunPuter.md

@@ -13,3 +13,4 @@
 - [Steam Deck](https://twitter.com/everythingSung/status/1782162352403828793)
 - [Ladybird Browser](https://x.com/HeyPuter/status/1810783504503800035)
 - [Garry's Mod](https://x.com/HeyPuter/status/1850587712786722862)
+- [Samsung Q88BA](https://x.com/AmirIsAround/status/1862614583263076540)

Diff for: doc/File Structure.drawio

@@ -1,2 +1,3 @@
-### `vscode`
-- `es6-string-html`
+## Puter Extensions
+
+See the [Wiki Page](https://github.com/HeyPuter/puter/wiki/ex_extensions)

Diff for: doc/File Structure.drawio.png

@@ -0,0 +1,2 @@
+### `vscode`
+- `es6-string-html`

Diff for: doc/contributors/extensions.md

@@ -17,7 +17,6 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#!/usr/bin/env node
 /*
  * Copyright (C) 2024 Puter Technologies Inc.
  *

Diff for: doc/contributors/vscode.md

@@ -21,7 +21,6 @@
 //       we have these things registered in "useapi".
 const {
     get_user,
-    generate_system_fsentries,
     invalidate_cached_user,
     deleteUser,
 } = require('../../../src/backend/src/helpers.js');
@@ -146,7 +145,8 @@ class ShareTestService extends use.Service {
             ],
         );
         const user = await get_user({ username });
-        await generate_system_fsentries(user);
+        const svc_user = this.services.get('user');
+        await svc_user.generate_default_fsentries({ user });
         invalidate_cached_user(user);
         return user;
     }

Diff for: experiments/x86emu/www/main.js

@@ -30,7 +30,7 @@
     "webpack-cli": "^5.1.1"
   },
   "scripts": {
-    "test": "npx mocha src/phoenix/test src/contextlink/test && node src/backend/tools/test",
+    "test": "npx mocha src/phoenix/test && node src/backend/tools/test",
     "start=gui": "nodemon --exec \"node dev-server.js\" ",
     "start": "node ./tools/run-selfhosted.js",
     "build": "cd src/gui; node ./build.js",

Diff for: mods/mods_available/kdmod/ShareTestService.js

@@ -1,40 +1,44 @@
 # Contributing to Puter's Backend
 
+## File Structure
+
+
+
 ## Architecture
 
-- [boot sequence](./boot-sequence.md)
-- [modules and services](./modules.md)
+- [boot sequence](./doc/contributors/boot-sequence.md)
+- [modules and services](./doc/contributors/modules.md)
 
 ## Features
 
-- [protected apps](../features/protected-apps.md)
-- [service scripts](../features/service-scripts.md)
+- [protected apps](./doc/features/protected-apps.md)
+- [service scripts](./doc/features/service-scripts.md)
 
 ## Lists of Things
 
-- [list of permissions](../lists-of-things/list-of-permissions.md)
+- [list of permissions](./doc/lists-of-things/list-of-permissions.md)
 
 ## Code-First Approach
 
 If you prefer to understand a system by looking at the
 first files which are invoked and starting from there,
 here's a handy list!
 
-- [Kernel](../../src/Kernel.js), despite its intimidating name, is a
+- [Kernel](./src/Kernel.js), despite its intimidating name, is a
   relatively simple (< 200 LOC) class which loads the modules
   (modules register services), and then starts all the services.
-- [RuntimeEnvironment](../../src/boot/RuntimeEnvironment.js)
+- [RuntimeEnvironment](./src/boot/RuntimeEnvironment.js)
   sets the configuration and runtime directories. It's invoked by Kernel.
 - The default setup for running a self-hosted Puter loads these modules:
-  - [CoreModule](../../src/CoreModule.js)
-  - [DatabaseModule](../../src/DatabaseModule.js)
-  - [LocalDiskStorageModule](../../src/LocalDiskStorageModule.js)
+  - [CoreModule](./src/CoreModule.js)
+  - [DatabaseModule](./src/DatabaseModule.js)
+  - [LocalDiskStorageModule](./src/LocalDiskStorageModule.js)
 - HTTP endpoints are registered with
-  [WebServerService](../../src/services/WebServerService.js)
+  [WebServerService](./src/services/WebServerService.js)
   by these services:
-  - [ServeGUIService](../../src/services/ServeGUIService.js)
-  - [PuterAPIService](../../src/services/PuterAPIService.js)
-  - [FilesystemAPIService](../../src/services/FilesystemAPIService.js)
+  - [ServeGUIService](./src/services/ServeGUIService.js)
+  - [PuterAPIService](./src/services/PuterAPIService.js)
+  - [FilesystemAPIService](./src/services/FilesystemAPIService.js)
 
 ## Development Philosophies
 
@@ -71,7 +75,7 @@ doing the useless work that reveals what the useful work is.
 
 ## Underlying Constructs
 
-- [putility's README.md](../../packages/putility/README.md)
+- [putility's README.md](../putility/README.md)
   - Whenever you see `AdvancedBase`, that's from here
     - Many things in backend extend this. Anything that doesn't only doesn't
       because it was written before `AdvancedBase` existed.

Diff for: package-lock.json

@@ -0,0 +1,65 @@
+# Puter Kernel Documentation
+
+## Overview
+
+The **Puter Kernel** is the core runtime component of the Puter system. It provides the foundational infrastructure for:
+
+- Initializing the runtime environment
+- Managing internal and external modules (extensions)
+- Setting up and booting core services
+- Configuring logging and debugging utilities
+- Integrating with third-party modules and performing dependency installs at runtime
+
+This kernel is responsible for orchestrating the startup sequence and ensuring that all necessary services, modules, and environmental configurations are properly loaded before the application enters its operational state.
+
+---
+
+## Features
+
+1. **Modular Architecture**:  
+   The Kernel supports both internal and external modules:
+   - **Internal Modules**: Provided to Kernel by an initializing script, such
+     as `tools/run-selfhosted.js`, via the `add_module()` method.
+   - **External Modules**: Discovered in configured module directories and installed
+     dynamically. This includes resolving and executing `package.json` entries and
+     running `npm install` as needed.
+
+2. **Service Container & Registry**:  
+   The Kernel initializes a service container that manages a wide range of services. Services can:
+   - Register modules
+   - Initialize dependencies
+   - Emit lifecycle events (`boot.consolidation`, `boot.activation`, `boot.ready`) to
+     orchestrate a stable and consistent environment.
+
+3. **Runtime Environment Setup**:  
+   The Kernel sets up a `RuntimeEnvironment` to determine configuration paths and environment parameters. It also provides global helpers like `kv` for key-value storage and `cl` for simplified console logging.
+
+4. **Logging and Debugging**:  
+   Uses a temporary `BootLogger` for the initialization phase until LogService is
+   initialized, at which point it will replace the boot logger. Debugging features
+   (`ll`, `xtra_log`) are enabled in development environments for convenience.
+
+## Initialization & Boot Process
+
+1. **Constructor**:  
+   When a Kernel instance is created, it sets up basic parameters, initializes an empty
+   module list, and prepares `useapi()` integration.
+
+2. **Booting**:  
+   The `boot()` method:
+   - Parses CLI arguments using `yargs`.
+   - Calls `_runtime_init()` to set up the `RuntimeEnvironment` and boot logger.
+   - Initializes global debugging/logging utilities.
+   - Sets up the service container (usually called `services`c instance of **Container**).
+   - Invokes module installation and service bootstrapping processes.
+
+3. **Module Installation**:  
+   Internal modules are registered and installed first.  
+   External modules are discovered, packaged, installed, and their code is executed.  
+   External modules are given a special context with access to `useapi()`, a dynamic
+   import mechanism for Puter modules and extensions.
+
+4. **Service Bootstrapping**:  
+   After modules and extensions are installed, services are initialized and activated.
+   For more information about how this works, see [boot-sequence.md](./contributors/boot-sequence.md).
+

Diff for: package.json

@@ -28,6 +28,9 @@ const { Context } = require("./src/util/context.js");
 const { TestDriversModule } = require("./src/modules/test-drivers/TestDriversModule.js");
 const { PuterAIModule } = require("./src/modules/puterai/PuterAIModule.js");
 const { BroadcastModule } = require("./src/modules/broadcast/BroadcastModule.js");
+const { WebModule } = require("./src/modules/web/WebModule.js");
+const { Core2Module } = require("./src/modules/core/Core2Module.js");
+const { TemplateModule } = require("./src/modules/template/TemplateModule.js");
 
 
 module.exports = {
@@ -42,9 +45,17 @@ module.exports = {
     Context,
 
     Kernel,
+    
+    EssentialModules: [
+        Core2Module,
+        CoreModule,
+        WebModule,
+        TemplateModule,
+    ],
 
     // Pre-built modules
     CoreModule,
+    WebModule,
     DatabaseModule,
     PuterDriversModule,
     LocalDiskStorageModule,