aias 0.1.0

data/docs/reference/api.md

@@ -0,0 +1,409 @@
+# API Reference
+
+All public classes live under the `Aias::` namespace and are autoloaded by Zeitwerk when `require "aias"` is called.
+
+---
+
+## `Aias::CLI`
+
+**Inherits:** `Thor`
+
+The command-line interface. All eight commands are public instance methods. `CLI.start(ARGV)` is the gem entry point called by the `aias` binary.
+
+### Class Methods
+
+#### `.exit_on_failure?`
+
+Returns `true`. Thor uses this to call `exit(1)` when a command raises an unhandled error.
+
+### Instance Methods
+
+#### `#update`
+
+Scan, validate, and install all scheduled prompts.
+
+```ruby
+cli = Aias::CLI.new
+cli.update
+```
+
+#### `#add(path)`
+
+Add or replace a single prompt's cron job. `path` is an absolute or relative path to the prompt file.
+
+```ruby
+cli.add("/Users/you/.prompts/standup.md")
+cli.add("./example_prompts/morning_standup.md")
+```
+
+Raises `SystemExit(1)` when the file is missing, outside the prompts directory, has no `schedule:` key, or fails validation.
+
+See [`aias add`](../cli/add.md) for full behaviour and upsert semantics.
+
+#### `#check`
+
+Print a diff between scheduled prompts and installed jobs.
+
+```ruby
+cli.check
+```
+
+#### `#list`
+
+Print a table of all installed jobs.
+
+```ruby
+cli.list
+```
+
+#### `#dry_run`
+
+Print the cron output that `update` would write, without touching the crontab.
+
+```ruby
+cli.dry_run
+```
+
+#### `#show(prompt_id)`
+
+Print details for a single installed job. Exits 1 if not found.
+
+```ruby
+cli.show("daily_digest")
+cli.show("reports/weekly")
+```
+
+#### `#upcoming(n = "5")`
+
+Print the next scheduled run time for installed jobs, computed via `fugit`. Aliased as `aias next` on the command line.
+
+```ruby
+cli.upcoming
+cli.upcoming("10")
+```
+
+#### `#last_run(n = "5")`
+
+Print the last-run time for installed jobs, derived from the log file modification timestamp. Aliased as `aias last` on the command line.
+
+```ruby
+cli.last_run
+cli.last_run("10")
+```
+
+#### `#clear`
+
+Remove all aias-managed crontab entries.
+
+```ruby
+cli.clear
+```
+
+### Dependency Injection
+
+Collaborators are initialized lazily via private accessors. Set instance variables before invoking a command to inject alternatives:
+
+```ruby
+cli = Aias::CLI.new
+cli.instance_variable_set(:@validator, Aias::Validator.new(binary_to_check: "ruby"))
+cli.instance_variable_set(:@scanner,  Aias::PromptScanner.new(prompts_dir: "/tmp/test"))
+cli.update
+```
+
+---
+
+## `Aias::PromptScanner`
+
+Discovers AIA prompt files that declare a `schedule:` key and parses their frontmatter.
+
+### `::Result`
+
+```ruby
+Aias::PromptScanner::Result = Data.define(:prompt_id, :schedule, :metadata, :file_path)
+```
+
+A frozen, immutable value object. Fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `prompt_id` | `String` | Subpath relative to prompts dir, no `.md` extension |
+| `schedule` | `String` | Raw value of the `schedule:` frontmatter key |
+| `metadata` | `PM::Metadata` | Full parsed frontmatter object |
+| `file_path` | `String` | Absolute path to the prompt file |
+
+### `.new`
+
+```ruby
+scanner = Aias::PromptScanner.new
+scanner = Aias::PromptScanner.new(prompts_dir: "/path/to/prompts")
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `prompts_dir:` | `ENV["AIA_PROMPTS_DIR"]` | Directory to scan |
+
+### `#scan`
+
+```ruby
+results = scanner.scan  # => Array<Aias::PromptScanner::Result>
+```
+
+Returns an array of `Result` objects for every prompt that has a non-empty `schedule:` key.
+
+**Raises** `Aias::Error` when:
+
+- `prompts_dir` is nil or empty (AIA_PROMPTS_DIR not set)
+- The directory does not exist
+- The directory is not readable
+
+Prompts with unparseable frontmatter are warned to stderr and skipped (no exception).
+
+### `#scan_one`
+
+```ruby
+result = scanner.scan_one(path)  # => Aias::PromptScanner::Result
+```
+
+Parses a single prompt file by path (absolute or relative). Returns a `Result` on success.
+
+**Raises** `Aias::Error` when:
+
+| Condition | Message |
+|---|---|
+| File does not exist | `"Prompt file not found: <path>"` |
+| File is not readable | `"Prompt file not readable: <path>"` |
+| File is outside `prompts_dir` | `"'<path>' is not inside the prompts directory '<dir>'"` |
+| No `schedule:` in frontmatter | `"'<prompt_id>' has no schedule: in its frontmatter"` |
+| Frontmatter is unparseable | `"Failed to parse '<prompt_id>': <original error>"` |
+| `prompts_dir` missing or unreadable | Same as `#scan` |
+
+Unlike `#scan`, `scan_one` never silently skips — every error condition is a raised exception.
+
+---
+
+## `Aias::Validator`
+
+Validates a `PromptScanner::Result` against three rules: schedule syntax, parameter completeness, and `aia` binary presence.
+
+### `::ValidationResult`
+
+```ruby
+Aias::Validator::ValidationResult = Data.define(:valid?, :errors)
+```
+
+A frozen, immutable value object. Fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `valid?` | `Boolean` | `true` when all checks pass |
+| `errors` | `Array<String>` | Human-readable error messages (empty when valid) |
+
+### `.new`
+
+```ruby
+validator = Aias::Validator.new
+validator = Aias::Validator.new(
+  shell:         "/bin/bash",
+  binary_to_check: "aia",
+  fallback_dirs: Aias::Validator::BINARY_FALLBACK_DIRS
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `shell:` | `ENV["SHELL"]` or `"/bin/bash"` | Login shell used for binary check |
+| `binary_to_check:` | `"aia"` | Binary name to locate |
+| `fallback_dirs:` | `BINARY_FALLBACK_DIRS` | Directories scanned when the login-shell check fails |
+
+`binary_to_check:` and `fallback_dirs:` are primarily useful in tests — pass `"ruby"` for a check that always succeeds, or an empty/nonexistent directory list for one that always fails.
+
+### `::BINARY_FALLBACK_DIRS`
+
+```ruby
+Aias::Validator::BINARY_FALLBACK_DIRS
+# => [
+#      "~/.rbenv/shims",
+#      "~/.rbenv/bin",
+#      "~/.rvm/bin",
+#      "~/.asdf/shims",
+#      "/usr/local/bin",
+#      "/usr/bin",
+#      "/opt/homebrew/bin"
+#    ]
+```
+
+The default fallback directory list. Covers rbenv, rvm, asdf, Homebrew (Intel + Apple Silicon), and the standard system paths.
+
+### `#validate`
+
+```ruby
+vr = validator.validate(scanner_result)  # => Aias::Validator::ValidationResult
+vr.valid?   # => true or false
+vr.errors   # => ["Schedule 'x': ...", "Parameter 'y' has no default ..."]
+```
+
+The binary check result is memoised per `Validator` instance and only runs once.
+
+### `#binary_in_fallback_location?`
+
+```ruby
+validator.binary_in_fallback_location?  # => true or false
+```
+
+Returns `true` when an executable file named `binary_to_check` exists in any of the `fallback_dirs`. Called automatically by `#validate`; exposed publicly for diagnostics.
+
+---
+
+## `Aias::JobBuilder`
+
+Converts a `PromptScanner::Result` into a raw cron line string. Pure function — no I/O.
+
+### `.new`
+
+```ruby
+builder = Aias::JobBuilder.new
+builder = Aias::JobBuilder.new(shell: "/bin/zsh")
+builder = Aias::JobBuilder.new(shell: "/bin/zsh", prompts_dir: "/path/to/prompts")
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `shell:` | `ENV["SHELL"]` or `"/bin/bash"` | Login shell binary used to wrap the `aia` invocation |
+| `prompts_dir:` | `nil` | When set, appends `--prompts-dir DIR` to every generated `aia` command |
+
+### `#build`
+
+```ruby
+cron_line = builder.build(scanner_result)  # => String
+```
+
+Returns a fully-formed cron line string suitable for passing to `CrontabManager#install` or `#add_job`. Uses `fugit` to resolve the `schedule:` value to a canonical 5-field cron expression.
+
+**Without `prompts_dir`:**
+
+```
+0 8 * * * /bin/zsh -l -c 'aia daily_digest >> /Users/you/.aia/schedule/logs/daily_digest.log 2>&1'
+```
+
+**With `prompts_dir: "/data/prompts"`:**
+
+```
+0 8 * * * /bin/zsh -l -c 'aia --prompts-dir /data/prompts daily_digest >> /Users/you/.aia/schedule/logs/daily_digest.log 2>&1'
+```
+
+### `#log_path_for`
+
+```ruby
+builder.log_path_for("daily_digest")     # => "/Users/you/.aia/schedule/logs/daily_digest.log"
+builder.log_path_for("reports/weekly")   # => "/Users/you/.aia/schedule/logs/reports/weekly.log"
+```
+
+Returns the absolute log path for a given prompt ID.
+
+---
+
+## `Aias::CrontabManager`
+
+Manages the aias-owned block in the user's crontab by directly invoking the system `crontab(1)` command via `Open3`.
+
+### Constants
+
+| Constant | Value | Description |
+|---|---|---|
+| `IDENTIFIER` | `"aias"` | Whenever identifier that marks the managed block |
+| `LOG_BASE` | `~/.aia/schedule/logs` | Default base directory for log files |
+| `ENTRY_RE` | Regexp | Parses installed cron lines to extract `prompt_id`, `cron_expr`, `log_path` |
+
+### `.new`
+
+```ruby
+manager = Aias::CrontabManager.new
+manager = Aias::CrontabManager.new(crontab_command: "crontab", log_base: "/custom/log/base")
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `crontab_command:` | `"crontab"` | Path to the `crontab(1)` binary |
+| `log_base:` | `LOG_BASE` | Base directory for log files |
+
+The `crontab_command:` parameter makes the manager testable with a fake crontab script backed by a tmpfile, with no system crontab involvement.
+
+### `#install`
+
+```ruby
+manager.install(cron_lines)
+```
+
+Accepts a single cron line string or an array of cron line strings. Creates `@log_base` if absent, then replaces the entire `aias`-managed crontab block by piping the new content to `crontab -` via `Open3`.
+
+**Raises** `Aias::Error` if the `crontab` command exits non-zero.
+
+### `#add_job`
+
+```ruby
+manager.add_job(cron_line, prompt_id)
+```
+
+Upserts a single cron entry into the aias-managed block. Any existing entry whose `prompt_id` matches is removed first; the new `cron_line` is appended. All other managed entries are left unchanged. Non-aias crontab entries are never touched.
+
+`cron_line` is a fully-formed cron line as produced by `JobBuilder#build`:
+
+```
+0 9 * * 1-5 /bin/zsh -l -c 'aia standup >> ~/.aia/schedule/logs/standup.log 2>&1'
+```
+
+Creates `@log_base` if absent. **Raises** `Aias::Error` if the crontab write fails.
+
+### `#clear`
+
+```ruby
+manager.clear
+```
+
+Removes the `# BEGIN aias` … `# END aias` block from the crontab and rewrites it via `crontab -`. Non-aias entries are untouched.
+
+### `#dry_run`
+
+```ruby
+output = manager.dry_run(cron_lines)  # => String
+```
+
+Returns the cron lines that would be installed joined by newlines, without making any system calls or writing to the crontab.
+
+### `#installed_jobs`
+
+```ruby
+jobs = manager.installed_jobs
+# => [
+#      { prompt_id: "daily_digest", cron_expr: "0 8 * * *", log_path: "/..." },
+#      { prompt_id: "reports/weekly", cron_expr: "0 9 * * 1", log_path: "/..." }
+#    ]
+```
+
+Reads the current crontab and parses the `aias`-managed block. Returns an empty array when no block is installed.
+
+### `#current_block`
+
+```ruby
+block = manager.current_block  # => String
+```
+
+Returns the raw text between the `# BEGIN aias` and `# END aias` marker lines (markers excluded). Returns `""` when no block exists.
+
+### `#ensure_log_directories`
+
+```ruby
+manager.ensure_log_directories(["daily_digest", "reports/weekly"])
+```
+
+Creates the log subdirectory structure under `@log_base` for each prompt ID. Called by `CLI#update` before installing.
+
+---
+
+## `Aias::Error`
+
+```ruby
+class Aias::Error < StandardError; end
+```
+
+Raised for unrecoverable errors: missing prompts directory, crontab write failure. Caught by `CLI` which prints the message and exits 1.

data/docs/reference/architecture.md

@@ -0,0 +1,122 @@
+# Architecture
+
+## Overview
+
+`aias` is a thin orchestration layer over three well-established tools: `grep` (for discovery), `PM::Metadata` from the `prompt_manager` gem (for frontmatter parsing), and `fugit` (for cron expression parsing and natural-language schedule resolution). Its five classes have narrow, well-defined responsibilities.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         aias gem                                │
+│                                                                 │
+│   Aias::CLI                                                     │
+│   ├── Aias::PromptScanner   grep -rl + PM::Metadata             │
+│   ├── Aias::Validator       schedule syntax + params + binary   │
+│   ├── Aias::JobBuilder      prompt ID + schedule → cron line    │
+│   └── Aias::CrontabManager  crontab(1) read/write               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+```
+$AIA_PROMPTS_DIR
+      │
+      ▼
+PromptScanner#scan
+      │ returns Array<PromptScanner::Result>
+      │   Result = Data.define(:prompt_id, :schedule, :metadata, :file_path)
+      ▼
+Validator#validate(result)
+      │ returns ValidationResult = Data.define(:valid?, :errors)
+      ▼
+[partition into valid / invalid]
+      │
+      ├── invalid → warn to stderr, skip
+      │
+      └── valid ──►  JobBuilder#build(result)
+                         │ returns String (raw cron line)
+                         ▼
+                    CrontabManager#install(cron_lines)
+                         │ writes via crontab(1) command
+                         ▼
+                    crontab (OS cron daemon manages execution)
+```
+
+## Class Responsibilities
+
+### `Aias::CLI`
+
+The entry point. A `Thor` subclass that exposes nine commands. CLI delegates all domain logic to its four collaborators; it only formats output and handles errors.
+
+Collaborators are created lazily and accessible via private accessors (`scanner`, `validator`, `builder`, `manager`). Tests inject replacements by setting instance variables before calling a command.
+
+### `Aias::PromptScanner`
+
+Discovers scheduled prompts in two steps:
+
+1. **grep phase**: runs `grep -rl "schedule:" $AIA_PROMPTS_DIR` via `Open3.capture3` (no shell injection)
+2. **parse phase**: for each candidate file, calls `PM.parse(absolute_path)` and reads `metadata.schedule`
+
+Returns an array of frozen `Result` value objects. Raises `Aias::Error` if the prompts directory is missing or unreadable.
+
+### `Aias::Validator`
+
+Validates a single `PromptScanner::Result` against three rules (see [Validation](../guides/validation.md)). Returns a frozen `ValidationResult` value object.
+
+The `aia` binary check is memoised — it runs at most once per `Validator` instance.
+
+The `binary_to_check:` constructor parameter makes the binary check testable without stubs.
+
+### `Aias::JobBuilder`
+
+Pure function: converts a `PromptScanner::Result` into a raw cron line string. No I/O, no side effects.
+
+Uses `fugit` to resolve the `schedule:` value to a canonical 5-field cron expression, then assembles:
+
+```
+<cron_expr> <shell> -l -c 'aia [--prompts-dir DIR] <prompt_id> >> <log> 2>&1'
+```
+
+Uses `ENV["SHELL"]` (defaulting to `/bin/bash`) as the login shell. Log paths follow the pattern `~/.aia/schedule/logs/<prompt_id>.log`.
+
+### `Aias::CrontabManager`
+
+Manages the aias-owned block in the user's crontab by directly invoking the system `crontab(1)` command via `Open3`. Three categories of operations:
+
+| Category | Methods | How |
+|---|---|---|
+| Write | `install(cron_lines)`, `add_job(cron_line, prompt_id)`, `clear` | `Open3.popen2(crontab_command, "-")` — pipes new content to stdin |
+| Read | `installed_jobs`, `current_block` | `Open3.capture3(crontab_command, "-l")` |
+| Preview | `dry_run(cron_lines)` | `Array(cron_lines).join("\n")` — no system calls |
+
+The managed block is delimited by `# BEGIN aias` and `# END aias` marker comments. All other crontab entries are preserved verbatim.
+
+The `crontab_command:` and `log_base:` constructor parameters make the manager fully testable with a fake crontab script backed by a tmpfile — no system crontab is ever touched during tests.
+
+## Key Value Objects
+
+Both value objects are defined with `Data.define` (Ruby 3.2+) and are automatically frozen and immutable.
+
+```ruby
+# Returned by PromptScanner#scan
+Aias::PromptScanner::Result = Data.define(:prompt_id, :schedule, :metadata, :file_path)
+
+# Returned by Validator#validate
+Aias::Validator::ValidationResult = Data.define(:valid?, :errors)
+```
+
+## Autoloading
+
+Zeitwerk handles autoloading. The `cli` filename is mapped to `Aias::CLI` (not `Aias::Cli`) via a custom inflection:
+
+```ruby
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("cli" => "CLI")
+loader.setup
+```
+
+## Error Handling
+
+A single `Aias::Error < StandardError` is raised for unrecoverable conditions (missing prompts dir, crontab write failure). The CLI rescues it, prints the message, and exits 1.
+
+Recoverable per-prompt issues (invalid schedule, missing parameter defaults) are collected as error strings in `ValidationResult#errors` and never raised as exceptions.

data/docs/reference/environment.md

@@ -0,0 +1,67 @@
+# Environment Variables
+
+## Prompts Directory Resolution
+
+The prompts directory is resolved in this order:
+
+| Priority | Source |
+|---|---|
+| 1 (highest) | `--prompts-dir PATH` CLI option |
+| 2 | `AIA_PROMPTS__DIR` environment variable (AIA >= 0.8.0) |
+| 3 | `AIA_PROMPTS_DIR` environment variable (AIA < 0.8.0) |
+| — | Error if none of the above is set |
+
+---
+
+## `AIA_PROMPTS__DIR`
+
+**Preferred.** Set by AIA >= 0.8.0. Takes precedence over `AIA_PROMPTS_DIR`.
+
+```bash
+export AIA_PROMPTS__DIR="$HOME/.prompts"
+```
+
+## `AIA_PROMPTS_DIR`
+
+**Legacy (AIA < 0.8.0).** The absolute path to the directory containing your AIA prompt files. Used as a fallback when `AIA_PROMPTS__DIR` is not set.
+
+```bash
+export AIA_PROMPTS_DIR="$HOME/.prompts"
+```
+
+Set this in your login profile (`.zprofile`, `.bash_profile`) so it is available in cron jobs.
+
+## `SHELL`
+
+**Optional.** The shell binary used to wrap each cron entry with a login invocation.
+
+`aias` reads `ENV["SHELL"]` when building job entries. If not set, falls back to `/bin/bash`.
+
+```bash
+echo $SHELL
+# /bin/zsh
+```
+
+This produces cron entries of the form:
+
+```
+0 8 * * * /bin/zsh -l -c 'aia daily_digest >> ... 2>&1'
+```
+
+To override the shell for a specific `update` run:
+
+```bash
+SHELL=/bin/bash aias update
+```
+
+## Variables Needed by AIA at Runtime
+
+These are not used by `aias` directly, but must be available in your login profile for cron jobs to succeed.
+
+| Variable | Description |
+|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic API key (when using Claude) |
+| `OPENAI_API_KEY` | OpenAI API key (when using GPT models) |
+| `AIA_PROMPTS_DIR` | Same as above — must be in login profile |
+
+Set these in your login profile, not only in your interactive shell's rc file (`.bashrc`, `.zshrc`). See [Cron Environment](../guides/cron-environment.md) for details.

data/docs/reference/logging.md

@@ -0,0 +1,73 @@
+# Logging
+
+## Log File Location
+
+Each scheduled prompt writes to its own log file under `~/.aia/schedule/logs/`:
+
+```
+~/.aia/schedule/logs/
+  daily_digest.log
+  reports/
+    weekly.log
+    monthly_summary.log
+```
+
+The subdirectory structure mirrors the prompt's subpath relative to `$AIA_PROMPTS_DIR`.
+
+| Prompt ID | Log File |
+|---|---|
+| `daily_digest` | `~/.aia/schedule/logs/daily_digest.log` |
+| `reports/weekly` | `~/.aia/schedule/logs/reports/weekly.log` |
+| `a/b/deep` | `~/.aia/schedule/logs/a/b/deep.log` |
+
+## Log Behaviour
+
+| Behaviour | Details |
+|---|---|
+| **Always append** | `>>` is used — log entries accumulate across runs |
+| **Combined stdout + stderr** | `2>&1` — all output goes to the same file |
+| **Created by cron** | The log file is created on the first run; `aias` only creates the parent directory |
+
+## Log Directory Creation
+
+`aias update` calls `ensure_log_directories` before installing, which creates the necessary subdirectory structure under `~/.aia/schedule/logs/`. The directories are created even if no jobs have run yet.
+
+## Viewing Logs
+
+```bash
+# Tail the log for a specific prompt
+tail -f ~/.aia/schedule/logs/daily_digest.log
+
+# Check the last run time
+ls -la ~/.aia/schedule/logs/daily_digest.log
+
+# View recent entries
+tail -n 50 ~/.aia/schedule/logs/reports/weekly.log
+```
+
+## Using aias next
+
+The `aias next` command shows the log file's modification timestamp as a proxy for the last run time:
+
+```bash
+aias next
+```
+
+```
+daily_digest
+  schedule : 0 8 * * *
+  last run : 2025-03-20 08:00:01 +0000
+  log      : /Users/you/.aia/schedule/logs/daily_digest.log
+```
+
+"never run" is shown when the log file does not exist.
+
+## Customising the Log Base
+
+The log base directory defaults to `~/.aia/schedule/logs`. It can be overridden when constructing `CrontabManager` directly:
+
+```ruby
+manager = Aias::CrontabManager.new(log_base: "/custom/log/dir")
+```
+
+This is intended for testing and programmatic use. The CLI always uses the default.