ultravisor 1.0.0 → 1.0.3

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,6 @@
-let libUltravisor = require(`../source/cli/Ultravisor-CLIProgram.cjs`);
+let libUltravisor = require(`../source/cli/Ultravisor-Run.cjs`);
+//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/README.md

@@ -0,0 +1,63 @@
+# Ultravisor Overview
+
+Ultravisor is a cyclic process execution tool with AI integration. It runs commands, HTTP requests and other tasks on schedule, producing structured output manifests that track timing, success/failure and logs for every execution.
+
+## What It Does
+
+Ultravisor manages two core primitives -- **Tasks** and **Operations** -- and provides multiple ways to run them: immediately via CLI or API, or on a recurring schedule via cron expressions.
+
+**Tasks** are individual units of work: shell commands, HTTP requests or other executable actions. **Operations** compose multiple tasks into a sequential pipeline with a unified output manifest.
+
+## How It Runs
+
+Ultravisor can be used in three modes:
+
+1. **CLI** -- run individual tasks or operations from the command line
+2. **API Server** -- start a Restify-based HTTP server exposing full CRUD and execution endpoints for tasks, operations, schedules and manifests
+3. **Scheduled** -- define cron schedules that automatically execute tasks or operations at the configured intervals
+
+## Configuration
+
+Ultravisor uses a layered configuration system. The default configuration ships with the module and can be overridden by a `.ultravisor.json` file in the working directory. Tasks and operations are persisted into this same configuration file.
+
+```json
+{
+    "UltravisorAPIServerPort": 54321,
+    "UltravisorFileStorePath": "/path/to/datastore",
+    "UltravisorTickIntervalMilliseconds": 60000,
+    "Tasks": {},
+    "Operations": {}
+}
+```
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| Task | A single executable unit (shell command, HTTP request, etc.) |
+| Operation | An ordered set of tasks executed sequentially |
+| Schedule | A cron-based trigger that runs a task or operation on a timer |
+| Manifest | The output record from executing an operation |
+| Hypervisor | The central scheduler that manages the schedule and dispatches executions |
+| State | Persistent storage of task and operation definitions in `.ultravisor.json` |
+
+## Module Dependencies
+
+Ultravisor is built on the Retold ecosystem:
+
+- **pict** / **pict-serviceproviderbase** -- service provider pattern and CLI framework
+- **pict-service-commandlineutility** -- CLI command registration
+- **orator** / **orator-serviceserver-restify** -- REST API server
+- **cron** -- cron expression scheduling
+
+## Documentation Map
+
+- [Architecture](architecture.md) -- service structure and data flow
+- [Quick Start](quickstart.md) -- get running in five minutes
+- [Tasks](features/tasks.md) -- task types, model and execution
+- [Operations](features/operations.md) -- composing tasks into pipelines
+- [Scheduling](features/scheduling.md) -- cron-based recurring execution
+- [API Server](features/api.md) -- REST endpoint reference
+- [CLI Commands](features/cli.md) -- command line interface reference
+- [Manifests](features/manifests.md) -- execution output and logging
+- [Configuration](features/configuration.md) -- configuration file format and options

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/_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/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 |