Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-PUBLISH(1)                     HEE Tools                     HEE-PUBLISH(1)

NAME
       hee-publish - 0-token activity summary, gated before it prints

SYNOPSIS
              hee-publish -blog OPER -range "N UNIT" [-context CONTEXT]
                          [--i-reviewed-manually]
              hee-publish help

DESCRIPTION
              Renders a markdown summary of one GitHub identity's recent public
              activity to stdout. Deterministic aggregation from real recorded
              events -- no model is called at runtime, which is the point: the
              output cannot hallucinate work that did not happen.

              The source is `gh api users/OPER/events?per_page=100`: ONE page, so at
              most 100 events, and GitHub's own Events API only serves recent
              activity regardless of the range you ask for. A wide -range does not
              reach further back than the API itself does.

              Output is one heading, the since-timestamp, any notes, then one bullet
              per event, newest first:

                  - **HH:MM:SS** [`owner/repo`] <what happened>

              Only six event types render -- issues, issue comments, pull requests,
              PR reviews, pushes and creates. Every other event type in the window is
              silently dropped, as is any event whose payload does not have the
              fields the renderer expects. The bullet count is therefore not the
              event count.

OPTIONS
              -blog OPER              GitHub login whose events are read. Required.
              -range "N UNIT"         How far back. Required. Quote it -- it is one
                                      argument with a space in it. UNIT is one of:
                                        min  minutes
                                        hrs  hours
                                        day  days
                                        wks  weeks
                                        sess sessions -- NOT really implemented. No
                                             state-capsule lookup is wired up, so N is
                                             ignored and the window is a flat 6 hours,
                                             with a note printed in the output saying
                                             exactly that. A stated default, never a
                                             faked session boundary.
              -context CONTEXT        Free text used in the heading only. Default:
                                      summary. It does not change what is collected.
              --i-reviewed-manually   Only affects the case where the content scanner
                                      is unavailable: prints a loud banner to stderr
                                      and publishes anyway. It cannot suppress real
                                      findings.

ENVIRONMENT
              No environment variables are read directly. `gh` must be installed and
              authenticated, and hee-filter must sit next to this script -- it is
              invoked by absolute path from this file's own directory. See
              `hee-filter help` for the cache and scanner paths it needs.

EXIT STATUS
              Nagios plugin convention.
              0 OK        summary printed, both gates passed
              1 WARNING   a gate failed or a lookup failed -- the content scan found
                          something, the scanner was unavailable without the
                          override, `gh api` failed, or -range was malformed. Nothing
                          is printed to stdout in any of these cases. Note: the org
                          vocabulary would put several of these at 2 CRITICAL; the
                          tool really exits 1 today and is documented as-is, not
                          changed here.
              2 CRITICAL  argparse usage error -- -blog or -range missing

EXAMPLES
              hee publish -blog touchy-claude -range "7 days"

              Not marked "# ci": it reads git history over a range and is gated on a
              content scan, so it is neither deterministic nor self-contained on a runner.

              hee-publish -blog spencerbutler -range "6 hrs"
              hee-publish -blog spencerbutler -range "2 wks" -context "sprint recap"

SEE ALSO
              hee-filter, contracts/publish-sanitization-v1.contract.yaml

SAFETY
              Two gates run before a single line reaches stdout, both delegated to
              hee-filter so there is one implementation, not a copy:

              1. Repo visibility. A user's event feed includes activity in every repo
                 that identity can see, private ones included. Every repo touched is
                 checked live and private ones are DROPPED BEFORE RENDERING, not
                 redacted after. The output states how many were excluded and names
                 them -- the names are already known to whoever ran the command.
              2. Content scan. The surviving text still comes from commit messages
                 and issue titles, which can themselves carry something sensitive, so
                 the fully rendered output is scanned before printing. If the scanner
                 is unavailable this tool prints NOTHING and fails rather than
                 skipping the scan silently.

                                                                 HEE-PUBLISH(1)