mirror of
https://github.com/murashit/codex-panel.git
synced 2026-07-22 06:57:10 +00:00
docs: streamline repository guidance
This commit is contained in:
murashit
parent
8fc051ebd4
commit
88694b2a6a
7 changed files with 45 additions and 134 deletions
|
|
@ -5,33 +5,24 @@ description: Use when updating Codex Panel for a new Codex CLI or app-server API
|
|||
|
||||
# Codex Panel App-Server Update
|
||||
|
||||
Use this skill when Codex Panel needs to follow Codex CLI or experimental `codex app-server` API changes.
|
||||
|
||||
## Ground Rules
|
||||
|
||||
- Treat `src/generated/app-server/` as generated output. Do not hand-edit generated bindings.
|
||||
- Use `docs/design.md` for app-server boundary and source-of-truth decisions before adding compatibility layers or product behavior.
|
||||
- Prefer current Codex CLI behavior over broad backward compatibility unless a concrete user need requires compatibility code.
|
||||
- Separate required compatibility fixes from optional cleanup or product improvements.
|
||||
- Do not rely on local Git hooks. Run required generation and verification commands explicitly.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Read the README Compatibility section, `docs/design.md`, `docs/development.md`, `package.json`, and app-server-related source around requests, notifications, threads, approvals, runtime settings, hooks, and model listing.
|
||||
2. Compare the README Compatibility table's `codex.testedCliVersion` with the target `codex --version`.
|
||||
3. Check official Codex CLI or app-server release information when the target version is newer or behavior is uncertain.
|
||||
4. Regenerate bindings with `npm run generate:app-server-types`.
|
||||
5. Review generated diffs for protocol changes that affect runtime behavior. If mechanical normalization is needed, update the normalization code in `scripts/generate-app-server-types.mjs` and regenerate instead of patching generated files by hand.
|
||||
6. Implement only the compatibility changes needed for the target Codex CLI version.
|
||||
7. Update the README Compatibility table's `codex.testedCliVersion` only after validating against that version.
|
||||
8. Identify optional follow-ups separately from required compatibility work:
|
||||
- API changes that allow removing compatibility shims, fallback code, or local workarounds.
|
||||
- New routes, notifications, fields, or lifecycle signals that could simplify existing implementation.
|
||||
- New app-server capabilities that could enable Codex Panel product improvements.
|
||||
9. Report optional follow-ups as proposals only, grouped separately from implemented required fixes unless the user explicitly asks to implement them.
|
||||
1. Read the README Compatibility section and the relevant design and development guidance, then trace the affected app-server paths.
|
||||
2. Confirm the recorded, installed, and target Codex CLI versions. Check official release information when behavior is uncertain.
|
||||
3. Regenerate bindings with `npm run generate:app-server-types`.
|
||||
4. Review generated diffs for protocol changes that affect runtime behavior. If mechanical normalization is needed, update the normalization code in `scripts/generate-app-server-types.mjs` and regenerate instead of patching generated files by hand.
|
||||
5. Implement only the required compatibility changes and record the target version after validating it.
|
||||
6. Report optional cleanup or product follow-ups separately; do not implement them unless requested.
|
||||
|
||||
## Verification
|
||||
|
||||
- Run `npm run check` after regenerated bindings or compatibility changes.
|
||||
- If the change must be reflected in Obsidian, run `npm run build` and verify the plugin reload path separately.
|
||||
- Report the tested Codex CLI version, the generation command used, any app-server compatibility behavior that changed, and any optional simplification or feature proposals found.
|
||||
- Use the live Obsidian workflow when runtime behavior needs verification.
|
||||
- Report the tested Codex CLI version, changed compatibility behavior, and optional follow-ups.
|
||||
|
|
|
|||
|
|
@ -5,15 +5,11 @@ description: Use when validating Codex Panel inside a live Obsidian app with the
|
|||
|
||||
# Codex Panel Obsidian Dev
|
||||
|
||||
Use this skill for live Obsidian checks after building Codex Panel or when investigating behavior that unit tests cannot observe.
|
||||
|
||||
## Ground Rules
|
||||
|
||||
- Work from the Codex Panel repository root.
|
||||
- Use `docs/development.md` for the build and generated-asset expectations before live Obsidian validation.
|
||||
- Treat `obsidian plugin:reload id=codex-panel`, `obsidian reload`, `obsidian restart`, `obsidian devtools`, `obsidian eval`, `obsidian dev:cdp`, and `obsidian dev:mobile` as state-changing or intrusive. Ask the user before running them.
|
||||
- Prefer read-only inspection first: `plugin`, `commands`, `dev:errors`, `dev:dom`, `dev:css`, `dev:console`, `dev:screenshot`, `version`.
|
||||
- If `dev:console` reports that the debugger is not attached, ask before running `obsidian dev:debug on`.
|
||||
- Ask before altering or reloading the live Obsidian session, attaching a debugger, or running intrusive evaluation or input commands.
|
||||
- Prefer read-only inspection before state-changing commands.
|
||||
- Do not clear console or error buffers unless the user approves; clearing can destroy useful failure context.
|
||||
|
||||
## Workflow
|
||||
|
|
@ -24,13 +20,13 @@ Use this skill for live Obsidian checks after building Codex Panel or when inves
|
|||
npm run build
|
||||
```
|
||||
|
||||
2. Before reloading the live plugin, ask the user whether it is OK to reload their current Obsidian session. If approved:
|
||||
2. If approved, reload the plugin when the live session needs the new build:
|
||||
|
||||
```bash
|
||||
obsidian plugin:reload id=codex-panel
|
||||
```
|
||||
|
||||
3. Open the relevant Codex Panel surface when needed:
|
||||
3. Open the relevant surface when needed:
|
||||
|
||||
```bash
|
||||
obsidian command id=codex-panel:open-panel
|
||||
|
|
@ -47,54 +43,12 @@ Use this skill for live Obsidian checks after building Codex Panel or when inves
|
|||
obsidian dev:screenshot path=<scratch-path>/codex-panel.png
|
||||
```
|
||||
|
||||
5. Use focused selectors for the behavior under test. Prefer stable Codex Panel classes such as `.codex-panel`, `.codex-panel__composer`, `.codex-panel-threads`, and `.codex-panel-chat-turn-diff`.
|
||||
5. Use focused Codex Panel-owned selectors found in the relevant implementation or styles.
|
||||
|
||||
## Dynamic UI Investigations
|
||||
|
||||
When checking behavior that depends on browser layout, asynchronous rendering, or virtualized DOM state, measure the live UI rather than inferring from unit tests alone.
|
||||
|
||||
- Capture both the user-visible state and the underlying DOM metrics. Useful fields include `scrollTop`, `scrollHeight`, `clientHeight`, element bounding rects, rendered element counts, inline styles, and relevant computed styles.
|
||||
- For virtualized or asynchronously rendered regions, compare framework state against DOM state where possible, such as virtualizer total size versus actual `scrollHeight`, rendered item count versus data count, or pre-event versus post-frame measurements.
|
||||
- Prefer real input paths for input-sensitive bugs. Use `obsidian dev:cdp method=Input.dispatchMouseEvent ...` or focused keyboard events when a synthetic `dispatchEvent()` may skip browser/Electron behavior.
|
||||
- Record measurements before the action, immediately after the action, after at least one animation frame, and after a short timeout when layout, markdown rendering, resize observers, or virtualizer settle loops may run later.
|
||||
- If injecting temporary DOM probes with `obsidian eval`, remove them before finishing and re-check `dev:errors`. Avoid leaving long-running eval promises; use bounded `setTimeout`-based scripts that resolve.
|
||||
- Treat console instrumentation as temporary. Remove debug logging before final validation, and search the touched files for probe markers or conflict markers before reporting.
|
||||
|
||||
## Common Checks
|
||||
|
||||
- Confirm the loaded version and enabled state:
|
||||
|
||||
```bash
|
||||
obsidian plugin id=codex-panel
|
||||
```
|
||||
|
||||
- List available Codex Panel commands:
|
||||
|
||||
```bash
|
||||
obsidian commands filter=codex-panel
|
||||
```
|
||||
|
||||
- Count rendered elements:
|
||||
|
||||
```bash
|
||||
obsidian dev:dom selector=.codex-panel__composer total
|
||||
```
|
||||
|
||||
- Inspect text, attributes, or computed styles:
|
||||
|
||||
```bash
|
||||
obsidian dev:dom selector=.codex-panel__composer text
|
||||
obsidian dev:dom selector=.codex-panel__composer attr=aria-label
|
||||
obsidian dev:dom selector=.codex-panel__composer css=display
|
||||
obsidian dev:css selector=.codex-panel__composer
|
||||
```
|
||||
|
||||
- Capture a screenshot for visual review:
|
||||
|
||||
```bash
|
||||
obsidian dev:screenshot path=<scratch-path>/codex-panel.png
|
||||
```
|
||||
When behavior depends on layout, asynchronous rendering, or virtualized DOM state, capture the visible state and relevant DOM metrics before and after the real input path, then again after rendering settles. Compare framework or data state with the DOM where possible. Remove temporary probes and instrumentation before final validation and re-check runtime errors.
|
||||
|
||||
## Reporting
|
||||
|
||||
Report the commands run, whether Obsidian was reloaded, key `dev:errors` or `dev:console` findings, and any screenshot path produced. If a command was skipped because it required user approval, state that plainly.
|
||||
Report the observed behavior, runtime errors, intrusive actions taken, and evidence paths. State when an approval-gated check was skipped.
|
||||
|
|
|
|||
|
|
@ -5,29 +5,23 @@ description: Use when preparing, checking, committing, tagging, pushing, or repa
|
|||
|
||||
# Codex Panel Release
|
||||
|
||||
Use this skill when delegating Codex Panel release work to an agent. `docs/release.md` is the public procedure and source of truth for the release command sequence. This skill adds agent-facing gates, review duties, and failure handling.
|
||||
`docs/release.md` is the public procedure and source of truth for the release command sequence. This skill adds agent-facing gates, review duties, and failure handling.
|
||||
|
||||
## Ground Rules
|
||||
|
||||
- Read and follow `docs/release.md`; do not maintain a parallel release command sequence here.
|
||||
- Do not assume local Git hooks exist or ran. Run required verification commands explicitly.
|
||||
- Do not create GitHub Releases locally with `gh release create`; the tag-triggered GitHub Actions workflow owns release creation and asset attachment.
|
||||
- Keep internal validation notes, procedural details, and implementation reasoning out of release notes.
|
||||
- Release notes must be short, public-facing bullets under the single `## Changes` section required by `docs/release.md`.
|
||||
- Treat the release notes produced by `release:prepare` as a draft. Conventional Commit types select candidate bullets, but the full release diff remains the source for checking completeness and user-facing accuracy.
|
||||
- Treat generated release notes as a draft. Review the full release diff and keep one short, public-facing `## Changes` section without internal or procedural detail.
|
||||
|
||||
## Delegation Procedure
|
||||
|
||||
1. Read `docs/release.md`, `package.json`, `manifest.json`, `versions.json`, and existing `.github/release-notes/` files.
|
||||
1. Read `docs/release.md` and inspect the current version metadata and recent release notes.
|
||||
2. Identify the target release version and the commit range since the previous released tag.
|
||||
3. Inspect the full diff since the previous released tag, then follow the preparation step in `docs/release.md`; it updates version files and generates `.github/release-notes/X.Y.Z.md` from Conventional Commits.
|
||||
4. Review the generated draft against the full diff. Rewrite bullets for users, combine related implementation commits, reorder by importance, add an omitted user-facing change when a commit was misclassified, and replace the empty placeholder when no candidate commit was generated.
|
||||
5. Before committing, ask the user to approve the release version, reviewed release-note bullets, and included commit range.
|
||||
6. After approval, follow `docs/release.md` for the Conventional Commit, preflight, tag, and push sequence. Do not rely on a local hook; preflight explicitly checks commits since the previous version in `versions.json`.
|
||||
7. After pushing, let GitHub Actions create or update the GitHub Release.
|
||||
3. Inspect the full release diff, run preparation as documented, and edit the draft for completeness, accuracy, and user-facing wording.
|
||||
4. Before committing, ask the user to approve the release version, reviewed release-note bullets, and included commit range.
|
||||
5. After approval, follow `docs/release.md` through preflight, tag, and push. Let GitHub Actions create or update the GitHub Release.
|
||||
|
||||
## Failure Handling
|
||||
|
||||
- If a release script or preflight fails, fix the cause and rerun the explicit failed command.
|
||||
- If the tag-triggered workflow fails before GitHub Release creation, use the repair procedure in `docs/release.md`.
|
||||
- If a GitHub Release already exists or was partially created, inspect the state before taking action; do not assume local asset upload is the right recovery path.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ This repository contains the Codex Panel Obsidian plugin.
|
|||
|
||||
Jujutsu is the recommended local change-management workflow when available.
|
||||
|
||||
Commits after the `5.0.0` tag must follow Conventional Commits. Use the repository's allowed types and examples in `docs/development.md`, and validate the relevant commit range explicitly because Jujutsu does not rely on local Git hooks.
|
||||
Use Conventional Commits for new commits; see `docs/development.md` for repository rules and local validation.
|
||||
|
||||
## What To Read
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Panel settings should store only panel-specific preferences. Do not mirror Codex
|
|||
|
||||
The app-server API is experimental. The project tracks the supported Codex CLI minor and favors a clean current flow over broad old-protocol compatibility.
|
||||
|
||||
Runtime controls should express visible user intent for the active thread. They should not copy Codex configuration, and diagnostics should expose only actionable troubleshooting facts.
|
||||
Runtime controls should express visible user intent for the active thread rather than copy Codex configuration. Diagnostics should expose only actionable troubleshooting facts.
|
||||
|
||||
## Code Boundaries
|
||||
|
||||
|
|
@ -42,7 +42,7 @@ Obsidian and app-server boundaries stay outside Preact components. External life
|
|||
|
||||
Chat-visible state belongs in the chat state store and named reducer actions. Signals and components may project that state, but they should not become parallel sources of truth.
|
||||
|
||||
Shared app-server resources should likewise have one query record per resource. In particular, model catalog data belongs to the model query; broader server metadata may report the model probe status but must not carry a second model snapshot.
|
||||
Each shared app-server resource should have one authoritative query record. Derived metadata may report status but must not duplicate its snapshot.
|
||||
|
||||
Preact Signals are a chat panel rendering adapter, not a second state system. Panel surfaces may read narrow signal-backed read models, but application workflows, domain code, presentation helpers, and pure UI components must not depend on broad reducer slices or reactive state primitives.
|
||||
|
||||
|
|
@ -54,9 +54,9 @@ Multiple panels are separate Obsidian leaves. Treat each panel as its own Codex
|
|||
|
||||
Subagent threads opened from agent activity remain persistent and restorable but stay outside ordinary thread history. Treat their panels as read-only conversation surfaces while preserving their parent and agent provenance for future specialized behavior.
|
||||
|
||||
Thread history, archived state, forks, catalog snapshots, and other app-server resources should follow app-server semantics. Panel-side views are read models over app-server snapshots and lifecycle events; stale or partial refreshes must not overwrite newer state. Obsidian integrations such as archive note export are convenience views of Codex state, not replacements for Codex history.
|
||||
Thread history and other app-server resources should follow app-server semantics. Panel-side views are read models over app-server snapshots and lifecycle events; stale or partial refreshes must not overwrite newer state. Obsidian integrations such as archive note export are convenience views, not replacements for Codex history.
|
||||
|
||||
Routine panel and Threads view refreshes should load only the first recency-ordered thread page. Older active threads are appended through an explicit load-more action; workflows that explicitly need a complete inventory, such as opening the thread picker, may finish pagination on demand.
|
||||
Routine thread lists should load a bounded recent set and paginate older threads on demand instead of eagerly fetching complete inventories.
|
||||
|
||||
Selection rewrite is intentionally scoped to a focused edit-and-review workflow. Avoid expanding it into a broader writing assistant without a separate design decision.
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ Codex Panel UI should feel native inside Obsidian. Prefer Obsidian variables, st
|
|||
|
||||
Tests should protect user expectations, app-server/panel responsibility boundaries, and state-transition invariants.
|
||||
|
||||
Prefer tests for visible behavior: independent panels, thread-scoped resets, pending request handling, approval flows, readable transcript/detail/status grouping, scroll preservation, and display fallbacks for structured app-server values.
|
||||
Prefer tests for visible behavior and state-transition invariants across panels, threads, requests, streams, and display fallbacks.
|
||||
|
||||
Avoid tests that freeze incidental implementation details such as exact DOM nesting, render counts, node reuse, helper decomposition, or no-op array updates unless those details directly protect a user-visible invariant.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,26 +10,24 @@ npm run fix
|
|||
npm run check
|
||||
```
|
||||
|
||||
Use Node.js 26, matching `.node-version`, CI, and the installed Node type definitions.
|
||||
Use the Node.js version in `.node-version`.
|
||||
|
||||
Use this as the normal edit loop: make the change, run `npm run fix`, then run `npm run check`. Treat `npm run fix` as trusted mechanical cleanup for formatting, import ordering, and Knip safe fixes; review the resulting diff at normal change-boundary checkpoints rather than after each tool adjustment.
|
||||
Use `npm run fix` for mechanical cleanup, review its diff, and run `npm run check` before handoff.
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Commits after the `5.0.0` tag follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/):
|
||||
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(threads): prevent manual titles from being overwritten
|
||||
refactor(chat): move session wiring into the runtime
|
||||
chore(release): 5.0.1
|
||||
fix: prevent manual titles from being overwritten
|
||||
```
|
||||
|
||||
Use one of `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, or `test`. Scopes are optional and are not restricted to a fixed list. Keep the description concise and omit a trailing period. Both lowercase and uppercase starts are accepted so Dependabot's generated `Bump ...` descriptions follow the same validation path. Use `!` before the colon or a `BREAKING CHANGE:` footer for a disruptive change.
|
||||
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 every commit introduced by a pull request or direct push. GitHub-generated `Merge pull request ...` commits are the only format exemption; write manual reverts as `revert: ...`, and rewrite `fixup!` or `squash!` commits before publication. Run `npm run commitlint -- --from <base> --to <head> --verbose` for the same local check; local Git hooks are optional and are not a substitute for CI in the Jujutsu-first workflow.
|
||||
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 such as `npm run typecheck`, `npm run test`, or `npm run build` only when diagnosing a specific failure or when a full check would obscure the signal while iterating. Do not treat focused scripts as a substitute for the final `npm run check`. CI and release preflight run the same `npm run check` command as local development.
|
||||
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.
|
||||
|
||||
|
|
@ -46,49 +44,25 @@ npm run generate:app-server-types
|
|||
npm run check
|
||||
```
|
||||
|
||||
The generation script uses `codex app-server generate-ts --experimental` because the panel depends on experimental app-server fields. Do not hand-edit generated bindings.
|
||||
The bindings include experimental app-server fields. Do not hand-edit them.
|
||||
|
||||
## Placement Rules
|
||||
|
||||
The source tree is organized by implementation ownership, not by the single Obsidian plugin entrypoint. Put behavior where its reason to change lives: app-server protocol adaptation at the app-server boundary, app-server-independent domain models in domain code, cross-feature reusable adapters and primitives under `src/shared/`, and feature workflows under their owning feature. Keep shared subfolders named by the boundary or primitive they own, such as DOM, Obsidian, runtime, or UI rendering.
|
||||
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.
|
||||
|
||||
Within chat, keep state transitions and workflow orchestration separate from app-server adaptation, session/Obsidian wiring, and rendering surfaces. Tests should mirror the ownership boundary of the code under test.
|
||||
|
||||
Keep new code near the state or API it owns. A feature may import another feature only for a capability that feature owns. When moving behavior across an ownership boundary or adding a new shared classification, update the lint policy and its tests with that boundary in the same change.
|
||||
|
||||
Generated app-server types should stay behind app-server connection and protocol adapter modules. If domain, shared code, settings, workspace, or feature code needs app-server data, add or reuse a panel-owned projection at the boundary instead of importing generated payload types directly.
|
||||
|
||||
Chat application workflows should receive chat-owned contracts, not root `src/app-server/` modules or direct `AppServerClient` access. Keep app-server access, connection freshness checks, vault-path injection, and payload projection in `src/features/chat/app-server/` transports or host-owned wiring.
|
||||
|
||||
Thread workflows should likewise depend on contracts under `src/features/threads/workflows/`. Keep thread RPC sequencing, client continuity, persisted transcript reads, and Codex-backed title generation in `src/features/threads/app-server/` adapters.
|
||||
|
||||
Keep shared thread query records as raw last-known-good app-server snapshots. `ThreadCatalog` owns lifecycle-event overlays and publishes the resulting projection immediately; chat panels, the Threads view, and settings consume that projection without writing optimistic state back into the query cache.
|
||||
|
||||
Selection rewrite sessions should depend on the feature-owned transport contract. Keep executable-path and vault-path wiring, short-lived app-server lifecycle, runtime override resolution, and server-request policy in the selection rewrite app-server adapter.
|
||||
|
||||
Chat panel-visible state belongs in `ChatStateStore` and should flow through named reducer actions and the panel read model adapter. Use Preact Signals only in chat panel rendering adapters such as the shell read model and surface projections. When a surface needs fewer dependencies, narrow the read model instead of passing broad reducer slices.
|
||||
|
||||
Each `ChatPanelSession` owns one concrete `ChatPanelSessionRuntime`. That runtime is the per-leaf composition owner for the connection, responder registry, controllers, presenters, shared subscriptions, and disposal ordering; do not add a parallel session graph or late-bound connection bootstrap registry.
|
||||
|
||||
Chat feature dependencies should flow from pure workflow and meaning code toward owned adapters and render surfaces. Lower layers must not reach into host/session wiring, panel internals, or UI implementation details.
|
||||
|
||||
Chat modules should not import `src/workspace/` directly; workspace operations enter chat through host contracts, while workspace modules may coordinate concrete Obsidian chat views.
|
||||
|
||||
Use DOM reads, writes, measurements, hit-tests, focus/selection operations, and DOM event listener wiring only from explicit bridge modules, Obsidian-owned API boundaries, or rendering and measurement code that cannot be expressed cleanly as Preact components. Normal modules may keep refs and call named adapters, but they should not interpret DOM structure or layout directly. Name bridge files with a `.dom`, `.obsidian`, or `.measure` suffix.
|
||||
|
||||
Use `.tsx` only where the module owns rendering or a host rendering bridge. Non-rendering source should use `.ts`; when a new rendering-owned location is intentional, update the source-shape lint policy and its tests rather than relying on convention alone.
|
||||
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 specific to Codex Panel classes. Avoid broad invalidation patterns such as `:has()`, hidden specificity inside `:where()`, IDs, and universal selectors. Keep needed type selectors under Codex Panel-owned class roots for Obsidian-rendered or semantic child DOM. Add new authored CSS files to `src/styles/order.json`, and remove unused or test-only `codex-panel` classes instead of keeping dead styles.
|
||||
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 responsibility: use `Controller` only for stateful lifecycle/control surfaces, `Handler` for inbound event or request entrypoints, `Actions` for caller-facing command or callback bundles without lifecycle ownership, `Coordinator` for stateful background or cross-surface coordination, `Service` for reusable domain capabilities, `Presenter` for UI state projection, `Renderer` for render-only UI contracts, and `Host`/`Ports` for dependency boundary objects. Use `State`, `Snapshot`, `Projection`, `ViewModel`, `Options`, `Context`, `Result`, `Target`, `Capabilities`, or `ActionTargets` for passive value objects; do not use `Actions` for passive values. Use boundary/infrastructure nouns such as `Client`, `Transport`, `Cache`, `Store`, `Catalog`, `Manager`, `Bridge`, `Tracker`, `Session`, `Runtime`, `Provider`, or `Adapter` only when the object owns that concrete boundary or lifecycle role.
|
||||
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 factory-created objects over classes. Use a class only when it owns mutable lifecycle/resource state, extends or implements an external class-based API such as Obsidian views/modals/tabs, or represents an `Error`; do not use a class merely to group pure functions or dependencies.
|
||||
Prefer functions and factories. Reserve classes for mutable resource ownership, external class APIs, and `Error` types.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
|
|
@ -99,8 +73,6 @@ Prefer functions and factory-created objects over classes. Use a class only when
|
|||
|
||||
## API Baselines
|
||||
|
||||
Use the local API baseline report when checking whether the development environment matches the supported API policy:
|
||||
|
||||
```sh
|
||||
npm run api:baseline
|
||||
```
|
||||
|
|
@ -109,4 +81,4 @@ Obsidian runtime compatibility is declared through `manifest.json` and `versions
|
|||
|
||||
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 runs `npm run api:baseline -- --recorded-only`, which validates checked-in compatibility declarations without requiring a Codex CLI installation. Local compatibility work should still run `npm run api:baseline` so the installed CLI is checked too.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ GitHub Releases attach only `main.js`, `manifest.json`, and `styles.css` as Obsi
|
|||
|
||||
Release work is Jujutsu-first in a colocated Git repository; Git is still used to push the tag that triggers the GitHub Release workflow. If the checkout has not been initialized for Jujutsu yet, run `jj git init --colocate` and `jj bookmark track main --remote=origin` once.
|
||||
|
||||
Plugin versions use SemVer-shaped numbers for Obsidian distribution, but they are not a library API compatibility contract. Prefer patch releases for fixes, dependency updates, internal changes, and compatibility refreshes that preserve existing workflows, including routine Codex CLI app-server compatibility updates. Prefer minor releases for user-visible capabilities, settings, workflow additions, or supported-runtime baseline changes such as raising the minimum supported Obsidian app/API version. Reserve major releases for disruptive workflow, settings, storage, or support-policy changes.
|
||||
Plugin versions are for Obsidian distribution, not a library API compatibility contract. Use patch releases for workflow-preserving changes, minor releases for visible capabilities or raised runtime baselines, and major releases for disruptive workflow, settings, storage, or support-policy changes.
|
||||
|
||||
Create a release by preparing the next version, reviewing and editing the generated release notes, committing the release changes, then running the preflight before pushing the matching tag:
|
||||
|
||||
|
|
@ -20,10 +20,10 @@ jj git push --remote origin --bookmark main
|
|||
git push origin X.Y.Z
|
||||
```
|
||||
|
||||
`release:prepare` updates the version files and generates a `## Changes` release notes draft from Conventional Commits after the previous version tag. It includes `feat`, `fix`, `perf`, and commits marked as breaking changes; other commit types are omitted. Review the generated bullets for user-facing wording, combine related implementation commits, and reorder them by importance before committing. If there are no included commits, preparation leaves an empty bullet to replace manually.
|
||||
`release:prepare` updates version files and drafts `## Changes` from selected Conventional Commits since the previous version. Review the draft against the full diff for complete, user-facing notes; consolidate and reorder entries as needed, and replace an empty placeholder.
|
||||
|
||||
`release:preflight` verifies all commit messages since the previous tag, the local Jujutsu/Git state, release metadata, API baselines, lockfile, and the same `npm run check` validation used by CI after the release commit is on `main`.
|
||||
Run `release:preflight` after the release commit is on `main`; it validates the commit range and release readiness.
|
||||
|
||||
Release notes should normally include only user-facing changes. Internal implementation changes, validation details, and release procedure notes should be omitted when minor; when they are important enough to mention, group them into at most one concise bullet.
|
||||
|
||||
The release workflow runs `npm ci`, `npm run release:check`, `npm run check`, attaches the install assets, and generates GitHub artifact attestations for them. The release notes file is required and must contain a single `## Changes` section. If a tag-triggered release fails before creating the GitHub Release, fix the commit, move the local tag with `jj tag set --allow-move -r main X.Y.Z`, then update the remote tag with `git push --force origin X.Y.Z`.
|
||||
The release notes file must contain a single `## Changes` section. The tag-triggered workflow validates and publishes the install assets. If it fails before creating the GitHub Release, fix the commit, move the local tag with `jj tag set --allow-move -r main X.Y.Z`, then update the remote tag with `git push --force origin X.Y.Z`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue