xumret 0.1.0__tar.gz

xumret-0.1.0/.claude/skills/code-deps/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: code-deps
+description: "Manage Python/Node dependencies in this project. Use this to install/update deps in the smooth way."
+allowed-tools: [Read, Edit, Bash, Glob, Grep]
+---
+
+# code-deps — Dependency Management
+
+Manage Python and Node dependencies for the xumret project. This skill covers adding, removing, upgrading, and troubleshooting packages.
+
+## Critical Rules
+
+- **NEVER run `pip install` or `uv pip install` directly.** Always add the package to `requirements.txt` first, then run `make deps`.
+- **NEVER edit `venv/` contents manually.** The venv is managed by uv via the Makefile.
+
+## Python Dependencies
+
+### Layout
+
+| Path | Purpose |
+|---|---|
+| `requirements.txt` | All Python deps (pinned and unpinned) |
+| `Makefile` | `deps`, venv creation targets |
+| `venv/` | The uv-managed virtualenv (Python 3.13) |
+
+### Adding a New Python Package
+
+1. **Edit `requirements.txt`**: Add the package. Don't add a version — uv will find the latest compatible version.
+2. **Install**: Run `make deps`
+3. **Verify**: The Makefile target uses `uv pip install -r requirements.txt` under the hood. It touches `venv/.deps_installed` as a sentinel file so subsequent `make deps` calls are no-ops unless `requirements.txt` changes.
+
+### Shared library (`ihate_work`)
+
+The `local-ihate-work` package is installed from GitHub (not a local editable tree):
+
+```
+local-ihate-work @ git+https://github.com/ihate-work/ihate-library
+```
+
+This provides `ihate_work.o11y`, `ihate_work.util`, etc. To upgrade to the latest commit, run:
+
+```bash
+uv pip install --force-reinstall "local-ihate-work @ git+https://github.com/ihate-work/ihate-library"
+```
+
+Or delete the venv and reinstall: `make clean && make deps`.
+
+### Removing a Python Package
+
+1. Remove the line from `requirements.txt`.
+2. Run `make deps`. Note: uv may not uninstall the removed package from the existing venv automatically. If a clean state is needed, run `make clean && make deps` to recreate.
+
+### Venv Details
+
+- **Location**: `venv/`
+- **Python version**: 3.13 (set by `PYTHON_VER` in Makefile)
+- **Created by**: `uv venv --clear --python=3.13 venv`
+- **Sentinel files**: `venv/.venv_created` (venv exists), `venv/.deps_installed` (deps are current)
+- **Environment variables used during install**: `UV_PYTHON=venv UV_LINK_MODE=symlink`
+- **Interpreter path**: `venv/bin/python`
+
+To recreate the venv from scratch: `make clean && make deps`.
+
+### Troubleshooting Python Deps
+
+- **`ModuleNotFoundError`**: Check that the package is in `requirements.txt` and run `make deps`. If the sentinel file is up to date but the package is missing, delete `venv/.deps_installed` and re-run.
+- **Stale venv**: Run `make clean && make deps` to get a clean state.
+- **`make deps` is a no-op but packages are missing**: The sentinel `venv/.deps_installed` may be newer than `requirements.txt`. Run `touch requirements.txt && make deps` to force reinstall.
+
+## Node Dependencies (Web UI)
+
+### Layout
+
+| Path | Purpose |
+|---|---|
+| `package.json` | JS deps for the web UI |
+| `package-lock.json` | Lockfile (committed) |
+
+### Adding a New Node Package
+
+```bash
+npm install <package-name>
+```
+
+For dev dependencies:
+
+```bash
+npm install -D <package-name>
+```
+
+### Installing
+
+```bash
+make webui-deps
+```
+
+This runs `npm ci` and touches `node_modules/.webui_deps_installed` as a sentinel.
+
+### Troubleshooting Node Deps
+
+- **Module not found**: Run `npm ci` to reinstall from the lockfile.
+- **Lockfile conflicts**: Delete `node_modules/` and `package-lock.json`, then run `npm install` to regenerate. Only do this as a last resort.

xumret-0.1.0/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: code-review
+description: "Review changed code for correctness, readability, testability, security, and adherence to project conventions. Checks multiple perspectives and flags issues with concrete suggestions."
+allowed-tools: [Read, Glob, Grep, Bash, Agent]
+---
+
+# code-review — Multi-Perspective Code Review
+
+Review the specified code (files, diff, or staged changes) from multiple perspectives, flagging issues with concrete suggestions.
+
+## Steps
+
+### 1. Determine what to review
+
+- If the user specifies files or a diff range, use that.
+- If nothing is specified, review the current uncommitted changes: run `git diff HEAD` (and `git diff --cached` for staged changes).
+- Read every file that has changes. Do not review code you haven't read.
+
+### 2. Read project conventions
+
+Read `doc/dev.md` to load the current review checklist and project conventions. These are authoritative — violations are must-fix, not nits.
+
+Also read `CLAUDE.md` for project-specific rules (Web UI rules, o11y conventions, etc.).
+
+### 3. Review from each perspective
+
+Evaluate every changed file against all perspectives listed in the "Code Review Checklist" section of `doc/dev.md`, plus the conventions defined earlier in that file (Principles, o11y, pytest, dotenv) and the project-specific rules in `CLAUDE.md`.
+
+Only report findings that are actionable — skip a perspective if there's nothing to flag.
+
+### 4. Report findings
+
+Present findings grouped by file path. For each finding:
+
+1. **File and line reference** — `path/to/file.py:42`
+2. **Perspective** — which review lens caught it (e.g. Correctness, Convention)
+3. **Issue** — one-line description
+4. **Suggestion** — concrete fix or direction (show code when helpful)
+
+Use the severity levels from `doc/dev.md`.
+
+### 5. Summary
+
+End with a brief summary:
+- Total findings by severity
+- Overall assessment (ship it / needs changes / needs rethink)
+- If the code is clean, say so — don't invent issues.
+
+## Rules
+
+- Do not suggest changes you haven't verified against the actual code.
+- Do not flag things that are already handled correctly.
+- Do not add noise — if the code is good, the review should be short.
+- Convention violations from `doc/dev.md` and `CLAUDE.md` are must-fix, not nits.

xumret-0.1.0/.claude/skills/code-work/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: code-work
+description: "Implement a milestone or task from a project plan. Reads the plan, picks up the next task, writes code + tests, runs them, and marks it done."
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent]
+---
+
+# code-work — Implement a Plan Task
+
+Pick up a milestone or task from a project's plan doc, implement it with tests, and mark it done.
+
+## Steps
+
+### 1. Load the plan and conventions
+
+- Read the plan doc specified by the user.
+- Read `doc/dev.md` for project-wide coding conventions.
+- Read `CLAUDE.md` for project-specific rules.
+- Read the `Makefile` to understand how to run tests and install deps.
+
+### 2. Determine what to work on
+
+- If the user specifies a task or milestone, use that.
+- If not, pick the first unchecked `- [ ]` item in the plan.
+- Read all existing code that the task will touch or depend on before writing anything.
+
+### 3. Implement
+
+Write code that follows these rules:
+
+- **Readable, testable, minimal.** Only implement what the task asks for. Don't refactor surrounding code, add speculative features, or over-abstract.
+- **Match existing patterns.** Read neighboring code and follow the same style, naming, imports, and structure. New code should look like it was written by the same person.
+- **Stable APIs.** Exported functions get a short docstring and a stable signature. Internal helpers do not need docstrings.
+- **Comments are for "why".** Use code for "what" and "how". Only comment when the reason behind a choice isn't obvious.
+- **Follow plan-level notes.** The plan doc may include project-specific conventions or constraints — read and follow them.
+
+### 4. Write tests
+
+Every task that adds or changes behavior must include tests.
+
+- Test file naming: `TESTEE_test.py`.
+- Tests live **beside** the testee module (same directory), not in a separate `tests/` tree.
+- Test behavior, not implementation. Prefer round-trip tests over mocking internals.
+- Keep tests fast and independent.
+
+### 5. Run tests
+
+- Run `make test` to execute the test suite.
+- All tests must pass before the task is considered done. If a test fails, fix the code or the test — don't skip or delete it.
+- Run `make format` before finishing.
+
+### 6. Update the plan
+
+In the plan doc, change `- [ ]` to `- [x]` for the completed task. Do not modify other tasks.
+
+### 7. Summarize
+
+Tell the user:
+- Which task was completed
+- What files were created or changed
+- Any design decisions you made (and why)
+- Anything you noticed that affects upcoming tasks
+
+## Rules
+
+- Do not start coding before reading the existing code that your task touches.
+- Do not change code outside the scope of the current task.
+- Do not mark a task done if tests don't pass.
+- If a task is ambiguous or blocked by an unresolved design decision in the plan, stop and ask the user rather than guessing.
+- One task per invocation. If the user asks for a whole milestone, work through tasks sequentially — finish and verify each one before starting the next.

xumret-0.1.0/.claude/skills/journal-save/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: journal-save
+description: "Please create or update journals/YYYYMMDD-{pid}-{topic}.md to document this session's work. Especially the intention, investigations, quirks, experiments, actual changes."
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash]
+---
+
+# journal-update — Document This Session's Work
+
+Create or update a journal entry capturing what happened in this conversation — the intent, investigations, discoveries, quirks, experiments, and actual changes made.
+
+## Steps
+
+### 1. Determine the journal filename
+
+The filename format is: `journals/YYYYMMDD-p{PID}-{topic}.md`
+
+- Get the Claude Code PID via `echo $PPID` (stable across all bash calls in a session)
+- Infer a 2-3 word kebab-case topic from the session's work (e.g. `ws-protocol`, `webui-layout`, `executor-refactor`). Prefer the verb-object pattern. The topic should always be inferable from the conversation — never use `unknown`.
+
+Example: `journals/20260324-p3593122-ws-protocol.md`
+
+### 2. Find or create the journal file
+
+One PID may have multiple journals (the user can `/clear` and start a new topic within the same Claude Code process). Search for all journals with this PID:
+
+```
+journals/*-p${PPID}-*.md
+```
+
+If matches exist:
+1. Read the first ~10 lines of each match (frontmatter + title) to understand its topic
+2. If the current session's work fits an existing file's topic, update that file (append a new dated section — don't rewrite history)
+3. If the current work is a clearly different topic from all existing files, create a new file
+
+If no matches exist, create a new file.
+
+### 3. Gather context
+
+Run `echo $HOST $USER` to find hostname and username to populate the frontmatter with. Then collect the following from the conversation history — do NOT run extra exploratory commands:
+
+- **Intent**: What did the user ask for? What was the goal?
+- **Investigations**: What did we read, search, or explore to understand the problem?
+- **Discoveries / Quirks**: Anything surprising, non-obvious, or worth remembering (gotchas, undocumented behavior, edge cases).
+- **Experiments**: Anything we tried that didn't work, and why.
+- **Changes**: What files were actually created, modified, or deleted? Summarize the substance of each change.
+- **Open threads**: Anything unfinished, deferred, or worth revisiting.
+
+### 4. Write the journal entry
+
+Use this template:
+
+```markdown
+---
+date: {YYYY-MM-DD HH:MM}
+branch: {current git branch}
+host: {hostname}
+user: {username}
+tldr: {One-sentence summary of the session's outcome}
+---
+
+# Journal: {brief title}
+
+## Intent
+
+{What the user wanted to accomplish.}
+
+## What happened
+
+{Narrative of the work — investigations, key decisions, pivots. Keep it concise but useful to future-you skimming old entries. Use subsections if the session covered multiple distinct topics.}
+
+## Discoveries / Quirks
+
+{Bullet list of non-obvious things learned. Omit this section if nothing surprising came up.}
+
+## Changes
+
+{Bullet list of files changed and what was done to each. Group by topic if the session touched multiple areas.}
+
+## Open threads
+
+{Anything left unfinished or worth revisiting. Omit if everything is wrapped up.}
+```
+
+### 5. Guidelines
+
+- Be concise but specific. The journal is for the user to skim later, not a transcript.
+- Focus on *why* and *what was surprising*, not mechanical play-by-play.
+- Use code references (`file:line`) where they help.
+- If updating an existing entry, append a new dated section rather than rewriting history.
+- Don't editorialize or add filler — if a section has nothing useful, omit it.

xumret-0.1.0/.claude/skills/journal-search/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: journal-search
+description: "Search past journal entries to answer questions about previous sessions — what was done, what was discovered, what changed, and what's still open."
+allowed-tools: [Read, Glob, Grep, Bash]
+---
+
+# journal-search — Answer Questions from Past Journals
+
+Search and synthesize information from journal entries in `journals/` to answer the user's question about previous work sessions.
+
+## Steps
+
+### 1. Understand the question
+
+Identify what the user is asking about. Common queries:
+
+- **What/when**: "What did we do about X?", "When did we change Y?"
+- **Why**: "Why is Z implemented this way?"
+- **Discoveries**: "What gotchas did we find about X?"
+- **Open threads**: "What's left unfinished?"
+- **Changes**: "What files were touched for feature X?"
+
+### 2. Search journals
+
+Journals live in `journals/*.md` and have YAML frontmatter with `pid`, `date`, `branch`, `host`, `user`, `tldr`.
+
+#### Strategy
+
+0. Use `git grep` when possible.
+
+1. **Start with grep** — search for keywords from the user's question across all journals:
+   ```
+   grep -li <keyword> journals/*.md
+   ```
+   Use multiple keywords in parallel if the question has several concepts.
+
+2. **If grep finds matches**, read the matching files. Start with frontmatter + title (first ~10 lines) to assess relevance, then read the full file for relevant ones.
+
+3. **If grep finds nothing**, broaden: try synonyms, related terms, or list all journals and scan their `tldr` fields:
+   ```
+   grep "^tldr:" journals/*.md
+   ```
+
+4. **For time-based queries** ("last week", "recently"), list journals sorted by date and read the most recent ones:
+   ```
+   ls -t journals/*.md
+   ```
+
+### 3. Synthesize an answer
+
+- Answer the user's question directly, citing specific journal entries by filename and section.
+- Use `journals/filename.md` references so the user can find the source.
+- If the answer spans multiple sessions, present it chronologically.
+- If journals contain contradictory information, flag it — the more recent entry is likely more accurate.
+- If no journals are relevant, say so clearly rather than guessing.
+
+### 4. Guidelines
+
+- Be concise. The user wants an answer, not a journal dump.
+- Quote specific discoveries/quirks verbatim when they're the answer — these are the high-value bits.
+- If the question is about open threads, check whether later journals resolved them.
+- Don't fabricate information that isn't in the journals. If the journals don't cover the topic, say so.

xumret-0.1.0/.claude/skills/wit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: wit
+description: "Record a small idea or design thought to doc/wits.md. Use when the user has a loose idea, observation, or future-facing thought they want to capture."
+allowed-tools: [Read, Edit, AskUserQuestion]
+---
+
+# wit — Capture a design thought
+
+The user has an idea or observation they want to land in `doc/wits.md`. Your job is to **interview** them until the intent is sharp, then write a concise entry.
+
+## The file
+
+Read `doc/wits.md` first to understand the existing format and entries.
+
+Entries live under dated `##` sections, sorted date DESC (newest at top, right after the header block). Each entry is a checkbox line followed by indented detail lines.
+
+## Interview
+
+The user may provide the idea inline (e.g. `/wit we should cache device state`) or just invoke `/wit` bare.
+
+Either way, ask clarifying questions using AskUserQuestion until you can answer ALL of these:
+
+1. **What** — the concrete idea (feature, API shape, behavior, constraint)
+2. **Why** — the motivation or problem it solves
+3. **Decisions** — any choices already made or explicitly deferred
+
+Keep the interview short. 1-3 questions max. If the user's initial description already covers everything, skip straight to writing. Do NOT over-interview obvious ideas.
+
+## Write the entry
+
+Each entry must be **very concise** — this is a scratchpad, not a design doc. But it must not lose intent, rationale, or decisions.
+
+Format:
+
+```markdown
+## YYYY-MM-DD
+
+- [ ] one-line summary of the idea
+    — detail line: rationale, constraints, decisions. Use em-dash prefix for continuation lines. Multiple detail lines are OK if needed, but keep each short.
+```
+
+If there are already entries under today's `## YYYY-MM-DD` section, append to that section instead of creating a duplicate date header.
+
+### Rules
+
+- Use today's date. Get it from context or `date +%Y-%m-%d`.
+- Sort sections date DESC — newest `##` section goes first (right after the file's top-level header block ending at the first `##`).
+- Never modify existing entries.
+- Never mark entries as done (`[x]`).
+- The summary line should be concrete enough that someone reading it months later understands the idea without expanding context.

xumret-0.1.0/.github/workflows/check.yaml

@@ -0,0 +1,26 @@
+name: Check
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  check:
+    name: Run tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: PYTHON_VER=${{ matrix.python-version }} make deps
+
+      - run: make test

xumret-0.1.0/.github/workflows/publish-pypi.yaml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/xumret
+    permissions:
+      id-token: write # mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+
+      - name: Build
+        run: python3 -m build --wheel --sdist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

xumret-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# python
+build
+.venv
+venv
+*.pyc
+__pycache__
+*.egg-info
+
+# tools
+.mypy_cache
+.pytest_cache
+.ruff_cache
+htmlcov
+.coverage
+
+# env
+.env
+.env.local
+
+# project
+/logs
+
+# misc
+.DS_Store
+*.log
+node_modules

xumret-0.1.0/.gitmodules

@@ -0,0 +1,9 @@
+[submodule "vendor/termux-api"]
+	path = vendor/termux-api
+	url = https://github.com/termux/termux-api
+[submodule "vendor/termux-app"]
+	path = vendor/termux-app
+	url = https://github.com/termux/termux-app
+[submodule "vendor/termux-api-package"]
+	path = vendor/termux-api-package
+	url = https://github.com/termux/termux-api-package

xumret-0.1.0/AGENTS.md

@@ -0,0 +1,44 @@
+This directory contains `xumret`, a remote control solution for termux and termux-api.
+
+Please check README.md to grasp the idea of the project.
+
+Please check doc/architecture.md to understand the components and roles.
+
+## Code
+
+- src/ : python code for server and clients
+
+- webui-src/ : React+TypeScript source for the controller UI. Built output goes to webui-assets/.
+
+## Vendor packages
+
+The dependency `termux-api` `termux-app` `termux-api-packages` repositories are added as git submodules for reference.
+
+Their code schematic is [indexed](doc/termux-schematic.md). Please refer to (and update if needed) the index to save your and human's energy.
+
+## Shared library
+
+Depends on `local-ihate-work` from `../ihate_library` (editable install). Provides `ihate_work.o11y` for observability.
+
+## Web UI rules
+
+- **PrimeReact is the ONLY component library.** Use PrimeReact components unconditionally for all UI (buttons, inputs, layout, data display, overlays, etc.). Do NOT use Tailwind CSS, custom utility classes, or other component libraries.
+- Theme: `lara-light-cyan` (imported in `main.tsx`). Use PrimeReact's built-in theming/styling — do not override with raw CSS unless absolutely necessary.
+- PrimeIcons for all icons (`primeicons` package).
+- Entry point: `webui-src/main.tsx`. Vite config + tsconfig at repo root.
+- Build: `make webui-dev` (dev server), `npm run build` (production → webui-assets/).
+
+## Wits
+
+`doc/wits.md` is a living scratchpad of small design ideas and decisions. When you encounter or make a non-obvious design choice worth preserving, add it there. Keep entries very concise — intent + rationale, one or two lines.
+
+## Coding rules
+
+Inherited from vibra conventions:
+
+- **o11y**: Use `ihate_work.o11y` exclusively (not stdlib `logging.getLogger()`). structlog uses keyword args, not printf-style. `setup_otel()` / `setup_structlog()` called exactly once at entry point (`__main__.py`).
+- **Data models**: Pydantic `BaseModel` by default for structured records. Keyword args only.
+- **No mutable globals**: Wire deps through constructor args or framework DI.
+- **Tests**: Named `TESTEE_test.py`. Run with `make test`.
+- **dotenv**: Always `load_dotenv(override=False)`.
+- **Formatting**: ruff (line-length 100, select E/F/I/N/W/UP).

xumret-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md