1k-dev-workflows

Original source / Raw SKILL.md

---
name: 1k-dev-workflows
description: Development workflow helpers for OneKey. Use when fixing lint warnings, creating test version branches, or performing pre-commit/pre-release tasks. Covers oxlint fixes, spellcheck, unused variables, and upgrade testing workflows.
---

# Development Workflows

Common development workflows and automation helpers for the OneKey monorepo.

## Quick Reference

| Task | Command | Description |
|------|---------|-------------|
| Lint all files | `yarn lint:only` | Full project lint |
| Lint staged files | `yarn lint:staged` | Pre-commit: only modified files |
| Type check | `yarn tsc:only` | Full project type check |
| Type check (staged) | `yarn tsc:staged` | Pre-commit type check |
| Create test version | See [upgrade-test-version.md](references/rules/upgrade-test-version.md) | Manual workflow |

## Lint Commands

See: [references/rules/fix-lint.md](references/rules/fix-lint.md)

### Lint All Files
```bash
yarn lint:only
```

### Lint Staged Files (Pre-commit)
```bash
# Only lint files that are staged for commit - fast!
yarn lint:staged
```

### Type Check
```bash
# Full project type check
yarn tsc:only

# Same as above, for pre-commit use
yarn tsc:staged
```

**Note:** TypeScript requires full project context and cannot check individual files.

## Common Lint Fixes

```typescript
// Unused variable → prefix with _
const { used, unused: _unused } = obj;

// Unused parameter → prefix with _
function foo(used: string, _unused: number) {}
```

## Pre-commit Workflow

Before committing:
1. `yarn lint:staged` - Lint only modified files (fast)
2. `yarn tsc:staged` - Type check (if needed)
3. Ensure changes are properly staged

For quick pre-commit validation:
```bash
# Quick: lint only
yarn lint:staged && git commit -m "your message"

# Thorough: lint + type check
yarn lint:staged && yarn tsc:staged && git commit -m "your message"
```

## Test Version Creation

See: [references/rules/upgrade-test-version.md](references/rules/upgrade-test-version.md)

For QA upgrade testing with version pattern `9XXX.YY.Z`.

**Build number formula:**
```bash
DATE=$(date +%Y%m%d)
BUILD_NUMBER=$((${DATE}00 + 30))
```

**Files to modify:**
- `.env.version`
- `.github/actions/shared-env/action.yml`
- `.github/workflows/release-android.yml`
- `apps/mobile/android/app/build.gradle`

## Key Files

| Purpose | File |
|---------|------|
| Lint config | `.oxlintrc.json` |
| Spellcheck skip list | `development/spellCheckerSkipWords.txt` |
| Version config | `.env.version` |
| Build config | `apps/mobile/android/app/build.gradle` |

## Related Skills

- `/1k-git-workflow` - Git branching and commit conventions
- `/1k-coding-patterns` - Code style and patterns


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/rules/upgrade-test-version.md

```markdown
# Creating Upgrade Test Version

Automates the creation of test version branches with hardcoded build configurations for testing app upgrade functionality and version migration flows.

## Workflow

### Step 1: Gather Version Information

Ask the user for the test version number using AskUserQuestion:

```
Question: "What test version number should be used?"
Options:
- "9005.20.0" (example format)
- Custom input
```

The version should follow the pattern `9XXX.YY.Z` where:
- `9XXX` indicates a test version (e.g., 9005)
- `YY.Z` matches the production version being tested

### Step 2: Calculate Build Number

Calculate the build number as: **current date (YYYYMMDD) + "00" suffix + 30**

The build number must be 10 digits in format: `YYYYMMDD00 + 30 = YYYYMMDD30`

Example: If today is `20260113`, the build number is `2026011300 + 30 = 2026011330`

```bash
# Calculate build number (10 digits)
DATE=$(date +%Y%m%d)
BUILD_NUMBER=$((${DATE}00 + 30))
echo "Build number: $BUILD_NUMBER"  # Output: 2026011330
```

### Step 3: Create and Checkout Branch

Create a new branch named after the test version:

```bash
git checkout -b <test_version>
# Example: git checkout -b 9005.20.0
```

### Step 4: Modify Configuration Files

Modify the following files in order:

#### 4.1 Update `.env.version`

Change the `VERSION` field to the test version:

```
VERSION=<test_version>
BUNDLE_VERSION=1
```

#### 4.2 Update `.github/actions/shared-env/action.yml`

In the "Setup ENV BUILD_NUMBER" steps, replace ALL build number logic with a hardcoded value. Remove the if/else conditions and simplify to:

```yaml
- name: Setup ENV BUILD_NUMBER
  shell: bash
  run: |
    echo "BUILD_NUMBER=<calculated_build_number>" >> $GITHUB_ENV
```

Remove both:
- "Setup ENV BUILD_NUMBER to 1" step
- "Setup ENV BUILD_NUMBER by workflow_run" step

Replace with single step that hardcodes the build number.

#### 4.3 Update `.github/workflows/release-android.yml`

In the "Write .env.version" step, change:

```yaml
echo "BUILD_NUMBER=${{ env.BUILD_NUMBER }}" >> .env.version
```

To:

```yaml
echo "BUILD_NUMBER=<calculated_build_number>" >> .env.version
```

#### 4.4 Update `apps/mobile/android/app/build.gradle`

In the `defaultConfig` block, update:

```gradle
versionCode <calculated_build_number>
versionName "<test_version>"
```

Example:
```gradle
versionCode 2026011330
versionName "9005.20.0"
```

### Step 5: Commit and Push

```bash
git add -A
git commit -m "chore: prepare test version <test_version> with build number <build_number>"
git push -u origin <test_version>
```

## File Locations Summary

| File | Change |
|------|--------|
| `.env.version` | Update VERSION |
| `.github/actions/shared-env/action.yml` | Hardcode BUILD_NUMBER, remove conditionals |
| `.github/workflows/release-android.yml` | Hardcode BUILD_NUMBER in .env.version write |
| `apps/mobile/android/app/build.gradle` | Update versionCode and versionName |

## Validation Checklist

Before pushing, verify:
- [ ] Branch name matches test version
- [ ] `.env.version` VERSION field updated
- [ ] Build number conditionals removed from shared-env
- [ ] Build number hardcoded in release-android workflow
- [ ] versionCode is numeric (build number)
- [ ] versionName is quoted string (test version)

```

### references/rules/fix-lint.md

```markdown
# Fix Lint

Helps fix oxlint warnings in the OneKey app-monorepo codebase.

**IMPORTANT**: This project uses **oxlint** (not ESLint). The active linting configuration is in `.oxlintrc.json`.

## Lint Commands

### Lint All Files
```bash
yarn lint:only
```

### Lint Staged Files (Pre-commit)
```bash
# Only lint files staged for commit - fast for pre-commit checks
yarn lint:staged
```

### Type Check
```bash
# Full project type check
yarn tsc:only

# Same as above, for pre-commit use
yarn tsc:staged
```

**Note:** TypeScript requires full project context and cannot check individual files.

## Usage

Use this when:
- Running `yarn lint` and encountering warnings
- Cleaning up code before committing
- Fixing spellcheck, unused variable, or other linting warnings

## Workflow

### Step 1: Run Lint and Analyze Warnings

```bash
yarn lint:only 2>&1 | tail -100
```

### Step 2: Categorize Warnings

Warnings typically fall into these categories:

| Category | Rule | Fix Strategy |
|----------|------|--------------|
| Spellcheck | `@cspell/spellchecker` | Add to skip list or fix typo |
| Unused vars | `@typescript-eslint/no-unused-vars` | Remove import or prefix with `_` |
| Non-null assertion | `@typescript-eslint/no-non-null-assertion` | Add type guard or cast |
| Nested components | `react/no-unstable-nested-components` | Extract component |
| Import order | `import/order` | Fix import ordering |

### Step 3: Fix Each Category

#### Spellcheck Warnings (`@cspell/spellchecker`)

1. **Evaluate the word**: Is it a legitimate technical term or a typo?

2. **For legitimate technical terms**, add to skip list:
   ```text
   # File: development/spellCheckerSkipWords.txt
   # Add the word on a new line at the end of the file
   newTechnicalTerm
   ```

3. **For known typos** that can't be fixed (e.g., in translation keys), add with a comment above:
   ```text
   # Known typo - exsited -> existed (ETranslations.some_key)
   exsited
   ```

4. **Common legitimate terms to add**:
   - Build tools: `chunkhash`, `minimizer`, `rspack`
   - Blockchain: `lovelace`, `Kusama`, `workchain`, `feebump`
   - UI: `Virtualized`, `overscan`, `overscrolling`
   - Crypto: `nacl`, `Bech32`, `secp256k1`

#### Unused Variable Warnings (`@typescript-eslint/no-unused-vars`)

1. **Unused imports** - Remove the import:
   ```typescript
   // Before
   import { Used, Unused } from 'package';
   // After
   import { Used } from 'package';
   ```

2. **Unused function parameters** - Prefix with underscore:
   ```typescript
   // Before
   function foo(used: string, unused: number) { return used; }
   // After
   function foo(used: string, _unused: number) { return used; }
   ```

3. **Unused destructured variables** - Prefix with underscore:
   ```typescript
   // Before
   const { used, unused } = obj;
   // After
   const { used, unused: _unused } = obj;
   ```

4. **Unused assigned variables** - Prefix with underscore:
   ```typescript
   // Before
   const unused = getValue();
   // After
   const _unused = getValue();
   ```

#### Non-null Assertion Warnings (`@typescript-eslint/no-non-null-assertion`)

Add type assertions or guards:
```typescript
// Before
const value = obj.prop!.name;
// After
const value = (obj.prop as { name: string } | undefined)?.name;
```

#### Nested Component Warnings (`react/no-unstable-nested-components`)

Extract the component outside the parent:
```typescript
// Before
function Parent() {
  const NestedComponent = () => <div />;
  return <NestedComponent />;
}

// After
const ExtractedComponent = () => <div />;
function Parent() {
  return <ExtractedComponent />;
}
```

### Step 4: Verify Fixes

```bash
yarn lint:only 2>&1 | tail -50
```

## Pre-commit Workflow

For fast pre-commit validation, only lint modified files:
```bash
# Lint only staged files
yarn lint:staged

# Then commit
git commit -m "your message"

# Or combine
yarn lint:staged && git commit -m "your message"

# With type check
yarn lint:staged && yarn tsc:staged && git commit -m "your message"
```

## Common Patterns in This Codebase

### Translation Key Typos
Translation enum keys (e.g., `ETranslations.perp_invaild_tp_sl`) cannot be easily renamed as they're managed externally. Add to skip list with a comment:
```text
# Known typo in translation key - invaild -> invalid
invaild
```

### Provider API Methods
Methods like `openInMobileApp` that throw `NotImplemented()` often have unused parameters:
```typescript
public async openInMobileApp(
  _request: IJsBridgeMessagePayload,
  _params: ISignMessagePayload,
): Promise<void> {
  throw new NotImplemented();
}
```

### Destructuring from Hooks
When destructuring from hooks but not using all values:
```typescript
const { used, unused: _unused } = usePromiseResult(...);
```

## Tips

1. **Check if word is in skip list** before adding:
   ```bash
   grep -i "wordToCheck" development/spellCheckerSkipWords.txt
   ```

2. **Verify no regressions** after fixes:
   ```bash
   yarn tsc:only
   ```

## Key Files

- `development/spellCheckerSkipWords.txt` - Add technical terms and known typos
- `.oxlintrc.json` - Linting configuration

```