kijito-tools 0.2.0

package/providers/monitor/RELEASING.md

@@ -0,0 +1,125 @@
+# Releasing
+
+Releases are automated with GitHub Actions Trusted Publishing (OIDC). No API tokens are stored
+anywhere. Pushing a version tag publishes to both PyPI and npm, with provenance attached.
+
+## Cut a release
+
+1. Bump the version to the same value in all THREE places:
+   - `pyproject.toml` -> `[project] version`
+   - `package.json` -> `"version"`
+   - `kijito_inbox_monitor.py` -> `__version__`
+   The third is easy to miss and this file used to omit it. It is not cosmetic: `__version__` builds
+   the `User-Agent` the watcher sends, so leaving it behind makes every request report the previous
+   release, and server-side logs then attribute traffic to a version that is not running.
+   Verify with: `grep -n '^version\|"version"\|^__version__' pyproject.toml package.json kijito_inbox_monitor.py`
+2. Add a section for the new version to `CHANGELOG.md`.
+3. Run the pre-publish gates. ALL FOUR (typography, memory-ids, path-escapes, private-detail) must report
+   clean, the exemption line must show nothing you expected to be inspected, and the canary must prove
+   the gate can still fire - a gate that cannot fail is worse than no gate, because it certifies:
+   ```sh
+   ./scripts/prepublish-gate.sh
+   ```
+   It re-derives the file list from `git ls-files` on purpose. A hardcoded list has been wrong twice,
+   and PyPI/npm metadata is immutable per version, so the descriptions in `pyproject.toml` and
+   `package.json` are exactly the text you cannot fix later.
+4. Commit, tag, and push:
+   ```sh
+   git commit -am "release: vX.Y.Z"
+   git tag -a vX.Y.Z -m "kijito-inbox-monitor vX.Y.Z"
+   git push origin main --follow-tags
+   ```
+5. The tag triggers `.github/workflows/publish-pypi.yml` and `publish-npm.yml`. Both publish
+   over OIDC, no tokens.
+6. Confirm BOTH registries independently - never trust the workflow's own report, because a
+   half-failure (one registry published, the other not) is the case that actually happens and a
+   version can never be re-uploaded:
+   ```sh
+   gh run watch
+   npm view kijito-inbox-monitor version
+   curl -s https://pypi.org/pypi/kijito-inbox-monitor/json | python3 -c 'import json,sys; print(json.load(sys.stdin)["info"]["version"])'
+   ```
+7. Create the GitHub Release for the tag:
+   ```sh
+   gh release create vX.Y.Z --title vX.Y.Z --notes-file <(sed -n '/## \[X.Y.Z\]/,/## \[/p' CHANGELOG.md)
+   ```
+   That `sed` range is INCLUSIVE, so it trails the next version's heading into the notes. Strip the
+   last line, or check the rendered release before you walk away.
+8. ⚠️ **PUBLISHING DOES NOT UPDATE THE FLEET, AND AFTER STEP 2 A RESTART ALONE DOES NOTHING EITHER.**
+   ⚠️ "STEP 2" HERE MEANS THE RECOVERY PLAN'S STEP 2 (repoint the launchd plist at a pinned artifact),
+   NOT step 2 of this file.
+   Once the plist points at a pinned artifact, the producer no longer reads the working tree, so a green PyPI/npm publish AND a restart both leave it on the OLD bytes. You must REBUILD /
+   REINSTALL the pinned artifact at the new version, repoint the plist, restart, and RE-VERIFY the health
+   block (exactly one process, `launchctl list` status 0, no PINNED/CORRUPT state files, zero
+   `bounded-window` alerts, heartbeat within ~2 min). `launchctl bootstrap` is not atomic - never assume
+   it came back.
+   ★ **THIS IS DONE-WHEN #7 AND THE RELEASE IS NOT COMPLETE WITHOUT IT.** Items 1-6 can all pass while the
+   fleet's only mail producer still runs the PRE-RELEASE artifact.
+
+## The producer runs a PINNED ARTIFACT - a restart deploys NOTHING
+
+✔ DONE 2026-07-27. `com.kijito.inbox-monitor` executes a read-only artifact under
+`~/.local/share/kijito-inbox-monitor/versions/<sha>/`, extracted with `git show <sha>:...` and checksum-
+asserted equal to the commit; both `ProgramArguments[2]` and `WorkingDirectory` point there. Confirm with
+`plutil -p ~/Library/LaunchAgents/com.kijito.inbox-monitor.plist`.
+⚠️⚠️ **THE CONSEQUENCE INVERTS THE OLD RULE, AND THIS IS THE DANGEROUS PART.** Editing the working tree,
+switching branches or committing changes NOTHING about what the fleet runs, and neither does a restart.
+**Anyone acting on the old "a restart IS the deploy" rule will deploy nothing and believe they deployed** -
+a no-op deploy and a successful one produce identical evidence (process up, status 0, heartbeat fresh,
+mail flowing), because those are properties of whatever is running, not of what you intended to run.
+★ TO DEPLOY: rebuild the artifact at the NEW sha, repoint BOTH plist paths, `bootout` -> wait for the pid
+to VANISH (~50s) -> `bootstrap`, then **assert the running process is that sha**. State the requirement as a
+PROPERTY, because the operator's own tooling is not part of this package:
+    THE RUNNING ARGV MUST CARRY THE EXPECTED SHA. Nothing else settles it.
+A self-contained check, which needs only a shell and a running producer:
+```sh
+# SHORT sha - the artifact directories are 7-char. A full 40-char rev-parse of the CORRECT running
+# commit FAILS this check, and it fails mid-release, which is exactly when a false alarm gets
+# "fixed" by loosening the check that was right.
+sha=$(git rev-parse --short <ref>)
+procs=$(pgrep -f 'kijito_inbox_monitor\.py' || true)
+n=$(printf '%s' "$procs" | grep -c . || true)
+[ "$n" -eq 1 ] || { echo "FAIL: expected exactly 1 producer, found $n"; exit 1; }
+ps -o command= -p "$procs" | grep -q "/versions/$sha/" \
+  && echo "ok: the single running producer carries $sha" \
+  || { echo "FAIL: the running argv does not carry $sha"; exit 1; }
+```
+⚠️ The process COUNT is asserted first and is not decoration: with an old and a new producer both alive, a
+bare match on the expected sha SUCCEEDS while the fleet is still partly serving the old bytes. Verified in
+all three directions (right sha, wrong sha, two processes) before being written down.
+Health alone cannot tell a successful deploy from a no-op one; only naming the expected sha can.
+⚠️ This file previously named a helper script by a RELATIVE PATH that pointed OUTSIDE the repository, so a
+clone could not run the gate this document mandates - and the path would silently resolve to whatever
+happened to sit above the checkout. The fleet operator's richer health tool lives in the private workspace
+alongside this repo, deliberately outside it; it is not required to perform a release, and no public
+instruction may depend on a path a clone does not contain.
+Before touching launchctl: `bootout` + `bootstrap` (never `kickstart`), never back-to-back (they race ->
+"Bootstrap failed: 5" leaving NO service), SIGTERM takes ~50s, copy the current plist aside as a rollback
+FIRST, and announce the restart to the hive - this is the fleet's only mail producer.
+⚠️ "Released artifact" does NOT mean a PyPI release. Reading it that way made the plan circular (repoint
+needs a release -> release needs a GREEN audit -> the audit was meant to follow the repoint). Install the
+audited SHA as a LOCAL versioned artifact: a built wheel, or a read-only checkout at the tag.
+(This section previously said the producer "does not run this package (yet)" and "currently executes the
+WORKING TREE directly", four lines after item 8 said the opposite. It was stale from the moment step 2
+landed, and the stale half was the one that would cause a silent no-op deploy - re-audit 11, F4.)
+
+## One-time setup (already done for 0.1.0)
+
+- PyPI: a Trusted Publisher is configured for the project (this repo + `publish-pypi.yml` + the
+  `pypi` environment).
+- npm: a Trusted Publisher is configured for the package.
+- GitHub: a `pypi` environment exists in repository settings.
+
+## Notes
+
+- A published version can never be re-uploaded. To fix a mistake, bump to the next patch version.
+- npm cannot use OIDC for the very first publish of a brand-new package, so that one is manual;
+  every version after it publishes over OIDC.
+- Keep public-facing text free of em-dashes and internal references before tagging. That includes
+  the README, the design doc, the script docstring and `--help` text, and the PyPI/npm
+  descriptions, not just Markdown. Step 3 enforces this; the prose here is the rationale, not the
+  check. A gate that lives only in prose does not run.
+- Beware the shell when writing any gate by hand. `FILES=$(git ls-files); grep -nE ... $FILES` does
+  NOT word-split in zsh: grep receives one nonexistent filename, exits non-zero, and an
+  `|| echo clean` reports success while having inspected nothing. That exact false clean was
+  observed in this repo. The script pipes NUL-delimited paths into `xargs -0` for this reason.

package/providers/monitor/arm-hive-monitor.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+DIR=$(CDPATH= cd "$(dirname "$0")" && pwd)
+STATE_FILE="${KIJITOMON_STATE_FILE:-$HOME/.cache/kijito-inbox-monitor/hive.json}"
+
+# Default to stdout (interactive). For a SUPERVISED producer, set KIJITOMON_EVENTS_FILE to an owned,
+# size-rotated events log that survives rotation (see --events-file). Do not redirect stdout to the log.
+set -- --state-file "$STATE_FILE" "$@"
+[ -n "${KIJITOMON_EVENTS_FILE_TEMPLATE:-}" ] && set -- --events-file-template "$KIJITOMON_EVENTS_FILE_TEMPLATE" "$@"
+[ -n "${KIJITOMON_EVENTS_FILE:-}" ] && set -- --events-file "$KIJITOMON_EVENTS_FILE" "$@"
+
+exec python3 -u "$DIR/kijito_inbox_monitor.py" "$@"

package/providers/monitor/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// kijito-inbox-monitor on npm is a SIGNPOST, not an installer.
+//
+// The real tool is a pure-Python package on PyPI. Building a Node installer for a
+// Python tool is fragile (it would need Node AND Python AND pipx all on PATH), so
+// this package does not install anything. It only:
+//   1. delegates to the Python tool via uvx / pipx run if either is present, or
+//   2. prints how to install it and exits non-zero.
+// There is deliberately no postinstall hook (npm v12 disables install lifecycle
+// scripts by default, and that hook is the supply-chain-worm pattern).
+
+const { spawnSync } = require('node:child_process');
+
+function present(cmd) {
+  const r = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
+  return !r.error && (r.status === 0 || r.status === null);
+}
+
+const args = process.argv.slice(2);
+
+// Prefer uvx (fast), then `pipx run`. Both run the published PyPI package without a
+// persistent install, which is the right zero-friction path for a one-off invocation.
+for (const [cmd, prefix] of [['uvx', []], ['pipx', ['run']]]) {
+  if (present(cmd)) {
+    const r = spawnSync(cmd, [...prefix, 'kijito-inbox-monitor', ...args], {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    process.exit(r.status ?? 1);
+  }
+}
+
+process.stderr.write(
+  'kijito-inbox-monitor is a Python tool; this npm package is only a pointer to it.\n' +
+  'Install the real tool with one of:\n' +
+  '  pipx install kijito-inbox-monitor\n' +
+  '  uv tool install kijito-inbox-monitor\n' +
+  '  pip install kijito-inbox-monitor\n' +
+  'then run:  kijito-inbox-monitor --help\n' +
+  'Docs: https://github.com/KijitoAI/kijito-inbox-monitor\n'
+);
+process.exit(1);

package/providers/monitor/com.kijito.inbox-monitor.plist.template

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  TEMPLATE - substitute the three placeholders before loading. This file is NOT loadable as-is, and
+  that is deliberate: it previously shipped one operator's absolute home directory baked into seven
+  paths, which is useless to you and leaks the layout of a machine you do not have.
+
+    __PYTHON__       absolute path to the interpreter, e.g. /usr/bin/python3 or /opt/homebrew/bin/python3
+                     (launchd does not search PATH, so this must be absolute)
+    __PROGRAM__      absolute path to the kijito_inbox_monitor.py you want to run
+    __HOME__         your home directory (the value of $HOME)
+
+  Install:
+    sed -e 's|__PYTHON__|'"$(command -v python3)"'|' \
+        -e 's|__PROGRAM__|'"$HOME/.local/share/kijito-inbox-monitor/versions/<sha>/kijito_inbox_monitor.py"'|' \
+        -e 's|__HOME__|'"$HOME"'|' \
+        com.kijito.inbox-monitor.plist.template > ~/Library/LaunchAgents/com.kijito.inbox-monitor.plist
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.kijito.inbox-monitor.plist
+
+  ⚠️ POINT __PROGRAM__ AT A PINNED, READ-ONLY ARTIFACT, NOT AT A WORKING TREE. If it points at a
+  checkout, "deploying" by publishing a package leaves the producer on whatever the tree happens to
+  contain, and a restart does not change that - you will believe you deployed and have not. Rebuild
+  the artifact, repoint this file, restart, then assert the running argv carries the expected short
+  sha (RELEASING.md has the check).
+
+  ⚠️ The token file must be mode 0600; the producer refuses a world-readable one.
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.kijito.inbox-monitor</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__PYTHON__</string>
+    <string>-u</string>
+    <string>__PROGRAM__</string>
+    <string>--token-file</string>
+    <string>__HOME__/.config/kijito-inbox-monitor/token</string>
+    <string>--state-file</string>
+    <string>__HOME__/.cache/kijito-inbox-monitor/hive.json</string>
+    <string>--events-file-template</string>
+    <string>__HOME__/.cache/kijito-inbox-monitor/events.{persona}.ndjson</string>
+    <string>--heartbeat</string>
+    <string>120</string>
+    <string>--no-content</string>
+  </array>
+  <key>StandardOutPath</key>
+  <string>__HOME__/.cache/kijito-inbox-monitor/monitor.out</string>
+  <key>StandardErrorPath</key>
+  <string>__HOME__/.cache/kijito-inbox-monitor/monitor.err</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+</dict>
+</plist>