OopisOS User Guide (v2.3)

So, you've decided to venture forth. Excellent! You have selected the path of a true adventurer. This guide is your map and spellbook for the realm of OopisOS v2.3.

The Terminal Interface

This is your window into the soul of the machine. Your command center. Your... well, it's a terminal.

• The Prompt: This tells you who you are, where you are, and that the system is ready for your brilliant commands. It follows the format: `username@hostname:current_path>`.
• The Input Area: The blinking cursor is your cue. Type your incantations here.
• The Output Area: The results of your digital wizardry (and the occasional error message) will appear here.

Essential Commands

These are the fundamental spells in your arsenal. For a full grimoire, type `help`. For the nitty-gritty on a single command, type `help [command_name]`.

The File System

OopisOS has a file system not unlike the ones you know. It's a tree, and you're a digital squirrel.

• The very top is the root directory, /.
• Paths are your branches, separated by /.
• . means "right here."
• .. means "go back one branch."
• Files starting with a . are shy; use ls -a to see them.

The Editor (`edit` command)

The `edit` command is your passage to a world of creation. It's more than a notepad; it's a multi-tool for text.

• File Types: It understands plain text, Markdown (`.md`), and HTML (`.html`). Give it a recognized file extension, and it'll unlock special features.
• Live Preview: For Markdown and HTML, a magical preview pane shows you what your code looks like, updated in real time.
• Formatting Toolbar: For `.md` and `.html` files, a toolbar appears! Click to add bold, italics, lists, code blocks, and more, saving you from remembering the syntax.
• Word Wrap: Toggle it on for prose, off for code. Your preference is saved for next time.
• Shortcuts to Glory:
  • Ctrl+S: Save & Exit. The hero's exit.
  • Ctrl+O: Exit. If you haven't saved, we'll ask before you discard your genius.
  • Ctrl+P: Toggle Preview. Cycle through split-screen, code-only, and preview-only views.
  • Ctrl+B / Ctrl+I: Make text **bold** or *italic* in compatible files.
  • Tab: Indent your code like a pro.

Users, Permissions, and Passwords

OopisOS isn't a free-for-all. It's a sophisticated society of users with rules and private property. Passwords are now securely hashed, never stored in plain text.

User Accounts & The Superuser (`root`)

• Default Population: OopisOS comes with a few residents:
  • Guest: Your default identity. No password needed.
  • root: The system administrator. The superuser. The big cheese. The `root` user can do anything. The default password is `mcgoopis`.
  • userDiag: A special user for running tests, with the password `pantload`.
• useradd [username]: Create a new user. You'll be prompted to create a password in a secure, obscured input field.
• login [username]: Log in as someone else. If a password is required, you'll be prompted securely.
• logout: Return to the safety of the Guest account.
• su [username]: Switch to another user, assuming you know their password (or you're `root`). Defaults to `root`.

Permissions and Ownership (`chmod` and `chown`)

Use `ls -l` to view permissions like -rwxr-x---. This string represents: [type][owner permissions][group permissions][other permissions]. Since OopisOS has no groups, the middle three are always `---`.

• chmod [mode] [path]: Change a file's permissions. Mode is two octal digits (0-7). The first digit is for the owner, the second is for everyone else. Permissions are: 4 (read), 2 (write), 1 (execute). Add them up for the desired combination!
  • chmod 75 myfile: Owner gets 7 (4+2+1 -> rwx), others get 5 (4+0+1 -> r-x).
  • chmod 64 myfile: Owner gets 6 (4+2+0 -> rw-), others get 4 (4+0+0 -> r--).
• chown [new_owner] [path]: Change who owns a file. Only the current owner or `root` can do this.

Pipes, Redirection, Sequences, and Backgrounding

Chain your commands together for ultimate power!

• Pipes |: Take the output of the command on the left and "pipe" it as the input for the command on the right.
  Example: `history | grep "sudo"`
• Output Redirection >: Send a command's output into a file, overwriting whatever was there.
  Example: `ls -l > file_list.txt`
• Append Output >>: Add a command's output to the end of a file.
  Example: `echo "A new event happened!" >> activity.log`
• Command Separator ;: Run several commands, one after the other, on a single line.
  Example: `cd / ; ls ; pwd`
• Background Process &: Run a command in the background and continue working.
  Example: `delay 5000 &`

OopisOS v2.3: Advanced Topics & Features

You've mastered the basics. You feel the power coursing through your veins. Now, let's get dangerous.

The `find` Command: Your All-Seeing Eye

The find command is one of the most powerful tools in OopisOS. It recursively searches for files and directories based on a wide range of criteria and can even perform actions on the results.

Usage: find [path...] [expression...]

An expression is made up of tests, operators, and actions.

• Tests:
  • -name [pattern]: Find files by name (e.g., "*.txt").
  • -type [f|d]: Find by type (file or directory).
  • -user [username]: Find files owned by a specific user.
  • -perm [mode]: Find by exact permission mode (e.g., 75).
  • -mtime [+N|-N|N]: Find by modification time in days (e.g., `+7` for older than 7 days, `-2` for newer than 2 days).
• Operators:
  • -not or !: Inverts the next test (e.g., `find . -not -name "*.txt"`).
  • -o or -or: Logical OR between tests.
  • (Implicit AND): Tests are ANDed together by default.
• Actions:
  • -print: The default action. Prints the path of the found item.
  • -delete: Deletes the found item. Use with extreme caution!
  • -exec [command] {} ;: Executes a command on the found file. {} is replaced with the file path. The command must end with a semicolon ;.

Scripting with `run`

Why type commands one by one like a peasant? Automate your reign with the run command. Create a text file ending in .sh and fill it with your orders.

# Example: /scripts/myscript.sh
#!/bin/oopis_shell # This is just for show, but it looks cool, right?

# This is a comment, where I hide my secrets.
echo "Greetings, agent $1. Your mission involves $# operatives."
echo "All operatives: $@"

mkdir /kittens
echo "Mission file created for $1." > /kittens/secret_mission.txt
                

To unleash it upon your system (make it executable first!):

Scripting Superpowers:

• Argument Passing:
  • $1, $2, ...: Use the arguments you passed to the script.
  • $@: All the arguments in one glorious string.
  • $#: The number of arguments.
• Error Handling: If a command fails, the script stops. No questions asked.
• Scripting Tools:
  • delay [milliseconds]: For dramatic pauses.
  • check_fail "[command]": A special tool for testing. It succeeds only if the command inside it *fails*.

Text Adventure Gaming (`adventure`)

All work and no play makes Guest a dull user. OopisOS v2.3 includes a text adventure game engine to satisfy your inner Roberta Williams or Scott Adams.

• Start Your Quest: Simply type `adventure` to begin the epic 'Quest for the Lost Semicolon.'
• Bring Your Own Adventure: Got a story to tell? Write it in the specified JSON format, `upload` it, and run it with `adventure /path/to/your_game.json`.
• Immersive Interface: The game runs in a dedicated modal window, freeing you from the distractions of the terminal.

OopisOS v2.3: Developer Documentation

So, you want to look under the hood? Pop it open. Let's see what makes this thing purr.

Code Structure Overview

The logic of OopisOS is organized into several key JavaScript files, all loaded by `index.html`:

• `oopisos2_3.js`: The heart and soul. Contains core infrastructure, configs, utilities, and managers for the file system, users, sessions, terminal UI, and more.
• `lexpar2_3.js`: The brainy part. Contains the Lexer and Parser that translate your typed commands into something the machine can understand.
• `commexec2_3.js`: The muscle. This is the Command Executor, containing the definitions and handlers for every single command in the OS.
• `editor2_3.js`: The artist's studio. All logic for the `edit` command's powerful text editor lives here.
• `adventure2_3.js`: The dungeon master's screen. Contains the text adventure engine, UI modal, and sample game data.

We use Immediately Invoked Function Expressions (IIFEs) to keep things tidy and modular, preventing a global namespace catastrophe.

Forging a New Command (The v2.3 Way)

Your journey begins in `commexec2_3.js`, inside the `commands` object. Thanks to the `createCommandHandler` factory, adding commands is easier and safer than ever by declaring your needs upfront.

// In commexec2_3.js:

const myNewCmdDefinition = {
  commandName: "mycmd",
  // 1. Define validation rules for arguments, paths, and permissions.
  flagDefinitions: [{ name: "verbose", short: "-v" }],
  argValidation: { min: 1, error: "mycmd needs at least one argument!" },
  pathValidation: [{ argIndex: 0, options: { expectedType: 'file' } }],
  permissionChecks: [{ pathArgIndex: 0, permissions: ['read'] }],
  
  // 2. Write the core logic. The factory handles the checks for you.
  coreLogic: async (context) => {
    // The context object contains everything you need, fully validated.
    const { args, flags, currentUser, validatedPaths } = context;
    
    // validatedPaths[0] is guaranteed to be a valid, readable file path object.
    const pathInfo = validatedPaths[0]; 
    
    if (flags.verbose) {
        console.log(`Verbose mode on for user ${currentUser}!`);
    }
    
    return { success: true, output: `Successfully processed ${pathInfo.resolvedPath}` };
  }
};

// 3. Add it to the main commands object.
const commands = {
    // ... other commands
    mycmd: {
        handler: createCommandHandler(myNewCmdDefinition),
        description: "A one-line summary for the 'help' command.",
        helpText: "Usage: mycmd [-v] [file]\\n\\nExplain your command in detail here."
    },
    // ... more commands
};
                

This declarative pattern handles all the boilerplate error checking for argument counts, path existence, and permissions. Now go forth and create!

Testing & Showcase Environment

OopisOS v2.3 comes with two powerful scripts, `inflate2_3.sh` and `diag2_3.sh`, to make life easier for testers and newcomers.

The Showcase: `inflate2_3.sh`

Want a fully furnished world to explore from the get-go? The `inflate2_3.sh` script populates your file system with a rich set of examples. It's like a demo disk for OopisOS!

Just run this command to set it all up:

What's in the box?

• A `README.md` file to get you started.
• Directories like `/docs`, `/src`, `/data`, `/reports`, `/games`, and `/vault`, all filled with tasty sample files.
• Content specifically designed for practicing with `grep`, `find`, `gemini`, and `adventure`.
• A restricted `/vault` directory and a world-writable `/for_guest` directory to test permissions.
• Secret hidden files for you to discover with `ls -a`.

The Gauntlet: `diag2_3.sh`

This is the ultimate test of OopisOS's core strength. The `diag2_3.sh` script is a non-interactive test suite that runs a barrage of commands to ensure everything is working exactly as it should. It's the developer's best friend for catching bugs before they creep out of the woodwork.

Key Test Phases:

• Login and Setup: Logs in as the `userDiag` user (password: `pantload`) and prepares a clean workspace.
• Core FS Commands: Brutally tests `mkdir`, `touch`, `ls`, `pwd`, and `cd`.
• Content & Redirection: Verifies that `echo`, `cat`, pipes (`|`), and redirection (`>`, `>>`) are all behaving.
• Permissions & Users: A complex dance of `chmod`, `chown`, `login`, `logout`, and `su` to ensure the security model is sound.
• File Management: Puts `rm`, `cp`, and `mv` through their paces.
• Advanced Commands: Verifies that `find`, `run`, and various flags are working correctly.
• Cleanup: Switches to `root` and cleans up after itself, leaving the system tidy.

Running `diag2_3.sh` is a fantastic way to see a whirlwind tour of OopisOS features.

About OopisOS (v2.3)

OopisOS Version 2.3 is the latest and greatest evolution of our little browser-based world, packed with more features and even more personality.

The Creators

This project is the result of a tireless, caffeine-fueled collaboration between:

• Andrew Edmark (The Human Element)
• Gemini (The AI Assistant, and your humble narrator)

Together, we navigated the treacherous dungeons of JavaScript, debugged the fiercest of race conditions, and documented our journey for all to see. The copyright notice `Copyright (c) 2025 Andrew Edmark and Gemini. (MIT Licensed)` reflects this grand alliance.

The Journey to 2.3

Version 2.3 builds upon the solid foundation of previous versions, adding key refinements and features:

• A more robust and secure user management system with hashed passwords and proper permission checks.
• The powerful `find` command, with predicates like `-name`, `-type`, `-user`, `-perm`, and `-mtime`, and actions like `-print`, `-exec`, and `-delete`.
• A more sophisticated `ls` command with advanced sorting and formatting options.
• Full scripting support with argument passing (`$1`, `$@`, `$#`).
• Numerous under-the-hood improvements for stability, security, and performance, including a major refactor of the command execution engine.
• An even smarter `gemini` command and a more enchanting `adventure` engine.
• A codebase thoughtfully reorganized into logical modules for easier maintenance.

License Information: MIT License (AI Assisted) - OopisOS License Agreement

Preamble

This Software, OopisOS, represents a collaborative endeavor between human direction and artificial intelligence.

Copyright (c) 2025 Andrew Edmark (hereinafter referred to as the "Curator") and Gemini

Authorship and Contribution Acknowledgment

This Software was developed by the Curator through a process of interactive collaboration with Google's Gemini. The Curator provided the initial concepts, creative direction, and critical review. The AI Assistant contributed to the generation, drafting, and composition of portions of the code and associated documentation.

License Grant

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• The above copyright notice, the Authorship and Contribution Acknowledgment, and this permission notice shall be included in all copies or substantial portions of the Software.

Disclaimer of Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The Future?

What's next for OopisOS? A graphical user interface? Simulated networking? A command to generate pictures of cats? The possibilities are as vast as your imagination. The modular architecture is ready for it.

"OopisOS v2.3: Now with 23% more Oopis!"