mps 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f0d20f2919cb1ee0ae46a3fe6eaef005af856eabd4650fc5e6e07477b5e7fb3
+  data.tar.gz: 259a623e9ee4b8edea593ab16a270b11015a55e3e22564359a424610f0510caa
+SHA512:
+  metadata.gz: 4653dca542034d736e5e61c69b2750c5ddb119c141876fac896b3f15e79d3d758f9e299a3ecf75fd17c52c5e7dbd8da9a562be228d760c6e4a7ba290359c83b0
+  data.tar.gz: 9cf8bf1273e814ed6708561c1f7cd5b82917e804b0e97e867d34c50bb2f35e762067f3df3493cb59eb4eea3ab0e5b1be9e02c38cbc7fffb43c9b9494c4790be3

data/.github/workflows/main.yml

@@ -0,0 +1,29 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - master
+      - release/*
+  pull_request:
+    branches:
+      - master
+      - dev
+      - release/*
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0.2
+      - name: Run the default task
+        run: |
+          gem update --system
+          gem install bundler -v 2.2.13
+          bundle add rake
+          bundle install
+          bundle exec rake

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.lock
+*.mps
+/vendor/
+**/**/*.gem
+

data/CLAUDE.md

@@ -0,0 +1,102 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MPS (MonoPsyches) is a Ruby gem — a plain-text personal productivity CLI. Users store tasks, notes, reminders, and logs in date-stamped `.mps` files (e.g. `20260226.1730000000.mps`) inside a configurable storage directory (`~/.mps/mps/` by default). Files are opened in Vim; git integration handles sync.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake test:with_groups
+
+# Run a single test file
+bundle exec ruby -Itest -Ilib test/config_test.rb
+
+# Run a single test by name
+bundle exec ruby -Itest -Ilib test/config_test.rb -n test_name
+
+# Build the gem
+gem build mps.gemspec
+
+# Run the CLI locally
+bundle exec exe/mps
+```
+
+```bash
+# List parsed elements from today's (or a given date's) file
+bundle exec exe/mps list [DATESIGN] [--type task|note|log|reminder]
+
+# Append a single element without opening Vim
+bundle exec exe/mps append TYPE BODY [--tags work,release] [--at 3pm]
+
+# Auto stage, commit, pull, and push inside storage_dir
+bundle exec exe/mps autogit
+```
+
+Set `MPS_DEBUG=true` to enable verbose `require_relative` tracing via the custom `ir()` loader.
+
+## Architecture
+
+### Entry point
+`exe/mps` calls `MPS::CLI::MPS.start(ARGV)` — a Thor-based CLI defined in `lib/cli/mps.rb`. All commands (`open`, `git`, `autogit`, `list`, `append`, `cmd`, `version`) live there and delegate to the library layer.
+
+### Custom loader (`ir`)
+`lib/mps/mps.rb` defines a global helper `ir(relative_path)` that wraps `require_relative` with caller-location resolution. All internal requires use `ir` instead of `require_relative`. This is intentional — don't replace it with standard requires.
+
+### Load order (`lib/mps.rb`)
+```
+mps/version → mps/mps (defines ir + MPS module methods) →
+  mps/constants → mps/config → mps/interpolators → mps/elements → mps/engines → cli/mps
+```
+
+### Parsing pipeline (`lib/mps/engines/mps.rb`)
+`Engines::MPS.parse_mps_file_to_elments_hash` reads an `.mps` file and uses `StringScanner` to tokenize it. It wraps the raw file contents in a synthetic `@mps[]{}` root element, then does a single-pass scan driven by two regexes from `Constants`: `AT_REGEXP_LA` (lookahead for `@element[args]{`) and `END_CURLY_REGEXP_LA` (lookahead for `}`). A stack tracks nesting; each closed element is instantiated and stored in a flat hash keyed by a dotted ref path (e.g. `"1234567890.1.2"`).
+
+### Elements (`lib/mps/elements/`)
+Each element type (Task, Note, Reminder, Log, MPS) is a class that `include`s the `MPS::Element` mixin. The mixin provides `initialize(args:, refs:, body_str:)`, `display_str`, and `attr_reader :body_str`. Each class must define `SIGNATURE_STAMP` (used when generating filenames/wrapping) and `SIGNATURE_REGEX` (matched against the parsed element sign to dispatch). The engine discovers all element classes dynamically via `MPS::Elements.constants`.
+
+### Interpolators (`lib/mps/interpolators/`)
+Interpolator classes (e.g. `Interpolators::Time`) are discovered the same way as elements — via `const_get` on the module's `constants`. Each defines `SIGNATURE_REGEX` and `get_str(**ref)`. They are loaded into `Engines::MPS` but the interpolation call-site is not yet wired up in the engine.
+
+### Configuration (`lib/mps/config.rb` + `lib/mps/constants.rb`)
+`Config.init(path)` writes a default YAML config. `Config.new(**hash)` holds `storage_dir`, `mps_dir`, `log_file`, and a `Logger`. Two additional optional YAML keys are supported: `git_remote` (default `"origin"`) and `git_branch` (default `"master"`); both are exposed as `attr_reader`s and used by `git` and `autogit` commands. The CLI re-reads the config on every invocation via `load_config`; it auto-creates missing directories and the log file.
+
+## File format
+
+```
+@task[tag1, tag2]{
+  Task body text
+}
+
+@note{
+  Free-form note
+}
+
+@reminder[at: 3pm]{
+  Meeting description
+}
+
+@log[start: 09:00, end: 12:30]{
+  Time log entry
+}
+
+@mps{
+  @task{ nested task }
+}
+```
+
+File names follow `YYYYMMDD.<epoch>.mps`; the epoch disambiguates multiple files per day. The regexp for valid names is `Constants::MPS_FILE_NAME_REGEXP`.
+
+## Testing
+
+Tests use Minitest with `fakefs` for filesystem isolation. The test helper at `test/test_helper.rb` sets up the load path and does `include MPS`, so all constants and module methods are available directly in test classes.
+
+`test/engine_test.rb` tests the parser directly: it uses a `parse_content(str)` helper that writes a fixture file under `FakeFS` at `/tmp/20260101.mps` and calls `Engines::MPS.parse_mps_file_to_elments_hash` on it. Covers empty files, single and multiple elements, unknown element fallback to `Struct`, nested `@mps{}`, `matched_element_class`, and `look_ahead_pos` edge cases.
+
+`test/config_test.rb` covers `Config.init`, `Config.load_conf_hash` (including `git_remote`/`git_branch` defaults), logger formatting, and `LoadError` on missing keys.

data/GETTING_STARTED.md

@@ -0,0 +1,447 @@
+# Getting Started with MPS
+
+MPS is a plain-text productivity system that lives in your terminal. Your tasks, notes, reminders, and logs are just `.mps` files in a folder — readable, portable, and git-backed. No app to install, no account to create, no sync service to trust.
+
+---
+
+## Install
+
+```bash
+gem install mps
+```
+
+First run creates everything automatically:
+
+```
+~/.mps_config.yaml   ← your config
+~/.mps/mps/          ← where your files live
+~/.mps/mps.log       ← activity log
+```
+
+---
+
+## The file format
+
+Before anything else, it helps to know what you're working with. Each `.mps` file is plain text. Every entry is an **element** — a type, optional arguments in `[]`, and a body in `{}`:
+
+```
+@task[work, release]{
+  Ship the API refactor
+}
+
+@note{
+  The auth token expiry edge case needs a second look
+}
+
+@reminder[at: 10am]{
+  Team standup
+}
+
+@log[start: 09:00, end: 12:30]{
+  Debugging the auth flow
+}
+
+@mps{
+  @task[backend]{
+    Nested task inside a sub-block
+  }
+}
+```
+
+The brackets are optional — `@task{ body }` is perfectly valid. Elements nest freely. Files are named `YYYYMMDD.<epoch>.mps` — the epoch allows multiple files per day without collision.
+
+---
+
+## A day in the life
+
+It's Monday morning. You open your terminal:
+
+```bash
+mps
+```
+
+Vim opens with today's file — `20260428.1745000000.mps`. You write your morning plan, save, and quit. That's your day started.
+
+If you want a specific date instead:
+
+```bash
+mps open yesterday
+mps open "last monday"
+mps open 20260421
+mps open "2 days ago"
+```
+
+Natural language dates work everywhere in MPS, powered by [Chronic](https://github.com/mojombo/chronic). Anything Chronic understands, MPS understands.
+
+---
+
+## Reading what you wrote
+
+You're two hours into the day and forget whether you wrote down that reminder. Don't open Vim — just ask:
+
+```bash
+mps list
+```
+
+```
+  [task] (open) Review the API pull request [work]
+  [reminder] (10am) Team standup
+  [note] The auth token expiry edge case needs a second look
+  [@mps]
+    [task] (open) Nested backend task [backend]
+```
+
+The nested tree is preserved — child elements appear indented under their parent `[@mps]` group. Each type gets its own color in the terminal.
+
+### Filter by type
+
+Only want tasks?
+
+```bash
+mps list --type task
+# short form:
+mps list -t task
+```
+
+### Filter by tag
+
+Everything tagged `work`:
+
+```bash
+mps list --tag work
+mps list -g work
+```
+
+### Filter by status (tasks only)
+
+See only what's still open:
+
+```bash
+mps list --status open
+mps list -s done
+```
+
+Status filtering only applies to tasks — notes, logs, and reminders are excluded when you use `--status`.
+
+### Look at a different day
+
+```bash
+mps list yesterday
+mps list "last friday"
+mps list 20260421
+```
+
+### Date ranges with `--since`
+
+Want everything from the last week up to today?
+
+```bash
+mps list --since "last monday"
+```
+
+This prints a date header for each day that has entries:
+
+```
+── 2026-04-25 ─────────────
+  [task] (done) Set up CI pipeline [devops]
+── 2026-04-28 ─────────────
+  [task] (open) Review the API pull request [work]
+  [note] Token expiry edge case
+```
+
+Combine filters freely: `mps list --since yesterday --type task --status open` shows all open tasks from yesterday to today.
+
+---
+
+## Quick-capture without opening Vim
+
+You're deep in a debugging session. A thought hits you. You don't want to break your flow:
+
+```bash
+mps append note "Check if the race condition only happens under load"
+```
+
+```
+  appended  [note] Check if the race condition only happens under load
+```
+
+The note lands at the bottom of today's file.
+
+### Append with tags
+
+```bash
+mps append task "Fix the token expiry bug" --tags work,backend
+```
+
+### Append a task with status
+
+Already done? Mark it immediately:
+
+```bash
+mps append task "Reviewed the PR" --tags work --status done
+```
+
+### Log your time
+
+Log a focused work session with start and end times:
+
+```bash
+mps append log "Deep work on auth refactor" --tags work --start-time 09:00 --end-time 12:30
+```
+
+The 3h30m duration is computed automatically and shown in `list`, `stats`, and `export`.
+
+### Set a timed reminder
+
+```bash
+mps append reminder "Push the hotfix before EOD" --at "5pm"
+```
+
+All types supported by `append`: `task`, `note`, `log`, `reminder`.
+
+---
+
+## Search across all your files
+
+End of quarter. You vaguely remember logging something about "auth" in March. You don't know which file.
+
+```bash
+mps search "auth"
+```
+
+```
+2026-04-28 [log] (3h30m) Debugging the auth flow [work, backend]
+2026-04-21 [task] (done) Fix auth token expiry [backend]
+(2 results)
+```
+
+Every `.mps` file in your storage directory is searched. Results show the date, type badge, and first line of the body.
+
+### Narrow the search
+
+Filter to a specific type:
+
+```bash
+mps search "auth" --type log
+mps search "auth" -t task
+```
+
+Filter to a tag:
+
+```bash
+mps search "auth" --tag backend
+mps search "auth" -g work
+```
+
+Limit to recent files:
+
+```bash
+mps search "auth" --since "last month"
+mps search "auth" -S "2026-04-01"
+```
+
+All filters compose: `mps search "auth" --type task --tag backend --since "last week"`.
+
+---
+
+## Your productivity at a glance
+
+Friday afternoon. How did your week go?
+
+```bash
+mps stats --since monday
+```
+
+```
+2026-04-25 — 2 tasks (1 open, 1 done), 1 note, 1 log (2h)
+2026-04-26 — 1 task (0 open, 1 done), 2 logs (5h30m)
+2026-04-28 — 3 tasks (2 open, 1 done), 1 note, 1 reminder, 1 log (3h30m)
+────────────────────────────────────────────────
+Total: 6 tasks, 3 notes, 1 reminder, 3 logs (11h total)
+```
+
+Open vs done task counts, total logged hours, everything in one view.
+
+For a single day:
+
+```bash
+mps stats
+mps stats yesterday
+mps stats 20260421
+```
+
+---
+
+## Export your data
+
+Need to feed your `.mps` data into a spreadsheet, script, or another tool?
+
+```bash
+mps export --format json
+```
+
+```json
+[
+  {
+    "date": "2026-04-28",
+    "ref": "1745000000.1",
+    "type": "task",
+    "tags": "work",
+    "body": "Review the API pull request",
+    "status": "open"
+  },
+  ...
+]
+```
+
+CSV format:
+
+```bash
+mps export --format csv
+```
+
+```
+date,ref,type,tags,body,status,at,start,end
+2026-04-28,1745000000.1,task,work,Review the API pull request,open,,,
+2026-04-28,1745000000.2,reminder,,Team standup,,10am,,
+```
+
+All the same filters apply:
+
+```bash
+# Export all tasks this week
+mps export --since monday --type task --format csv > this_week_tasks.csv
+
+# Export everything from a specific day as JSON
+mps export 20260421 --format json > april21.json
+
+# Pipe into jq
+mps export --since "last month" --format json | jq '[.[] | select(.status == "done")]'
+```
+
+---
+
+## Git backup — one command
+
+Your files live in `~/.mps/mps/`. Initialize that directory as a git repo once, then let MPS handle sync:
+
+```bash
+mps autogit
+```
+
+This does: `git add .` → `git commit -m "$(date)"` → `git pull` → `git push`. Run it at the end of each day.
+
+For manual control:
+
+```bash
+mps git status
+mps git log --oneline -5
+mps git commit -m "end of sprint retrospective"
+mps git auto         # same as autogit
+mps git autocommit   # stage and commit only, no push
+```
+
+Every `mps git` command runs inside your storage directory — no `cd` needed.
+
+### Configure your remote and branch
+
+By default MPS pushes to `origin` on `master`. To use a different remote or branch, edit `~/.mps_config.yaml`:
+
+```yaml
+mps_dir: /home/you/.mps
+storage_dir: /home/you/.mps/mps
+log_file: /home/you/.mps/mps.log
+git_remote: origin
+git_branch: main
+```
+
+---
+
+## Run any shell command in your storage directory
+
+Need to see what files exist, or grep across everything raw?
+
+```bash
+mps cmd ls -la
+mps cmd grep -r "token expiry" .
+mps cmd wc -l *.mps
+```
+
+Everything runs inside `~/.mps/mps/`.
+
+---
+
+## Version
+
+```bash
+mps version
+```
+
+---
+
+## Full reference
+
+### Commands
+
+| Command | What it does |
+|---------|-------------|
+| `mps` / `mps open [date]` | Open a date's file in Vim (default: today) |
+| `mps list [date]` | Print elements in tree order (default: today) |
+| `mps append TYPE BODY` | Add one element to today's file without Vim |
+| `mps search QUERY` | Full-text search across all files |
+| `mps stats [date]` | Element counts and log durations for a date |
+| `mps export [date]` | Export elements as JSON or CSV to stdout |
+| `mps autogit` | Stage, commit, pull, push in one shot |
+| `mps git ARGS` | Run any git command inside storage dir |
+| `mps cmd ARGS` | Run any shell command inside storage dir |
+| `mps version` | Print current version |
+
+### list options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--type TYPE` | `-t` | Filter by: `task`, `note`, `log`, `reminder` |
+| `--tag TAG` | `-g` | Filter by tag name |
+| `--status STATUS` | `-s` | Filter tasks by: `open`, `done` |
+| `--since DATESIGN` | `-S` | Show elements from SINCE up to DATESIGN |
+
+### append options
+
+| Option | Description |
+|--------|-------------|
+| `--tags t1,t2` | Comma-separated tags |
+| `--status open\|done` | Task status (default: open) |
+| `--at TIME` | Time for reminders (e.g. `5pm`) |
+| `--start-time HH:MM` | Start time for logs |
+| `--end-time HH:MM` | End time for logs |
+
+### search options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--type TYPE` | `-t` | Filter by element type |
+| `--tag TAG` | `-g` | Filter by tag |
+| `--since DATESIGN` | `-S` | Search from this date onward |
+
+### stats options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--since DATESIGN` | `-S` | Stats from SINCE up to DATESIGN |
+
+### export options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--format FORMAT` | `-f` | Output format: `json` (default), `csv` |
+| `--type TYPE` | `-t` | Filter by element type |
+| `--since DATESIGN` | `-S` | Export from SINCE up to DATESIGN |
+
+### Date formats accepted everywhere
+
+| Input | Meaning |
+|-------|---------|
+| `today`, `yesterday` | Relative day |
+| `monday`, `last friday` | Day of week |
+| `2 days ago`, `last week` | Natural language |
+| `20260421` | Explicit YYYYMMDD |

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in mps.gemspec
+gemspec

data/IMPROVEMENTS.md

@@ -0,0 +1,90 @@
+# MPS Improvements & Feature Roadmap
+
+## Bugs
+
+| # | File | Issue | Severity |
+|---|------|-------|----------|
+| B1 | `lib/mps/elements/*.rb` | `# frozen string_literal: true` missing the `_` — magic comment is silently ignored | Medium |
+| B2 | `lib/cli/mps.rb:61` | `git pull orign master` — typo `orign` instead of `origin` | High |
+| B3 | `lib/mps/engines/mps.rb:12` | Uses `eval("::MPS::Elements::#{k}")` — unsafe; use `const_get` | Medium |
+| B4 | `test/config_test.rb` | All test bodies are commented out — zero test coverage on Config | High |
+| B5 | `lib/mps/interpolators/` | Interpolators are loaded into `Engines::MPS` but never invoked anywhere | Medium |
+
+## Code Quality
+
+| # | Issue | Fix |
+|---|-------|-----|
+| Q1 | `ir()` is defined as a bare global method in `lib/mps/mps.rb` — pollutes `Object` | Move inside `MPS` module as `MPS.ir` or keep but at least document it |
+| Q2 | Element classes are identical boilerplate — only `SIGNATURE_STAMP` / `SIGNATURE_REGEX` differ | Extract a `MPS::Elements.define(stamp)` factory or use a shared DSL |
+| Q3 | `Engines::MPS` class name clashes with `Elements::MPS` class — confusing namespace | Rename engine to `Engines::Parser` |
+| Q4 | `Exception` is rescued in every CLI command instead of `StandardError` — catches `SignalException`, `SystemExit` | Use `StandardError` |
+| Q5 | Config is re-read on every CLI invocation but never cached or validated beyond key presence | Add type-checked struct |
+
+## New Features
+
+### F1 — `list` command
+Display parsed elements from any `.mps` file in the terminal, with optional type filter.
+
+```
+mps list                    # today's file
+mps list yesterday          # yesterday's file
+mps list 20260226 --type task
+```
+
+### F2 — `search` command
+Full-text search across all `.mps` files in storage, return matching elements.
+
+```
+mps search "meeting"
+mps search "deploy" --type task --since 7.days.ago
+```
+
+### F3 — `stats` command
+Print a summary of element counts per type for a date (or range).
+
+```
+mps stats                   # today
+mps stats --since last.week
+```
+
+### F4 — `append` command (non-Vim fast entry)
+Append a single element to today's file without opening Vim.
+
+```
+mps append task "Write release notes" --tags work,release
+mps append note "Idea: dark mode"
+mps append reminder "Standup" --at "9am"
+```
+
+### F5 — Typed element attribute parsing
+Currently `@log[start: 09:00, end: 12:30]` args are raw strings. Parse them into typed structs so `list`/`stats` can compute duration, countdown to reminder time, etc.
+
+### F6 — Export command
+Serialize parsed elements to JSON or CSV.
+
+```
+mps export --format json > today.json
+mps export --format csv --since last.week > week.csv
+```
+
+### F7 — Configurable branch / remote for git sync
+`git auto` hardcodes `master` and `origin`. Make both configurable in `~/.mps_config.yaml`.
+
+```yaml
+git_remote: origin
+git_branch: main
+```
+
+## Implementation Priority
+
+1. **B1, B2, B3** — straightforward, low-risk fixes
+2. **Q4** — safety (rescue `StandardError` not `Exception`)
+3. **B4** — restore test coverage (Config + Engine parser)
+4. **F1 `list`** — most immediately useful, builds on existing parser
+5. **F4 `append`** — second most useful daily-driver feature
+6. **F7 git config** — removes hardcoded branch/remote
+7. **Q3 rename engine** — minor breaking internal rename
+8. **F5 typed args** — enables F1/F3 to show richer output
+9. **F2 `search`** — builds on F1 infrastructure
+10. **F3 `stats`** — builds on F2
+11. **F6 `export`** — nice-to-have