Add REST API. Refactor config logic.

The REST API is simply a wrapper around the command line (and actually
invokes the command line). It relies on the command line tool validating
its input.

Currently only the `/list` endpoint is implemented, exposing the `list`
command.

.gitignore

@@ -1,3 +1,4 @@
 *.sw*
 nimcache/
 /pit
+/pit_api

pit.nimble

@@ -1,12 +1,15 @@
 # Package
 
-version       = "4.0.5"
+include "src/pitpkg/private/version.nim"
+
+version       = PIT_VERSION
 author        = "Jonathan Bernard"
 description   = "Personal issue tracker."
 license       = "MIT"
 srcDir        = "src"
-bin           = @["pit"]
+bin           = @["pit", "pit_api"]
 
 # Dependencies
 
-requires @["nim >= 0.18.0", "uuids 0.1.9", "docopt 0.6.5", "cliutils 0.3.4", "timeutils 0.3.0"]
+requires @[ "nim >= 0.18.0", "cliutils 0.3.5", "docopt 0.6.5", "jester 0.2.0",
+  "timeutils 0.3.0", "uuids 0.1.9" ]

src/pit.nim

@@ -1,66 +1,42 @@
-## Personal Issue Tracker
+## Personal Issue Tracker CLI interface
-## ======================
+## ====================================
-##
 
 import cliutils, docopt, json, logging, options, os, ospaths, sequtils,
-  tables, terminal, times, unicode, uuids
+  tables, terminal, times, timeutils, unicode, uuids
 
 import strutils except capitalize, toUpper, toLower
 import pitpkg/private/libpit
 export libpit
 
+include "pitpkg/private/version.nim"
+
 type
   CliContext = ref object
-    autoList, triggerPtk: bool
+    autoList, triggerPtk, verbose: bool
-    tasksDir*: string
+    cfg*: PitConfig
     contexts*: TableRef[string, string]
+    defaultContext*, tasksDir*: string
     issues*: TableRef[IssueState, seq[Issue]]
     termWidth*: int
 
 proc initContext(args: Table[string, Value]): CliContext =
-  let pitrcLocations = @[
+  let pitCfg = loadConfig(args)
-    if args["--config"]: $args["--config"] else: "",
-    ".pitrc", $getEnv("PITRC"), $getEnv("HOME") & "/.pitrc"]
 
-  var pitrcFilename: string =
+  let cliJson =
-    foldl(pitrcLocations, if len(a) > 0: a elif existsFile(b): b else: "")
+    if pitCfg.cfg.json.hasKey("cli"): pitCfg.cfg.json["cli"]
+    else: newJObject()
 
-  if not existsFile(pitrcFilename):
+  let cliCfg = CombinedConfig(docopt: args, json: cliJson)
-    warn "pit: could not find .pitrc file: " & pitrcFilename
-    if isNilOrWhitespace(pitrcFilename):
-      pitrcFilename = $getEnv("HOME") & "/.pitrc"
-    var cfgFile: File
-    try:
-      cfgFile = open(pitrcFilename, fmWrite)
-      cfgFile.write("{\"tasksDir\": \"/path/to/tasks\"}")
-    except: warn "pit: could not write default .pitrc to " & pitrcFilename
-    finally: close(cfgFile)
-
-  var cfgJson: JsonNode
-  try: cfgJson = parseFile(pitrcFilename)
-  except: raise newException(IOError,
-    "unable to read config file: " & pitrcFilename &
-    "\x0D\x0A" & getCurrentExceptionMsg())
-
-  let cfg = CombinedConfig(docopt: args, json: cfgJson)
 
   result = CliContext(
-    autoList: cfgJson.getOrDefault("autoList").getBool(false),
+    autoList: cliJson.getOrDefault("autoList").getBool(false),
-    contexts: newTable[string,string](),
+    contexts: pitCfg.contexts,
+    defaultContext: cliJson.getOrDefault("defaultContext").getStr(""),
+    verbose: parseBool(cliCfg.getVal("verbose", "false")) and not args["--quiet"],
     issues: newTable[IssueState, seq[Issue]](),
-    tasksDir: cfg.getVal("tasks-dir", ""),
+    tasksDir: pitCfg.tasksDir,
-    termWidth: parseInt(cfg.getVal("term-width", "80")),
+    termWidth: parseInt(cliCfg.getVal("term-width", "80")),
-    triggerPtk: cfgJson.getOrDefault("triggerPtk").getBool(false))
+    triggerPtk: cliJson.getOrDefault("triggerPtk").getBool(false))
-
-  if cfgJson.hasKey("contexts"):
-    for k, v in cfgJson["contexts"]:
-      result.contexts[k] = v.getStr()
-
-  if isNilOrWhitespace(result.tasksDir):
-    raise newException(Exception, "no tasks directory configured")
-
-  if not existsDir(result.tasksDir):
-    raise newException(Exception, "cannot find tasks dir: " & result.tasksDir)
 
 proc getIssueContextDisplayName(ctx: CliContext, context: string): string =
   if not ctx.contexts.hasKey(context):
@@ -68,9 +44,9 @@ proc getIssueContextDisplayName(ctx: CliContext, context: string): string =
     else: return context.capitalize()
   return ctx.contexts[context]
 
-proc writeIssue(ctx: CliContext, issue: Issue, state: IssueState,
+proc writeIssue(ctx: CliContext, issue: Issue, width: int, indent = "",
-                 width: int, indent: string, topPadded: bool) =
+                verbose = false, topPadded = false) =
-  var showDetails = not issue.details.isNilOrWhitespace
+  var showDetails = not issue.details.isNilOrWhitespace and verbose
 
   if showDetails and not topPadded: stdout.writeLine("")
 
@@ -79,7 +55,7 @@ proc writeIssue(ctx: CliContext, issue: Issue, state: IssueState,
   wrappedSummary = wrappedSummary[(6 + indent.len)..^1]
   stdout.setForegroundColor(fgBlack, true)
   stdout.write(indent & ($issue.id)[0..<6])
-  stdout.setForegroundColor(fgCyan, false)
+  stdout.setForegroundColor(fgWhite, false)
   stdout.write(wrappedSummary)
 
   if issue.tags.len > 0:
@@ -90,20 +66,23 @@ proc writeIssue(ctx: CliContext, issue: Issue, state: IssueState,
     else:
       stdout.writeLine("\n" & indent & "  " & tagsStr)
   else: stdout.writeLine("")
-  stdout.resetAttributes
 
-  if state == Pending and issue.hasProp("pending"):
+  if issue.hasProp("pending"):
     let startIdx = "Pending: ".len
     var pendingText = issue["pending"].wordWrap(width - startIdx - 2)
                                       .indent(startIdx)
     pendingText = ("Pending: " & pendingText[startIdx..^1]).indent(indent.len + 2)
+    stdout.setForegroundColor(fgCyan, false)
     stdout.writeLine(pendingText)
 
-  if showDetails: stdout.writeLine(issue.details.indent(indent.len + 2))
+  if showDetails:
+    stdout.setForegroundColor(fgCyan, false)
+    stdout.writeLine(issue.details.indent(indent.len + 2))
 
+  stdout.resetAttributes
 
 proc writeSection(ctx: CliContext, issues: seq[Issue], state: IssueState,
-                   indent = "") =
+                   indent = "", verbose = false) =
   let innerWidth = ctx.termWidth - (indent.len * 2)
 
   stdout.setForegroundColor(fgBlue, true)
@@ -125,15 +104,15 @@ proc writeSection(ctx: CliContext, issues: seq[Issue], state: IssueState,
       stdout.resetAttributes
 
       for i in ctxIssues:
-        ctx.writeIssue(i, state, innerWidth - 2, indent & "  ", topPadded)
+        ctx.writeIssue(i, innerWidth - 2, indent & "  ", verbose, topPadded)
-        topPadded = not i.details.isNilOrWhitespace
+        topPadded = not i.details.isNilOrWhitespace and verbose
 
       if not topPadded: stdout.writeLine("")
 
   else:
     for i in issues:
-      ctx.writeIssue(i, state, innerWidth, indent, topPadded)
+      ctx.writeIssue(i, innerWidth, indent, verbose, topPadded)
-      topPadded = not i.details.isNilOrWhitespace
+      topPadded = not i.details.isNilOrWhitespace and verbose
 
   stdout.writeLine("")
 
@@ -185,12 +164,12 @@ proc edit(issue: Issue) =
       getCurrentExceptionMsg()
     issue.store()
 
-proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState], today, future: bool) =
+proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState], today, future, verbose: bool) =
 
   if state.isSome:
     ctx.loadIssues(state.get)
     if filter.isSome: ctx.filterIssues(filter.get)
-    ctx.writeSection(ctx.issues[state.get], state.get)
+    ctx.writeSection(ctx.issues[state.get], state.get, "", verbose)
     return
 
   ctx.loadAllIssues()
@@ -204,14 +183,14 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
 
     for s in [Current, TodoToday]:
       if ctx.issues.hasKey(s) and ctx.issues[s].len > 0:
-        ctx.writeSection(ctx.issues[s], s, indent)
+        ctx.writeSection(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:
-          ctx.writeSection(doneIssues, Done, indent)
+          ctx.writeSection(doneIssues, Done, indent, verbose)
 
   # Future items
   if future:
@@ -219,7 +198,7 @@ proc list(ctx: CliContext, filter: Option[IssueFilter], state: Option[IssueState
 
     for s in [Pending, Todo]:
       if ctx.issues.hasKey(s) and ctx.issues[s].len > 0:
-        ctx.writeSection(ctx.issues[s], s, indent)
+        ctx.writeSection(ctx.issues[s], s, indent, verbose)
 
 when isMainModule:
 
@@ -227,8 +206,8 @@ when isMainModule:
   let doc = """
 Usage:
   pit ( new | add) <summary> [<state>] [options]
-  pit list [<state>] [options]
+  pit list [<listable>] [options]
-  pit ( start | done | pending | do-today | todo | suspend ) <id>...
+  pit ( start | done | pending | do-today | todo | suspend ) <id>... [options]
   pit edit <id>
   pit ( delete | rm ) <id>...
 
@@ -236,33 +215,39 @@ Options:
 
   -h, --help                Print this usage information.
 
-  -t, --tags <tags>         Specify tags for an issue.
-
   -p, --properties <props>  Specify properties. Formatted as "key:val;key:val"
                             When used with the list command this option applies
                             a filter to the issues listed, only allowing those
                             which have all of the given properties.
 
+  -c, --context <ctxName>   Shorthand for '-p context:<ctxName>'
+
+  -g, --tags <tags>         Specify tags for an issue.
+
   -T, --today               Limit to today's issues.
 
   -F, --future              Limit to future issues.
 
+  -v, --verbose             Show issue details when listing issues.
+
+  -q, --quiet               Suppress verbose output.
+
   -y, --yes                 Automatically answer "yes" to any prompts.
 
   -C, --config <cfgFile>    Location of the config file (defaults to $HOME/.pitrc)
 
   -E, --echo-args           Echo arguments (for debug purposes).
 
-  --tasks-dir               Path to the tasks directory (defaults to the value
+  -d, --tasks-dir           Path to the tasks directory (defaults to the value
                             configured in the .pitrc file)
 
-  --term-width              Manually set the terminal width to use.
+  --term-width <width>      Manually set the terminal width to use.
 """
 
   logging.addHandler(newConsoleLogger())
 
   # Parse arguments
-  let args = docopt(doc, version = "pit 4.0.5")
+  let args = docopt(doc, version = PIT_VERSION)
 
   if args["--echo-args"]: stderr.writeLine($args)
 
@@ -272,10 +257,22 @@ Options:
 
   let ctx = initContext(args)
 
-  # Create our tasks directory structure if needed
+  var propertiesOption = none(TableRef[string,string])
-  for s in IssueState:
+
-    if not existsDir(ctx.tasksDir / $s):
+  if args["--properties"] or args["--context"] or
-      (ctx.tasksDir / $s).createDir
+     not ctx.defaultContext.isNilOrWhitespace:
+
+    var props =
+      if args["--properties"]: parsePropertiesOption($args["--properties"])
+      else: newTable[string,string]()
+
+    if args["--context"] and $args["--context"] != "all":
+      props["context"] = $args["--context"]
+    elif not args["--context"] and not ctx.defaultContext.isNilOrWhitespace:
+      stderr.writeLine("Limiting to default context: " & ctx.defaultContext)
+      props["context"] = ctx.defaultContext
+
+    propertiesOption = some(props)
 
   ## Actual command runners
   if args["new"] or args["add"]:
@@ -283,14 +280,15 @@ Options:
       if args["<state>"]: parseEnum[IssueState]($args["<state>"])
       else: TodoToday
 
+    var issueProps = propertiesOption.get(newTable[string,string]())
+    if not issueProps.hasKey("created"): issueProps["created"] = getTime().local.formatIso8601
+
     var issue = Issue(
       id: genUUID(),
       summary: $args["<summary>"],
-      properties:
+      properties: issueProps,
-        if args["--properties"]: parsePropertiesOption($args["--properties"])
-        else: newTable[string,string](),
       tags:
-        if args["--tags"]: ($args["tags"]).split(",").mapIt(it.strip)
+        if args["--tags"]: ($args["--tags"]).split(",").mapIt(it.strip)
         else: newSeq[string]())
 
     ctx.tasksDir.store(issue, state)
@@ -306,13 +304,17 @@ Options:
     var targetState: IssueState
     if args["done"]: targetState = Done
     elif args["do-today"]: targetState = TodoToday
-    elif args["pending"]: targetState = Todo
+    elif args["pending"]: targetState = Pending
     elif args["start"]: targetState = Current
     elif args["todo"]: targetState = Todo
     elif args["suspend"]: targetState = Dormant
 
     for id in @(args["<id>"]):
-      ctx.tasksDir.loadIssueById(id).changeState(ctx.tasksDir, targetState)
+      var issue = ctx.tasksDir.loadIssueById(id)
+      if propertiesOption.isSome:
+        for k,v in propertiesOption.get:
+          issue[k] = v
+      issue.changeState(ctx.tasksDir, targetState)
 
     if ctx.triggerPtk:
       if targetState == Current:
@@ -321,7 +323,8 @@ Options:
         if issue.tags.len > 0: cmd &= "-g \"" & issue.tags.join(",") & "\""
         cmd &= " \"" & issue.summary & "\""
         discard execShellCmd(cmd)
-      elif targetState == Done: discard execShellCmd("ptk stop")
+      elif targetState == Done or targetState == Pending:
+        discard execShellCmd("ptk stop")
 
   elif args["delete"] or args["rm"]:
     for id in @(args["<id>"]):
@@ -339,21 +342,31 @@ Options:
 
     let filter = initFilter()
     var filterOption = none(IssueFilter)
-    if args["--properties"]:
+    if propertiesOption.isSome:
-      filter.properties = parsePropertiesOption($args["--properties"])
+      filter.properties = propertiesOption.get
       filterOption = some(filter)
 
-    let stateOption =
+    var stateOption = none(IssueState)
-      if args["<state>"]: some(parseEnum[IssueState]($args["<state>"]))
+    var issueIdOption = none(string)
-      else: none(IssueState)
+    if args["<listable>"]:
+      try: stateOption = some(parseEnum[IssueState]($args["<listable>"]))
+      except: issueIdOption = some($args["<listable>"])
 
-    let showBoth = args["--today"] == args["--future"]
+    # List a specific issue
-    ctx.list(filterOption, stateOption, showBoth or args["--today"],
+    if issueIdOption.isSome:
-                                             showBoth or args["--future"])
+      let issue = ctx.tasksDir.loadIssueById(issueIdOption.get)
+      ctx.writeIssue(issue, ctx.termWidth, "", true, true)
+
+    # List all issues
+    else:
+      let showBoth = args["--today"] == args["--future"]
+      ctx.list(filterOption, stateOption, showBoth or args["--today"],
+                                          showBoth or args["--future"],
+                                          ctx.verbose)
 
   if ctx.autoList and not args["list"]:
     ctx.loadAllIssues()
-    ctx.list(none(IssueFilter), none(IssueState), true, true)
+    ctx.list(none(IssueFilter), none(IssueState), true, true, false)
 
  except:
   fatal "pit: " & getCurrentExceptionMsg()

src/pit_api.nim

@@ -0,0 +1,132 @@
+## Personal Issue Tracker API Interface
+## ====================================
+
+import asyncdispatch, cliutils, docopt, jester, json, logging, sequtils, strutils
+import nre except toSeq
+
+import pitpkg/private/libpit
+
+include "pitpkg/private/version.nim"
+
+type
+  PitApiCfg* = object
+    apiKeys*: seq[string]
+    global*: PitConfig
+    port*: int
+
+const TXT = "text/plain"
+
+proc raiseEx(reason: string): void = raise newException(Exception, reason)
+
+template checkAuth(cfg: PitApiCfg) =
+  ## Check this request for authentication and authorization information.
+  ## If the request is not authorized, this template sets up the 401 response
+  ## correctly. The calling context needs only to return from the route.
+
+  var authed {.inject.} = false
+
+  try:
+    if not request.headers.hasKey("Authorization"):
+      raiseEx "No auth token."
+
+    let headerVal = request.headers["Authorization"]
+    if not headerVal.startsWith("Bearer "):
+      raiseEx "Invalid Authentication type (only 'Bearer' is supported)."
+
+    if not cfg.apiKeys.contains(headerVal[7..^1]):
+      raiseEx "Invalid API key."
+
+    authed = true
+
+  except:
+    stderr.writeLine "Auth failed: " & getCurrentExceptionMsg()
+    response.data[0] = CallbackAction.TCActionSend
+    response.data[1] = Http401
+    response.data[2]["WWW-Authenticate"] = "Bearer"
+    response.data[2]["Content-Type"] = TXT
+    response.data[3] = getCurrentExceptionMsg()
+
+proc paramsToArgs(params: StringTableRef): tuple[stripAnsi: bool, args: seq[string]] =
+  result = (false, @[])
+
+  if params.hasKey("color"):
+    if params["color"] != "true":
+      result[0] = true
+
+  for k,v in params:
+    if k == "color": continue
+    elif k.startsWith("arg"): result[1].add(v) # support ?arg1=val1&arg2=val2 -> cmd val1 val2
+    else :
+      result[1].add("--" & k)
+      if v != "true": result[1].add(v) # support things like ?verbose=true -> cmd --verbose
+
+let STRIP_ANSI_REGEX = re"\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[m|K]"
+
+proc stripAnsi(str: string): string =
+  return str.replace(STRIP_ANSI_REGEX, "")
+
+proc start*(cfg: PitApiCfg) =
+
+  var stopFuture = newFuture[void]()
+
+  settings:
+    port = Port(cfg.port)
+    appName = "/api"
+
+  routes:
+
+    get "/ping":
+      resp("pong", TXT)
+
+    get "/issues":
+      checkAuth(cfg); if not authed: return true
+
+      var (stripAnsi, args) = paramsToArgs(request.params)
+      args = @["list"] & args
+
+      info "args: \n" & args.join(" ")
+      let execResult = execWithOutput("pit", ".", args)
+      if execResult[2] != 0: resp(Http500, stripAnsi($execResult[0] & "\n" & $execResult[1]), TXT)
+      else:
+        if stripAnsi: resp(stripAnsi(execResult[0]), TXT)
+        else: resp(execResult[0], TXT)
+
+    post "/issues":
+      checkAuth(cfg); if not authed: return true
+
+  waitFor(stopFuture)
+
+proc loadApiConfig(args: Table[string, Value]): PitApiCfg =
+  let pitCfg = loadConfig(args)
+  let apiJson =
+    if pitCfg.cfg.json.hasKey("api"): pitCfg.cfg.json["api"]
+    else: newJObject()
+
+  let apiCfg = CombinedConfig(docopt: args, json: apiJson)
+
+  let apiKeysArray =
+    if apiJson.hasKey("apiKeys"): apiJson["apiKeys"]
+    else: newJArray()
+
+  result = PitApiCfg(
+    apiKeys: toSeq(apiKeysArray).mapIt(it.getStr),
+    global: pitCfg,
+    port: parseInt(apiCfg.getVal("port", "8123")))
+
+when isMainModule:
+
+  let doc = """\
+Usage:
+  pit_api [options]
+
+Options:
+
+  -c, --config <cfgFile>      Path to the pit_api config file.
+  -d, --tasks-dir             Path to the tasks directory.
+  -p, --port                  Port to listen on (defaults to 8123)
+"""
+
+  let args = docopt(doc, version = PIT_VERSION)
+
+  let apiCfg = loadApiConfig(args)
+  start(apiCfg)

src/pitpkg/private/libpit.nim

@@ -1,4 +1,5 @@
-import cliutils, options, os, ospaths, sequtils, strutils, tables, times, timeutils, uuids
+import cliutils, docopt, json, logging, options, os, ospaths, sequtils,
+  strutils, tables, times, timeutils, uuids
 
 from nre import re, match
 type
@@ -21,6 +22,11 @@ type
     properties*: TableRef[string, string]
     completedRange*: tuple[b, e: DateTime]
 
+  PitConfig* = ref object
+    tasksDir*: string
+    contexts*: TableRef[string, string]
+    cfg*: CombinedConfig
+
 const DONE_FOLDER_FORMAT* = "yyyy-MM"
 
 let ISSUE_FILE_PATTERN = re"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}\.txt"
@@ -189,3 +195,52 @@ proc filter*(issues: seq[Issue], filter: IssueFilter): seq[Issue] =
              filter.completedRange.b,
              filter.completedRange.e))
 
+### Configuration utilities
+proc loadConfig*(args: Table[string, Value] = initTable[string, Value]()): PitConfig =
+  let pitrcLocations = @[
+    if args["--config"]: $args["--config"] else: "",
+    ".pitrc", $getEnv("PITRC"), $getEnv("HOME") & "/.pitrc"]
+
+  var pitrcFilename: string =
+    foldl(pitrcLocations, if len(a) > 0: a elif existsFile(b): b else: "")
+
+  if not existsFile(pitrcFilename):
+    warn "pit: could not find .pitrc file: " & pitrcFilename
+    if isNilOrWhitespace(pitrcFilename):
+      pitrcFilename = $getEnv("HOME") & "/.pitrc"
+    var cfgFile: File
+    try:
+      cfgFile = open(pitrcFilename, fmWrite)
+      cfgFile.write("{\"tasksDir\": \"/path/to/tasks\"}")
+    except: warn "pit: could not write default .pitrc to " & pitrcFilename
+    finally: close(cfgFile)
+
+  var cfgJson: JsonNode
+  try: cfgJson = parseFile(pitrcFilename)
+  except: raise newException(IOError,
+    "unable to read config file: " & pitrcFilename &
+    "\x0D\x0A" & getCurrentExceptionMsg())
+
+  let cfg = CombinedConfig(docopt: args, json: cfgJson)
+
+  result = PitConfig(
+    cfg: cfg,
+    contexts: newTable[string,string](),
+    tasksDir: cfg.getVal("tasks-dir", ""))
+
+  if cfgJson.hasKey("contexts"):
+    for k, v in cfgJson["contexts"]:
+      result.contexts[k] = v.getStr()
+
+  if isNilOrWhitespace(result.tasksDir):
+    raise newException(Exception, "no tasks directory configured")
+
+  if not existsDir(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):
+      (result.tasksDir / $s).createDir
+
+

src/pitpkg/private/version.nim

@@ -0,0 +1 @@
+const PIT_VERSION = "4.1.0"