mostr/README.md

# mostr

An immutable nested collaborative task manager, powered by nostr!

> Mostr is beta software. 
> Do not entrust it exclusively with your data unless you know what you are doing!

> Intermediate versions might not properly persist all changes.
> A failed relay connection currently looses all intermediate changes.

## Quickstart

Install rust(up) and run a development build with:

    cargo run

A `relay` list can be placed in a config file
under `${XDG_CONFIG_HOME:-$HOME/.config}/mostr/`.
Ideally any project with different collaborators has its own relay.
If not saved, mostr will ask for a relay url
(entering none is fine too, but your data will not be persisted between sessions)
and a private key, alternatively generating one on the fly.
The key is saved in the system keychain.

Install latest build:

    cargo install --path .

This one-liner can help you stay on the latest version
(optionally add a `cd` to your mostr-directory in front to use it anywhere):

    git pull && cargo install --path . && mostr

To exit the application, press `Ctrl-D`.

## Reference

### Command Syntax

Uppercased words are placeholders, brackets enclose optional arguments.

`TASK` creation syntax: `NAME #TAG *PRIO @ASSIGNEE # TAG1 TAG2 ...`

- `TASK` - create task
  + prefix with space if you want a task to start with a command character
  + paste text with newlines to create one task per line
- `.` - clear all filters
- `.TASK`
  + activate task by id
  + match by task name prefix: if one or more tasks match, filter / activate (tries case-sensitive then case-insensitive)
  + no match: create & activate task
- `.2` - set view depth to the given number (how many subtask levels to show, default is 1)
- `/[TEXT]` - activate task or filter by smart-case substring match (empty: move to root)
- `||TASK` - create and activate a new task procedure (where subtasks automatically depend on the previously created task)
- `|[TASK]` - mark current task as procedure or create a sibling task depending on the current one and move up
- sibling task shortcut?

Dot or slash can be repeated to move to parent tasks before acting.
Append `@TIME` to any task creation or change command to record the action with the given time.
To add tags or edit the priority or assignee, make the change part of a comment or state update:

- `:[IND][PROP]` - add property column PROP at IND or end,
  if it already exists remove property column PROP or IND; empty: list properties
- `::[PROP]` - sort by property PROP (multiple space-separated values allowed)
- `([TIME]` - list tracked times or insert time-tracking with the specified offset (double to view all history)
  such as `(20` (for 20:00), `(-1d`, `(-15 minutes`, `(yesterday 17:20`, `(in 2 fortnights`
  - TBI: track whole interval in one with dash
- `)[TIME]` - stop time-tracking with optional offset (also convenience helper to move to root)
- `>[TEXT]` - complete active task and move up, with optional status description
- `<[TEXT]` - close active task and move up, with optional status description
- `!TEXT` - set status for current task from text and move up; empty: Open
- `!TIME: REASON` - defer (hide) current task until given time
- `,[TEXT]` - list notes or add text (activity / task description)
- TBI: `;[TEXT]` - list comments or comment on task
- TBI: show status history and creation with attribution
- `&` - revert
  - with string argument, find first matching task in history
  - with int argument, jump back X tasks in history
  - undo last action (moving in place or upwards confirms pending actions)
- `*` - (un)bookmark current task or list all bookmarks
- `wss://...` - switch or subscribe to relay (prefix with space to forcibly add a new one)

Property Filters:

- `#TAG1 TAG2` - set tag filter
- `+TAG` - add tag filter (empty: list all used tags)
- `-TAG` - remove tag filters (by prefix)
- `?STATUS` - set status filter (type or description) - plain `?` to reset, `??` to show all
- `*INT` - set priority filter - `**` to reset
- `@[AUTHOR|TIME]` - filter by time or author (pubkey, or `@` for self, TBI: id prefix, name prefix)

Status descriptions can be used for example for Kanban columns or review flows.
An active tag or status filter will also set that attribute for newly created tasks.

## Basic Usage

### Navigation and Nesting

Create tasks and navigate using the shortcuts below.
Whichever task is active (selected)
will be the parent task for newly created tasks
and automatically has time-tracking running.
To track task progress,
simply subdivide the task -
checking off tasks will automatically update the progress
for all parent tasks.
Generally a flat hierarchy is recommended
with tags for filtering,
since hierarchies cannot be changed.
Filtering by a tag is just as easy
as activating a task and more flexible.

Using subtasks has two main advantages:
- ability to accumulate time tracked
- swiftly navigate between related tasks

Managing a project with subtasks makes it continuously visible,
which is helpful if you want to be able to track time on the project itself
without a specific task,
Thus subtasks can be very useful for specific contexts,
for example a project or a specific place.

On the other hand, related tasks like chores
should be grouped with a tag instead.
Similarly for projects which are only sporadically worked on
when a specific task comes up, so they do not clutter the list.

### Task States

> TODO: Mark as Done vs Closed

### Collaboration

Since everything in mostr is inherently immutable,
live collaboration is easily possible.
After every command,
mostr checks if new updates arrived from the relay
and updates its display accordingly.

If a relay has a lot of events,
initial population of data can take a bit -
but you can already start creating events without issues,
updates will be fetched in the background.
For that reason,
it is recommended to leave mostr running
as you work.

### Time-Tracking

The currently active task is automatically time-tracked.
To stop time-tracking completely, simply move to the root of all tasks.
Time-tracking by default recursively summarizes

### Priorities

Task priorities can be set as any natural number,
with higher numbers denoting higher priorities.
The syntax here allows for very convenient incremental usage:
By default, using priorities between 1 and 9 is recommended,
with an exemplary interpretation like this:

* 1 Ideas / "Someday"
* 2 Later
* 3 Soon
* 4 Relevant
* 5 Important
* 9 DO NOW

Internally, when giving a single digit, a 0 is appended,
so that the default priorities increment in steps of 10.
So in case you need more than 10 priorities,
instead of stacking them on top,
you can granularly add them in between.
For example, `12` is in between `1` and `2`
which are equivalent to `10` and `20`,
not above `9` but above `09`!

By default, only tasks with priority `35` and upward are shown
so you can focus on what matters,
but you can temporarily override that using `**PRIO`.

### Quick Access

Paper-based lists are often popular because you can quickly put down a bunch of items.
Mostr offers three useful workflows depending on the use-case:
If you want to TBC...

- temporary task with subtasks (especially handy for progression)
- Filter by recently created
- Pin to bookmarks
- high priority

### Notes

- TBI = To Be Implemented
- `. TASK` - create and enter a new task even if the name matches an existing one

# Development and Contributions

This Project follows the [Kull Collaboration Convention](https://kull.jfischer.org/),
especially the commit message format.
Currently a separate dev branch is maintained because users regularly receive updates via the main branch.
Once proper packaging is in place, this can be simplified.

## Local Development Tools

Start a nostr relay, such as
- https://github.com/coracle-social/bucket for local development
- https://github.com/rnostr/rnostr for production use

To create a test task externally:
`nostril --envelope --content "test task" --kind 1621 | websocat ws://localhost:4736`

## Plans

- Handle event sending rejections (e.g. permissions)
- Local Database Cache, Negentropy Reconciliation
  -> Offline Use!
- Remove status filter when moving up?
- Task markdown support? - colored
- Calendar Events - make future time-tracking editable -> parametrised replaceable events
- Speedup: Offline caching & Expiry (no need to fetch potential years of history)
  + Fetch most recent tasks first
  + Relay: compress tracked time for old tasks, filter closed tasks
  + Relay: filter out task status updates within few seconds, also on client side

### Commands

Open Command characters: `_^\=$%~'"`, `{}[]`
  
### Conceptual

The following features are not ready to be implemented
because they need conceptualization.
Suggestions welcome!

- Queueing tasks
- Allow adding new parent via description?
- Special commands: help, exit, tutorial, change log level
- Duplicate task (subtasks? time-tracking?)
- What if I want to postpone a procedure, i.e. make it pending, or move it across kanban, does this make sense?
- Dependencies (change from tags to properties so they can be added later? or maybe as a status?)
- Templates
- Ownership
- Combined formatting and recursion specifiers
  + progress count/percentage and recursive or not
  + Subtask progress immediate/all/leafs
  + path full / leaf / top

### Interfaces & Integrations

- TUI: Clear Terminal? Refresh on empty prompt after timeout?
- Kanban, GANTT, Calendar
- n8n node
- Webcal Feed: Scheduled (planning) / Tracked (events, time-tracking) with args for how far back/forward

Interfaces:

- text-based REPL for terminal and messengers
- interactive UI for web, mobile, desktop e.g. https://docs.slint.dev/latest/docs/slint/src/introduction/

### Config Files

- format strings
- thresholds: auto-send message, time-tracking overview interval and count
- global and per-relay: username, key location, tag mappings (i.e. server implies pc, home implies phys) -> also get from relay

## Exemplary Workflows - User Stories

- Freelancer
- Family Chore Management
- Inter-Disciplinary Project Team -> Company with multiple projects and multiple relays
  + Permissions via status or assignment (reassignment?)
  + Tasks can be blocked while having a status (e.g. kanban column)
  + A meeting can be worked on (tracked) before it starts
  + Schedule for multiple people
- Tracking Daily Routines / Habits

### Freelancer

For a Freelancer, mostr can help structure work times
across different projects
because it can connect to multiple clients,
using their mental state effectively (Mind Management not Time Management).
It also enables transparency for clients
by sharing the tracked time -
but alternatively the freelancer
can track times on their own auxiliary relay
without problems.

### Family

With a mobile client implemented,
mostr can track shopping lists and other chores for a family,
and provide them context-dependently -
allowing you to batch shopping and activities without mental effort.

### Project Team

sharing, assigning, stand-ups, communication

### Contexts

A context is a custom set of filters such as status, tags, assignee
so that the visible tasks are always relevant
and newly created tasks are less of a hassle to type out
since they will automatically take on that context.
By automating these contexts based on triggers, scripts or time,
relevant tasks can be surfaced automatically.

#### Vision of Work-Life-Balance for Freelancer

In the morning, your groggy brain is good at divergent thinking,
and you like to do sports in the morning.
So for that time, mostr can show you tasks tagged for divergent thinking,
since you are easily distracted filter out those that require the internet,
as well as anything sportsy.
After you come back from sports and had breakfast,
for example detected through a period of inactivity on your device,
you are ready for work, so the different work projects are shown and you delve into one.
After 90 minutes you reach a natural low in your focus,
so mostr surfaces break activities -
such as a short walk, a small workout, some instrument practice
or simply grabbing a snack and drink.
After lunch you like to take an extended afternoon break,
so your call list pops up -
you can give a few people a call as you make a market run,
before going for siesta.