utils/README.md
Krzysztof kuhy Rudnicki 4531be3870
Some checks failed
dependency freshness / dependencies on newest stable (push) Waiting to run
file length / file-length (push) Waiting to run
godot_dev_tools tests / test (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
game_recording pre-commit / pre-commit (push) Has been cancelled
game_recording tests / test (push) Has been cancelled
List the two game packages in the root
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V
2026-11-16 14:29:49 +01:00

5.4 KiB

utils

Shared libraries used across kuhyx's other projects. Each subdirectory is a formerly-standalone repo, folded in here with full commit history preserved (see each subdirectory's own git log for its pre-merge history).

crdt_sync_dart/

Dart/Flutter CRDT sync library (pub package name: crdt_sync, not published to pub.dev — consumed via a git dependency). Mirrors crdt-sync (below) module-for-module and test-for-test. Consumed by diet_guard's app, screen-locker's workout_app, wake_alarm's phone_app, and todo (whose notes are stored in the v0.2.0 LogStore).

Consume via:

dependencies:
  crdt_sync:
    git:
      url: https://github.com/kuhyx/utils
      ref: crdt_sync_dart-v0.10.0
      path: crdt_sync_dart

sync_settings_ui/

Shared Flutter "Sync settings" screen (pub package name: sync_settings_ui, not published to pub.dev). Firebase sync (primary) plus an optional local backup slot — no GitHub mirror UI. Pure UI + a FirebaseSyncController service layer over injected closures (keystore/Google-plugin access stays in each consuming app, exactly as before this package existed). Consumed by todo, diet_guard_app, workout_app, wake_alarm/phone_app, and home_inventory's dedicated "Sync settings" route.

Consume via:

dependencies:
  sync_settings_ui:
    git:
      url: https://github.com/kuhyx/utils
      ref: sync_settings_ui-v0.1.0
      path: sync_settings_ui

google_account_token/

Flutter plugin (Android only; other platforms return null): one-tap Google ID token via AccountManager, replacing google_sign_in in the sync apps.

Consume via:

dependencies:
  google_account_token:
    git:
      url: https://github.com/kuhyx/utils
      ref: google_account_token-v0.1.0
      path: google_account_token

crdt-sync/

Python CRDT sync library (package: crdt_sync, not published to PyPI). Same design as crdt_sync_dart (HLC clocks, per-field LWW, sticky-delete tombstones). Consumed by diet-guard and screen-locker.

Consume via:

crdt-sync @ git+https://github.com/kuhyx/utils@crdt-sync-v0.2.0#subdirectory=crdt-sync

guard-lib/

Bash tamper-resistance primitives (guardctl: chattr + bind-mount + systemd watcher + pacman hooks). Not a package — installed by running guard-lib/install.sh as root, which copies files onto the system (/usr/local/bin, /usr/local/lib/guard-lib, systemd units, pacman hooks). Consumed by steam-backlog-enforcer (expects a guard-lib/install.sh sibling clone) and referenced by screen-locker.

gatelock/

Python lock-window + HMAC log-integrity backend (package: gatelock, not published to PyPI). Consumed via pip by screen-locker, diet-guard, and wake-alarm:

gatelock @ git+https://github.com/kuhyx/utils@gatelock-v0.1.0#subdirectory=gatelock

music_theory/

Music theory from first principles as typed Python (package: music_theory, not published to PyPI): pitch, tuning, scales, chords, progressions, a numpy synth and a Recipe → WAV composer with a degrade transform. Follows Luke Haas's "Music Theory for Programmers" section by section; python -m music_theory demo all --out DIR renders one WAV per section. Consumed by roadside-assistance for its three world-state music beds.

Consume via:

music_theory @ git+https://github.com/kuhyx/utils@music-theory-v0.1.0#subdirectory=music_theory

game_recording/

Session recorder for a game (package: game_recording, stdlib only, not published to PyPI): records a dev run from outside the game and stamps its telemetry moments onto the video. A game configures it with one Config.

Consume via:

game_recording @ git+https://github.com/kuhyx/utils@game-recording-v0.1.0#subdirectory=game_recording

unified-design-system/

Not a package — the frozen design tokens (colors, spacing, type, radius, shadow policy) and per-stack (Flutter/web/Tkinter) implementation patterns that keep every one of kuhy's repos visually identical, plus annotated component references (components.html, button.html). Read unified-design-system/README.md and DOCS-tokens.md before touching any theme/CSS/style file in any repo. The unified-design-system Claude Code skill is a thin pointer here, not a duplicate.

ts_config/

@kuhyx/ts-config — the one lint / TypeScript bar every kuhyx TypeScript repo extends (pnpm only, like ts_core and web_ui). A strict tsconfig.base.json, ESLint flat-config presets (defineConfig() stacking base / react / vitest / playwright / layer boundaries()), a type-free eslint/fast subset for editor hooks, and Knip / jscpd / Stryker bases. Plain JS, no build step; the git tag is the release. Every plugin is a dependency of the package so consumers list none. A fixture repo with one planted violation per rule family proves each gate bites.

"devDependencies": {
  "@kuhyx/ts-config": "github:kuhyx/utils#ts_config-v0.1.0&path:/ts_config"
}

godot_dev_tools/

Godot addon (addons/dev_tools/): the F12 dev feedback mode of kuhy's games (annotate the frozen frame, save a bundle that feedback_inbox turns into a task). A game mounts it at a pinned tag; the game's own code stays a small host object. Read godot_dev_tools/README.md.

Consume via a shallow fetch of the tag, then mount the addon folder:

git clone --depth 1 --branch godot-dev-tools-v0.1.0 https://github.com/kuhyx/utils
# link or copy godot_dev_tools/addons/dev_tools to res://addons/dev_tools