AGENTS.md

Guidance for coding agents working on nk304 packages/app-core. This package holds platform-neutral application rules shared by web and mobile surfaces.

Project Overview

packages/app-core exports shared logic for auth session control, deep-link parsing, notification normalization, and presence policy. It is intentionally small and framework-neutral. Its job is to prevent web and mobile from implementing subtly different session, linking, notification, or presence semantics.

Avoid pulling app-specific state managers, browser globals, native modules, or API clients into this package. If a rule needs platform access, pass it in through an interface and keep the rule testable in Node.

Project Map

• src/index.ts is the public export boundary.
• src/auth-session-controller.ts owns token/session controller behavior through a storage interface.
• src/deep-links.ts parses supported deep-link targets.
• src/notification-mapping.ts normalizes notification records into a shared UI-ready form.
• src/presence-policy.ts decides whether presence should remain active.
• src/app-core.test.mts covers the package with the Node test runner.
• package.json exposes ESM, CommonJS, and type declaration outputs from dist/.

Setup Commands

bashpnpm --filter @nk304/app-core run test
pnpm --filter @nk304/app-core run build

Before changing exported behavior, inspect consumers:

bashrg "@nk304/app-core" apps packages

Change Rules For Agents

• Keep the package pure TypeScript with no React, browser, or React Native imports.
• Preserve storage and platform dependencies as caller-provided interfaces.
• Treat src/index.ts as the public API. Export intentionally and remove dead exports only with consumer checks.
• Add tests for every new rule. This package should remain cheap to verify.
• Keep notification normalization compatible with both desktop and mobile display constraints.
• Keep presence rules deterministic. Avoid timers or ambient globals inside the rule itself.
• When deep-link behavior changes, update web and mobile route handling together or document the unsupported side.

Verification

bashpnpm --filter @nk304/app-core run test
pnpm --filter @nk304/app-core run build

For session or link changes, also run the relevant web/mobile auth or route tests that consume the shared rule.

Security Notes

Do not store real tokens or credentials in fixtures. Session tests should use synthetic token names and fake storage. Deep-link parsing should reject unsafe or ambiguous targets rather than normalizing them into trusted navigation.

PR Checklist

• Public exports are deliberate.
• Shared rules stay platform-neutral.
• Node tests cover new edge cases.
• Web and mobile consumers are checked before changing semantics.