@yulolimum/toolkit

Personal development toolkit and source registry. Nothing here is published or installable. Copy the files you need into your own project and adapt them there.

Everything here is meant to be copied out. Much of it runs in this repository too, which is how it stays exercised: the shared configs lint this repo, and the toolkit-living-docs skill maintains its documentation.

Skills (skills/)

Agent skills, shared the same way as configs. Each skill has a README with a short overview and use instructions.

• toolkit-living-docs - Review, update, audit, and scaffold agent-facing living documentation.
  • README - Overview and use instructions.
  • references/index.md - Registry template for new Living Docs scaffolds.
• toolkit-convention-pass - Apply selected code and writing conventions after implementation.
  • README - Overview and use instructions.
  • references/new-convention.md - Workflow for adding a shared or project convention.
  • barrel-exports - Direct-import conventions.
  • comments - Code-comment conventions.
  • commit-seven-rules - Commit-message and staging conventions.
  • component-style-slots - Reusable-component style-slot conventions.
  • humanizer - Invokes the editorial humanizer flavor.
  • jsx-truthiness - JSX truthiness and conditional-rendering conventions.
  • markdown - Markdown formatting conventions.
  • prefer-local-implementations - Guidance for preferring readable local code over premature extraction.
  • react-hook-form - React Hook Form inference, access, and submit-handler conventions.
  • simplified-technical-english - Invokes the editorial Simplified Technical English flavor.
  • tanstack-query-data-fetching - TanStack Query data-fetching and mutation conventions.
  • typescript-inference - Return-type inference guidance.
  • zod-schema-naming - Zod schema naming conventions.
  • conventions/extensions/template.md - Template for a project-specific convention.
• toolkit-editorial-pass - Apply a selected editorial flavor to human-facing prose.
  • README - Overview and use instructions.
  • humanizer - Natural, fact-preserving prose guidance.
  • simplified-technical-english - Controlled technical-prose guidance.
  • references/extensions/template.md - Template for a project-specific editorial flavor.
• toolkit-link-global-skills - Link local skills individually into the global directories for Codex, Claude Code, Cursor, and Antigravity CLI.
  • README - Overview and use instructions.
• toolkit-update-paseo-base-branch - Update the saved base branch for the current Paseo worktree.
  • README - Overview and use instructions.
• toolkit-linear-ticket-authoring - Create and update Linear tickets with workspace checks and a structured draft.
  • README - Overview and use instructions.
• toolkit-typescript-script-pattern - Build TypeScript automation scripts with consistent prompt, CLI, cache, and logging conventions.
  • README - Overview and use instructions.
• toolkit-react-provider-pattern - Create React context providers with a data hook, thin provider, and guarded consumer hook.
  • README - Overview and use instructions.
• toolkit-pr-authoring - Write pull-request descriptions from branch commits and diffs.
  • README - Overview and use instructions.
  • templates/pr-description.md - Default pull-request-description outline.
  • references/diagrams.md - Decision rules for optional diagrams.
  • references/examples.md - Worked pull-request-description examples.
  • references/proofs.md - Proof-table rules.
  • extensions/template.md - Template for project-specific requirements.
• toolkit-dependency-catalog-upgrade - Consolidate monorepo dependency versions into a catalog, pin them, and upgrade them.
  • README - Overview and use instructions.
• toolkit-graph-dev-v1 - Research a surface area into a spec of dependency-ordered work units, then implement one unit from that spec.
  • README - Overview and use instructions.
• toolkit-graph-dev-v2 - Research, implement, and refine a spec with dependency-ordered units and reviewable chunks.
  • README - Overview and use instructions.

Services (services/)

Stateful abstractions that own storage or network configuration. Adopt a storage class and its schema together.

• api-base.ts - Resettable Axios client with JSON defaults, base-URL and header setters, normalized API results, and an unsafe unwrapping helper.
• storage.ts - Typed store with get, set, remove, clear, and a reactive useStorage hook. Per-key defaults, JSON serialization for objects, and version-based clearing when a key's schema changes. Accepts a custom MMKV instance.
• secure-storage.ts - Typed Expo SecureStore wrapper with get, set, remove, and clear. Reads fall back to schema defaults, writes warn instead of throwing, and clear only removes keys the schema declares.
• tauri-storage.ts - Schema-driven Tauri store wrapper with async updates and key-change listeners. It clears versioned keys when needed, returns defaults, and skips writes outside Tauri or when storage is unavailable.

Components (components/)

Unstyled React Native components. Each solves one layout or state problem and leaves appearance to you.

• AspectImage.tsx - Expo Image wrapper that renders at the source's natural aspect ratio, with optional max width or height.
• CollapsibleView.tsx - View that measures its content and animates it open or closed.
• MeasuringView.tsx - View that measures its own layout and passes the size to a render-prop child.
• PolymorphicView.tsx - View that can render another React Native component through an as prop.
• QueryState.tsx - Composable TanStack Query state primitives. Include only the states a view needs.

Hooks (hooks/)

Reusable React and React Native hooks.

• useAppState.ts - Track foreground state with callbacks for the active and background transitions.
• useDebouncedValue.ts - Debounce a value, with leading mode, forced update, and cancel.
• useMultiCountPress.ts - Detect N presses within a time window, for debug menus and hidden features. Returns undefined when disabled.
• useQueryRefreshControlProp.ts - RefreshControl prop for exact query targets, with an optional reset for infinite lists.
• useRNDevTools.ts - Development-only Rozenite panels for React Native network activity, TanStack Query, MMKV, and Expo SecureStore.
• useScreenPreventRemove.ts - Block navigation away from a screen while any condition holds, with functions to leave anyway.
• useTauriDevTools.ts - Enable the Cmd/Ctrl+R reload shortcut in a Tauri development build.
• useTauriStorage.ts - React state for one Tauri storage key, with async updates, reset, and external change synchronization.
• useAuthorization.tsx - Role and permission gating. Replace the placeholder auth state with your own.

Scripts (scripts/)

Interactive automation, one self-contained file per task. Every prompt has a flag that skips it, and each script remembers your last answers.

• worktree-setup - Prepare a mobile worktree for an agent to use. Invoke with pnpm exec tsx scripts/worktree-setup.ts.
• worktree-run - Launch an isolated iOS or Android development session for the current worktree. Invoke with pnpm exec tsx scripts/worktree-run.ts --platform ios or pnpm exec tsx scripts/worktree-run.ts --platform android.
• worktree-teardown - Reclaim the mobile resources for a worktree when it is archived. Invoke with pnpm exec tsx scripts/worktree-teardown.ts.
• dev:check-code-quality - Pick and run any of TypeScript, ESLint, and Prettier. Remembers the selection.
• dev:clean - Recursively delete node_modules, build output, and caches.
• dev:verify-software - Check installed Node, pnpm, Java, Xcode, Android, and CocoaPods versions against the ranges set at the top of the script.
• eas:build - Interactive EAS build for development, shared preview, or production. Prompts for platform and profile, prints the assembled command, then runs it.
• eas:submit - Submit a build to TestFlight or Play Store internal testing.
• eas:update - Publish an over-the-air update to a channel, with an optional message.
• hueforge:swatch - Generate a stepped STL from a HueForge export’s actual thickness. Run pnpm hueforge:swatch "/path/to/describe.txt"; square cells default to 15 mm (--cell-mm), with a near-square grid, empty unused cells, and no added backing. Writes <export-name>-swatch.stl beside the input without overwriting; use --output to choose another path. Run pnpm hueforge:swatch --self-test for geometry and parsing checks. Set filament changes in your slicer.
• linear:start-clockify-timer - Start a Clockify timer from a Linear issue URL, or log a fixed duration retroactively.
• media:accelerate-video - Speed up a video with FFmpeg, with or without audio.
• media:normalize-episode-names - Rename TV episode files to Show Name s01e01.ext using an LLM, translating Russian titles when confident.
• media:play-twitch-stream - Pick a live stream from your followed channels and launch it in streamlink.
• media:recursively-hardlink - Hardlink a file or flat directory of media into a new location.

Usage

Package commands are the usual entry point. Each script can also be run directly:

# .mjs scripts can be run without dependencies
npx zx --install ./scripts/script-name.mjs

# .ts scripts can be run via tsx
npx tsx ./scripts/script-name.ts

# Shell scripts can be run directly
./scripts/script-name.sh

Utils (utils/)

Standalone helpers, one file per subject. No cross-imports, so copying a single file is enough.

arrays.ts - Array normalization, selection, sorting, and search.

• ensureArray - Wrap a value, array, or nullish input into a new array.
• toggleStringItem - Add or remove an item, deduplicating the result.
• shuffleArray - Fisher-Yates copy. The source is never modified.
• randomArrayItem - One random item, or undefined when empty.
• randomArrayItems - N random items without reusing a source position.
• dedupeByKey - Drop duplicate objects by key, keeping the first occurrence.
• localeSort - Sort by an accessor, ignoring case and ordering embedded numbers naturally.
• localeSortStrings - Same comparison, for an array of strings.
• localeSortByKey - Same comparison, by object property. Nullish sorts as empty.
• fuzzySearch - Search object keys, returning direct substring matches before falling back to weighted fuzzy matching.

objects.ts - Type-safe object access and reshaping.

• getObjPath - Read a nested value by dot or bracket path.
• isObjEmpty - True for null, undefined, or an object with no keys.
• getObjectKeys - Object.keys with the keys typed.
• getObjectValues - Object.values with the values typed.
• getObjectEntries - Object.entries with each key paired to its own value type.
• pick - New object containing only the given keys.
• pickBy - New object containing properties that pass a predicate.
• omit - New object without the given keys.
• removeNullishValues - New object without null or undefined values.
• getRootLevelObject - Only the primitive properties. Drops nested objects, arrays, and functions.

strings.ts - Text formatting, escaping, and SemVer.

• pluralize - Choose singular or plural, optionally prefixed with the count.
• escapeRegExp - Escape text so it matches literally inside a RegExp.
• truncateWithEllipsis - Truncate to a maximum length. The ellipsis counts toward the limit.
• joinArrayWithRemainingCount - Join the first N values and append the hidden count.
• semverString - Assemble a version from core, prerelease, and build metadata. Performs no validation.
• semverGT - Compare two normalized MAJOR.MINOR.PATCH versions.
• removeNonAlphaNumeric - Strip everything except Unicode letters and numbers, with optional characters preserved.

colors.ts - Color parsing and WCAG contrast.

• parseHexColor - Parse #RGB or #RRGGBB.
• parseRgbColor - Parse rgb() or rgba().
• parseColor - Parse any supported format, ignoring surrounding whitespace.
• toLinearSrgb - Convert one 8-bit channel to its linear-light value.
• getRelativeLuminance - WCAG relative luminance of an opaque color.
• getContrastRatio - WCAG contrast ratio between two opaque colors.
• getContrastingColor - Black or white, whichever contrasts better. Returns the fallback for invalid or semi-transparent input.

dates.ts - Elapsed time and range containment.

• formatElapsed - Compact 1h 1m 1s label from a millisecond duration.
• isDateRangeContainedBy - Whether one range fits inside another. Endpoints are inclusive and either bound may be omitted.

timers.ts - Delays and controllable intervals.

• delay - Promise that resolves after a duration. Throws on a negative or non-finite input.
• createInterval - Interval built on recursive timeouts, with run and stop. Calling run while active will not double-schedule.

geo.ts - Map region calculation for React Native Maps.

• getRegionForCoordinates - Smallest region containing a set of coordinates, with optional padding. Returns undefined for an empty list.

images.ts - Placeholder image URLs.

• generatePlaceholderImageUrl - Build a placehold.co URL with configurable size, colors, format, and label.

safe-try-catch.ts - Error handling without try/catch at the call site.

• safeResolve - Await a promise and get { ok, value } with a fallback instead of a throw.
• safeExec - Same, for a synchronous function.

provider-registry.tsx - Flat React provider composition.

• ProviderRegistry - Compose providers from a registry and an ordered list, with typed per-provider props and conditional entries.

Configs (configs/)

Shareable config files. The root eslint.config.mjs and prettier.config.mjs re-export these, so this repo runs on what it hands out.

• eslint.config.mjs - Flat ESLint config covering TypeScript, React, hooks, import sorting, and Prettier.
• prettier.config.mjs - Prettier with package.json, shell, and Tailwind plugins.
• eas.json - EAS build and submit profiles for development, PR previews, shared previews, and production releases.

Workflows (workflows/)

Reusable GitHub Actions workflows. Copy into .github/workflows/ and replace the placeholders.

• mobile-ci.yml - Runs mobile tests for non-draft pull requests.
• mobile-pr-preview.yml - Label-gated PR preview builds that reuse compatible native builds and publish PR OTA updates.
• mobile-preview.yml - Builds shared previews after main merges, submits iOS to TestFlight, and distributes Android through Firebase App Distribution.
• mobile-production.yml - Manually builds and submits production iOS and Android releases.

Docs (docs/)

Guides written for people, with no application-specific details.

• dev-ai-setup.md - Preferred AI development setup: repository context, living documentation, and reusable skills shared globally.
• dev-environment-setup.md - macOS React Native environment setup: brew, asdf, Node, pnpm, Java, CocoaPods, Xcode, and Android Studio.
• dev-eas.md - EAS profiles, fingerprints, PR previews, Firebase tester distribution, store releases, and OTA updates.
• dev-push-notifications.md - Push notification architecture, with Expo and Firebase options for both the server and client halves.
• dev-react-native-architecture.md - React Native's old and new architectures, interoperability layers, and native module migration guidance.

Lib (lib/)

Pre-configured library instances. Configure one here and everything downstream picks it up as a default.

• mmkv.ts - Shared MMKV v4 instance for React Native persistent storage. Used by services/storage.ts unless another instance is injected.
• secure-storage.ts - Shared typed Expo SecureStore instance for access and refresh tokens. Used by useRNDevTools.ts; adapt its schema for each app.