bacon-tracker 1.0.0

data/lib/bacon_tracker/commands/tracker.md

@@ -0,0 +1,269 @@
+---
+name: tracker
+description: Manage bacon-tracker stories - create features/ bugs/ chores, move them through workflow, edit fields, delete, check the backlog, and view story content. Use when the user mentions stories, the backlog, creating features/ bugs/ chores, or workflow transitions like commit, start, done, next.
+argument-hint: "[new feature|bug|chore <title> [field=value]] [commit|start|done|show <ID>] [edit <ID> <field>=<value>] [delete <ID>] [list [stage]] [next] [lint]"
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash(find *)
+  - Bash(grep *)
+  - Bash(ls *)
+  - Bash(mv *)
+  - Bash(rm *)
+  - Bash(rake *)
+  - Bash(bundle exec rake *)
+---
+
+# /tracker - Bacon Tracker
+
+Manage stories for a project using bacon-tracker. Arguments: `$ARGUMENTS`
+
+---
+
+## Vocabulary - use these words
+
+The work item is a **story** (a file). Never call it a card, ticket, issue, or task. A **card** is only the board's rendering of a story. A **column** is only the board's rendering of a stage. The board is the *tracker board*, not a kanban board.
+
+- **type** - `feature`, `bug`, or `chore`. The directory is the plural.
+- **stage** - the directory: `1_icebox`, `2_backlog`, `3_started`, `4_done`. Authoritative. `status:` in frontmatter merely mirrors it and can drift.
+- **commit / start / done** - the workflow verbs. `commit` means icebox → backlog, *not* a git commit; say which when both are in play.
+- **subtask** - a `- [ ]` line in a body. Not a child story; there is no hierarchy, no epics, no parents.
+- **blocked_by / blocks**, **linked_to / linked_from** - you write the first of each pair; the second is derived and never typed.
+- Stories are **moved**, never assigned or transitioned. Nothing is closed or resolved - it is **done**, and done is append-only.
+
+There are no sprints, points, priorities, or epics. Position in `backlog.md` is the priority. Full glossary: `docs/vocabulary.md` in the bacon-tracker repo.
+
+---
+
+## Step 1 - find the tracker root
+
+**Dashboard setup.** If the current directory holds a `dashboard.md` (the tracker home - where `tracker-init` installs this command), each `## Heading` in it is a project with a `path:` (the project directory) and a `namespace:`. The stories are in `<path>/tracker`, unless the entry has a `tracker:` key, which is relative to `path:`. Relative paths are relative to `dashboard.md`'s directory. An older entry may point `path:` straight at a tracker directory (one holding `backlog.md` or `.next-id`); use it as is. Pick the project the user named (by title or namespace); if they didn't name one and there's more than one, ask.
+
+**Single project.** Otherwise, search the current repo for a directory containing `backlog.md` and `.next-id`. Common locations, in order: `tracker/` (the convention), then `docs/tracker/` (an older layout, still supported). If not found, tell the user and stop.
+
+Decisions, if the project has them, live in a **separate** tree: `docs/decisions/`, with one directory per status and its own `.next-id`. Never conflate the two - a decision is not a story, and `/tracker` does not manage them.
+
+Once found, set `TRACKER_ROOT` to that path.
+
+**Find the namespace** - from the `namespace:` in `dashboard.md`, or from existing files in `TRACKER_ROOT`:
+1. Read the first entry in `backlog.md` - e.g. `- APP-003 implement user auth` → namespace is `APP`
+2. Or find any story file - e.g. `find $TRACKER_ROOT -name '[A-Z]*-[0-9]*.md' -o -name '[A-Z]*-[0-9]*.feature' | head -1` → parse the prefix before the first `-[0-9]`
+
+**Prefer the rake tasks.** If a `Rakefile` that loads bacon-tracker is available - next to `dashboard.md` in a dashboard setup, or in the project directory in a single-project setup - run the matching rake task instead of editing files by hand. It allocates IDs under a lock and applies exactly the gem's rules. Run it from the Rakefile's directory, with `NS=<namespace>` in a dashboard setup (a single-project Rakefile needs no `NS`), and always **quote a task that has brackets** - zsh treats `[ ]` as a glob:
+
+| Subcommand | Rake task |
+|---|---|
+| `new <type> <title> [field=value ...]` | `rake "story:<type>[<title>,field=value,...]"` |
+| `commit` / `start` / `done <ID>` | `rake "story:commit[<ID>]"` (and `story:start`, `story:done`) |
+| `edit <ID> field=value ...` | `rake "story:edit[<ID>,field=value,...]"` |
+| `next` | `rake story:next` |
+| `lint` | `rake story:lint` |
+
+Rake splits bracket arguments on commas, so a title or value containing a comma can't go through rake - fall back to the file steps below for that one (or set the title afterwards). Prefix with `bundle exec` if the Rakefile's directory has a `Gemfile`. If rake fails, relay its message; don't retry by hand-editing unless the user asks. The file steps below are the fallback when no Rakefile is available, and the only way for `show`, `list`, `delete`, and multi-line body edits.
+
+---
+
+## Step 2 - dispatch on arguments
+
+Parse the first word of `$ARGUMENTS` as the subcommand. Match case-insensitively.
+
+---
+
+### No arguments - status
+
+Show a compact overview by reading the filesystem directly:
+- Count files matching `<NS>-*.{md,feature}` in each of `features/`, `bugs/`, `chores/` × `1_icebox/`, `2_backlog/`, `3_started/`, `4_done/`
+- Read `backlog.md` for the ordered backlog IDs and titles
+
+Output format:
+```
+<Project> (<NS>)
+
+  done     12
+  started   1
+  backlog   3
+  icebox    5
+
+  next: APP-003 - implement user auth
+
+  backlog:
+    APP-003  implement user auth
+    APP-007  add email notifications
+    APP-001  set up CI
+```
+
+If backlog is empty, say so. If no stories exist at all, suggest `/tracker new feature My First Story`.
+
+---
+
+### `new <type> <title> [field=value ...]`
+
+type must be `feature`, `bug`, or `chore`. The title is everything after the type, except for any trailing `field=value` tokens (`size=`, `assignee=`, `blocked_by=`, `linked_to=`) - those set fields at creation, the same fields as `edit`. The directory for a type is its PLURAL: feature → `features/`, bug → `bugs/`, chore → `chores/` - these are the only directories the tracker scans.
+
+1. Determine N: read the integer from `$TRACKER_ROOT/.next-id`, then **floor it above the highest `<NS>-NNN` already on disk** (`N = max(read, highest + 1)`). A stale `.next-id` from a merge or hand edit must never reissue an existing ID. When `rake` is available, prefer `rake story:<type>['title',field=…]`, which allocates the ID atomically (with this floor, under a file lock).
+2. Write `N+1` back to `.next-id`
+3. Pad N to 3 digits: `NNN`
+4. Slugify the title: lowercase it, turn each run of characters that aren't `a-z` or `0-9` into a single hyphen, and trim hyphens from both ends. If nothing is left, the slug is `untitled`
+5. Extension: `.feature` for features, `.md` for bugs and chores
+6. Create `$TRACKER_ROOT/<plural-type>/1_icebox/<NS>-<NNN>-<slug>.<ext>` (e.g. `features/1_icebox/...`). The body is the type's `_template.feature` / `_template.md` if one exists, with the title filled in (`Feature: <title>`, or `Title: <title>` on the first line for `.md`). Write frontmatter **in the file's format**: for `.md`, a YAML block `---` / `id: <NS>-<NNN>` / `type: <type>` / `status: icebox` / `---`; for `.feature`, comment-style header lines `# id: <NS>-<NNN>` / `# type: <type>` / `# status: icebox`. (A `.feature` file is parsed by its `# key:` lines **or** a leading YAML `---` block if one is present - but a file mixes only one style, so match the sibling files in the same tracker rather than introducing the other.)
+7. If any `field=value` tokens were given, set them in the frontmatter (same rules as `edit`)
+8. Confirm the new ID and file path
+
+If type is missing or unrecognised, list valid types and stop. If title is missing, ask for one.
+
+---
+
+### `commit <ID>`
+
+Move a story from icebox → backlog (committing to do it).
+
+1. Find the file: `find $TRACKER_ROOT -path "*/1_icebox/${ID}-*"`
+2. `mv` it to the corresponding `2_backlog/` directory
+3. Update `status:` in the frontmatter to `backlog`
+4. Append `- <ID> <title>` to `backlog.md`, where the title is the filename slug with hyphens as spaces (bottom = lowest priority, unless user specifies a position)
+5. Confirm new stage
+
+---
+
+### `start <ID>`
+
+Move a story from backlog → started (actively working on it).
+
+1. Find the file: `find $TRACKER_ROOT -path "*/2_backlog/${ID}-*"`
+2. `mv` it to the corresponding `3_started/` directory
+3. Update `status:` in the frontmatter to `started`
+4. Remove the ID line from `backlog.md` - it mirrors `2_backlog/` only (`rake story:lint` flags leftovers as phantom)
+5. Confirm new stage
+6. If > 2 stories are now in started across all types, flag it
+
+---
+
+### `done <ID>`
+
+Mark a story as done.
+
+1. Find the file in any non-done stage (`1_icebox/`, `2_backlog/`, or `3_started/`) - `done` may be called from any stage, matching `rake story:done` / `Core#done` (which only refuse a story already in `4_done/`)
+2. `mv` it to the corresponding `4_done/` directory
+3. Update `status:` in the frontmatter to `done`
+4. Remove the ID line from `backlog.md` if present
+5. Confirm
+
+---
+
+### `edit <ID> <field>=<value> [...]`
+
+Update story fields in place. Fields: `title`, `size` (S/M/L), `assignee` (initials), `blocked_by` (comma-separated IDs this story waits on), `linked_to` (comma-separated IDs of related stories - a symmetric "see also"), or free-form body edits described in plain language - including adding or ticking off [subtasks](#subtasks).
+
+1. Find the file: `find $TRACKER_ROOT -name "${ID}-*"`
+2. Frontmatter fields: update the existing line, or add it if missing - matching the file's format (comment-style for `.feature`, YAML for `.md`). An empty value (`size=`) removes the line.
+3. `title`: re-slugify the new title, `mv` the file to `<ID>-<new-slug>.<ext>` in its current stage directory, and update the story's `backlog.md` line if it has one (keep the `- <ID> <title>` format)
+4. Reject values containing newlines - the gem treats these as invalid everywhere
+5. Confirm what changed
+
+---
+
+### `delete <ID>`
+
+Delete a story permanently.
+
+1. Find the file: `find $TRACKER_ROOT -name "${ID}-*"`
+2. If the story is in `4_done/`, refuse and stop: done is a permanent record, and every bacon-tracker interface refuses to delete it. A regression is a new bug, not a reopened or removed story.
+3. Show its ID, title, and stage, and confirm with the user before deleting
+4. `rm` the file
+5. Remove the story's line from `backlog.md` if present
+6. Confirm what was deleted
+
+---
+
+### `show <ID>`
+
+Display a story's content:
+
+1. `find $TRACKER_ROOT -name "${ID}-*"` to locate the file
+2. Read it, strip the frontmatter block
+3. Print: ID, type, stage, title (humanised from filename), any set metadata fields, then body
+
+```
+APP-003 - implement user auth
+type:       feature    stage: backlog
+size:       M
+assignee:   AB
+blocked by: APP-005
+linked to:  APP-012
+
+Feature: Implement User Auth
+  ...
+```
+
+Omit `size`, `assignee`, `blocked by`, and `linked to` when not set. If the story has subtasks, show its `done/total` count under the metadata.
+
+Those four fields live in the story's own frontmatter. The reverse ends - which stories *this* one blocks, and which link back - aren't stored anywhere; the board derives them across all files. To surface them here, `grep -rl "blocked_by:.*${ID}\|linked_to:.*${ID}" $TRACKER_ROOT` and list the matches as `blocks:` / `linked from:`.
+
+---
+
+### Subtasks
+
+A story tracks its own checklist through Markdown checkbox lines in the **body** - `- [ ]` (open) and `- [x]` (done). They are just body text, so there is no separate command: manage them through `edit`.
+
+- **Add** subtasks: append `- [ ]` lines to the body (via `edit <ID>` with a plain-language body change).
+- **Tick off / reopen** a subtask: flip its `- [ ]` ↔ `- [x]` in the body.
+- **Count** for `show`/`status`: subtasks are checkbox lines in the body, *excluding* any inside fenced blocks (```` ``` ```` in Markdown, `"""` in Gherkin) - those are examples, not real subtasks. Report `done/total`.
+
+The web UI renders these as clickable checkboxes with a `done/total` bar; from `/tracker` they are ordinary body edits.
+
+---
+
+### `list [stage]`
+
+List stories. Optional stage filter: `icebox`, `backlog`, `started`, or `done`.
+
+Read filenames directly from `$TRACKER_ROOT/{features,bugs,chores}/<stage>/`. Print a compact table:
+
+```
+Started (1):
+  APP-003  feature  M  AB  implement user auth
+
+Backlog (3):
+  APP-007  bug         crash on empty cart
+  APP-001  chore       upgrade ruby
+  APP-009  feature  S  set up CI
+```
+
+Show size and assignee when present in the filename or frontmatter. Default: all stages (done capped at 10 most recent).
+
+---
+
+### `next`
+
+Show the top item from `backlog.md`: read the first ID line, then `show` that story.
+
+---
+
+### `lint`
+
+Check tracker consistency. If a Rakefile with story tasks is available, prefer running `rake story:lint` (with `NS=<namespace>` in a dashboard setup) and relay its output. Otherwise perform the same checks directly on the filesystem:
+
+1. **Backlog drift** - every ID in `backlog.md` must have a file in a `2_backlog/` directory (phantom lines), and every file in `2_backlog/` must have a line in `backlog.md` (unlisted stories)
+2. **Duplicate IDs** - no ID may have files in more than one stage directory
+3. **Stale `.next-id`** - the counter must exceed the highest existing story number
+4. **Status drift** - each story's `status:` frontmatter must match its stage directory (the directory is authoritative)
+5. **Stale blocker** - a `blocked_by` naming a story that is now in `4_done`. The blocker shipped and the blocked story never got the memo; clear it from `blocked_by`
+6. **Dangling reference** - a `blocked_by` or `linked_to` naming an ID with no story file
+7. **Blocker cycle** - `A` waits on `B` waits on `A`, or a story naming itself. Nothing in the cycle can ever start
+8. **Started while blocked** - a story in `3_started` with an unresolved blocker. Report it, but this is a flow signal, not corruption: `rake story:lint` deliberately does not fail on it
+
+Checks 5–7 only apply to values shaped like a story ID for this namespace. `blocked_by` may legitimately name something outside the tracker (an upstream release, another team's ticket) - leave those alone. Stories already in `4_done` are never reported as the subject of checks 5–8: done is append-only, so their relationships are record, not a to-do.
+
+Report each finding with the ID and file path, or confirm all checks pass. Don't fix anything without being asked; when asked, the directory is the source of truth.
+
+---
+
+## Implementation notes
+
+- Expand `~` in any paths using shell: `eval echo <path>` or `realpath`.
+- When editing frontmatter, match the existing format (comment-style for `.feature`, YAML for `.md`).
+- Slugify: `echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'` - and use `untitled` if the result is empty
+- `backlog.md` line format: `- <NS>-NNN <title>` (leading dash, single space - exactly what the gem writes; the stats and next-task parsers depend on it). Preserve this when adding/removing entries.
+- Keep output concise - one line per story, full content only for `show`.

data/lib/bacon_tracker/dashboard.rb

@@ -0,0 +1,168 @@
+module BaconTracker
+  class Dashboard
+    Project = Struct.new(:name, :slug, :path, :namespace, :tracker_root, :docs_root, :version_path,
+                         keyword_init: true) do
+      # A surface exists if its directory does. Absent means "this project has
+      # none" - not an error (BT-ADR-0016).
+      def tracker? = Dir.exist?(tracker_root.to_s)
+      def docs?    = Dir.exist?(docs_root.to_s)
+
+      # Derived, never configured: a repo that keeps its tracker inside its docs
+      # tree still works, the docs surface just skips it. Both paths are already
+      # known, so there is nothing to ask twice.
+      def tracker_inside_docs?
+        return false unless tracker_root && docs_root
+
+        tracker_root.start_with?(docs_root + File::SEPARATOR)
+      end
+    end
+
+    def initialize(path)
+      @path = path
+    end
+
+    # Re-parses when dashboard.md's mtime changes, so edits apply without
+    # restarting the server.
+    def projects
+      mtime = begin
+        File.mtime(@path)
+      rescue Errno::ENOENT
+        nil
+      end
+      if @projects.nil? || mtime != @parsed_mtime
+        @projects     = parse
+        @parsed_mtime = mtime
+      end
+      @projects
+    end
+
+    def project_core(slug)
+      proj = projects.find { |p| p.slug == slug }
+      proj && core_for(proj)
+    end
+
+    def project_stats
+      projects.map do |proj|
+        core = core_for(proj)
+        core.stats
+            .merge(core.docs_stats)
+            .merge(name: proj.name, slug: proj.slug, namespace: proj.namespace,
+                   tracker: proj.tracker?, docs: proj.docs?,
+                   # resolve_version alone - project_front would also render
+                   # README and CHANGELOG on every stats poll (BT-179).
+                   version: core.resolve_version(proj.path).first)
+      end
+    end
+
+    # The one place a registry entry becomes a Configuration. The server and
+    # the Rake tasks both go through it, so they cannot disagree about which
+    # directory holds the stories (BT-179: the tasks used to take the project
+    # root for the tracker root and write stories beside tracker/ instead of
+    # inside it).
+    def config_for(proj)
+      config = Configuration.new
+      config.namespace    = proj.namespace
+      config.tracker_root = proj.tracker_root
+      config.project_root = proj.path
+      config.version_path = proj.version_path
+      if proj.docs?
+        config.docs_root      = proj.docs_root
+        config.decisions_root = File.join(proj.docs_root, 'decisions')
+      end
+      config
+    end
+
+    private
+
+    def core_for(proj)
+      Core.new(config_for(proj))
+    end
+
+    def parse
+      return [] unless File.exist?(@path)
+
+      entries = []
+      current = nil
+
+      # Explicit UTF-8: the locale default (US-ASCII under LANG=C, the norm in
+      # containers and CI) raises on a non-ASCII project name (BT-179).
+      File.foreach(@path, encoding: 'utf-8') do |raw|
+        line = raw.scrub
+        if (m = line.match(/^## (.+)/))
+          entries << current if current
+          current = { name: m[1].strip, attrs: {} }
+        elsif current && (m = line.match(/^(\w+):\s*(.+)/))
+          current[:attrs][m[1]] = m[2].strip
+        end
+      end
+      entries << current if current
+
+      # build_project warns and returns nil for an unusable entry (no path, or a
+      # name that yields an empty namespace) instead of dropping it silently or
+      # building a broken project (BT-086).
+      results = entries.filter_map { |e| build_project(e) }
+
+      # Colliding slugs would route every request to the first match - suffix
+      # later duplicates so each project keeps a working board.
+      seen = Hash.new(0)
+      results.each do |p|
+        n = (seen[p.slug] += 1)
+        p.slug = "#{p.slug}-#{n}" if n > 1
+      end
+
+      results
+    end
+
+    def tracker_dir?(dir)
+      File.exist?(File.join(dir, 'backlog.md')) || File.exist?(File.join(dir, '.next-id'))
+    end
+
+    # An absent default root is silent - the project simply has no such surface.
+    # An explicit key that resolves nowhere is a typo and warns, the same way a
+    # missing 'path:' does (BT-ADR-0016).
+    def resolve_root(item, key, default, path)
+      given = item[:attrs][key]
+      root  = File.expand_path(given || default, path)
+      if given && !Dir.exist?(root)
+        warn "[BaconTracker] dashboard.md: #{item[:name].inspect} sets #{key}: #{given.inspect}, " \
+             "which does not exist (#{root})"
+      end
+      root
+    end
+
+    def build_project(item)
+      unless item[:attrs]['path']
+        warn "[BaconTracker] dashboard.md: skipping project #{item[:name].inspect} - no 'path:'"
+        return nil
+      end
+
+      slug      = BaconTracker.slugify(item[:name])
+      namespace = item[:attrs]['namespace'] || slug.upcase.gsub('-', '_')
+      if namespace.empty?
+        warn "[BaconTracker] dashboard.md: skipping project #{item[:name].inspect} - " \
+             "empty namespace (its name has no letters/digits; add an explicit 'namespace:')"
+        return nil
+      end
+
+      # Relative paths are relative to dashboard.md, not the process CWD.
+      path = File.expand_path(item[:attrs]['path'], File.dirname(@path))
+
+      # Compatibility (BT-134): a registry written before BT-ADR-0016 points
+      # 'path:' straight at the tracker directory. Detect that - a directory
+      # holding backlog.md or .next-id IS the tracker root - rather than
+      # silently showing an empty board, which is this codebase's worst failure
+      # mode. An explicit 'tracker:' always wins.
+      legacy = item[:attrs]['tracker'].nil? && tracker_dir?(path)
+
+      Project.new(
+        name:         item[:name],
+        slug:         slug,
+        path:         legacy ? File.dirname(path) : path,
+        namespace:    namespace,
+        version_path: item[:attrs]['version'],
+        tracker_root: legacy ? path : resolve_root(item, 'tracker', 'tracker', path),
+        docs_root:    resolve_root(item, 'docs', 'docs', legacy ? File.dirname(path) : path)
+      )
+    end
+  end
+end

data/lib/bacon_tracker/launcher.rb

@@ -0,0 +1,64 @@
+require 'rbconfig'
+require 'shellwords'
+
+module BaconTracker
+  # Opening a file in an editor, or revealing it in the file manager, is the
+  # one thing the board does outside its own files - and the only part that
+  # differs by platform. Everything else is plain Ruby file I/O.
+  #
+  # A missing launcher is reported, never swallowed: the endpoints answer 501
+  # with the reason, so the board can say so instead of claiming success.
+  module Launcher
+    class Unavailable < StandardError; end
+
+    module_function
+
+    def host_os = RbConfig::CONFIG['host_os']
+
+    def windows? = host_os.match?(/mswin|mingw|cygwin/)
+    def macos?   = host_os.include?('darwin')
+
+    # Show a file (or folder) in the file manager.
+    def reveal_argv(target)
+      if macos?
+        ['open', '-R', target]
+      elsif windows?
+        ['explorer.exe', "/select,#{target}"]
+      elsif which('xdg-open')
+        # xdg-open has no "select this file" - open the folder that holds it.
+        ['xdg-open', File.directory?(target) ? target : File.dirname(target)]
+      end
+    end
+
+    # Open a file in the user's editor. BACON_EDITOR wins and may carry
+    # arguments ("code -w"); otherwise the platform's default handler.
+    def open_argv(target)
+      editor = ENV['BACON_EDITOR'].to_s.strip
+      return Shellwords.split(editor) + [target] unless editor.empty?
+
+      if macos?
+        ['open', target]
+      elsif windows?
+        ['cmd.exe', '/c', 'start', '', target]
+      elsif which('xdg-open')
+        ['xdg-open', target]
+      end
+    end
+
+    # Fire and forget: the board never waits on an editor. No shell is
+    # involved - argv goes straight to exec, so a path is never interpreted.
+    def run(argv)
+      raise Unavailable, 'no launcher found on this system - install xdg-open or set BACON_EDITOR' unless argv
+
+      pid = Process.spawn(*argv, out: File::NULL, err: File::NULL)
+      Process.detach(pid)
+      nil
+    rescue SystemCallError => e
+      raise Unavailable, "could not run #{argv.first}: #{e.message}"
+    end
+
+    def which(cmd)
+      ENV['PATH'].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, cmd)) }
+    end
+  end
+end