mirror of
https://github.com/boolean-maybe/tiki
synced 2026-04-21 13:37:20 +00:00
update docs
This commit is contained in:
booleanmaybe
parent
00ba1ed8ec
commit
5eed6072cb
13 changed files with 190 additions and 280 deletions
|
|
@ -62,7 +62,7 @@ Search order: user config dir (base) → `.doc/workflow.yaml` (project) → cwd
|
|||
|
||||
**Views (plugins)** — merged by name across files. The user config is the base; project and cwd files override individual fields:
|
||||
- Non-empty fields in the override replace the base (description, key, colors, view mode)
|
||||
- Non-empty arrays in the override replace the entire base array (lanes, actions, sort)
|
||||
- Non-empty arrays in the override replace the entire base array (lanes, actions)
|
||||
- Empty/zero fields in the override are ignored — the base value is kept
|
||||
- Views that only exist in the override are appended
|
||||
|
||||
|
|
@ -149,18 +149,17 @@ views:
|
|||
key: "F1"
|
||||
lanes:
|
||||
- name: Ready
|
||||
filter: status = 'ready' and type != 'epic'
|
||||
action: status = 'ready'
|
||||
filter: select where status = "ready" and type != "epic" order by priority, createdAt
|
||||
action: update where id = id() set status="ready"
|
||||
- name: In Progress
|
||||
filter: status = 'in_progress' and type != 'epic'
|
||||
action: status = 'in_progress'
|
||||
filter: select where status = "inProgress" and type != "epic" order by priority, createdAt
|
||||
action: update where id = id() set status="inProgress"
|
||||
- name: Review
|
||||
filter: status = 'review' and type != 'epic'
|
||||
action: status = 'review'
|
||||
filter: select where status = "review" and type != "epic" order by priority, createdAt
|
||||
action: update where id = id() set status="review"
|
||||
- name: Done
|
||||
filter: status = 'done' and type != 'epic'
|
||||
action: status = 'done'
|
||||
sort: Priority, CreatedAt
|
||||
filter: select where status = "done" and type != "epic" order by priority, createdAt
|
||||
action: update where id = id() set status="done"
|
||||
- name: Backlog
|
||||
description: "Tasks waiting to be picked up, sorted by priority"
|
||||
foreground: "#5fff87"
|
||||
|
|
@ -169,12 +168,11 @@ views:
|
|||
lanes:
|
||||
- name: Backlog
|
||||
columns: 4
|
||||
filter: status = 'backlog' and type != 'epic'
|
||||
filter: select where status = "backlog" and type != "epic" order by priority, id
|
||||
actions:
|
||||
- key: "b"
|
||||
label: "Add to board"
|
||||
action: status = 'ready'
|
||||
sort: Priority, ID
|
||||
action: update where id = id() set status="ready"
|
||||
- name: Recent
|
||||
description: "Tasks changed in the last 24 hours, most recent first"
|
||||
foreground: "#f4d6a6"
|
||||
|
|
@ -183,8 +181,7 @@ views:
|
|||
lanes:
|
||||
- name: Recent
|
||||
columns: 4
|
||||
filter: NOW - UpdatedAt < 24hours
|
||||
sort: UpdatedAt DESC
|
||||
filter: select where now() - updatedAt < 24hour order by updatedAt desc
|
||||
- name: Roadmap
|
||||
description: "Epics organized by Now, Next, and Later horizons"
|
||||
foreground: "#e2e8f0"
|
||||
|
|
@ -194,19 +191,18 @@ views:
|
|||
- name: Now
|
||||
columns: 1
|
||||
width: 25
|
||||
filter: type = 'epic' AND status = 'ready'
|
||||
action: status = 'ready'
|
||||
filter: select where type = "epic" and status = "ready" order by priority, points desc
|
||||
action: update where id = id() set status="ready"
|
||||
- name: Next
|
||||
columns: 1
|
||||
width: 25
|
||||
filter: type = 'epic' AND status = 'backlog' AND priority = 1
|
||||
action: status = 'backlog', priority = 1
|
||||
filter: select where type = "epic" and status = "backlog" and priority = 1 order by priority, points desc
|
||||
action: update where id = id() set status="backlog" priority=1
|
||||
- name: Later
|
||||
columns: 2
|
||||
width: 50
|
||||
filter: type = 'epic' AND status = 'backlog' AND priority > 1
|
||||
action: status = 'backlog', priority = 2
|
||||
sort: Priority, Points DESC
|
||||
filter: select where type = "epic" and status = "backlog" and priority > 1 order by priority, points desc
|
||||
action: update where id = id() set status="backlog" priority=2
|
||||
view: expanded
|
||||
- name: Help
|
||||
description: "Keyboard shortcuts, navigation, and usage guide"
|
||||
|
|
|
|||
|
|
@ -77,17 +77,16 @@ views:
|
|||
lanes:
|
||||
- name: Backlog
|
||||
columns: 4
|
||||
filter: status = 'backlog' and type != 'epic'
|
||||
filter: select where status = "backlog" and type != "epic" order by priority, id
|
||||
actions:
|
||||
- key: "b"
|
||||
label: "Add to board"
|
||||
action: status = 'ready'
|
||||
sort: Priority, ID
|
||||
action: update where id = id() set status="ready"
|
||||
```
|
||||
|
||||
that translates to - show all tikis in the status `backlog`, sort by priority and then by ID arranged visually in 4 columns in a single lane.
|
||||
The `actions` section defines a keyboard shortcut `b` that moves the selected tiki to the board by setting its status to `ready`
|
||||
You define the name, description, caption colors, hotkey, tiki filter and sorting. The `description` is displayed in the header when the view is active. Save this into a `workflow.yaml` file in the config directory
|
||||
You define the name, description, caption colors, hotkey, and `ruki` expressions for filtering and actions. The `description` is displayed in the header when the view is active. Save this into a `workflow.yaml` file in the config directory
|
||||
|
||||
Likewise the documentation is just a plugin:
|
||||
|
||||
|
|
@ -119,28 +118,27 @@ name: Custom
|
|||
foreground: "#5fff87"
|
||||
background: "#005f00"
|
||||
key: "F4"
|
||||
sort: Priority, Title
|
||||
lanes:
|
||||
- name: Ready
|
||||
columns: 1
|
||||
width: 20
|
||||
filter: status = 'ready'
|
||||
action: status = 'ready'
|
||||
filter: select where status = "ready" order by priority, title
|
||||
action: update where id = id() set status="ready"
|
||||
- name: In Progress
|
||||
columns: 1
|
||||
width: 30
|
||||
filter: status = 'in_progress'
|
||||
action: status = 'in_progress'
|
||||
filter: select where status = "inProgress" order by priority, title
|
||||
action: update where id = id() set status="inProgress"
|
||||
- name: Review
|
||||
columns: 1
|
||||
width: 30
|
||||
filter: status = 'review'
|
||||
action: status = 'review'
|
||||
filter: select where status = "review" order by priority, title
|
||||
action: update where id = id() set status="review"
|
||||
- name: Done
|
||||
columns: 1
|
||||
width: 20
|
||||
filter: status = 'done'
|
||||
action: status = 'done'
|
||||
filter: select where status = "done" order by priority, title
|
||||
action: update where id = id() set status="done"
|
||||
```
|
||||
|
||||
### Lane width
|
||||
|
|
@ -168,135 +166,92 @@ that apply to the currently selected tiki via a keyboard shortcut. These shortcu
|
|||
actions:
|
||||
- key: "b"
|
||||
label: "Add to board"
|
||||
action: status = 'ready'
|
||||
action: update where id = id() set status="ready"
|
||||
- key: "a"
|
||||
label: "Assign to me"
|
||||
action: assignee = CURRENT_USER
|
||||
action: update where id = id() set assignee=user()
|
||||
```
|
||||
|
||||
Each action has:
|
||||
- `key` - a single printable character used as the keyboard shortcut
|
||||
- `label` - description shown in the header
|
||||
- `action` - an action expression (same syntax as lane actions, see below)
|
||||
- `action` - a `ruki` `update` statement (same syntax as lane actions, see below)
|
||||
|
||||
When the shortcut key is pressed, the action is applied to the currently selected tiki.
|
||||
For example, pressing `b` in the Backlog plugin changes the selected tiki's status to `ready`, effectively moving it to the board.
|
||||
|
||||
### Action expression
|
||||
### ruki expressions
|
||||
|
||||
The `action: status = 'backlog'` statement in a plugin is an action to be run when a tiki is moved into the lane. Here `=`
|
||||
means `assign` so status is assigned `backlog` when the tiki is moved. Likewise you can manipulate tags using `+-` (add)
|
||||
or `-=` (remove) expressions. For example, `tags += [idea, UI]` adds `idea` and `UI` tags to a tiki
|
||||
Plugin filters, lane actions, and plugin actions all use the [ruki](ruki/index.md) language. Filters use `select` statements and actions use `update` statements.
|
||||
|
||||
#### Supported Fields
|
||||
#### Filter (select)
|
||||
|
||||
- `status` - set workflow status (must be a key defined in `workflow.yaml` statuses)
|
||||
- `type` - set task type: `story`, `bug`, `spike`, `epic` (case-insensitive)
|
||||
- `priority` - set numeric priority (1-5)
|
||||
- `points` - set numeric points (0 or positive, up to max points)
|
||||
- `assignee` - set assignee string
|
||||
- `tags` - add/remove tags (list)
|
||||
- `dependsOn` - add/remove dependency tiki IDs (list)
|
||||
- `due` - set due date (YYYY-MM-DD format)
|
||||
- `recurrence` - set recurrence pattern (cron format: `0 0 * * *`, `0 0 * * MON`, `0 0 1 * *`)
|
||||
The `filter` field uses a `ruki` `select` statement to determine which tikis appear in a lane. Sorting is part of the select — use `order by` to control display order.
|
||||
|
||||
#### Operators
|
||||
```sql
|
||||
-- basic filter with sort
|
||||
select where status = "backlog" and type != "epic" order by priority, id
|
||||
|
||||
- `=` assigns a value to `status`, `type`, `priority`, `points`, `assignee`, `due`, `recurrence`
|
||||
- `+=` adds tags or dependencies, `-=` removes them
|
||||
- multiple operations are separated by commas: `status=done, tags+=[moved]`
|
||||
-- recent items, most recent first
|
||||
select where now() - updatedAt < 24hour order by updatedAt desc
|
||||
|
||||
#### Literals
|
||||
-- multiple conditions
|
||||
select where type = "epic" and status = "backlog" and priority > 1 order by priority, points desc
|
||||
|
||||
- strings can be quoted (`'in_progress'`, `"alex"`) or bare (`done`, `alex`)
|
||||
- use quotes when the value has spaces
|
||||
- integers are used for `priority` and `points`
|
||||
- tag lists use brackets: `tags += [ui, frontend]`
|
||||
- `CURRENT_USER` assigns the current git user to `assignee`
|
||||
- example: `assignee = CURRENT_USER`
|
||||
|
||||
### Filter expression
|
||||
|
||||
The `filter: status = 'backlog'` statement in a plugin is a filter expression that determines which tikis appear in the view.
|
||||
|
||||
#### Supported Fields
|
||||
|
||||
You can filter on these task fields:
|
||||
- `id` - Task identifier (e.g., 'TIKI-m7n2xk')
|
||||
- `title` - Task title text (case-insensitive)
|
||||
- `type` - Task type: 'story', 'bug', 'spike', or 'epic' (case-insensitive)
|
||||
- `status` - Workflow status (must match a key defined in `workflow.yaml` statuses)
|
||||
- `assignee` - Assigned user (case-insensitive)
|
||||
- `priority` - Numeric priority value
|
||||
- `points` - Story points estimate
|
||||
- `tags` (or `tag`) - List of tags (case-insensitive)
|
||||
- `dependsOn` - List of dependency tiki IDs
|
||||
- `due` - Due date (YYYY-MM-DD format, supports time arithmetic)
|
||||
- `recurrence` - Recurrence pattern (cron string, compared as string)
|
||||
- `createdAt` - Creation timestamp
|
||||
- `updatedAt` - Last update timestamp
|
||||
|
||||
All string comparisons are case-insensitive.
|
||||
|
||||
#### Operators
|
||||
|
||||
- **Comparison**: `=` (or `==`), `!=`, `>`, `>=`, `<`, `<=`
|
||||
- **Logical**: `AND`, `OR`, `NOT` (precedence: NOT > AND > OR)
|
||||
- **Membership**: `IN`, `NOT IN` (check if value in list using `[val1, val2]`)
|
||||
- **Grouping**: Use parentheses `()` to control evaluation order
|
||||
|
||||
#### Literals and Special Values
|
||||
|
||||
**Special expressions**:
|
||||
- `CURRENT_USER` - Resolves to the current git user (works in comparisons and IN lists)
|
||||
- `NOW` - Current timestamp
|
||||
|
||||
**Time expressions**:
|
||||
- `NOW - UpdatedAt` - Time elapsed since update
|
||||
- `NOW - CreatedAt` - Time since creation
|
||||
- Duration units: `min`/`minutes`, `hour`/`hours`, `day`/`days`, `week`/`weeks`, `month`/`months`
|
||||
- Examples: `2hours`, `14days`, `3weeks`, `60min`, `1month`
|
||||
- Operators: `+` (add), `-` (subtract or compute duration)
|
||||
|
||||
**Special tag semantics**:
|
||||
- `tags IN ['ui', 'frontend']` matches if ANY task tag matches ANY list value
|
||||
- This allows intersection testing across tag arrays
|
||||
|
||||
#### Examples
|
||||
|
||||
```text
|
||||
# Multiple statuses
|
||||
status = 'ready' OR status = 'in_progress'
|
||||
|
||||
# With tags
|
||||
tags IN ['frontend', 'urgent']
|
||||
|
||||
# High priority bugs
|
||||
type = 'bug' AND priority = 0
|
||||
|
||||
# Features and ideas assigned to me
|
||||
(type = 'feature' OR tags IN ['idea']) AND assignee = CURRENT_USER
|
||||
|
||||
# Unassigned large tasks
|
||||
assignee = '' AND points >= 5
|
||||
|
||||
# Recently created tasks not in backlog
|
||||
(NOW - CreatedAt < 2hours) AND status != 'backlog'
|
||||
-- assigned to me
|
||||
select where assignee = user() order by priority
|
||||
```
|
||||
|
||||
### Sorting
|
||||
#### Action (update)
|
||||
|
||||
The `sort` field determines the order in which tikis appear in the view. You can sort by one or more fields, and control the direction (ascending or descending).
|
||||
The `action` field uses a `ruki` `update` statement. In plugin context, `id()` refers to the currently selected tiki.
|
||||
|
||||
#### Sort Syntax
|
||||
```sql
|
||||
-- set status on move
|
||||
update where id = id() set status="ready"
|
||||
|
||||
```text
|
||||
sort: Field1, Field2 DESC, Field3
|
||||
-- set multiple fields
|
||||
update where id = id() set status="backlog" priority=2
|
||||
|
||||
-- assign to current user
|
||||
update where id = id() set assignee=user()
|
||||
```
|
||||
|
||||
#### Examples
|
||||
#### Supported fields
|
||||
|
||||
```text
|
||||
# Sort by creation time descending (recent first), then priority, then title
|
||||
sort: CreatedAt DESC, Priority, Title
|
||||
```
|
||||
- `id` - task identifier (e.g., "TIKI-M7N2XK")
|
||||
- `title` - task title text
|
||||
- `type` - task type: "story", "bug", "spike", or "epic"
|
||||
- `status` - workflow status (must match a key defined in `workflow.yaml` statuses)
|
||||
- `assignee` - assigned user
|
||||
- `priority` - numeric priority value (1-5)
|
||||
- `points` - story points estimate
|
||||
- `tags` - list of tags
|
||||
- `dependsOn` - list of dependency tiki IDs
|
||||
- `due` - due date (YYYY-MM-DD format)
|
||||
- `recurrence` - recurrence pattern (cron format)
|
||||
- `createdAt` - creation timestamp
|
||||
- `updatedAt` - last update timestamp
|
||||
|
||||
#### Conditions
|
||||
|
||||
- **Comparison**: `=`, `!=`, `>`, `>=`, `<`, `<=`
|
||||
- **Logical**: `and`, `or`, `not` (precedence: not > and > or)
|
||||
- **Membership**: `"value" in field`, `status not in ["done", "cancelled"]`
|
||||
- **Emptiness**: `assignee is empty`, `tags is not empty`
|
||||
- **Quantifiers**: `dependsOn any status != "done"`, `dependsOn all status = "done"`
|
||||
- **Grouping**: parentheses `()` to control evaluation order
|
||||
|
||||
#### Literals and built-ins
|
||||
|
||||
- Strings: double-quoted (`"ready"`, `"alex"`)
|
||||
- Integers: `1`, `5`
|
||||
- Dates: `2026-03-25`
|
||||
- Durations: `2hour`, `14day`, `3week`, `1month`
|
||||
- Lists: `["bug", "frontend"]`
|
||||
- `user()` — current user
|
||||
- `now()` — current timestamp
|
||||
- `id()` — currently selected tiki (in plugin context)
|
||||
- `count(select where ...)` — count matching tikis
|
||||
|
||||
For the full language reference, see the [ruki documentation](ruki/index.md).
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
- [Markdown viewer](markdown-viewer.md)
|
||||
- [Image support](image-requirements.md)
|
||||
- [Customization](customization.md)
|
||||
- [Ruki](ruki/index.md)
|
||||
- [ruki](ruki/index.md)
|
||||
- [tiki format](tiki-format.md)
|
||||
- [Quick capture](quick-capture.md)
|
||||
- [AI skills](skills.md)
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
# Ruki Documentation
|
||||
# ruki Documentation
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Ruki](#ruki)
|
||||
- [ruki](#ruki)
|
||||
- [Quick start](#quick-start)
|
||||
- [More details](#more-details)
|
||||
|
||||
## Ruki
|
||||
## ruki
|
||||
|
||||
This section documents the Ruki language. Ruki is a small language for finding, creating, updating, and deleting tikis, with SQL-like statements and trigger rules.
|
||||
This section documents the `ruki` language. `ruki` is a small language for finding, creating, updating, and deleting tikis, with SQL-like statements and trigger rules.
|
||||
|
||||
## Quick start
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
|
||||
## Overview
|
||||
|
||||
This page describes the operators and built-in functions available in Ruki.
|
||||
This page describes the operators and built-in functions available in `ruki`.
|
||||
|
||||
## Operator precedence and associativity
|
||||
|
||||
|
|
@ -201,7 +201,7 @@ create title="x" dependsOn=dependsOn + tags
|
|||
|
||||
## Built-in functions
|
||||
|
||||
Ruki has these built-ins:
|
||||
`ruki` has these built-ins:
|
||||
|
||||
| Name | Result type | Arguments | Notes |
|
||||
|---|---|---|---|
|
||||
|
|
@ -246,7 +246,7 @@ after update where new.status = "in progress" run("echo hello")
|
|||
|
||||
## Shell-related forms
|
||||
|
||||
Ruki includes two shell-related forms:
|
||||
`ruki` includes two shell-related forms:
|
||||
|
||||
- `call(...)` as a string-returning expression
|
||||
- `run(...)` as an `after`-trigger action
|
||||
|
|
|
|||
|
|
@ -11,18 +11,18 @@
|
|||
|
||||
## Overview
|
||||
|
||||
This page is a practical introduction to the Ruki language. It covers the main statement forms, the conditions they use, and the trigger rules that let you block or react to changes.
|
||||
This page is a practical introduction to the `ruki` language. It covers the main statement forms, the conditions they use, and the trigger rules that let you block or react to changes.
|
||||
|
||||
## Mental model
|
||||
|
||||
Ruki has two top-level forms:
|
||||
`ruki` has two top-level forms:
|
||||
|
||||
- Statements: `select`, `create`, `update`, and `delete`
|
||||
- Triggers: `before` or `after` rules attached to `create`, `update`, or `delete`
|
||||
|
||||
Statements read and change tiki fields such as `status`, `type`, `tags`, `dependsOn`, `priority`, and `due`. Triggers use the same fields and conditions, but add `before` or `after` timing around `create`, `update`, or `delete`.
|
||||
|
||||
The simplest way to read Ruki is:
|
||||
The simplest way to read `ruki` is:
|
||||
|
||||
- `select` filters tikis
|
||||
- `create` assigns fields for a new tiki
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
|
||||
## Overview
|
||||
|
||||
This page explains how Ruki statements, triggers, conditions, and expressions behave.
|
||||
This page explains how `ruki` statements, triggers, conditions, and expressions behave.
|
||||
|
||||
## Statement semantics
|
||||
|
||||
|
|
|
|||
|
|
@ -12,11 +12,11 @@
|
|||
|
||||
## Overview
|
||||
|
||||
This page describes Ruki syntax. It starts with tokens and then shows the grammar for statements, triggers, conditions, and expressions.
|
||||
This page describes `ruki` syntax. It starts with tokens and then shows the grammar for statements, triggers, conditions, and expressions.
|
||||
|
||||
## Lexical structure
|
||||
|
||||
Ruki uses these token classes:
|
||||
`ruki` uses these token classes:
|
||||
|
||||
- comments: `--` to end of line
|
||||
- whitespace: ignored between tokens
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ after delete
|
|||
|
||||
Triggers are defined in `workflow.yaml` under the `triggers:` key. Each entry has two fields:
|
||||
|
||||
- `ruki` — the trigger rule in Ruki syntax (required)
|
||||
- `ruki` — the trigger rule in `ruki` syntax (required)
|
||||
- `description` — an optional label
|
||||
|
||||
```yaml
|
||||
|
|
@ -309,7 +309,7 @@ Time triggers are parsed and validated at startup alongside event triggers. A pa
|
|||
|
||||
Triggers are loaded during application startup, after the store is initialized but before controllers are created.
|
||||
|
||||
- Each trigger definition is parsed with the ruki parser. A parse error in any trigger is **fail-fast**: the application will not start, and the error message identifies the failing trigger by its `description` (or by index if no description is set).
|
||||
- Each trigger definition is parsed with the `ruki` parser. A parse error in any trigger is **fail-fast**: the application will not start, and the error message identifies the failing trigger by its `description` (or by index if no description is set).
|
||||
- If no `triggers:` section is found in any workflow file, zero triggers are loaded and the app starts normally.
|
||||
- Successfully loaded triggers are logged with a count at startup.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,11 +13,11 @@
|
|||
|
||||
## Overview
|
||||
|
||||
This page explains the value types used in Ruki. You do not write types explicitly. Ruki works them out from the values, expressions, built-in functions, and tiki fields you use.
|
||||
This page explains the value types used in `ruki`. You do not write types explicitly. `ruki` works them out from the values, expressions, built-in functions, and tiki fields you use.
|
||||
|
||||
## Value types
|
||||
|
||||
Ruki uses these value types:
|
||||
`ruki` uses these value types:
|
||||
|
||||
| Type | Meaning |
|
||||
|---|---|
|
||||
|
|
@ -37,7 +37,7 @@ Ruki uses these value types:
|
|||
|
||||
## Field catalog
|
||||
|
||||
The workflow field catalog exposes these fields to Ruki:
|
||||
The workflow field catalog exposes these fields to `ruki`:
|
||||
|
||||
| Field | Type |
|
||||
|---|---|
|
||||
|
|
|
|||
|
|
@ -13,13 +13,13 @@
|
|||
|
||||
## Overview
|
||||
|
||||
This page explains the errors you can get in Ruki. It covers syntax errors, unknown fields, type mismatches, invalid enum values, unsupported operators, and invalid trigger structure.
|
||||
This page explains the errors you can get in `ruki`. It covers syntax errors, unknown fields, type mismatches, invalid enum values, unsupported operators, and invalid trigger structure.
|
||||
|
||||
## Validation layers
|
||||
|
||||
|
||||
|
||||
Ruki has two distinct failure stages:
|
||||
`ruki` has two distinct failure stages:
|
||||
|
||||
1. Parse-time failures
|
||||
2. Validation-time failures
|
||||
|
|
|
|||
|
|
@ -194,11 +194,11 @@ When asked to remove or clear a due date:
|
|||
|
||||
### Query by due date
|
||||
|
||||
Users can filter tasks by due date in the TUI using filter expressions:
|
||||
- `due = '2026-04-01'` - exact match
|
||||
- `due < '2026-04-01'` - before date
|
||||
- `due < NOW` - overdue tasks
|
||||
- `due - NOW < 7day` - due within 7 days
|
||||
Users can filter tasks by due date in the TUI using `ruki` select statements:
|
||||
- `select where due = 2026-04-01` - exact match
|
||||
- `select where due < 2026-04-01` - before date
|
||||
- `select where due < now()` - overdue tasks
|
||||
- `select where due - now() < 7day` - due within 7 days
|
||||
|
||||
### Validation
|
||||
|
||||
|
|
|
|||
|
|
@ -57,17 +57,16 @@ views:
|
|||
lanes:
|
||||
- name: Backlog
|
||||
columns: 4
|
||||
filter: status = 'backlog' and type != 'epic'
|
||||
filter: select where status = "backlog" and type != "epic" order by priority, id
|
||||
actions:
|
||||
- key: "b"
|
||||
label: "Add to board"
|
||||
action: status = 'ready'
|
||||
sort: Priority, ID
|
||||
action: update where id = id() set status="ready"
|
||||
```
|
||||
|
||||
that translates to - show all tikis in the status `backlog`, sort by priority and then by ID arranged visually in 4 columns in a single lane.
|
||||
The `actions` section defines a keyboard shortcut `b` that moves the selected tiki to the board by setting its status to `ready`
|
||||
You define the name, caption colors, hotkey, tiki filter and sorting. Save this into a `workflow.yaml` file in the config directory
|
||||
You define the name, caption colors, hotkey, and `ruki` expressions for filtering and actions. Save this into a `workflow.yaml` file in the config directory
|
||||
|
||||
Likewise the documentation is just a plugin:
|
||||
|
||||
|
|
@ -98,28 +97,27 @@ name: Custom
|
|||
foreground: "#5fff87"
|
||||
background: "#005f00"
|
||||
key: "F4"
|
||||
sort: Priority, Title
|
||||
lanes:
|
||||
- name: Ready
|
||||
columns: 1
|
||||
width: 20
|
||||
filter: status = 'ready'
|
||||
action: status = 'ready'
|
||||
filter: select where status = "ready" order by priority, title
|
||||
action: update where id = id() set status="ready"
|
||||
- name: In Progress
|
||||
columns: 1
|
||||
width: 30
|
||||
filter: status = 'in_progress'
|
||||
action: status = 'in_progress'
|
||||
filter: select where status = "inProgress" order by priority, title
|
||||
action: update where id = id() set status="inProgress"
|
||||
- name: Review
|
||||
columns: 1
|
||||
width: 30
|
||||
filter: status = 'review'
|
||||
action: status = 'review'
|
||||
filter: select where status = "review" order by priority, title
|
||||
action: update where id = id() set status="review"
|
||||
- name: Done
|
||||
columns: 1
|
||||
width: 20
|
||||
filter: status = 'done'
|
||||
action: status = 'done'
|
||||
filter: select where status = "done" order by priority, title
|
||||
action: update where id = id() set status="done"
|
||||
```
|
||||
|
||||
### Lane width
|
||||
|
|
@ -147,129 +145,90 @@ that apply to the currently selected tiki via a keyboard shortcut. These shortcu
|
|||
actions:
|
||||
- key: "b"
|
||||
label: "Add to board"
|
||||
action: status = 'ready'
|
||||
action: update where id = id() set status="ready"
|
||||
- key: "a"
|
||||
label: "Assign to me"
|
||||
action: assignee = CURRENT_USER
|
||||
action: update where id = id() set assignee=user()
|
||||
```
|
||||
|
||||
Each action has:
|
||||
- `key` - a single printable character used as the keyboard shortcut
|
||||
- `label` - description shown in the header
|
||||
- `action` - an action expression (same syntax as lane actions, see below)
|
||||
- `action` - a `ruki` `update` statement (same syntax as lane actions, see below)
|
||||
|
||||
When the shortcut key is pressed, the action is applied to the currently selected tiki.
|
||||
For example, pressing `b` in the Backlog plugin changes the selected tiki's status to `ready`, effectively moving it to the board.
|
||||
|
||||
### Action expression
|
||||
### ruki expressions
|
||||
|
||||
The `action: status = 'backlog'` statement in a plugin is an action to be run when a tiki is moved into the lane. Here `=`
|
||||
means `assign` so status is assigned `backlog` when the tiki is moved. Likewise you can manipulate tags using `+-` (add)
|
||||
or `-=` (remove) expressions. For example, `tags += [idea, UI]` adds `idea` and `UI` tags to a tiki
|
||||
Plugin filters, lane actions, and plugin actions all use the `ruki` language. Filters use `select` statements and actions use `update` statements.
|
||||
|
||||
#### Supported Fields
|
||||
#### Filter (select)
|
||||
|
||||
- `status` - set workflow status (must be a key defined in `workflow.yaml` statuses)
|
||||
- `type` - set task type: `story`, `bug`, `spike`, `epic` (case-insensitive)
|
||||
- `priority` - set numeric priority (1-5)
|
||||
- `points` - set numeric points (0 or positive, up to max points)
|
||||
- `assignee` - set assignee string
|
||||
- `tags` - add/remove tags (list)
|
||||
The `filter` field uses a `ruki` `select` statement to determine which tikis appear in a lane. Sorting is part of the select — use `order by` to control display order.
|
||||
|
||||
#### Operators
|
||||
```sql
|
||||
-- basic filter with sort
|
||||
select where status = "backlog" and type != "epic" order by priority, id
|
||||
|
||||
- `=` assigns a value to `status`, `type`, `priority`, `points`, `assignee`
|
||||
- `+=` adds tags, `-=` removes tags
|
||||
- multiple operations are separated by commas: `status=done, tags+=[moved]`
|
||||
-- recent items, most recent first
|
||||
select where now() - updatedAt < 24hour order by updatedAt desc
|
||||
|
||||
#### Literals
|
||||
-- multiple conditions
|
||||
select where type = "epic" and status = "backlog" and priority > 1 order by priority, points desc
|
||||
|
||||
- strings can be quoted (`'in_progress'`, `"alex"`) or bare (`done`, `alex`)
|
||||
- use quotes when the value has spaces
|
||||
- integers are used for `priority` and `points`
|
||||
- tag lists use brackets: `tags += [ui, frontend]`
|
||||
- `CURRENT_USER` assigns the current git user to `assignee`
|
||||
- example: `assignee = CURRENT_USER`
|
||||
|
||||
### Filter expression
|
||||
|
||||
The `filter: status = 'backlog'` statement in a plugin is a filter expression that determines which tikis appear in the view.
|
||||
|
||||
#### Supported Fields
|
||||
|
||||
You can filter on these task fields:
|
||||
- `id` - Task identifier (e.g., 'TIKI-m7n2xk')
|
||||
- `title` - Task title text (case-insensitive)
|
||||
- `type` - Task type: 'story', 'bug', 'spike', or 'epic' (case-insensitive)
|
||||
- `status` - Workflow status (must match a key defined in `workflow.yaml` statuses)
|
||||
- `assignee` - Assigned user (case-insensitive)
|
||||
- `priority` - Numeric priority value
|
||||
- `points` - Story points estimate
|
||||
- `tags` (or `tag`) - List of tags (case-insensitive)
|
||||
- `createdAt` - Creation timestamp
|
||||
- `updatedAt` - Last update timestamp
|
||||
|
||||
All string comparisons are case-insensitive.
|
||||
|
||||
#### Operators
|
||||
|
||||
- **Comparison**: `=` (or `==`), `!=`, `>`, `>=`, `<`, `<=`
|
||||
- **Logical**: `AND`, `OR`, `NOT` (precedence: NOT > AND > OR)
|
||||
- **Membership**: `IN`, `NOT IN` (check if value in list using `[val1, val2]`)
|
||||
- **Grouping**: Use parentheses `()` to control evaluation order
|
||||
|
||||
#### Literals and Special Values
|
||||
|
||||
**Special expressions**:
|
||||
- `CURRENT_USER` - Resolves to the current git user (works in comparisons and IN lists)
|
||||
- `NOW` - Current timestamp
|
||||
|
||||
**Time expressions**:
|
||||
- `NOW - UpdatedAt` - Time elapsed since update
|
||||
- `NOW - CreatedAt` - Time since creation
|
||||
- Duration units: `min`/`minutes`, `hour`/`hours`, `day`/`days`, `week`/`weeks`, `month`/`months`
|
||||
- Examples: `2hours`, `14days`, `3weeks`, `60min`, `1month`
|
||||
- Operators: `+` (add), `-` (subtract or compute duration)
|
||||
|
||||
**Special tag semantics**:
|
||||
- `tags IN ['ui', 'frontend']` matches if ANY task tag matches ANY list value
|
||||
- This allows intersection testing across tag arrays
|
||||
|
||||
#### Examples
|
||||
|
||||
```text
|
||||
# Multiple statuses
|
||||
status = 'ready' OR status = 'in_progress'
|
||||
|
||||
# With tags
|
||||
tags IN ['frontend', 'urgent']
|
||||
|
||||
# High priority bugs
|
||||
type = 'bug' AND priority = 0
|
||||
|
||||
# Features and ideas assigned to me
|
||||
(type = 'feature' OR tags IN ['idea']) AND assignee = CURRENT_USER
|
||||
|
||||
# Unassigned large tasks
|
||||
assignee = '' AND points >= 5
|
||||
|
||||
# Recently created tasks not in backlog
|
||||
(NOW - CreatedAt < 2hours) AND status != 'backlog'
|
||||
-- assigned to me
|
||||
select where assignee = user() order by priority
|
||||
```
|
||||
|
||||
### Sorting
|
||||
#### Action (update)
|
||||
|
||||
The `sort` field determines the order in which tikis appear in the view. You can sort by one or more fields, and control the direction (ascending or descending).
|
||||
The `action` field uses a `ruki` `update` statement. In plugin context, `id()` refers to the currently selected tiki.
|
||||
|
||||
#### Sort Syntax
|
||||
```sql
|
||||
-- set status on move
|
||||
update where id = id() set status="ready"
|
||||
|
||||
```text
|
||||
sort: Field1, Field2 DESC, Field3
|
||||
-- set multiple fields
|
||||
update where id = id() set status="backlog" priority=2
|
||||
|
||||
-- assign to current user
|
||||
update where id = id() set assignee=user()
|
||||
```
|
||||
|
||||
#### Examples
|
||||
#### Supported fields
|
||||
|
||||
```text
|
||||
# Sort by creation time descending (recent first), then priority, then title
|
||||
sort: CreatedAt DESC, Priority, Title
|
||||
```
|
||||
- `id` - task identifier (e.g., "TIKI-M7N2XK")
|
||||
- `title` - task title text
|
||||
- `type` - task type: "story", "bug", "spike", or "epic"
|
||||
- `status` - workflow status (must match a key defined in `workflow.yaml` statuses)
|
||||
- `assignee` - assigned user
|
||||
- `priority` - numeric priority value (1-5)
|
||||
- `points` - story points estimate
|
||||
- `tags` - list of tags
|
||||
- `dependsOn` - list of dependency tiki IDs
|
||||
- `due` - due date (YYYY-MM-DD format)
|
||||
- `recurrence` - recurrence pattern (cron format)
|
||||
- `createdAt` - creation timestamp
|
||||
- `updatedAt` - last update timestamp
|
||||
|
||||
#### Conditions
|
||||
|
||||
- **Comparison**: `=`, `!=`, `>`, `>=`, `<`, `<=`
|
||||
- **Logical**: `and`, `or`, `not` (precedence: not > and > or)
|
||||
- **Membership**: `"value" in field`, `status not in ["done", "cancelled"]`
|
||||
- **Emptiness**: `assignee is empty`, `tags is not empty`
|
||||
- **Quantifiers**: `dependsOn any status != "done"`, `dependsOn all status = "done"`
|
||||
- **Grouping**: parentheses `()` to control evaluation order
|
||||
|
||||
#### Literals and built-ins
|
||||
|
||||
- Strings: double-quoted (`"ready"`, `"alex"`)
|
||||
- Integers: `1`, `5`
|
||||
- Dates: `2026-03-25`
|
||||
- Durations: `2hour`, `14day`, `3week`, `1month`
|
||||
- Lists: `["bug", "frontend"]`
|
||||
- `user()` — current git user
|
||||
- `now()` — current timestamp
|
||||
- `id()` — currently selected tiki (in plugin context)
|
||||
- `count(select where ...)` — count matching tikis
|
||||
|
|
|
|||
Loading…
Reference in a new issue