OopisOS User Guide (v2.6)

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.6.

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, links, quotes, code blocks, and lists, saving you from remembering the syntax.
• Status Bar: A handy bar at the bottom shows cursor position (line, column), total lines, word count, and character count.
• Word Wrap: Toggle it on for prose, off for code. Your preference is saved for next time.
• Export to HTML: Click the "Export" button to download a fully rendered HTML file of your Markdown/HTML preview.
• 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.

The ASCII Art Studio (`paint` command)

For when text is not enough, OopisOS includes a surprisingly powerful character-based art editor. The paint command opens a dedicated, full-screen canvas where you can create ASCII and ANSI art.

• Canvas & Tools: The editor features an 80x24 character canvas. Use the Pencil tool to draw with a selected character and color, or the Eraser tool to clear cells.
• Color Palette: Add a splash of color to your creations with a 6-color ANSI palette (green, red, sky, amber, lime, neutral).
• File Format: Your masterpieces are saved to a custom .oopic file format, which stores character, color, and canvas dimension data in a JSON structure.
• Keyboard-First Workflow:
  • P / E: Switch between Pencil and Eraser tools.
  • 1-6: Select a color from the palette.
  • Any other character key: Sets the character to be used by the pencil.
  • Ctrl+S: Save & Exit.
  • Ctrl+O: Exit without saving (will prompt if there are unsaved changes).
  • Ctrl+Z / Ctrl+Y: Undo and Redo your strokes.

Users, Groups, and Permissions

OopisOS isn't a free-for-all. It's a sophisticated society of users with rules, groups, and private property. Passwords are 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. Every user is in their own primary group by default (e.g., user 'Guest' is in group 'Guest').
  • 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. A primary group with the same name is also created.
• 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`, `chown`, `chgrp`)

Use ls -l to view permissions like -rwxr-x---. This string represents: [type][owner permissions][group permissions][other permissions].

• chmod [mode] [path]: Change a file's permissions. Mode is a 3-digit octal number (0-7). The digits represent Owner, Group, and Other. Permissions are: 4 (read), 2 (write), 1 (execute). Add them up for the desired combination!
  • chmod 755 myfile: Owner gets 7 (4+2+1 -> rwx), group gets 5 (4+0+1 -> r-x), others get 5 (r-x).
  • chmod 640 myfile: Owner gets 6 (4+2+0 -> rw-), group gets 4 (4+0+0 -> r--), others get 0 (---).
• chown [new_owner] [path]: Change who owns a file. Only `root` can do this.
• chgrp [new_group] [path]: Change a file's group. Only the 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.6: 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., 755).
  • -mtime [+N|-N|N]: Find by modification time in days (e.g., `+7` for older than 7 days, `-2` for newer than 2 days).
  • -newermt [date_string]: Find files modified more recently than the given date string (e.g., "1 day ago", "2025-01-01").
• 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 ;.

Managing Background Processes (`ps` & `kill`)

Sent a long-running task to the background with `&` and now you regret it? Or maybe you just want to see what's still churning away. OopisOS v2.6 gives you the tools to be the master of your background jobs.

• ps: Stands for "Process Status". This command gives you a neat list of all the commands currently running in the background. Each job has a unique Process ID (PID) that you can use to interact with it.
• kill [PID]: The solution to a runaway process. Use this command with the PID from `ps` to terminate a background job immediately.

Connecting to the World: `wget` & `curl`

OopisOS can now reach beyond its digital borders! The `wget` and `curl` commands allow you to interact with the real-world internet, downloading files and fetching data directly into your virtual environment. Please note that these commands are subject to the browser's Cross-Origin Resource Sharing (CORS) policies, so they may not work with all websites.

wget [-O file] [url]

The "web get" command. Its primary purpose is to download files. By default, it saves the file with its original name from the URL.

• -O [file]: Use this flag to specify a different output filename.

curl [-o file] [url]

A versatile data transfer tool. By default, `curl` fetches the content from a URL and prints it directly to your terminal screen. This is great for quickly viewing data from APIs or reading simple text files without saving them.

• -o [file]: Use this flag to redirect the output to a file instead of the screen.

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.6 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 'The Lost Key of Oopis.'
• 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.6: 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`:

• `main.js` & `config.js` & `utils.js`: The heart and soul. Contains core infrastructure, configs, utilities, and managers for the file system, users, sessions, terminal UI, and more.
• `lexpar.js`: The brainy part. Contains the Lexer and Parser that translate your typed commands into something the machine can understand.
• `commexec.js`: The muscle. This is the Command Executor, containing the definitions and handlers for every single command in the OS.
• `editor.js`: The artist's studio. All logic for the `edit` command's powerful text editor lives here.
• `paint.js`: The other artist's studio. All logic for the `paint` command's ASCII/ANSI art editor.
• `adventure.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.6 Way)

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

// In commexec.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.6 comes with two powerful scripts, `inflate.sh` and `diag.sh`, to make life easier for testers and newcomers.

The Showcase: `inflate.sh`

Want a fully furnished world to explore from the get-go? The `inflate.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 `/shared_for_guest` directory to test permissions.
• Secret hidden files for you to discover with `ls -a`.

The Gauntlet: `diag.sh`

This is the ultimate test of OopisOS's core strength. The `diag.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`, `chgrp`, `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`, `alias`, `ps`, `kill`, and various flags are working correctly.
• Cleanup: Switches to `root` and cleans up after itself, leaving the system tidy.

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

Recent Changes

Version 2.6 (Current)

• Environment Variables: Added a full environment variable system. Use `set` to create/view variables, `unset` to remove them, and `$VAR` or `${VAR}` in any command for shell expansion. Default variables include `$USER`, `$HOME`, `$HOST`, and `$PATH`.
• Paint Application: Introduced the `paint` command, a full-screen ASCII/ANSI art editor with multiple colors, tools, and a custom `.oopic` save format.

Version 2.5

• Initial public release version.
• Features included the core file system, multi-user support, text editor, and `gemini` integration.

About OopisOS (v2.6)

OopisOS Version 2.6 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` reflects this grand alliance.

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")

Authorship and Contribution Acknowledgment

This Software was developed by the Curator through a process of interactive collaboration with Google's Gemini, an artificial intelligence language model (hereinafter referred to as the "AI Assistant"). The Curator provided the initial concepts, creative direction, iterative prompts, critical review, testing, and the selection of the final form of the Software. The AI Assistant, under the explicit direction and oversight of the Curator, 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 (INCLUDING THE CURATOR) OR COPYRIGHT HOLDERS (TO THE EXTENT APPLICABLE UNDER LAW REGARDING AI-ASSISTED WORKS) 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.6: Now with 26% more Oopis!"