ultravisor 1.0.0 → 1.0.2

package/.babelrc

@@ -0,0 +1,6 @@
+{
+    "presets": [
+        "@babel/preset-env"
+    ],
+    "sourceMaps": "both"
+}

package/.browserslistrc

@@ -0,0 +1 @@
+> 0.01%

package/.browserslistrc-BACKUP

@@ -0,0 +1 @@
+since 2018

package/.gulpfile-quackage-config.json

@@ -0,0 +1,7 @@
+{
+    "EntrypointInputSourceFile": "/Users/stevenvelozo/Code/retold/modules/utility/ultravisor/source/Ultravisor.js",
+    "LibraryObjectName": "Ultravisor",
+    "LibraryOutputFolder": "/Users/stevenvelozo/Code/retold/modules/utility/ultravisor/dist/",
+    "LibraryUniminifiedFileName": "ultravisor.compatible.js",
+    "LibraryMinifiedFileName": "ultravisor.compatible.min.js"
+}

package/.gulpfile-quackage.js

@@ -0,0 +1,2 @@
+require('/Users/stevenvelozo/Code/retold/node_modules/quackage/gulp/Quackage-Gulpfile.js');
+require('/Users/stevenvelozo/Code/retold/node_modules/quackage/gulp/Quackage-Gulpfile.js');

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Retold
+
+We welcome contributions to Retold and its modules. This guide covers the expectations and process for contributing.
+
+## Code of Conduct
+
+The Retold community values **empathy**, **equity**, **kindness**, and **thoughtfulness**. We expect all participants to treat each other with respect, assume good intent, and engage constructively. These values apply to all interactions: pull requests, issues, discussions, and code review.
+
+## How to Contribute
+
+### Pull Requests
+
+Pull requests are the preferred method for contributing changes. To submit one:
+
+1. Fork the module repository you want to change
+2. Create a branch for your work
+3. Make your changes, following the code style of the module you are editing
+4. Ensure your changes have test coverage (see below)
+5. Open a pull request against the module's main branch
+
+**Submitting a pull request does not guarantee it will be accepted.** Maintainers review contributions for fit, quality, and alignment with the project's direction. A PR may be declined, or you may be asked to revise it. This is normal and not a reflection on the quality of your effort.
+
+### Reporting Issues
+
+If you find a bug or have a feature suggestion, open an issue on the relevant module's repository. Include enough detail to reproduce the problem or understand the proposal.
+
+## Test Coverage
+
+Every commit must include test coverage for the changes it introduces. Retold modules use Mocha in TDD style. Before submitting:
+
+- **Write tests** for any new functionality or bug fixes
+- **Run the existing test suite** with `npm test` and confirm all tests pass
+- **Check coverage** with `npm run coverage` if the module supports it
+
+Pull requests that break existing tests or lack coverage for new code will not be merged.
+
+## Code Style
+
+Follow the conventions of the module you are working in. The general Retold style is:
+
+- **Tabs** for indentation, never spaces
+- **Plain JavaScript** only (no TypeScript)
+- **Allman-style braces** (opening brace on its own line)
+- **Variable naming:** `pVariable` for parameters, `tmpVariable` for temporaries, `libSomething` for imports
+
+When in doubt, match what the surrounding code does.
+
+## Repository Structure
+
+Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/README.md

@@ -62,6 +62,26 @@ Tasks can be executed based on a number of scenarios:
 * After a condition is met (a condition in a browser, a disk drops below 5g)
 * After another task is completed (ffmpeg returns successfully transcoding)
 
+#### Task Model
+
+Each task has at minimum a GUID, Code and Name, as well as a type and
+parameters.  There is also a description to store markdown content about the
+task.
+
+#### Task Types
+
+Tasks have a type which dictates how they are executed:
+
+* Command - a shell command executed on the node
+* Browser - a headless browser task that can navigate, click and interact
+* Browser Read - a headless browser task that only reads data from pages
+* Browser Action - a click, navigation or data fill action for a browser
+* Request - an HTTP request task for pulling/pushing data from/to APIs
+* Store File - a task for storing files in the output file store
+* Read File - a task for reading files from the output file store
+* Database Table - a task for creating a table in the output data store
+* Integration - a meadow integration task
+
 ### Nodes
 
 Any execution of Ultravisor.  Can be distributed across multiple machines.
@@ -117,3 +137,17 @@ meant to be a persistent storage location that is accessible across nodes.
 The output data store is a flexible database for storing final output data from
 operations.  This can be used to store structured data, metadata, or any other
 information that needs to be queried or analyzed later.
+
+## Related Packages
+
+- [orator](https://github.com/stevenvelozo/orator) - API server abstraction
+- [pict](https://github.com/stevenvelozo/pict) - MVC application framework
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/debug/Harness.js

@@ -1,4 +1,5 @@
 let libUltravisor = require(`../source/cli/Ultravisor-CLIProgram.cjs`);
 
 //libUltravisor.run(['node', 'Harness.js', 'explain-config']);
-libUltravisor.run(['node', 'Harness.js', 'start']);
+
+//libUltravisor.run(['node', 'Harness.js', 'start']);

package/docs/_sidebar.md

@@ -0,0 +1,18 @@
+- Getting Started
+
+  - [Overview](overview.md)
+  - [Quick Start](quickstart.md)
+  - [Architecture](architecture.md)
+
+- Features
+
+  - [Tasks](features/tasks.md)
+  - [Operations](features/operations.md)
+  - [Scheduling](features/scheduling.md)
+  - [Manifests](features/manifests.md)
+
+- Reference
+
+  - [API Server](features/api.md)
+  - [CLI Commands](features/cli.md)
+  - [Configuration](features/configuration.md)

package/docs/_topbar.md

@@ -0,0 +1,7 @@
+# Ultravisor
+
+- [Overview](overview.md)
+- [Quick Start](quickstart.md)
+- [Tasks](features/tasks.md)
+- [Configuration](features/configuration.md)
+- [GitHub](https://github.com/stevenvelozo/ultravisor)

package/docs/architecture.md

@@ -0,0 +1,103 @@
+# Ultravisor Architecture
+
+## Service Provider Pattern
+
+Ultravisor is built on the Retold `fable-serviceproviderbase` pattern. Each
+major component is a service registered with a Fable instance via
+`addAndInstantiateServiceTypeIfNotExists`. Services access each other through
+the shared `this.fable[ServiceName]` namespace.
+
+## Service Map
+
+```
+Ultravisor-CLIProgram (Pict CLI entrypoint)
+  |
+  +-- Ultravisor-Hypervisor          Scheduler / orchestrator
+  |     |
+  |     +-- Ultravisor-Hypervisor-Event-Cron   Cron job management
+  |     +-- Ultravisor-Hypervisor-Event-Solver  Condition-based triggers (future)
+  |
+  +-- Ultravisor-Hypervisor-State    Task/operation CRUD + persistence
+  |
+  +-- Ultravisor-Task                Task execution engine
+  +-- Ultravisor-Operation           Operation execution (sequential task runner)
+  +-- Ultravisor-Operation-Manifest  Execution output tracking
+  |
+  +-- Ultravisor-API-Server          REST API (Orator + Restify)
+```
+
+## Data Flow
+
+### Immediate Execution
+
+```
+CLI Command or API Request
+  --> Hypervisor-State.getTask() or getOperation()
+  --> Task.executeTask() or Operation.executeOperation()
+  --> Operation-Manifest tracks results
+  --> Manifest returned to caller
+```
+
+### Scheduled Execution
+
+```
+Hypervisor.startSchedule()
+  --> For each schedule entry:
+      --> Event-Cron creates a CronJob
+      --> On tick: look up target from State
+      --> Execute via Task or Operation service
+      --> Results logged
+```
+
+### State Persistence
+
+```
+State.updateTask() or updateOperation()
+  --> In-memory hash updated
+  --> persistState() writes merged JSON to .ultravisor.json
+```
+
+## File Structure
+
+```
+source/
+  Ultravisor.cjs                          Module entry point
+  cli/
+    Ultravisor-CLIProgram.cjs             CLI bootstrap + service init
+    Ultravisor-Run.cjs                    Executable entry (shebang)
+    commands/
+      Ultravisor-Command-Start.cjs        Start API server
+      Ultravisor-Command-Stop.cjs         Stop scheduler
+      Ultravisor-Command-ScheduleView.cjs View schedule
+      Ultravisor-Command-ScheduleOperation.cjs  Schedule an operation
+      Ultravisor-Command-ScheduleTask.cjs       Schedule a task
+      Ultravisor-Command-UpdateTask.cjs         Add/update a task definition
+      Ultravisor-Command-SingleOperation.cjs    Run operation immediately
+      Ultravisor-Command-SingleTask.cjs         Run task immediately
+  config/
+    Ultravisor-Default-Command-Configuration.cjs  Default config values
+  services/
+    Ultravisor-Hypervisor.cjs             Scheduler + schedule management
+    Ultravisor-Hypervisor-State.cjs       CRUD + persistence
+    Ultravisor-Task.cjs                   Task execution engine
+    Ultravisor-Operation.cjs              Operation runner
+    Ultravisor-Operation-Manifest.cjs     Manifest lifecycle
+    Ultravisor-Hypervisor-Event-Base.cjs  Base event class
+    events/
+      Ultravisor-Hypervisor-Event-Cron.cjs    Cron scheduling
+      Ultravisor-Hypervisor-Event-Solver.cjs  Condition-based (future)
+  web_server/
+    Ultravisor-API-Server.cjs             REST endpoint definitions
+```
+
+## Configuration Layering
+
+Configuration is gathered automatically by Pict in this order:
+
+1. **Default Program Configuration** -- hardcoded defaults in
+   `Ultravisor-Default-Command-Configuration.cjs`
+2. **`.ultravisor.json`** -- project-level overrides (searched from cwd upward)
+
+The final merged result is available as `fable.ProgramConfiguration`. Tasks
+and operations are stored in this same file under the `Tasks` and
+`Operations` keys.

package/docs/cover.md

@@ -0,0 +1,15 @@
+# Ultravisor
+
+> Cyclic process execution with AI integration
+
+- Run shell commands and HTTP requests on a schedule
+- Compose tasks into sequential operations
+- Full REST API for remote management
+- Structured manifests track every execution
+- Cron-based scheduling with daily and hourly shortcuts
+- CLI and API for task and operation CRUD
+- Persistent state in a single JSON config file
+
+[Get Started](overview.md)
+[Quick Start](quickstart.md)
+[GitHub](https://github.com/stevenvelozo/ultravisor)

package/docs/features/api.md

@@ -0,0 +1,230 @@
+# API Server
+
+Ultravisor includes a REST API server built on Orator (Restify). Start it
+with `ultravisor start` and it exposes endpoints for managing tasks,
+operations, schedules and manifests.
+
+## Server Configuration
+
+The API server port is configured in `.ultravisor.json`:
+
+```json
+{
+    "UltravisorAPIServerPort": 54321
+}
+```
+
+Default port: `54321`. Fallback if not configured: `55555`.
+
+## Starting the Server
+
+```bash
+ultravisor start
+```
+
+Or with verbose logging:
+
+```bash
+ultravisor start --verbose
+```
+
+## Endpoint Reference
+
+### System
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/package` | Returns the package.json metadata |
+| `GET` | `/status` | Returns server and schedule status |
+| `GET` | `/stop` | Stops the scheduler and shuts down the server |
+
+#### GET /status
+
+```json
+{
+    "Status": "Running",
+    "ScheduleEntries": 3,
+    "ScheduleRunning": true
+}
+```
+
+### Tasks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/Task` | List all tasks |
+| `GET` | `/Task/:GUIDTask` | Get a single task |
+| `POST` | `/Task` | Create or update a task |
+| `PUT` | `/Task/:GUIDTask` | Update a task |
+| `DELETE` | `/Task/:GUIDTask` | Delete a task |
+| `GET` | `/Task/:GUIDTask/Execute` | Execute a task immediately |
+
+#### POST /Task
+
+```bash
+curl -X POST http://localhost:54321/Task \
+  -H "Content-Type: application/json" \
+  -d '{
+    "GUIDTask": "my-task",
+    "Name": "My Task",
+    "Type": "Command",
+    "Command": "echo hello"
+  }'
+```
+
+Response:
+
+```json
+{
+    "GUIDTask": "my-task",
+    "Name": "My Task",
+    "Type": "Command",
+    "Command": "echo hello"
+}
+```
+
+#### GET /Task/:GUIDTask/Execute
+
+```bash
+curl http://localhost:54321/Task/my-task/Execute
+```
+
+Response:
+
+```json
+{
+    "GUIDTask": "my-task",
+    "Name": "My Task",
+    "Type": "Command",
+    "StartTime": "2026-02-10T12:00:00.000Z",
+    "StopTime": "2026-02-10T12:00:00.025Z",
+    "Status": "Complete",
+    "Success": true,
+    "Output": "hello\n",
+    "Log": ["..."]
+}
+```
+
+### Operations
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/Operation` | List all operations |
+| `GET` | `/Operation/:GUIDOperation` | Get a single operation |
+| `POST` | `/Operation` | Create or update an operation |
+| `PUT` | `/Operation/:GUIDOperation` | Update an operation |
+| `DELETE` | `/Operation/:GUIDOperation` | Delete an operation |
+| `GET` | `/Operation/:GUIDOperation/Execute` | Execute an operation |
+
+#### POST /Operation
+
+```bash
+curl -X POST http://localhost:54321/Operation \
+  -H "Content-Type: application/json" \
+  -d '{
+    "GUIDOperation": "my-pipeline",
+    "Name": "My Pipeline",
+    "Tasks": ["task-a", "task-b", "task-c"]
+  }'
+```
+
+#### GET /Operation/:GUIDOperation/Execute
+
+Returns a full manifest with results for each task in the operation.
+
+### Schedule
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/Schedule` | List all schedule entries |
+| `POST` | `/Schedule/Task` | Schedule a task |
+| `POST` | `/Schedule/Operation` | Schedule an operation |
+| `DELETE` | `/Schedule/:GUID` | Remove a schedule entry |
+| `GET` | `/Schedule/Start` | Start all scheduled cron jobs |
+| `GET` | `/Schedule/Stop` | Stop all scheduled cron jobs |
+
+#### POST /Schedule/Task
+
+```bash
+curl -X POST http://localhost:54321/Schedule/Task \
+  -H "Content-Type: application/json" \
+  -d '{
+    "GUIDTask": "disk-check",
+    "ScheduleType": "cron",
+    "Parameters": "*/5 * * * *"
+  }'
+```
+
+Response:
+
+```json
+{
+    "GUID": "sched-task-disk-check-1707566400000",
+    "TargetType": "Task",
+    "TargetGUID": "disk-check",
+    "ScheduleType": "cron",
+    "Parameters": "*/5 * * * *",
+    "CronExpression": "*/5 * * * *",
+    "Active": false,
+    "CreatedAt": "2026-02-10T12:00:00.000Z"
+}
+```
+
+#### POST /Schedule/Operation
+
+```bash
+curl -X POST http://localhost:54321/Schedule/Operation \
+  -H "Content-Type: application/json" \
+  -d '{
+    "GUIDOperation": "nightly-etl",
+    "ScheduleType": "daily",
+    "Parameters": "0 2 * * *"
+  }'
+```
+
+### Manifests
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/Manifest` | List all operation run manifests |
+| `GET` | `/Manifest/:GUIDRun` | Get a specific manifest by run GUID |
+
+#### GET /Manifest
+
+Returns an array of all operation manifests from the current session.
+
+#### GET /Manifest/:GUIDRun
+
+```json
+{
+    "GUIDOperation": "my-pipeline",
+    "GUIDRun": "my-pipeline-1707566400000",
+    "Name": "My Pipeline",
+    "StartTime": "2026-02-10T12:00:00.000Z",
+    "StopTime": "2026-02-10T12:00:02.500Z",
+    "Status": "Complete",
+    "Success": true,
+    "Summary": "Operation my-pipeline Complete: 3 task(s) executed.",
+    "TaskResults": [],
+    "Log": []
+}
+```
+
+## Error Responses
+
+All error responses follow this format:
+
+```json
+{
+    "Error": "Description of what went wrong"
+}
+```
+
+HTTP status codes used:
+
+| Code | Meaning |
+|------|---------|
+| `200` | Success |
+| `400` | Bad request (invalid input) |
+| `404` | Resource not found |
+| `500` | Server error |

package/docs/features/cli.md

@@ -0,0 +1,182 @@
+# CLI Commands
+
+Ultravisor provides a command-line interface for managing tasks, operations,
+schedules, and the API server. The CLI is invoked via the `ultravisor`
+command (or `node source/cli/Ultravisor-Run.cjs`).
+
+## Command Reference
+
+### start
+
+Start the API server.
+
+```bash
+ultravisor start
+ultravisor start --verbose
+```
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Enable verbose console output |
+
+The server starts on the port configured in `.ultravisor.json`
+(`UltravisorAPIServerPort`, default `54321`).
+
+### stop
+
+Stop the Hypervisor scheduler. Deactivates all running cron jobs.
+
+```bash
+ultravisor stop
+```
+
+### updatetask
+
+Add or update a task definition. The task is persisted to
+`.ultravisor.json`.
+
+```bash
+ultravisor updatetask -g disk-check -n "Check Disk" -t Command -p "df -h"
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-g, --guid` | Task GUID | (none) |
+| `-c, --code` | Task code | (none) |
+| `-n, --name` | Task name | (none) |
+| `-t, --type` | Task type | `CRON` |
+| `-p, --parameters` | Task parameters | `0 0 * * * *` |
+| `-f, --file` | Path to JSON task definition file | (none) |
+
+When `-f` is provided, the JSON file is loaded and then any CLI parameters
+override the file values:
+
+```bash
+# Load from file, but override the GUID
+ultravisor updatetask -f ./my-task.json -g custom-guid
+```
+
+Example JSON file:
+
+```json
+{
+    "GUIDTask": "api-health",
+    "Name": "API Health Check",
+    "Type": "Request",
+    "URL": "https://api.example.com/health"
+}
+```
+
+### singletask (alias: task)
+
+Execute a single task immediately.
+
+```bash
+ultravisor singletask disk-check
+ultravisor task disk-check
+ultravisor singletask disk-check --dry_run
+```
+
+| Argument | Description |
+|----------|-------------|
+| `<task>` | The task GUID to execute |
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --operation` | Scope task to an operation | `Default` |
+| `-d, --dry_run` | Print what would happen without executing | `false` |
+
+### singleoperation (alias: operation)
+
+Execute a single operation immediately.
+
+```bash
+ultravisor singleoperation etl-pipeline
+ultravisor operation etl-pipeline
+ultravisor singleoperation etl-pipeline --dry_run
+```
+
+| Argument | Description |
+|----------|-------------|
+| `<operation>` | The operation GUID to execute |
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-d, --dry_run` | Print what would happen without executing | `false` |
+
+### schedule (alias: cal)
+
+View the current schedule.
+
+```bash
+ultravisor schedule
+ultravisor cal
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-f, --format` | Visualization format (day, week, month) | `day` |
+
+Example output:
+
+```
+=== Ultravisor Schedule (2 entries) ===
+
+  [INACTIVE] Task: disk-check
+           Schedule: cron (*/5 * * * *)
+           GUID: sched-task-disk-check-1707566400000
+
+  [INACTIVE] Operation: etl-pipeline
+           Schedule: daily (0 2 * * *)
+           GUID: sched-op-etl-pipeline-1707566400001
+```
+
+### schedule_task (alias: st)
+
+Add a task to the schedule.
+
+```bash
+ultravisor schedule_task disk-check -t cron -p "*/5 * * * *"
+ultravisor st disk-check -t hourly
+```
+
+| Argument | Description |
+|----------|-------------|
+| `<task_guid>` | The task GUID to schedule |
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --type` | Schedule type (cron, daily, hourly, solver) | `cron` |
+| `-p, --parameters` | Cron expression or schedule parameters | (empty) |
+
+### schedule_operation (alias: so)
+
+Add an operation to the schedule.
+
+```bash
+ultravisor schedule_operation etl-pipeline -t daily -p "0 2 * * *"
+ultravisor so etl-pipeline -t cron -p "0 6 * * 1-5"
+```
+
+| Argument | Description |
+|----------|-------------|
+| `<operation_guid>` | The operation GUID to schedule |
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --type` | Schedule type (cron, daily, hourly, solver) | `cron` |
+| `-p, --parameters` | Cron expression or schedule parameters | (empty) |
+
+### configuration
+
+Auto-generated command that explains how Ultravisor resolved its
+configuration (which files were loaded, what values came from where).
+
+```bash
+ultravisor configuration
+```
+
+## Exit Codes
+
+- `0` -- command completed successfully
+- Non-zero -- an error occurred during execution