# Development Notes

## Runtime

Next.js runs inside the Docker container `Raikyakun-Mobile-Node`.

The macOS workspace is mounted over SMB. Do not use macOS-side `npm`, `yarn`, `next`, or `tsc` results as the source of truth because `node_modules` and `.next` belong to the Linux container environment.

Use SSH into the container for runtime checks.

## SSH

Connect to the mobile container:

```bash
ssh raikyakun-mobile
```

Run a command inside the app:

```bash
ssh raikyakun-mobile 'cd /usr/src/node && <command>'
```

The mobile development container is rebuilt often, so its SSH host key can change.
For development-only SSH config, it is acceptable to disable known_hosts checks for this host:

```sshconfig
Host raikyakun-mobile
  HostName 192.168.10.253
  Port 2225
  User codex
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
  LogLevel ERROR
```

If the VPN address is preferred in your environment, use `HostName 10.3.0.3` instead.

## Dev Server

By default `yarn dev` is started by Docker Compose. The startup command checks for a
`node/.prod-mode` marker file: if present it runs `yarn build && yarn start` (production
build), otherwise `yarn dev`.

The server log (both modes) is mirrored inside the container at:

```bash
/tmp/next-dev.log
```

## Switching dev / prod build mode

Use `switch-mode.sh` on the Docker host (run from the `mobile/` directory):

```bash
./switch-mode.sh prod      # 本番ビルドへ (yarn build && yarn start)
./switch-mode.sh dev       # dev へ (yarn dev)
./switch-mode.sh status    # 現在のモード表示 (restart しない)
./switch-mode.sh package   # 本番ビルド成果物を tar に固める (restart しない)
```

`prod`/`dev` touches/removes `node/.prod-mode` then runs `docker compose restart node`.
`status`/`package` do not restart.

`prod` does not return immediately: after the restart it polls the container log
(`/tmp/next-dev.log`) and **waits until `yarn build` finishes and `next start` reports
"Ready"** (or fails / times out after `BUILD_TIMEOUT`, default 900s). So once `prod`
returns successfully you can run `package` right away — no manual wait needed.

`package` calls `./build` and produces `standalone.tar.gz` / `static.tar.gz` /
`public.tar.gz` in `mobile/`. It requires a completed prod build (`node/build/standalone`
must exist) — run `./switch-mode.sh prod` first. `yarn start` does not mutate the packaged
directories, so running `package` while the prod server is up is safe. Deploy flow:
`prod` → 動作確認 → `package` → 本番先へ3つの tar.gz を展開.
(`package` という名前は、Node サーバーを使わない静的出力を指す Next.js の `next export`
と紛らわしいため `export` を避けたもの。)

Notes:
- `yarn build` takes a few minutes; the server is down during the build.
- If `yarn build` fails the container restarts and rebuilds in a loop — run
  `./switch-mode.sh dev` to recover.
- Production build runs with `NODE_ENV=production`, so it reads `.env.production`
  (`NEXT_PUBLIC_BASE_URL=https://mobile.raikyakun.app`). To keep the dev URL while
  testing a prod build, add `NEXT_PUBLIC_BASE_URL` to `environment:` in
  `docker-compose.yml`.
- `node/.prod-mode` is a per-machine local marker and is gitignored.

Check recent logs:

```bash
ssh raikyakun-mobile 'tail -n 120 /tmp/next-dev.log'
```

Follow logs:

```bash
ssh raikyakun-mobile 'tail -f /tmp/next-dev.log'
```

## Page Check

Trigger a page compile and check the HTTP response from inside the container:

```bash
ssh raikyakun-mobile 'curl -I http://127.0.0.1:3000/'
```

## TypeScript Check

Run TypeScript inside the container. The container user cannot write `tsconfig.tsbuildinfo`, so pass `--incremental false` to avoid `EACCES`:

```bash
ssh raikyakun-mobile 'cd /usr/src/node && node node_modules/typescript/lib/tsc.js --noEmit --incremental false --pretty false'
```

As of 2026-05-12, this command passes cleanly.

## Lint Check

The mobile container does not provide `sudo`, and ESLint has not been initialized yet (running `yarn lint` triggers `next lint`'s interactive setup prompt asking for Strict/Base/Cancel). As of 2026-05-12, lint is **not yet configured** for this project. When initializing, prefer `Strict`. Run as the container user (no sudo):

```bash
ssh raikyakun-mobile 'cd /usr/src/node && yarn lint'
```

Keep this file updated when the mobile verification workflow changes so both Codex and Claude Code use the same test knowledge.