Add debug logging when changing the state of an issue.

When calling pit from other programs or as part of a pipe, the display
style typically used to format listed issues contains a lot of unwanted
output (ANSI escape code, headings, etc.). Now when STDIN is not a TTY,
a plain and consistently formatted version of the issues is listed
without any additional formatting, one issue per line of output.

.tool-versions

@@ -0,0 +1 @@
+nim 1.6.20

pit.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "4.24.0"
+version       = "4.25.2"
 author        = "Jonathan Bernard"
 description   = "Personal issue tracker."
 license       = "MIT"

src/pit.nim

@@ -70,6 +70,24 @@ proc formatIssue*(issue: Issue): string =
 
   result &= termReset
 
+proc formatPlainIssueSummary*(issue: Issue): string =
+
+  result = "$#: $# $#" % [
+    $issue.state,
+    ($issue.id)[0..<6],
+    issue.summary ]
+
+  if issue.hasProp("delegated-to") or issue.hasProp("pending"):
+    var parts = newSeq[string]()
+
+    if issue.hasProp("delegated-to"):
+      parts.add("delegated to " & issue["delegated-to"])
+
+    if issue.hasProp("pending"):
+      parts.add("pendin: " & issue["pending"])
+
+    result &= "($#)" % [ parts.join("; ") ]
+
 proc formatSectionIssue*(
     issue: Issue,
     width: int = 80,
@@ -251,7 +269,15 @@ proc list(
           it.hasProp("completed") and
           sameDay(getTime().local, it.getDateTime("completed")))
 
-      stdout.write ctx.formatSection(ctx.issues[state], state, "", verbose)
+      if isatty(stdout):
+        stdout.write ctx.formatSection(ctx.issues[state], state, "", verbose)
+
+      else:
+        stdout.writeLine ctx.issues[state]
+          .mapIt(formatPlainIssueSummary(it))
+          .join("\n")
+
+
     trace "listing complete"
     return
 
@@ -279,7 +305,13 @@ proc list(
           not (it.hasProp("hide-until") and
                it.getDateTime("hide-until") > getTime().local))
 
-        stdout.write ctx.formatSection(visibleIssues, s, indent, verbose)
+        if isatty(stdout):
+          stdout.write ctx.formatSection(visibleIssues, s, indent, verbose)
+
+        else:
+          stdout.writeLine visibleIssues
+            .mapIt(formatPlainIssueSummary(it))
+            .join("\n")
 
   # Future items
   if future:
@@ -296,7 +328,13 @@ proc list(
           not (it.hasProp("hide-until") and
                it.getDateTime("hide-until") > getTime().local))
 
-        stdout.write ctx.formatSection(visibleIssues, s, indent, verbose)
+        if isatty(stdout):
+          stdout.write ctx.formatSection(visibleIssues, s, indent, verbose)
+
+        else:
+          stdout.writeLine visibleIssues
+            .mapIt(formatPlainIssueSummary(it))
+            .join("\n")
 
   trace "listing complete"
 
@@ -463,7 +501,7 @@ when isMainModule:
           )
           cmd &= " -g \"" & tags.join(",") & "\""
         cmd &= " -n \"pit-id: " & $issue.id & "\""
-        cmd &= " \"" & issue.summary & "\""
+        cmd &= " \"[" & ($issue.id)[0..<6] & "] " & issue.summary & "\""
         discard execShellCmd(cmd)
       elif targetState == Done or targetState == Pending:
         discard execShellCmd("ptk stop")

src/pitpkg/cliconstants.nim

@@ -1,4 +1,4 @@
-const PIT_VERSION* = "4.24.0"
+const PIT_VERSION* = "4.25.2"
 
 const USAGE* = """Usage:
   pit ( new | add) <summary> [<state>] [options]
@@ -101,7 +101,9 @@ Issue Properties:
     created
 
       If present, expected to be an ISO 8601-formatted date that represents the
-      time when the issue was created.
+      time when the issue was created. E.g.:
+
+          created: 2023-07-13T13:28:41-05:00
 
     completed
 
@@ -110,12 +112,16 @@ Issue Properties:
       property automatically when you use the "done" command, and can filter on
       this value.
 
+          completed: 2023-04-27T11:52:28-05:00
+
     context
 
       Allows issues to be organized into contexts. The -c option is short-hand
       for '-p context:<context-name>' and the 'list contexts' command will show
       all values of 'context' set in existing issues.
 
+          context: family
+
     delegated-to
 
       When an issue now belongs to someone else, but needs to be monitored for
@@ -123,17 +129,23 @@ Issue Properties:
       note how it has been delegated. When present PIT will prepend this value
       to the issue summary with an accent color.
 
+          delegated-to: Bob Ross
+
     hide-until
 
       When present, expected to be an ISO 8601-formatted date and used to
       supress the display of the issue until on or after the given date.
 
+          hide-until: 2024-01-01T13:45:00-05:00
+
     pending
 
       When an issue is blocked by a third party, this property can be used to
       capture details about the dependency When present PIT will display this
       value after the issue summary.
 
+          pending: Results of WCAG analysis.
+
     recurrence
 
       When an issue is moved to the "done" state, if the issue has a valid
@@ -144,7 +156,7 @@ Issue Properties:
       A valid recurrence value has a time value and optionally has an source
       issue ID. For example:
 
-        every 5 days, 10a544
+          recurrence: every 5 days, 10a544
 
       The first word, "every", is expected to be either "every" or "after".
 
@@ -162,12 +174,12 @@ Issue Properties:
 
       Examples:
 
-        every day
-        every 2 days
-        after 2 days
-        every week
-        after 12 hours
-        every 2 weeks, 10a544
+          every day
+          every 2 days
+          after 2 days
+          every week
+          after 12 hours
+          every 2 weeks, 10a544
 
     tags
 

src/pitpkg/private/libpit.nim

@@ -328,11 +328,16 @@ proc loadAllIssues*(tasksDir: string): TableRef[IssueState, seq[Issue]] =
   for state in IssueState: result[state] = tasksDir.loadIssues(state)
 
 proc changeState*(issue: Issue, tasksDir: string, newState: IssueState) =
+  var dbgInfo = "[$#] changing state: $# → $#" %
+    [ ($issue.id)[0..<6], $issue.state, $newState ]
+
   let oldFilepath = issue.filepath
   if newState == Done: issue.setDateTime("completed", getTime().local)
   tasksDir.store(issue, newState)
   if oldFilePath != issue.filepath: removeFile(oldFilepath)
+  dbgInfo &= "\n\told path: $#\n\tnew path: $#" % [oldFilePath, issue.filepath]
   issue.state = newState
+  debug dbgInfo
 
 proc delete*(issue: Issue) = removeFile(issue.filepath)