utils/README.md

# 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:
```yaml
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:
```yaml
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:
```yaml
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
```

## 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`](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.

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