Skip to content

Commit aaf38e2

Browse files
l2hyunwool2hyunwoo
authored
docs: add AGENTS.md files (#73)
* docs: agent md files * docs: update github agent docs
1 parent e3b45cb commit aaf38e2

File tree

14 files changed

+868
-2
lines changed

14 files changed

+868
-2
lines changed

‎.github/AGENTS.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
<!-- Parent: ../AGENTS.md -->
2+
<!-- Generated: 2026-02-13 -->
3+
4+
# GitHub Configuration
5+
6+
## Purpose
7+
GitHub-specific configuration: CI/CD workflows, issue templates, and repository settings.
8+
9+
## Key Files
10+
11+
| File | Description |
12+
|------|-------------|
13+
| `workflows/ci.yml` | Main CI: lint, typecheck, build, build-ios, build-android, validate-package, mcp-server (path-based change detection) |
14+
| `workflows/publish.yml` | Library publish: version bump -> tag -> NPM publish with provenance -> GitHub Release (`workflow_dispatch`) |
15+
| `workflows/publish-mcp.yml` | MCP server publish: validate -> version bump -> tag -> NPM publish -> GitHub Release (`workflow_dispatch`) |
16+
| `workflows/docs-deploy.yml` | Docs deployment to GitHub Pages on push to main (`docs/**` path filter) |
17+
| `workflows/docs-validation.yml` | Docs build validation on PRs (`docs/**` path filter) |
18+
| `CODEOWNERS` | Default reviewer: @l2hyunwoo (all files) |
19+
| `ISSUE_TEMPLATE/bug_report.yml` | Bug report template (library version, environment info, repro steps, repro repo required) |
20+
| `ISSUE_TEMPLATE/config.yml` | Disables blank issues; routes feature requests and questions to GitHub Discussions |
21+
22+
## For AI Agents
23+
24+
### Working In This Directory
25+
- CI uses `dorny/paths-filter@v3` for change detection with 4 filters: `library`, `mcp-server`, `docs`, `deps`
26+
- All workflows use Node.js 20 and `yarn install --immutable`
27+
- CI jobs (triggered on push to main/develop and PRs):
28+
- **lint**: oxlint + TypeScript typecheck (runs when library, mcp-server, or deps change)
29+
- **build**: TypeScript build via `yarn prepare`, verifies `lib/module`, `lib/typescript`, `nitrogen/generated` outputs
30+
- **build-ios**: CocoaPods install + xcodebuild on `macos-15` (showcase app, Release config, iphonesimulator)
31+
- **build-android**: ktlint check + Gradle assembleDebug on `ubuntu-latest` (Java 17 temurin)
32+
- **validate-package**: `npm pack` + verifies tarball contains required files (lib, src, ios, android)
33+
- **mcp-server**: typecheck + build + test (only when `packages/mcp-server/**` changes)
34+
- Publish workflows are `workflow_dispatch` only, require `version` input (X.Y.Z format) and support `dry_run`
35+
- Library tags: `v{VERSION}`, MCP server tags: `mcp-server-v{VERSION}`
36+
37+
### Testing Requirements
38+
- Verify workflow syntax with `act` or manual trigger
39+
- Test path filters match actual monorepo directory structure (`packages/react-native-nitro-device-info/`, `packages/mcp-server/`, `docs/`, `example/`)
40+
- Ensure `NPM_TOKEN` and `GITHUB_TOKEN` secrets are configured for publish workflows
41+
- Publish workflows use NPM provenance (`--provenance --access public`)
42+
43+
### Common Patterns
44+
- Path-based filtering via `dorny/paths-filter@v3` to skip unnecessary CI jobs
45+
- CI workflow exposes `workflow_call` for reuse from other workflows
46+
- Caching strategies: Yarn (built-in `actions/setup-node` cache), Gradle (`~/.gradle/caches`), CocoaPods (`~/Library/Caches/CocoaPods`), Xcode DerivedData
47+
- Publish workflows: version commit -> tag -> NPM publish -> GitHub Release with auto-generated release notes
48+
- Concurrency groups on publish workflows to prevent parallel releases
49+
50+
## Dependencies
51+
52+
### Internal
53+
- Workflows reference package scripts from root `package.json` (`yarn prepare`, `yarn lint`, `yarn typecheck`, `yarn test`)
54+
- Build jobs depend on monorepo workspace structure (`packages/`, `example/`)
55+
56+
### External
57+
- `actions/checkout@v4`, `actions/setup-node@v4`, `actions/cache@v4`
58+
- `actions/setup-java@v4` (Android build, temurin JDK 17)
59+
- `actions/configure-pages@v5`, `actions/upload-pages-artifact@v3`, `actions/deploy-pages@v4` (docs)
60+
- `actions/upload-artifact@v4` (docs validation)
61+
- `dorny/paths-filter@v3` - Change detection
62+
- `softprops/action-gh-release@v1` - GitHub Release creation (publish workflows)
63+
64+
<!-- MANUAL: -->

‎.gitignore‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,10 +97,9 @@ packages/react-native-nitro-device-info/nitrogen/
9797
CLAUDE.md
9898
specs/
9999
.specify/
100+
.omc/
100101

101102
# openspec
102-
AGENTS.md
103-
**/AGENTS.md
104103
openspec/
105104

106105
# ios

‎AGENTS.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
<!-- OPENSPEC:START -->
2+
# OpenSpec Instructions
3+
4+
These instructions are for AI assistants working in this project.
5+
6+
Always open `@/openspec/AGENTS.md` when the request:
7+
- Mentions planning or proposals (words like proposal, spec, change, plan)
8+
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
9+
- Sounds ambiguous and you need the authoritative spec before coding
10+
11+
Use `@/openspec/AGENTS.md` to learn:
12+
- How to create and apply change proposals
13+
- Spec format and conventions
14+
- Project structure and guidelines
15+
16+
Keep this managed block so 'openspec update' can refresh the instructions.
17+
18+
<!-- OPENSPEC:END -->
19+
20+
## 코드 작성 규칙
21+
22+
### Comments
23+
- Comments should be written in English as much as possible.
24+
- Avoid adding unnecessary comments, only use KDoc format.
25+
26+
### Kotlin
27+
- `companion object`를 추가할 시 클래스 최하단 영역에 추가한다.
28+
- `try-catch` 문은 최대한 지양하고 `runCatching` 문을 사용하자.
29+
- Closable 리소스는 `use` 확장함수를 사용해보자.
30+
31+
### Git Commit
32+
- Git commit 시에는 message의 body는 비운채로 커밋해야한다.
33+
34+
## 기능 구현 체크리스트 (Feature Implementation Checklist)
35+
36+
- 모든 기능 구현 Spec에 대해 다음 문서들의 최신화 작업을 포함해야 합니다:
37+
- `@docs/**` (API 문서, 가이드 등)
38+
- `@README.md`
39+
- 한국어 문서 (`README-ko.md` 등)
40+
- 기능 구현 작업 시 `@example/showcase/**` 앱에도 해당 기능을 시연할 수 있도록 업데이트해야 합니다.
41+
42+
---
43+
44+
<!-- Generated: 2026-02-13 -->
45+
46+
# React Native Nitro Device Info - Monorepo Guide
47+
48+
## Purpose
49+
50+
Monorepo for `react-native-nitro-device-info` (v1.5.1), a high-performance React Native library providing 80+ device information properties through Nitro's zero-overhead JSI bindings. Implements native code in Swift (iOS) and Kotlin (Android).
51+
52+
## Key Files
53+
54+
| File | Description |
55+
|------|-------------|
56+
| `package.json` | Monorepo root with workspace definitions and shared scripts |
57+
| `turbo.json` | Turborepo configuration for build caching and task orchestration |
58+
| `.nvmrc` | Node.js version (20) |
59+
| `.yarnrc.yml` | Yarn 3.6.1 configuration with PnP mode |
60+
| `tsconfig.json` | Root TypeScript configuration |
61+
| `README.md` | Main project documentation |
62+
| `CONTRIBUTING.md` | Development workflow and guidelines |
63+
| `CLAUDE.md` | Project-specific AI assistant instructions |
64+
| `API-REFERENCE.md` | Complete API documentation for all 100+ methods |
65+
66+
## Subdirectories
67+
68+
| Directory | Purpose |
69+
|-----------|---------|
70+
| `packages/react-native-nitro-device-info/` | Main library (see `packages/react-native-nitro-device-info/AGENTS.md`) |
71+
| `packages/mcp-server/` | MCP server for AI tools (see `packages/mcp-server/AGENTS.md`) |
72+
| `example/showcase/` | Demo app displaying all properties (see `example/showcase/AGENTS.md`) |
73+
| `example/benchmark/` | Performance benchmark app (see `example/benchmark/AGENTS.md`) |
74+
| `docs/` | Rspress documentation site (see `docs/AGENTS.md`) |
75+
| `specs/` | Archived feature specifications (see `specs/AGENTS.md`) |
76+
| `openspec/` | OpenSpec change management system (see `openspec/AGENTS.md`) |
77+
| `.github/` | CI/CD workflows (see `.github/AGENTS.md`) |
78+
79+
## For AI Agents
80+
81+
### Working In This Directory
82+
83+
**Architecture Overview**:
84+
1. This is a **Nitro Module** - uses JSI for zero-overhead native communication
85+
2. API surface defined in `packages/react-native-nitro-device-info/src/DeviceInfo.nitro.ts`
86+
3. Native: `ios/DeviceInfo.swift` (iOS) and `android/.../DeviceInfo.kt` (Android)
87+
4. **Nitrogen codegen**: Always run `yarn nitrogen` after modifying `.nitro.ts` files
88+
89+
**Development Workflow**:
90+
1. Modify API in `DeviceInfo.nitro.ts`
91+
2. Run `yarn nitrogen` (generates C++/Java/Swift boilerplate)
92+
3. Implement native code in Swift (iOS) and Kotlin (Android)
93+
4. Run `yarn prepare` to build library
94+
5. Test in showcase/benchmark apps
95+
6. Update docs (`API-REFERENCE.md`, `docs/`, `README.md`, showcase app)
96+
7. Verify: `yarn typecheck`, `yarn lint`, `yarn test`
97+
98+
**File Rules**:
99+
- **Never** edit files in `nitrogen/generated/` or `lib/` (auto-generated)
100+
- For significant changes, create an OpenSpec proposal first (`openspec/AGENTS.md`)
101+
102+
### Testing Requirements
103+
104+
1. `yarn typecheck` - TypeScript validation
105+
2. `yarn lint` - oxlint validation
106+
3. `yarn test` - Jest unit tests
107+
4. Test in both showcase and benchmark apps
108+
5. Verify on both iOS and Android if native code changed
109+
110+
### Common Patterns
111+
112+
**Adding a New Property**:
113+
```typescript
114+
// 1. DeviceInfo.nitro.ts
115+
readonly newProperty: string
116+
117+
// 2. yarn nitrogen
118+
119+
// 3. iOS (DeviceInfo.swift)
120+
public var newProperty: String { return "value" }
121+
122+
// 4. Android (DeviceInfo.kt)
123+
override val newProperty: String get() = "value"
124+
```
125+
126+
**Adding an Async Method**:
127+
```typescript
128+
// 1. DeviceInfo.nitro.ts
129+
getNewInfo(): Promise<string>
130+
131+
// 2. yarn nitrogen
132+
133+
// 3. iOS
134+
public func getNewInfo() -> Promise<String> {
135+
return Promise.async { return "value" }
136+
}
137+
138+
// 4. Android
139+
override fun getNewInfo(): Promise<String> = Promise.async { "value" }
140+
```
141+
142+
### Dependencies
143+
144+
**Runtime**: `react-native-nitro-modules@0.31.2` (peer dependency)
145+
146+
**Development**: `yarn@3.6.1`, `node@20`, `typescript@5.9.2`, `nitrogen@0.31.2`, `turbo@2.6.2`, `oxlint@1.24.0`, `jest@30.0.0`, `commitlint@20.1.0`
147+
148+
**Native**: iOS Swift 5.9+ (UIKit, Foundation, Combine), Android Kotlin 1.9+ (kotlinx-coroutines 1.7.3)
149+
150+
### Common Commands
151+
152+
```bash
153+
yarn # Install dependencies
154+
yarn nitrogen # Generate native bindings
155+
yarn prepare # Build library
156+
yarn typecheck # TypeScript validation
157+
yarn lint # Linting
158+
yarn test # Jest tests
159+
yarn showcase ios # Run showcase on iOS
160+
yarn showcase android # Run showcase on Android
161+
yarn benchmark ios # Run benchmark on iOS
162+
yarn clean # Clean build artifacts
163+
```
164+
165+
### Important Notes
166+
167+
1. **Nitro Codegen**: After any `.nitro.ts` change, run `yarn nitrogen` or build fails
168+
2. **Documentation is Mandatory**: All features must update API-REFERENCE.md, docs/, README.md, and showcase app
169+
3. **Platform Support**: iOS 13.4+, Android API 24+
170+
4. **Commit Conventions**: Conventional commits with empty body (enforced by commitlint)
171+
5. **OpenSpec Proposals**: Required for new capabilities, breaking changes, architecture shifts
172+
173+
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

‎docs/AGENTS.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<!-- Parent: ../AGENTS.md -->
2+
<!-- Generated: 2026-02-13 -->
3+
4+
# Documentation Site
5+
6+
## Purpose
7+
Rspress-based documentation website for react-native-nitro-device-info. Deployed to GitHub Pages. Provides API reference, guides, examples, and integration instructions.
8+
9+
## Key Files
10+
11+
| File | Description |
12+
|------|-------------|
13+
| `rspress.config.ts` | Rspress configuration (nav, sidebar, search, theme, plugins) |
14+
| `package.json` | Dependencies (rspress ^1.40.2), scripts (dev, build, preview) |
15+
| `tsconfig.json` | TypeScript configuration for docs build |
16+
17+
## Subdirectories
18+
19+
| Directory | Purpose |
20+
|-----------|---------|
21+
| `docs/` | Documentation content (markdown files: api/, guide/, examples/, contributing/) |
22+
| `doc_build/` | Build output directory (generated by `npm run build`) |
23+
24+
## For AI Agents
25+
26+
### Working In This Directory
27+
- Run `npm run dev` to start local development server (hot reload)
28+
- Run `npm run build` to generate static site in doc_build/
29+
- Navigation and sidebar configured in rspress.config.ts
30+
- Deployed via GitHub Actions (`.github/workflows/docs-deploy.yml`)
31+
32+
### Testing Requirements
33+
- Verify all internal links resolve correctly
34+
- Test code examples compile and run
35+
- Validate markdown syntax and frontmatter
36+
37+
### Common Patterns
38+
- Code blocks: ```typescript, ```bash, ```kotlin, ```swift
39+
- Cross-references using relative paths
40+
- Container syntax plugin for callouts, warnings, tips
41+
42+
## Dependencies
43+
44+
### Internal
45+
- Documents API from `packages/react-native-nitro-device-info/`
46+
47+
### External
48+
- `rspress@^1.40.2` - Static site generator
49+
- `@rspress/plugin-container-syntax@^1.45.8` - Markdown container plugin
50+
51+
<!-- MANUAL: -->

‎example/AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<!-- Parent: ../AGENTS.md -->
2+
<!-- Generated: 2026-02-13 -->
3+
4+
# Example Apps
5+
6+
## Purpose
7+
Container directory for React Native example applications demonstrating react-native-nitro-device-info library usage.
8+
9+
## Subdirectories
10+
11+
| Directory | Purpose |
12+
|-----------|---------|
13+
| `showcase/` | Main demo app displaying all 80+ device properties (see `showcase/AGENTS.md`) |
14+
| `benchmark/` | Performance benchmark app for latency comparison (see `benchmark/AGENTS.md`) |
15+
16+
## For AI Agents
17+
18+
### Working In This Directory
19+
- Each subdirectory is a complete React Native app with independent package.json
20+
- All apps use workspace:* for library dependency (changes reflect immediately for TS)
21+
- Native changes require rebuilding the app
22+
- iOS apps require `pod install` in ios/ directory before first run
23+
24+
### Common Patterns
25+
- Library import: `import { DeviceInfo } from 'react-native-nitro-device-info'`
26+
- Hook usage: `import { useBatteryLevel } from 'react-native-nitro-device-info'`
27+
28+
## Dependencies
29+
30+
### Internal
31+
- All apps depend on `react-native-nitro-device-info` (workspace:*)
32+
33+
### External
34+
- react 19.1.0, react-native 0.82.1, react-native-nitro-modules ^0.31.2
35+
36+
<!-- MANUAL: -->

‎example/benchmark/AGENTS.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<!-- Parent: ../AGENTS.md -->
2+
<!-- Generated: 2026-02-13 -->
3+
4+
# Benchmark Example App
5+
6+
## Purpose
7+
Performance benchmark application measuring and comparing react-native-nitro-device-info API call latency against react-native-device-info.
8+
9+
## Key Files
10+
11+
| File | Description |
12+
|------|-------------|
13+
| `package.json` | Dependencies (includes react-native-device-info ^11.1.0 for comparison) |
14+
| `index.js` | App entry point |
15+
| `metro.config.js` | Metro bundler configuration with workspace support |
16+
17+
## Subdirectories
18+
19+
| Directory | Purpose |
20+
|-----------|---------|
21+
| `src/` | TypeScript source (App.tsx, benchmarks/, components/) |
22+
| `android/` | Android native project |
23+
| `ios/` | iOS native project |
24+
25+
## For AI Agents
26+
27+
### Working In This Directory
28+
- Run `yarn android` / `yarn ios` to launch the app
29+
- Benchmarks measure API call latency, throughput, memory overhead
30+
- Compares react-native-nitro-device-info vs react-native-device-info
31+
32+
### Testing Requirements
33+
- Validate benchmark accuracy: consistent results across runs
34+
- Measure sync API calls and async listener performance
35+
- Record memory usage before/after API calls
36+
- Verify performance targets: <10ms registration, <500ms callback latency
37+
38+
### Common Patterns
39+
- Benchmark loop: warmup → measure N iterations → calculate stats (mean, median, p95, p99)
40+
- Timing: `performance.now()` for high-resolution timestamps
41+
- Side-by-side comparison table for both libraries
42+
43+
## Dependencies
44+
45+
### Internal
46+
- `react-native-nitro-device-info` (workspace:*)
47+
48+
### External
49+
- react 19.1.0, react-native 0.82.1, react-native-nitro-modules ^0.31.2
50+
- react-native-device-info ^11.1.0 (comparison library)
51+
52+
<!-- MANUAL: -->

0 commit comments

Comments
 (0)