assayfluxos 0.1.0__tar.gz

assayfluxos-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 AssayFluxOS contributors
+
+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 and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

assayfluxos-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: assayfluxos
+Version: 0.1.0
+Summary: A thoughtfully designed Python shell and FluxScript workspace for Termux, Android-oriented workflows, and desktop Python.
+Author: AssayFluxOS contributors
+License: MIT
+Keywords: assayfluxos,shell,terminal,termux,android,fluxscript,interpreter,workspace,developer-tools,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AssayFluxOS 0.1.0
+
+**A calm, capable command-line workspace for Python, Termux, and the emerging FluxScript language.**
+
+AssayFluxOS brings everyday file work, a persistent project workspace, familiar full-word commands, and a small expressive scripting language into one approachable environment. It is designed for people who want to organise projects and experiment with a custom scripting workflow from a Python-capable terminal—including Termux on Android—without pretending that an early CLI is already a complete mobile operating system.
+
+> **Release status:** 0.1.0 is an alpha foundation. It provides a Python command-line application and an early FluxScript interpreter. A native Android APK/AAB, graphical terminal/editor, and some advanced language features are planned separately and are **not included** in this Python package.
+
+## Highlights
+
+- **Readable commands:** prefer `copy`, `move`, `rename`, `delete`, `directory`, and `change directory` instead of requiring cryptic abbreviations.
+- **A home for your work:** creates a structured `AssayFluxOS Files` workspace with project, document, data, script, module, plugin, download, log, backup, and configuration folders.
+- **FluxScript starter language:** variables, output and input, conditions, loops, functions, return/stop, collections, indexing, arithmetic, comparisons, and boolean expressions.
+- **Persistent preferences:** settings, aliases, and command history are stored in the workspace.
+- **Useful terminal workflows:** basic pipelines, output redirection, text search, file properties, and workspace tree inspection.
+- **Extension point:** trusted Python plugins can register additional commands.
+- **Backup tools:** create and restore workspace archives with path checks and a confirmation step.
+- **Python integration:** run trusted Python scripts from the CLI when appropriate.
+- **No mandatory runtime dependencies:** the core package uses the Python standard library.
+
+## Install
+
+Python 3.10 or newer is required.
+
+```bash
+python -m pip install assayfluxos
+```
+
+Start the shell with either command:
+
+```bash
+assayfluxos
+# or the short alias
+af
+```
+
+See command-line options:
+
+```bash
+assayfluxos --help
+```
+
+### Install from a downloaded source project
+
+From the project directory:
+
+```bash
+python -m pip install .
+```
+
+## Android / Termux workspace
+
+In Termux, enable Android shared-storage access when prompted:
+
+```bash
+termux-setup-storage
+```
+
+AssayFluxOS attempts to use `/storage/emulated/0/AssayFluxOS Files` when the shared-storage parent is writable. Otherwise it falls back to `~/AssayFluxOS Files`. You can explicitly choose a workspace where supported with `--workspace PATH`.
+
+The workspace initialisation creates these folders when missing and does not intentionally erase existing content:
+
+```text
+AssayFluxOS Files/
+├── Projects/
+│   ├── Python/
+│   ├── FluxScript/
+│   ├── Web/
+│   └── Experiments/
+├── Documents/
+├── Data/
+├── Scripts/
+├── Modules/
+├── Downloads/
+├── Logs/
+├── Backups/
+├── Config/
+└── Plugins/
+```
+
+For a future native Android app, the recommended design is to use Android's Storage Access Framework for user-selected directories rather than assuming unrestricted filesystem access.
+
+## Everyday commands
+
+Examples (the exact command grammar is documented in the CLI help and source):
+
+```text
+directory
+change directory to Projects
+create file "hello world.flux"
+write file "hello world.flux"
+read file "hello world.flux"
+copy file "hello world.flux" to "hello backup.flux"
+move "hello backup.flux" to Backups
+rename file old.txt new.txt
+search hello
+findtext "Welcome" Projects
+properties "hello world.flux"
+tree
+```
+
+Longer, natural command forms are supported where implemented. Full-word forms are preferred for readability.
+
+## FluxScript quick start
+
+```text
+let items = ["alpha", "beta"]
+
+function greet(name)
+    say "Hello, " + name
+end
+
+call greet("Researcher")
+
+loop 2
+    say items[0]
+end
+
+if 2 > 1
+    say "The expression is true"
+else
+    say "The expression is false"
+end
+```
+
+### Current language scope
+
+The implemented subset includes `say`, `ask`, `let`, `if/else/end`, `loop/end`, `while/end`, `function/end`, `call`, `return`, and `stop`, along with common literals, lists, tuples, dictionaries, indexing, arithmetic, comparisons, and boolean operations. Expression handling uses a restricted Python AST evaluator; it does not call Python `eval()` or `exec()` for FluxScript expressions.
+
+User-defined classes, asynchronous tasks, module imports (`use`), exception blocks, and general operating-system APIs are not implemented in this release. Execution limits help guard against accidental runaway scripts, but **FluxScript is not a security sandbox for hostile code**.
+
+## Aliases, settings, history, and plugins
+
+- `set NAME = VALUE` stores supported JSON-compatible settings in `Config/settings.json`.
+- `alias ll = directory` creates a persistent command alias; `unalias ll` removes one.
+- Command history is written to `Logs/history.txt`.
+- Trusted Python plugins in `Plugins/` define `register(registry)` and may register commands using `registry.add(name, handler, help_text)`.
+
+**Security note:** Python scripts and plugins execute with the permissions of the current user. Only run code you trust. Keep backups of important data. Restore operations can overwrite existing files even though archive paths are validated and links/devices are rejected.
+
+## Test and develop
+
+From the project root:
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m compileall -q src tests tools
+python tools/assayflux_preflight.py
+```
+
+The preflight helper checks for an installed `assayflux` command and uses its available version/help/doctor interfaces. It does not assume the external CLI has an Android packaging feature.
+
+## Roadmap
+
+1. Stabilise the CLI and expand automated tests.
+2. Extend FluxScript with carefully designed modules, classes, and async tasks.
+3. Build a native Android application shell with a terminal, file browser, and graphical editor.
+4. Integrate Android storage selection and manage runtime lifecycle correctly.
+5. Build and test APK/AAB artifacts on real devices before calling them production-ready.
+
+See `ANDROID_ROADMAP.md`, `android/README.md`, and `docs/FLUXSCRIPT_REFERENCE.md` for more details.
+
+## Publishing
+
+A Google Colab notebook is provided separately to run tests, build source and wheel distributions, validate metadata, and upload to PyPI using a token entered securely at runtime. Never commit or share a PyPI token. PyPI does not allow replacing an already-published file for the same project version; if `assayfluxos==0.1.0` already exists on PyPI, increment the version before publishing.
+
+## License
+
+MIT. See `LICENSE`.

assayfluxos-0.1.0/README.md

@@ -0,0 +1,170 @@
+# AssayFluxOS 0.1.0
+
+**A calm, capable command-line workspace for Python, Termux, and the emerging FluxScript language.**
+
+AssayFluxOS brings everyday file work, a persistent project workspace, familiar full-word commands, and a small expressive scripting language into one approachable environment. It is designed for people who want to organise projects and experiment with a custom scripting workflow from a Python-capable terminal—including Termux on Android—without pretending that an early CLI is already a complete mobile operating system.
+
+> **Release status:** 0.1.0 is an alpha foundation. It provides a Python command-line application and an early FluxScript interpreter. A native Android APK/AAB, graphical terminal/editor, and some advanced language features are planned separately and are **not included** in this Python package.
+
+## Highlights
+
+- **Readable commands:** prefer `copy`, `move`, `rename`, `delete`, `directory`, and `change directory` instead of requiring cryptic abbreviations.
+- **A home for your work:** creates a structured `AssayFluxOS Files` workspace with project, document, data, script, module, plugin, download, log, backup, and configuration folders.
+- **FluxScript starter language:** variables, output and input, conditions, loops, functions, return/stop, collections, indexing, arithmetic, comparisons, and boolean expressions.
+- **Persistent preferences:** settings, aliases, and command history are stored in the workspace.
+- **Useful terminal workflows:** basic pipelines, output redirection, text search, file properties, and workspace tree inspection.
+- **Extension point:** trusted Python plugins can register additional commands.
+- **Backup tools:** create and restore workspace archives with path checks and a confirmation step.
+- **Python integration:** run trusted Python scripts from the CLI when appropriate.
+- **No mandatory runtime dependencies:** the core package uses the Python standard library.
+
+## Install
+
+Python 3.10 or newer is required.
+
+```bash
+python -m pip install assayfluxos
+```
+
+Start the shell with either command:
+
+```bash
+assayfluxos
+# or the short alias
+af
+```
+
+See command-line options:
+
+```bash
+assayfluxos --help
+```
+
+### Install from a downloaded source project
+
+From the project directory:
+
+```bash
+python -m pip install .
+```
+
+## Android / Termux workspace
+
+In Termux, enable Android shared-storage access when prompted:
+
+```bash
+termux-setup-storage
+```
+
+AssayFluxOS attempts to use `/storage/emulated/0/AssayFluxOS Files` when the shared-storage parent is writable. Otherwise it falls back to `~/AssayFluxOS Files`. You can explicitly choose a workspace where supported with `--workspace PATH`.
+
+The workspace initialisation creates these folders when missing and does not intentionally erase existing content:
+
+```text
+AssayFluxOS Files/
+├── Projects/
+│   ├── Python/
+│   ├── FluxScript/
+│   ├── Web/
+│   └── Experiments/
+├── Documents/
+├── Data/
+├── Scripts/
+├── Modules/
+├── Downloads/
+├── Logs/
+├── Backups/
+├── Config/
+└── Plugins/
+```
+
+For a future native Android app, the recommended design is to use Android's Storage Access Framework for user-selected directories rather than assuming unrestricted filesystem access.
+
+## Everyday commands
+
+Examples (the exact command grammar is documented in the CLI help and source):
+
+```text
+directory
+change directory to Projects
+create file "hello world.flux"
+write file "hello world.flux"
+read file "hello world.flux"
+copy file "hello world.flux" to "hello backup.flux"
+move "hello backup.flux" to Backups
+rename file old.txt new.txt
+search hello
+findtext "Welcome" Projects
+properties "hello world.flux"
+tree
+```
+
+Longer, natural command forms are supported where implemented. Full-word forms are preferred for readability.
+
+## FluxScript quick start
+
+```text
+let items = ["alpha", "beta"]
+
+function greet(name)
+    say "Hello, " + name
+end
+
+call greet("Researcher")
+
+loop 2
+    say items[0]
+end
+
+if 2 > 1
+    say "The expression is true"
+else
+    say "The expression is false"
+end
+```
+
+### Current language scope
+
+The implemented subset includes `say`, `ask`, `let`, `if/else/end`, `loop/end`, `while/end`, `function/end`, `call`, `return`, and `stop`, along with common literals, lists, tuples, dictionaries, indexing, arithmetic, comparisons, and boolean operations. Expression handling uses a restricted Python AST evaluator; it does not call Python `eval()` or `exec()` for FluxScript expressions.
+
+User-defined classes, asynchronous tasks, module imports (`use`), exception blocks, and general operating-system APIs are not implemented in this release. Execution limits help guard against accidental runaway scripts, but **FluxScript is not a security sandbox for hostile code**.
+
+## Aliases, settings, history, and plugins
+
+- `set NAME = VALUE` stores supported JSON-compatible settings in `Config/settings.json`.
+- `alias ll = directory` creates a persistent command alias; `unalias ll` removes one.
+- Command history is written to `Logs/history.txt`.
+- Trusted Python plugins in `Plugins/` define `register(registry)` and may register commands using `registry.add(name, handler, help_text)`.
+
+**Security note:** Python scripts and plugins execute with the permissions of the current user. Only run code you trust. Keep backups of important data. Restore operations can overwrite existing files even though archive paths are validated and links/devices are rejected.
+
+## Test and develop
+
+From the project root:
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m compileall -q src tests tools
+python tools/assayflux_preflight.py
+```
+
+The preflight helper checks for an installed `assayflux` command and uses its available version/help/doctor interfaces. It does not assume the external CLI has an Android packaging feature.
+
+## Roadmap
+
+1. Stabilise the CLI and expand automated tests.
+2. Extend FluxScript with carefully designed modules, classes, and async tasks.
+3. Build a native Android application shell with a terminal, file browser, and graphical editor.
+4. Integrate Android storage selection and manage runtime lifecycle correctly.
+5. Build and test APK/AAB artifacts on real devices before calling them production-ready.
+
+See `ANDROID_ROADMAP.md`, `android/README.md`, and `docs/FLUXSCRIPT_REFERENCE.md` for more details.
+
+## Publishing
+
+A Google Colab notebook is provided separately to run tests, build source and wheel distributions, validate metadata, and upload to PyPI using a token entered securely at runtime. Never commit or share a PyPI token. PyPI does not allow replacing an already-published file for the same project version; if `assayfluxos==0.1.0` already exists on PyPI, increment the version before publishing.
+
+## License
+
+MIT. See `LICENSE`.

assayfluxos-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "assayfluxos"
+version = "0.1.0"
+description = "A thoughtfully designed Python shell and FluxScript workspace for Termux, Android-oriented workflows, and desktop Python."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AssayFluxOS contributors" }]
+keywords = ["assayfluxos", "shell", "terminal", "termux", "android", "fluxscript", "interpreter", "workspace", "developer-tools", "python"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Interpreters",
+  "Topic :: System :: Shells",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+assayfluxos = "assayfluxos.cli:main"
+af = "assayfluxos.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

assayfluxos-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

assayfluxos-0.1.0/src/assayfluxos/__init__.py

@@ -0,0 +1,2 @@
+"""AssayFluxOS: a custom Python shell and FluxScript workspace."""
+__version__ = "0.1.0"

assayfluxos-0.1.0/src/assayfluxos/cli.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+import argparse
+from .shell import AssayFluxShell
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="assayfluxos", description="AssayFluxOS custom Python shell")
+    parser.add_argument("--workspace", help="Use a specific workspace directory")
+    args = parser.parse_args()
+    shell = AssayFluxShell(workspace=args.workspace)
+    shell.loop()
+
+if __name__ == "__main__":
+    main()

assayfluxos-0.1.0/src/assayfluxos/config.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+
+class Settings:
+    """Small JSON settings store. Invalid settings are preserved and safely ignored."""
+    def __init__(self, workspace: Path):
+        self.path = workspace / "Config" / "settings.json"
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.data = {"theme": "dark", "aliases": {}, "variables": {}, "plugins_enabled": True}
+        try:
+            loaded = json.loads(self.path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                self.data.update(loaded)
+        except (OSError, ValueError):
+            pass
+        if not isinstance(self.data.get("aliases"), dict): self.data["aliases"] = {}
+        if not isinstance(self.data.get("variables"), dict): self.data["variables"] = {}
+
+    def save(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(self.data, ensure_ascii=False, indent=2), encoding="utf-8")
+        tmp.replace(self.path)

assayfluxos-0.1.0/src/assayfluxos/filesystem.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+import os
+import shutil
+from pathlib import Path
+
+MASTER_FOLDER = "AssayFluxOS Files"
+DEFAULT_FOLDERS = ("Projects/Python", "Projects/FluxScript", "Projects/Web", "Projects/Experiments", "Documents", "Data", "Scripts", "Modules", "Downloads", "Logs", "Backups", "Config", "Plugins")
+
+class Workspace:
+    """Filesystem facade confined to a workspace root, including symlink resolution."""
+    def __init__(self, root: str | Path | None = None):
+        if root is None:
+            shared = Path("/storage/emulated/0") / MASTER_FOLDER
+            home = Path.home() / MASTER_FOLDER
+            root_path = shared if shared.parent.exists() and os.access(shared.parent, os.W_OK) else home
+        else:
+            root_path = Path(root).expanduser()
+        root_path.mkdir(parents=True, exist_ok=True)
+        self.root = root_path.resolve()
+        self.cwd = self.root
+        for item in DEFAULT_FOLDERS:
+            (self.root / item).mkdir(parents=True, exist_ok=True)
+
+    def resolve(self, raw: str | Path = ".") -> Path:
+        p = Path(raw).expanduser()
+        if not p.is_absolute(): p = self.cwd / p
+        resolved = p.resolve(strict=False)
+        if resolved != self.root and self.root not in resolved.parents:
+            raise PermissionError("Path is outside the AssayFluxOS workspace.")
+        return resolved
+
+    def change(self, raw: str) -> Path:
+        target = self.resolve(raw)
+        if not target.is_dir(): raise NotADirectoryError(str(target))
+        self.cwd = target
+        return target
+
+    def list(self, raw: str = ".") -> list[Path]:
+        target = self.resolve(raw)
+        if not target.is_dir(): raise NotADirectoryError(str(target))
+        return sorted(target.iterdir(), key=lambda p: (not p.is_dir(), p.name.casefold()))
+
+    def create_file(self, raw: str) -> Path:
+        target = self.resolve(raw)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.touch(exist_ok=False)
+        return target
+
+    def make_dir(self, raw: str) -> Path:
+        target = self.resolve(raw)
+        target.mkdir(parents=True, exist_ok=False)
+        return target
+
+    def read_text(self, raw: str, encoding: str = "utf-8") -> str:
+        target = self.resolve(raw)
+        if not target.is_file(): raise IsADirectoryError(str(target))
+        if target.stat().st_size > 20_000_000: raise ValueError("File exceeds 20 MB text-read limit.")
+        return target.read_text(encoding=encoding)
+
+    def write_text(self, raw: str, content: str, encoding: str = "utf-8") -> Path:
+        target = self.resolve(raw)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding=encoding)
+        return target
+
+    def copy(self, source: str, destination: str) -> Path:
+        src, dst = self.resolve(source), self.resolve(destination)
+        if not src.exists(): raise FileNotFoundError(str(src))
+        if src == self.root: raise PermissionError("Copying the workspace root is not supported.")
+        if src.is_dir() and (dst == src or src in dst.parents):
+            raise ValueError("Cannot copy a directory into itself or one of its descendants.")
+        if dst.exists() and dst.is_dir(): dst = dst / src.name
+        if dst.exists(): raise FileExistsError(str(dst))
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if src.is_dir(): shutil.copytree(src, dst)
+        else: shutil.copy2(src, dst)
+        return dst
+
+    def move(self, source: str, destination: str) -> Path:
+        src, dst = self.resolve(source), self.resolve(destination)
+        if not src.exists(): raise FileNotFoundError(str(src))
+        if src == self.root: raise PermissionError("The workspace root cannot be moved.")
+        if src.is_dir() and (dst == src or src in dst.parents):
+            raise ValueError("Cannot move a directory into itself or one of its descendants.")
+        if dst.exists() and dst.is_dir(): dst = dst / src.name
+        if dst.exists(): raise FileExistsError(str(dst))
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        result = Path(shutil.move(str(src), str(dst)))
+        if self.cwd == src or src in self.cwd.parents: self.cwd = self.root
+        return result
+
+    def rename(self, source: str, destination: str) -> Path:
+        src, dst = self.resolve(source), self.resolve(destination)
+        if src == self.root: raise PermissionError("The workspace root cannot be renamed.")
+        if not src.exists(): raise FileNotFoundError(str(src))
+        if dst.exists(): raise FileExistsError(str(dst))
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        return src.rename(dst)
+
+    def delete(self, raw: str) -> Path:
+        target = self.resolve(raw)
+        if target == self.root: raise PermissionError("The workspace root cannot be deleted.")
+        if not target.exists(): raise FileNotFoundError(str(target))
+        if target.is_dir(): shutil.rmtree(target)
+        else: target.unlink()
+        if self.cwd == target or target in self.cwd.parents: self.cwd = self.root
+        return target
+
+    def search_names(self, needle: str) -> list[Path]:
+        key = needle.casefold()
+        found = []
+        for p in self.cwd.rglob("*"):
+            try:
+                resolved = p.resolve()
+                if (resolved == self.root or self.root in resolved.parents) and key in p.name.casefold(): found.append(p)
+            except OSError: continue
+        return found
+
+    def find_text(self, needle: str, raw: str = ".") -> list[tuple[Path, int, str]]:
+        target = self.resolve(raw)
+        candidates = [target] if target.is_file() else target.rglob("*")
+        results = []
+        for p in candidates:
+            try:
+                if not p.is_file() or p.stat().st_size > 2_000_000: continue
+                resolved = p.resolve()
+                if resolved != self.root and self.root not in resolved.parents: continue
+                for line_no, line in enumerate(p.read_text(encoding="utf-8").splitlines(), 1):
+                    if needle.casefold() in line.casefold(): results.append((p, line_no, line.strip()))
+            except (UnicodeDecodeError, OSError, PermissionError): continue
+        return results