aias 0.1.0

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+# SimpleCov must be required and started BEFORE minitest/autorun registers its
+# at_exit hook. Ruby runs at_exit handlers in LIFO order, so whichever gem
+# calls at_exit last will run first. We want:
+#   1. Minitest at_exit → tests execute
+#   2. SimpleCov at_exit → results collected after tests finish
+#
+# Achieving this requires SimpleCov to register its at_exit first (i.e. load
+# before minitest/autorun). The test_prelude is prepended to the -e string
+# before 'require "minitest/autorun"', giving us the correct ordering.
+SIMPLECOV_PRELUDE = <<~RUBY.tr("\n", ";")
+  require "simplecov"
+  SimpleCov.start do
+    add_filter "/test/"
+    enable_coverage :branch
+  end
+RUBY
+
+Minitest::TestTask.create do |t|
+  t.test_prelude = "#{SIMPLECOV_PRELUDE} require \"minitest/autorun\"; "
+end
+
+task default: :test

data/aia_schedule_idea.md

@@ -0,0 +1,256 @@
+# aias Gem — Analysis & Requirements
+
+## Origin
+
+Inspired by reviewing the `ai_sentinel` gem (https://github.com/mcelicalderon/ai_sentinel),
+a lightweight Ruby gem for scheduling AI-driven automation tasks via YAML-defined workflows
+and Rufus-scheduler.
+
+---
+
+## Core Concept
+
+`aias` is a standalone gem that runs AIA prompts as scheduled batch jobs. Schedule
+information lives directly in the YAML frontmatter of individual AIA prompt files —
+no separate configuration file is needed. The gem scans the prompts directory, discovers
+all prompts that declare a `schedule:` key, and installs them as crontab entries via the
+`whenever` gem.
+
+The prompts are self-describing — a prompt that wants to run on a schedule says so in
+its own frontmatter.
+
+---
+
+## Gem Identity
+
+| Property | Value |
+|---|---|
+| Gem name | `aias` |
+| Binary | `aias` |
+| Ruby module | `Aias::` |
+| Version | Tracks `aia` version exactly (reads from the same `.version` file) |
+| Author / license | Same as `aia` — madbomber's RubyGems account, MIT license |
+| Distribution | Standalone gem, released independently from `aia` |
+| Entry point | Separate `aias` binary — not an `aia` subcommand |
+
+---
+
+## Scheduling Backend: `whenever`
+
+`whenever` was chosen over `rufus-scheduler` because:
+
+- AIA is already a CLI tool — scheduled jobs are simply `aia <prompt_id>` invocations
+- No long-running daemon to manage; the OS cron daemon handles reliability and reboots
+- Each job runs as a fresh, clean `aia` process — no shared state between runs
+- Crontab entries are visible and auditable with standard Unix tools (`crontab -l`)
+
+`whenever` is normally driven by a hand-written `config/schedule.rb`. `aias` eliminates
+that file entirely — it auto-generates the equivalent by scanning prompt frontmatter,
+then hands the result to `whenever` to install into the user's crontab.
+
+`whenever` is a **hard dependency** — its marker-block management and cron DSL are not
+worth reimplementing.
+
+---
+
+## The `schedule:` Frontmatter Key
+
+A single string value. No hash form. No additional fields.
+
+```yaml
+# Raw cron expression
+schedule: "0 8 * * *"
+
+# whenever human-readable DSL — both forms accepted
+schedule: "every 1.day at 8:00am"
+schedule: "every :monday at 9:00am"
+schedule: "every 6.hours"
+```
+
+Everything else is derived — there is nothing else to configure at the prompt level:
+
+| Concern | Behaviour |
+|---|---|
+| Enabled / disabled | Presence of `schedule:` means enabled. Remove the line to disable. |
+| Log file | Composed from prompt ID: `~/.aia/schedule/logs/<prompt_id>.log` |
+| Append vs overwrite | Always append (`>>`). Log entries accumulate across runs. |
+| stdout + stderr | Always combined (`2>&1`). No separate error log. |
+| AIA flags / model / role | AIA reads these from the prompt's own frontmatter. `aias` passes only the prompt ID. |
+
+### Example scheduled prompt
+
+```yaml
+---
+name: daily_digest
+description: Summarizes overnight news and activity
+schedule: "every 1.day at 8:00am"
+---
+Summarize what happened overnight in the Ruby and AI ecosystems.
+```
+
+### Non-scheduled prompt (unchanged, ignored by aias)
+
+```yaml
+---
+name: ad_hoc
+description: An Ad Hoc prompt for on the fly consultations
+parameters:
+  what_now_human: "I'm going to give you my resume and then we are going to talk about it."
+---
+<%= what_now_human %>
+```
+
+---
+
+## How It Works
+
+### Prompt Discovery
+
+`aias` uses `grep -rl "schedule:" $AIA_PROMPTS_DIR` to find candidate files. This is
+recursive, filename-only output, POSIX-standard, and reads only files that actually
+contain the word `schedule:` — avoiding loading every prompt in the directory.
+
+The full subpath relative to `$AIA_PROMPTS_DIR` is the prompt ID:
+
+```
+~/.prompts/reports/weekly_digest.md  →  aia reports/weekly_digest
+~/.prompts/daily_digest.md           →  aia daily_digest
+```
+
+### Primary Operation: `aias update`
+
+1. Run `grep -rl "schedule:" $AIA_PROMPTS_DIR` to find candidates
+2. Parse frontmatter of each candidate via `PM::Metadata`
+3. Validate each scheduled prompt (see Validation below)
+4. For valid prompts, build an `aia <prompt_id>` invocation string
+5. Generate a complete `whenever`-managed crontab block
+6. Install, replacing the previous `aias`-managed block entirely
+
+This is a **full sync on every run**. Orphaned entries (from deleted or de-scheduled
+prompts) are automatically removed because the entire block is replaced.
+
+### The Cron Environment
+
+Cron runs in a minimal shell with no PATH, no rbenv/rvm activation, and no user
+environment variables. `aias` solves this by wrapping every cron entry in a login
+shell invocation, detected from `ENV['SHELL']` at `update` time.
+
+`whenever` supports this natively via `job_template`:
+
+```ruby
+set :job_template, "zsh -l -c ':job'"   # or bash -l -c, fish -l -c, etc.
+```
+
+The login shell sources the user's profile, providing rbenv, PATH, and all AIA
+environment variables automatically. No PATH capture or manual config step required.
+
+### Example Generated Crontab Entry
+
+```
+# aias -- reports/daily_digest
+0 8 * * *  /bin/zsh -l -c 'aia reports/daily_digest >> ~/.aia/schedule/logs/reports/daily_digest.log 2>&1'
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `aias update` | Full sync: scan prompts, regenerate all crontab entries, install. Primary command. |
+| `aias clear` | Remove all `aias`-managed entries from crontab. Non-AIA entries untouched. |
+| `aias list` | Report all `aias` jobs currently in the crontab: prompt ID, schedule, log file. |
+| `aias check` | Diff view: prompts with `schedule:` vs what is installed. Surfaces uninstalled, orphaned, and invalid prompts. |
+| `aias dry-run` | Show what `update` would write without touching the crontab. |
+| `aias next [N]` | Show next N scheduled run times for all installed jobs (default N=5). |
+| `aias show <prompt_id>` | Show the installed crontab entry for a single prompt. |
+
+---
+
+## Architecture
+
+```
+aias gem
+├── Aias::CLI             (Thor: update, clear, list, check, dry-run, next, show)
+├── Aias::PromptScanner   (grep -rl discovery + PM::Metadata frontmatter parsing)
+├── Aias::JobBuilder      (prompt ID + schedule string → whenever job definition)
+├── Aias::CrontabManager  (wraps whenever; installs/clears/reads managed crontab block)
+└── Aias::Validator       (cron expression syntax, parameter defaults, aia binary presence)
+```
+
+---
+
+## Validation
+
+Before writing to crontab, `aias` validates each scheduled prompt:
+
+1. **Schedule syntax** — cron expression or whenever DSL string is parseable
+2. **Parameter completeness** — all `parameters:` keys must have default values;
+   interactive input is impossible in a cron context
+3. **AIA binary** — `aia` must be locatable (checked via `which aia` inside the login shell)
+4. **Prompts directory** — `$AIA_PROMPTS_DIR` must exist and be readable
+
+On validation failure during `update`: the invalid prompt is warned loudly, excluded
+from the install, and any existing crontab entry for it is removed.
+
+Validation also runs standalone via `aias check`.
+
+---
+
+## Output and Logging
+
+- Log directory: `~/.aia/schedule/logs/` — created on first `update` if absent
+- Log file per prompt: `~/.aia/schedule/logs/<prompt_id>.log`
+  (subdirectory structure mirrors the prompt subpath, e.g. `logs/reports/daily_digest.log`)
+- stdout and stderr always combined (`2>&1`)
+- Always append — logs accumulate across runs
+
+---
+
+## Key Dependencies
+
+```ruby
+spec.add_dependency "aia"            # no version constraint
+spec.add_dependency "prompt_manager" # already used by aia
+spec.add_dependency "whenever"       # crontab generation and management
+spec.add_dependency "thor"           # CLI framework
+spec.add_dependency "zeitwerk"       # autoloading
+```
+
+`sequel`, `sqlite3`, and `rufus-scheduler` are not required.
+
+---
+
+## Deferred Decisions
+
+| Topic | Notes |
+|---|---|
+| `timeout:` support | Would require wrapping cron entry with Unix `timeout` command. Deferred to post-v1. |
+
+---
+
+## All Resolved Decisions
+
+| Decision | Outcome |
+|---|---|
+| Scheduling backend | `whenever` — no daemon, OS cron handles reliability |
+| Invocation method | Shell out to `aia` binary — fresh process, clean state per job |
+| Separate config file | None — schedule data lives entirely in prompt frontmatter |
+| `schedule:` format | Single string only — cron expression or whenever DSL |
+| Enabled/disabled | Presence of `schedule:` key means enabled; remove line to disable |
+| AIA flags in schedule block | Not needed — AIA reads its own frontmatter; `aias` passes only the prompt ID |
+| Append vs overwrite | Always append |
+| stdout/stderr | Always combined |
+| Log location | Config-anchored: `~/.aia/schedule/logs/<prompt_id>.log` |
+| Prompt discovery | `grep -rl "schedule:" $AIA_PROMPTS_DIR` — POSIX, no extra tools |
+| Prompt ID format | Full subpath relative to prompts dir (e.g. `reports/weekly_digest`) |
+| Cron environment | Login shell wrapping via `whenever`'s `job_template`, detected from `ENV['SHELL']` |
+| Validation failure | Warn loudly, skip invalid prompt, remove any existing crontab entry for it |
+| Parameters in scheduled prompts | All `parameters:` must have defaults in frontmatter |
+| Gem name / binary | `aias` / `aias` |
+| Gem boundary | Standalone gem, distributed separately from `aia` |
+| Version tracking | Matches `aia` version; reads shared `.version` file |
+| Ownership | madbomber RubyGems account, MIT license, same author as `aia` |
+| `aia` dependency constraint | No version pin — user is responsible for compatibility |
+| `whenever` coupling | Hard dependency |
+| Execution history DB | Out of scope — cron logs to files |

data/docs/cli/add.md

@@ -0,0 +1,101 @@
+# aias add
+
+Add or replace a single prompt's cron job without touching any other installed jobs.
+
+```bash
+aias add PATH
+```
+
+`PATH` is the path to the prompt file — absolute or relative. The file must live inside the configured prompts directory.
+
+## What It Does
+
+1. Expands `PATH` to an absolute path
+2. Verifies the file exists and is inside the prompts directory
+3. Parses the file's YAML frontmatter via `PM::Metadata`
+4. Errors immediately if the file has no `schedule:` key
+5. Runs the same validation as `update` (schedule syntax, parameter defaults, `aia` binary)
+6. Derives the prompt ID from the file's path relative to the prompts directory
+7. Upserts the single cron entry into the aias-managed crontab block — if the prompt was already installed, its old entry is replaced; all other entries are left untouched
+
+## When to Use `add` vs `update`
+
+| Situation | Command |
+|---|---|
+| You edited or created one prompt and want it scheduled now | `aias add PATH` |
+| You edited multiple prompts, or want to sync everything | `aias update` |
+| You want to see what would change first | `aias dry-run` or `aias check` |
+
+`add` is faster than `update` for large prompts directories because it does not scan the entire tree — it only reads the one file you specify.
+
+## Example Output
+
+**Success:**
+
+```
+aias: added standup (every weekday at 9:00am (0 9 * * 1-5))
+```
+
+**Prompt has no schedule:**
+
+```
+aias [error] 'drafts/idea' has no schedule: in its frontmatter
+```
+
+**Invalid schedule:**
+
+```
+aias [error] bad_prompt: Schedule 'every banana': not a valid cron expression or natural language schedule
+```
+
+**File outside prompts directory:**
+
+```
+aias [error] '/tmp/idea.md' is not inside the prompts directory '/Users/you/.prompts'
+```
+
+## Upsert Semantics
+
+Re-running `add` on the same prompt replaces its cron entry cleanly — no duplicates are created. This makes `add` safe to run any number of times:
+
+```bash
+# Install:
+aias add ~/.prompts/standup.md
+# aias: added standup (every weekday at 9:00am (0 9 * * 1-5))
+
+# Update the schedule in the file, then re-install:
+aias add ~/.prompts/standup.md
+# aias: added standup (every weekday at 10:00am (0 10 * * 1-5))
+```
+
+## Prompt ID Derivation
+
+The prompt ID is derived the same way as `update`: the file's absolute path with the prompts directory prefix and `.md` extension removed.
+
+```
+prompts_dir:  /Users/you/.prompts
+file:         /Users/you/.prompts/reports/weekly.md
+prompt_id:    reports/weekly
+```
+
+## Options
+
+| Option | Alias | Description |
+|---|---|---|
+| `--prompts-dir PATH` | `-p` | Use PATH as the prompts directory (also determines the prompt ID prefix) |
+
+When `--prompts-dir` is not supplied, the prompts directory is read from `AIA_PROMPTS__DIR` or `AIA_PROMPTS_DIR`. The same value is embedded in the generated `aia` command so the cron job runs against the correct directory.
+
+## Exit Codes
+
+| Code | Condition |
+|---|---|
+| `0` | Job installed successfully |
+| `1` | File not found, outside prompts dir, no `schedule:`, validation failure, or crontab write error |
+
+## See Also
+
+- [`aias update`](update.md) — sync all scheduled prompts at once
+- [`aias check`](check.md) — diff view before making changes
+- [`aias list`](list.md) — confirm the job was installed
+- [Scheduling Prompts](../guides/scheduling-prompts.md) — schedule format reference

data/docs/cli/check.md

@@ -0,0 +1,70 @@
+# aias check
+
+Diff view: compare prompts that declare `schedule:` against what is currently installed in the crontab.
+
+```bash
+aias check
+```
+
+## What It Shows
+
+`check` categorises every prompt and every installed job into one of four states:
+
+| Label | Meaning |
+|---|---|
+| `OK` | Crontab is in sync — nothing to report |
+| `NEW` | Prompt has `schedule:` but is not yet installed — run `update` |
+| `ORPHANED` | Installed in crontab but no corresponding prompt found — run `update` to remove |
+| `INVALID` | Prompt has `schedule:` but failed validation — shown with error details |
+
+## Example Output
+
+**In sync:**
+
+```
+=== aias check ===
+
+OK — crontab is in sync with scheduled prompts
+```
+
+**Changes needed:**
+
+```
+=== aias check ===
+
+INVALID (would be skipped by update):
+  bad_prompt: Schedule 'every banana': undefined method 'banana' for ...
+
+NEW (not yet installed — run `aias update`):
+  + reports/weekly
+
+ORPHANED (installed but no longer scheduled):
+  - old_daily_job
+```
+
+## Typical Workflow
+
+Run `check` after editing prompt files to see what `update` would change before actually running it:
+
+```bash
+# Edit a prompt's schedule:
+vim $AIA_PROMPTS_DIR/daily_digest.md
+
+# Preview the impact:
+aias check
+
+# Apply:
+aias update
+```
+
+## Options
+
+| Option | Alias | Description |
+|---|---|---|
+| `--prompts-dir PATH` | `-p` | Use PATH instead of `AIA_PROMPTS__DIR` / `AIA_PROMPTS_DIR` |
+
+## See Also
+
+- [`aias update`](update.md) — apply the changes shown by `check`
+- [`aias dry-run`](dry-run.md) — preview the generated cron lines
+- [`aias list`](list.md) — see all currently installed jobs

data/docs/cli/clear.md

@@ -0,0 +1,45 @@
+# aias clear
+
+Remove all aias-managed crontab entries.
+
+```bash
+aias clear
+```
+
+## What It Does
+
+Calls `whenever --clear` for the `aias` identifier, removing the entire `aias`-managed block from the crontab. All other crontab entries (your own manually added jobs or other `whenever`-managed blocks) are left untouched.
+
+## Output
+
+```
+aias: all managed crontab entries removed
+```
+
+## Use Cases
+
+**Temporarily disable all scheduled prompts** without editing any prompt files:
+
+```bash
+aias clear
+# Re-enable later:
+aias update
+```
+
+**Reset before a clean reinstall:**
+
+```bash
+aias clear
+aias update
+```
+
+## Notes
+
+`clear` does not validate prompts or read `$AIA_PROMPTS_DIR`. It simply removes whatever `aias` block is currently in the crontab.
+
+After `clear`, `aias list` returns "no installed jobs" and `aias check` shows all scheduled prompts as `NEW`.
+
+## See Also
+
+- [`aias update`](update.md) — reinstall after clearing
+- [`aias list`](list.md) — verify the crontab is empty after clearing

data/docs/cli/dry-run.md

@@ -0,0 +1,57 @@
+# aias dry-run
+
+Show what `aias update` would write to the crontab without making any changes.
+
+```bash
+aias dry-run
+```
+
+## Output
+
+The raw cron lines that would be installed, exactly as they would appear in the crontab:
+
+```
+0 8 * * * /bin/zsh -l -c 'aia daily_digest >> /Users/you/.aia/schedule/logs/daily_digest.log 2>&1'
+0 9 * * 1 /bin/zsh -l -c 'aia reports/weekly >> /Users/you/.aia/schedule/logs/reports/weekly.log 2>&1'
+```
+
+Invalid prompts are printed to stderr (same as `update`):
+
+```
+aias [skip] bad_prompt: Schedule 'every banana': ...
+```
+
+When no valid prompts are found:
+
+```
+aias: no valid scheduled prompts found
+```
+
+## Use Cases
+
+**Verify the generated cron expression** before committing it to your crontab:
+
+```bash
+aias dry-run
+# Inspect the output, then:
+aias update
+```
+
+**Check login shell wrapping** — confirm the correct shell binary and `-l` flag appear in the output.
+
+**Audit from CI** — `dry-run` is safe to run in automated pipelines because it never modifies the crontab.
+
+## Notes
+
+`dry-run` runs the full scan and validation pipeline. The only thing it skips is the final crontab write. This means it accurately reflects what `update` would do, including which prompts would be skipped.
+
+## Options
+
+| Option | Alias | Description |
+|---|---|---|
+| `--prompts-dir PATH` | `-p` | Use PATH instead of `AIA_PROMPTS__DIR` / `AIA_PROMPTS_DIR` |
+
+## See Also
+
+- [`aias update`](update.md) — apply the output shown by `dry-run`
+- [`aias check`](check.md) — higher-level diff view

data/docs/cli/index.md

@@ -0,0 +1,51 @@
+# CLI Reference
+
+`aias` provides nine commands. All are available via `aias help` at the terminal.
+
+```
+aias help
+```
+
+## Command Summary
+
+| Command | Purpose |
+|---|---|
+| [`aias install [PATTERN...]`](install.md) | Capture PATH, API keys, and env vars into `env.sh`. Run once before scheduling any prompts. |
+| [`aias update`](update.md) | Scan prompts, validate, install all scheduled jobs. Primary command. |
+| [`aias add PATH`](add.md) | Add or replace a single prompt's cron job without touching others. |
+| [`aias remove PROMPT_ID`](remove.md) | Remove a single prompt's cron job. Aliases: `rm`, `delete`. |
+| [`aias check`](check.md) | Diff view: what is scheduled vs what is installed. |
+| [`aias list`](list.md) | Print all currently installed jobs. |
+| [`aias dry-run`](dry-run.md) | Preview `update` output without writing the crontab. |
+| [`aias show PROMPT_ID`](show.md) | Inspect a single installed job. |
+| [`aias next [N]`](next.md) | Show next scheduled run time for installed jobs. |
+| [`aias last [N]`](last.md) | Show last-run time for installed jobs. |
+| [`aias clear`](clear.md) | Remove all aias-managed crontab entries. |
+| [`aias uninstall`](uninstall.md) | Remove the managed env block from `env.sh`. |
+
+## Global Option
+
+`--prompts-dir PATH` (alias `-p`) overrides the `AIA_PROMPTS__DIR` / `AIA_PROMPTS_DIR` environment variables for any command that reads prompt files. It has no effect on commands that only read from the crontab (`list`, `show`, `next`, `last`, `clear`).
+
+```bash
+aias --prompts-dir ~/work/prompts update
+aias --prompts-dir ~/work/prompts add ~/work/prompts/standup.md
+aias -p ~/work/prompts dry-run
+aias -p ~/work/prompts check
+```
+
+The lookup order for the prompts directory is:
+
+1. `--prompts-dir` CLI option (highest priority)
+2. `AIA_PROMPTS__DIR` environment variable (AIA >= 0.8.0)
+3. `AIA_PROMPTS_DIR` environment variable (AIA < 0.8.0)
+4. Error — neither option nor env var is set
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Error (bad prompts directory, crontab write failure, prompt not found) |
+
+Validation failures during `update` do **not** cause a non-zero exit — invalid prompts are warned and skipped while valid ones are installed.