murashit_codex-panel/docs/development.md

# Development

Use this document for day-to-day implementation mechanics: commands, generated files, loaded artifacts, source layout, naming, validation, and common pitfalls. For product boundaries and design rationale, see `docs/design.md`.

## Commands

```sh
npm ci
npm run fix
npm run check
```

Use the Node.js version in `.node-version`.

Use `npm run fix` for mechanical cleanup, review its diff, and run `npm run check` before handoff.

## Commit Messages

Use [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) for new commits:

```text
feat(composer): add daily note context suggestions
fix: prevent manual titles from being overwritten
```

Use one of `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, or `test`. Scopes are optional. Keep the description concise and omit a trailing period; capitalization is unrestricted. Use `!` before the colon or a `BREAKING CHANGE:` footer for a disruptive change.

CI checks commits introduced by pull requests and direct pushes; GitHub-generated pull-request merge commits are exempt. To check a range locally, run `npm run commitlint -- --from <base> --to <head> --verbose`.

Use focused scripts while iterating, but run `npm run check` before handoff. CI and release preflight use the same check.

Keep rule suppressions local and include the Obsidian-specific reason when a native Obsidian UI pattern intentionally diverges from a generic browser rule.

## Generated and Loaded Files

`main.js`, `styles.css`, `data.json`, and `node_modules/` are ignored by Git. `main.js` and `styles.css` are still the files Obsidian loads, so run `npm run build` before live Obsidian validation if you have not already run `npm run check` after the source change.

CSS is authored in `src/styles/` and generated into the ignored root `styles.css` release asset. Use `npm run build:styles` when only regenerating CSS; it also verifies the authored CSS order before writing `styles.css`.

The app-server TypeScript bindings in `src/generated/app-server/` are generated from the installed Codex CLI:

```sh
npm run generate:app-server-types
npm run check
```

The bindings include experimental app-server fields. Do not hand-edit them.

## Placement Rules

Follow the ownership boundaries in `docs/design.md` and the import and source-shape lint rules. Put behavior where its reason to change lives, and update the lint policy and its tests when intentionally changing a boundary.

Keep generated protocol types behind app-server adapters and expose panel-owned contracts or projections to features. Keep direct DOM work in explicit bridge, measurement, or rendering modules; use the established filename suffixes for those boundaries and reserve `.tsx` for rendering.

## CSS Rules

CSS should stay native to Obsidian. Prefer Obsidian variables and Codex Panel tokens for color, typography, spacing, and layout dimensions instead of hardcoded values.

Keep selectors shallow and scoped to Codex Panel classes. Add new authored CSS files to `src/styles/order.json`, and remove unused or test-only classes.

## Naming Conventions

Name modules by owned responsibility. Use lifecycle or boundary nouns only when the object owns that lifecycle or boundary, and passive-data names for values.

Prefer functions and factories. Reserve classes for mutable resource ownership, external class APIs, and `Error` types.

## Common Pitfalls

- Build before Obsidian validation. Obsidian loads ignored root assets, not the TypeScript or authored CSS sources directly.
- Preserve last-known-good app-server state on refresh failure. Do not turn disconnected reads into authoritative empty thread lists, settings snapshots, hook inventories, or diagnostics.
- Normalize optional and nullable app-server values before display. Users should not see raw `undefined`, `null`, protocol enum gaps, or fallback labels that imply Panel owns a Codex runtime setting.
- Do not use DOM order as thread history state. Thread stream DOM is a presentation surface, and delayed Markdown rendering can change heights after initial render.

## API Baselines

```sh
npm run api:baseline
```

Obsidian runtime compatibility is declared through `manifest.json` and `versions.json`. The `obsidian` npm package provides compile-time TypeScript API definitions; it is not runtime validation for an Obsidian app-version matrix. Because the project does not run app-version smoke tests, keep the API type package in the same minor as `manifest.minAppVersion` and use the latest patch in that minor for local type checking. `npm run api:baseline` exits non-zero when the local environment or recorded baselines drift. Raise `manifest.minAppVersion` only when intentionally adopting a newer Obsidian app/API minor.

Codex app-server compatibility is managed by Codex CLI minor version. README records the tested Codex CLI patch version, `src/app-server/connection/compatibility.json` records the machine-readable app-server capability baseline used by the panel client profile, and the baseline check verifies that the local `codex --version` is in the same minor before app-server binding or compatibility work.

Pull-request CI validates recorded compatibility declarations without requiring a Codex CLI installation. Local compatibility work should run `npm run api:baseline` so the installed CLI is checked too.
Restructure public documentation 2026-05-16 11:16:10 +00:00			`# Development`

Document panel-owned projections 2026-06-22 11:56:26 +00:00			Use this document for day-to-day implementation mechanics: commands, generated files, loaded artifacts, source layout, naming, validation, and common pitfalls. For product boundaries and design rationale, see `docs/design.md`.
Document design boundaries 2026-06-18 23:30:08 +00:00
			`## Commands`

Restructure public documentation 2026-05-16 11:16:10 +00:00			```sh
			`npm ci`
Rename format script to Biome fix 2026-06-25 07:35:05 +00:00			`npm run fix`
Restructure public documentation 2026-05-16 11:16:10 +00:00			`npm run check`
			```

docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Use the Node.js version in `.node-version`.
Align Node 26 tooling and enforce recorded compatibility checks 2026-07-10 03:48:36 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Use `npm run fix` for mechanical cleanup, review its diff, and run `npm run check` before handoff.
Introduce Biome formatting and linting 2026-06-24 04:31:30 +00:00
chore(release): adopt Conventional Commits and generated release notes 2026-07-14 06:53:19 +00:00			`## Commit Messages`

docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			`Use [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) for new commits:`
chore(release): adopt Conventional Commits and generated release notes 2026-07-14 06:53:19 +00:00
			```text
			`feat(composer): add daily note context suggestions`
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			`fix: prevent manual titles from being overwritten`
chore(release): adopt Conventional Commits and generated release notes 2026-07-14 06:53:19 +00:00			```

docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Use one of `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, or `test`. Scopes are optional. Keep the description concise and omit a trailing period; capitalization is unrestricted. Use `!` before the colon or a `BREAKING CHANGE:` footer for a disruptive change.
chore(release): adopt Conventional Commits and generated release notes 2026-07-14 06:53:19 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			CI checks commits introduced by pull requests and direct pushes; GitHub-generated pull-request merge commits are exempt. To check a range locally, run `npm run commitlint -- --from <base> --to <head> --verbose`.
chore(release): adopt Conventional Commits and generated release notes 2026-07-14 06:53:19 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Use focused scripts while iterating, but run `npm run check` before handoff. CI and release preflight use the same check.
Tighten Biome lint policy 2026-06-24 07:09:29 +00:00
Tighten design and development docs 2026-06-28 07:36:16 +00:00			`Keep rule suppressions local and include the Obsidian-specific reason when a native Obsidian UI pattern intentionally diverges from a generic browser rule.`
Restructure public documentation 2026-05-16 11:16:10 +00:00
Document design boundaries 2026-06-18 23:30:08 +00:00			`## Generated and Loaded Files`

Clarify docs and skill lint guidance 2026-06-23 09:57:55 +00:00			`main.js`, `styles.css`, `data.json`, and `node_modules/` are ignored by Git. `main.js` and `styles.css` are still the files Obsidian loads, so run `npm run build` before live Obsidian validation if you have not already run `npm run check` after the source change.
Document design boundaries 2026-06-18 23:30:08 +00:00
Simplify validation scripts 2026-06-19 23:18:19 +00:00			CSS is authored in `src/styles/` and generated into the ignored root `styles.css` release asset. Use `npm run build:styles` when only regenerating CSS; it also verifies the authored CSS order before writing `styles.css`.
Document design boundaries 2026-06-18 23:30:08 +00:00
			The app-server TypeScript bindings in `src/generated/app-server/` are generated from the installed Codex CLI:

			```sh
			`npm run generate:app-server-types`
			`npm run check`
			```

docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			`The bindings include experimental app-server fields. Do not hand-edit them.`
Restructure public documentation 2026-05-16 11:16:10 +00:00
Rehome shared modules by ownership boundary 2026-06-30 14:47:59 +00:00			`## Placement Rules`
Restructure public documentation 2026-05-16 11:16:10 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Follow the ownership boundaries in `docs/design.md` and the import and source-shape lint rules. Put behavior where its reason to change lives, and update the lint policy and its tests when intentionally changing a boundary.
Clarify docs and skill lint guidance 2026-06-23 09:57:55 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Keep generated protocol types behind app-server adapters and expose panel-owned contracts or projections to features. Keep direct DOM work in explicit bridge, measurement, or rendering modules; use the established filename suffixes for those boundaries and reserve `.tsx` for rendering.
Restrict TSX rendering source placement 2026-06-26 01:06:02 +00:00
Clarify docs and skill lint guidance 2026-06-23 09:57:55 +00:00			`## CSS Rules`

			`CSS should stay native to Obsidian. Prefer Obsidian variables and Codex Panel tokens for color, typography, spacing, and layout dimensions instead of hardcoded values.`

docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Keep selectors shallow and scoped to Codex Panel classes. Add new authored CSS files to `src/styles/order.json`, and remove unused or test-only classes.
Clarify docs and skill lint guidance 2026-06-23 09:57:55 +00:00
Align chat naming conventions 2026-06-18 11:58:25 +00:00			`## Naming Conventions`

docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			`Name modules by owned responsibility. Use lifecycle or boundary nouns only when the object owns that lifecycle or boundary, and passive-data names for values.`
Align chat naming conventions 2026-06-18 11:58:25 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Prefer functions and factories. Reserve classes for mutable resource ownership, external class APIs, and `Error` types.
Align chat naming conventions 2026-06-18 11:58:25 +00:00
Document design boundaries 2026-06-18 23:30:08 +00:00			`## Common Pitfalls`
Restructure public documentation 2026-05-16 11:16:10 +00:00
Document design boundaries 2026-06-18 23:30:08 +00:00			`- Build before Obsidian validation. Obsidian loads ignored root assets, not the TypeScript or authored CSS sources directly.`
			`- Preserve last-known-good app-server state on refresh failure. Do not turn disconnected reads into authoritative empty thread lists, settings snapshots, hook inventories, or diagnostics.`
			- Normalize optional and nullable app-server values before display. Users should not see raw `undefined`, `null`, protocol enum gaps, or fallback labels that imply Panel owns a Codex runtime setting.
Align internal thread stream vocabulary 2026-07-08 21:45:55 +00:00			`- Do not use DOM order as thread history state. Thread stream DOM is a presentation surface, and delayed Markdown rendering can change heights after initial render.`
Add API baseline checks for Obsidian and Codex 2026-05-17 12:18:49 +00:00
			`## API Baselines`

			```sh
			`npm run api:baseline`
			```

Simplify validation scripts 2026-06-19 23:18:19 +00:00			Obsidian runtime compatibility is declared through `manifest.json` and `versions.json`. The `obsidian` npm package provides compile-time TypeScript API definitions; it is not runtime validation for an Obsidian app-version matrix. Because the project does not run app-version smoke tests, keep the API type package in the same minor as `manifest.minAppVersion` and use the latest patch in that minor for local type checking. `npm run api:baseline` exits non-zero when the local environment or recorded baselines drift. Raise `manifest.minAppVersion` only when intentionally adopting a newer Obsidian app/API minor.
Add API baseline checks for Obsidian and Codex 2026-05-17 12:18:49 +00:00
Make app-server initialize profile explicit 2026-07-07 13:06:19 +00:00			Codex app-server compatibility is managed by Codex CLI minor version. README records the tested Codex CLI patch version, `src/app-server/connection/compatibility.json` records the machine-readable app-server capability baseline used by the panel client profile, and the baseline check verifies that the local `codex --version` is in the same minor before app-server binding or compatibility work.
Align Node 26 tooling and enforce recorded compatibility checks 2026-07-10 03:48:36 +00:00
docs: streamline repository guidance 2026-07-14 07:37:42 +00:00			Pull-request CI validates recorded compatibility declarations without requiring a Codex CLI installation. Local compatibility work should run `npm run api:baseline` so the installed CLI is checked too.