Документация проекта AtlasOS

atlas_os/docs/07-command-set.md

@@ -0,0 +1,71 @@
+# 07 — Набор команд (Command Set)
+
+## 1. Базовые правила
+
+- Команды регистрируются в CMC через `register(name, func, desc)`.
+- Аргументы — таблица строк после парсинга `gmatch("%S+")`.
+- Вывод — через `print(text)` (цвет текущий) или `printerror(text)`.
+- Ошибки возвращаются как `error("msg")` — перехватываются `pcall`.
+
+## 2. Обязательные команды (минимум v2.0)
+
+### `ls [path]`
+
+- Выводит список имён в cwd (или `path`).
+- Без `-l` — только имена, по одному на строку.
+
+### `ls -l [path]`
+
+- Длинный формат: `type mode uid gid size mtime name`.
+- Пример: `d rwxr-xr-x 0 0 4096 1712345678 bin`
+
+### `ls -la [path]`
+
+- То же, что `-l`, плюс скрытые файлы (начинающиеся с `.`).
+
+### `cat path`
+
+- Выводит содержимое файла (распакованное).
+- При ошибке (нет прав, нет файла) — `printerror`.
+
+### `cd [path]`
+
+- Меняет cwd сессии.
+- MMC проверяет право `x` на каталоге.
+- `cd` без аргумента → `$HOME` пользователя.
+
+## 3. Выходной формат `ls -l`
+
+```
+type perms uid gid size mtime name
+f rw-r--r-- 100 10 1234 1712345678 readme.txt
+d rwxr-xr-x 0 0 0 1712345678 bin
+```
+
+## 4. Расширяемость
+
+- Новые команды добавляются регистрацией в `commands`.
+- Имя — одно слово, без пробелов.
+- Описание — краткая строка для `help`.
+- Примеры: `login`, `su`, `logout`, `echo`, `clear`, `color`, `help`, `status`.
+
+## 5. Примеры ошибок
+
+| Ситуация | Сообщение |
+|---|---|
+| Нет файла | `cat: /foo: No such file or directory` |
+| Нет прав | `ls: /secret: Permission denied` |
+| Неизвестная команда | `Error: Unknown command. Type 'help' for list.` |
+
+## 6. Совместимость с прототипом
+
+Текущий `AtlasOS.lua` уже реализует `help`, `echo`, `clear`, `color`, `status`.
+Новые команды (`ls*`, `cat`, `cd`) добавляются по той же схеме:
+
+```lua
+register_command("ls", function(args) ... end, "List directory")
+```
+
+---
+
+**Конец комплекта документации v2.0**