Compare commits

...

16 Commits

Author SHA1 Message Date
d93c0cf348 Add the ability to hide tasks until a certain date. 2021-08-24 10:56:47 -05:00
9606e71cec Add support for binary properties via data URIs. 2021-06-07 18:34:41 -05:00
98f4dda1ad Reset terminal attributes after printing single issues. 2021-02-01 07:41:01 -06:00
393be347c9 Default list command no longer includes Done issues. 2020-11-12 14:50:43 -06:00
f8fed9d937 Allow filtering by issue tags. 2020-11-12 07:37:22 -06:00
ef16eafd48 Update to address changes for Nim 1.x (currently 1.4.0). 2020-11-12 04:05:04 -06:00
4af0d09356 Remove stuff in the README that I don't understand. 🤷 2020-10-02 12:33:51 -05:00
071c4b66e5 Explicitly document list contexts subcommand. Sort listed contexts alphabetically. 2020-10-02 12:13:22 -05:00
57a3af4f2f When moving issues, create target directories if they do not already exist. 2020-07-06 11:47:31 -05:00
08b9df2086 Update to reflect changes in Nim stdlib in v1.2. 2020-07-06 11:39:57 -05:00
339e88cddd list contexts command now prints both the listeral context value and the display name. 2020-05-05 09:40:08 -05:00
0a2249018b Add ptk integration option as a command-line switch. 2020-04-16 10:22:56 -05:00
ec3008937d Add README, bugfix CLI configuration. 2020-03-23 09:18:44 -05:00
10fcc34ea2 Update nim-cli-util dependency version to get a fix to the queryParamsToCli function. 2020-03-23 08:27:30 -05:00
4127fbe41c Better PTK integration.
- Now includes the context as a PTK tag (if present).
- Add the PIT ID to the PTK notes.
2020-03-16 09:39:17 -05:00
0671d7728e Add helper to update version easily. 2020-02-16 00:57:58 -06:00
6 changed files with 285 additions and 52 deletions

138
README.md Normal file
View File

@ -0,0 +1,138 @@
# Personal Issue Tracker
This is [Jonathan Bernard's](mailto:jonathan@jdbernard.com) personal issue
tracker. In it's current form it is essentially a way to keep an curated list of
TODO's, organizing them by workflow category (todo, todo-today, dormant, etc.)
and context (Personal, Work, etc.).
## Categories
`pit` organizes issues into the following workflow categories:
- `current` - actively in progress
- `todo` - to be addressed in the future
- `todo-today` - chosen to be addressed today
- `pending` - blocked by some third party
- `dormant` - long-term things I don't want to forget but don't need in front
of me every day.
- `done`
In my typical workflow the `todo` category serves as a collection point for
things I want to keep track of. Then on a a daily basis I review issues in the
`todo` category and move a selection to the `todo-today` category. I also try
to keep the total number of issues in the `todo` below about a dozen. If there
are more than a dozen things in my `todo` category I will identify the lowest
priority items and move them to the `dormant` category.
## Issue Properties
`pit` allows arbitrary properties to be attached to issues in the form of
key-value pairs. On the command line these can be provided via the `-p` or
`--properties` parameter in the form
`-p <prop1Name>:<prop1Value>;<prop2Name>:<prop2Value>[;...]`
There are a couple of properties that pit will recognize automatically:
- `context`: the context organization feature is implemented using issue
properties.
- `created`: `pit` uses this property to timestamp an issue when it is created.
- `completed`: `pit` uses this property to timestamp an issue when it is moved
to the `done` category.
- `pending`: `pit` looks to this property to provide extra information about
issues in the `pending` category. Typically I use this to note who or what is
blocking the issue and why.
Some other common properties I use are:
- `resolution`: for short notes about why an issue was moved to `done`,
especially if it the action wasn't taken or if it is not completely clear
that this issue was completed.
## Configuration Options
`pit` allows configuration via command-line options and via a configuration
file. There is some overlap between the two methods of configuring `pit`, but
it is not a complete mapping.
### Config File
`pit` looks for a JSON configuration file in the following places (in order):
1. From a file path passed on the command line via the `--config <cfgFile>` parameter,
2. `./.pitrc`, in the current working directory,
3. From a file path set in the `PITRC` environment variable.
4. `$HOME/.pitrc`, in the user's home directory.
#### Sample Config File
This example illustrates all of the possible configuration options.
```json
{
"api": {
"apiKeys": [
"50cdcb660554e2d50fd88bd40b6579717bf00643f6ff57f108baf16c8c083f77",
"e4fc1aac49fc1f2f7f4ca6b1f04d41a4ccdd58e13bb53b41da97703d47267ceb",
]
},
"cli": {
"defaultContext": "personal",
"verbose": false,
"termWidth": 120,
"triggerPtk": true
},
"contexts": {
"nla-music": "New Life Music",
"nla-youth-band": "New Life Youth Band",
"acn": "Accenture",
"hff": "Hope Family Fellowship"
},
"tasksDir": "/mnt/c/Users/Jonathan Bernard/synced/tasks"
}
```
#### Explanation of configurable options.
In general, options supplied on the CLI directly will override options supplied
in the configuration file. All options are optional unless stated otherwise.
* `api`: configuration options specific to the API service.
- `apiKeys`: a list of Bearer tokens accepted by the API for the purpose of
authenticating API requests.
* `cli`: configuration options specific to the CLI.
- `defaultContext`: if present all invokations to the CLI will
be in this context. This is like adding a `--context <defaultContext>`
parameter to every CLI invocation. Any actual `--context` parameter will
override this value.
- `verbose`: Show issue details when listing issues (same as
`--verbose` flag).
- `termWidth`: Set the expected width of the terminal (for wrapping text).
- `triggerPtk`: If set to `true`, invoke the `ptk` command to start and stop
timers when issues move to the `current` and `done` categories
respectively.
* `contexts`: `pit` allows issues to be organized into different contexts via
a `context` property on the issue. The CLI groups issues according to
context. When printing contexts the CLI will take the value from the issues'
`context` properties and capatalize it. In some cases you may wish to have a
different display value for a context. I like to use abbreviations for long
context names to reduce the need to type, `hff` for "Hope Family Fellowship",
for example. The `contexts` config option allows you to provide a map of
context values to context display names See the sample file below for an
example.
Note that this mapping does not have to have entries for all contexts, only
those you wish to provide with an alternate display form. For example, in the
configuration sample above the default context is `personal`, a value not
present in the `contexts` configuration. `personal` will be displayed as
"Personal"; it does not need an alternate display name.
* `tasksDir` **required**: a file path to the root directory for the issue
repository (same as `--tasks-dir` CLI parameter).

View File

@ -1,8 +1,6 @@
# Package
include "src/pitpkg/version.nim"
version = PIT_VERSION
version = "4.13.0"
author = "Jonathan Bernard"
description = "Personal issue tracker."
license = "MIT"
@ -11,8 +9,18 @@ bin = @["pit", "pit_api"]
# Dependencies
requires @[ "nim >= 0.19.0", "docopt 0.6.8", "jester 0.4.1", "uuids 0.1.10" ]
requires @[
"nim >= 1.4.0",
"docopt 0.6.8",
"jester 0.5.0",
"uuids 0.1.10",
requires "https://git.jdb-labs.com/jdb/nim-cli-utils.git >= 0.6.1"
requires "https://git.jdb-labs.com/jdb/nim-lang-utils.git >= 0.4.0"
requires "https://git.jdb-labs.com/jdb/nim-time-utils.git >= 0.4.0"
"https://git.jdb-software.com/jdb/nim-cli-utils.git >= 0.6.4",
"https://git.jdb-software.com/jdb/nim-lang-utils.git >= 0.4.0",
"https://git.jdb-software.com/jdb/nim-time-utils.git >= 0.4.0",
"https://git.jdb-software.com/jdb/nim-data-uri.git >= 1.0.0",
"https://git.jdb-software.com/jdb/update-nim-package-version"
]
task updateVersion, "Update the version of this package.":
exec "update_nim_package_version pit 'src/pitpkg/version.nim'"

View File

@ -1,11 +1,11 @@
## Personal Issue Tracker CLI interface
## ====================================
import cliutils, docopt, json, logging, options, os, ospaths, sequtils,
tables, terminal, times, timeutils, unicode, uuids
import algorithm, cliutils, data_uri, docopt, json, logging, options, os,
sequtils, std/wordwrap, tables, terminal, times, timeutils, unicode, uuids
from nre import re
import strutils except capitalize, strip, toUpper, toLower
import strutils except alignLeft, capitalize, strip, toUpper, toLower
import pitpkg/private/libpit
export libpit
@ -36,6 +36,7 @@ proc initContext(args: Table[string, Value]): CliContext =
let cliCfg = CombinedConfig(docopt: args, json: cliJson)
result = CliContext(
cfg: pitCfg,
contexts: pitCfg.contexts,
defaultContext:
if not cliJson.hasKey("defaultContext"): none(string)
@ -43,12 +44,12 @@ proc initContext(args: Table[string, Value]): CliContext =
verbose: parseBool(cliCfg.getVal("verbose", "false")) and not args["--quiet"],
issues: newTable[IssueState, seq[Issue]](),
tasksDir: pitCfg.tasksDir,
termWidth: parseInt(cliCfg.getVal("term-width", "80")),
termWidth: parseInt(cliCfg.getVal("termWidth", "80")),
triggerPtk: cliJson.getOrDefault("triggerPtk").getBool(false))
proc getIssueContextDisplayName(ctx: CliContext, context: string): string =
if not ctx.contexts.hasKey(context):
if context.isNilOrWhitespace: return "<default>"
if context.isEmptyOrWhitespace: return "<default>"
else: return context.capitalize()
return ctx.contexts[context]
@ -66,15 +67,17 @@ proc formatIssue(ctx: CliContext, issue: Issue): string =
result &= "--------".withColor(fgBlack, true) & "\n"
if not issue.details.isNilOrWhitespace:
if not issue.details.isEmptyOrWhitespace:
result &= issue.details.strip.withColor(fgCyan) & "\n"
result &= termReset
proc formatSectionIssue(ctx: CliContext, issue: Issue, width: int, indent = "",
verbose = false): string =
result = ""
var showDetails = not issue.details.isNilOrWhitespace and verbose
var showDetails = not issue.details.isEmptyOrWhitespace and verbose
var prefixLen = 0
var summaryIndentLen = indent.len + 7
@ -82,7 +85,7 @@ proc formatSectionIssue(ctx: CliContext, issue: Issue, width: int, indent = "",
if issue.hasProp("delegated-to"): prefixLen += issue["delegated-to"].len + 2 # space for the ':' and ' '
# Wrap and write the summary.
var wrappedSummary = ("+".repeat(prefixLen) & issue.summary).wordWrap(width - summaryIndentLen).indent(summaryIndentLen)
var wrappedSummary = ("+".repeat(prefixLen) & issue.summary).wrapWords(width - summaryIndentLen).indent(summaryIndentLen)
wrappedSummary = wrappedSummary[(prefixLen + summaryIndentLen)..^1]
@ -102,7 +105,7 @@ proc formatSectionIssue(ctx: CliContext, issue: Issue, width: int, indent = "",
if issue.hasProp("pending"):
let startIdx = "Pending: ".len
var pendingText = issue["pending"].wordWrap(width - startIdx - summaryIndentLen)
var pendingText = issue["pending"].wrapWords(width - startIdx - summaryIndentLen)
.indent(startIdx)
pendingText = ("Pending: " & pendingText[startIdx..^1]).indent(summaryIndentLen)
result &= "\n" & pendingText.withColor(fgCyan)
@ -198,6 +201,10 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
if state.isSome:
ctx.loadIssues(state.get)
if filter.isSome: ctx.filterIssues(filter.get)
if state.get == Done and showToday:
ctx.issues[Done] = ctx.issues[Done].filterIt(
it.hasProp("completed") and
sameDay(getTime().local, it.getDateTime("completed")))
stdout.write ctx.formatSection(ctx.issues[state.get], state.get, "", verbose)
return
@ -220,20 +227,17 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
if ctx.issues.hasKey(s) and ctx.issues[s].len > 0:
stdout.write ctx.formatSection(ctx.issues[s], s, indent, verbose)
if ctx.issues.hasKey(Done):
let doneIssues = ctx.issues[Done].filterIt(
it.hasProp("completed") and
sameDay(getTime().local, it.getDateTime("completed")))
if doneIssues.len > 0:
stdout.write ctx.formatSection(doneIssues, Done, indent, verbose)
# Future items
if future:
if today: ctx.writeHeader("Future")
for s in [Pending, Todo]:
if ctx.issues.hasKey(s) and ctx.issues[s].len > 0:
stdout.write ctx.formatSection(ctx.issues[s], s, indent, verbose)
let visibleIssues = ctx.issues[s].filterIt(
not (it.hasProp("hide-until") and
it.getDateTime("hide-until") > getTime().local))
stdout.write ctx.formatSection(visibleIssues, s, indent, verbose)
when isMainModule:
@ -241,14 +245,18 @@ when isMainModule:
let doc = """
Usage:
pit ( new | add) <summary> [<state>] [options]
pit list [<listable>] [options]
pit list contexts [options]
pit list [<stateOrId>] [options]
pit ( start | done | pending | todo-today | todo | suspend ) <id>... [options]
pit edit <ref>...
pit edit <ref>... [options]
pit tag <id>... [options]
pit untag <id>... [options]
pit reorder <state>
pit reorder <state> [options]
pit delegate <id> <delegated-to>
pit ( delete | rm ) <id>...
pit hide-until <id> <date> [options]
pit ( delete | rm ) <id>... [options]
pit add-binary-property <id> <propName> <propSource> [options]
pit get-binary-property <id> <propName> <propDest> [options]
Options:
@ -287,6 +295,8 @@ Options:
configured in the .pitrc file)
--term-width <width> Manually set the terminal width to use.
--ptk Enable PTK integration for this command.
"""
logging.addHandler(newConsoleLogger())
@ -401,16 +411,30 @@ Options:
if targetState == Done: issue["completed"] = getTime().local.formatIso8601
issue.changeState(ctx.tasksDir, targetState)
if ctx.triggerPtk:
if ctx.triggerPtk or args["--ptk"]:
if targetState == Current:
let issue = ctx.tasksDir.loadIssueById($(args["<id>"][0]))
var cmd = "ptk start "
if issue.tags.len > 0: cmd &= "-g \"" & issue.tags.join(",") & "\""
var cmd = "ptk start"
if issue.tags.len > 0 or issue.properties.hasKey("context"):
let tags = concat(
issue.tags,
if issue.properties.hasKey("context"): @[issue.properties["context"]]
else: @[]
)
cmd &= " -g \"" & tags.join(",") & "\""
cmd &= " -n \"pit-id: " & $issue.id & "\""
cmd &= " \"" & issue.summary & "\""
discard execShellCmd(cmd)
elif targetState == Done or targetState == Pending:
discard execShellCmd("ptk stop")
elif args["hide-until"]:
let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
issue.setDateTime("hide-until", parseDate($args["<date>"]))
issue.store()
elif args["delegate"]:
let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
@ -455,6 +479,10 @@ Options:
filter.properties["context"] = ctx.defaultContext.get
filterOption = some(filter)
if args["--tags"]:
filter.hasTags = ($args["--tags"]).split(',')
filterOption = some(filter)
# Finally, if the "context" is "all", don't filter on context
if filter.properties.hasKey("context") and
filter.properties["context"] == "all":
@ -465,11 +493,10 @@ Options:
var stateOption = none(IssueState)
var issueIdOption = none(string)
if args["<listable>"]:
if $args["<listable>"] == "contexts": listContexts = true
else:
try: stateOption = some(parseEnum[IssueState]($args["<listable>"]))
except: issueIdOption = some($args["<listable>"])
if args["contexts"]: listContexts = true
elif args["<stateOrId>"]:
try: stateOption = some(parseEnum[IssueState]($args["<stateOrId>"]))
except: issueIdOption = some($args["<stateOrId>"])
# List the known contexts
if listContexts:
@ -480,7 +507,13 @@ Options:
if issue.hasProp("context") and not uniqContexts.contains(issue["context"]):
uniqContexts.add(issue["context"])
for c in uniqContexts: stdout.writeLine(c)
let maxLen = foldl(uniqContexts,
if a.len > b.len: a
else: b
).len
for c in uniqContexts.sorted:
stdout.writeLine(c.alignLeft(maxLen+2) & ctx.getIssueContextDisplayName(c))
# List a specific issue
elif issueIdOption.isSome:
@ -494,6 +527,33 @@ Options:
showBoth or args["--future"],
ctx.verbose)
elif args["add-binary-property"]:
let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
let propIn =
if $(args["<propSource>"]) == "-": stdin
else: open($(args["<propSource>"]))
try: issue[$(args["<propName>"])] = encodeAsDataUri(readAll(propIn))
finally: close(propIn)
issue.store()
elif args["get-binary-property"]:
let issue = ctx.tasksDir.loadIssueById($(args["<id>"]))
if not issue.hasProp($(args["<propName>"])):
raise newException(Exception,
"issue " & ($issue.id)[0..<6] & " has no property name '" &
$(args["<propName>"]) & "'")
let propOut =
if $(args["<propDest>"]) == "-": stdout
else: open($(args["<propDest>"]), fmWrite)
try: write(propOut, decodeDataUri(issue[$(args["<propName>"])]))
finally: close(propOut)
except:
fatal "pit: " & getCurrentExceptionMsg()
#raise getCurrentException()

View File

@ -20,7 +20,7 @@ proc raiseEx(reason: string): void = raise newException(Exception, reason)
template halt(code: HttpCode,
headers: RawHeaders,
content: string): typed =
content: string): void =
## Immediately replies with the specified request. This means any further
## code will not be executed after calling this template in the current
## route.

View File

@ -1,4 +1,4 @@
import cliutils, docopt, json, logging, langutils, options, os, ospaths,
import cliutils, docopt, json, logging, langutils, options, os,
sequtils, strutils, tables, times, timeutils, uuids
from nre import find, match, re, Regex
@ -22,6 +22,7 @@ type
IssueFilter* = ref object
completedRange*: Option[tuple[b, e: DateTime]]
fullMatch*, summaryMatch*: Option[Regex]
hasTags*: seq[string]
properties*: TableRef[string, string]
PitConfig* = ref object
@ -49,6 +50,7 @@ proc `[]`*(issue: Issue, key: string): string =
proc `[]=`*(issue: Issue, key: string, value: string) =
issue.properties[key] = value
## Issue property accessors
proc hasProp*(issue: Issue, key: string): bool =
return issue.properties.hasKey(key)
@ -62,11 +64,13 @@ proc getDateTime*(issue: Issue, key: string, default: DateTime): DateTime =
proc setDateTime*(issue: Issue, key: string, dt: DateTime) =
issue.properties[key] = dt.formatIso8601
## Issue filtering
proc initFilter*(): IssueFilter =
result = IssueFilter(
completedRange: none(tuple[b, e: DateTime]),
fullMatch: none(Regex),
summaryMatch: none(Regex),
hasTags: @[],
properties: newTable[string, string]())
proc propsFilter*(props: TableRef[string, string]): IssueFilter =
@ -89,6 +93,10 @@ proc fullMatchFilter*(pattern: string): IssueFilter =
result = initFilter()
result.fullMatch = some(re("(?i)" & pattern))
proc hasTagsFilter*(tags: seq[string]): IssueFilter =
result = initFilter()
result.hasTags = tags
proc groupBy*(issues: seq[Issue], propertyKey: string): TableRef[string, seq[Issue]] =
result = newTable[string, seq[Issue]]()
for i in issues:
@ -97,6 +105,23 @@ proc groupBy*(issues: seq[Issue], propertyKey: string): TableRef[string, seq[Iss
result[key].add(i)
## Parse and format dates
const DATE_FORMATS = [
"MM/dd",
"MM-dd",
"yyyy-MM-dd",
"yyyy/MM/dd",
"yyyy-MM-dd'T'hh:mm:ss"
]
proc parseDate*(d: string): DateTime =
var errMsg = ""
for df in DATE_FORMATS:
try: return d.parse(df)
except:
errMsg &= "\n\tTried " & df & " with " & d
continue
raise newException(ValueError, "Unable to parse input as a date: " & d & errMsg)
## Parse and format issues
proc fromStorageFormat*(id: string, issueTxt: string): Issue =
type ParseState = enum ReadingSummary, ReadingProps, ReadingDetails
@ -120,7 +145,7 @@ proc fromStorageFormat*(id: string, issueTxt: string): Issue =
of ReadingProps:
# Ignore empty lines
if line.isNilOrWhitespace: continue
if line.isEmptyOrWhitespace: continue
# Look for the sentinal to start parsing as detail lines
if line == "--------":
@ -147,9 +172,9 @@ proc toStorageFormat*(issue: Issue, withComments = false): string =
lines.add(issue.summary)
if withComments: lines.add("# Properties (\"key:value\" per line):")
for key, val in issue.properties:
if not val.isNilOrWhitespace: lines.add(key & ": " & val)
if not val.isEmptyOrWhitespace: lines.add(key & ": " & val)
if issue.tags.len > 0: lines.add("tags: " & issue.tags.join(","))
if not isNilOrWhitespace(issue.details) or withComments:
if not isEmptyOrWhitespace(issue.details) or withComments:
if withComments: lines.add("# Details go below the \"--------\"")
lines.add("--------")
lines.add(issue.details)
@ -168,6 +193,7 @@ proc loadIssueById*(tasksDir, id: string): Issue =
raise newException(KeyError, "cannot find issue for id: " & id)
proc store*(issue: Issue, withComments = false) =
discard existsOrCreateDir(issue.filePath.parentDir)
writeFile(issue.filepath, toStorageFormat(issue, withComments))
proc store*(tasksDir: string, issue: Issue, state: IssueState, withComments = false) =
@ -200,7 +226,7 @@ proc loadIssues*(path: string): seq[Issue] =
toSeq(orderFile.lines)
.mapIt(it.split(' ')[0])
.deduplicate
.filterIt(not it.startsWith("> ") and not it.isNilOrWhitespace)
.filterIt(not it.startsWith("> ") and not it.isEmptyOrWhitespace)
else: newSeq[string]()
type TaggedIssue = tuple[issue: Issue, ordered: bool]
@ -256,6 +282,9 @@ proc filter*(issues: seq[Issue], filter: IssueFilter): seq[Issue] =
let p = filter.fullMatch.get
result = result.filterIt( it.summary.find(p).isSome or it.details.find(p).isSome)
for tag in filter.hasTags:
result = result.filterIt(it.tags.find(tag) >= 0)
### Configuration utilities
proc loadConfig*(args: Table[string, Value] = initTable[string, Value]()): PitConfig =
let pitrcLocations = @[
@ -263,11 +292,11 @@ proc loadConfig*(args: Table[string, Value] = initTable[string, Value]()): PitCo
".pitrc", $getEnv("PITRC"), $getEnv("HOME") & "/.pitrc"]
var pitrcFilename: string =
foldl(pitrcLocations, if len(a) > 0: a elif existsFile(b): b else: "")
foldl(pitrcLocations, if len(a) > 0: a elif fileExists(b): b else: "")
if not existsFile(pitrcFilename):
if not fileExists(pitrcFilename):
warn "pit: could not find .pitrc file: " & pitrcFilename
if isNilOrWhitespace(pitrcFilename):
if isEmptyOrWhitespace(pitrcFilename):
pitrcFilename = $getEnv("HOME") & "/.pitrc"
var cfgFile: File
try:
@ -293,15 +322,13 @@ proc loadConfig*(args: Table[string, Value] = initTable[string, Value]()): PitCo
for k, v in cfgJson["contexts"]:
result.contexts[k] = v.getStr()
if isNilOrWhitespace(result.tasksDir):
if isEmptyOrWhitespace(result.tasksDir):
raise newException(Exception, "no tasks directory configured")
if not existsDir(result.tasksDir):
if not dirExists(result.tasksDir):
raise newException(Exception, "cannot find tasks dir: " & result.tasksDir)
# Create our tasks directory structure if needed
for s in IssueState:
if not existsDir(result.tasksDir / $s):
if not dirExists(result.tasksDir / $s):
(result.tasksDir / $s).createDir

View File

@ -1 +1 @@
const PIT_VERSION* = "4.6.1"
const PIT_VERSION* = "4.13.0"